有奖捉虫:办公协同&微信生态&物联网文档专题 HOT

TUIRoomEngine 简介

TUIRoomEngine SDK 提供了房间管理、多人实时音视频互动、屏幕分享、成员管理、即时聊天等功能。
安装方式:
// 使用 npm
npm i @tencentcloud/tuiroom-engine-js --save

// 使用 pnpm
pnpm i @tencentcloud/tuiroom-engine-js --save

// 使用 yarn
yarn add @tencentcloud/tuiroom-engine-js

TUIRoomEngine API

TUIRoomEngine 静态方法

API
描述
once
监听 TUIRoomEngine ready 事件。
注意:TUIRoomEngine.login 以外的所有方法必须在监听到 TUIRoomEngine ready 事件且 TUIRoomEngine.login 方法执行成功后执行。
login
登录 TUIRoomEngine
设置当前用户基本信息(用户名、用户头像)
获取当前用户基本信息(用户名、用户头像)
logout
登出 TUIRoomEngine

roomEngine 房间管理 API

API
描述
创建房间
enterRoom
进入房间
销毁房间
exitRoom
离开房间
获取房间信息
更新房间的名字(仅群主或者管理员可以调用)
更新房间的发言模式(仅群主或者管理员可以调用),该接口自 v2.0.0 版本废弃
更新房间上麦模式(仅群主或者管理员可以调用)
获取当前房间用户列表
获取用户的详细信息

roomEngine 音视频 API

API
描述
设置本地流的渲染位置
本地摄像头视频流采集
关闭本地摄像头
打开本地麦克风
关闭本地麦克风
设置本地视频的分辨率
设置本地视频流的分辨率模式
设置本地视频的编码参数
设置本地音频的参数
开始屏幕共享
停止屏幕共享
开始向远端推本地视频流
停止向远端推本地视频流
停止向远端推本地音频流
开始向远端推本地音频流
设置远端流渲染的区域
开始播放远端用户视频流
停止播放远端用户视频流
停止远端用户的音频流

roomEngine 成员管理 API

API
描述
请求远端用户打开媒体设备
参会者向主持人申请打开设备
关闭远端用户媒体设备
取消已经发出的请求
回复远端用户的请求
改变用户的角色
将用户踢出房间
禁用/打开所有用户的媒体设备
禁止/允许所有用户发送消息
禁止/允许某个用户发送消息
设置用户的自定义信息

roomEngine 麦位管理 API

API
描述
设置房间麦位最大值
获取麦位信息
takeSeat
获取麦位
leaveSeat
释放麦位
邀请其他人上麦(仅房间主持人和管理员可调用此方法)
将其他人踢下麦(仅房间主持人和管理员可调用此方法)
锁定某个麦位状态(仅房间主持人和管理员可调用此方法)
获取上麦请求列表,该接口自 v2.1.0 版本支持(仅房间主持人和管理员可调用此方法)

roomEngine 消息发送 API该模块自 v2.0.0 版本废弃,聊天模块请使用 chat 实例实现

API
描述
发送文本消息,该接口自 v2.0.0 版本废弃
发送自定义消息,该接口自 v2.0.0 版本废弃

roomEngine 设备管理 API

API
描述
获取摄像头设备列表
获取麦克风设备列表
获取扬声器设备列表
设置要使用的摄像头设备
设置要使用的麦克风设备
设置要使用的扬声器设备
获取当前正在使用的摄像头设备
获取当前正在使用的麦克风设备
获取当前正在使用的扬声器设备
开始进行摄像头测试
停止摄像头测试

roomEngine 事件监听 API

API
描述
on
监听 TUIRoomEvents 事件
off
取消监听 TUIRoomEvents 事件

roomEngine 其他 API

API
描述
获取 trtcCloud 实例
getTIM
获取 tim 实例

API 详情

once

监听 TUIRoomEngine 'ready' 事件。
TUIRoomEngine.once('ready', () => {
const roomEngine = new TUIRoomEngine();
await TUIRoomEngine.login({
sdkAppId: 0, // 填写您申请的 sdkAppId
userId: '', // 填写您业务对应的 userId
userSig: '', // 填写服务器或本地计算的 userSig
});
await roomEngine.createRoom({
roomId: '12345', // 填入您的房间 Id, 注意房间 Id 要求为字符串类型
name: 'Test Room', // 填入您的房间名称, 房间名称默认为 roomId,最长 30 字节
roomType: TUIRoomType.kConference, // 设置房间类型为 TUIRoomType.kConference 类型
});
});

login

说明:
v1.0.0 版本该接口命名为 TUIRoomEngine.init,v1.0.1 及其以上版本请使用 TUIRoomEngine.login 登录 TUIRoomEngine。
登录 TUIRoomEngine, 您必须在登录 TUIRoomEngine 之后才可以调用 TUIRoomEngine 及其实例的其他方法。
// 登录 TUIRoomEngine
await TUIRoomEngine.login({
sdkAppId: 0, // 填写您申请的 sdkAppId
userId: '', // 填写您业务对应的 userId
userSig: '', // 填写服务器或本地计算的 userSig
});
参数:
参数
类型
说明
默认值
含义
sdkAppId
number
必填
-
在 实时音视频控制台 单击 应用管理 > 创建应用 创建新应用之后,即可在 应用信息 中获取 sdkAppId 信息。
userId
string
必填
-
用户ID建议限制长度为32字节,只允许包含大小写英文字母(a-zA-Z)、数字(0-9)及下划线和连词符。
userSig
string
必填
-
userSig 签名
计算 userSig 的方式请参考 UserSig 相关
tim
TIM
非必填
-
若您在接入 roomEngine 的同时想使用即时通信 SDK 的更多能力,您可以将创建的 tim 实例传入 TUIRoomEngine。tim 实例的创建方式请参考 TIM.create
Returns Promise<void>

