Client

Client

Client object created by TRTC.createClient() for real-time audio/video calls.

Client provide the core APIs of TRTC Web SDK.

Client life cycle:

Methods

(async) join(options) → {Promise}

Enter an audio/video call room.
Room entering indicates the start of an audio/video call. After an audio/video call starts, the SDK listens for the room entering and leaving events of remote users. If a remote user enters the room and publishes a stream,
the local user will receive a 'stream-added' event notification. After entering a room, a user can use publish() to publish a local stream. After the local stream is successfully published, the remote user can receive the corresponding 'stream-added' event notification. In this way, a two-way audio/video call connection is completed.

Example
const client = TRTC.createClient({ mode: 'live', sdkAppId, userId, userSig });
client.join({ roomId: 8888, role: 'anchor' }).then(() => {
  // join room success
}).catch(error => {
  console.error('Join room failed: ' + error);
});
Parameters:
Name Type Description
options object

Room entry parameters

Properties
Name Type Attributes Description
roomId number | string

The room ID is of the number type by default. To use a room ID of the string type, set the useStringRoomId parameter to true in createClient().
If roomId is of the number type, the value must be an integer in the range of [1, 4294967294].
If roomId is of the string type, the value can be up to 64 bytes, and the following character sets are supported:

  • Letters (a-z, A-Z)
  • Digits (0-9)
  • Space ! # $ % & ( ) + - : ; < = . > ? @ [ ] ^ _ { } | ~ , Note: if roomId is of the string type and the room ID needs to be displayed on GUIs, you are advised to escape special characters.
role string <optional>

User role. This parameter is valid only in live mode. Currently, two roles are supported:

  • anchor
  • audience

Note: in live mode, users of the audience role do not have the permission to publish local streams. They have only the permission to view remote streams. If they want to co-anchor with the anchor for interaction, they need to use switchRole() to switch their roles to anchor before publishing local streams.

privateMapKey string <optional>

Deprecated Key for entering a room. If permission control is required, please carry this parameter (empty or incorrect value will cause a failure in entering the room).
privateMapKey permission configuration

Throws:

RtcErr

Returns:
Type
Promise

(async) leave() → {Promise}

Leave the current audio/video call room to end the audio/video call.
Before leaving a room, make sure that you have unpublished local streams via unpublish(). Otherwise, the SDK will automatically unpublish them. In addition, all remote streams will be stopped when you leave the room.

Example
client.leave().then(() => {
  // leaving room success
}).catch(error => {
  console.error('leaving room failed: ' + error);
});
Returns:
Type
Promise

destroy()

Destroy client.

When to call:

  • After leave room, if the business side no longer needs to use the client, this interface should be called to destroy the client instance in time to release the relevant resources.
  • When the user's network is not good, client.join may take a long time, you can call this interface to interrupt the client.join call process.

Note:

  • Destroyed client cannot be used anymore.
  • If client has joined room, you have call client.leave to leave room before call client.destroy().
Since:
  • v4.13.0
Examples
let client = TRTC.createClient({ sdkAppId, userId, userSig, mode: 'rtc' });
await client.join({ roomId: 123456 });
// leave room before client.destroy()
await client.leave();
// destroy client if the client is useless.
client.destroy();
client = null;
let client = TRTC.createClient({ sdkAppId, userId, userSig, mode: 'rtc' });
// It is assumed that the business logic needs to finish joining the room within 5s, otherwise the join timeout is considered.
const id = setTimeout(() => {
 // destroy client to abort client.join()
 client.destroy();
 client = null;
}, 5000)
try {
 await client.join({ roomId: 123456 });
} catch(error) {}
clearTimeout(id);

(async) publish(stream, optionsopt) → {Promise}

Publish the local audio/video stream.

When the current user publishes a local stream, the corresponding remote user will receive the stream-added event notification.

NOTE

  • This API works only if it is called after users enter a room via join().
  • After publishing a local stream, you can use removeTrack(), addTrack(), and replaceTrack() to update an audio or video stream in the local stream.
  • If the client's mode is 'live' and role is 'audience', that is, under the audience role in live mode, users do not have the permission to publish local streams. If they want to co-anchor with the anchor for interaction, they need to use switchRole('anchor') to switch their roles to anchor before publishing local streams.
  • Do not call this API before the LocalStream.switchDevice API call is completed. Otherwise, device switching exceptions may occur.
  • In v4.15.0+, the SDK supports publishing main stream + auxiliary stream at the same time for one Client. What is 'Main Stream' and 'Auxiliary Stream'? Refer to: Screen sharing.
