Publish: Settings & Devices

Use this guide to configure how you capture and encode your outgoing video and audio. It covers device permissions and selection, remembering devices, camera facing mode, resolution and frame rate, content hints for motion or text, publishing from alternate sources (Canvas, Video, Web Audio), and where to find advanced Publisher options.

Check camera and microphone permissions

Before a Publisher can access the client's camera and microphone, the user must grant access. The Publisher object dispatches events when the user grants or denies access to the camera and microphone:

publisher.on({
  accessAllowed: function () {
    // The user granted access to the camera and mic.
  },
  accessDenied: function () {
    // The user denied access to the camera and mic.
  }
});

It also dispatches events when the Allow/Deny dialog is opened or closed:

publisher.on({
  accessDialogOpened: function () {
    // The Allow/Deny dialog box is opened.
  },
  accessDialogClosed: function () {
    // The Allow/Deny dialog box is closed.
  }
});

The Publisher has an accessAllowed property indicating whether access has been granted.

Choose camera and microphone

Choose which camera and microphone the Publisher should use. You can enumerate devices and select via Publisher options.

You can have the publisher use the rear-facing camera of the device by setting a properties prop of the OTPublisher component and setting the cameraPosition property of that object to "back":

<OTPublisher
  properties={{
    cameraPosition: 'back',
  }}
/>

Note that you can also publish a screen-sharing stream — one in which the source is the client's screen, not a camera. For details, see Screen sharing.

You can (optionally) specify an audio and video input device for the publisher to use. When you call the OT.initPublisher() method, you can (optionally) set the audioSource and videoSource properties of the properties object passed into the OT.initPublisher() method.

First, use the OT.getDevices() method to enumerate available devices. The array of devices is passed in as the devices parameter of the callback function passed into the OT.getDevices() method. For example, the following code gets a list of audio and video input devices:

var audioInputDevices;
var videoInputDevices;
OT.getDevices(function(error, devices) {
  audioInputDevices = devices.filter(function(element) {
    return element.kind == "audioInput";
  });
  videoInputDevices = devices.filter(function(element) {
    return element.kind == "videoInput";
  });
  for (var i = 0; i < audioInputDevices.length; i++) {
    console.log("audio input device: ", audioInputDevices[i].deviceId);
  }
  for (i = 0; i < videoInputDevices.length; i++) {
    console.log("video input device: ", videoInputDevices[i].deviceId);
  }
});

Each device listed by OT.getDevices() has a unique device ID, set as the deviceId property. You can use these device ID values as the audioSource and videoSource properties of the properties object passed into OT.initPublisher():

var pubOptions =
  {
    audioSource: audioInputDevices[0].deviceId,
    videoSource: videoInputDevices[0].deviceId
  };
var publisher = OT.initPublisher(null, pubOptions, function(error) {
  console.log("OT.initPublisher error: ", error);
});

Set the videoSource property to null or false in a voice-only session (see Publishing in a voice session).

Set the videoSource property to null or false in a voice-only session.

The Vonage Video hardware set-up component provides a user interface for clients to select the camera and microphone to use. It is built using the OT.getDevices() method.

Note that you can also publish a screen-sharing stream — one in which the source is the client's screen, not a camera. For details, see Screen sharing.

You can also change the camera used by the publisher.

You can also change the audio source used by the publisher.

Remember device selection

In HTTPS contexts, some browsers can remember the camera and microphone selection for subsequent visits. For example, in IE you can set usePreviousDeviceSelection: true when initializing the Publisher:

var pubOptions = { usePreviousDeviceSelection: true };
var publisher = OT.initPublisher(null, pubOptions, function (error) {
  console.log("OT.initPublisher error:", error);
});

You can also set facingMode to choose front or back camera on supported devices and disable automatic audio input device management via disableAudioInputDeviceManagement if you need full control.

To prompt the user to select the camera and microphone to use in IE (and ignore previous device selections), do not set the usePreviousDevices property in the options you pass into the OT.initPublisher() method (or set it to false, the default).

Disable automatic audio input device management (advanced):

var pubOptions = {disableAudioInputDeviceManagement: true};
var publisher = OT.initPublisher(null, pubOptions, function(error) {
  console.log("Publishing a stream");
});

Set resolution and frame rate

Set recommended video resolution and frame rate via OT.initPublisher() options:

var publisher = OT.initPublisher(targetElement, {
  resolution: '1280x720', // 1920x1080, 1280x720, 640x480, or 320x240
  frameRate: 15            // 30, 15, 7, or 1
});

Note: Actual subscriber resolution and frame rate can vary based on network and device conditions.

Stream settings (Web)

To set a recommended video resolution for a published stream, set the resolution property of the properties parameter you pass into OT.initPublisher():

var publisherProperties = {resolution: '1280x720'};
var publisher = OT.initPublisher(targetElement, publisherProperties);
publisher.on('streamCreated', function(event) {
  console.log('Stream resolution: ' + event.stream.videoDimensions.width + 'x' + event.stream.videoDimensions.height);
});

Valid values are "1920x1080", "1280x720", "640x480", and "320x240". The default is 640x480.

To set a recommended frame rate for a published stream, set the frameRate property:

