Client

new Client()

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

• 进房 join()
• 退房 leave()
• 发布本地流 publish()
• 取消发布本地流 unpublish()
• 订阅远端流 subscribe()
• 取消订阅远端流 unsubscribe()
• 销毁 Client 实例 destroy()

Client 生命周期如图所示：

Methods

(async) join(options) → {Promise}

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:

Throws:

Returns:

Type

Promise

(async) leave() → {Promise}

Example

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

Returns:

Type

Promise

destroy()

Since:

• v4.13.0

Examples

let client = TRTC.createClient({ sdkAppId, userId, userSig, mode: 'rtc' });
await client.join({ roomId: 123456 });
// 通话结束时
await client.leave();
// 若后续无需再使用该 client，则销毁 client，并释放引用。
client.destroy();
client = null;

let client = TRTC.createClient({ sdkAppId, userId, userSig, mode: 'rtc' });
// 假设业务逻辑需要在5s内完成进房，否则认为进房超时。
const id = setTimeout(() => {
 // 销毁 client 实例，中止 client.join 流程。
 client.destroy();
 client = null;
}, 5000)
try {
 await client.join({ roomId: 123456 });
} catch(error) {}
clearTimeout(id);

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

Examples

const localStream = TRTC.createStream({
  userId: 'userA',
  audio: true, // 采集麦克风
  video: true // 采集摄像头
})
await localStream.initialize();
await client.publish(localStream);

const shareStream = TRTC.createStream({
  userId: 'userA',
  screen: true, // 采集屏幕分享
})
await shareStream.initialize();
// 将 isAuxiliary 参数设为 true，将以辅流的形式推送屏幕分享，支持 v4.15.0+ 版本。
await client.publish(shareStream, { isAuxiliary: true });

Parameters:

Throws:

Returns:

Type

Promise

(async) unpublish(stream) → {Promise}

Example

// 取消发布本地流
client.unpublish(localStream).then(() => {
  // 取消发布本地流成功
});

Parameters:

Throws:

Returns:

Type

Promise

(async) subscribe(stream, optionsopt)

Examples

// 监听远端流订阅成功事件
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');
    if (e.getCode() === 16461) {
      // API_CALL_ABORTED 订阅过程中，远端取消了推流导致订阅中断，无需特殊处理。
    }
    // 其他异常，例如因网络问题导致连接超时。
  });
  // 仅订阅音频数据
  // client.subscribe(remoteStream, { audio: true, video: false }).catch(e => {
  //  console.error('failed to subscribe remoteStream');
  // });
});

// 对于同一远端流，必须得在 subscribe/unsubscribe 调用完成后，才能开始下一次调用。
// 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:

Fires:

• ClientEvent.event:STREAM_SUBSCRIBED 订阅成功事件通知

Throws:

(async) unsubscribe(stream)

Examples

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

// 对于同一远端流，必须得在 subscribe/unsubscribe 调用完成后，才能开始下一次调用。
// 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:

Throws:

(async) switchRole(role) → {Promise}

Example

// 进房成功后
// live 互动直播模式下，观众切换为主播
await client.switchRole('anchor');
// 观众角色切换为主播，开始推流
await client.publish(localStream);
// live 互动直播模式下，主播切换为观众
await client.switchRole('audience');

Parameters:

Throws:

Returns:

Type

Promise

on(eventName, handler, context)

Example

client.on('stream-added', event => {
  // stream-added event handler
});

Parameters:

off(eventName, handler, context)

Example

client.on('peer-join', function peerJoinHandler(event) {
  // peer-join event handler
  console.log('peer joined');
  client.off('peer-join', peerJoinHandler);
});
// 解除所有事件绑定
client.off('*');

Parameters:

getRemoteMutedState() → {Array.<RemoteMutedState>}

Since:

• 4.11.2 新增属性 hasSmall，标识远端流是否有小流视频。

Returns:

Type

Array.<RemoteMutedState>

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

Example

const stats = await client.getTransportStats();
console.log('uplink rtt: ' + stats.rtt);
// v4.10.1 版本开始支持获取下行 rtt
for (let userId in stats.downlinksRTT) {
   console.log('downlink rtt:' + stats.downlinksRTT[userId]);
}

Returns:

Type

Promise.<TransportStats>

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

Example

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

Returns:

Type

Promise.<LocalAudioStatsMap>

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

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:

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 +
                ' packetsLost: ' + stats[userId].end2EndDelay);
  }
});

Returns:

Type

Promise.<RemoteAudioStatsMap>

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

Example

// 获取主流中摄像头视频的统计数据
const stats = await client.getRemoteVideoStats('main');
// 获取辅流中的屏幕分享的统计数据
const stats = await client.getRemoteVideoStats('auxiliary');

Parameters:

Returns:

Type

Promise.<RemoteVideoStatsMap>

(async) startPublishCDNStream(options) → {Promise}

Since:

• 4.10.0

Example

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

Parameters:

Returns:

Type

Promise

(async) stopPublishCDNStream() → {Promise}

