Room Management Class

Room Management Category（Room）

Room

-This method instantiates an object of the room management class. Almost all operations within the room are controlled by this object.

• Method example

var room = TK.Room()

Initial setup

init(appKey, options) ->

• This method is used to initialize the Room object Note: Other methods of the room can only be called after the init method is successfully invoked. Suggestion: It is recommended to complete device detection before calling the init method, as the init method will select a device from the device list after it is called, and the availability of this device cannot be guaranteed.

Parameter name	Required	Type	Description
appKey	Yes	String	Corporate domain
options	No	Object	Initialization configuration items. The detailed optional configurations are as follows

• Options

Parameter name	Type	Description
tk_multistream	Boolean	Whether to enable multi-video mode, default is false
checkDevice	{ video?: boolean, audio?: boolean }	Whether to check audio and video devices, by default both audio and video devices are checked

• Method example

await room.init(appKey, options = {}).catch(err => {})

uninit()

• This method is used to reset the Room object to its uninitialized state
• Method example

room.uninit()

checkInit()

• This method is used to check the initialization status of the room
• Method example

var isInit = room.checkInit()

Room entry and exit and room information

joinroom(roomOption, userOption) ->

• This method is used to join a room that has already been created. It should be the first method to be called in the Room class.

Parameter name	Required	Type	Description
roomOption	Yes	Object	The basic parameters required to join the room
userOption	Yes	Object	User attributes

• roomOption

Parameter name	Type	Description
roomId	String	Room ID
userPwd	String	String

• userOption

Parameter name	Type	Description
userId	String	User id
role	Number	User identity
nickname	String	User nickname

• Method example

await room.joinroom( {roomId: '123', userPwd: 'qwer' }, { userId: '1', role: 2, nickname: 'test' }).catch(err => {})

joinRoomEx(roomOption, userOption) ->

• This method is used to join a room that has already been created. It should be the first method to be called in the Room class.

Parameter name	Required	Type	Description
roomOption	Yes	Object	The basic parameters required to join the room
userOption	Yes	Object	User-defined attributes

• roomJsonOptions

Parameter name	Type	Description
roomId	String	Room ID
tk_token	String	tk signature
userPwd	String	Room password

• userJsonOptions

Parameter name	Type	Description
userId	String	User id
role	Number	User identity
nickname	String	User nickname

• Method example

await room.joinRoomEx( {roomId: '123', userPwd: 'qwer', tk_ttoken: 'asdfzxc' }, { userId: '1', role: 2, nickname: 'test' }).catch(err => {})

leaveroom ()

• This method is used to leave the room. After leaving the room, all audio and video calls will be terminated.
• Method example

room.leaveroom()

getRoomProperties()

• This method is used to get the room information. This information includes all the configurations made when booking the room.
• Method example

var property = room.getRoomProperties()

- Return value: The interface returns an object. Only some commonly used room attributes within the object are listed below

Parameter name	Type	Description
serial	String	Room number
roomname	String	Room name
companyid	String	Company ID
maxvideo	Number	Maximum number of video streams supported by the room
videowidth	String	Maximum video resolution width
videoheight	String	Maximum video resolution height

User information

getMySelf()

• This method is used to get your own user object. Note: If the joinRoom method is not successfully invoked (i.e., the TK.EVENT_TYPE.roomConnected event is not received), an empty object will be returned
• Method example

var self = room.getMySelf();

getUser(userId)

• This method is used to get the specified RoomUser object Note: When used in a large room (i.e., a large-scale room), this interface can only retrieve users who have already gone on stage (i.e., users who have published audio/video) and special users (such as teachers/teaching assistants). Therefore, in the large room mode, it is recommended to use this interface only to operate on users who have gone on stage

Parameter name	Required	Type	Description
userId	Yes	String	The ID of the user to be retrieved

• Method example

var user = room.getUser("1");

getUsers()

• This method returns a collection of all user objects in the room, and the return value type is Object. Note: When used in a large room (i.e., a large-scale room), this interface can only retrieve users who have already gone on stage (i.e., users who have published audio/video) and special users (such as teachers/teaching assistants). Therefore, in the large room mode, it is recommended to use this interface only to operate on users who have gone on stage
• Method example

var users = room.getUsers();

- Return value

Type	Description
Object	A user collection object, in the format of userid: user

