Class: Publisher

 var apiKey = ''; // Replace with your API key. See https://dashboard.nexmo.com
 var sessionID = ''; // Replace with your own session ID.
                     // See https://developer.vonage.com/en/video/guides/create-session/.
 var token = ''; // Replace with a generated token that has been assigned the moderator role.
                 // See https://developer.vonage.com/en/video/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);
   }
 });

Applies an audio filter for the publisher. In the current version, you can only apply an advanced noise suppression filter. A publisher can have only one (or zero) filters applied at one time. When you set a new filter, any previously set filter is removed.

This method is incompatible with the Publisher.setAudioMediaProccessorConnector() method. Calling this method after Publisher.setAudioMediaProccessorConnector(connector) returns a promise that is rejected with an error, with the name property of the error set to 'OT_NOT_SUPPORTED'. You can remove the connector by calling Publisher.setAudioMediaProccessorConnector(null).

Note: Audio filters are only supported in recent versions of Chrome, Electron, Opera, and Edge. They are not supported in other (non-Chromium-based) browsers or on iOS. You can check if the client supports this feature by calling the OT.hasMediaProcessorSupport() method.

Important: Audio filters require adequate processor support. Even in supported browsers, transformers may not be stable when background processes limit available processing resources. See Client requirements.

Calling this method results in an error (the Promise returned by the method is rejected) in the following conditions:

• The browser does not support this method.
• A custom filter is already being used via the Publisher.setAudioMediaProcessorConnector() method.
• There was an error applying the transformation filter.

You can also set the initial audio filter by setting a audioFilter option when calling OT.initPublisher().

Applies a video filter for the publisher. You can apply a background blur filter. A publisher can have only one (or zero) applied at one time. When you set a new filter, a previously set filter is removed.

This method is incompatible with the Publisher.setVideoMediaProcessorConnector() method. Calling this method after Publisher.setVideoMediaProcessorConnector(connector) returns a promise that is rejected with an error, with the name property of the error set to 'OT_NOT_SUPPORTED'. You can remove the connector by calling Publisher.setVideoMediaProcessorConnector(null).

Note: Video filters are only supported in recent versions of Chrome, Electron, Opera, and Edge. They are not supported in other (non-Chromium-based) browsers or on iOS. You can check if the client supports this feature by calling the OT.hasMediaProcessorSupport() method.

Important: Video filters require adequate processor support. Even in supported browsers, transformers may not be stable when background processes limit available processing resources. See Client requirements.

Calling this method results in an error (the Promise returned by the method is rejected) in the following conditions:

• The browser does not support this method.
• The publisher is not using a supported video source. (The videoSource option of the OT.initPublisher() method was set to null, false, or "screen").
• A custom filter is already being used via the Publisher.setVideoMediaProcessorConnector() method.
• There are no video input devices (cameras) available.
• There was an error acquiring video from the video input device.
• There was an error applying the transformation filter.

You can also set the initial video filter by setting a videoFilter option when calling OT.initPublisher().

Removes the audio filter being applied to the publisher.

This will result in an error (the Promise returned by the method is rejected) if the audio filter could not be stopped.

Removes the video filter being applied to the publisher.

This will result in an error (the Promise returned by the method is rejected) if the video filter could not be stopped.

Switches the video input source used by the publisher to the next one in the list of available devices.

This will result in an error (the Promise returned by the method is rejected) in the following conditions:

• The user denied access to the video input device.
• The publisher is not using a camera video source. (The videoSource option of the OT.initPublisher() method was set to null, false, a MediaStreamTrack object, or "screen").
• There are no video input devices (cameras) available.
• There was an error acquiring video from the video input device.

  publisher.cycleVideo().then(console.log);
  // Output: {deviceId: "967a86e52..."}

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 audio filter used by the publisher (or null if there is no audio filter).

Returns the MediaStreamTrack object used as the audio input source for the publisher. If the publisher does not have an audio source, this method returns null.

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 a promise that, on success, resolves with an array of objects that include RTCStatsReport properties for the published stream. (See RTCStatsReport.)

For a publisher in a routed session (one that uses the OpenTok Media Router), this array includes one object, defining the statistics for the single audio-media stream that is sent to the OpenTok Media Router. In a relayed session, the array includes an object for each subscriber to the published stream. Each object in the array contains an rtcStatsReport property that is a RTCStatsReport object.

