Client

Client

音视频通话客户端对象 Client 通过 createClient() 创建，代表一次音视频会话。
Client 客户端对象提供 TRTC Web SDK 的核心功能，包括:

Methods

setProxyServer(url)

设置代理服务器
该方法适用于企业自己部署代理服务器，如 nginx+coturn 方案。


Note:
  • 该方法需要在 join() 之前调用。
Example
client.setProxyServer('wss://proxy.example.com:443');
Parameters:
Name Type Description
url string

websocket 代理服务器地址，格式如：‘wss://proxy.example.com:443’

setTurnServer(config)

设置 TURN 服务器
该方法配合 setProxyServer() 使用，适用于企业自己部署代理服务器和 TURN 中转。


Note:
  • 该方法需要在 join() 之前调用。
Example
client.setTurnServer({ url: '192.168.0.110:3478', username: 'bob', credential: 'bobspassword', credentialType: 'password' });
Parameters:
Name Type Description
config object

TURN 服务器配置项

Properties
Name Type Attributes Description
url string

TURN 服务器 url
username string <optional>

TURN 服务器验证用户名
credential string <optional>

TURN 服务器验证密码
credentialType string <optional>

TURN 服务器验证密码类型，默认是 ‘password’
credentialType 参考

(async) join(options) → {Promise}

加入一个音视频通话房间。
进房代表开始一个音视频通话会话，这时候 SDK 会监听远端用户进房退房情况，若有远端用户进房并且发布流，
本地会收到 'stream-added' 事件。进房后用户可以通过 publish() 发布本地流，本地流发布成功后远端用户就会收到相应 'stream-added' 事件通知从而完成一个双向的音视频通话连接。

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

进房参数

Properties
Name Type Attributes Description
roomId number | string

默认是 number 类型，如需使用 string 类型的 roomId，请在 createClient() 中设置 useStringRoomId 参数为 true。
roomId 为 number 类型时，取值要求为 [1, 4294967294] 的整数;
roomId 为 string 类型时，限制长度为64字节，且仅支持以下范围的字符集：

  • 大小写英文字母（a-zA-Z）;
  • 数字（0-9）;
  • 空格、"!"、"#"、"$"、"%"、"&"、"("、")"、"+"、"-"、":"、";"、"<"、"="、"."、">"、"?"、"@"、"["、"]"、"^"、"_"、" {"、"}"、"|"、"~"、",";

注意：若 roomId 为 string 类型，且需要在页面显示时, 建议对特殊字符进行转义。

role string <optional>

用户角色，仅在 ‘live’ 模式下有意义，目前支持两种角色：

  • ‘anchor’ 主播
  • ‘audience’ 观众
    注意：互动直播 live 模式下的观众角色没有发布本地流的权限，只有收看远端流的权限。如果观众想要连麦跟主播互动， 请先通过 switchRole() 切换角色到主播 anchor 后再发布本地流。
privateMapKey string <optional>

Deprecated 进房钥匙，若需要权限控制请携带该参数（传空或传错会导致进房失败）。
privateMapKey 权限设置
Throws:

RtcError

Returns:
Type
Promise

(async) leave() → {Promise}

退出当前音视频通话房间，结束一次音视频通话会话。
退房前请确保已经通过 unpublish() 取消发布本地流，若未取消发布本地流，SDK 内部会自动取消发布本地流。 同时，退房会关闭所有远端流。

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

publish(stream) → {Promise}

发布本地音视频流。
该方法需要在 join() 进房后调用，一次音视频会话中只能发布一个本地流。若想发布另外一个本地流，可先通过 unpublish() 取消发布当前本地流后再发布新的本地流。
在发布本地流后，可通过 removeTrack()、addTrack()、 replaceTrack() 来更新本地流中的某个音频或视频流。
发布本地流后远端会收到 ‘stream-added’ 事件通知。

NOTE

  • 在 Client mode 为 'live' 及 role 为 'audience' 的场景下，即互动直播观众角色场景下，用户没有发布本地流权限。 如果观众想要连麦互动，需要先调用 switchRole('anchor') 切换到主播角色后再调用该接口发布本地流。
Example
localStream.initialize().then(() => {
  // 本地流初始化成功，发布本地流
  client.publish(localStream).then(() => {
    // 本地流发布成功
  });
});
Parameters:
Name Type Description
stream Stream

本地流，通过 createStream() 创建出来。
Throws:

RtcError

Returns:
Type
Promise

unpublish(stream) → {Promise}

取消发布本地流。
取消发布本地流后远端会收到 'stream-removed' 事件通知。
请在 leave() 退房前取消已经发布的本地流。

Example
// 取消发布本地流
client.unpublish(localStream).then(() => {
  // 取消发布本地流成功
});
Parameters:
Name Type Description
stream Stream

本地流
Throws:

RtcError

Returns:
Type
Promise

(async) subscribe(stream, optionsopt)

订阅远端流
默认情况下，当收到远端流增加事件 'stream-added' 后，SDK 会立刻接收并解码该远端流所包含的音视频数据。
开发者可通过该订阅接口指明需要订阅音频、视频或者音视频流。若不想接收该远端流所包含的任何音视频数据，请通过 unsubscribe() 取消订阅。

Example
// 监听远端流订阅成功事件
client.on('stream-subscribed', event => {
  const remoteStream = event.stream;
  // 远端流订阅成功，播放远端音视频流
  remoteStream.play('remote_stream');
});
// 监听远端流增加事件
client.on('stream-added', event => {
  const remoteStream = event.stream;
  // 订阅远端音频和视频流
  client.subscribe(remoteStream, { audio: true, video: true }).catch(e => {
    console.error('failed to subscribe remoteStream');
  });

  // 仅订阅音频数据
  // client.subscribe(remoteStream, { audio: true, video: false }).catch(e => {
  //  console.error('failed to subscribe remoteStream');
  // });
});
Parameters:
Name Type Attributes Description
stream Stream

远端流，通过监听 'stream-added' 事件获得。
options object <optional>

订阅选项

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

是否订阅音频
video boolean <optional>
 true

是否订阅视频
Fires:
  • Event.event:STREAM_SUBSCRIBED 订阅成功事件通知
Throws:

RtcError

(async) unsubscribe(stream)

取消订阅远端流
当收到远端流增加事件 'stream-added' 通知后，SDK 默认会立刻接收并解码该远端流所包含的音视频数据，如果你想拒绝接收 该远端流的任何音视频数据，请在 'stream-added' 事件处理回调中调用此接口。

Example
client.on('stream-added', event => {
  const remoteStream = event.stream;
  // 拒绝接收该远端流所包含的任何音视频数据
  client.unsubscribe(remoteStream).catch(e => {
    console.error('failed to unsubscribe remoteStream');
  });
});
Parameters:
Name Type Description
stream Stream

远端流，通过监听 ‘stream-added’ 事件获得。
Throws:

RtcError

(async) switchRole(role) → {Promise}

切换用户角色，仅在 ‘live’ 互动直播模式下生效。
该方法主要用于互动直播模式下观众用户连麦推流场景，在观众用户连麦推流之前，请先将用户角色转换为 ‘anchor’ 主播角色然后再发布本地流。

Example
// live互动直播模式下，观众连麦推流
client.switchRole('anchor').then(() => {
  // 连麦观众角色切换为主播，开始推流
  client.publish(localStream);
});
Parameters:
Name Type Description
role string

用户角色

  • ‘anchor’ 主播
  • ‘audience’ 观众
Throws:

RtcError

Returns:
Type
Promise

on(eventName, handler)

监听客户端对象事件
详细事件列表请参见：Event

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

事件名称
handler function

事件处理方法

off(eventName, handler)

取消事件绑定
用于移除通过 on() 绑定的事件。

Example
client.on('peer-join', function peerJoinHandler(event) {
  // peer-join event handler
  console.log('peer joined');

  client.off('peer-join', peerJoinHandler);
});

// 解除所有事件绑定
client.off('*');
Parameters:
Name Type Description
eventName string

事件名称，传入通配符 '*' 会解除所有事件绑定。
handler function

事件处理方法

getRemoteMutedState() → {Array.<RemoteMutedState>}

获取当前房间内远端用户音视频 mute 状态列表。

Returns:

远端用户音视频 mute 状态数组

Type
Array.<RemoteMutedState>

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

获取当前网络传输状况统计数据
该方法需要在 publish() 后调用。

Example
client.getTransportStats().then(stats => {
    console.log('RTT: ' + stats.rtt);
  }
});
Returns:

Promise成功返回 TransportStats

Type
Promise.<TransportStats>

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

获取当前已发布本地流的音频统计数据
该方法需要在 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成功返回 LocalAudioStatsMap

Type
Promise.<LocalAudioStatsMap>

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

获取当前已发布本地流的视频统计数据
该方法需要在 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成功返回 LocalVideoStatsMap

Type
Promise.<LocalVideoStatsMap>

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

获取当前所有远端流的音频统计数据

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成功返回 RemoteAudioStatsMap

Type
Promise.<RemoteAudioStatsMap>

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

获取当前所有远端流的视频统计数据

Example
client.getRemoteVideoStats().then(stats => {
  for (let userId in stats) {
    console.log('userId: ' + userId +
                ' bytesReceived: ' + stats[userId].bytesReceived +
                ' packetsReceived: ' + stats[userId].packetsReceived +
                ' packetsLost: ' + stats[userId].packetsLost +
                ' framesDecoded: ' + stats[userId].framesDecoded +
                ' frameWidth: ' + stats[userId].frameWidth +
                ' frameHeight: ' + stats[userId].frameHeight);

  }
});
Returns:

Promise成功返回 RemoteVideoStatsMap

Type
Promise.<RemoteVideoStatsMap>

startMixTranscode(config) → {Promise}

开始混流转码
请在成功发布本地流（publish）之后调用该接口

发起混流转码的方法：

  • 调用 startMixTranscode，并传入混流转码参数 config
    通过调用 startMixTranscode 接口发起混流转码时，SDK 会向腾讯云的转码服务器发送一条指令，目的是将房间里的多路音视频流混合为一路
    开发者可以通过 config.mixUsers 来调整每一路混入流的参数，也可以通过 config.videoWidth、config.videoHeight、config.videoBitrate 等属性控制混合后音视频流的编码值
Since:
  • v4.8.0
Example
// 开始混流转码
try {
 let config = {
   streamId: '',
   videoWidth: 1280,
   videoHeight: 500,
   videoBitrate: 1500,
   videoFramerate: 15,
   videoGOP: 2,
   audioSampleRate: 48000,
   audioBitrate: 64,
   audioChannels: 1,
   backgroundColor: 0x000000,
   backgroundImage: '',
   mixUsers: [
     {
       userId: 'user_1',
       pureAudio: false,
       width: 640,
       height: 480,
       locationX: 0,
       locationY: 0,
       zOrder: 1
     },
     {
       userId: 'user_2',
       pureAudio: true
     }
   ]
 }
 await client.startMixTranscode(config);
} catch (e) {
 console.error('startMixTranscode fail', e);
}
Parameters:
Name Type Description
config object

混流转码参数列表

Properties
Name Type Description
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

stopMixTranscode()

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

停止混流转码的方法：

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