Add Messaging, Voice, and Authentication to your apps with Vonage Communications APIs
Visit the Vonage API Developer PortalYou can make audio and video adjustments to published and subscribed streams:
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).
When you toggle audio or video on or off, the OTSession object in each connected client dispatches a streamPropertyChanged event with the changedProperty property of the event object set to "hasAudio" or "hasVideo".
To set up a voice-only session, set the videoTrack properties of the properties prop passed into the
OTPublisher component to false:
<OTPublisher
properties={{
videoTrack: false,
}}
/>
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 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.
For sessions that use the OpenTok Media Router (sessions with themedia mode set to routed), lowering the frame rate proportionally reduces the maximum bandwidth the stream can use. However, in session with the media mode set to relayed, lowering the frame rate does not reduce the stream's bandwidth.
Reducing the frame rate can reduce the bandwidth required. Smaller resolution videos can have a lower frame rate without as much of a perceived difference to the user. So if you are using a low resolution, you might also want to think about using a low frame rate.
You can also restrict the frame rate of a Subscriber's video stream. For more information, see Restricting the frame rate of a subscribed stream.
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.
To disable audio or video in a subscriber, set the subscribeToAudio or subscribeToVideo properties of the properties prop passed into the OTSubscriber component:
<OTSubscriber
properties={{
subscribeToAudio: true,
subscribeToVideo: false,
}}
/>
By default, these are set to true (both audio and video are consumed).
Set the subscribeToAudio pro
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 audio only:
Note however that you can only subscribe to audio or video if the client publishing the stream includes audio or video. For example, setting subscribeToVideo to false will have no effect if the client publishing the stream is publishing audio only.
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)
In the OTSession streamCreated event includes hasAudio and hasVideo properties:
<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.
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.
}
}}/>
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:
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 of the properties prop passed into the OTPublisher component:
<OTPublisher
properties={{
enableDtx: true,
}}
/>
For more information, see this Vonage Video API knowledge base article.
Use the OTPublisher.setVideoTransformers() method to apply a video filter for published video. You can apply a background blur filter or a background image filter.
The following code applies a background blur filter to a publisher's video:
<OTPublisher
eventHandlers={{
streamCreated: () => {
this.publisher.setVideoTransformers([
{
name: 'BackgroundBlur',
properties: JSON.stringify({
radius: 'low',
}),
}
])
}
}}
ref={instance => {
this.publisher = instance;
}}
/>
Note that the OTPublisher.setVideoTransformers() method takes an array of transformer objects. Each object has two properties:
A name property, set to either 'BackgroundBlur' or 'BackgroundReplacement'.
A properties property, defining options for the filter.
For details, see the documentation for the OTPublisher.setVideoTransformers() method.
The following code applies a background replacement filter to a publisher's video (supported on iOS only):
<OTPublisher
eventHandlers={{
streamCreated: () => {
this.publisher.setVideoTransformers([
{
name: 'BackgroundReplacement',
properties: JSON.stringify({
image_file_path: 'path/to/image',
}),
}
])
}
}}
ref={instance => {
this.publisher = instance;
}}
/>
To remove video filters from the published stream, call the OTPublisher.setVideoTransformers() method and pass in an empty array.
Important: Background blur and background replacement filters are resource-intensive and require devices with high processing power. It is recommended to only use these transformations on supported devices. See the following documentation:
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.