Examples
const localStream = TRTC.createStream({
  userId: 'userA',
  audio: true, // capture microphone
  video: true // capture camera
})
await localStream.initialize();
await client.publish(localStream);
const shareStream = TRTC.createStream({
  userId: 'userA',
  screen: true, // capture screen share
})
await shareStream.initialize();
// publish shareStream on auxiliary stream by setting 'isAuxiliary' to true. Supported v4.15.0+.
await client.publish(shareStream, { isAuxiliary: true });
Parameters:
Name Type Attributes Description
stream Stream

Local stream, created via createStream()

options Object <optional>
Properties
Name Type Attributes Default Description
isAuxiliary boolean <optional>
false

Whether publish stream on auxiliary stream.

  • SDK version supported: v4.15.0+.
  • Browsers supported: Chrome 69+, Safari 11+, Firefox 59+, Edge 79+.
Throws:

RtcError

Returns:
Type
Promise

(async) unpublish(stream) → {Promise}

Unpublish a local stream.
After a local stream is unpublished, the remote user will receive the 'stream-removed' event notification.
You need to unpublish the local stream before leaving the room via leave().

Example
// Unpublish the local stream
client.unpublish(localStream).then(() => {
  // Unpublishing the local stream is successful
});
Parameters:
Name Type Description
stream Stream

Local stream

Throws:

RtcErr

Returns:
Type
Promise

(async) subscribe(stream, optionsopt)

Subscribe to a remote stream.
By default, when you receive the 'stream-added' event notification for a remote stream, the SDK immediately receives and decodes the audio/video data contained in that stream.
You can use this subscription API to specify whether to subscribe to audio, video, or audio/video streams. If you do not want to receive any audio/video data contained in the remote stream, use unsubscribe() to unsubscribe from the stream.

NOTE

  • For the same remote stream, you can start the next call only after the current subscribe/unsubscribe call is completed.
Examples
// Listen for remote stream subscription success events
client.on('stream-subscribed', event => {
  const remoteStream = event.stream;
  // Play back the remote audio/video stream after successful subscription
  remoteStream.play('remote_stream');
});
// Listen for remote stream 'stream-added' events
client.on('stream-added', event => {
  const remoteStream = event.stream;
  // Subscribe to remote audio/video streams
  client.subscribe(remoteStream, { audio: true, video: true }).catch(e => {
    console.error('failed to subscribe remoteStream');
  });
  // Subscribe to audio data only
  // client.subscribe(remoteStream, { audio: true, video: false }).catch(e => {
  //  console.error('failed to subscribe remoteStream');
  // });
});
// For the same remote stream, you can start the next call only after the current `subscribe`/`unsubscribe` call is completed
// bad
client.subscribe(remoteStream, { audio: true, video: true });
client.unsubscribe(remoteStream);
// good
await client.subscribe(remoteStream, { audio: true, video: true });
await client.unsubscribe(remoteStream);
Parameters:
Name Type Attributes Description
stream Stream

Remote stream, obtained via listening for 'stream-added' events

options object <optional>

Subscription options

Properties
Name Type Attributes Default Description
audio boolean <optional>
true

Whether to subscribe to audio data

video boolean <optional>
true

Whether to subscribe to video data

Fires:
  • ClientEvent.event:STREAM_SUBSCRIBED subscription success event notification
Throws:

RtcErr

(async) unsubscribe(stream)

Unsubscribe from the remote stream.
When receiving a remote stream 'stream-added' event notification, the SDK will immediately receive and decode the audio/video data contained in the remote stream by default. To refuse to receive any audio/video data from the remote stream, call this API in the 'stream-added' event processing callback.
Note:

  • For the same remote stream, you can start the next call only after the current subscribe/unsubscribe call is completed.
