Publisher Settings

Overview

The Vonage Video Client SDKs allow for participants to publish audio and video in a session. The Client SDKs allow for configuring the Publisher object based on your preferences and use case.

This how-to will go over:

  • Publishing audio or video only
  • Changing a publisher's video settings
  • Changing a publisher's audio settings

Publishing Audio or Video Only

When you create a Publisher object, you can specify whether to initially publish only audio or only video. For example, the following code creates an audio-only Publisher:

To toggle audio and video on and off, set the publishAudio and publishVideo properties of the properties prop passed into the OTPublisher component:

<OTPublisher
  properties={{
    publishAudio: true,
    publishVideo: false,
  }}
/>

By default, these are set to true (both audio and video are published).

Once you have created a Publisher object, you can toggle audio and video on or off, by calling the publishAudio() and publishVideo() methods (passing in a Boolean value). For example, the following code turns audio off:

publisher.publishAudio(false);

When you toggle audio or video on or off, the Session object in each connected client dispatches a streamPropertyChanged event. There are also a number of user interface optimizations that you can make in a voice-only session. See the Voice guide.

Publishing in a voice-only session

To set up a voice-only session, set the videoSource property to null or false when you create each Publisher object in the session. For example, the following code creates a Publisher for a voice-only session:

<OTPublisher
  properties={{
    videoTrack: false,
  }}
/>

When you set the videoSource property to null, the publishing client does not request access to the camera, and no video is published.

Publishing audio only for Publishers with low bandwidth

Publishers can be configured to disable video, keeping audio enabled, in low bandwidth situations. Video publishing will resume when the Publisher's bandwidth improves.

For more information, see the Audio fallback developer guide.

Changing a Publisher’s Video Settings

Setting the Resolution and Frame Rate for a Video

To set a recommended video resolution for a published stream, set the resolution property of the properties prop of the OTPublisher component:

<OTPublisher
  properties={{
    resolution: '1280x720',
  }}
/>

This resolution property is a string, defining the desired resolution of the video. The format of the string is "widthxheight", where the width and height are represented in pixels. Valid values are "1920x1080", "1280x720", "640x480", and "320x240".

The default resolution for a stream (if you do not specify a resolution) is 640x480 pixels. If the client system cannot support the resolution you requested, the stream will use the next largest setting supported.

It is best to try to match the resolution to the size that the video will be displayed. If you are only displaying the video at 320x240 pixels then there is no point in streaming at 1280x720 or 1920x1080. Reducing the resolution can save bandwidth and reduce congestion and connection drops.

Note: See the 1080p developer guide for considerations about using 1080p resolution.

To set a recommended frame rate for a published stream, set the frameRate property of the properties prop of the OTPublisher component:

<OTPublisher
  properties={{
    frameRate: 7,
  }}
/>

Set the value to the desired frame rate, in frames per second, of the video. Valid values are 30 (the default), 15, 7, and 1.

Enabling the camera torch (flashlight)

Set the cameraTorch property of the object passed in as the properties prop of the OTPublisher object to enable or disable the camera flashlight (torch) while capturing video:

<OTPublisher
  properties={{
    cameraTorch: false,
  }}
/>

The default value is false (the flashlight is not used).

Note the not all device cameras have a camera flashlight. If the active camera does not support camera flashlight functionality (for example, the front camera typically does not support it), setting cameraTorch has no effect.

Setting the camera zoom

Set the cameraZoomFactor property of the object passed in as the properties prop of the OTPublisher object to set the camera zoom ratio (factor):

<OTPublisher
  properties={{
    cameraZoomFactor: 0.7,
  }}
/>

The ratio/factor value ranges from 0.5 to the maximum zoom factor. Values between 0.5 and 1.0 represent ultra-wide-angle (zoom out), and values between 1.0 and the maximum zoom factor represent zooming in. The actual zoom factor applied is clamped to the range supported by the active camera's configuration — if the camera does not support ultra-wide-angle, zoom factors set below 1.0 will not take effect and no zoom will be applied. For values over the maximum zoom factor supported by the camera, the zoom factor will be set to the maximum supported value.

Switching the Camera Used by a Publisher

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',
  }}
/>

Mirroring the Local Display of a Publisher’s Video

You can set the mirror property of the options passed into the OT.initPublisher() method to have the publisher's locally rendered video mirrored (true) or not (false). By default, video is mirrored for a publisher that has a camera video source, and not mirrored for a screen-sharing video.

This setting only affects the rendered video in the publisher's client application. It has no effect on the video in subscribing clients.

