TRTC

TRTC

TRTC 是 TRTC Web SDK 的主入口,通过 TRTC 方法可以创建一个实时音视频通信的客户端对象 (Client) 和本地音视频流对象 (Stream)。 TRTC 方法还可以检测浏览器的兼容性,是否支持屏幕分享,以及设置日志级别及日志上传。

Namespaces

Logger

Members

(static) VERSION :string

TRTC Web SDK 版本号

Type:
  • string

Methods

(async) checkSystemRequirements() → {Promise.<object>}

检测 TRTC Web SDK 是否支持当前浏览器
若 TRTC Web SDK 不支持当前浏览器,根据用户设备类型建议用户使用 SDK 可以支持的浏览器。

Breaking Change:

  • v4.7.0 以下版本的 SDK: Promise 返回 boolean, 表示 SDK 是否支持当前浏览器。
  • v4.7.0 及其以上版本的 SDK: Promise 返回 object, 详见 Returns。
  • v4.9.0 及其以上版本的 SDK: checkResult.detail 移除了 isH264Supported,新增了 isH264EncodeSupported,isVp8EncodeSupported,isH264DecodeSupported 以及 isVp8DecodeSupported。
Example
// v4.7.0 以下版本的 SDK
TRTC.checkSystemRequirements().then((result) => {
  if(!result) {
     console('Your browser is not compatible with TRTC');
     // SDK 不支持当前浏览器,建议用户使用最新版本的 Chrome 浏览器。
  }
});
// v4.7.0 及其以上版本的 SDK
TRTC.checkSystemRequirements().then((checkResult) => {
  if(!checkResult.result) {
     console.log('checkResult', checkResult.result, 'checkDetail', checkResult.detail);
     // SDK 不支持当前浏览器,根据用户设备类型建议用户使用 SDK 支持的浏览器
  }
});
Returns:

Promise 返回检测结果

Property Type Description
checkResult.result boolean 检测结果
checkResult.detail.isBrowserSupported boolean 当前浏览器是否是 SDK 支持的浏览器
checkResult.detail.isWebRTCSupported boolean 当前浏览器是否支持 webRTC
checkResult.detail.isMediaDevicesSupported boolean 当前浏览器是否支持获取媒体设备及媒体流
checkResult.detail.isH264EncodeSupported boolean 当前浏览器上行是否支持 H264 编码
checkResult.detail.isH264DecodeSupported boolean 当前浏览器下行是否支持 H264 解码
checkResult.detail.isVp8EncodeSupported boolean 当前浏览器上行是否支持 VP8 编码
checkResult.detail.isVp8DecodeSupported boolean 当前浏览器下行是否支持 VP8 解码
Type
Promise.<object>

isScreenShareSupported() → {boolean}

检测浏览器是否支持屏幕分享
在创建屏幕分享流之前请调用该方法检查当前浏览器是否支持屏幕分享。

Example
if (TRTC.isScreenShareSupported()) {
  console.log('当前浏览器支持屏幕分享');
} else {
  console.log('当前浏览器不支持屏幕分享');
}
Returns:
Type
boolean

isSmallStreamSupported() → {boolean}

检测浏览器是否支持开启大小流模式
在开启大小流模式之前请调用该方法检查当前浏览器是否支持开启大小流。

Example
if (TRTC.isSmallStreamSupported()) {
  console.log('当前浏览器支持开启大小流模式');
} else {
  console.log('当前浏览器不支持开启大小流模式');
}
Returns:
Type
boolean

(async) getDevices() → {Promise.<Array.<MediaDeviceInfo>>}

返回媒体输入输出设备列表
Note

  • 该接口不支持在 http 协议下使用,请使用 https 协议部署您的网站。Privacy and security
  • 出于安全的考虑,在用户未授权摄像头或麦克风访问权限前,label 及 deviceId 字段可能都是空的。因此建议在用户授权访问后, 再调用该接口获取设备详情,比如在 initialize() 后再调用此接口获取设备详情。