Examples
client.on('stream-added', event => {
  const remoteStream = event.stream;
  // Refuse to receive any audio/video data from the remote stream
  client.unsubscribe(remoteStream).catch(e => {
    console.error('failed to unsubscribe remoteStream');
  });
});
// For the same remote stream, you can start the next call only after the current `subscribe`/`unsubscribe` call is completed
// bad
client.subscribe(remoteStream, { audio: true, video: true });
client.unsubscribe(remoteStream);
// good
await client.subscribe(remoteStream, { audio: true, video: true });
await client.unsubscribe(remoteStream);
Parameters:
Name Type Description
stream Stream

Remote stream, obtained via listening for 'stream-added' events

Throws:

RtcErr

(async) switchRole(role) → {Promise}

Switch the user role. Valid only in 'live' mode. In interactive live streaming mode, a user can switch between audience and anchor roles. You can use the role field in join() to specify the role or use switchRole to switch the role after entering a room.

  • Switch from audience to anchor: call client.switchRole('anchor') to switch the user role from audience to anchor and call publish() to publish the local stream.
  • Switch from anchor to audience: call client.switchRole('audience') to switch the user role from anchor to audience. If a published local stream exists, the SDK will unpublish it.
Example
// In `live` mode, switch the user role from `audience` to `anchor`
await client.switchRole('anchor');
// Switch the user role from `audience` to `anchor` and start pushing streams
await client.publish(localStream);
// In `live` mode, switch the user role from `anchor` to `audience`
await client.switchRole('audience');
Parameters:
Name Type Description
role string

User role

  • Anchors can publish local streams. A single room allows up to 50 anchors to publish local streams at the same time.
  • Audience cannot publish local streams. They can only watch remote streams. There is no limit on the number of audience in a single room.
Throws:

RtcErr

Returns:
Type
Promise

on(eventName, handler, context)

Listen for client object events.
For the detailed event list, please see ClientEvent.

Example
client.on('stream-added', event => {
  // stream-added event handler
});
Parameters:
Name Type Description
eventName string

Event name

handler function

Event handling method

context context

Context

off(eventName, handler, context)

Unbind events.
This API is used to unbind events bound via on().

Example
client.on('peer-join', function peerJoinHandler(event) {
  // Peer-join event handler
  console.log('peer joined');
  client.off('peer-join', peerJoinHandler);
});
// Unbind all bound events
client.off('*');
Parameters:
Name Type Description
eventName string

Event name. If the wildcard '*' is passed in, all bound events will be unbound.

handler function

Event handling method

context context

Context

getRemoteMutedState() → {Array.<RemoteMutedState>}

Get the list of the audio/video mute status of remote users in the current room.

Since:
  • 4.11.2 Added the `hasSmall` attribute to identify whether a remote stream has a substream video.
Returns:

Array of the audio/video mute status of remote use

Type
Array.<RemoteMutedState>

(async) getTransportStats() → {Promise.<TransportStats>}

Get current network transfer statistics.
NOTE

  • This API works only if it is called after publish().
  • Firefox does not support getting RTT statistics.
Example
const stats = await client.getTransportStats();
console.log('uplink rtt: ' + stats.rtt);
// Getting downstream RTT statistics is supported starting from v4.10.1
for (let userId in stats.downlinksRTT) {
   console.log('downlink rtt:' + stats.downlinksRTT[userId]);
}
Returns:

Promise successfully returns TransportStats</cod

Type
Promise.<TransportStats>

(async) getLocalAudioStats() → {Promise.<LocalAudioStatsMap>}

Get audio statistics of published local streams.
This API works only if it is called after publish().

Example
client.getLocalAudioStats().then(stats => {
  for (let userId in stats) {
    console.log('userId: ' + userId +
                ' bytesSent: ' + stats[userId].bytesSent +
                ' packetsSent: ' + stats[userId].packetsSent);
  }
});
Returns:

Promise successfully returns LocalAudioStatsMap</cod

Type
Promise.<LocalAudioStatsMap>

(async) getLocalVideoStats() → {Promise.<LocalVideoStatsMap>}

Get video statistics of published local streams.
This API works only if it is called after publish().

Example
client.getLocalVideoStats().then(stats => {
  for (let userId in stats) {
    console.log('userId: ' + userId +
                'bytesSent: ' + stats[userId].bytesSent +
                'packetsSent: ' + stats[userId].packetsSent +
                'framesEncoded: ' + stats[userId].framesEncoded +
                'framesSent: ' + stats[userId].framesSent +
                'frameWidth: ' + stats[userId].frameWidth +
                'frameHeight: ' + stats[userId].frameHeight);
  }
});
Returns:

