Adjusting audio and video

You can make audio and video adjustments to published and subscribed streams.

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:

By default, a Subscriber object is initialized to subscribe to audio and video, if they are available.

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:

When you toggle audio or video on or off, the Session object in each connected client dispatches a streamPropertyChanged event. For more information, see StreamPropertyChangedEvent.

Setting the resolution and frame rate for a video

You can set the frame rate and resolution for a publisher's stream by setting a resolution property of the options you pass into the OT.initPublisher() method. See Setting the video resolution of a stream and Setting the frame rate of a stream.

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 preferreResolution option to "auto" to optimize the CPU and network usage. See Setting the preferred frame rate and resolution.

Switching the camera used by a Publisher

You can switch the video input device (camera) used as the video source for a Publisher by calling the Publisher.cycleVideo() or Publisher.setVideoSource() method:

Publisher.cycleVideo()

The Publisher.cycleVideo() method lets you cycle through the available video sources (cameras). For example, on a mobile device you can switch between the front and back camera. The method returns a promise that resolves when the operation completes successfully. The promise resolves with an object that has a deviceId property set to the device ID of the camera used:

If there is an error, the promise is rejected. This can occur in the following conditions:

• The user denied access to the video input device.
• The publisher is not using a camera video source. This method does not work for a screen-sharing publisher, a publisher that uses a MediaStreamTrack source, or a publisher that does not include a video track (an audio-only publisher).
• There are no video input devices (cameras) available.
• There was an error acquiring video from the video input device. Note that this method only works for a publisher that is using a camera video source.

Publisher.setVideoSource()

The Publisher.setVideoSource() method lets you pass in the device ID of the new video source (camera). The method returns a promise that resolves when the operation completes:

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'. You can use the OT.getDevices() method to enumerate the available video input devices (and get their device IDs).

You can use the Publisher.getVideoSource() method to get the current video source and its device ID (if it is a video input device).

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.

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:

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.

Switching the audio output used

You can switch the audio output device (a speaker or headphones) used to play audio from all publishers and subscribers (in all OpenTok 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:

Detecting when a publisher switches audio input devices

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:

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:

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

Optimizations in voice-only sessions

There are a number of user interface optimizations that you can make in a voice-only session. See the Voice guide.