TUIRoomEngine
Introduction to TUIRoomEngine
The TUIRoomEngine SDK provides room management, multi-person real-time audio and video interaction, screen sharing, member management, instant chat, and other features.
Installation Method:
// Use npmnpm i @tencentcloud/tuiroom-engine-js --save// Use pnpmpnpm i @tencentcloud/tuiroom-engine-js --save// Use yarnyarn add @tencentcloud/tuiroom-engine-js
TUIRoomEngine API
TUIRoomEngine Static Methods
API | Description |
Listen to the TUIRoomEngine ready event. Note: All methods except TUIRoomEngine.login must be executed after listening to the TUIRoomEngine ready event and the successful execution of the TUIRoomEngine.login method. | |
Log in to TUIRoomEngine | |
Set current user basic information (userName, user profile photo) | |
Get current user basic information (userName, user profile photo) | |
Logout TUIRoomEngine | |
Get TUIRoomEngine instance |
RoomEngine Room Management API
API | Description |
Create Room | |
Enter room | |
Terminate room | |
Exit Room | |
Obtain room information | |
Update room name (only group owner or admin can call the API) | |
Update speech mode (only group owner or admin can call the API). This API is deprecated since version 2.0.0. | |
Update room microphone mode (only group owner or admin can call the API) | |
Update room password (only group owner or admin can call the API) | |
Retrieve the current room user list | |
User's detailed information | |
Set user's custom information. This API needs to be called after entering the room. The host can set their own, admin's, and general user's custom information. The admin can set their own and general user's custom information. General users can only set their own custom information. | |
Set room's custom information. This API can only be called after the anchor enters the room. | |
Retrieve room custom information |
roomEngine Audio and Video API
API | Description |
Set the rendering position for the local stream | |
Local camera video stream capture | |
Turn the local camera off | |
Open the local microphone | |
Turn the local microphone off | |
Set the resolution of the local video | |
Set the resolution mode of the local video stream | |
Set the encoding parameters of the local video | |
Set local audio parameters | |
Start screen sharing | |
Stop screen sharing | |
Start pushing local video stream to remote | |
Stop pushing local video stream to remote | |
Stop pushing local audio stream to remote | |
Start pushing local audio stream to remote | |
Set the remote streaming rendering area | |
Start playing remote user video stream | |
Stop playing remote user video stream | |
Stop remote user audio stream | |
Set remote audio playback volume |
RoomEngine Member Management API
API | Description |
Request remote user to open media device | |
Attendee submits an application to the host to turn on the device | |
Turn off remote user media device | |
Cancel request | |
Reply to remote user's request | |
Change user's role | |
Modify user nickname in the room. This API is supported since v2.5.0. | |
Kick user out of room | |
Disable/enable all users' media devices | |
Forbid/allow all users to send messages | |
Forbid/allow specific user to send messages | |
Set user's custom information |
RoomEngine Seat Management API
API | Description |
Retrieve seat information | |
Retrieve seat info | |
Release microphone position | |
Move a seat | |
Invite others to the stage (only the room host and admin can call this method) | |
Kick others off the mic (only the room host and admin can call this method) | |
Lock a certain seat status (only the room host and admin can call this method) | |
Retrieve the Microphone Request List. This API is supported since v2.1.0 (only the room host and admin can call this method). |
RoomEngine Message Sending API (<0>This Module Is Deprecated since Version 2.0.0. Please Use the Chat Instance to Implement the Chat Module<2>)</2>
API | Description |
Send text message. This API is deprecated since v2.0.0. | |
Send custom messages. This API is deprecated since v2.0.0. |
RoomEngine Device Management API
API | Description |
Retrieve the camera list | |
Retrieve the microphone list | |
Retrieve the speaker device list | |
Set the camera to be used | |
Set the microphone to be used | |
Set the speaker to be used | |
Retrieve the camera in use | |
Retrieve the microphone in use | |
Retrieve the speaker in use | |
Start camera test | |
Stop camera test | |
Start mic test | |
Stop mic test |
RoomEngine Event Monitoring API
RoomEngine Other APIs
API | Description |
Get a TRTCCloud instance | |
Get a TIM instance | |
Obtain the device management module (supported from version 2.1.0) | |
Retrieve the meeting list management module (supported from version 2.5.0) | |
Retrieve the live list management module (supported from version 3.0.0) | |
Retrieve the live stream layout management module (supported from version 3.0.0) | |
Retrieve the Live Connection management module (supported from version 3.2.0) | |
Retrieve the live PK management module (supported from version 3.3.0) | |
Retrieve the in-meeting invitation management module (supported from version 2.6.0) |
API Details
once
Listen to the TUIRoomEngine 'ready' event.
TUIRoomEngine.once('ready', () => {const roomEngine = new TUIRoomEngine();await TUIRoomEngine.login({sdkAppId: 0, // Fill in your applied sdkAppIduserId: '', // Fill in your service correspondence userIduserSig: '', // Fill in the userSig for server or local computing});await roomEngine.createRoom({roomId: '12345', // Fill in your Room ID. Note that the Room ID must be a string typename: 'Test Room', // Fill in your room name. The default is roomId, with a maximum of 30 bytesroomType: TUIRoomType.kConference, // Set the room type to TUIRoomType.kConference});});
login
Note:
Note: In v1.0.0, the API is named TUIRoomEngine.init. In v1.0.1 and later versions, please use TUIRoomEngine.login to sign in to TUIRoomEngine.
To use TUIRoomEngine, you must log in to TUIRoomEngine first. Afterward, you can call the API and other methods of the instance.
// Log in to TUIRoomEngineawait TUIRoomEngine.login({sdkAppId: 0, // Fill in your applied sdkAppIduserId: '', // Fill in your service correspondence userIduserSig: '', // Fill in the userSig for server or local computing});
Parameters:
Parameter | Type | Description | Default Value | Meaning |
sdkAppId | number | Required | - | In the TRTC console, click Application Management > Create Application. After creating a new application, you can obtain the sdkAppId information from the application information. |
userId | string | Required | - | The uid should have a length limit of 32 bytes and only allow a combination of uppercase and lowercase letters (a-zA-Z), digits (0-9), underscore, and hyphen. |
userSig | string | Required | - | userSig signature Compute userSig see UserSig related. |
tim | TIM | optional | - | If you want to use more capabilities of the Instant Messaging SDK while integrating roomEngine, you can create a tim instance and import it into TUIRoomEngine. For tim instance creation, see TIM.create. |
Returns Promise<void>
setSelfInfo
Set current user basic information (userName, user profile photo).
// Set current user userName and user profile photoawait TUIRoomEngine.setSelfInfo({userName: '', // Fill in your new usernameavatarUrl: '', // Fill in your new profile photo url});// Set current user userName, user profile photo and user-customized messageawait TUIRoomEngine.setSelfInfo({userName: '', // Fill in your new usernameavatarUrl: '', // Fill in your new profile photo urlcustomInfo: { // Fill in user custom infoTag_Profile_Custom_Test: 'value1',Tag_Profile_Custom_profile: 'value2',},})
Parameters:
Parameter | Type | Description | Default Value | Meaning |
userName | string | Required | - | Username |
avatarUrl | string | Required | - | user profile photo |
customInfo | object | Optional | - | user-defined profile, supported since v1.3.0 |
Note:
App admin can add new custom profile fields in IM console > User-defined fields. After user-defined fields take effect, users can call the setSelfInfo API to set custom profiles.
Returns Promise<void>
getSelfInfo
Get current user basic information (userName, user profile photo).
// Get current user userName and user profile photoconst loginUserInfo = await TUIRoomEngine.getSelfInfo();
logout
Note:
Note: This API is supported since v1.0.1.
Logout TUIRoomEngine
// Logout TUIRoomEngineawait TUIRoomEngine.logout();
Returns Promise<void>
getInstance
Note:
Note: This API is supported since v2.5.0.
Get the roomEngine instance.
const roomEngine = TUIRoomEngine.getInstance();
Returns <TUIRoomEngine>
createRoom
The host creates a room. The user who calls createRoom becomes the owner. When creating a room, you can set the room ID, room name, room type, whether microphone position control is enabled, whether users are allowed to join, enable audio and video, send messages, and other features.
const roomEngine = TUIRoomEngine.getInstance();await roomEngine.createRoom({roomId: '12345', // Fill in your Room ID. Note that the Room ID must be a string typeroomName: 'Test Room', // Fill in your room name. The default is roomId, with a maximum of 30 bytesroomType: TUIRoomType.kConference, // Set the room type to TUIRoomType.kConferenceisSeatEnabled: false, // Set whether microphone position control is enabledisMicrophoneDisableForAllUser: false, // Set whether to allow joining users to turn on microphoneisCameraDisableForAllUser: false, // Set whether to allow joining users to turn on the cameraisMessageDisableForAllUser: false, // Set whether to allow joining users to send messages});
Parameters:
Parameter | Type | Description | Default Value | Meaning |
roomId | string | Required | - | Room ID, roomId has a length limit of 64 bytes and only supports the following character set: uppercase and lowercase English letters (a-zA-Z) Digits (0-9) space ! # $ % & ( ) + - : ; < = . > ? @ [ ] ^ _ { } | ~ , |
roomName | string | Optional | roomId | Room name, default value roomId, does not allow input of empty string |
roomType | Optional | TUIRoomType.kConference | room type office collaboration, medical consultation, remote conference, education scenarios, roomType is set to TUIRoomType.kConference ecommerce live stream, voice chat room scenario, roomType is set to TUIRoomType.kLive | |
isSeatEnabled | boolean | Optional | false | Whether microphone position control is enabled, disabled by default |
seatMode | Optional | TUISeatMode.kFreeToTake | Mic on mode (takes effect after microphone position control is enabled), default value: TUISeatMode.kFreeToTake Free speaking mode. The audience can join the podium freely without applying. seatMode is set to TUISeatMode.kFreeToTake. Apply for microphone mode. Audience must obtain approval from the room owner or admin before joining the podium. seatMode is set to TUISeatMode.kApplyToTake. | |
isMicrophoneDisableForAllUser | boolean | Optional | false | Whether to mute all is enabled, disabled by default |
isScreenShareDisableForAllUser | boolean | Optional | false | Whether to prohibit screen sharing is enabled, disabled by default (supported since v2.3.0) |
isCameraDisableForAllUser | boolean | Optional | false | Whether to disable camera for all is enabled, disabled by default |
isMessageDisableForAllUser | boolean | Optional | false | Whether members are allowed to send messages, allowed by default |
maxSeatCount | number | Optional | - | Maximum number of microphones When roomType is TUIRoomType.kConference (education and conference scenarios), maxSeatCount has no restrictions. When roomType is TUIRoomType.kLivingRoom (live-streaming scenarios), the maximum limit for maxSeatCount is 16. |
password | string | Optional | '' | room password (supported since v2.5.0) |
Returns Promise<void>
enterRoom
Enter Room API.
const roomEngine = TUIRoomEngine.getInstance();const roomInfo = await roomEngine.enterRoom({roomId: '12345',roomType: TUIRoomType.kConference});
Parameters:
Parameter | Type | Description | Default Value | Meaning |
roomId | string | Required | - | room number |
roomType | Optional | TUIRoomType.kConference | room type (supported since v2.3.0) | |
options | object | Optional | - | Optional parameters for entering a room (supported since v2.5.0) |
options.password | string | Optional | - | Room password |
API response: current room info
destroyRoom
Dissolve Room interface. The room owner must initiate the dismissal. Afterward, the room is not accessible.
const roomEngine = TUIRoomEngine.getInstance();await roomEngine.destroyRoom();
Returns Promise<void>
exitRoom
Leave Room interface. Users can exit the room via exitRoom after executing enterRoom.
const roomEngine = TUIRoomEngine.getInstance();await roomEngine.exitRoom();
Returns Promise<void>
fetchRoomInfo
Obtain room information.
const roomEngine = TUIRoomEngine.getInstance();const roomInfo = roomEngine.fetchRoomInfo();
updateRoomNameByAdmin
Update current room name (only group owner or admin can call the API).
const roomEngine = TUIRoomEngine.getInstance();await roomEngine.createRoom({ roomId: '12345' });await roomEngine.updateRoomNameByAdmin({ roomName: 'new name' });
Parameters:
Parameter | Type | Description | Default Value | Meaning |
roomName | string | Required | - | Update the room name, roomName must not be an empty string |
updateRoomSpeechModeByAdmin
Update speech mode (only group owner or admin can call the API).
Note:
Note: This API is deprecated in v2.0.0; this API is deleted in v2.5.0, please use updateRoomSpeechModeByAdmin.
const roomEngine = TUIRoomEngine.getInstance();await roomEngine.createRoom({ roomId: '12345' });await roomEngine.updateRoomSpeechModeByAdmin({speechMode: TUISpeechMode.kSpeakAfterTakingSeat // Update to speech mode after taking seat});
Parameters:
Parameter | Type | Description | Default Value | Meaning |
speechMode | Required | - | Update room speech mode |
updateRoomSeatModeByAdmin
Update room microphone mode (only group owner or admin can call the API).
const roomEngine = TUIRoomEngine.getInstance();await roomEngine.createRoom({ roomId: '12345' });await roomEngine.updateRoomSeatModeByAdmin({seatMode: TUISeatMode.kApplyToTake, // Update to apply for microphone mode});
Parameters:
Parameter | Type | Description | Default Value | Meaning |
seatMode | Required | - | type of seat |
updateRoomPasswordByAdmin
Update room password (only group owner or admin can call the API).
Note:
Note: This API is supported since v2.5.0.
const roomEngine = TUIRoomEngine.getInstance();await roomEngine.createRoom({ roomId: '12345', password: '123' });await roomEngine.updateRoomPasswordByAdmin({password: '1234', // Update password to 1234});
Parameters:
Parameter | Type | Description | Default Value | Meaning |
password | string | Required | - | Room password |
getUserList
Retrieve the current Room User List. Note that this API can get a maximum of 50 users at once.
const roomEngine = TUIRoomEngine.getInstance();const userList = [];let result;let nextSequence = 0;do {result = await roomEngine.getUserList({ nextSequence });userList.push(...result.userInfoList);nextSequence = result.nextSequence;} while (result.nextSequence !== 0)
Parameters:
Parameter | Type | Description | Default Value | Meaning |
nextSequence | number | Optional | 0 | Offset. The default starts from 0 when fetching users. |
Returns:Promise<Array> result
result.nextSequence The offset for the next pull of group users. If result.nextSequence is 0, it signifies the userList has been fully pulled.
result.userInfoList The userList pulled this time
getUserInfo
User's detailed information.
const roomEngine = TUIRoomEngine.getInstance();const userList = [];const userInfo = await roomEngine.getUserInfo({userId: 'user_12345',});
Parameters:
Parameter | Type | Description | Default Value | Meaning |
userId | string | Required | - | Get user's detailed information by userId |
API response: user information of the specified user
setRoomMetadataByAdmin
Set room custom information. This API can only be called after the anchor enters the room.
const roomEngine = TUIRoomEngine.getInstance();await roomEngine.setRoomMetadataByAdmin({metadata: JSON.stringify({key1: "value1", key2: "value2"}), // value can only be string});
Parameters:
Parameter | Type | Description | Default Value | Description |
options | object | Required | - | Set room metadata |
options.metadata | string | Required | - | Custom Information |
Returns:Promise<void>
getRoomMetadata
Set room custom information. This API can only be called after the anchor enters the room.
const roomEngine = TUIRoomEngine.getInstance();const result = await roomEngine.getRoomMetadata({keys: ["key1", "key2"]});
Parameters:
Parameter | Type | Description | Default Value | Description |
options | object | Required | - | Retrieve room metadata |
options.metadata | Array<string> | Required | - | Array of custom information keys |
Returns:Promise<any>
setLocalVideoView
Set the rendering position for the local video stream.
const roomEngine = TUIRoomEngine.getInstance();// Set the playback area of the local camera stream to the div element with id 'preview-camera'await roomEngine.setLocalVideoView({view: 'preview-camera',});
Parameters:
Parameter | Type | Description | Default Value | Meaning |
view | string | Required | - | id of the div element for stream rendering corresponding to streamType |
Returns:Promise<void>
Note:
Since v1.6.1, setLocalVideoView just applies the view parameter to set the playback container for the local video stream.
openLocalCamera
Turn on local camera, start video stream acquisition.
const roomEngine = TUIRoomEngine.getInstance();await roomEngine.setLocalVideoView({streamType: TUIVideoStreamType.kCameraStream,view: 'preview-camera',});// case 1: turn on the camera on PCawait roomEngine.openLocalCamera();// case 2: turn on the camera on mobile terminal for video previewawait roomEngine.openLocalCamera({ isFrontCamera: true });// case 3: turn on the rear-facing camera on mobile terminal for video previewawait roomEngine.openLocalCamera({ isFrontCamera: false });
Parameters:
Parameter | Type | Description | Default Value | Meaning |
isFrontCamera | boolean | Optional | - | Set the default camera for local video preview on mobile terminal, this parameter only applies to mobile terminal This parameter is supported since v1.3.1. |
Returns:Promise<void>
closeLocalCamera
Turn the local camera off.
const roomEngine = TUIRoomEngine.getInstance();await roomEngine.closeLocalCamera();
Returns:Promise<void>
openLocalMicrophone
Open local microphone, start collecting audio stream.
const roomEngine = TUIRoomEngine.getInstance();await roomEngine.openLocalMicrophone();
Returns:Promise<void>
closeLocalMicrophone
Turn the local microphone off.
const roomEngine = TUIRoomEngine.getInstance();await roomEngine.closeLocalMicrophone();
Returns:Promise<void>
updateVideoQuality
Set the encoding parameters for the local video stream, defaulting to TUIVideoProfile.kVideoQuality_720P.
const roomEngine = TUIRoomEngine.getInstance();await roomEngine.updateVideoQuality({quality: TUIVideoQuality.kVideoQuality_540p,});
Parameters:
Parameter | Type | Description | Default Value | Meaning |
quality | Required | - | Clear TUIVideoProfile.kVideoQuality_360P Standard TUIVideoProfile.kVideoQuality_540P High-definition TUIVideoProfile.kVideoQuality_720P Ultra HD TUIVideoProfile.kVideoQuality_1080P |
Returns:Promise<void>
setVideoResolutionMode
Set the resolution mode of the local video stream, defaulting to TUIResolutionMode.kResolutionMode_Landscape.
const roomEngine = TUIRoomEngine.getInstance();await roomEngine.setVideoResolutionMode({type: TUIVideoStreamType.kCameraStream,resolutionMode: TUIResolutionMode.kResolutionMode_Landscape,});
Parameters:
Parameter | Type | Description | Default Value | Meaning |
streamType | Required | - | Local stream type | |
resolutionMode | Required | TUIResolutionMode.kResolutionMode_Landscape | Resolution mode |
Returns:Promise<void>
Note:
Note: This API is supported since v1.5.0.
updateVideoQualityEx
Set the encoding parameters of the local video stream
const roomEngine = TUIRoomEngine.getInstance();await roomEngine.updateVideoQualityEx({streamType: TUIVideoStreamType.kCameraStream,encoderParams: {videoResolution: TUIVideoQuality.kVideoQuality_720p,fps: 15,bitrate: 2000,resolutionMode: TUIResolutionMode.kResolutionMode_Landscape,}});
Parameters:
Parameter | Type | Description | Default Value | Meaning |
streamType | Required | - | Local stream type | |
encoderParams | Required | - | Encoding parameters |
Note:
Note: This API is supported since v1.5.0.
updateAudioQuality
Set local audio parameters.
Note:
This method needs to be set before openLocalMicrophone, otherwise it will not take effect.
const roomEngine = TUIRoomEngine.getInstance();await roomEngine.updateAudioQuality({quality: TUIAudioQuality.kAudioProfileMusic,});
Parameters:
Parameter | Type | Description | Default Value | Meaning |
audioProfile | Required | - | TUIAudioQuality.kAudioProfileSpeech: language mode; sampling rate: 16k TUIAudioQuality.kAudioProfileDefault: standard mode (or default mode); sampling rate: 48k TUIAudioQuality.kAudioProfileMusic: music mode; sampling rate: 48k |
Returns:Promise<void>
startScreenSharing
Start screen sharing.
const roomEngine = TUIRoomEngine.getInstance();// example 1: Start screen sharingawait roomEngine.startScreenSharing();// example 2: Start screen sharing (with system audio collection)await roomEngine.startScreenSharing({ screenAudio: true });Start screen sharing and preview locallyawait roomEngine.startScreenSharing({ view: 'screen-preview' });
Parameters:
Parameter | Type | Description | Default Value | Meaning |
screenAudio | boolean | Optional | false | Is sharing system audio optional for web screen sharing? The default value of screenAudio is false. |
view | string | Optional | - | The id of the DOM element for local preview screen sharing. This parameter is supported since v1.6.1. |
Returns:Promise<void>
stopScreenSharing
Stop screen sharing.
const roomEngine = TUIRoomEngine.getInstance();await roomEngine.stopScreenSharing();
Returns:Promise<void>
startPushLocalVideo
After entering the room, the local video stream is pushed to the remote end by default. This API is used to push the local video stream to the remote end again after stopping streaming.
const roomEngine = TUIRoomEngine.getInstance();await roomEngine.startPushLocalVideo();
Returns:Promise<void>
stopPushLocalVideo
Stop pushing local video stream to remote.
const roomEngine = TUIRoomEngine.getInstance();await roomEngine.stopPushLocalVideo();
Returns:Promise<void>
startPushLocalAudio
After entering the room, the local audio stream is pushed to the remote end by default. This API is used to push the local audio stream to the remote end again after stopping streaming.
const roomEngine = TUIRoomEngine.getInstance();await roomEngine.startPushLocalAudio();
Returns:Promise<void>
Note:
Note: This API is deprecated in version 1.5.0. Please use the muteLocalAudio method to replace it.
stopPushLocalAudio
Stop pushing local audio stream to remote.
const roomEngine = TUIRoomEngine.getInstance();await roomEngine.stopPushLocalAudio();
Returns:Promise<void>
Note:
Note: This API is deprecated in version 1.5.0. Please use the muteLocalAudio method to replace it.
muteLocalAudio
Stop pushing local audio stream to remote.
const roomEngine = TUIRoomEngine.getInstance();await roomEngine.muteLocalAudio();
Returns:Promise<void>
Note:
Note: This API is supported since v1.5.1.
unmuteLocalAudio
Start pushing local audio stream to remote.
const roomEngine = TUIRoomEngine.getInstance();await roomEngine.unmuteLocalAudio();
Returns:Promise<void>
Note:
Note: This API is supported since v1.5.1.
setRemoteVideoView
Set the remote streaming rendering area.
const roomEngine = TUIRoomEngine.getInstance();// Set the remote user video stream to play in the area with id 'remote_preview_camera'await roomEngine.setRemoteVideoView({userId: 'user_1234',streamType: TUIVideoStreamType.kCameraStream,view: 'remote_preview_camera',});// Set the remote user screen sharing stream to play in the area with id 'remote_preview_screen'await roomEngine.setRemoteVideoView({userId: 'user_1234',streamType: TUIVideoStreamType.kScreenStream,view: 'remote_preview_screen',});
Parameters:
Parameter | Type | Description | Default Value | Meaning |
userId | string | Required | - | User ID |
streamType | Required | - | User stream type | |
view | string | Required | - | ID of the div element for remote user stream playback |
Returns:Promise<void>
startPlayRemoteVideo
Start playing remote user video stream.
const roomEngine = TUIRoomEngine.getInstance();await roomEngine.startPlayRemoteVideo({userId: 'user_1234',streamType: TUIVideoStreamType.kCameraStream,});
Parameters:
Parameter | Type | Description | Default Value | Meaning |
userId | string | Required | - | User ID |
streamType | Required | - | User stream type TUIVideoStreamType.kCameraStream video stream TUIVideoStreamType.kScreenStream screen sharing stream TUIVideoStreamType.kCameraStreamLow low-quality video stream |
Returns:Promise<void>
stopPlayRemoteVideo
Stop playing remote user video stream.
const roomEngine = TUIRoomEngine.getInstance();await roomEngine.stopPlayRemoteVideo({userId: 'user_1234',streamType: TUIVideoStreamType.kCameraStream,});
Parameters:
Parameter | Type | Description | Default Value | Meaning |
userId | string | Required | - | User ID |
streamType | Required | - | User stream type TUIVideoStreamType.kCameraStream video stream TUIVideoStreamType.kScreenStream screen sharing stream TUIVideoStreamType.kCameraStreamLow low-quality video stream |
Returns:Promise<void>
muteRemoteAudioStream
Stop remote user audio stream.
const roomEngine = TUIRoomEngine.getInstance();await roomEngine.muteRemoteAudioStream({userId: 'user_1234',isMute: true,});
Parameter | Type | Description | Default Value | Meaning |
userId | string | Required | - | User ID |
isMute | boolean | Required | - | Whether to stop remote user audio |
setAudioPlayoutVolume
Set remote audio playback volume
const roomEngine = TUIRoomEngine.getInstance();await roomEngine.setAudioPlayoutVolume({volume: 100,});
Parameter | Type | Description | Default Value | Meaning |
volume | number | Required | - | Remote audio playback volume, value ranges from 0 to 150 |
openRemoteDeviceByAdmin
Request remote user to open media device.
const roomEngine = TUIRoomEngine.getInstance();const requestId = roomEngine.openRemoteDeviceByAdmin({userId: 'user_1234',device: TUIMediaDevice.kMicrophone //Request to the device as microphonetimeout: 0,requestCallback: ({ requestCallbackType, requestId, userId, code, message }) => {switch (requestCallbackType) {case TUIRequestCallbackType.kRequestAccepted:// Request acceptedbreak;case TUIRequestCallbackType.kRequestRejected:// Request rejectedbreak;case TUIRequestCallbackType.kRequestCancelled:// Request canceledbreak;case TUIRequestCallbackType.kRequestTimeout:// Request timeoutbreak;case TUIRequestCallbackType.kRequestError:// Request errorbreak;default:break;}},});
Parameters:
Parameter | Type | Description | Default Value | Meaning |
userId | string | Required | - | User ID |
device | Required | - | Media device type (camera/microphone/screen sharing) | |
timeout | number | Required | - | Timeout period. If timeout is set to 0, there is no timeout. |
requestCallback | Function | Optional | empty function | Request callback, used to notify the initiator of request acceptance/rejection/cancellation/timeout/error callback |
Returns:Promise<string> requestId
The API returns a requestId. User can use this requestId to call the cancelRequest API to cancel the request.
Note:
In v1.0.2 and later versions, the requestId data type in the API response is string. In v1.0.0 and v1.0.1, the requestId data type in the API response is number.
applyToAdminToOpenLocalDevice
Attendee submits an application to the host to turn on the device.
const roomEngine = TUIRoomEngine.getInstance();const requestId = roomEngine.applyToAdminToOpenLocalDevice({device: TUIMediaDevice.kMicrophone //Request to the device as microphonetimeout: 0,requestCallback: ({ requestCallbackType, requestId, userId, code, message }) => {switch (requestCallbackType) {case TUIRequestCallbackType.kRequestAccepted:// Request acceptedbreak;case TUIRequestCallbackType.kRequestRejected:// Request rejectedbreak;case TUIRequestCallbackType.kRequestCancelled:// Request canceledbreak;case TUIRequestCallbackType.kRequestTimeout:// Request timeoutbreak;case TUIRequestCallbackType.kRequestError:// Request errorbreak;default:break;}},});
Parameters:
Parameter | Type | Description | Default Value | Meaning |
device | Required | - | Media device type (camera/microphone/screen sharing) | |
timeout | number | Required | - | Timeout period. If timeout is set to 0, there is no timeout. |
requestCallback | Function | Optional | empty function | Request callback, used to notify the initiator of request acceptance/rejection/cancellation/timeout/error callback |
Returns:Promise<string> requestId
The API returns a requestId. User can use this requestId to call the cancelRequest API to cancel the request.
closeRemoteDeviceByAdmin
Turn off remote user media device.
const roomEngine = TUIRoomEngine.getInstance();await roomEngine.closeRemoteDeviceByAdmin({userId: 'user_1234',device: TUIMediaDevice.kMicrophone, //Turn off the microphone});
Parameters:
Parameter | Type | Description | Default Value | Meaning |
userId | string | Required | - | User ID |
device | Required | - | Media device type (camera/microphone/screen sharing) |
Returns:Promise<void>
cancelRequest
Cancel request
const roomEngine = TUIRoomEngine.getInstance();await roomEngine.cancelRequest({requestId: '', // please use actual requestId});
Parameters:
Parameter | Type | Description | Default Value | Meaning |
requestId | string | Required | - | Request ID. |
Returns:Promise<void>
Note:
Note: In v1.0.2 and later versions, the requestId parameter type accepted by this API is string. In v1.0.0 and v1.0.1, the requestId parameter type accepted by this API is number.
responseRemoteRequest
Reply to remote user's request.
const roomEngine = TUIRoomEngine.getInstance();// Grant the remote requestawait roomEngine.responseRemoteRequest({requestId: '', // please use actual requestIdagree: true,});// Deny the remote requestawait roomEngine.responseRemoteRequest({requestId: '', // please use actual requestIdagree: false,});
Parameters:
Parameter | Type | Description | Default Value | Meaning |
requestId | string | Required | - | Request ID. |
agree | boolean | Required | - | Whether to agree |
Returns:Promise<void>
Note:
Note: In v1.0.2 and later versions, the requestId parameter type accepted by this API is string. In v1.0.0 and v1.0.1, the requestId parameter type accepted by this API is number.
disableDeviceForAllUserByAdmin
Forbid/allow all users to enable media devices (this API is unavailable for room owners and admins).
const roomEngine = TUIRoomEngine.getInstance();// Example 1: Forbid all users to turn on microphoneawait roomEngine.disableDeviceForAllUserByAdmin({device: TUIMediaDevice.kMicrophone,isDisable: true,})// Example 2: Allow all users to turn on microphoneawait roomEngine.disableDeviceForAllUserByAdmin({device: TUIMediaDevice.kMicrophone,isDisable: false,})
Parameters:
Parameter | Type | Description | Default Value | Meaning |
device | Required | - | Disabled media device type (camera/microphone/screen sharing) | |
isDisable | boolean | Required | - | Forbidden |
Returns:Promise<void>
disableSendingMessageForAllUser
Whether all users are allowed to send messages (this API is unavailable for room owners and admins).
const roomEngine = TUIRoomEngine.getInstance();await roomEngine.disableSendingMessageForAllUser({isDisable: true,});
Parameters:
Parameter | Type | Description | Default Value | Meaning |
isDisable | boolean | Required | - | Whether is disabled |
Returns:Promise<void>
disableSendingMessageByAdmin
Is the specific user allowed to send messages.
const roomEngine = TUIRoomEngine.getInstance();await roomEngine.disableSendingMessageByAdmin({userId: 'user_1234',isDisable: true,});
Parameters:
Parameter | Type | Description | Default Value | Meaning |
userId | string | Required | - | User ID |
isDisable | boolean | Required | - | Whether is disabled |
Returns:Promise<void>
changeUserRole
Alter the user's role (only the host can call this API).
const roomEngine = TUIRoomEngine.getInstance();// Transfer the room to user user_1234await roomEngine.changeUserRole({userId: 'user_1234',role: TUIRole.kRoomOwner,});// Set user user_1234 as room administratorawait roomEngine.changeUserRole({userId: 'user_1234',userRole: TUIRole.kAdministrator,});
Parameters:
Parameter | Type | Description | Default Value | Meaning |
userId | string | Required | - | User ID |
userRole | Required | - | User Role host TUIRole.kRoomOwner admin TUIRole.kAdministrator ordinary member TUIRole.kGeneralUser |
Returns:Promise<void>
changeUserNameCard
Modify Room User Name. Ordinary members can only modify their own Room User Name; admins can modify their own and ordinary members' Room User Name; hosts can modify their own, admins', and ordinary members' Room User Name.
Note:
Note: This API is supported since v2.5.0.
const roomEngine = TUIRoomEngine.getInstance();await roomEngine.changeUserNameCard({userId: 'user_1234',nameCard: 'jack',});
Parameters:
Parameter | Type | Description | Default Value | Meaning |
userId | string | Required | - | User ID |
nameCard | string | Required | - | Users in the room name |
Returns:Promise<void>
setCustomInfoForUser
The host can configure custom information for self, admin, and regular user accounts.
The admin can set custom information for self and regular user accounts.
Regular user accounts can only set their own custom information.
const roomEngine = TUIRoomEngine.getInstance();await roomEngine.setCustomInfoForUser({userId: 'user_12345',customInfo: {'key1': 'value1','key2': 'value2',}});
Returns:Promise<void>
kickRemoteUserOutOfRoom
Kick user out of room (Only host and admin can call this API).
const roomEngine = TUIRoomEngine.getInstance();await roomEngine.kickRemoteUserOutOfRoom({userId: 'user_1234',});
Parameters:
Parameter | Type | Description | Default Value | Meaning |
userId | string | Required | - | User ID |
Returns:Promise<void>
getSeatList
Get seat list.
const roomEngine = TUIRoomEngine.getInstance();const seatList = await roomEngine.getSeatList();
Returns:Promise<TUISeatInfo[]> seatList
SeatList is the seat list of the current room
takeSeat
Mic-off users can call takeSeat to become on-mic users. Only on-mic users can publish local audio/video streams.
When roomInfo.roomType is TUIRoomType.kConference and roomInfo.seatMode is TUISeatMode.kApplyToTake, general users have to wait for host/admin approval after consent to become on-mic users by calling the takeSeat method.
When roomInfo.roomType is TUIRoomType.kLivingRoom and roomInfo.seatMode is TUISeatMode.kFreeToTake, general users become on-mic users upon success of calling the takeSeat method.
Host/admin becomes on-mic user upon success of calling takeSeat.
Changes to on-mic users are notified to all users via TUIRoomEvents.onSeatListChanged.
const roomEngine = TUIRoomEngine.getInstance();// Scenario 1: Host/Admin joins the stage// Scenario 2: When roomInfo.roomType is TUIRoomType.kConference// When roomInfo.seatMode is TUISeatMode.kFreeToTake, general users can go on-micawait roomEngine.takeSeat({seatIndex: -1,timeout: 0,});// Scenario: When roomInfo.seatMode is TUISeatMode.kApplyToTake, general users can go on-micconst requestId = await roomEngine.instance?.takeSeat({seatIndex: -1,timeout: 0,requestCallback: ({ requestCallbackType, requestId, userId, code, message }) => {switch (requestCallbackType) {case TUIRequestCallbackType.kRequestAccepted:// Request acceptedbreak;case TUIRequestCallbackType.kRequestRejected:// Request rejectedbreak;case TUIRequestCallbackType.kRequestCancelled:// Request canceledbreak;case TUIRequestCallbackType.kRequestTimeout:// Request timeoutbreak;case TUIRequestCallbackType.kRequestError:// Request errorbreak;default:break;}},});
Parameters:
Parameter | Type | Description | Default Value | Meaning |
seatIndex | number | Required | - | Seat index, set to -1 when no serial number is available |
timeout | number | Required | - | Timeout period. If timeout is set to 0, there is no timeout. |
requestCallback | Function | Optional | Empty function | Request callback, used to notify the initiator of request acceptance/rejection/cancellation/timeout/error callback |
Returns:Promise<string> requestId
When roomInfo.seatMode is TUISeatMode.kApplyToTake, general users call this API and get a requestId. The user can use this requestId to call the cancelRequest API to cancel the request to speak.
Note:
In v1.0.2 and later versions, the requestId data type in the API response is string. In v1.0.0 and v1.0.1, the requestId data type in the API response is number.
leaveSeat
Release microphone position.
const roomEngine = TUIRoomEngine.getInstance();await roomEngine.leaveSeat();
Returns:Promise<void>
moveToSeat
Move a seat
const roomEngine = TUIRoomEngine.getInstance();await roomEngine.moveToSeat({ targetSeatIndex: 1 });
Parameters:
Parameter | Type | Description | Default Value | Meaning |
targetSeatIndex | number | Required | - | Move to target seat index. You will be on this seat after moving. |
Returns:Promise<void>
takeUserOnSeatByAdmin
Invite others to the stage.
const roomEngine = TUIRoomEngine.getInstance();const requestId = roomEngine.takeUserOnSeatByAdmin({seatIndex: 0,userId: 'user_1234',timeout: 0,requestCallback: ({ requestCallbackType, requestId, userId, code, message }) => {switch (requestCallbackType) {case TUIRequestCallbackType.kRequestAccepted:// Request acceptedbreak;case TUIRequestCallbackType.kRequestRejected:// Request rejectedbreak;case TUIRequestCallbackType.kRequestCancelled:// Request canceledbreak;case TUIRequestCallbackType.kRequestTimeout:// Request timeoutbreak;case TUIRequestCallbackType.kRequestError:// Request errorbreak;default:break;}},});
Parameters:
Parameter | Type | Description | Default Value | Meaning |
seatIndex | number | Required | - | Seat index |
userId | string | Required | - | User ID |
timeout | number | Required | - | Timeout period. If set to 0, there is no timeout. |
requestCallback | Function | Optional | Empty function | Request callback, used to notify the initiator of request acceptance/rejection/cancellation/timeout/error callback |
Returns:Promise<string> requestId
The API returns a requestId. User can use this requestId to call the cancelRequest API to cancel the request.
Note:
In v1.0.2 and later versions, the requestId data type in the API response is string. In v1.0.0 and v1.0.1, the requestId data type in the API response is number.
kickUserOffSeatByAdmin
Ask others to leave the stage.
const roomEngine = TUIRoomEngine.getInstance();const requestId = await roomEngine.kickUserOffSeatByAdmin({seatIndex: 0,userId: 'user_1234',});
Parameters:
Parameter | Type | Description | Default Value | Meaning |
seatIndex | number | Required | - | Seat index |
userId | string | Required | - | User ID |
Returns:Promise<void>
lockSeatByAdmin
Lock a certain seat status (only the room host and admin can call this method).
const roomEngine = TUIRoomEngine.getInstance();await roomEngine.lockSeatByAdmin({seatIndex: 0,lockParams: {lockSeat: true,lockVideo: true,lockAudio: true,},});
Parameters:
Parameter | Type | Description | Default Value | Meaning |
seatIndex | number | Required | - | Seat index |
lockParams | Required | - | Microphone Mute Parameters |
Returns:Promise<void>
getSeatApplicationList
Get the request list of users applying for microphone in the room. This API is supported since v2.1.0 (only the room host and admin can call this method).
const roomEngine = TUIRoomEngine.getInstance();const applicationList = await roomEngine.getSeatApplicationList();
Returns:Promise<TUIRequest[]>
sendTextMessage
Send text messages.
const roomEngine = TUIRoomEngine.getInstance();await roomEngine.sendTextMessage({messageText: 'hello, everyone',});
Parameters:
Parameter | Type | Description | Default Value | Meaning |
messageText | string | Required | - | Text message content |
Returns:Promise<void>
Note:
This API is deprecated since version 2.0.0. Please use the getTIM method to get the TIM instance send message.
sendCustomMessage
Send custom messages.
const roomEngine = TUIRoomEngine.getInstance();await roomEngine.sendCustomMessage({messageText: '{ data:'', description: ''}',});
Parameters:
Parameter | Type | Description | Default Value | Meaning |
messageText | string | Required | - | Custom message content |
Returns:Promise<void>
Note:
This API is deprecated since version 2.0.0. Please use the getTIM method to get the TIM instance send message.
switchCamera
Switch front and rear cameras. This API is applicable to mobile terminals.
Note:
Note: This API is supported since v1.3.1.
const roomEngine = TUIRoomEngine.getInstance();// Switch to front-facing camera on mobile terminalawait roomEngine.switchCamera({ isFrontCamera: true });// Switch to rear-facing camera on mobile terminalawait roomEngine.switchCamera({ isFrontCamera: false });
Parameters:
Parameter | Type | Description | Default Value | Meaning |
isFrontCamera | boolean | Required | - | Whether to switch to front camera |
Returns:Promise<void>
getCameraDevicesList
Retrieve the camera list.
const roomEngine = TUIRoomEngine.getInstance();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);}
getMicDevicesList
Retrieve the microphone list.
const roomEngine = TUIRoomEngine.getInstance();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);}
getSpeakerDevicesList
Retrieve the speaker device list.
const roomEngine = TUIRoomEngine.getInstance();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);}
setCurrentCameraDevice
Set the camera to be used.
const roomEngine = TUIRoomEngine.getInstance();await roomEngine.setCurrentCameraDevice({ deviceId: '' });
Parameters:
Parameter | Type | Description | Default Value | Meaning |
deviceId | string | Required | - | Device ID obtained from getCameraDevicesList |
Returns:void
setCurrentMicDevice
Set the microphone to be used.
const roomEngine = TUIRoomEngine.getInstance();await roomEngine.setCurrentMicDevice({ deviceId: '' });
Parameters:
Parameter | Type | Description | Default Value | Meaning |
deviceId | string | Required | - | Device ID obtained from getMicDevicesList |
Returns:void
setCurrentSpeakerDevice
Set the speaker to be used.
const roomEngine = TUIRoomEngine.getInstance();await roomEngine.setCurrentSpeakerDevice({ deviceId: '' });
Parameters:
Parameter | Type | Description | Default Value | Meaning |
deviceId | string | Required | - | Device ID obtained from getSpeakerDevicesList |
Returns:void
getCurrentCameraDevice
Retrieve the camera in use.
const roomEngine = TUIRoomEngine.getInstance();const currentCameraDevice = roomEngine.getCurrentCameraDevice();
Device information, including device ID and device name.
getCurrentMicDevice
Retrieve the microphone in use.
const roomEngine = TUIRoomEngine.getInstance();const currentMicDevice = roomEngine.getCurrentMicDevice();
Device information, including device ID and device name.
getCurrentSpeakerDevice
Retrieve the speaker in use.
const roomEngine = TUIRoomEngine.getInstance();const currentSpeakerDevice = roomEngine.getCurrentSpeakerDevice();
Device information, including device ID and device name.
startCameraDeviceTest
Start camera test.
const roomEngine = TUIRoomEngine.getInstance();await roomEngine.startCameraDeviceTest({ view: 'test-preview' });
Parameters:
Parameter | Type | Description | Default Value | Meaning |
view | string | Required | - | Display the video area for camera test. The passed in view is the ID of the div element hosting the video preview. |
Returns:Promise<void>
stopCameraDeviceTest
Stop camera test.
const roomEngine = TUIRoomEngine.getInstance();await roomEngine.stopCameraDeviceTest();
Returns:Promise<void>
startMicDeviceTest
Start mic test
const roomEngine = TUIRoomEngine.getInstance();await roomEngine.startMicDeviceTest({interval: 200});
Parameters:
Parameter | Type | Description | Default Value | Meaning |
interval | number | Required | - | Microphone Volume callback time (ms) |
Returns:Promise<void>
stopMicDeviceTest
Stop mic test
const roomEngine = TUIRoomEngine.getInstance();await roomEngine.stopMicDeviceTest();
Returns:Promise<void>
on
Listen to the roomEngine event.
const roomEngine = TUIRoomEngine.getInstance();roomEngine.on(event, func);
Parameters:
Parameter | Type | Description | Default Value | Meaning |
event | Required | - | List of TUIRoomEngine Events | |
func | Function | Required | - | Event callback function |
Returns:void
off
Cancel listening to the roomEngine event.
const roomEngine = TUIRoomEngine.getInstance();roomEngine.off(event, func);
Parameters:
Parameter | Type | Description | Default Value | Meaning |
event | Required | - | List of TUIRoomEngine Events | |
func | Function | Required | - | Event callback function |
Returns:void
getTRTCCloud
const roomEngine = TUIRoomEngine.getInstance();const trtcCloud = roomEngine.getTRTCCloud();
Returns:TRTCCloud
getTIM
const roomEngine = TUIRoomEngine.getInstance();const tim = roomEngine.getTIM();
Note:
Note: Since version 1.6.0, the IM SDK has been upgraded to v3. Check the IM API documentation.
getMediaDeviceManager
Obtain the device management module
const roomEngine = TUIRoomEngine.getInstance();const deviceManager = roomEngine.getMediaDeviceManager();
getConferenceListManager
Retrieve the meeting list module
const roomEngine = TUIRoomEngine.getInstance();const conferenceListManager = roomEngine.getConferenceListManager();
getLiveListManager
Retrieve the live list module
const roomEngine = TUIRoomEngine.getInstance();const liveListManager = roomEngine.getLiveListManager();
getLiveLayoutManager
Retrieve the live stream layout module
const roomEngine = TUIRoomEngine.getInstance();const liveLayoutManager = roomEngine.getLiveLayoutManager();
getLiveConnectionManager
Retrieve the Live Connection module
const roomEngine = TUIRoomEngine.getInstance();const liveConnectionManager = roomEngine.getLiveConnectionManager();
getLiveBattleManager
Retrieve the live PK module
const roomEngine = TUIRoomEngine.getInstance();const liveBattleManager = roomEngine.getLiveBattleManager();
getConferenceInvitationManager
Retrieve the meeting invitation module
const roomEngine = TUIRoomEngine.getInstance();const conferenceInvitationManager = roomEngine.getConferenceInvitationManager();