getRoomUsers({ start, max, roles, search, order }) ->

• This method is used to get the user list. Note: This interface is recommended for use only in large rooms (i.e., large-scale rooms). In non-large room modes, it is suggested to use the getUsers interface instead

Parameter name	Required	Type	Description
start	NO	Number	Start position, default is 0
max	NO	Number	Maximum number of items to retrieve, default is 200
roles	NO	Array	Role list, default is all roles. For role values, please refer to Room Roles
search	NO	String	Nickname search content, default is "". Note: Here only user nicknames are searched, and it is a fuzzy search
order	NO	Array	Sorting rules, detailed rules are described below

• Supplementary explanation of the order rule:
• Use 'asc' for ascending order and 'desc' for descending order
• A maximum of three sorting rules can be applied. Any additional rules beyond this limit will not take effect. The default sorting rule is based on the time of joining in ascending order (i.e., order: [{ts: 'asc'}])
• The rules that appear earlier take precedence, meaning that the lower the index of the rule in the order array, the higher the sorting priority
• Method example

const users = await room.getRoomUsers({ start: 0, max: 100, roles: [0,2] , search: '', order: 'asc' }).catch(err => {})

getRoomUserNum({ roles, search }) ->

• This method obtains the total number of users

Parameter name	Required	Type	Description
roles	No	Array	Role list, default is all roles. For role values, please refer to Room Roles
search	No	String	Nickname search content, default is "". Note: Here only user nicknames are searched, and it is a fuzzy search

• Method example

const num = await room.getRoomUserNum({ roles: [0,2] , search: '' }).catch(err => {}})

getUserList({ start, max, roles, search }) ->

• This method returns the current list of users and the total number in the room

Parameter name	Required	Type	Description
options	No	Object	Query conditions, parameters, and descriptions are as follows

• options

Parameter name	Type	Description
start	Number	The starting coordinate in the list, not supported in small class non-large room mode
max	Number	Maximum number of results, not supported in small class non-large room mode
roles	Array	Array of user roles, it will return the list of users that match the queried roles, for user role values, please refer to Room Roles
search	String	Keywords in user nicknames, not supported in small class non-large room mode

• Method example

var options = {
  start: 0,
  max: 200,
  roles: [TK.ROOM_ROLE.TEACHER, TK.ROOM_ROLE.STUDENT]}
const res = await room.getUserList(options).catch(err => {})

Signaling and modifying properties

sendMessage({ textMessage, toID, extendJson }) ->

• This method sends a chat message to the specified user
• The recipient can obtain the message content by listening to the TK.EVENT_TYPE.roomTextMessage event
• The default throttling frequency for sending messages is 1 message per second. If you need to force sending, please configure isforceSend: true in the option

Parameter name	Required	Type	Description
textMessage	Yes	String	Content of the text message
toID	No	String	Message recipient, default is everyone. Possible values can be found in Room Roles
extendJson	No	Object	User-defined extension data

• Method example

var extenJson = {
  textfont : ’Arial’,
  fontsize : 14};
 await room.sendMessage({ textMessage: ‘hello world’, toID: TK.MSG_TO_ALLUSER, extenJson }).catch(err => {})

pubMsg(params) ->

• This method publishes user-defined messages
• The recipient can obtain the message content by listening to the TK.EVENT_TYPE.roomPubmsg event
• If all users in the room have exited, this message will be automatically deleted

Parameter name	Required	Type	Description
name	Yes	String	Message name
id	Yes	String	Message ID
toID	No	String	Message recipient. For role values, please refer to Message Sending Roles
data	Yes	Object	Data information carried by the message
save	No	Boolean	Whether the message is saved to the server, default is false. If it is not saved to the server, users who enter the room later than the time of message publication will not receive this message; only users who entered the room before the message was published will receive it. If it is saved to the server, any user who enters the room at any time will receive this message as long as it has not been deleted.
associatedMsgID	No	String	The associated message ID. For example, if this message is associated with a message whose msgId is 'test-msg', then this message will also be deleted when the 'test-msg' message is deleted
associatedUserID	No	String	The associated user ID. For example, if this message is associated with a user whose ID is 'user-id-123', then this message will be deleted when the user 'user-id-123' leaves the room
			Note: If a user ID is associated, when that user leaves, the recipient of the message (i.e., the toID specified when sending pubMsg) will receive the TK.EVENT_TYPE.roomDelmsg event