Promise successfully returns LocalVideoStatsMap</cod

Type
Promise.<LocalVideoStatsMap>

(async) getRemoteAudioStats() → {Promise.<RemoteAudioStatsMap>}

Get audio statistics of all current remote streams.

Example
client.getRemoteAudioStats().then(stats => {
  for (let userId in stats) {
    console.log('userId: ' + userId +
                ' bytesReceived: ' + stats[userId].bytesReceived +
                ' packetsReceived: ' + stats[userId].packetsReceived +
                ' packetsLost: ' + stats[userId].packetsLost);
  }
});
Returns:

Promise successfully returns RemoteAudioStatsMap</cod

Type
Promise.<RemoteAudioStatsMap>

(async) getRemoteVideoStats(typeopt) → {Promise.<RemoteVideoStatsMap>}

Get video statistics of all current remote streams.

Example
// Get camera video statistics of the primary stream
const stats = await client.getRemoteVideoStats('main');
// Get screen sharing statistics of the substream
const stats = await client.getRemoteVideoStats('auxiliary');
Parameters:
Name Type Attributes Default Description
type string <optional>
'main'

Stream type

  • main: get camera video statistics of the primary stream
  • auxiliary: get screen sharing statistics of the substream; supported in v4.10.1 and later versions
Returns:

Promise successfully returns RemoteVideoStatsMap</cod

Type
Promise.<RemoteVideoStatsMap>

(async) startPublishCDNStream(options) → {Promise}

开始发布当前用户音视频流到 CDN

使用该接口的时,您需要注意:

  • 请先在 实时音视频控制台 中的功能配置页开启“启用旁路推流”,并根据业务需求选择“指定流旁路” 或 “全局自动旁路”。
  • 请在成功发布本地流 publish 之后调用该接口。

该接口的应用场景:

  1. 开始发布当前用户音视频流到腾讯云 CDN 或修改发布到腾讯云 CDN 的 StreamId
  • “指定流旁路”模式下,您可以通过该接口将当前用户音视频流推送到腾讯云 CDN 且指定 StreamId;
  • “全局自动旁路”模式下,您可以通过该接口调整当前用户的 StreamId;
    注意:该接口会指定当前用户的音视频流在腾讯云 CDN 所对应的 StreamId,进而可以指定当前用户的 CDN 播放地址。
    例如:使用 client.startPublishCDNStream 设置当前用户的主画面 StreamId 为 user_stream_001, 那么该用户主画面对应的 CDN 播放地址为:"http://yourdomain/live/user_stream_001.flv",其中 yourdomain 为您自己备案的播放域名。 您可以在 云直播域名管理 配置您的播放域名,腾讯云不提供默认的播放域名。
  1. 将当前用户音视频流发布到指定的 CDN 地址

停止将当前用户的音视频流推送到 CDN 的方法:

  • 当前用户调用 stopPublishCDNStream 停止发布音视频流到 CDN;
  • 当前用户退出房间;

更多详细内容可以参考 实现推流到 CDN

Since:
  • 4.10.0
Example
// example 1:“全局自动旁路”模式下,修改当前用户音视频流在腾讯云 CDN 对应的 StreamId
let options = { streamId: 'user_stream_001' }
client.startPublishCDNStream(options);
// example 2:“指定流旁路”模式下,以默认 streamId: ${sdkAppId}_${roomId}_${userId}_main 发布当前用户音视频流到腾讯云 CDN
client.startPublishCDNStream();
// example 3:“指定流旁路”模式下,以指定 streamId 发布当前用户音视频流到腾讯云 CDN
let options = { streamId: 'user_stream_001' }
client.startPublishCDNStream(options);
// example 4: 将当前用户音视频流发布到指定的 CDN 地址
// 说明:如有需要,example 4 可以和 example1,2,3 结合使用
let options = {
 appId: 0,
 bizId: 0,
 url: ''
}
client.startPublishCDNStream(options);
Parameters:
Name Type Description
options Object

发布当前用户音视频流到 CDN 的参数