Additionally, for a publisher in a relayed session, each object in the array contains the following two properties:

• connectionId (String) — The unique ID of the client's connection, which matches the id property of the connection property of the connectionCreated event that the Session object dispatched for the remote client.
• subscriberId (String) — The unique ID of the subscriber, which matches the id property of the Subscriber object in the subscribing client's app.

These two properties are undefined for a publisher in a routed session.

The Promise will be rejected in the following conditions:

• The browser does not support this method (for example, in Chrome version 57 and lower, which does not support the RTCPeerConnection.getStats() standard).
• The PeerConnection for the Publisher is not connected.

Returns the details on the publisher's stream quality, including the following:

• The total number of audio and video packets lost
• The total number of audio and video packets sent
• The total number of audio and video bytes sent
• The current average video frame rate

You can use these stats to assess the quality of the publisher's audio-video stream.

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.)

Returns the content hint for the video track.

Returns the video filter applied used by the publisher.

Returns an object containing properties defining the publisher's current video source.

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
   });

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.

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);

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.

Starts publishing captions (if it is currently not being published) when the value is true; stops publishing captions (if it is currently being published) when the value is false.

Note: No captions will be published if the publisher does not have an audio source.

For more information, see the Live Captions developer guide.

Toggles video on or off for the publisher. It causes the video to be published (if it is currently not being published, the client is connected, and the publisher is publishing) when the value is true; it stops publishing video (if it is currently being published) when the value is false.

Note: The behavior of publishVideo varies depending on whether the publisher is currently connected and publishing:

• Calling publishVideo(true) when the publisher is not connected to a session causes the publisher to capture and render video locally, but it does not stream video.
• Calling publishVideo(false) when the publisher is not connected to a session causes the publisher to stop capturing video locally. No video is streamed.
• Calling publishVideo(true) when the publisher is connected to a session but not currently publishing causes it to capture and render video locally, but it does not stream video.
• Calling publishVideo(false) when the publisher is connected to a session but not currently publishing causes the publisher to stop capturing video locally. No video is streamed.
• Calling publishVideo(true) when the publisher is both connected to a session and currently publishing causes the publisher to capture and render video locally and to stream video.
• Calling publishVideo(false) when the publisher is both connected to a session and currently publishing causes the publisher to stop capturing video and to stream empty video frames.

Sets a MediaProcessorConnector for the publisher audio track. A publisher can have only one audio MediaProcessorConnector applied at one time. When you set a new connector, the previously set audio connector is removed.

Note: MediaProcessors are only supported in recent versions of Chrome, Electron, Opera, and Edge. They are not supported in other (non-Chromium-based) browsers or on iOS. You can check if the client supports this feature by calling the OT.hasMediaProcessorSupport() method.

Important: Media processors require adequate processor support. Even in supported browsers, transformers may not be stable when background processes limit available processing resources. See Client requirements.

Calling this method results in an error (the Promise returned by the method is rejected) in the following conditions:

• There are no audio input devices (microphones) available.
• There was an error acquiring audio from the audio input device.
• There was an error acquiring the processed track from the MediaProcessorConnector.

You can clear the current connector by calling this method with null.

For more information, see the Using the Vonage Media Processor library developer guide.

Switches the audio input source used by the publisher. You can set the audioSource to a device ID (string) or audio MediaStreamTrack object.

This will result in an error (the Promise returned by the method is rejected) in the following conditions:

• The browser does not support this method. This method is not supported in Internet Explorer or non-Chromium versions of Edge (older than version 79).
• The publisher was not initiated with an audio source. (The audioSource option of the OT.initPublisher() method was set to null or false).
• The user denied access to the audio input device.
• There was an error acquiring audio from the audio input device or MediaStreamTrack object.
• The audioSource value is not a string or MediaStreamTrack object.
• The audioSource string is not a valid audio input device available to the browser.

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.

Sets the content hint for the video track of the publisher's stream. This allows browsers to use encoding or processing methods more appropriate to the type of content.

Use this method to change the video content hit dynamically. Set the initial video content hit by setting the videoContentHint property of the options passed into the OT.initPublisher() method.

