Suggestions

close search

Adjusting audio and video — Web

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:

var pubOptions = {publishAudio:true, publishVideo:false};

// Replace replacementElementId with the ID of the DOM element to replace:
publisher = OT.initPublisher(replacementElementId, pubOptions);

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:

publisher.publishAudio(false);

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.

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:

var pubOptions = {videoSource: null};

// Replace replacementElementId with the ID of the DOM element to replace:
publisher = OT.initPublisher(replacementElementId, pubOptions);

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

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:

var options = {subscribeToAudio:true, subscribeToVideo:false};

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

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.

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.

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:

if (!stream.hasAudio) {
    // You may want to adjust the user interface
}
if (!stream.hasVideo) {
    // You may want to adjust the user interface
}

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 Session object dispatches a streamPropertyChanged event when a stream toggles audio or video on or off. The streamPropertyChanged event is defined by the StreamPropertyChangedEvent class. The event object has a changedProperty property (identifying the Stream property that changed) and a newValue property (the new value of the Stream property). For example, the following code listens for changes in a audio and video in a Stream:

session.on("streamPropertyChanged", function (event) {
    var subscribers = session.getSubscribersForStream(event.stream);
    for (var i = 0; i < subscribers.length; i++) {
        // You may want to display some UI text for each
        // subscriber, or make some other UI change,
        // based on event.changedProperty and
        // event.newValue
    }
}

Note that a subscriber's video can be disabled or enabled for reasons other than the publisher disabling or enabling it. A Subscriber object dispatches videoDisabled and videoEnabled events in all conditions that cause the subscriber's stream to be disabled or enabled. For details, see the documentation for the Subscriber videoDisabled and Subscriber videoEnabled events.

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

Tuning audio quality

The OT.initPublisher() method includes options for tuning audio quality. This lets you publish streams that use high-quality (or lower quality) audio:

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

The following are recommended settings:

If you do not set this option option, OpenTok.js automatically sets the audio bitrate for the stream.

Currently, this setting is not supported in streams published in Firefox.

disableAudioProcessing (Boolean) — Whether to disable echo cancellation, automatic gain control, and noise suppression for the pubished audio. You may want to set this to true when publishing high-quality audio (by setting the audioBitrate property of the OT.initPublisher() options). The default value is false.

enableStereo (Boolean) — Whether to publish stereo audio. The default value is false.

Applying filters and effects to published audio and video

You can use an audio MediaStream track or a video MediaStream track as the source audio or video for a published stream. Using this feature, you can apply filters and effects to the published audio or video.

You can use the OT.getUserMedia() method to get a reference to a MediaStream that uses the camera selected by the user. You can then use the video MediaStreamTrack obtained from that MediaStream object as the source for a Video element. You can then add that Video element to an HTML Canvas element, apply filters or effects to the canvas, and use the filtered video MediaStreamTrack object obtained from the canvas as the video source for a published stream. For an example, see the Stream-Filter sample opentok-web-samples repo on GitHub.

You can use the OT.getUserMedia() method to get a reference to a MediaStream that uses the microphone selected by the user. You can then use the audio MediaStreamTrack obtained from that MediaStream object as the as the audioSource when calling OT.initPublisher(). You can then create an AudioContext object and call its createMediaStreamSource() object, passing in the MediaStream object to to create a MediaStreamAudioSourceNode object. You can then apply audio filters to the MediaStreamAudioSourceNode object, which will result in the filters being applied to the published stream.

Other user interface customization options

For other available options for customizing the user interface, see the Customizing the UI guide.