Properties
Name Type Description
streamId string

自定义流ID, 默认为${sdkAppId}_${roomId}_${userId}_main

appId number

腾讯云直播 appId [发布当前用户音视频流到指定 CDN 时必填]
请在 实时音视频控制台【应用管理】-【应用信息】-【旁路直播信息】中获取

bizId number

腾讯云直播 bizId [发布当前用户音视频流到指定 CDN 时必填]
请在 实时音视频控制台【应用管理】-【应用信息】-【旁路直播信息】中获取

url string

指定的 CDN 推流地址[发布当前用户音视频流到指定 CDN 时必填]

Returns:
Type
Promise

(async) stopPublishCDNStream() → {Promise}

停止发布当前用户音视频流到 CDN
请在成功发布当前用户音视频流到 CDN(startPublishCDNStream)之后调用该接口

注意:“全局自动旁路”模式下调用 client.stopPublishCDNStream 将停止向指定的 CDN 发布当前用户音视频流,但无法停止向腾讯云 CDN 发布当前用户音视频流。

Since:
  • v4.10.0
Example
client.stopPublishCDNStream();
Returns:
Type
Promise

(async) startMixTranscode(config) → {Promise}

开始混流转码,请在进房推流后调用该接口

如果您在实时音视频 控制台 中的功能配置页开启了“启用旁路直播”功能, 房间里的每一路画面都会有一个默认的直播 CDN 地址
一个直播间中可能有不止一位主播,而且每个主播都有自己的画面和声音,但对于 CDN 观众来说,他们只需要一路直播流, 所以您需要将多路音视频流混成一路标准的直播流,这就需要混流转码。

当您调用 startMixTranscode 接口发起混流转码时,SDK 会向腾讯云的转码服务器发送一条指令,目的是将房间里的多路音视频流混合为一路
开发者可以通过 config.mixUsers 来调整每一路混入流的参数,也可以通过 config.videoWidth、config.videoHeight、config.videoBitrate 等属性控制混合后音视频流的编码值

注意:

  • 混流转码为收费功能,调用 startMixTranscode 接口将产生云端混流转码费用,详见 云端混流转码计费说明
  • 若您还在房间中且不再需要混流,请务必调用 stopMixTranscode 进行取消,因为当您发起混流后,云端混流模块就会开始工作,不及时取消混流可能会引起不必要的计费损失。
  • 请放心,您退房时会自动取消混流状态。

版本说明:

  • v4.11.5 开始支持跨房间混流
  • 跨房间混流时,同一个 sdkAppId 请务必选用同一种房间号码类型(数字类型或者字符串类型),避免影响混流结果。
  • 跨房间混流时,如果您启用的是“手动旁路”模式,与发起混流用户不在同一房间的用户需要先开启旁路。开启旁路的方式请参考 startPublishCDNStream 或 createClient 的 streamId 字段。
  • v4.9.0 开始支持预排版模式混流
  • v4.8.0 开始支持全手动模式混流
Since:
  • v4.8.0