• Method example

var msgData = {
  textmsg : ‘every body will receive the hello world message’,
  textfont : ‘Arial’,
  fontsize : 14};var params = {
  name : ‘sendTextMsg’,
  id : ‘sendTextMsg’,
  toID : TK.MSG_TO_ALLEXCEPTSENDER,
  data : msgData,
  save : true,};
 await room.pubMsg(params).catch(err => {})

delMsg(params) ->

• This method is used to delete user-defined messages
• The recipient can obtain the message content by listening to the TK.EVENT_TYPE.roomDelmsg event
• The ID of the message to be deleted must correspond to the message ID published by the pubMsg method; otherwise, it is considered an invalid message, and the recipient will not receive the event

Parameter name	Required	Type	Description
name	Yes	String	Message name
id	Yes	String	Message ID
toID	No	String	Message recipient. For role values, please refer to Message Sending Roles
data	No	String	Data information carried by the message (not recommended to carry data)

• Method example

var params = {
   name : ‘sendTextMsg’,
   id : ‘sendTextMsg’,
   toID : TK.MSG_TO_ALLEXCEPTSENDER,
   data : {}};await room.delMsg(params).catch(err => {})

evictUser({ id, causeJson }) ->

• This method is used to kick a user out of the room
• The user who is kicked out of the room will receive the TK.EVENT_TYPE.roomParticipantEvicted event

Parameter name	Required	Type	Description
id	Yes	String	The ID of the user who is kicked out of the room
causeJson	No	Object	The reason for kicking the user out of the room. User-defined (if the "reason" parameter is included, then the reason must be less than 400 characters)

• Method example

var cause = {
  reason : 100,
  say : ‘good-bye’};
await room.evictUser({ id: ‘user-id-123’, causeJson: cause }).catch(err => {})

changeUserProperty({ id, toID, properties }) ->

• This method modifies or adds attributes for a specific user and notifies the specified users in the room of the attribute changes.
• The notified users will receive the TK.EVENT_TYPE.roomUserPropertyChanged event
• In large room mode, there are limitations on the dispatch of the TK.EVENT_TYPE.roomUserPropertyChanged event (user property changes). For details, please refer to the TK.EVENT_TYPE.roomUserPropertyChanged event dispatch documentation

Parameter name	Required	Type	Description
id	Yes	String	The ID of the user whose attributes are being changed
toID	No	String	The users to be notified. For possible values, please refer to Message Sending Roles
properties	Yes	Object	A collection of user attributes to be modified

• Method example

  var self = room.getMySelf();var prop = {};
  if (self.nickname === ‘tester’) {
    prop.nickname : ‘tester-abc’;}
  if (!self. hasOwnProperty(‘age’)) {
    prop.age = 18;}    
  await room.changeUserProperty({ id: self.id, toID: TK.MSG_TO_ALLUSER, properties: prop }).catch(err => {})

batchChangeUserProperty({ ids, toID, properties }) ->

• This method modifies or adds attributes for multiple users and notifies the specified users in the room of the attribute changes.
• The notified users will receive the TK.EVENT_TYPE.roomUserPropertyChanged event
• In large room mode, there are limitations on the dispatch of the TK.EVENT_TYPE.roomUserPropertyChanged event (user property changes). For details, please refer to the TK.EVENT_TYPE.roomUserPropertyChanged event dispatch documentation

Parameter name	Required	Type	Description
ids	Yes	Array	List of user IDs whose attributes are being changed
toID	No	String	The users to be notified. For possible values, please refer to Message Sending Roles
properties	Yes	Object	A collection of user attributes to be modified

• Method example

var ids=[ user1.id, user2.id, user3.id ] ; var prop = {
  age:20};await room.batchChangeUserProperty({ ids: ids, toID: TK.MSG_TO_ALLUSER, properties: prop }).catch(err => {})

changeUserPropertyByRole({ roles, toID, properties }) ->

• This method modifies or adds attributes for users with certain roles in batches and notifies the specified users in the room of the attribute changes
• The notified users will receive the TK.EVENT_TYPE.roomUserPropertyChanged event
• In large room mode, there are limitations on the dispatch of the TK.EVENT_TYPE.roomUserPropertyChanged event (user property changes). For details, please refer to the TK.EVENT_TYPE.roomUserPropertyChanged event dispatch documentation

