Suggestions

close search

Publisher

Properties Methods Events 

The Publisher object provides the mechanism through which control of the published stream is accomplished. Calling the OT.initPublisher() method creates a Publisher object.

The following code instantiates a session, and publishes an audio-video stream upon connection to the session:

 var apiKey = ''; // Replace with your API key. See https://tokbox.com/account
 var sessionID = ''; // Replace with your own session ID.
                     // See https://tokbox.com/developer/guides/create-session/.
 var token = ''; // Replace with a generated token that has been assigned the moderator role.
                 // See https://tokbox.com/developer/guides/create-token/.

 var session = OT.initSession(apiKey, sessionID);
 session.connect(token, function(error) {
   if (error) {
     console.log(error.message);
   } else {
     // This example assumes that a DOM element with the ID 'publisherElement' exists
     var publisherProperties = {width: 400, height:300, name:"Bob's stream"};
     publisher = OT.initPublisher('publisherElement', publisherProperties);
     session.publish(publisher);
   }
 });

This example creates a Publisher object and adds its video to a DOM element with the ID publisherElement by calling the OT.initPublisher() method. It then publishes a stream to the session by calling the publish() method of the Session object.

Properties

Name Type Description
accessAllowed Boolean Whether the user has granted access to the camera and microphone. The Publisher object dispatches an accessAllowed event when the user grants access. The Publisher object dispatches an accessDenied event when the user denies access.
element Element The HTML DOM element containing the Publisher. (Note: when you set the insertDefaultUI option to false in the call to OT.initPublisher, the element property is undefined.)
id String The DOM ID of the Publisher.
stream Stream The Stream object corresponding the stream of the Publisher.
session Session The Session to which the Publisher belongs.
See:

Methods

Name Description
addEventListener(type, listener, context) Deprecated; use on() or once() instead.
destroy() → {Publisher} Deletes the Publisher object and removes it from the HTML DOM.
getImgData() → {String} Returns the base-64-encoded string of PNG data representing the Publisher video.
getStyle() → {Object} Returns an object that has the properties that define the current user interface controls of the Publisher.
off(type, handler, context) → {Object} Removes an event handler or handlers.
on(type, handler, context) → {EventDispatcher} Adds an event handler function for one or more events.
once(type, handler, context) → {Object} Adds an event handler function for one or more events.
publishAudio(value) Starts publishing audio (if it is currently not being published) when the value is true; stops publishing audio (if it is currently being published) when the value is false.
publishVideo(value) Starts publishing video (if it is currently not being published) when the value is true; stops publishing video (if it is currently being published) when the value is false.
removeEventListener(type, listener, context) Deprecated; use off() instead.
setStyle(style, value) → {Publisher} Sets properties that define the appearance of some user interface controls of the Publisher.
videoHeight() → {Number} Returns the height, in pixels, of the Publisher video.
videoWidth() → {Number} Returns the width, in pixels, of the Publisher video.

addEventListener(type, listener, context)

Deprecated; use on() or once() instead.

This method registers a method as an event listener for a specific event.

If a handler is not registered for an event, the event is ignored locally. If the event listener function does not exist, the event is ignored locally.

Throws an exception if the listener name is invalid.

Parameters:
Name Type Description
type String The string identifying the type of event.
listener function The function to be invoked when the object dispatches the event.
context Object (Optional) Defines the value of this in the event handler function.
See:

destroy() → {Publisher}

Deletes the Publisher object and removes it from the HTML DOM.

The Publisher object dispatches a destroyed event when the DOM element is removed.

Returns:
The Publisher.

getImgData() → {String}

Returns the base-64-encoded string of PNG data representing the Publisher video.

You can use the string as the value for a data URL scheme passed to the src parameter of an image file, as in the following:

 var imgData = publisher.getImgData();

 var img = document.createElement("img");
 img.setAttribute("src", "data:image/png;base64," + imgData);
 var imgWin = window.open("about:blank", "Screenshot");
 imgWin.document.write("<body></body>");
 imgWin.document.body.appendChild(img);
Returns:
The base-64 encoded string. Returns an empty string if there is no video.

getStyle() → {Object}

Returns an object that has the properties that define the current user interface controls of the Publisher. You can modify the properties of this object and pass the object to the setStyle() method of thePublisher object. (See the documentation for setStyle() to see the styles that define this object.)
See:
Returns:
The object that defines the styles of the Publisher.

off(type, handler, context) → {Object}

Removes an event handler or handlers.

If you pass in one event name and a handler method, the handler is removed for that event:

obj.off("eventName", eventHandler);

If you pass in multiple event names and a handler method, the handler is removed for those events:

obj.off("eventName1 eventName2", eventHandler);

If you pass in an event name (or names) and no handler method, all handlers are removed for those events:

obj.off("event1Name event2Name");

If you pass in no arguments, all event handlers are removed for all events dispatched by the object:

obj.off();

The method also supports an alternate syntax, in which the first parameter is an object that is a hash map of event names and handler functions and the second parameter (optional) is the context for this in each handler:

obj.off(
   {
      eventName1: event1Handler,
      eventName2: event2Handler
   });
Parameters:
Name Type Description
type String (Optional) The string identifying the type of event. You can use a space to specify multiple events, as in "accessAllowed accessDenied accessDialogClosed". If you pass in no type value (or other arguments), all event handlers are removed for the object.
handler function (Optional) The event handler function to remove. The handler must be the same function object as was passed into on(). Be careful with helpers like bind() that return a new function when called. If you pass in no handler, all event handlers are removed for the specified event type.
context Object (Optional) If you specify a context, the event handler is removed for all specified events and handlers that use the specified context. (The context must match the context passed into on().)
See:
Returns:
The object that dispatched the event.

on(type, handler, context) → {EventDispatcher}

Adds an event handler function for one or more events.

The following code adds an event handler for one event:

obj.on("eventName", function (event) {
    // This is the event handler.
});

If you pass in multiple event names and a handler method, the handler is registered for each of those events:

obj.on("eventName1 eventName2",
       function (event) {
           // This is the event handler.
       });

You can also pass in a third context parameter (which is optional) to define the value of this in the handler method:

obj.on("eventName",
       function (event) {
           // This is the event handler.
       },
       obj);

The method also supports an alternate syntax, in which the first parameter is an object that is a hash map of event names and handler functions and the second parameter (optional) is the context for this in each handler:

obj.on(
   {
      eventName1: function (event) {
              // This is the handler for eventName1.
          },
      eventName2:  function (event) {
              // This is the handler for eventName2.
          }
   },
   obj);

If you do not add a handler for an event, the event is ignored locally.

Parameters:
Name Type Description
type String The string identifying the type of event. You can specify multiple event names in this string, separating them with a space. The event handler will process each of the events.
handler function The handler function to process the event. This function takes the event object as a parameter.
context Object (Optional) Defines the value of this in the event handler function.
See:
Returns:
The EventDispatcher object.

once(type, handler, context) → {Object}

Adds an event handler function for one or more events. Once the handler is called, the specified handler method is removed as a handler for this event. (When you use the on() method to add an event handler, the handler is not removed when it is called.) The once() method is the equivilent of calling the on() method and calling off() the first time the handler is invoked.

The following code adds a one-time event handler for one event:

obj.once("eventName", function (event) {
   // This is the event handler.
});

If you pass in multiple event names and a handler method, the handler is registered for each of those events:

obj.once("eventName1 eventName2"
         function (event) {
             // This is the event handler.
         });

You can also pass in a third context parameter (which is optional) to define the value of this in the handler method:

obj.once("eventName",
         function (event) {
             // This is the event handler.
         },
         obj);

The method also supports an alternate syntax, in which the first parameter is an object that is a hash map of event names and handler functions and the second parameter (optional) is the context for this in each handler:

