TUIRoomEngine

TUIRoomEngine 简介

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

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

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

TUIRoomEngine API

TUIRoomEngine 静态方法

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

roomEngine 房间管理 API

API
描述
创建房间
enterRoom
进入房间
销毁房间
exitRoom
离开房间
获取房间信息
更新房间的名字(仅群主或者管理员可以调用)
更新房间的发言模式(仅群主或者管理员可以调用)
获取当前房间用户列表
获取用户的详细信息

roomEngine 音视频 API

API
描述
设置本地流的渲染位置
本地摄像头视频流采集
关闭本地摄像头
打开本地麦克风
关闭本地麦克风
设置本地视频的参数
设置本地音频的参数
开始向远端推本地视频流
停止向远端推本地视频流
开始向远端推本地音频流
停止向远端推本地音频流
设置远端流渲染的区域
开始播放远端用户视频流
停止播放远端用户视频流
停止远端用户的音频流

roomEngine 成员管理 API

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

roomEngine 屏幕分享 API

API
描述
开始屏幕共享
停止屏幕共享
获取屏幕分享列表
切换屏幕分享窗口

roomEngine 麦位管理API

API
描述
设置房间麦位最大值
获取麦位信息
takeSeat
获取麦位
leaveSeat
释放麦位
邀请其他人上麦(仅房间主持人和管理员可调用此方法)
将其他人踢下麦(仅房间主持人和管理员可调用此方法)
锁定某个麦位状态(仅房间主持人和管理员可调用此方法)

roomEngine 消息发送API

API
描述
发送文本消息
发送自定义消息

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.init({
sdkAppId: 0, // 填写您申请的 sdkAppId
userId: '', // 填写您业务对应的 userId
userSig: '', // 填写服务器或本地计算的 userSig
});
await roomEngine.createRoom({
roomId: '12345', // 填入您的房间 Id, 注意房间 Id 要求为字符串类型
name: 'Test Room', // 填入您的房间名称, 房间名称默认为 roomId,最长 30 字节
roomType: TUIRoomType.kGroup, // 设置房间类型为 TUIRoomType.kGroup 类型
});
});

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
在 实时音视频控制台 单击 应用管理 > 创建应用 创建新应用之后,即可在 应用信息 中获取 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: '', // 填写您的新头像地址
});
参数:
参数
类型
说明
默认值
含义
userName
string
必填
-
用户名
avatarUrl
string
必填
-
用户头像
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 类型
speechMode: TUISpeechMode.kFreeToSpeak, // 设置发言模式为自由发言模式
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
speechMode
TUISpeechMode
选填
TUISpeechMode.kFreeToSpeak
房间内发言模式
roomType 为 TUIRoomType.kConference (教育及会议场景)
speechMode 设置为 TUISpeechMode.kFreeToSpeak,用户进房默认可以打开摄像头和麦克风 speechMode 设置为 TUISpeechMode.kApplyToSpeak,用户进房默认不打开摄像头和麦克风,需要向主持人申请打开摄像头或麦克风TUISpeechMode.kFreeToSpeak 及 TUISpeechMode.kApplyToSpeak 模式可互相切换 speechMode 设置为 TUISpeechMode.kSpeakAfterTakingSeat,用户进房后需要调用 takeSeat 上麦接口获取打开摄像头和麦克风的权限

roomType 为 TUIRoomType.kLivingRoom (直播场景) 时:
speechMode 设置为 TUISpeechMode.kFreeToSpeak,上麦不需要主持人同意
speechMode 设置为 TUISpeechMode.kSpeakAfterTakingSeat,上麦需要主持人同意
TUISpeechMode.kFreeToSpeak 及 TUISpeechMode.kSpeakAfterTakingSeat 模式可互相切换
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 不为空字符串
Returns Promise<void>

updateRoomSpeechModeByAdmin

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

getUserList

获取当前房间用户列表,注意该接口一次拉取的用户列表量最大为 100 个。
const roomEngine = new TUIRoomEngine();
const userList = [];
let result;
do {
result = await globalProperties.roomEngine.getUserList();
userList.push(...result.userInfoList);
} while (result.nextSequence !== 0)
参数:
参数
类型
说明
默认值
含义
nextSequence
number
选填
0
偏移量,默认从 0 开始拉取用户
ReturnsPromise<object> 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 获取该用户的详细信息
ReturnsPromise<TUIUserInfo> userInfo
该接口返回指定用户的用户信息

setLocalVideoView

设置本地流的渲染位置。
const roomEngine = new TUIRoomEngine();
// 设置本地摄像头流的播放区域为 id 是 'preview-camera' 的 div 元素
await roomEngine.setLocalVideoView({
streamType: TUIVideoStreamType.kCameraStream,
view: 'preview-camera',
});
// 设置本地屏幕分享流的播放区域为 id 是 'preview-screen' 的 div 元素
await roomEngine.setLocalVideoView({
streamType: TUIVideoStreamType.kScreenStream,
view: 'preview-screen',
});
参数:
参数
类型
说明
默认值
含义
streamType
必填
-
本地流类型
view
string
必填
-
streamType 对应的流渲染的 div 元素的 id
Returns:Promise<void>

openLocalCamera

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

updateAudioQuality

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