setSelfInfo

设置当前用户基本信息(用户名、用户头像)。
// 设置当前用户用户名及用户头像
await TUIRoomEngine.setSelfInfo({
userName: '', // 填写您的新用户名
avatarUrl: '', // 填写您的新头像地址
});

// 设置当前用户用户名, 用户头像及用户自定义消息
await TUIRoomEngine.setSelfInfo({
userName: '', // 填写您的新用户名
avatarUrl: '', // 填写您的新头像地址
customInfo: { // 填写用户自定义信息
Tag_Profile_Custom_Test: 'value1',
Tag_Profile_Custom_profile: 'value2',
},
})
参数:
参数
类型
说明
默认值
含义
userName
string
必填
-
用户名
avatarUrl
string
必填
-
用户头像
customInfo
object
选填
-
用户自定义资料,该字段自 v1.3.0 版本支持
说明:
App 管理员可以在 即时通信 IM 控制台 > 用户自定义字段 新增自定义资料字段,用户自定义字段生效以后,用户可以调用 setSelfInfo 接口设置自定义资料。
Returns Promise<void>

getSelfInfo

获取当前用户基本信息(用户名、用户头像)。
// 获取当前用户用户名及用户头像
const loginUserInfo = await TUIRoomEngine.getSelfInfo();
Returns Promise<TUILoginUserInfo> loginUserInfo

logout

说明:
该接口自 v1.0.1 版本支持。
登出 TUIRoomEngine。
// 登出 TUIRoomEngine
await TUIRoomEngine.logout();
Returns Promise<void>

createRoom

主持人创建房间,调用 createRoom 的用户为房间的所有者。创建房间时可设置房间 ID、房间名称、房间类型、是否开启麦位控制、是否允许加入用户开启音视频、发送消息等功能。
const roomEngine = new TUIRoomEngine();
await roomEngine.createRoom({
roomId: '12345', // 填入您的房间 Id, 注意房间 Id 要求为字符串类型
roomName: 'Test Room', // 填入您的房间名称, 房间名称默认为 roomId,最长 30 字节
roomType: TUIRoomType.kConference, // 设置房间类型为 TUIRoomType.kConference 类型
isSeatEnabled: false, // 设置是否开启麦位控制
isMicrophoneDisableForAllUser: false, // 设置是否允许加入用户打开麦克风
isCameraDisableForAllUser: false, // 设置是否允许加入用户打开摄像头
isMessageDisableForAllUser: false, // 设置是否允许加入用户发送消息
});
参数:
参数
类型
说明
默认值
含义
roomId
string
必填
-
房间 ID,roomId 限制长度为64字节,且仅支持以下范围的字符集:
大小写英文字母(a-zA-Z)
数字(0-9)
空格 ! # $ % & ( ) + - : ; < = . > ? @ [ ] ^ _ { } | ~ ,
roomName
string
选填
roomId
房间名称,默认值为 roomId, 不可传入空字符串
roomType
选填
TUIRoomType.kConference
房间类型
办公协同、医疗问诊、远程会议、教育场景,roomType 设置为 TUIRoomType.kConference
电商直播、语聊房场景,roomType 设置为 TUIRoomType.kLivingRoom
isSeatEnabled
boolean
选填
false
是否开启麦位控制,默认不开启
seatMode
选填
TUISeatMode.kFreeToTake
上麦模式(开启麦位控制后生效),默认值为 TUISeatMode.kFreeToTake
自由上麦模式,台下观众可以自由上麦,无需申请,seatMode 设置为 TUISeatMode.kFreeToTake
申请上麦模式,台下观众上麦需要房主或者管理员同意后才能上麦,seatMode 设置为 TUISeatMode.kApplyToTake
isMicrophoneDisableForAllUser
boolean
选填
false
是否开启全员禁麦,默认不开启全员禁麦
isCameraDisableForAllUser
boolean
选填
false
是否开启全员禁画,默认不开启全员禁画
isMessageDisableForAllUser
boolean
选填
false
是否允许成员发送消息,默认不禁止
maxSeatCount
number
选填
-
最大麦位数量
roomType 为 TUIRoomType.kConference (教育及会议场景) 时,maxSeatCount 值不做限制
roomType 为 TUIRoomType.kLivingRoom (直播场景) 时,maxSeatCount 最大限制为 16
enableCDNStreaming
boolean
选填
false
是否开启 CDN 直播流
cdnStreamDomain
string
选填
''
直播推流域名
Returns Promise<void>

enterRoom

进入房间接口。
const roomEngine = new TUIRoomEngine();
const roomInfo = await roomEngine.enterRoom({
roomId: '12345',
});
参数:
参数
类型
说明
默认值
含义
roomId
string
必填
-
房间号
Returns Promise<TUIRoomInfo> roomInfo
该接口返回当前房间信息

destroyRoom

解散房间接口,解散房间必须由房间所有者发起,解散房间之后房间不可进入。
const roomEngine = new TUIRoomEngine();
await roomEngine.destroyRoom();
Returns Promise<void>