Example
TRTC.getDevices()
  .then(deviceList => {
    deviceList.forEach(item => {
      console.log('device: ' + item.kind + ' ' + item.label + ' ' + item.deviceId);
    });
  })
  .catch(error => console.error('getDevices error observed ' + error));
Returns:

Promise 返回 MediaDeviceInfo 数组

Type
Promise.<Array.<MediaDeviceInfo>>

(async) getCameras() → {Promise.<Array.<MediaDeviceInfo>>}

返回摄像头设备列表
Note

  • 该接口不支持在 http 协议下使用,请使用 https 协议部署您的网站。Privacy and security
  • 出于安全的考虑,在用户未授权摄像头或麦克风访问权限前,label 及 deviceId 字段可能都是空的。因此建议在用户授权访问后, 再调用该接口获取设备详情,比如在 initialize() 后再调用此接口获取设备详情。
  • v4.14.2+ 版本支持调用 getCapabilities 浏览器原生接口。可从该接口获取摄像头的基本参数,例如支持的最大分辨率、最大帧率、在移动端设备区分前置或后置摄像头等。 该接口支持 Chrome 67+, Edge 79+, Opera 54+ 浏览器。
Example
TRTC.getCameras()
  .then(cameraList => {
    cameraList.forEach(item => {
      console.log('camera: ' + item.kind + ' ' + item.label + ' ' + item.deviceId);
      // v4.14.2+ 版本支持
      if (item.getCapabilities) {
         const capabilities = item.getCapabilities();
         if (capabilities.facingMode[0] === 'user') {
           // 前置摄像头
         } else if (capabilities.facingMode[0] === 'environment') {
           // 后置摄像头
         }
      }
    });
  })
  .catch(error => console.error('getCameras error observed ' + error));
Returns:

Promise 返回 MediaDeviceInfo 数组

Type
Promise.<Array.<MediaDeviceInfo>>

(async) getMicrophones() → {Promise.<Array.<MediaDeviceInfo>>}

返回麦克风设备列表
Note

  • 该接口不支持在 http 协议下使用,请使用 https 协议部署您的网站。Privacy and security
  • 出于安全的考虑,在用户未授权摄像头或麦克风访问权限前,label 及 deviceId 字段可能都是空的。因此建议在用户授权访问后, 再调用该接口获取设备详情,比如在 initialize() 后再调用此接口获取设备详情。
  • 为避免可能出现的无声问题,4.11.9+ 版本该接口不再返回 deviceId 为 'communications' 的麦克风。详情请参考:WebRTC 已知问题中的 Chrome case 8
  • v4.14.2+ 版本支持调用 getCapabilities 原生接口,可从该接口获取麦克风的基本参数,例如支持的最大声道数。 该接口支持 Chrome 67+, Edge 79+, Opera 54+ 浏览器。
Example
TRTC.getMicrophones()
  .then(microphoneList => {
    microphoneList.forEach(item => {
      console.log('microphone: ' + item.kind + ' ' + item.label + ' ' + item.deviceId);
      // v4.14.2+ 支持
      if (item.getCapabilities) {
         console.log(item.getCapabilities());
      }
    });
  })
  .catch(error => console.error('getMicrophones error observed ' + error));
Returns:

Promise 返回 MediaDeviceInfo 数组

Type
Promise.<Array.<MediaDeviceInfo>>

(async) getSpeakers() → {Promise.<Array.<MediaDeviceInfo>>}

返回扬声器设备列表

  • 出于安全的考虑,在用户未授权摄像头或麦克风访问权限前,label 及 deviceId 字段可能都是空的。因此建议在用户授权访问后 再调用该接口获取设备详情,比如在 initialize() 后再调用此接口获取设备详情。
  • 移动端不支持获取扬声器列表。
Example
TRTC.getSpeakers()
  .then(speakerList => {
    speakerList.forEach(item => {
      console.log('speaker: ' + item.kind + ' ' + item.label + ' ' + item.deviceId);
    });
  })
  .catch(error => console.error('getSpeakers error observed ' + error));
Returns:

Promise 返回 MediaDeviceInfo 数组