obj.once(
   {
      eventName1: function (event) {
                 // This is the event handler for eventName1.
          },
      eventName2:  function (event) {
                 // This is the event handler for eventName1.
          }
   },
   obj);
Parameters:
Name Type Description
type String The string identifying the type of event. You can specify multiple event names in this string, separating them with a space. The event handler will process the first occurence of the events. After the first event, the handler is removed (for all specified events).
handler function The handler function to process the event. This function takes the event object as a parameter.
context Object (Optional) Defines the value of this in the event handler function.
See:
Returns:
The object that dispatched the event.

publishAudio(value)

Starts publishing audio (if it is currently not being published) when the value is true; stops publishing audio (if it is currently being published) when the value is false.
Parameters:
Name Type Description
value Boolean Whether to start publishing audio (true) or not (false).
See:

publishVideo(value)

Starts publishing video (if it is currently not being published) when the value is true; stops publishing video (if it is currently being published) when the value is false.
Parameters:
Name Type Description
value Boolean Whether to start publishing video (true) or not (false).
See:

removeEventListener(type, listener, context)

Deprecated; use off() instead.

Removes an event listener for a specific event.

Throws an exception if the listener name is invalid.

Parameters:
Name Type Description
type String The string identifying the type of event.
listener function The event listener function to remove.
context Object (Optional) If you specify a context, the event handler is removed for all specified events and event listeners that use the specified context. (The context must match the context passed into addEventListener().)
See:

setStyle(style, value) → {Publisher}

Sets properties that define the appearance of some user interface controls of the Publisher.

You can either pass one parameter or two parameters to this method.

If you pass one parameter, style, it is an object that has the following properties:

  • audioLevelDisplayMode (String) — How to display the audio level indicator. Possible values are: "auto" (the indicator is displayed when the video is disabled), "off" (the indicator is not displayed), and "on" (the indicator is always displayed).
  • archiveStatusDisplayMode (String) — How to display the archive status indicator. Possible values are: "auto" (the indicator is displayed when the session is being recorded), "off" (the indicator is not displayed). If you disable the archive status display indicator, you can display your own user interface notifications based on the archiveStarted and archiveStopped events dispatched by the Session object.
  • backgroundImageURI (String) — A URI for an image to display as the background image when a video is not displayed. (A video may not be displayed if you call publishVideo(false) on the Publisher object). You can pass an http or https URI to a PNG, JPEG, or non-animated GIF file location. You can also use the data URI scheme (instead of http or https) and pass in base-64-encrypted PNG data, such as that obtained from the Publisher.getImgData() method (for example, you could call myPublisher.setStyle("backgroundImageURI", myPublisher.getImgData())). If the URL or the image data is invalid, the property is ignored (the attempt to set the image fails silently).
  • buttonDisplayMode (String) — How to display the microphone controls. Possible values are: "auto" (controls are displayed when the stream is first displayed and when the user mouses over the display), "off" (controls are not displayed), and "on" (controls are always displayed).
  • nameDisplayMode (String) — Whether to display the stream name. Possible values are: "auto" (the name is displayed when the stream is first displayed and when the user mouses over the display), "off" (the name is not displayed), and "on" (the name is always displayed).

For example, the following code passes one parameter to the method:

myPublisher.setStyle({nameDisplayMode: "off"});

If you pass two parameters, style and value, they are key-value pair that define one property of the display style. For example, the following code passes two parameter values to the method:

myPublisher.setStyle("nameDisplayMode", "off");

You can set the initial settings when you call the Session.publish() or OT.initPublisher() method. Pass a style property as part of the properties parameter of the method.

The OT object dispatches an exception event if you pass in an invalid style to the method. The code property of the ExceptionEvent object is set to 1011.

Parameters:
Name Type Description
style Object Either an object containing properties that define the style, or a String defining this single style property to set.
value String The value to set for the style passed in. Pass a value for this parameter only if the value of the style parameter is a String.

See:
Returns:
The Publisher object

videoHeight() → {Number}

