TRTCCloud

TRTCCloud

new TRTCCloud()

Example
// 创建 TRTCCloud 对象的示例代码：
import TRTCCloud from 'trtc-cloud-js-sdk';
const trtcCloud = new TRTCCloud();
// 获取 SDK 版本号
let version = trtcCloud.getSDKVersion();

Methods

(static) getTRTCShareInstance() → {TRTCCloud}

创建 TRTCCloud 对象单例

Example
import TRTCCloud from 'trtc-cloud-js-sdk';
const trtcCloud = TRTCCloud.getTRTCShareInstance(); // 创建 TRTCCloud 对象单例
Returns:
Type
TRTCCloud

(static) destroyTRTCShareInstance()

释放 TRTCCloud 对象并清理资源

Example
import TRTCCloud from 'trtc-cloud-js-sdk';
TRTCCloud.destroyTRTCShareInstance(); // 释放 TRTCCloud 对象并清理资源

getSDKVersion() → {String}

获取 SDK 版本信息

Returns:
Type
String

on(event, callback)

绑定事件

Example
trtcCloud.on('onEnterRoom', callback);
Parameters:
Name Type Description
event String

事件名称
callback function

事件回调

off(event, callback)

取消事件绑定

Example
trtcCloud.off('onEnterRoom', callback);
trtcCloud.off('*'); // 取消所有绑定的事件
Parameters:
Name Type Description
event String

事件名称，传入通配符 '*' 会解除所有事件绑定。
callback function

事件回调

enterRoom(params, scene) → {Promise}

进房
调用接口后，您会收到来自 TRTCCallback 中的 onEnterRoom 回调

  • 如果加入成功，result 会是一个正数（result > 0），表示加入房间所消耗的时间，单位是毫秒（ms）
  • 如果加入失败，result 会是一个负数（result < 0），表示进房失败的错误码

参数 scene 的枚举值如下：

  • TRTCAppSceneVideoCall：
    视频通话场景，支持720P、1080P高清画质，单个房间最多支持300人同时在线，最高支持50人同时发言。
    适合：[1对1视频通话]、[300人视频会议]、[在线问诊]、[视频聊天]、[远程面试]等。
  • TRTCAppSceneAudioCall：
    语音通话场景，支持 48kHz，支持双声道。单个房间最多支持300人同时在线，最高支持50人同时发言。
    适合：[1对1语音通话]、[300人语音会议]、[语音聊天]、[语音会议]、[在线狼人杀]等。
  • TRTCAppSceneLIVE：
    视频互动直播，支持平滑上下麦，切换过程无需等待，主播延时小于300ms；支持十万级别观众同时播放，播放延时低至1000ms。
    适合：[视频低延时直播]、[十万人互动课堂]、[视频直播 PK]、[视频相亲房]、[互动课堂]、[远程培训]、[超大型会议]等。
  • TRTCAppSceneVoiceChatRoom：
    语音互动直播，支持平滑上下麦，切换过程无需等待，主播延时小于300ms；支持十万级别观众同时播放，播放延时低至1000ms。
    适合：[语音低延时直播]、[语音直播连麦]、[语聊房]、[K 歌房]、[FM 电台]等。

Note:

  1. 当 scene 选择为 TRTCAppSceneLIVE 或 TRTCAppSceneVoiceChatRoom 时，您必须通过 TRTCParams 中的 role 字段指定当前用户的角色。
  2. 不管进房是否成功，enterRoom() 都必须与 exitRoom() 配对使用。 在调用 exitRoom() 前再次调用 enterRoom() 函数会导致不可预期的错误问题。
Example
import TRTCCloud from 'trtc-cloud-js-sdk';
const trtcCloud = TRTCCloud.getTRTCShareInstance(); // 创建实例，只需创建一次
const params = {
  sdkAppId: 0,
  userId: 'denny',
  roomId: 12345,
  userSig: 'xxx'
};
await trtcCloud.enterRoom(params, TRTCAppScene.TRTCAppSceneVideoCall);
Parameters:
Name Type Description
params TRTCParams

进房参数

Properties
Name Type Attributes Description
sdkAppId Number

应用标识（必填）
userId String

用户标识（必填）
userSig String

用户签名（必填）
roomId Number

房间号码, roomId 和 strRoomId 必须填一个, 若您选用 strRoomId，则 roomId 需要填写为0。
strRoomId String

字符串房间号码 [选填]，在同一个房间内的用户可以看到彼此并进行视频通话, roomId 和 strRoomId 必须填一个。若两者都填，则优先选择 roomId
role TRTCRoleType