Examples
try {
 // 预排版模式,自 v4.9.0 版本开始支持
 const config = {
    mode: 'preset-layout',
    videoWidth: 1280,
    videoHeight: 720,
    videoBitrate: 1500,
    videoFramerate: 15,
    videoGOP: 2,
    audioSampleRate: 48000,
    audioBitrate: 64,
    audioChannels: 1,
    // 预设一路本地摄像头、一路本地屏幕分享、两路远端流的排版位置
    mixUsers: [
       {
         width: 960,
         height: 720,
         locationX: 0,
         locationY: 0,
         pureAudio: false,
         userId: 'share_123456', // 本地屏幕分享占位,填写用于推屏幕分享流的 client userId
         zOrder: 1
       },
       {
         width: 320,
         height: 240,
         locationX: 960,
         locationY: 0,
         pureAudio: false,
         userId: '123456', // 本地摄像头占位,填写用于推摄像头流的 client userId
         zOrder: 1
       },
       {
         width: 320,
         height: 240,
         locationX: 960,
         locationY: 240,
         pureAudio: false,
         userId: '$PLACE_HOLDER_REMOTE$', // 远端流占位
         zOrder: 1
       },
       {
         width: 320,
         height: 240,
         locationX: 960,
         locationY: 480,
         pureAudio: false,
         userId: '$PLACE_HOLDER_REMOTE$', // 远端流占位
         zOrder: 1
       },
       {
         width: 320,
         height: 240,
         locationX: 960,
         locationY: 720,
         pureAudio: false,
         userId: 'user_355624',
         roomId: 355624,  // roomId 字段自 v4.11.5 版本开始支持,支持跨房间混流
         zOrder: 1,
       },
     ];
  }
  await client.startMixTranscode(config);
} catch (e) {
  console.error('startMixTranscode failed ', e);
}
// 全手动模式 自 v4.8.0 版本开始支持
try {
  const config = {
    mode: 'manual',
    videoWidth: 1280,
    videoHeight: 720,
    videoBitrate: 1500,
    videoFramerate: 15,
    mixUsers: [
      {
        userId: 'user_1',
        roomId: 12345, // roomId 字段自 v4.11.5 版本开始支持,支持跨房间混流
        pureAudio: false,
        width: 640,
        height: 480,
        locationX: 0,
        locationY: 0,
        streamType: 'main', // 指明该配置为远端主流
        zOrder: 1
      },
      {
        userId: 'user_1',
        roomId: 12345, // roomId 字段自 v4.11.5 版本开始支持,支持跨房间混流
        pureAudio: false,
        width: 640,
        height: 480,
        locationX: 640,
        locationY: 0,
        streamType: 'auxiliary', // 指明该配置为远端辅流
        zOrder: 1
      },
    ]
  }
  await client.startMixTranscode(config);
} catch (error) {
  console.error('startMixTranscode failed: ', error);
}
Parameters:
Name Type Description
config object

混流转码参数列表

Properties
Name Type Description
mode string

混流模式,支持全手动模式(manual)、预排版模式(preset-layout),默认为全手动模式

预排版模式(preset-layout) 全手动模式(manual)
调用次数 只需调用一次 以下场景需调用混流接口:
- 有连麦者加入时
- 有连麦者离开时
- 连麦者开关摄像头、开关麦克风时
混合内容 自定义设置混流模板
开发者需要预设本地摄像头、本地屏幕分享、远端流的排版位置,SDK 会在恰当的时机,根据预设的模板,自动更新混流参数。
参考:云端混流-预排版模式
自定义设置各路内容
开发者需要自行控制更新混流参数的时机。
streamId string

混流转码后的流 ID,默认值为''
若 streamId 为 '',mixUsers 中的其他用户流会混合到接口调用者的视频流上,转推流名为 ${sdkappid}_${roomid}_${userid}_main
若 streamId 非 '',mixUsers 中所有用户的流会混合为流名为 ${streamId} 的视频流上,转推名为 ${streamId}

videoWidth number

转码后视频分辨率的宽度(px),转码后视频的宽度设置必须大于等于 0 且能容纳所有混入视频,默认值为 640

videoHeight number

转码后视频分辨率的高度(px),转码后视频的高度设置必须大于等于 0 且能容纳所有混入视频,默认值为 480

videoBitrate number

转码后的视频码率(kbps),如果传入值为 0,码率值将由 videoWidth 和 videoHeight 决定

videoFramerate number

转码后的视频帧率(fps),默认值为 15, 取值范围为(0, 30]

videoGOP number

转码后的视频关键帧间隔(s),默认值为 2,取值范围为[1, 8]

audioSampleRate number

转码后的音频采样率(Hz),默认值为 48000

audioBitrate number

转码后的音频码率(kbps),默认值为 64,取值范围为[32, 192]

audioChannels number

转码后的音频声道数, 默认值为 1,取值范围为 1 或 2

backgroundColor number

混合后画面的背景颜色,格式为十六进制数字,默认值为 0x000000(黑色)

backgroundImage string

混合后画面的背景图,默认值为 ''

mixUsers Array.<MixUser>

混入用户流的信息列表[必填],必须包含接口调用者的信息

Returns:
Type
Promise

(async) stopMixTranscode()

停止混流转码
请在成功发布本地流(publish)及成功开始混流转码(startMixTranscode)之后调用该接口

停止混流转码的方法:

  • 发起混流转码的用户调用 stopMixTranscode
  • 发起混流转码的用户退出房间