Type
Promise.<Array.<MediaDeviceInfo>>

createClient(clientConfig) → {Client}

创建一个实时音视频通话的 Client 对象,用于实现进房、推流、拉流等功能。
一个 Client 对象相当于一个用户,跟一个 userId 绑定;同一个页面中可以有多个不同的 Client,每个 Client 对象跟不同 userId 绑定。
比如,你可以使用一个 Client 对象负责推送本地音视频流和接收远端流, 同时使用另外一个 Client 对象负责推送屏幕分享流,但是不接收远端流。

Examples
// 实时通话模式下创建客户端对象
const client = TRTC.createClient({
  sdkAppId: 0,   // 填写您申请的 sdkAppId
  userId: '',    // 填写您业务对应的 userId
  userSig: '',   // 填写服务器或本地计算的 userSig
  mode: 'rtc'
});
// 互动直播模式下创建客户端对象
const client = TRTC.createClient({
  sdkAppId: 0,   // 填写您申请的 sdkAppId
  userId: '',    // 填写您业务对应的 userId
  userSig: '',   // 填写服务器或本地计算的 userSig
  mode: 'live'
});
Parameters:
Name Type Description
clientConfig object

客户端配置项

Properties
Name Type Attributes Default Description
sdkAppId number

sdkAppId
实时音视频控制台 单击 应用管理 > 创建应用 创建新应用之后,即可在 应用信息 中获取 sdkAppId 信息。

userId string

用户ID
建议限制长度为32字节,只允许包含大小写英文字母(a-zA-Z)、数字(0-9)及下划线和连词符。

userSig string

userSig 签名
计算 userSig 的方式请参考 UserSig 相关

mode string

应用场景,目前支持以下两种场景:

  • 'rtc' 实时通话模式
  • 'live' 互动直播模式
useStringRoomId boolean <optional>
false

是否使用 String 类型的 roomId,支持 v4.3.0+ 版本。

autoSubscribe boolean <optional>
true

是否自动订阅远端流,支持 v4.8.0+ 版本。

  • 默认开启,当收到 stream-added 事件时,SDK 会立刻接收并解码该远端流所包含的音视频数据。
  • 同时推摄像头+屏幕分享的场景下,屏幕分享 client 只需推流、不需要拉流,因此可在屏幕分享 client 中关闭自动订阅。
enableAutoPlayDialog boolean <optional>
true

是否开启 SDK 自动播放失败弹窗。支持 v4.11.9+ 版本。

  • 默认开启,当出现自动播放失败时,SDK 会弹窗引导用户点击页面,来恢复音视频播放。
  • 可设置为 false 关闭,建议接入侧参考 自动播放受限处理建议 来处理自动播放失败相关问题。
streamId string <optional>

绑定腾讯云直播 CDN 流 ID,设置之后,您就可以在腾讯云直播 CDN 上通过标准直播方案(FLV|HLS)播放该用户的音视频流。 限制长度为64字节,可以不填写,一种推荐的方案是使用 “sdkAppId_roomId_userId_main” 作为 streamId,这样比较好辨认且不会在您的多个应用中发生冲突。

userDefineRecordId string <optional>

设置云端录制完成后的回调消息中的 "userdefinerecordid" 字段内容,便于您更方便的识别录制回调。

  • 【推荐取值】限制长度为64字节,只允许包含大小写英文字母(a-zA-Z)、数字(0-9)及下划线和连词符。
  • 【参考文档】云端录制
  • 【特殊说明】云端转码录制出现上行音视频流前几秒没有被录制到的情况。如需解决该问题,可提交 TRTC 用户支持申请 后加入TRTC交流群,联系群内技术支持按需修改云端录制配置。
pureAudioPushMode number <optional>

纯音频推流模式,需要旁路直播和录制时需要带上此参数:

  • 1 表示本次是纯音频推流,不需要录制 MP3 文件
  • 2 表示本次是纯音频推流,录制文件为 MP3
Returns:

客户端对象

Type
Client

createStream(streamConfig) → {Stream}