Parameter name	Required	Type	Description
roles	Yes	Array	The list of roles whose attributes are being changed. For possible values, please refer to Room Roles
toID	Yes	String	The users to be notified. For possible values, please refer to Message Sending Roles
properties	Yes	Object	A collection of user attributes to be modified

• Method example

var roles=[TK.ROOM_ROLE.STUDENT, TK.ROOM_ROLE.ASSISTANT] ;
var prop = {age:20};  
await room.changeUserPropertyByRole({ roles: roles, toID: TK.MSG_TO_ALLUSER, properties: prop }).catch(err => {})

Publish and play audio and video

publishVideo({ videoinputDeviceId }) ->

• This method publishes your own video
• Users in the room will receive the TK.EVENT_TYPE.roomUserVideoStateChanged event. After parsing the event message, if the video is in the published state, the published video can be viewed by calling the playVideo method
• If this method is called in multi-video mode, the ID of the device needs to be passed in

Parameter name	Required	Type	Description
videoinputDeviceId	No	String	[Required for multi-video mode] Video device ID

• Method example

await room.publishVideo().catch(err => {})

unpublishVideo({ videoinputDeviceId }) ->

• This method stops publishing your own video
• Users in the room will receive the TK.EVENT_TYPE.roomUserVideoStateChanged event. After parsing the event message, if the video is in the unpublished state, the published video can be stopped by calling the unplayVideo method.
• If this method is called in multi-video mode, the ID of the device needs to be passed in.

Parameter name	Required	Type	Description
videoinputDeviceId	No	String	[Required for multi-video mode] Video device ID

• Method example

await room.unpublishVideo().catch(err => {})

- This method publishes your own audio - Users in the room will receive the TK.EVENT_TYPE.roomUserAudioStateChanged event. After parsing the event message, if the audio is in the published state, the published audio can be played by calling the playAudio method. - Method example

await room.publishAudio().catch(err => {})

publishAudio() ->

• This method publishes your own audio
• Users in the room will receive the TK.EVENT_TYPE.roomUserAudioStateChanged event. After parsing the event message, if the audio is in the unpublished state, the published audio can be stopped by calling the unplayAudio method
• Method example

await room.unpublishAudio().catch(err => {})

unpublishAudio() ->

• This method publishes your own audio
• Users in the room will receive the TK.EVENT_TYPE.roomUserAudioStateChanged event. After parsing the event message, if the audio is in the unpublished state, the published audio can be stopped by calling the unplayAudio method
• Method example

await room.unpublishAudio().catch(err => {})

playVideo({ userId, elementId, options, videoinputDeviceId }) ->

• This method is used to play the video of the specified user
• If playing local video, this method can be called directly
• If playing another user's video, this method can only be called after receiving the TK.EVENT_TYPE.roomUserVideoStateChanged event and the video is in the published state

Parameter name	Required	Type	Description
userId	Yes	String	The specified user ID. If it is "", then play your own video
elementId	是	String	The DOM element ID. This DOM element is used to contain the player
options	否	Object	Playback configuration items. The properties are described below
videoinputDeviceId	否	String	[Required for multi-video mode] Video device ID

• options

Parameter name	Type	Description
mode	Number	Indicates the video display mode (whether to crop). For possible values, see Video Display Modes. The default is TK_VIDEO_MODE.ASPECT_RATIO_CONTAIN, which means no cropping
mirror	Boolean	Whether to play in mirror mode

• Method example

await room.playVideo({ userId: ‘user-id-123’, elementId: ‘element-id-123’, options: {mirror: true} }).catch(err => {})

unplayVideo({ userId, videoinputDeviceId }) ->

• This method is used to stop playing the video of the specified use

Parameter name	Required	Type	Description
userId	Yes	String	The specified user ID. If it is "", then stop playing your own video
videoinputDeviceId	No	String	[Required for multi-video mode] Video device ID

• Method example

await room.unplayVideo({ userId: ‘user-id-123’ }).catch(err => {})

playAudio({ userId }) ->

• This method is used to play the audio of the specified user
• If playing another user's audio, this method can only be called after receiving the TK.EVENT_TYPE.roomUserAudioStateChanged event and the audio is in the published state
• Users cannot play their own audio