Since:
  • v4.8.0
Example
// 停止混流转码
try {
 await client.stopMixTranscode();
} catch (e) {
 console.error('stopMixTranscode fail', e);
}

enableAudioVolumeEvaluation(intervalopt, enableInBackgroundopt)

Enable/Disable the volume callback feature.
If the volume callback feature is enabled, the SDK periodically throws the Client.on('audio-volume') volume callback event to provide the evaluated volume of each user regardless of whether someone is speaking in the room.
NOTE

  • The SDK provides evaluated volume values only for audio/video streams that call the stream.play API.
Since:
  • v4.9.0
Example
client.on('audio-volume', event => {
    event.result.forEach(({ userId, audioVolume, stream }) => {
        console.log(`userId: ${userId}, audioVolume: ${audioVolume}`);
    })
})
// Enable volume callback and set the SDK to trigger the volume callback event at an interval of 1000 ms
client.enableAudioVolumeEvaluation(1000);
// To disable volume callback, you only need to pass in a value less than or equal to 0 for `interval`
client.enableAudioVolumeEvaluation(-1);
Parameters:
Name Type Attributes Default Description
interval number <optional>
2000

Time interval for triggering the volume callback event. The default value is 2000 (ms), and the minimum value is 16 (ms). If this parameter is set to a value less than or equal to 0, volume callback is disabled.

enableInBackground boolean <optional>
false

For performance reasons, the SDK does not throw a volume callback event after your application is switched to the background. If you want to receive the volume callback event after your application is switched to the background, set this parameter to true.

(async) enableSmallStream() → {Promise}

Enable the big/small stream mode on the push end.
When the big/small stream mode is enabled, do not perform operations (including addTrack, removeTrack, and replaceTrack) on tracks. Otherwise, performance inconsistency between the big and small streams occurs.

Note:

  • This API works only if it is called before stream publishing (publish) or after stream unpublishing (unpublish).
  • The big/small stream mode cannot be enabled during stream publishing.
  • Because browsers have different restrictions on media elements, the big/small stream mode cannot be enabled on iOS and WeChat.
Since:
  • 4.11.0
Example
// Enable the small stream mode
await client.enableSmallStream();
// Local stream initialized successfully
await localStream.initialize();
// Publish a local stream
await client.publish(localStream);
Throws:

RtcErr

Returns:
Type
Promise

(async) disableSmallStream() → {Promise}

Disable the big/small stream mode on the push end.
Note that this API must be called before stream publishing or after stream unpublishing. If it is called after stream publishing and before stream unpublishing, performance inconsistency will occur between the big and small streams.

Since:
  • 4.11.0
Example
await client.unpublish(localStream);
await client.disableSmallStream();
Throws:

RtcErr

Returns:
Type
Promise

setSmallStreamProfile(options)

Set small stream parameters.
If this API is not called, the SDK uses the default small stream video attributes: resolution (W × H) of 160x120, bitrate of 100 Kbps, and frame rate of 15 fps.
The SDK automatically ensures the aspect ratio consistency between the big and small streams. If the resolution aspect ratio of the small stream is different from that of the big stream, the SDK automatically adjusts the height of the video resolution of the small stream to achieve the same aspect ratio as that of the big stream.

Note: The enableSmallStream and setSmallStreamProfile APIs work only if they are called before publish, and the order in which they are called does not affect their functionalities.

Since:
  • 4.11.0
Example
client.setSmallStreamProfile({
  width: 160,
  height: 120,
  bitrate: 100,
  frameRate: 15
});
Parameters:
Name Type Description
options Object
Properties
Name Type Description
width Number

Width of the video resolution of the small stream

height Number

Height of the video resolution of the small stream

bitrate Number

Bitrate of the small stream

framerate Number

Frame rate of the small stream

setRemoteVideoStreamType(remoteStream, status)

Switch the big/small stream attribute on the audience side.
The big/small stream attribute can be switched successfully only when the small stream mode is enabled on the remote end.
You must call setRemoteVideoStreamType after successfully subscribing to the remote stream:

  • In the stream-subscribed callback, immediately switch the remote big stream to the small stream.
  • After subscribing to the big stream for some time, call setRemoteVideoStreamType to switch the big stream to the small stream.
  • After subscribing to the small stream for some time, you can call setRemoteVideoStreamType to switch the small stream to the big stream.