创建一个本地流 Stream 对象,本地流 Stream 对象通过 publish() 方法发布本地音视频流。

注意:一个音视频流 Stream 中最多只能包含一个音频 track 和一个视频 track。

本地音视频流可以

  • 从摄像头和麦克风采集获得,适用于一般的音视频通话。
  • 从屏幕分享源采集获得,适用于进行屏幕分享。
  • 从开发者通过 audioSource/videoSource 指定的 MediaStreamTrack 获得, 使用这种方式业务层可先对音视频进行前处理,比如,对音频进行混音,或者对视频进行美颜处理,亦或者通过这种方式向远端用户推送一个正在播放的音视频文件。
Examples
// 从麦克风和摄像头采集本地音视频流
const localStream = TRTC.createStream({ userId, audio: true, video: true });
localStream.initialize().then(() => {
  console.log('initialize localStream success');
  // 本地流初始化成功,可通过Client.publish(localStream)发布本地音视频流
}).catch(error => {
  console.error('failed initialize localStream ' + error);
});
// 从屏幕分享源采集
// 仅采集屏幕分享视频流
const localStream = TRTC.createStream({ userId, audio: false, screen: true });
// 采集麦克风及屏幕分享视频流
// const localStream = TRTC.createStream({ userId, audio: true, screen: true });
// 采集系统音频及屏幕分享视频流
// const localStream = TRTC.createStream({ userId, screenAudio: true, screen: true });
localStream.initialize().then(() => {
  console.log('initialize localStream success');
  // 本地流初始化成功,可通过Client.publish(localStream)发布本地音视频流
}).catch(error => {
  console.error('failed initialize localStream ' + error);
});
// 从外部App指定的音视频源创建本地音视频流
navigator.mediaDevices.getUserMedia({ audio: true, video: true }).then(stream => {
  const audioTrack = stream.getAudioTracks()[0];
  const videoTrack = stream.getVideoTracks()[0];
  // 对audioTrack和videoTrack处理之后,
  const localStream = TRTC.createStream({ userId, audioSource: audioTrack, videoSource: videoTrack });
  localStream.initialize().then(() => {
    console.log('initialize localStream success');
    // 本地流初始化成功,可通过Client.publish(localStream)发布本地音视频流
  }).catch(error => {
    console.error('failed initialize localStream ' + error);
  });
}
);
Parameters:
Name Type Description
streamConfig object
Properties
Name Type Attributes Default Description
userId string

用户ID

audio boolean

是否从麦克风采集音频

microphoneId string <optional>

麦克风设备 deviceId,通过 getMicrophones() 获取

video boolean

是否从摄像头采集视频

cameraId string <optional>

摄像头设备 deviceId,通过 getCameras() 获取

facingMode string <optional>

指定使用前置或后置摄像头来采集视频。
在移动设备上,可通过该参数选择使用前置或后置摄像头:

  • 'user':前置摄像头
  • 'environment':后置摄像头

注意

  • 请勿同时使用 cameraId 和 facingMode 参数。
screen boolean <optional>

是否采集屏幕分享流

screenAudio boolean

是否采集系统音频
注意

  • 请勿同时设置 audio 和 screenAudio 为 true
  • 采集系统声音只支持 Chrome M74+ ,在 Windows 和 Chrome OS 上,可以捕获整个系统的音频,在 Linux 和 Mac 上,只能捕获选项卡的音频。其它 Chrome 版本、其它系统、其它浏览器均不支持。
  • 屏幕分享获取指引。
audioSource MediaStreamTrack

音频源

videoSource MediaStreamTrack

视频源

mirror boolean <optional>
true

是否开启本地视频镜像预览。建议在使用前置摄像头时开启,使用后置摄像头时关闭。
注意

  • 该参数只对本地预览有效,推流是没有镜像效果的。
  • 该参数不适用于屏幕分享。
  • 该参数从 v4.12.1 废弃,设置本地视频镜像预览请参考 localStream.play()
Throws:
Returns:

本地音视频流对象

Type
Stream