exitRoom

离开房间接口,用户在执行 enterRoom 之后可通过 exitRoom 离开房间。
const roomEngine = new TUIRoomEngine();
await roomEngine.exitRoom();
Returns Promise<void>

fetchRoomInfo

获取房间信息。
const roomEngine = new TUIRoomEngine();
const roomInfo = roomEngine.fetchRoomInfo();
Returns:Promise<TUIRoomInfo> roomInfo

updateRoomNameByAdmin

更新当前房间的名字(仅群主或者管理员可以调用)。
const roomEngine = new TUIRoomEngine();
await roomEngine.createRoom({ roomId: '12345' });
await roomEngine.updateRoomNameByAdmin({ roomName: '新的名字' });
参数:
参数
类型
说明
默认值
含义
roomName
string
必填
-
更新房间的名字,要求 roomName 不为空字符串

updateRoomSpeechModeByAdmin

更新房间的发言模式(仅群主或者管理员可以调用)。
const roomEngine = new TUIRoomEngine();
await roomEngine.createRoom({ roomId: '12345' });
await roomEngine.updateRoomSpeechModeByAdmin({
speechMode: TUISpeechMode.kSpeakAfterTakingSeat // 更新为上麦后发言模式
});
参数:
参数
类型
说明
默认值
含义
speechMode
TUISpeechMode
必填
-
更新房间的发言模式
注意:
该接口自 v2.0.0 版本废弃

updateRoomSeatModeByAdmin

更新房间上麦模式(仅群主或者管理员可以调用)。
const roomEngine = new TUIRoomEngine();
await roomEngine.createRoom({ roomId: '12345' });
await roomEngine.updateRoomSeatModeByAdmin({
seatMode: TUISeatMode.kApplyToTake, // 更新为申请上麦模式
});
参数:
参数
类型
说明
默认值
含义
seatMode
TUISeatMode
必填
-
发言类型

getUserList

获取当前房间用户列表,注意该接口一次拉取的用户列表量最大为 50 个。
const roomEngine = new TUIRoomEngine();
const userList = [];
let result;
let nextSequence = 0;
do {
result = await roomEngine.getUserList({ nextSequence });
userList.push(...result.userInfoList);
nextSequence = result.nextSequence;
} while (result.nextSequence !== 0)
参数:
参数
类型
说明
默认值
含义
nextSequence
number
选填
0
偏移量,默认从 0 开始拉取用户
Returns:Promise<Array> result
result.nextSequence 下一次拉取群组用户的偏移量,如果 result.nextSequence 为 0 则代表 userList 全部拉取完毕。
result.userInfoList 本次拉取的 userList

getUserInfo

获取用户的详细信息。
const roomEngine = new TUIRoomEngine();
const userList = [];
const userInfo = await roomEngine.getUserInfo({
userId: 'user_12345',
});

参数:
参数
类型
说明
默认值
含义
userId
string
必填
-
根据 userId 获取该用户的详细信息
Returns:Promise<Array<TUIUserInfo>> userInfoList
该接口返回指定用户的用户信息

setLocalVideoView

设置本地视频流的渲染位置。
const roomEngine = new TUIRoomEngine();
// 设置本地摄像头流的播放区域为 id 是 'preview-camera' 的 div 元素
await roomEngine.setLocalVideoView({
view: 'preview-camera',
});
参数:
参数
类型
说明
默认值
含义
view
string
必填
-
streamType 对应的流渲染的 div 元素的 id
Returns:Promise<void>
说明:
自 v1.6.1 版本起,setLocalVideoView 只需传入 view 参数,设置本地视频流的播放容器。

openLocalCamera

打开本地摄像头,开始视频流采集。
const roomEngine = new TUIRoomEngine();
await roomEngine.setLocalVideoView({
streamType: TUIVideoStreamType.kCameraStream,
view: 'preview-camera',
});

// case 1: 桌面端打开摄像头
await roomEngine.openLocalCamera();

// case 2: 移动端使用前置摄像头打开视频预览
await roomEngine.openLocalCamera({ isFrontCamera: true });
// case 3: 移动端使用后置摄像头打开视频预览
await roomEngine.openLocalCamera({ isFrontCamera: false });
参数:
参数
类型
说明
默认值
含义
isFrontCamera
boolean
选填
-
设置移动端打开本地预览视频的默认摄像头,该参数仅对移动端有效
该参数自 v1.3.1 版本开始支持
Returns:Promise<void>

closeLocalCamera

关闭本地摄像头。
const roomEngine = new TUIRoomEngine();
await roomEngine.closeLocalCamera();
Returns:Promise<void>

openLocalMicrophone

打开本地麦克风,开始采集音频流。
const roomEngine = new TUIRoomEngine();
await roomEngine.openLocalMicrophone();
Returns:Promise<void>

closeLocalMicrophone

关闭本地麦克风。
const roomEngine = new TUIRoomEngine();
await roomEngine.closeLocalMicrophone();
Returns:Promise<void>

updateVideoQuality

设置本地视频流的编码参数,默认为 TUIVideoProfile.kVideoQuality_720P。
const roomEngine = new TUIRoomEngine();
await roomEngine.updateVideoQuality({
quality: TUIVideoQuality.kVideoQuality_540p,
});
参数:
参数
类型
说明
默认值
含义
quality
必填
-
清晰 TUIVideoProfile.kVideoQuality_360P
标清 TUIVideoProfile.kVideoQuality_540P
高清 TUIVideoProfile.kVideoQuality_720P
超清 TUIVideoProfile.kVideoQuality_1080P
Returns:Promise<void>