Since:
  • 4.11.0
Example
// Set the big/small stream attribute for the remote stream
client.setRemoteVideoStreamType(remoteStream, 'small');
Parameters:
Name Type Description
remoteStream RemoteStream

Remote stream subscribed

status String
  • 'big': manually switch to the big stream
  • 'small': manually switch to the small stream
Throws:

RtcErr

sendSEIMessage(buffer, optionsopt)

send SEI message

The principle of the interface is to use this header block, called SEI, to embed a custom message you want to send along with the video frame. The SEI message can accompany the video frame all the way to the live CDN.

Applicable scene: precise layout of video screen, lyrics synchronization, live Q&A, etc.

When to call: after publish localStream successfully.
Note:

  1. The max buffer size is 1000(byte). The max call times in a second is 30. The max size can be send in a second is 8KB(byte).
  2. Supported browsers: Chrome 86+, Edge 86+, Opera 72+.
  3. Since the SEI is sent along with the video frame, there is a possibility that the video frame is lost and therefore the SEI may also be lost.
  4. SEI cannot be sent when there is no video published, and cannot be received when there is no video subscribed.
  5. Supported codec: H264.
Since:
  • v4.14.1
Example
// 1. enable SEI
const client = TRTC.createClient({
   sdkAppId: 24215236, // fake sdkAppId
   userId: 'test',
   userSig: 'fake',
   enableSEI: true // enable SEI
})
// 2. send SEI
try {
 const unit8Array = new Uint8Array([1, 2, 3]);
 client.sendSEIMessage(unit8Array.buffer);
 // SEI message will be sent along with next video frame.
} catch(error) {
 // Failed to send, reasons:
 // - not support on current browser.
 // - client has not publish localStream or localStream has no video.
 // - api call times or max buffer size in a second is over the limitation.
 // - without using H264 codec.
 // etc.
 console.warn(error);
}
// 3. received SEI message
client.on('sei-message', event => {
 console.warn(`received ${event.userId} sei message ${event.data}`);
})
Parameters:
Name Type Attributes Description
buffer ArrayBuffer

ArrayBuffer to be sent. The max buffer size is 1000(byte).

options Object <optional>
Properties
Name Type Description
seiPayloadType Number

The SDK uses custom payloadType 243 by default, the business side can use this parameter to set the payloadType to the standard 5. When the business side uses 5 payloadType, make sure the first 16 bytes of the buffer are the business side custom uuid according to the specification.

setProxyServer(url)

Set a proxy server.
This API is suitable where you deploy proxy servers, e.g., Nginx+Coturn, by yourself.


Note:
  • This API works only if it is called before join().
Example
client.setProxyServer('wss://proxy.example.com:443');
Parameters:
Name Type Description
url string

WebSocket proxy server address, for example, wss://proxy.example.com:443

setTurnServer(options)

Set TURN servers.
This API is used along with setProxyServer() and is suitable where you deploy proxy and TURN servers by yourself.


Note:
  • This API works only if it is called before join().
  • For versions earlier than v4.8.5, this API can be used to set only one TURN server, and a value of the Object type must be passed in.
  • For v4.8.5 and later versions, this API can be used to set multiple TURN servers, and a value of the Array type must be passed in.
Example
// For versions earlier than v4.8.5, this API can be used to set only one TURN server
client.setTurnServer({ url: '192.168.0.110:3478', username: 'bob', credential: 'bobspassword', credentialType: 'password' });
// For v4.8.5 and later versions, this API can be used to set multiple TURN servers
client.setTurnServer([{ url: '192.168.0.110:3478', username: 'bob', credential: 'bobspassword', credentialType: 'password' }]);
Parameters:
Name Type Description
options array
Properties
Name Type Description
config object

TURN server configuration items

Properties
Name Type Attributes Description
url string

TURN server URL

username string <optional>

TURN server verification username

credential string <optional>

TURN server verification password

credentialType string <optional>

Type of the TURN server verification password. The default value is password
credentialType reference


Documentation generated by JSDoc 3.6.11 on Tue Jun 11 2024 19:17:34 GMT+0800 (中国标准时间) using the docdash theme.