Add Messaging, Voice, and Authentication to your apps with Vonage Communications APIs
Visit the Vonage API Developer PortalAbout the OpenTok scalable video feature
Scalable video is a feature for routed sessions that improves video quality in multi-party sessions by letting each subscriber receive a video quality that matches their current network conditions — independently of every other subscriber.
Without scalable video, the OpenTok Media Router forwards the same video quality to every subscriber on a stream. When a subscriber's connection degrades, the router uses bandwidth estimation to tell the publisher to reduce its bitrate — which lowers the quality for all subscribers on that stream. With scalable video active, the router selects the most appropriate quality layer for each subscriber independently in real time, without affecting what other subscribers receive.
Scalable video requires a routed session (a session that uses the OpenTok Media Router). It is not available in relayed sessions and would not be useful there, since streams travel directly between clients with no router in the path to select or switch quality layers. See The OpenTok Media Router and media modes.
Scalable video is enabled by default. The project-level setting defaults to Auto, which means the OpenTok Media Router activates scalable video automatically when there are more than two clients in a session and all other conditions are met. You can also set it to On (always active) or Off — see Enabling and disabling scalable video for details. For most applications, no code changes are needed.
How scalable video works depends on the codec the publisher negotiates. Understanding the differences helps you choose the right codec for your use case, such as when you need to optimize for publisher CPU usage, upstream bandwidth, or subscriber-side quality adaptation.
With VP8, scalable video is implemented through simulcast. The publisher encodes and transmits multiple completely separate bitstreams at different resolutions and frame rates — for example, 1080p, 540p, and 270p each with their own temporal (frame rate) layers. Each stream is self-contained and can be decoded on its own.
Because each stream is fully independent, the OpenTok Media Router can instantly switch any subscriber to a different quality level with no re-encoding — providing strong resilience to changing network conditions.
Tradeoff: Encoding and uploading multiple streams requires more CPU and upstream bandwidth on the publisher side than sending a single quality. Lower-resolution layers are significantly cheaper to encode than the highest quality, but the total cost is still higher than a non-simulcast stream.
With VP9, scalable video uses Scalable Video Coding (SVC). The publisher encodes a single bitstream that has multiple spatial (resolution) and temporal (frame rate) layers mathematically embedded within it. Each higher layer depends on the lower layers, so a decoder receiving only the base layer gets low quality, while one receiving all layers gets full quality — all from the same bitstream.
The publisher CPU cost for SVC encoding is higher than encoding a single stream — roughly comparable to VP8 simulcast — but SVC requires less upstream bandwidth because there is only one bitstream to upload instead of multiple independent streams. From the single encoded stream, the OpenTok Media Router can extract and forward exactly the right subset of layers for each subscriber, providing efficient and flexible quality adaptation that is also more resilient to packet loss.
SVC requires the publisher endpoint and the OpenTok Media Router to both support VP9 SVC. Firefox supports VP9 but not SVC — a Firefox publisher sends VP9 without layers, so the OpenTok Media Router cannot adapt quality for that stream.
For a full explanation of SVC layers, scalability modes (L1T3, L2T3, L3T3), archiving behavior, and device support, see VP9 Scalable Video Coding for routed sessions.
| Aspect | Simulcast (VP8) | SVC (VP9) |
|---|---|---|
| What the publisher sends | Multiple independent bitstreams at different resolutions and frame rates (distinct SSRCs/RIDs) | 1 bitstream with spatial and temporal layers embedded (single SSRC) |
| Spatial layers | Multi-stream: each resolution is a separate encoded stream | Embedded within a single bitstream |
| Temporal layers | Each simulcast stream can include temporal layers | Embedded within a single bitstream |
| Media Router role | Pick which stream to forward | Extract and forward the right layers |
| Firefox publisher support | Supported via RID-based encodings | VP9 yes; SVC not supported on Firefox |
Spatial layer resolution ratio: Each spatial step uses a 2:1 resolution ratio. An
L3T3stream has layers at 100%, 50%, and 25% of the source resolution (e.g., 1080p → 540p → 270p). This is whysetPreferredResolution()can target substantially different resolutions.
The H.264 codec is fully supported in the Vonage Video API for publishing and subscribing, but scalable video is not available for H.264 streams. The OpenTok Media Router cannot switch quality layers for H.264 streams, and scalable video settings have no effect when H.264 is negotiated. If your application requires scalable video, use VP8 or VP9 instead. See Video codecs.
Scalable video is supported for VP8 simulcast and VP9 SVC. It is not supported for H.264 streams. It is only available in routed sessions.
The following clients support scalable video:
For VP9 SVC device and browser compatibility details, see VP9 Scalable Video Coding for routed sessions.
Note: By default, scalable video is disabled for screen-sharing streams and enabled for camera and custom video source streams. To enable scalable video for screen-sharing, see Scalable screen-sharing streams.
You may want to disable scalable video to lock the resolution and frame rate or to help limit bandwidth. (Streams require more bandwidth if they use scalable video.)
By default, scalable video is automatically enabled for sessions in all projects. You can customize the scalable video setting for a specific project:
Go to your Video API account and select the project from the list of projects in the left-hand menu.
Under Project settings, find Scalable Video and select the desired setting for the project:
On — Scalable video is always enabled (in supported clients) for all sessions in the project.
Off — Scalable video is not enabled for any sessions in the project. Use this to lock the resolution and frame rate, or to reduce publisher CPU and bandwidth usage.
Auto (default) — Scalable video is enabled for a session in the project when the OpenTok Media Router determines that it should be used (when there are more than two clients in the session).
Unless there is a specific reason for scalable video to be always on or off, you should leave the Auto option selected.
Click the Save button.
Note: This setting controls VP8 simulcast behavior. VP9 always uses SVC when supported, and H.264 does not support scalable video — neither is affected by this setting.
Note: Streams require more upstream bandwidth from the publisher when scalable video is active, because additional quality layers are encoded and transmitted.
By default, scalable video is disabled for screen-sharing streams and enabled for camera and custom video source streams. Screen-sharing content typically changes less frequently than camera video, so the additional encoding cost of scalable video is usually unnecessary. However, enabling it can be beneficial in sessions where screen-share subscribers have varying network conditions.
For sessions that support scalable video (that do not have scalable video turned off at the project level), you can override the default scalable video setting for a published stream:
| SDK | Method / Property |
|---|---|
| OpenTok.js | scalableScreenshare option in OT.initPublisher() |
| Android SDK | PublisherKit.Builder.scalableScreenshare() |
| iOS SDK | OTPublisherKitSettings.scalableScreenshare |
| Windows SDK | Publisher.Builder.ScalableScreenshare |
| Linux SDK | otc_publisher_settings_set_scalable_screenshare() |
When a stream is published with scalable video, subscribers can signal a preferred quality to the OpenTok Media Router. The Media Router selects the closest available layer that fits the subscriber's actual network conditions.
Important: Calling
setPreferredResolution()orsetPreferredFrameRate()triggers a renegotiation with the OpenTok Media Router. Doing so repeatedly or in rapid succession is costly — it consumes CPU and can degrade the overall stream quality. Set the preferred values once (or only when the subscriber's layout changes significantly), rather than adjusting them continuously.
All OpenTok clients can subscribe to scalable video streams. The client SDKs include methods or properties for setting the preferred frame rate and resolution for the stream a subscribing client receives from the OpenTok Media Router:
| SDK | Frame rate | Resolution |
|---|---|---|
| OpenTok.js | Subscriber.setPreferredFrameRate() |
Subscriber.setPreferredResolution() |
| Android SDK | SubscriberKit.setPreferredFrameRate() |
SubscriberKit.setPreferredResolution() |
| iOS SDK | OTSubscriberKit.preferredFrameRate |
OTSubscriberKit.preferredResolution |
| Windows SDK | Subscriber.PreferredFramerate |
Subscriber.PreferredResolution |
| Linux SDK | otc_subscriber_set_preferred_frame_rate() |
otc_subscriber_set_preferred_resolution() |
| React Native | preferredFrameRate property of OTSubscriber |
preferredResolution property of OTSubscriber |
There is no single "scalable video active" flag in the SDK, but you can confirm it is operating using the following approaches.
The Video Inspector Tool in the Quality Metrics module displays the codec, resolution, and frame rate. Hover over any point on a plotted line to view the codec currently in use. When scalable video is enabled, the resolution and/or frame rate for one or more subscribers may adjust dynamically in response to changing network conditions.
Each SDK exposes the underlying WebRTC stats report. On the publisher side, inspect RTCOutboundRtpStreamStats:
ssrc entries with different frameWidth/frameHeight values — one per simulcast layer.ssrc with a scalabilityMode property set (for example, L3T3).SDK methods to access the stats report:
Publisher.getRtcStatsReport() and Subscriber.getRtcStatsReport()If you are not observing adaptive quality behavior, verify the following:
No. "Scalable video" is the name of the Vonage Video API feature. The technical mechanism depends on the codec:
Both mechanisms let the OpenTok Media Router adapt the quality each subscriber receives. When documentation mentions "scalable video" without specifying a codec, it refers to the feature as a whole.
No. Selecting a preferred codec (in the dashboard or via the preferredVideoCodecs publisher option) is independent of scalable video. Whether scalable video activates depends on all of the following:
Subscriber.setPreferredResolution() not adapting quality?The subscriber-side setPreferredResolution() and setPreferredFrameRate() are hints to the OpenTok Media Router, not direct commands to the publisher's encoder. The Media Router can only act on these hints when it is actively selecting between scalable video layers for that subscriber. If any of the following conditions is true, there are no layers to select from and the hints have no effect:
Note: In relayed sessions, some SDKs may still accept these API calls without error, but the OpenTok Media Router is not involved in stream forwarding so the preferences cannot be honored for quality-layer selection.
Note: Publisher-side resolution and frame rate APIs (where available in certain SDKs) behave differently — they directly control the encoded stream's resolution and frame rate, not a Media Router quality hint.
Yes. Scalable video is determined per stream, not per session. A session can simultaneously have publishers using scalable video and publishers that are not (for example, H.264 publishers, or clients publishing with scalable video disabled). The OpenTok Media Router handles each stream independently.
For VP8 simulcast, the archiver records using the highest available quality layer.
For VP9 SVC, individual archives store each participant's stream as VP9 SVC-encoded WebM. Composed archives are always transcoded to H.264/AAC MP4 regardless of the session codec.
Playback of VP9 SVC WebM files may not work in all media players. For playback instructions and transcoding commands, see Notes on Archiving in the VP9 guide.
For more information, see this article.