Subscriber Settings

Overview

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

This how-to will go over:

  • Subscribing to audio or video only
  • Detecting whether a stream has audio or video
  • Changing a Subscriber's video settings
  • Changing a Subscriber's audio settings

Subscribing to Audio or Video Only

When you subscribe to a stream, you can specify whether to initially subscribe to audio or video (if they are available). For example, the following code subscribes to the audio stream only:

<OTSubscriber
  properties={{
    subscribeToAudio: true,
    subscribeToVideo: false,
  }}
/>

After you create a Subscriber object, you toggle audio on or off by calling the subscribeToAudio() method of the Subscriber object:

subscriber.subscribeToAudio(false); // audio off
subscriber.subscribeToAudio(true); // audio on

You toggle video on or off by calling the subscribeToVideo() method of the Subscriber object:

subscriber.subscribeToVideo(false); // video off
subscriber.subscribeToVideo(true); // video on

Note however that you can only subscribe to audio or video if the client publishing the stream includes audio or video. For example, calling subscribeToVideo(false) will have no effect if the client publishing the stream is publishing audio only.

Detecting Whether a Stream Has Audio or Video

By default, a Subscriber object plays back both audio and video (if they are available). You can check if a stream has audio or video (if the publisher of the stream is streaming audio or video) by checking the hasAudio and hasVideo properties of the Stream object:

<OTSession
  eventHandlers={{
    streamCreated: event => {
      console.log('Stream created -- stream ID:', event.streamId);
      console.log('hasAudio:', event.hasAudio);
      console.log('hasVideo:', event.hasVideo);
    }
  }}/>

You may want to set state properties based on the hasAudio and hasVideo properties and adjust the UI for the OTSubscriber based on these state values. You may want to adjust the user interface based on whether the stream has audio or video. For example, you may want to indicate to the user whether a stream has audio or not; or you may not want to hide a subscriber if a stream does not have video.

For example, when you subscribe to a stream, you may want to adjust the user interface based on whether the stream has audio or video. For example, you may want to indicate to the user whether a stream has audio or not; or you may not want to hide a subscriber if a stream does not have video.

Detecting When a Stream Adds or Removes Audio or Video

The OTSession object dispatches a streamPropertyChanged event when a stream toggles audio or video on or off. The event object has a changedProperty property set to hasAudio or hasVideo when the audio or video changes. The newValue property is set to a Boolean value. For example, the following code listens for changes in a audio and video in a Stream:

<OTSession
eventHandlers={{
  streamPropertyChanged: event => {
    if (event.changedProperty === 'hasAudio')
      // Adjust the UI for the subscriber to event.streamId.
    } else if (event.changedProperty === 'hasVideo') {
      // Adjust the UI for the subscriber to event.streamId.
    }
}}/>

Changing a Subscriber’s Video Settings

Setting the Resolution and Frame Rate for a Video

You can set the frame rate and resolution for a subscriber's stream by setting the preferredFrameRate and preferredResolution properties of the options you pass into the session.subscribe() method. We recommend setting the preferredResolution option to "auto" to optimize the CPU and network usage. The "auto" option is a beta feature. See Setting the preferred frame rate and resolution

Changing a Subscriber’s Audio Settings

Switching the Audio Output Used by a Subscriber

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

Changing the Audio Level of a Subscriber

When you subscribe to a stream, you can set the initial volume of the subscriber when you call the subscribe() method of the Session object:

// Set a value between 0 (silent) and 100 (full volume):
var subOptions = {audioVolume = 10};

// Replace stream and replacementElementId with your own values:
subscriber = session.subscribe(stream,
                                replacementElementId,
                                subOptions);

After you create a Subscriber object, you can set its volume by calling its setAudioVolume() method, passing in a value from 0 (silent) to 100 (full volume):

subscriber.setAudioVolume(0); (silent)

Note that the user can also mute the subscriber via user interface controls in the subscriber.