setVideoResolutionMode

设置本地视频流的分辨率模式,默认为 TUIResolutionMode.kResolutionMode_Landscape。
const roomEngine = new TUIRoomEngine();
await roomEngine.setVideoResolutionMode({
type: TUIVideoStreamType.kCameraStream,
resolutionMode: TUIResolutionMode.kResolutionMode_Landscape,
});
参数:
参数
类型
说明
默认值
含义
streamType
必填
-
本地流类型
resolutionMode
必填
TUIResolutionMode.kResolutionMode_Landscape
分辨率模式
Returns:Promise<void>
说明:
该接口自 v1.5.0 版本开始支持。

updateVideoQualityEx

设置本地视频流的编码参数
const roomEngine = new TUIRoomEngine();
await roomEngine.updateVideoQualityEx({
streamType: TUIVideoStreamType.kCameraStream,
encoderParams: {
videoResolution: TUIVideoQuality.kVideoQuality_720p,
fps: 15,
bitrate: 2000,
resolutionMode: TUIResolutionMode.kResolutionMode_Landscape,
}
});
参数:
参数
类型
说明
默认值
含义
streamType
必填
-
本地流类型
encoderParams
必填
-
详细编码参数
说明:
该接口自 v1.5.0 版本开始支持。

updateAudioQuality

设置本地音频的参数。
注意:
该方法需要在 openLocalMicrophone 之前进行设置,否则不会生效。
const roomEngine = new TUIRoomEngine();
await roomEngine.updateAudioQuality({
quality: TUIAudioQuality.kAudioProfileMusic,
});
参数:
参数
类型
说明
默认值
含义
audioProfile
必填
-
TUIAudioQuality.kAudioProfileSpeech:语言模式;采样率:16k
TUIAudioQuality.kAudioProfileDefault:标准模式(或者默认模式);采样率:48k
TUIAudioQuality.kAudioProfileMusic:音乐模式;采样率:48k
Returns:Promise<void>

startScreenSharing

开始屏幕共享。
const roomEngine = new TUIRoomEngine();
// example 1: 开始屏幕分享
await roomEngine.startScreenSharing();
// example 2: 开始屏幕分享(可采集系统音频)
await roomEngine.startScreenSharing({ screenAudio: true });
// example 3: 开始屏幕分享并在本地预览
await roomEngine.startScreenSharing({ view: 'screen-preview' });
参数:
参数
类型
说明
默认值
含义
screenAudio
boolean
选填
false
web 端屏幕共享是否可选共享系统声音, screenAudio 默认值为 false
view
string
选填
-
本地预览屏幕分享的 dom 元素的 id,该参数自 v1.6.1 版本支持
Returns:Promise<void>

stopScreenSharing

停止屏幕共享。
const roomEngine = new TUIRoomEngine();
await roomEngine.stopScreenSharing();
Returns:Promise<void>

startPushLocalVideo

进房后会默认向远端推本地视频流,该接口用于停止推流后重新向远端推本地视频流。
const roomEngine = new TUIRoomEngine();
await roomEngine.startPushLocalVideo();
Returns:Promise<void>

stopPushLocalVideo

停止向远端推本地视频流。
const roomEngine = new TUIRoomEngine();
await roomEngine.stopPushLocalVideo();
Returns:Promise<void>

startPushLocalAudio

进房后会默认向远端推本地音频流,该接口用于停止推流后重新向远端推本地音频流。
const roomEngine = new TUIRoomEngine();
await roomEngine.startPushLocalAudio();
Returns:Promise<void>
注意:
该接口自 v1.5.0 版本废弃,请使用 muteLocalAudio 方法代替。

stopPushLocalAudio

停止向远端推本地音频流。
const roomEngine = new TUIRoomEngine();
await roomEngine.stopPushLocalAudio();
Returns:Promise<void>
注意:
该接口自 v1.5.0 版本废弃,请使用 muteLocalAudio 方法代替。

muteLocalAudio

停止向远端推本地音频流。
const roomEngine = new TUIRoomEngine();
await roomEngine.muteLocalAudio();
Returns:Promise<void>
说明:
该接口自 v1.5.1 版本开始支持。

unmuteLocalAudio

开始向远端推本地音频流。
const roomEngine = new TUIRoomEngine();
await roomEngine.unmuteLocalAudio();
Returns:Promise<void>
说明:
该接口自 v1.5.1 版本开始支持。

setRemoteVideoView

设置远端流渲染的区域。
const roomEngine = new TUIRoomEngine();

// 设置远端用户视频流在 id 为 'remote_preview_camera' 的区域播放
await roomEngine.setRemoteVideoView({
userId: 'user_1234',
streamType: TUIVideoStreamType.kCameraStream,
view: 'remote_preview_camera',
});
// 设置远端用户屏幕分享流在 id 为 'remote_preview_screen' 的区域播放
await roomEngine.setRemoteVideoView({
userId: 'user_1234',
streamType: TUIVideoStreamType.kScreenStream,
view: 'remote_preview_screen',
});
参数:
参数
类型
说明
默认值
含义
userId
string
必填
-
用户 ID
streamType
必填
-
用户流类型
view
string
必填
-
播放远端用户流的 div 元素的 id
Returns:Promise<void>