直播场景下的角色，默认值：主播

  • TRTCRoleAnchor: 主播，可以上行视频和音频，一个房间里最多支持50个主播同时上行音视频。
  • TRTCRoleAudience: 观众，只能观看，不能上行视频和音频，一个房间里的观众人数没有上限。
privateMapKey String <optional>

房间签名（非必填）
streamId String <optional>

自定义 CDN 播放地址（非必填）
userDefineRecordId String <optional>

设置云端录制完成后的回调消息中的 "userdefinerecordid" 字段内容，便于您更方便的识别录制回调（非必填）
scene TRTCAppScene

应用场景，目前支持视频通话（TRTCAppSceneVideoCall）、语音通话（TRTCAppSceneAudioCall）、 在线直播（TRTCAppSceneLIVE）、语音聊天室（VTRTCAppSceneVoiceChatRoom）四种场景，详见 [TrtcDefines] 中 TRTCAppScene 参数定义
Returns:
Type
Promise

exitRoom() → {Promise}

退房
执行退出房间的相关逻辑释放资源后，SDK 会通过 onExitRoom 回调通知到您

Note:

  1. 如果您要再次调用 enterRoom() 或者切换到其它的音视频 SDK，请等待 onExitRoom() 回调到来后再执行相关操作，否则可能会遇到如摄像头、麦克风设备被强占等各种异常问题。
Example
await trtcCloud.exitRoom();
Returns:
Type
Promise

switchRole(role) → {Promise}

切换角色，仅适用于直播场景（TRTCAppSceneLIVE 和 TRTCAppSceneVoiceChatRoom）
在直播场景下，一个用户可能需要在“观众”和“主播”之间来回切换。 您可以在进房前通过 TRTCParams 中的 role 指定角色，也可以通过 switchRole() 在进房后切换角色。

Example
import TRTCCloud, { TRTCRoleType } from 'trtc-cloud-js-sdk';
const trtcCloud = TRTCCloud.getTRTCShareInstance();
await trtcCloud.switchRole(TRTCRoleType.TRTCRoleAudience);
Parameters:
Name Type Description
role TRTCRoleType

目标角色，默认为主播

  • TRTCRoleAnchor: 主播，可以上行视频和音频，一个房间里最多支持50个主播同时上行音视频
  • TRTCRoleAudience: 观众，只能观看，不能上行视频和音频，一个房间里的观众人数没有上限
Returns:
Type
Promise

enableAudioVolumeEvaluation(interval)

开启或关闭音量大小回调
开启此功能后，SDK 会在 onUserVoiceVolume 中反馈对每一路声音音量大小值的评估。

Note:

  • 如需打开此功能，请在 startLocalAudio() 之前调用才可以生效。
Example
trtcCloud.enableAudioVolumeEvaluation(300);
Parameters:
Name Type Description
interval Number

设置 onUserVoiceVolume 回调的触发间隔，单位为ms，最小间隔为100ms，如果小于等于0则会关闭回调，建议设置为300ms

startLocalAudio(quality) → {Promise}

开启本地音频的采集和上行, 并设置音频质量
该函数会启动麦克风采集，并将音频数据传输给房间里的其他用户。 SDK 不会默认开启本地音频采集和上行，您需要调用该函数开启，否则房间里的其他用户将无法听到您的声音
主播端的音质越高，观众端的听感越好，但传输所依赖的带宽也就越高，在带宽有限的场景下也更容易出现卡顿

Note:

  1. 音质参数 WebRTCAudioQuality 不同于 Electron startLocalAudio
Example
import { WebRTCAudioQuality } from 'trtc-cloud-js-sdk';
await trtcCloud.startLocalAudio(WebRTCAudioQuality.WebRTCAudioQualityHigh);
Parameters:
Name Type Description
quality WebRTCAudioQuality

声音音质

  • WebRTCAudioQualityStandard，采样率：48k；单声道；码率：40kbps，默认使用 WebRTCAudioQualityStandard
  • WebRTCAudioQualityHigh，采样率：48k；单声道；码率：128kbps
  • WebRTCAudioQualityStandardStereo，采样率：48k；双声道；码率：64kbps
  • WebRTCAudioQualityHighStereo，采样率：48k；双声道；码率：192kbps
Returns:
Type
Promise

stopLocalAudio() → {Promise}

关闭本地音频的采集和上行
当关闭本地音频的采集和上行，房间里的其它成员会收到 onUserAudioAvailable 回调通知