Parameter name	Required	Type	Description
userId	Yes	String	The specified user ID.

• Method example

await room.playAudio({ userId: ‘user-id-123’ }).catch(err => {})

unplayAudio({ userId }) ->

• This method is used to stop playing the audio of the specified user

Parameter name	Required	Type	Description
userId	Yes	String	The specified user ID.

• Method example

await room.unplayAudio ({ userId: ‘user-id-123’ }).catch(err => {})

Configure local audio and video properties

getDeviceMgr()

• This method returns the device management class object
• Note: The methods in DeviceMgr can be directly called via TK.DeviceMgr and do not necessarily need to be accessed through this interface to obtain the DeviceMgr object
• Method example

var devMgr = room.getDeviceMgr();

setLocalVideoMirror(isMirror)

• This method sets whether the local video uses video mirroring
• By default, the room does not enable local video mirroring

Parameter name	Required	Type	Description
isMirror	Yes	Boolean	Whether the local video uses video mirroring
videoinputDeviceId	No	String	[Required for multi-video mode] Video device ID

• Method example

room.setLocalVideoMirror(true);

getVideoProfile()

• This method retrieves the current video resolution attribute information

Parameter name	Required	Type	Description
videoinputDeviceId	No	String	[Required for multi-video mode] Video device ID

• Method example

var profile = room.getVideoProfile();

Return value

Parameter name	Type	Description
width	Number	Horizontal resolution
height	Number	Vertical resolution
maxfps	Number	Maximum frame rate

setVideoProfile({ profile, videoinputDeviceId }) ->

• This method sets the video resolution attributes
• Note: The set resolution and frame rate must not exceed the product of the maximum resolution (width*height) and the maximum frame rate set when booking the room. If the resolution exceeds the limit, it will be scaled down proportionally. If the frame rate exceeds the limit, it will be set to the maximum frame rate specified when booking the room.

Parameter name	Required	Type	Description
profile	Yes	Object	Video resolution attribute information. Detailed attributes are described below
videoinputDeviceId	No	String	[Required for multi-video mode] Video device ID

• profile

Parameter name	Type	Description
width	Number	Horizontal resolution
height	Number	Vertical resolution
maxfps	Number	Maximum frame rate

• Method example

var profile = {
    width : 80,
    height : 60,
    maxfps : 10};await room.setVideoProfile({ profile }).catch(err => {})

getAudioVolume({ userId, type }) ->

• This method retrieves the current audio capture volume (i.e., microphone input volume) of the specified user
• If you want to represent the real-time changes in local or remote volume, we recommend using the registerAudioVolumeListener interface to obtain it in real time

Parameter name	Required	Type	Description
userId	Yes	String	The specified user ID
type	No	String	The media type to be operated on, default is TK.MEDIA_TYPE.DEVICE_AV. For the range of values, see Media Types

• Method example

const volume = await room.getAudioVolume({ userId: room.getMySelf().id }).catch(err => {})

setRemoteAudioVolume({ volume, userId, type }) ->

• This method sets the audio playback volume for the specified user
• This method takes effect only after calling the playAudio method

Parameter name	Required	Type	Description
volume	YES	Number	Playback volume value. The value range is [0,100]
userId	YES	String	The specified user ID
type	NO	String	The media type to be operated on, default is TK.MEDIA_TYPE.DEVICE_AV. For the range of values, see Media Types

• Method example

await room.setRemoteAudioVolume({ volume: 80, userId: "userId-xxx" }).catch(err => {})

registerAudioVolumeListener({ userId, msInterval, onVolume, type }) ->

• This method is used to obtain the real-time volume changes of the specified user. There is no need for users to use setTimeout or setInterval to call the getAudioVolume method periodically. It is an upgraded version of the getAudioVolume method.

Parameter name	Required	Type	Description
userId	YES	String	The specified user ID. If it is '', then monitor your own volume changes
msInterval	YES	Number	Millisecond-level time interval. The minimum value is 50
onVolume	YES	Function	Volume callback. The value range is [0,100]
type	NO	String	The media type to be operated on, default is TK.MEDIA_TYPE.DEVICE_AV. For the range of values, see Media Types

• Method example

await room.registerAudioVolumeListener({ userId: room.getMySelf().id, msInterval: 80, onVolume: (vol, userId) => {
  console.log(‘user: ’ + userId + ‘. volume: ’ + vol);} }).catch(err => {})