var publisherProperties = {frameRate: 7};
var publisher = OT.initPublisher(targetElement, publisherProperties);
publisher.on('streamCreated', function(event) {
  console.log('Frame rate: ' + event.stream.frameRate);
});

Valid values are 30, 15, 7, and 1.

If the publisher specifies a frame rate, the actual frame rate of the video stream is set as the frameRate property of the Stream object, though the actual frame rate will vary based on changing network and system conditions. If you do not specify a frame rate when you call OT.initPublisher, this property is undefined.

For sessions that use the Media Router (sessions with the media mode set to routed), lowering the frame rate proportionally reduces the maximum bandwidth the stream can use.

However, in sessions with the media mode set to relayed, lowering the frame rate does not reduce the stream's bandwidth.

The videoHeight() and videoWidth() methods return the configured resolution of the Publisher object. The actual resolution of a Subscriber video stream is returned by the videoWidth() and videoHeight() methods of the Subscriber object. These may differ from the values of the resolution property you passed to OT.initPublisher() if the publishing browser does not support the requested resolution.

Video content hints

You can set a video content hint to improve the quality and performance of a published video. This can be useful in certain situations:

When publishing screen-sharing video that will primarily contain either text or video content.
When using a camera video source, if you would prefer to degrade frame rate and maintain resolution, you can set the content hint to "text" or "detail". In a routed session, if the publisher supports using scalable video, it will send a full-resolution, low frame-rate stream and — if network conditions permit — a full-resolution, regular frame-rate stream. The OpenTok Media Router will forward one of those streams to the subscribers.

This tells the browser to use encoding or processing methods more appropriate to the type of content you specify.

Set the initial video content hint for a stream by setting the videoContentHint property of the options you pass into the OT.initPublisher() method:

var publisherOptions = {
  videoContentHint: "text",
  // other options, such as videoSource: "screen"
};
var publisher = OT.initPublisher(targetElement, publisherOptions, callbackFunction);

You can change the video content hint dynamically by calling the setVideoContentHint() method of a Publisher object:

publisher.setVideoContentHint("motion");

You can set the video content hint to one of the following values:

"" — No hint is provided (the default). The publishing client will make a best guess at how video content should be treated.
"motion" — The track should be treated as if it contains video where motion is important. For example, you may use this setting for a screen-sharing video stream that contains video.
"detail" — The track should be treated as if video details are extra important. For example, you may use this setting for a screen-sharing video stream that contains text content, painting, or line art.
"text" — The track should be treated as if text details are extra important. For example, you may use this setting for a screen-sharing video stream that contains text content.

With the "text" and "detailed" content hints, the browser attempts to maintain high resolution, even if it must reduce the video frame rate. For the "motion" content hint, the browser reduces resolution to prevent the frame rate from stalling.

Chrome 60+, Safari 12.1+, Edge 79+, and Opera 47+ support video content hints. The setting is ignored in other browsers.

Set maximum bitrate

You can set a maximum video bitrate for a Publisher to cap bandwidth usage (for example on metered networks). Use either predefined presets (DEFAULT, BW_SAVER, EXTRA_BW_SAVER) or set a raw bitrate value; the encoder will adapt within the allowed range based on network conditions.

Publish from alternate sources (Web)

Publish from custom video sources

You can set the video source for a Publisher to a video MediaStreamTrack object. This lets you do the following:

Publish video using an HTML Canvas element as the video. You can call the captureStream() method of the HTMLCanvasElement object and call the getVideoTracks() method of the resulting CanvasCaptureMediaStream object to get a video MediaStreamTrack object.
Publish video from a Video element. Call the captureStream() method of an HTMLVideoElement object to obtain a MediaStream object. The getVideoTracks() method of the MediaStream object returns an array of audio MediaStreamTrack objects (usually one). You can then use the MediaStreamTrack object as the audioSource property of the options object you pass into the OT.initPublisher() method.

You can use a video MediaStreamTrack object as the videoSource property of the options object you pass into the OT.initPublisher() method. This causes the video represented by the MediaStreamTrack object to be the video source for the published stream.

Setting the video source to a MediaStreamTrack object is not supported in the Vonage video Plugin for Internet Explorer.

Publish from custom audio sources

You can set the audio source for a Publisher to an audio MediaStreamTrack object. This lets you do the following:

Publish audio from a Audio or Video element. Call the captureStream() method of an HTMLAudioElement object or an HTMLVideoElement object to obtain a MediaStream object. The getAudioTracks() method of the MediaStream object is an array of audio MediaStreamTrack objects (usually one). You can then use the MediaStreamTrack object as the audioSource property of the options object you pass into the OT.initPublisher() method.
Publish audio from an audio MediaStreamTrack object. For example, you can use the AudioContext object and the Web audio API to dynamically generate audio. You can then call createMediaStreamDestination().stream.getAudioTracks()[0] on the AudioContext object to get the audio MediaStreamTrack object to use as the audioSource property of the options object you pass into the OT.initPublisher() method.

Applying filters and effects

You can apply filters and effects on audio or video obtained from a microphone or camera used as the source for a published stream. See Filters and Effects.