startPlayRemoteVideo

开始播放远端用户视频流。
const roomEngine = new TUIRoomEngine();
await roomEngine.startPlayRemoteVideo({
userId: 'user_1234',
streamType: TUIVideoStreamType.kCameraStream,
});
参数:
参数
类型
说明
默认值
含义
userId
string
必填
-
用户 ID
streamType
必填
-
用户流类型
TUIVideoStreamType.kCameraStream 视频流
TUIVideoStreamType.kScreenStream 屏幕分享流
TUIVideoStreamType.kCameraStreamLow 低清视频流
Returns:Promise<void>

stopPlayRemoteVideo

停止播放远端用户视频流。
const roomEngine = new TUIRoomEngine();
await roomEngine.stopPlayRemoteVideo({
userId: 'user_1234',
streamType: TUIVideoStreamType.kCameraStream,
});
参数:
参数
类型
说明
默认值
含义
userId
string
必填
-
用户 ID
streamType
必填
-
用户流类型
TUIVideoStreamType.kCameraStream 视频流
TUIVideoStreamType.kScreenStream 屏幕分享流
TUIVideoStreamType.kCameraStreamLow 低清视频流
Returns:Promise<void>

muteRemoteAudioStream

停止远端用户的音频流。
const roomEngine = new TUIRoomEngine();
await roomEngine.muteRemoteAudioStream({
userId: 'user_1234',
isMute: true,
});
参数
类型
说明
默认值
含义
userId
string
必填
-
用户 ID
isMute
boolean
必填
-
是否停止远端用户的音频

openRemoteDeviceByAdmin

请求远端用户打开媒体设备。
const roomEngine = new TUIRoomEngine();
const requestId = roomEngine.openRemoteDeviceByAdmin({
userId: 'user_1234',
device: TUIMediaDevice.kMicrophone //请求的设备为麦克风
timeout: 0,
requestCallback: ({ requestCallbackType, requestId, userId, code, message }) => {
switch (requestCallbackType) {
case TUIRequestCallbackType.kRequestAccepted:
// 请求被接受
break;
case TUIRequestCallbackType.kRequestRejected:
// 请求被拒绝
break;
case TUIRequestCallbackType.kRequestCancelled:
// 请求已取消
break;
case TUIRequestCallbackType.kRequestTimeout:
// 请求超时
break;
case TUIRequestCallbackType.kRequestError:
// 请求错误
break;
default:
break;
}
},
});
参数:
参数
类型
说明
默认值
含义
userId
string
必填
-
用户 ID
device
必填
-
媒体设备类型(摄像头/麦克风/屏幕共享)
timeout
number
必填
-
超时时间。若 timeout 设置为 0 ,则无超时时间
requestCallback
Function
选填
空函数
请求回调,用来通知发起方请求被接受/拒绝/取消/超时/错误的回调
Returns:Promise<string> requestId
该接口返回 requestId,用户可使用该 requestId 调用 cancelRequest 接口取消请求。
说明:
v1.0.2 及其以上版本该接口返回的 requestId 类型为 string;v1.0.0 及 v1.0.1 版本该接口返回的 requestId 类型为 number。

applyToAdminToOpenLocalDevice

参会者向主持人申请打开设备。
const roomEngine = new TUIRoomEngine();
const requestId = roomEngine.applyToAdminToOpenLocalDevice({
device: TUIMediaDevice.kMicrophone //请求的设备为麦克风
timeout: 0,
requestCallback: ({ requestCallbackType, requestId, userId, code, message }) => {
switch (requestCallbackType) {
case TUIRequestCallbackType.kRequestAccepted:
// 请求被接受
break;
case TUIRequestCallbackType.kRequestRejected:
// 请求被拒绝
break;
case TUIRequestCallbackType.kRequestCancelled:
// 请求已取消
break;
case TUIRequestCallbackType.kRequestTimeout:
// 请求超时
break;
case TUIRequestCallbackType.kRequestError:
// 请求错误
break;
default:
break;
}
},
});
参数:
参数
类型
说明
默认值
含义
device
必填
-
媒体设备类型(摄像头/麦克风/屏幕共享)
timeout
number
必填
-
超时时间。若 timeout 设置为 0 ,则无超时时间
requestCallback
Function
选填
空函数
请求回调,用来通知发起方请求被接受/拒绝/取消/超时/错误的回调
Returns:Promise<string> requestId
该接口返回 requestId,用户可使用该 requestId 调用 cancelRequest 接口取消请求。

closeRemoteDeviceByAdmin

关闭远端用户媒体设备。
const roomEngine = new TUIRoomEngine();
await roomEngine.closeRemoteDeviceByAdmin({
userId: 'user_1234',
device: TUIMediaDevice.kMicrophone, //关闭麦克风
});
参数:
参数
类型
说明
默认值
含义
userId
string
必填
-
用户 ID
device
必填
-
媒体设备类型(摄像头/麦克风/屏幕共享)
Returns:Promise<void>

cancelRequest

取消已经发出的请求。
const roomEngine = new TUIRoomEngine();
await roomEngine.cancelRequest({
requestId: '', // 请使用实际 requestId
});
参数:
参数
类型
说明
默认值
含义
requestId
string
必填
-
请求 ID
Returns:Promise<void>
说明:
v1.0.2 及其以上版本该接口接收的 requestId 参数类型为 string;v1.0.0 及 v1.0.1 版本该接口接收的 requestId 参数类型为 number。

responseRemoteRequest

回复远端用户的请求。
const roomEngine = new TUIRoomEngine();
// 同意远端的请求
await roomEngine.responseRemoteRequest({
requestId: '', // 请使用实际 requestId
agree: true,
});
// 拒绝远端的请求
await roomEngine.responseRemoteRequest({
requestId: '', // 请使用实际 requestId
agree: false,
});
参数:
参数
类型
说明
默认值
含义
requestId
string
必填
-
请求 ID
agree
boolean
必填
-
是否同意
Returns:Promise<void>
说明:
v1.0.2 及其以上版本该接口接收的 requestId 参数类型为 string;v1.0.0 及 v1.0.1 版本该接口接收的 requestId 参数类型为 number。

disableDeviceForAllUserByAdmin

禁止/允许所有用户打开媒体设备(此接口对于房主和管理员无效)。
// Example 1: 禁止所有用户打开麦克风
await roomEngine.disableDeviceForAllUserByAdmin({
device: TUIMediaDevice.kMicrophone,
isDisable: true,
})
// Example 2: 允许所有用户打开麦克风
await roomEngine.disableDeviceForAllUserByAdmin({
device: TUIMediaDevice.kMicrophone,
isDisable: false,
})
参数:
参数
类型
说明
默认值
含义
device
必填
-
被禁用的媒体设备类型(摄像头/麦克风/屏幕共享)
isDisable
boolean
必填
-
是否被禁止
Returns:Promise<void>

disableSendingMessageForAllUser

所有用户的是否允许发消息(此接口对于房主和管理员无效)。
await roomEngine.disableSendingMessageForAllUser({
isDisable: true,
});
参数:
参数
类型
说明
默认值
含义
isDisable
boolean
必填
-
是否被禁用
Returns:Promise<void>

disableSendingMessageByAdmin

特定用户是否被允许发消息。
await roomEngine.disableSendingMessageByAdmin({
userId: 'user_1234',
isDisable: true,
});
参数:
参数
类型
说明
默认值
含义
userId
string
必填
-
用户 ID
isDisable
boolean
必填
-
是否被禁用
Returns:Promise<void>

changeUserRole

改变用户的角色(仅主持人可调用该接口)。
const roomEngine = new TUIRoomEngine();

// 将房间移交给用户 user_1234
await roomEngine.changeUserRole({
userId: 'user_1234',
role: TUIRole.kRoomOwner,
});

// 将用户 user_1234 设置为房间管理员
await roomEngine.changeUserRole({
userId: 'user_1234',
userRole: TUIRole.kAdministrator,
});
参数:
参数
类型
说明
默认值
含义
userId
string
必填
-
用户 ID
userRole
TUIRole
必填
-
用户角色
主持人 TUIRole.kRoomOwner
管理员 TUIRole.kAdministrator
普通成员 TUIRole.kGeneralUser
Returns:Promise<void>

setCustomInfoForUser

主持人可以设置自己,管理员及普通用户的自定义信息。
管理员可以设置自己及普通用户的自定义信息。
普通用户仅可以设置自己的自定义信息。
const roomEngine = new TUIRoomEngine();
await roomEngine.setCustomInfoForUser({
userId: 'user_12345',
customInfo: {
'key1': 'value1',
'key2': 'value2',
}
});
Returns:Promise<void>

kickRemoteUserOutOfRoom

将用户踢出房间(仅主持人和管理员可调用该接口)。
const roomEngine = new TUIRoomEngine();
await roomEngine.kickRemoteUserOutOfRoom({
userId: 'user_1234',
});
参数:
参数
类型
说明
默认值
含义
userId
string
必填
-
用户 ID
Returns:Promise<void>

setMaxSeatCount

设置房间麦位最大值
roomType 为 TUIRoomType.kConference (教育及会议场景) 时,maxSeatCount 值不做限制;
roomType 为 TUIRoomType.kLivingRoom (直播场景) 时,maxSeatCount 最大限制为 16;
const roomEngine = new TUIRoomEngine();
await roomEngine.createRoom({ roomId: '12345' });
await roomEngine.setMaxSeatCount({ maxSeatCount: 16 })
参数:
参数
类型
说明
默认值
含义
maxSeatCount
number
必填
-
设置房间麦位最大值
Returns:Promise<void>

getSeatList

获取麦位列表。
const roomEngine = new TUIRoomEngine();
const seatList = await roomEngine.getSeatList();
Returns:Promise<TUISeatInfo[]> seatList
seatList 为当前房间所有麦位列表

takeSeat

麦下用户可调用 takeSeat 成为麦上用户,仅麦上用户可发布本地音视频流。
当 roomInfo.roomType 为 TUIRoomType.kConference 且 roomInfo.seatMode 为 TUISeatMode.kApplyToTake 时,普通用户调用 takeSeat 方法需要等待主持人/管理员的同意后成为麦上用户。
当 roomInfo.roomType 为 TUIRoomType.kLivingRoom 且 roomInfo.seatMode 为 TUISeatMode.kFreeToTake 时, 普通用户调用 takeSeat 方法成功后即为麦上用户。
主持人&管理员调用 takeSeat 成功后即为麦上用户。
麦上用户的变更通过 TUIRoomEvents.onSeatListChanged 通知所有用户。
const roomEngine = new TUIRoomEngine();
// 情景一:主持人/管理员上麦
// 情景二:当 roomInfo.roomType 为 TUIRoomType.kConference
// 且 roomInfo.seatMode 为 TUISeatMode.kFreeToTake 模式时,普通用户上麦
await roomEngine.takeSeat({
seatIndex: -1,
timeout: 0,
});
// 情景三:roomInfo.seatMode 为 TUISeatMode.kApplyToTake 模式时,普通用户上麦
const requestId = await roomEngine.instance?.takeSeat({
seatIndex: -1,
timeout: 0,
requestCallback: ({ requestCallbackType, requestId, userId, code, message }) => {
switch (requestCallbackType) {
case TUIRequestCallbackType.kRequestAccepted:
// 请求被接受
break;
case TUIRequestCallbackType.kRequestRejected:
// 请求被拒绝
break;
case TUIRequestCallbackType.kRequestCancelled:
// 请求已取消
break;
case TUIRequestCallbackType.kRequestTimeout:
// 请求超时
break;
case TUIRequestCallbackType.kRequestError:
// 请求错误
break;
default:
break;
}
},
});
参数:
参数
类型
说明
默认值
含义
seatIndex
number
必填
-
麦位 index, 无麦位序号时设置为 -1
timeout
number
必填
-
超时时间。若 timeout 设置为 0,则无超时时间
requestCallback
Function
选填
空函数
请求回调,用来通知发起方请求被接受/拒绝/取消/超时/错误的回调
Returns:Promise<string> requestId
roomInfo.seatMode 为 TUISeatMode.kApplyToTake 模式时,普通用户调用该接口时返回 requestId,普通用户可使用该 requestId 调用 cancelRequest 接口取消上麦请求。
说明:
v1.0.2 及其以上版本该接口返回的 requestId 类型为 string;v1.0.0 及 v1.0.1 版本该接口返回的 requestId 类型为 number。

leaveSeat

释放麦位。
const roomEngine = new TUIRoomEngine();
await roomEngine.leaveSeat();
Returns:Promise<void>

takeUserOnSeatByAdmin

邀请其他人上麦。
const roomEngine = new TUIRoomEngine();
const requestId = roomEngine.takeUserOnSeatByAdmin({
seatIndex: 0,
userId: 'user_1234',
timeout: 0,
requestCallback: ({ requestCallbackType, requestId, userId, code, message }) => {
switch (requestCallbackType) {
case TUIRequestCallbackType.kRequestAccepted:
// 请求被接受
break;
case TUIRequestCallbackType.kRequestRejected:
// 请求被拒绝
break;
case TUIRequestCallbackType.kRequestCancelled:
// 请求已取消
break;
case TUIRequestCallbackType.kRequestTimeout:
// 请求超时
break;
case TUIRequestCallbackType.kRequestError:
// 请求错误
break;
default:
break;
}
},
});
参数:
参数
类型
说明
默认值
含义
seatIndex
number
必填
-
麦位 index
userId
string
必填
-
用户 ID
timeout
number
必填
-
超时时间,设置为 0 时,无超时时间
requestCallback
Function
选填
空函数
请求回调,用来通知发起方请求被接受/拒绝/取消/超时/错误的回调
Returns:Promise<string> requestId
该接口返回 requestId,用户可使用该 requestId 调用 cancelRequest 接口取消请求。
说明:
v1.0.2 及其以上版本该接口返回的 requestId 类型为 string;v1.0.0 及 v1.0.1 版本该接口返回的 requestId 类型为 number。

kickUserOffSeatByAdmin

要求其他人下麦。
const roomEngine = new TUIRoomEngine();
const requestId = await roomEngine.kickUserOffSeatByAdmin({
seatIndex: 0,
userId: 'user_1234',
});
参数:
参数
类型
说明
默认值
含义
seatIndex
number
必填
-
麦位 index
userId
string
必填
-
用户 ID
Returns:Promise<void>

lockSeatByAdmin

锁定某个麦位状态(仅房间主持人和管理员可调用此方法)。
const roomEngine = new TUIRoomEngine();
await roomEngine.lockSeatByAdmin({
seatIndex: 0,
lockParams: {
lockSeat: true,
lockVideo: true,
lockAudio: true,
},
});
参数:
参数
类型
说明
默认值
含义
seatIndex
number
必填
-
麦位索引
lockParams
必填
-
锁麦参数
Returns:Promise<void>

getSeatApplicationList

获取房间内申请上麦用户的请求列表, 该接口自 v2.1.0 版本支持(仅房间主持人和管理员可调用此方法)。
const roomEngine = new TUIRoomEngine();
const applicationList = await roomEngine.getSeatApplicationList();
Returns:Promise<TUIRequest[]>

sendTextMessage

发送文本消息。
const roomEngine = new TUIRoomEngine();
await roomEngine.sendTextMessage({
messageText: 'hello, everyone',
});
参数:
参数
类型
说明
默认值
含义
messageText
string
必填
-
文本消息内容
Returns:Promise<void>
注意:
该接口自 v2.0.0 版本废弃。请使用 getTIM 方法获取 tim 实例发送消息。

sendCustomMessage

发送自定义消息。
const roomEngine = new TUIRoomEngine();
await roomEngine.sendCustomMessage({
messageText: '{ data:'', description: ''}',
});
参数:
参数
类型
说明
默认值
含义
messageText
string
必填
-
自定义消息内容
Returns:Promise<void>
注意:
该接口自 v2.0.0 版本废弃。请使用 getTIM 方法获取 tim 实例发送消息。

switchCamera

切换前后置摄像头,该接口适用于移动端。
说明:
该接口自 v1.3.1 版本开始支持
// 移动端切换为前置摄像头
await roomEngine.switchCamera({ isFrontCamera: true });

// 移动端切换为后置摄像头
await roomEngine.switchCamera({ isFrontCamera: false });
参数:
参数
类型
说明
默认值
含义
isFrontCamera
boolean
必填
-
是否切换为前置摄像头
Returns:Promise<void>

getCameraDevicesList

获取摄像头设备列表。
const roomEngine = new TUIRoomEngine();
const cameraList = await roomEngine.getCameraDevicesList();
for (i = 0; i < cameraList.length; i++) {
var camera = cameraList[i];
console.info("camera deviceName: " + camera.deviceName + " deviceId:" + camera.deviceId);
}
Returns: Promise<TRTCDeviceInfo[]> cameraList

getMicDevicesList

获取麦克风设备列表。
const roomEngine = new TUIRoomEngine();
const micList = await roomEngine.getMicDevicesList();
for (i = 0; i < micList.length; i++) {
var mic = micList[i];
console.info("mic deviceName: " + mic.deviceName + " deviceId:" + mic.deviceId);
}
Returns: Promise<TRTCDeviceInfo[]> micList

getSpeakerDevicesList

获取扬声器设备列表。
const roomEngine = new TUIRoomEngine();
const speakerList = await roomEngine.getSpeakerDevicesList();
for (i = 0; i < speakerList.length; i++) {
var speaker = speakerList[i];
console.info("speaker deviceName: " + speaker.deviceName + " deviceId:" + speaker.deviceId);
}
Returns: Promise<TRTCDeviceInfo[]> speakerList

setCurrentCameraDevice

设置要使用的摄像头设备。
const roomEngine = new TUIRoomEngine();
await roomEngine.setCurrentCameraDevice({ deviceId: '' });
参数:
参数
类型
说明
默认值
含义
deviceId
string
必填
-
从 getCameraDevicesList 中得到的设备 ID
Returns:void

setCurrentMicDevice

设置要使用的麦克风设备。
const roomEngine = new TUIRoomEngine();
await roomEngine.setCurrentMicDevice({ deviceId: '' });
参数:
参数
类型
说明
默认值
含义
deviceId
string
必填
-
从 getMicDevicesList 中得到的设备 ID
Returns:void

setCurrentSpeakerDevice

设置要使用的扬声器设备。
const roomEngine = new TUIRoomEngine();
await roomEngine.setCurrentSpeakerDevice({ deviceId: '' });
参数:
参数
类型
说明
默认值
含义
deviceId
string
必填
-
从 getSpeakerDevicesList 中得到的设备 ID
Returns:void

getCurrentCameraDevice

获取当前正在使用的摄像头设备。
const roomEngine = new TUIRoomEngine();
const currentCameraDevice = roomEngine.getCurrentCameraDevice();
Returns:TRTCDeviceInfo
设备信息,能获取设备 ID 和设备名称。

getCurrentMicDevice

获取当前正在使用的麦克风设备。
const roomEngine = new TUIRoomEngine();
const currentMicDevice = roomEngine.getCurrentMicDevice();
Returns:TRTCDeviceInfo
设备信息,能获取设备 ID 和设备名称。

getCurrentSpeakerDevice

获取当前正在使用的扬声器设备。
const roomEngine = new TUIRoomEngine();
const currentSpeakerDevice = roomEngine.getCurrentSpeakerDevice();
Returns:TRTCDeviceInfo
设备信息,能获取设备 ID 和设备名称。

startCameraDeviceTest

开始进行摄像头测试。
const roomEngine = new TUIRoomEngine();
await roomEngine.startCameraDeviceTest({ view: 'test-preview' });
参数:
参数
类型
说明
默认值
含义
view
string
必填
-
显示摄像头测试的视频区域, 传入的 view 为承载预览画面 div 元素的 Id
Returns:Promise<void>

stopCameraDeviceTest

停止摄像头测试。
const roomEngine = new TUIRoomEngine();
await roomEngine.stopCameraDeviceTest();
Returns:Promise<void>

on

监听 roomEngine 的事件。
const roomEngine = new TUIRoomEngine();
roomEngine.on(event, func);
参数:
参数
类型
说明
默认值
含义
event
必填
-
TUIRoomEngine 事件列表
func
Function
必填
-
事件回调函数
Returns:void

off

取消监听 roomEngine 的事件。
const roomEngine = new TUIRoomEngine();
roomEngine.off(event, func);
参数:
参数
类型
说明
默认值
含义
event
必填
-
TUIRoomEngine 事件列表
func
Function
必填
-
事件回调函数
Returns:void

getTRTCCloud

获取 trtcCloud 实例, web 端 trtcCloud 能力请查看:TRTCCloud API 文档
const roomEngine = new TUIRoomEngine();
const trtcCloud = roomEngine.getTRTCCloud();
Returns:TRTCCloud

getTIM

获取 tim 实例, web 端 tim 能力请查看: IM API 文档
const roomEngine = new TUIRoomEngine();
const tim = roomEngine.getTIM();
Returns:tim
注意:
自 v1.6.0 版本后,IM SDK 升级至 v3 版本,请查看: IM API 文档