unregisterAudioVolumeListener({ userId, type }) ->

• This method removes the volume listener for the specified user

Parameter name	Required	Type	Description
userId	Yes	String	The specified user ID. If it is '', then remove your own volume listener
type	No	String	The media type to be operated on, default is TK.MEDIA_TYPE.DEVICE_AV. For the range of values, see Media Types

• Method example

await room.unregisterAudioVolumeListener({ userId: room.getMySelf().id }).catch(err => {})

disableVideoDevice(tk_disablevideo)

• This method is used to change the disabled status of your own video device. The video device in the room is not disabled by default
• After setting the video device to be disabled, the local camera will not be turned on, and video data cannot be published.
• To publish video, you need to disable the video device and then call publishVideo again

Parameter name	Required	Type	Description
tk_disablevideo	Yes	Boolean	Whether to disable the video device

• Method example

room.disableVideoDevice (true)

setAutoProcessDeviceChangeEvent(autoProcess)

• This method sets whether the SDK automatically handles device change (plug/unplug) events
• If set to automatic handling, in single-video mode, the SDK will automatically select a device to republish local audio and video after a device is plugged or unplugged (if audio and video are currently being published). In multi-video mode, it will automatically unpublish the removed device (i.e., actively call unpublishVideo, but not actively call unplayVideo)
• If set to non-automatic handling, after a device is unplugged, the video will freeze on the last frame. Unless explicitly set to automatic handling, the SDK will not automatically handle device changes
• In multi-video mode, if the removed device is the main camera, the SDK will automatically switch to the first device in the video device list as the new main camera

Parameter name	Required	Type	Description
autoProcess	Yes	Boolean	Specify whether to automatically handle device change (plug/unplug) events

• Method example

room.setAutoProcessDeviceChangeEvent(true)

Share and play screen-sharing streams

startShareScreen(screenInfo) ->

• The method begins to share the screen
• The receiver of the desktop sharing stream will receive the TK.EVENT_TYPE.roomUserScreenStateChanged event. After parsing the event message, if the sharing stream is in the publishing state, the receiver can play the screen video of the sharer by calling the playRemoteScreen method

Parameter name	Required	Type	Description
screenInfo	No	Object	Sharing parameters, parameter configurations are shown in the following text

• screenInfo

Parameter name	Required	Type	Description
toID	No	String	The receiver of the shared stream defaults to TK.MSG_TO_ALLUSER. For optional values, refer to Message Sending Roles

• Method example

await room.startShareScreen().catch(err => {})

stopShareScreen() ->

• The method ends the screen sharing
• The receiver of the desktop sharing stream will receive the TK.EVENT_TYPE.roomUserScreenStateChanged event. After parsing the event message, if the sharing stream is in the unpublished state, the receiver can stop playing the sharer's screen video by calling the unplayRemoteScreen method
• Method example

await room.stopShareScreen().catch(err => {})

playRemoteScreen({ userId, elementId, options = {} }) ->

• This method is used to play the screen-sharing stream
• It must be called after receiving the TK.EVENT_TYPE.roomUserScreenStateChanged event and when the sharing stream is in the published state

Parameter name	Required	Type	Description
userId	Yes	String	The user ID of the sharer
elementId	Yes	String	The DOM element ID. This DOM element is used to contain the player
options	No	Object	Playback configuration options. Specific parameters are detailed in the following text

• options

Parameter name	Required	Type	Description
mirror	No	Boolean	Whether the video is displayed in mirror mode. The default is not mirrored
mode	No	String	Used to indicate the video display mode (whether to crop). The values can be found in Video Display Modes. The default is TK_VIDEO_MODE.ASPECT_RATIO_CONTAIN, which means no cropping

• Method example

await room.playRemoteScreen({ userId: "user-1233", elementId: "user-123-dom" }).catch(err => {})

unplayRemoteScreen({ userId }) ->

• This method is used to stop playing the screen-sharing stream

Parameter name	Required	Type	Description
userId	Yes	String	The user ID of the sharer

• Method example

await room.unplayRemoteScreen({ userId: "user-1233" }).catch(err => {})

Share and play media streams

• Sharing media files refers to media files (audio or video files) that have been uploaded to the server