stopPushLocalAudio

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

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
必填
-
媒体设备类型(摄像头/麦克风/屏幕共享)

cancelRequest

取消已经发出的请求。
const roomEngine = new TUIRoomEngine();
await roomEngine.cancelRequest({
requestId: '', // 请使用实际 requestId
});
参数:
参数
类型
说明
默认值
含义
requestId
string
必填
-
请求 ID
ReturnsPromise<string> requestId
该接口返回 requestId,用户可使用该 requestId 调用 cancelRequest 接口取消请求
说明:
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
必填
-
是否同意
ReturnsPromise<void>
说明:
v1.0.2 及其以上版本该接口接收的 requestId 参数类型为 string;v1.0.0 及 v1.0.1 版本该接口接收的 requestId 参数类型为 number; disableDeviceForAllUserByAdmin

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>

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();
ReturnsPromise<TUISeatInfo[]> seatList
seatList 为当前房间所有麦位列表

takeSeat

麦下用户可调用 takeSeat 成为麦上用户,仅麦上用户可发布本地音视频流。
当 roomInfo.roomType 为 TUIRoomType.kConference 且 roomInfo.speechMode 为 TUISpeechMode.kSpeakAfterTakingSeat 时,普通用户调用 takeSeat 方法需要等待主持人/管理员的同意后成为麦上用户。
当 roomInfo.roomType 为 TUIRoomType.kLivingRoom 且 roomInfo.speechMode 为 TUISpeechMode.kFreeToSpeak 时, 普通用户调用 takeSeat 方法成功后即为麦上用户
主持人&管理员调用 takeSeat 成功后即为麦上用户。
麦上用户的变更通过 TUIRoomEvents.onSeatListChanged 通知所有用户。
const roomEngine = new TUIRoomEngine();
// 情景一:主持人/管理员上麦
// 情景二:当 roomInfo.roomType 为 TUIRoomType.kConference
// 且 roomInfo.speechMode 为 TUISpeechMode.kSpeakAfterTakingSeat 时,普通用户上麦
await roomEngine.takeSeat({
seatIndex: -1,
timeout: 0,
});
// 情景三:当 roomInfo.enableSeatControl 为 true 时,普通用户上麦
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.enableSeatControl 为 true,普通用户调用该接口时返回 requestId,普通用户可使用该 requestId 调用 cancelRequest 接口取消上麦请求。
说明:
v1.0.2 及其以上版本该接口返回的 requestId 类型为 string;v1.0.0 及 v1.0.1 版本该接口返回的 requestId 类型为 number;

leaveSeat

释放麦位。
const roomEngine = new TUIRoomEngine();
await roomEngine.leaveSeat();
ReturnsPromise<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
必填
-
超时时间。若 timeout 设置为 0 ,则无超时时间
requestCallback
Function
选填
空函数
请求回调,用来通知发起方请求被接受/拒绝/取消/超时/错误的回调
ReturnsPromise<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
ReturnsPromise<void>

lockSeatByAdmin

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

startScreenSharingElectron

开始屏幕共享 Electron。
const roomEngine = new TUIRoomEngine();
await roomEngine.startScreenSharingElectron('targetId');
参数:
参数
类型
说明
默认值
含义
targetId
string
选填
-
分享窗口 ID,可从 getScreenSharingTarget 获取
ReturnsPromise<void>

stopScreenSharingElectron

停止屏幕共享 Electron。
const roomEngine = new TUIRoomEngine();
await roomEngine.stopScreenSharingElectron();
ReturnsPromise<void>

getScreenSharingTarget

获取屏幕分享列表 Electron。
const roomEngine = new TUIRoomEngine();
const screenList = await roomEngine.getScreenSharingTarget();
ReturnsPromise<void>

selectScreenSharingTarget

切换屏幕分享窗口 Electron。
const roomEngine = new TUIRoomEngine();
await roomEngine.selectScreenSharingTarget('targetId');
参数:
参数
类型
说明
默认值
含义
targetId
string
必填
-
分享窗口 ID,可从 getScreenSharingTarget 获取
ReturnsPromise<void>

sendTextMessage

发送文本消息。
const roomEngine = new TUIRoomEngine();
await roomEngine.sendTextMessage({
messageText: 'hello, everyone',
});
参数:
参数
类型
说明
默认值
含义
messageText
string
必填
-
文本消息内容
ReturnsPromise<void>

sendCustomMessage

发送自定义消息。
const roomEngine = new TUIRoomEngine();
await roomEngine.sendCustomMessage({
messageText: '{ data:'', description: ''}',
});
参数:
参数
类型
说明
默认值
含义
messageText
string
必填
-
自定义消息内容
ReturnsPromise<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
Returnsvoid

setCurrentMicDevice

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

setCurrentSpeakerDevice

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

getCurrentCameraDevice

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

getCurrentMicDevice

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

getCurrentSpeakerDevice

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

startCameraDeviceTest

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

stopCameraDeviceTest

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

on

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

off

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

getTRTCCloud

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

getTIM

获取 tim 实例,web 端 tim 能力请查看: IM API 文档
const roomEngine = new TUIRoomEngine();
const trtcCloud = roomEngine.getTIM();
ReturnsTIM