Returns the height, in pixels, of the Publisher video. This may differ from the resolution property passed in as the properties property the options passed into the OT.initPublisher() method, if the browser does not support the requested resolution.
Returns:
the height, in pixels, of the Publisher video.

videoWidth() → {Number}

Returns the width, in pixels, of the Publisher video. This may differ from the resolution property passed in as the properties property the options passed into the OT.initPublisher() method, if the browser does not support the requested resolution.
Returns:
the width, in pixels, of the Publisher video.

Events

accessAllowed

Dispatched when the user has clicked the Allow button, granting the app access to the camera and microphone. The Publisher object has an accessAllowed property which indicates whether the user has granted access to the camera and microphone.
See:

accessDenied

Dispatched when the user has clicked the Deny button, preventing the app from having access to the camera and microphone.
See:

accessDialogClosed

Dispatched when the Allow/Deny box is closed. (This is the dialog box in which the user can grant the app access to the camera and microphone.)
See:

accessDialogOpened

Dispatched when the Allow/Deny dialog box is opened. (This is the dialog box in which the user can grant the app access to the camera and microphone.)
See:

audioLevelUpdated

Dispatched periodically to indicate the publisher's audio level. The event is dispatched up to 60 times per second, depending on the browser. The audioLevel property of the event is audio level, from 0 to 1.0. See AudioLevelUpdatedEvent for more information.

The following example adjusts the value of a meter element that shows volume of the publisher. Note that the audio level is adjusted logarithmically and a moving average is applied:

var movingAvg = null;
publisher.on('audioLevelUpdated', function(event) {
  if (movingAvg === null || movingAvg <= event.audioLevel) {
    movingAvg = event.audioLevel;
  } else {
    movingAvg = 0.7 * movingAvg + 0.3 * event.audioLevel;
  }

  // 1.5 scaling to map the -30 - 0 dBm range to [0,1]
  var logLevel = (Math.log(movingAvg) / Math.LN10) / 1.5 + 1;
  logLevel = Math.min(Math.max(logLevel, 0), 1);
  document.getElementById('publisherMeter').value = logLevel;
});

This example shows the algorithm used by the default audio level indicator displayed in an audio-only Publisher.

See:

destroyed

Dispatched when the Publisher element is removed from the HTML DOM. When this event is dispatched, you may choose to adjust or remove HTML DOM elements related to the publisher.

mediaStopped

The user publishing the stream has stopped sharing one or all media types (video, audio and/or screen). This can occur when a user disconnects a camera or microphone used as a media source for the Publisher. Or it can occur when a user closes a window or application that is the video source for a screen-sharing stream.
See:

streamCreated

The publisher has started streaming to the session.
See:

streamDestroyed

The publisher has stopped streaming to the session. The default behavior is that the Publisher object is removed from the HTML DOM. The Publisher object dispatches a destroyed event when the element is removed from the HTML DOM. If you call the preventDefault() method of the event object in the event listener, the default behavior is prevented, and you can, optionally, retain the Publisher for reuse or clean it up using your own code.
See:

videoDimensionsChanged

Dispatched when the video dimensions of the video change. This can only occur in when the stream.videoType property is set to "screen" (for a screen-sharing video stream), when the user resizes the window being captured. This event object has a newValue property and an oldValue property, representing the new and old dimensions of the video. Each of these has a height property and a width property, representing the height and width, in pixels.
See:

videoElementCreated

Dispatched when the Publisher's video element is created. Add a listener for this event when you set the insertDefaultUI option to false in the call to the OT.initPublisher() method. The element property of the event object is a reference to the Publisher's video element (or in Internet Explorer the object element containing the video). Add it to the HTML DOM to display the video. When you set the insertDefaultUI option to false, the video (or object) element is not automatically inserted into the DOM.

Add a listener for this event only if you have set the insertDefaultUI option to false. If you have not set insertDefaultUI option to false, do not move the video (or object) element in in the HTML DOM. Doing so causes the Publisher object to be destroyed.

See: