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

房间号，32位整型
role string <optional>

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

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

Deprecated 进房钥匙，若需要权限控制请携带该参数，因某些局限性目前已不建议使用该参数。
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 Description
audio boolean <optional>

是否订阅音频
video boolean <optional>

是否订阅视频
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>