Tutorial: Enabling Dual-Stream Mode

Enabling Dual-Stream Mode

Prerequisites

To use the big stream/small stream feature, you need to upgrade the SDK to v4.11.0.

Connection Guide

Step 1. Check the environment support

Check whether the current environment supports big stream/small stream.

const result = TRTC.isSmallStreamSupported()
if (!result) {
  alert('You browser does not support opening small streams.')
}

Step 2. Enable the big stream/small stream feature

Before publishing video, the client calls the enableSmallStream method to enable the big stream/small stream mode.

// Enable before calling `publish`
await client.enableSmallStream();
// Initialized the local stream successfully
await localStream.initialize();
// Publish the local stream
await client.publish(localStream);

Step 3. The viewer client switches the remote stream to the small stream

Before v4.12.5 Before enabling the small stream, check whether the remote stream contains a small stream. You can call the client.getRemoteMutedState method to check whether the hasSmall status of the remote stream is true

// After a video stream is successfully subscribed to
await client.subscribe(remoteStream, { audio: true, video: true });

If you want to switch the big stream to small stream, you need to determine if the remote stream has a small stream before switching to the small stream.

const state = client.getRemoteMutedState()
  .filter((item) => item.userId === remoteStream.getUserId())[0];
if (!(state && state.hasSmall)) {
  console.log('The substream is not enabled in the remote stream');
  return;
}
// The viewer client actively sets the subscribed video stream to the substream
client.setRemoteVideoStreamType(remoteStream, 'small');

v4.12.5+

The viewing end actively sets the subscribed video streams to small streams, and does not need to determine whether the remote streams are pushed with small streams. When the remote stream has a small stream, the SDK will automatically subscribe to the small stream.

await client.setRemoteVideoStreamType(remoteStream, 'small');
await client.subscribe(remoteStream, { audio: true, video: true });

API Description

The audio/video call client object Client is created through createClient() and represents an audio/video call. It provides the core features of the TRTC SDK for Web.

TRTC.isSmallStreamSupported()

Feature: this API is used to check whether the current browser environment supports enabling the big stream/small stream feature. The returned value is of Boolean type. true indicates that the feature is supported, while false indicates not supported.

Note: in iOS and WeChat environments, the big stream/small stream feature cannot be enabled.

const result = TRTC.isSmallStreamSupported()
if (!result) {
  alert('You browser does not support opening small streams.')
}

Client.enableSmallStream()

Feature: this API is used to enable the big stream/small stream transfer mode on the video push terminal. Dual stream means the primary video stream and small stream, where the former refers to a high-resolution and high-bitrate video stream, and the latter refers to a low-resolution and low-bitrate video stream.

How to use: it must be set before the stream is published to avoid big stream/small stream performance inconsistency.

Note: do not perform any operations on track when enabling the big stream/small stream mode (including addTrack, removeTrack, and replaceTrack); otherwise, big stream/small stream performance inconsistency will occur.

// Enable before calling `publish`
await client.enableSmallStream();
// Initialized the local stream successfully
await localStream.initialize();
// Publish the local stream
await client.publish(localStream);

Client.disableSmallStream()

Feature: this API is used to disable big stream/small stream transfer.

How to use: it must be called before the stream is published or after stream publishing ends so as to avoid big stream/small stream performance inconsistency.

await client.unpublish(remoteStream);
// It must be called before the stream is published or after stream publishing ends
await client.disableSmallStream();

Client.setSmallStreamProfile(params)

Feature: this API is used to set the small stream parameters.

How to use: it must be called before the stream is published or after stream publishing ends so as to avoid big stream/small stream performance inconsistency.

If this method is not called, the SDK will use the default small stream video attributes: 160x120 px for resolution (width * height), 100 Kbps for bitrate, and 15 fps for frame rate.

The aspect ratios of the small stream video and big stream video will become the same automatically. If the aspect ratio set for the small stream is different from that of the big stream, the SDK will automatically adjust the small stream height to make their aspect ratios the same.

Note:

enableSmallStream and setSmallStreamProfile must be called before publish. The call sequence of them does not matter.

Params

Name Type Description
width number small stream video width
height number small stream video height
bitrate number small stream video bitrate
frameRate number small stream video frame rate
// If the aspect ratio of your big stream is 4 : 3, you need to set the parameters of the small stream to 4 : 3
client.setSmallStreamProfile({
  width: 160,
  height: 120,
  bitrate: 100,
  frameRate: 15
});
// If the aspect ratio of your big stream is 16 : 9, you need to set the parameters of the small stream to 16 : 9
client.setSmallStreamProfile({
  width: 160,
  height: 90,
  bitrate: 100,
  frameRate: 15
});

Client.setRemoteVideoStreamType(remoteStream, type)

You can call this function after successfully subscribing to the remote stream.

The receiver selects to manually subscribe to the big stream or small stream. The big stream is selected by default.

  • big: manually switches to big stream.
  • small: manually switches to small stream.
Name Type Description
stream stream Remote video stream object
type string big: manually switches to big stream
small: manually switches to small stream.
client.setRemoteVideoStreamType(remoteStream, 'small');

FAQs

  1. enableSmallStream and setSmallStreamProfile must be called before publish. The call sequence of them does not matter.

  2. The viewer client needs to call setRemoteVideoStreamType after the remote stream is successfully subscribed to:

    • In the stream-subscribed callback, immediately switch the remote big stream to the small stream.
    • After subscribing to the big stream for a while, call setRemoteVideoStreamType to switch to the small stream.
    • After subscribing to the small stream for a while, call setRemoteVideoStreamType to switch to the big stream.
  3. The switch from the big stream to the small stream takes effect on the viewer client only if the small stream is enabled on the push terminal.

  4. Currently, there are no event notifications for big stream/small stream switch.