Changing a Publisher’s Audio Settings

Switching the Audio Source Used by a Publisher

You can switch the microphone or MediaStreamTrack object used as the audio source for a Publisher by calling the setAudioSource() method of the Publisher object.

Pass a device ID for a microphone or an audio MediaStreamTrack object into the Publisher.setAudioSource() method. The method returns a Promise that is rejected on error (see the reference documentation for setAudioSource()).

For example, the following code shows you how to implement a cycleMicrophone() function that cycles through the microphones available:

// Setting an audio source to a new MediaStreamTrack
const stream = await OT.getUserMedia({
  videoSource: null,
});

const [audioSource] = stream.getAudioTracks();
publisher.setAudioSource(audioSource).then(() => console.log('Audio source updated'));

// Cycling through microphone inputs
let audioInputs;
let currentIndex = 0;
OT.getDevices((err, devices) => {
  audioInputs = devices.filter(device => device.kind === 'audioInput');
  // Find the right starting index for cycleMicrophone
  audioInputs.forEach((device, idx) => {
    if (device.label === publisher.getAudioSource().label) {
      currentIndex = idx;
    }
  });
});

const cycleMicrophone = () => {
  currentIndex += 1;
  let deviceId = audioInputs[currentIndex % audioInputs.length].deviceId;
  publisher.setAudioSource(deviceId);
};

The Publisher.setAudioSource() method only works for a publisher that has an audio source. If you set audioSource to null (or false) when calling OT.initPublisher(), you cannot later add an audio source to the publisher.

The Publisher.getAudioSource() method returns the MediaStreamTrack object used as the current audio input source for the publisher.

The OT.getDevices() method enumerates the audio and video input devices available to the browser.

Detecting When a Publisher Switches Audio Input Devices (Web)

By default, the SDK automatically handles audio input device switching for any Publisher object when an audio input device is added or removed, unless audio input device management has been disabled. See Disabling default audio input device management if you wish to disable automatic audio input device switching.

The Publisher object dispatches an audioInputDeviceChanged event when the SDK automatically changes the audio input. This event will be dispatched when a new audio input device is added, the current audio input device is removed, or when the Publisher's operating system switches audio input devices. The dispatched event has a device property that contains information about the audio input device. You may want to let your users know their microphone has changed:

publisher.on('audioInputDeviceChanged', (event) => {
  console.log('audio input device', event.device);
  console.log(`changing device to: ${event.device.label}`);
});

Switching the Audio Output Used by a Publisher

You can switch the audio output device (a speaker or headphones) used to play audio from all publishers and subscribers (in all Vonage Video sessions in the browser).

The OT.getAudioOutputDevices() method enumerates the audio and video input devices available to the browser.

The OT.getActiveAudioOutputDevice() method identifies the currently active audio output device.

Use the OT.setAudioOutputDevice() method to set the audio output device.

For example, the following code shows you how to implement a cycleAudioOutput() function that cycles through the available audio output devices:

// Cycling through audio output devices
let currentIndex = 0;
const audioOutputs = await OT.getAudioOutputDevices();
const currentOutputDevice = await OT.getActiveAudioOutputDevice();
audioOutputs.forEach((device, index) => {
  if (device.label === currentOutputDevice.label) {
    currentIndex = index;
  }
});

const cycleAudioOutput = async () => {
  currentIndex += 1;
  let deviceId = audioOutputs[currentIndex % audioOutputs.length].deviceId;
  await OT.setAudioOutputDevice(deviceId);
};

Tuning Audio Quality

To set the audio bitrate for a publisher's audio stream, set the audioBitrate property of the properties prop passed into the OTPublisher component:

<OTPublisher
  properties={{
    audioBitrate: 48000,
  }}
/>

The audioBitrate setting is the desired bitrate for the published audio, in bits per second. The supported range of values is 6,000 - 510,000. Set this value to enable high-quality audio (or to reduce bandwidth usage with lower-quality audio).

The following are recommended settings:

  • 8,000 - 12,000 for narrowband (NB) speech
  • 16,000 - 20,000 for wideband (WB) speech
  • 28,000 - 40,000 for full-band (FB) speech
  • 48,000 - 64,000 for full-band (FB) music

Reducing Audio Bandwidth With Opus DTX

Opus DTX (Discontinuous Transmission) is an audio codec that can reduce the bandwidth usage when a participant is not speaking. This can be useful in large sessions with many audio participants.

You enable Opus DTX by setting the enableDtx property when initializing a Publisher. For more information, see this Vonage Video API knowledge base article.