new Client()
音视频通话客户端对象 Client 通过 createClient() 创建,代表一次音视频会话。
Client 客户端对象提供 TRTC Web SDK 的核心功能,包括:
- 进房 join()
- 退房 leave()
- 发布本地流 publish()
- 取消发布本地流 unpublish()
- 订阅远端流 subscribe()
- 取消订阅远端流 unsubscribe()
Methods
setProxyServer(url)
Example
client.setProxyServer('wss://proxy.example.com:443');
Parameters:
Name | Type | Description |
---|---|---|
url |
string |
websocket 代理服务器地址,格式如:‘wss://proxy.example.com:443’ |
setTurnServer(config)
Example
client.setTurnServer({ url: '192.168.0.110:3478', username: 'bob', credential: 'bobspassword', credentialType: 'password' });
Parameters:
Name | Type | Description | ||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
config |
object |
TURN 服务器配置项 Properties
|
(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
|
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
|
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 |
用户角色
|
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
|
Returns:
- Type
- Promise
stopMixTranscode()
停止混流转码
请在成功发布本地流(publish)及成功开始混流转码(startMixTranscode)之后调用该接口
停止混流转码的方法:
- 发起混流转码的用户调用 stopMixTranscode
- 发起混流转码的用户退出房间
- Since:
-
- v4.8.0
Example
// 停止混流转码
try {
await client.stopMixTranscode();
} catch (e) {
console.error('stopMixTranscode fail', e);
}