startShareMedia({ url, isVideo, options }) ->

• The shared media file must be one that has already been uploaded to the server. It is not possible to share media files that are not on the server, because the media file is shared by the server startShareMedia({ url, isVideo, options }) -> {Promise}
• This method begins to share the media file
• After the sharing is successful, all users in the room will receive the TK.EVENT_TYPE.roomUserMediaStateChanged event. After parsing the event message, if the media stream is in the published state, the media stream can be played by calling the playRemoteMedia method
• Since the media file is shared by the server, even the sharer themselves need to call the playRemoteMedia method to play the media stream after receiving the TK.EVENT_TYPE.roomUserMediaStateChanged event

Parameter name	Required	Type	Description
url	Yes	String	The absolute path of the shared media file
isVideo	No	Boolean	Whether it is a video file. The default is false
options	No	Object	Sharing configuration options. Details are provided in the following text

• options

Parameter name	Required	Type	Description
toID	No	String	Who to send to. The default is to send to everyone
attrs	No	Object	The attributes data carried by the stream

• Method example

await room.startShareMedia({ url: "xxx-url", isVideo: false }).catch(err => {})

stopShareMedia({ onlyStopMyself }) ->

• This method ends the sharing of the media file
• After the sharing is ended, all users in the room will receive the TK.EVENT_TYPE.roomUserMediaStateChanged event. After parsing the event message, if the media stream is in the unpublished state, the media stream can be stopped by calling the unplayRemoteMedia method
• Since the media file is shared by the server, the person who shared it also needs to call the unplayRemoteMedia method to stop the media stream after receiving the TK.EVENT_TYPE.roomUserMediaStateChanged event

Parameter name	Required	Type	Description
onlyStopMyself	No	Boolean	Whether to stop only the media file that you shared

• Method example

await room.stopShareMedia().catch(err => {})

pauseShareMedia({ pause }) ->

• This method pauses the sharing of the media file

Parameter name	Required	Type	Description
pause	Yes	Boolean	Whether to pause (or resume) the sharing of the media file

• Method example

await room.pauseShareMedia({ pause: true }).catch(err => {})

seekMedia({ positionPercent }) ->

• This method controls the progress of the shared media file, allowing the media file to jump to a specified time point and continue playing

Parameter name	Required	Type	Description
positionPercent	Yes	Number	The specified progress percentage, with a value range of [0-1]

• Method example

await room.seekMedia({ positionPercent: 0.5 }).catch(err => {})

playRemoteMedia({ userId, elementId, options }) ->

• This method plays the media file shared in the room
• After receiving the TK.EVENT_TYPE.roomUserMediaStateChanged event, if the media stream is in the published state and the media stream type is media, this method should be called to watch the media file

Parameter name	Required	Type	Description
userId	YES	String	The user ID of the sharer
elementId	YES	String	The DOM element ID. This DOM element is used to contain the player
options	YES	Object	Playback configuration options. Detailed configurations are provided in the following text

• options

Parameter name	Required	Type	Description
mirror	No	Boolean	Whether the video is displayed in mirror mode. The default is not mirrored
mode	No	String	Used to indicate the video display mode (whether to crop). The values can be found in Video Display Modes. The default is TK_VIDEO_MODE.ASPECT_RATIO_CONTAIN, which means no cropping

• Method example

await room.playRemoteMedia({ userId: "user-123", elementId: "user-123-dom" }).catch(err => {})

unplayRemoteMedia({ userId }) ->

• This method stops playing the shared media file
• After receiving the TK.EVENT_TYPE.roomUserMediaStateChanged event, if the media stream is in the unpublished state and the media stream type is media, this method should be called to close the player

Parameter name	Required	Type	Description
userId	Yes	String	The user ID of the sharer

• Method example

await room.unplayRemoteMedia({ userId: "user-123" }).catch(err => {})

playRemoteMediaFile({ userId, elementId, options }) ->

• This method plays the media file shared remotely (the local media file shared by a user through the TopClass client)
• After receiving the TK.EVENT_TYPE.roomUserMediaStateChanged event, if the media stream is in the published state and the media stream type is file, this method should be called to watch the media file

Parameter name	Required	Type	Description
userId	Yes	String	The user ID of the sharer
elementId	Yes	String	The DOM element ID. This DOM element is used to contain the player
options	No	Object	Playback configuration options. Detailed configurations are provided in the following text