Chrome 60+, Safari 12.1+, Edge 79+, and Opera 47+ support video content hints.

Sets a MediaProcessorConnector for the publisher video track. A publisher can have only one video MediaProcessorConnector applied at one time. When you set a new connector, the previously set video connector is removed.

This method is incompatible with the Publisher.applyVideoFilter() method. Calling this method after Publisher.applyVideoFilter(filter) returns a promise rejected with an error, with the name property of the error set to 'OT_NOT_SUPPORTED'. You can clear the video filter by calling Publisher.clearVideoFilter().

Note: MediaProcessors are only supported in recent versions of Chrome, Electron, Opera, and Edge. They are not supported in other (non-Chromium-based) browsers or on iOS. You can check if the client supports this feature by calling the OT.hasMediaProcessorSupport() method.

Important: Media processors require adequate processor support. Even in supported browsers, transformers may not be stable when background processes limit available processing resources. See Client requirements.

Calling this method results in an error (the Promise returned by the method is rejected) in the following conditions:

• There are no video input devices (cameras) available.
• A video filter has already been applied via the Publisher.applyVideoFilter() method.
• There was an error acquiring video from the video input device.
• There was an error acquiring the processed track from the MediaProcessorConnector.

You can clear the current connector by calling this method with null.

For more information, see the Using the Vonage Media Processor library developer guide.

This method sets the video source for a publisher that is using a camera. Pass in the device ID of the new video source.

The following will result in errors:

• If the videoSourceId parameter is not a string or the device ID for a valid video input device, the promise will reject with an error with the name property set to 'OT_INVALID_VIDEO_SOURCE'.
• If the publisher does not currently use a camera input, the promise will reject with an error with the name property set to 'OT_SET_VIDEO_SOURCE_FAILURE'.

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 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.

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.

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

This event is also dispatched if the user removes the permissions after previously granting them. This is a beta feature.

Note: On macOS 10.15+ (Catalina), to publish a screen-sharing stream the user must grant the browser access to the screen in macOS System Preferences > Security & Privacy > Privacy > Screen Recording. Otherwise, the Publisher will dispatch an accessDenied event.

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.)

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.)

Dispatched when the audio input device is changed.

This is a beta feature.

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.

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.

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 when the video and audio sources of the stream are MediaStreamTrack elements and tracks are stopped or destroyed.

This is a beta feature. Dispatched when the MediaStream is available.

A moderator has forced this client to mute audio.

The publisher has started streaming to the session.

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.

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.

Dispatched when the video for the publisher is disabled.

Before sending this event, when the Publisher's stream quality deteriorates to a level that is low enough that the video stream is at risk of being disabled, the Publisher dispatches a videoDisableWarning event.

If connectivity improves to support video again, the Publisher object dispatches a videoEnabled event, and the Subscriber resumes receiving video.

By default, the Publisher displays a video disabled indicator when a videoDisabled event with this reason is dispatched and removes the indicator when the videoEnabled event with this reason is dispatched. You can control the display of this icon by setting the videoDisabledDisplayMode with the Publisher.setStyle() method or by setting the videoDisabledDisplayMode style property when initializing the Publisher with the OT.initPublisher() method.

You can enable this audio-only fallback feature, by setting the publisher property to true in the audioFallbackEnabled option passed into the OT.initPublisher() method for the publishing client. (See OT.initPublisher().)

This is a beta feature.

Dispatched when the Publisher determines that the stream quality has degraded and the video will be disabled if the quality degrades more. If the quality degrades further, the Publisher disables the video and dispatches a videoDisabled event.

By default, the Publisher displays a video disabled warning indicator when this event is dispatched (and the video is disabled). You can control the display of this icon by calling the setStyle() method of the Publisher and setting the videoDisabledDisplayMode property, or you can set the videoDisabledDisplayMode property when calling the OT.initPublisher() method and setting the style property of the properties parameter.

This is a beta feature.

Dispatched when the Publisher determines that the stream quality has improved to the point at which the video being disabled is not an immediate risk. This event is dispatched after the Publisher object dispatches a videoDisableWarning event.

This is a beta feature.

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.

Dispatched when the Publisher resumes sending video to the publisher after video was previously disabled.

This is a beta feature.