Example
await trtcCloud.stopLocalAudio();
Returns:
Type
Promise

muteLocalAudio(mute)

静音本地的音频
当静音本地音频后，房间里的其它成员会收到 onUserAudioAvailable 回调通知。 与 stopLocalAudio 不同之处在于，muteLocalAudio 并不会停止发送音视频数据，而是会继续发送码率极低的静音包。 在对录制质量要求很高的场景中，选择 muteLocalAudio 是更好的选择，能录制出兼容性更好的 MP4 文件。 这是由于 MP4 等视频文件格式，对于音频的连续性是要求很高的，简单粗暴地 stopLocalAudio 会导致录制出的 MP4 不易播放。

Example
trtcCloud.muteLocalAudio(true);
Parameters:
Name Type Description
mute Boolean

true：屏蔽；false：开启，默认值：false

muteRemoteAudio(userId, mute)

静音掉某个用户的声音，同时不再拉取该远端用户的音频数据流

Example
trtcCloud.muteRemoteAudio('denny', true);
Parameters:
Name Type Description
userId String

用户 ID
mute Boolean

true：静音；false：非静音

muteAllRemoteAudio(mute)

静音掉远端所有用户的声音，同时不再拉取远端用户的音频数据流

Example
trtcCloud.muteAllRemoteAudio(true);
Parameters:
Name Type Description
mute Boolean

true：静音；false：非静音

setRemoteAudioVolume(userId, volume)

设置某个远程用户的播放音量

Example
trtcCloud.setRemoteAudioVolume('denny', 80);
Parameters:
Name Type Description
userId String

远程用户 ID
volume Number

音量大小，100为原始音量，范围是：[0 ~ 100]，默认值为100

getAudioCaptureVolume() → {Number}

获取 SDK 采集音量

Example
trtcCloud.getAudioCaptureVolume('denny', 80);
Returns:

SDK 采集音量

Type
Number

startLocalPreview(view) → {Promise}

开启本地视频的预览画面
这个接口会启动默认的摄像头，可以通过 setCurrentCameraDevice 接口选用其它摄像头

Example
// 预览本地画面
const view = document.getElementById('local-view');
await trtcCloud.startLocalPreview(view);
Parameters:
Name Type Description
view HTMLElement

承载预览画面的 DOM
Returns:
Type
Promise

stopLocalPreview() → {Promise}

停止本地摄像头采集和预览
首先停止播放，然后关闭本地流（关闭摄像头和麦克风访问权限）

Example
await trtcCloud.stopLocalPreview();
Returns:
Type
Promise

muteLocalVideo(mute)

暂停/恢复发布本地的视频流
当屏蔽本地视频后，房间里的其它成员将会收到 onUserVideoAvailable 回调通知

Example
trtcCloud.muteLocalVideo(true);
Parameters:
Name Type Description
mute Boolean

true：屏蔽；false：开启，默认值：false

startRemoteView(userId, view, streamType) → {Promise}

显示远端视频或辅流
在收到 SDK 的 onUserVideoAvailable 通知时，可以获知该远程用户开启了视频， 此后调用 startRemoteView 接口加载该用户的远程画面时，可以用 loading 动画优化加载过程中的等待体验。

Example
import { TRTCVideoStreamType } from 'trtc-cloud-js-sdk';
const view = document.getElementById('remote-view');
await trtcCloud.startRemoteView('denny', view, TRTCVideoStreamType.TRTCVideoStreamTypeBig);
Parameters:
Name Type Description
userId String

对方的用户标识
view HTMLElement

承载预览画面的 DOM
streamType TRTCVideoStreamType

视频流类型

  • 高清大画面：TRTCVideoStreamType.TRTCVideoStreamTypeBig
  • 低清小画面：TRTCVideoStreamType.TRTCVideoStreamTypeSmall
  • 辅流（屏幕分享）：TRTCVideoStreamType.TRTCVideoStreamTypeSub
Returns:
Type
Promise

stopRemoteView(userId, streamType) → {Promise}

停止显示远端视频画面，同时不再拉取该远端用户的视频数据流
指定要停止观看的 userId 的视频流类型

Example
import { TRTCVideoStreamType } from 'trtc-cloud-js-sdk';
await trtcCloud.stopRemoteView('denny', TRTCVideoStreamType.TRTCVideoStreamTypeBig);
Parameters:
Name Type Description
userId String

userId 指定的远端用户 ID
streamType TRTCVideoStreamType