• options

Parameter name	Required	Type	Description
mirror	No	Boolean	Whether the video is displayed in mirror mode. The default is not mirrored
mode	No	String	Used to indicate the video display mode (whether to crop). The values can be found in Video Display Modes. The default is TK_VIDEO_MODE.ASPECT_RATIO_CONTAIN, which means no cropping

• Method example

await room.playRemoteMediaFile({ userId: "user-123", elementId: "user-123-dom" }).catch(err => {})

unplayRemoteMediaFile({ userId }) ->

• This method stops playing the remotely shared media file (the local media file shared by a user through the TopClass client)
• After receiving the TK.EVENT_TYPE.roomUserMediaStateChanged event, if the media stream is in the unpublished state and the media stream type is file, this method should be called to close the player

Parameter name	Required	Type	Description
userId	Yes	String	The user ID of the sharer

• Method example

await room.unplayRemoteMediaFile({ userId: "user-123" }).catch(err => {})

Room status

switchOnlyAudioRoom({ onlyAudio }) ->

• This method switches the room mode to a pure audio room

Parameter name	Required	Type	Description
onlyAudio	Yes	Boolean	Whether to switch to a pure audio room

• Method example

await room.switchOnlyAudioRoom({ onlyAudio: true }).catch(err => {})

Server recording and local recording

startServerRecord

• This method starts server-side recording
• Calling startServerRecord twice consecutively (i.e., calling startServerRecord again without calling stopServerRecord in between) will take the first call as the standard

Parameter name	Required	Type	Description
spec	No	Object	Recording configuration. Detailed configuration information is as follows

• spec

Parameter name	Type	Description
recordMode	String	Recording mode: (standard: Standard regular recording), (mix: Custom mixed-stream recording)
mixStreamParams	Object	Mixed-stream mode parameters, effective only in mixed-stream mode. Detailed explanations are as follows

• mixStreamParamsspec

Parameter name	Type	Description
template	Number	The mixed-stream layout template ID. 0 for even distribution layout; 1 for picture-in-picture layout; 2 for custom layout
backgroundColor	String	Color value
customConfig	Object	Custom configuration. The configuration details are as follows

• customConfig

Parameter name	Type	Description
backgroundColor	String	Color value. If set, it takes precedence over mixStreamParams.backgroundColor
noStreamTimeout_s	Number	mixed stream. After the mixed stream starts, if there are no user streams in the room, the mixed stream will stop after this timeout period, measured in seconds (s)
videoLayout	Array	Custom video stream styles for users. Pass an array of user style objects, videoLayoutUser, into the configuration. The user style object is described as follows

• videoLayoutUser

Parameter name	Type	Description
uid	String	User ID. If the video stream is a desktop-sharing stream, the ID should be in the format uid:screen
x_coord	Number	The x-coordinate of the window, expressed as a percentage of the total video width
y_coord	Number	The y-coordinate of the window, expressed as a percentage of the total video height
width	Number	Window width, expressed as a percentage of the total video width
height	Number	Window height, expressed as a percentage of the total video height
alpha	Number	Window transparency
play_video	Boolean	Whether to play the video. The default is true
play_audio	Boolean	Whether to play the audio. The default is true

• Method example

const recordParams ={
    recordMode: 'mix',
    mixStreamParams: {
        template: 0,
        backgroundColor: '#0d69fb',
        customConfig: {
            backgroundColor: '#0d69fb',
            noStreamTimeout_s: 30,
            videoLayout: [
                {
                    uid: 'xxx',
                  x_coord: 0.81,
                    y_coord: 0.1,
                    width: 0.18,
                    height: 0.24,
                    alpha: 1,
                    play_video: true,
                    play_audio: true
                }
            ]
        }
    }}
room.startServerRecord(recordParams)

stopServerRecord

• This method stops the server-side recording
• Method example

room.stopServerRecord()

pauseServerRecord

• This method pauses the server-side recording
• Method example

room.stopServerRecord()

resumeServerRecord

• This method resumes the server-side recording
• Method example

room.resumeServerRecord()

getServerRecordState

• This method retrieves the server-side recording status and returns the recording status enumeration value
• The recording status enumeration values can be found in the Server Recording Status section
• Method example

const recordState = room.getServerRecordState()