Since:

• v4.10.0

Example

client.stopPublishCDNStream();

Returns:

Type

Promise

(async) startMixTranscode(config) → {Promise}

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
         streamType: 'main',  // streamType 取值为 'main' 或者 'auxiliary'
         zOrder: 1
       },
       {
         width: 320,
         height: 240,
         locationX: 960,
         locationY: 0,
         pureAudio: false,
         userId: '123456', // 本地摄像头占位，填写用于推摄像头流的 client userId
         streamType: 'main',  // streamType 取值为 'main' 或者 'auxiliary'
         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:

Returns:

Type

Promise

(async) stopMixTranscode()

Since:

• v4.8.0

Example

// 停止混流转码
try {
 await client.stopMixTranscode();
} catch (e) {
 console.error('stopMixTranscode fail', e);
}

enableAudioVolumeEvaluation(intervalopt, enableInBackgroundopt)

Since:

• v4.9.0

Example

client.on('audio-volume', event => {
    event.result.forEach(({ userId, audioVolume, stream }) => {
        console.log(`userId: ${userId}, audioVolume: ${audioVolume}`);
    })
})
// 开启音量回调，并设置每 1000ms 触发一次事件
client.enableAudioVolumeEvaluation(1000);
// 如需关闭音量回调，传入 interval 值小于等于0即可
client.enableAudioVolumeEvaluation(-1);

Parameters:

(async) enableSmallStream() → {Promise}

Since:

• 4.11.0

Example

// 开启小流
await client.enableSmallStream();
// 本地流初始化成功
await localStream.initialize();
// 发布本地流
await client.publish(localStream);

Throws:

Returns:

Type

Promise

(async) disableSmallStream() → {Promise}

Since:

• 4.11.0

Example

await client.unpublish(localStream);
await client.disableSmallStream();

Throws:

Returns:

Type

Promise

setSmallStreamProfile(options)

Since:

• 4.11.0

Example

// 如果您大流的宽高比是 4 : 3，您需要把小流的参数设置成 4 : 3
client.setSmallStreamProfile({
  width: 160,
  height: 120,
  bitrate: 100,
  frameRate: 15
});
// 如果您大流的宽高比是 16 : 9，您需要把小流的参数设置成 16 : 9
client.setSmallStreamProfile({
   width: 160,
   height: 90,
   bitrate: 100,
   frameRate: 15
});

Parameters:

(async) setRemoteVideoStreamType(remoteStream, status) → {Promise}

Since:

• 4.11.0

Example

// 切换成小流
await client.setRemoteVideoStreamType(remoteStream, 'small');
// 对同一个远端流，必须得在 setRemoteVideoStreamType 调用完成之后，才能开始下一次调用
// bad
client.setRemoteVideoStreamType(remoteStream, 'small');
client.setRemoteVideoStreamType(remoteStream, 'big');
// good
await client.setRemoteVideoStreamType(remoteStream, 'small');
await client.setRemoteVideoStreamType(remoteStream, 'big');

Parameters:

Throws:

Returns:

Type

Promise

sendSEIMessage(buffer, optionsopt)

Since:

• v4.14.1

Example

// 1. 开启 SEI
const client = TRTC.createClient({
   sdkAppId: 1400000000,
   userId: 'test',
   userSig: 'fake',
   enableSEI: true // 开启 SEI 收发功能
})
// 2. 推流端发送 SEI
try {
 const unit8Array = new Uint8Array([1, 2, 3]);
 client.sendSEIMessage(unit8Array.buffer);
 // 消息已通过限制，等待后续视频帧发送。
} catch(error) {
 // 发送失败，可能原因：当前浏览器不支持、参数校验未通过、未推流、没推视频流、调用次数超出限制、使用非 H264 编码器等。
 console.warn(error);
}
// 3. 拉流端接收 SEI
client.on('sei-message', event => {
 console.warn(`收到 ${event.userId} 的 sei ${event.data}`);
})

Parameters:

setProxyServer(options)

Examples

// 传 string 类型
client.setProxyServer('wss://proxy.example.com');

// v4.8.0+ 版本可传 object 类型，支持设置 loggerProxy
client.setProxyServer({
  // 设置 Websocket 代理，用于中转 SDK 与 TRTC 后台的数据包。
  websocketProxy: 'wss://proxy.example.com/ws/',
  // 设置日志上报代理，日志是排查问题的关键数据，请务必设置该代理。 v4.8.0+ 版本 SDK 支持设置该字段。
  loggerProxy: 'https://proxy.example.com/logger/'
});

Parameters:

setTurnServer(options)

Example

// v4.8.5 之前版本，仅支持设置一个 turn server
client.setTurnServer({ url: '192.168.0.110:3478', username: 'bob', credential: 'bobspassword', credentialType: 'password' });
// 自 v4.8.5 支持设置多个 turn server
client.setTurnServer([{ url: '192.168.0.110:3478', username: 'bob', credential: 'bobspassword', credentialType: 'password' }]);

Parameters: