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>