视频流类型

  • 高清大画面：TRTCVideoStreamType.TRTCVideoStreamTypeBig
  • 低清小画面：TRTCVideoStreamType.TRTCVideoStreamTypeSmall
  • 辅流（屏幕分享）：TRTCVideoStreamType.TRTCVideoStreamTypeSub
Returns:
Type
Promise

muteRemoteVideoStream(userId, mute)

暂停接收指定的远端视频流
该接口仅停止接收远程用户的视频流，但并不释放显示资源，所以视频画面会冻屏在 mute 前的最后一帧。

Parameters:
Name Type Description
userId String

对方的用户标识
mute Boolean

是否停止接收

setRemoteRenderParams(userId, streamType, params) → {Promise}

设置远端流渲染参数

Parameters:
Name Type Description
userId String

流 userId
streamType TRTCVideoStreamType

流类型

  • 高清大画面：TRTCVideoStreamType.TRTCVideoStreamTypeBig
  • 低清小画面：TRTCVideoStreamType.TRTCVideoStreamTypeSmall
  • 辅流（屏幕分享）：TRTCVideoStreamType.TRTCVideoStreamTypeSub
params TRTCRenderParams

远端流渲染参数

Properties
Name Type Description
fillMode TRTCVideoFillMode

填充模式
mirrorType TRTCVideoMirrorType

画面渲染镜像
Returns:
Type
Promise

getCameraDevicesList() → {Promise(Array<TRTCDeviceInfo>)}

获取摄像头设备列表

Example
var cameralist = await trtcCloud.getCameraDevicesList();
for (i = 0; i < cameralist.length; i++) {
   var camera = cameralist[i];
   console.info("camera deviceName: " + camera.deviceName + " deviceId:" + camera.deviceId);
}
Returns:

摄像头管理器列表

Type
Promise(Array<TRTCDeviceInfo>)

setCurrentCameraDevice(deviceId) → {Promise}

设置要使用的摄像头

Parameters:
Name Type Description
deviceId String

从 getCameraDevicesList 中得到的设备 ID
Returns:
Type
Promise

getCurrentCameraDevice() → {TRTCDeviceInfo}

获取当前使用的摄像头

Returns:

设备信息，能获取设备 ID 和设备名称

Type
TRTCDeviceInfo

getMicDevicesList() → {Promise(Array<TRTCDeviceInfo>)}

获取麦克风设备列表

Example
var micList = await trtcCloud.getMicDevicesList();
  for (i = 0; i < micList.length; i++) {
    var mic = micList[i];
    console.info("mic deviceName: " + mic.deviceName + " deviceId:" + mic.deviceId);
  }
Returns:

麦克风管理器列表

Type
Promise(Array<TRTCDeviceInfo>)

getCurrentMicDevice() → {TRTCDeviceInfo}

获取当前选择的麦克风

Returns:

设备信息，能获取设备 ID 和设备名称

Type
TRTCDeviceInfo

setCurrentMicDevice(micId) → {Promise}

设置要使用的麦克风
选择指定的麦克风作为录音设备，不调用该接口时，默认选择索引为0的麦克风

Parameters:
Name Type Description
micId String

从 getMicDevicesList 中得到的设备 ID
Returns:
Type
Promise

getSpeakerDevicesList() → {Promise(Array<TRTCDeviceInfo>)}

获取扬声器设备列表

  • 出于安全的考虑，在用户未授权摄像头或麦克风访问权限前，deviceId 字段可能都是空的。因此建议在用户授权访问后 再调用该接口获取设备详情
  • 移动端不支持获取扬声器列表
Example
var speakerList = await trtcCloud.getSpeakerDevicesList();
  for (i = 0; i < speakerList.length; i++) {
    var speaker = speakerList[i];
    console.info("mic deviceName: " + speaker.deviceName + " deviceId:" + speaker.deviceId);
  }
Returns:

扬声器管理器列表

Type
Promise(Array<TRTCDeviceInfo>)

getCurrentSpeakerDevice() → {TRTCDeviceInfo}

获取当前的扬声器设备

Returns:

设备信息，能获取设备 ID 和设备名称

Type
TRTCDeviceInfo

setCurrentSpeakerDevice(speakerId) → {Promise}

设置要使用的扬声器

  • 移动端不支持设置扬声器。
Parameters:
Name Type Description
speakerId String

从 getSpeakerDevicesList 中得到的设备 ID
Returns:
Type
Promise

startScreenShare(options) → {Promise}

开始屏幕分享
Note:

  • 屏幕分享 ID 的命名规则：'share_jack'，也即当前用户的 ID 加上 'share_' 前缀后得到屏幕分享的 ID
Example
const options = {
   shareUserId: 'share_jack',
   shareUserSig: 'xxxx',
 };
 await trtcCloud.startScreenShare(options);
Parameters:
Name Type Description
options Object

屏幕分享参数

Properties
Name Type Description
shareUserId String

屏幕分享传入的 ID
shareUserSig String

屏幕分享的签名 userSig Note:

  • shareUserId 屏幕分享 ID 的命名规则：'share_jack'，也即当前用户的 ID 加上 'share_' 前缀后得到屏幕分享的 ID
Returns:
Type
Promise

setSubStreamEncoderParam(params)

设置屏幕分享的视频编码参数
Note:

  • setSubStreamEncoderParam 需在调用 startScreenShare() 进行屏幕分享之前调用
  • 默认分辨率：1920*1080，视频采集帧率：15fps，视频码率：1500kps
Example
import { TRTCVideoResolution } from 'trtc-cloud-js-sdk';
 const params = {
   videoResolution: TRTCVideoResolution.TRTCVideoResolution_640_480,
   videoFps: 15,
   videoBitrate: 1500,
 };
 trtcCloud.setSubStreamEncoderParam(params);
Parameters:
Name Type Description
params TRTCVideoEncParam

屏幕分享视频编码参数

Properties
Name Type Description
videoResolution TRTCVideoResolution

视频分辨率
videoFps Number

视频采集帧率
videoBitrate Number

视频码率

stopScreenShare() → {Promise}

停止屏幕分享

Example
await trtcCloud.stopScreenShare();
Returns:
Type
Promise

startPublishing(streamId, type) → {Promise}

开始向腾讯云的直播 CDN 推流
该接口会指定当前用户的音视频流在腾讯云 CDN 所对应的 StreamId，进而可以指定当前用户的 CDN 播放地址。

例如：如果我们采用如下代码设置当前用户的主画面 StreamId 为 user_stream_001，那么该用户主画面对应的 CDN 播放地址为： http://yourdomain/live/user_stream_001.flv，其中 yourdomain 为您自己备案的播放域名， 您可以在直播控制台 配置您的播放域名，腾讯云不提供默认的播放域名。

您也可以在设置 enterRoom 的参数 TRTCParams 时指定 streamId, 而且我们更推荐您采用这种方案。

注意：您需要先在实时音视频 控制台 中的功能配置页开启“启动自动旁路直播”才能生效。

Example
import TRTCCloud, { TRTCAppScene, WebRTCAudioQuality, TRTCVideoStreamType } from 'trtc-cloud-js-sdk';
const trtcCloud = TRTCCloud.getTRTCShareInstance();
const params = {
  sdkAppId: 0,
  userId: 'denny',
  roomId: 12345,
  userSig: 'xxx'
};
trtcCloud.enterRoom(params, TRTCAppScene.TRTCAppSceneVideoCall);
const view = document.createElement('local-view');
trtcCloud.startLocalPreview(view);
trtcCloud.startLocalAudio(WebRTCAudioQuality.WebRTCAudioQualityStandard);
trtcCloud.startPublishing("user_stream_001", TRTCVideoStreamType.TRTCVideoStreamTypeBig);
Parameters:
Name Type Description
streamId String

自定义流 ID。
type TRTCVideoStreamType

仅支持 TRTCVideoStreamTypeBig 和 TRTCVideoStreamTypeSub。
Returns:
Type
Promise

stopPublishing() → {Promise}

停止向腾讯云的直播 CDN 推流

Returns:
Type
Promise

startPublishCDNStream(param) → {Promise}

开始向非腾讯云的直播 CDN 转推
该接口跟 startPublishing() 类似，但 startPublishCDNStream() 支持向非腾讯云的直播 CDN 转推。 使用 startPublishing() 绑定腾讯云直播 CDN 不收取额外的费用。 使用 startPublishCDNStream() 绑定非腾讯云直播 CDN 需要收取转推费用，且需要通过工单联系我们开通。

Parameters:
Name Type Description
param TRTCPublishCDNParam

转推参数

Properties
Name Type Description
appId Number

腾讯云 AppID
bizId Number

腾讯云直播 bizId
url String

旁路转推的 URL
Returns:
Type
Promise

stopPublishCDNStream() → {Promise}

停止向非腾讯云的直播 CDN 推流

Returns:
Type
Promise