房间管理类

房间管理类（Room）
- Room
初始化设置
进出房间和房间信息
用户信息
信令和修改属性
发布和播放音视频
设置本地音视频属性
分享和播放桌面共享流
分享和播放媒体流
房间状态
- switchOnlyAudioRoom({ onlyAudio }) -> {Promise}
服务器录制和本地录制

房间管理类（Room）

Room

该方法实例化一个房间管理类对象。房间中所有操作，几乎都由该对象控制。
方法示例

1	`var room = TK.Room()`

初始化设置

init(appKey, options) -> {Promise}

该方法用于初始化Room对象

注：在init成功后才能调用room的其它方法。建议：建议在init调用前建议先完成设备检测，因为调用init方法后会从设备列表中寻找一个设备（这个设备是否可用无法确保）

参数名	必填	类型	说明
appKey	是	String	企业domain
options	否	Object	初始化配置项，详细可选配置如下

options

参数	类型	说明
tk_multistream	Boolean	是否开启多视频模式, 默认为 false
checkDevice	{ video?: boolean, audio?: boolean }	是否检查音视频设备设备, 默认音视频设备都检查

方法示例

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

uninit()

该方法用于重置Room对象到未初始化状态
方法示例

1	`room.uninit()`

checkInit()

该方法用于检测房间的初始化状态
方法示例

1	`var isInit = room.checkInit()`

进出房间和房间信息

joinroom(roomOption, userOption) -> {Promise}

调用该方法加入已创建的房间。此方法应为Room类中首先被调用的方法。

参数名	必填	类型	说明
roomOption	是	Object	加入房间所需的基本参数
userOption	是	Object	用户属性

roomOption

参数名	类型	说明
roomId	String	房间ID
userPwd	String	房间口令

userOption

参数名	类型	说明
userId	String	用户id
role	Number	用户身份
nickname	String	用户昵称

方法示例

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

joinRoomEx(roomOption, userOption) -> {Promise}

调用该方法加入已创建的临时房间。此方法应为Room类中首先被调用的方法。

参数名	必填	类型	说明
roomOption	是	Object	加入房间所需的基本参数
userOption	是	Object	用户自定义属性

roomJsonOptions

参数名	类型	说明
roomId	String	房间ID
tk_token	String	tk签名
userPwd	String	房间口令

userJsonOptions

参数名	类型	说明
userId	String	用户id
role	Number	用户身份
nickname	String	用户昵称

方法示例

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

leaveroom ()

使用该方法离开房间。离开房间后，所有音视频通话都被终止。
方法示例

1	`room.leaveroom()`

getRoomProperties()

该方法获取房间信息。此信息中包括预约房间时的所有配置。
方法示例

1	`var property = room.getRoomProperties()`

- 返回值 + 该接口返回object, 以下只列举object内部分常用房间属性

参数	类型	说明
serial	String	房间号
roomname	String	房间名称
companyid	String	公司id
maxvideo	Number	房间支持最大视频路数
videowidth	String	视频分辨率最大宽度
videoheight	String	视频分辨率最大高度

用户信息

getMySelf()

该方法获取自己的用户对象。

注：如果没有joinroom成功（即没有收到TK.EVENT_TYPE.roomConnected事件），则返回空对象

方法示例

1	`var self = room.getMySelf();`

getUser(userId)

该方法获取指定RoomUser对象

注：该接口在大房间（即大规模房间）下使用只能获取到已经上台的用户（即发布音频/视频人的用户）和特殊用户（如：老师/助教），因此在大房间模式下，建议只使用该接口来操作上台的用户

参数名	必填	类型	说明
userId	是	String	被获取用户的id

方法示例
1
var user = room.getUser("1");

getUsers()

该方法返回房间中所有用户对象集合,返回值类型为Object。

注：该接口在大房间（即大规模房间）下使用只能获取到已经上台的用户（即发布音频/视频人的用户）和特殊用户（如：老师/助教），因此在大房间模式下，建议只使用该接口来操作上台的用户

方法示例

1	`var users = room.getUsers();`

返回值

类型	说明
Object	用户集合对象，键值格式为 userid: user

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

该方法获取用户列表。

注：该接口建议只在大房间（即大规模房间）下使用，非大房间模式下建议使用getUsers接口

参数名	必填	类型	说明
start	否	Number	开始位置，缺省为0
max	否	Number	最大获取个数,缺省为200
roles	否	Array	角色列表，缺省为所有角色，角色取值请见房间角色]
search	否	String	昵称检索的内容，缺省为"" 【注：此处只对于用户昵称进行搜索且为模糊搜索】
order	否	Array	排序规则,详细规则见下文说明

order 规则补充说明：
升序使用’asc’,降序使用’desc’
最多3条排序规则，超过的规则将不起效,默认规则为根据加入的时间进行升序（即：order为[{ts:’asc’}]）
规则在前面的优先起效，即order数组下标越小排序优先级越高
方法示例

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

getRoomUserNum({ roles, search }) -> {Promise}

该方法获取用户总数。

参数名	必填	类型	说明
roles	否	Array	角色列表，缺省为所有角色，角色取值请见房间角色
search	否	String	昵称检索的内容，缺省为"" 【注：此处只对于用户昵称进行搜索且为模糊搜索】

方法示例

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

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

该方法返回房间内当前用户列表和总数

参数名	必填	类型	说明
options	否	Object	查询条件，参数及说明如下

options

参数名	类型	说明
start	Number	列表中起始坐标，小班课非大房间模式下不支持
max	Number	最大结果个数，小班课非大房间模式下不支持
roles	Array	用户角色数组, 会返回符合查询角色的用户列表, 用户角色取值参考房间角色
search	String	用户昵称中的关键字, 小班课非大房间模式下不支持

方法示例

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

信令和修改属性

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

该方法发送聊天消息给指定用户
接收者可通过监听TK.EVENT_TYPE.roomTextMessage事件获取消息内容
发送消息默认节流频率为 1条/秒,如需强制发送，请在 options 中配置 isforceSend: true

参数名	必填	类型	说明
textMessage	是	String	文本消息内容
toID	否	String	消息接收者，缺省为所有人。可能取值请见房间角色
extendJson	否	Object	用户可自定义的扩展数据

方法示例

var extenJson = {
  textfont : ’Arial’,
  fontsize : 14
};


 await room.sendMessage({ textMessage: ‘hello world’, toID: TK.MSG_TO_ALLUSER, extenJson }).catch(err => {})

pubMsg(params) -> {Promise}

该方法发布用户自定义消息
接收者可通过监听TK.EVENT_TYPE.roomPubmsg事件事件获取消息内容
若房间中所有用户已退出，此消息会被自动删除

参数名	必填	类型	说明
name	是	String	消息名
id	是	String	消息ID
toID	否	String	消息接收者。角色取值请见消息发送角色
data	是	Object	消息携带的数据信息
save	否	Boolean	息是否保存到服务器，默认为false。若不保存到服务器，晚于发布消息时刻进入房间的用户不会收到此消息，只有发布消息时刻前进入房间的用户可收到此消息；若保存到服务器，在该消息未被删除的情况下，任何时刻进入房间的用户都会收到此消息。
associatedMsgID	否	String	关联的消息ID。假设此消息关联了一条msgId为‘test-msg’的消息，那么当’test-msg’消息被删除后，此消息也被删除
associatedUserID	否	String	关联的用户ID。假设此消息关联了一个id为‘user-id-123’的用户，那么当user-id-123’用户离开房间后，此消息将被删除
			注：若关联了用户ID，则该用户离开后，则该消息的接收者（即：发送pubMsg时指定的toID）会收到TK.EVENT_TYPE.roomDelmsg事件

方法示例

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) -> {Promise}

该方法用于删除用户自定义消息
接收者可通过监听TK.EVENT_TYPE.roomDelmsg事件获取消息内容
删除消息的ID必须与pubMsg方法发布的消息ID对应，否则为无效消息，接收者不会收到事件

参数名	必填	类型	说明
name	是	String	消息名
id	是	String	消息ID
toID	否	String	消息接收者。角色取值请见消息发送角色
data	否	Object	消息携带的数据信息（不建议携带数据）

方法示例

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

evictUser({ id, causeJson }) -> {Promise}

该方法用于将用户请出房间
被请出房间的用户将会收到 TK.EVENT_TYPE.roomParticipantEvicted 事件

参数名	必填	类型	说明
id	是	String	被请出房间的用户ID
causeJson	否	Object	请出房间的原因。用户自定义（如果包含"reason"参数，则reason必须小于400）

方法示例

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

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

该方法改变或添加某用户属性，并将属性变化通知给房间中的指定用户。
被通知的用户会收到 TK.EVENT_TYPE.roomUserPropertyChanged 事件
在大房间模式下，事件派发TK.EVENT_TYPE.roomUserPropertyChanged（用户属性改变）有限制, 详情请见 TK.EVENT_TYPE.roomUserPropertyChanged事件派发

参数名	必填	类型	说明
id	是	String	被改变属性的用户ID
toID	否	String	被通知的用户。可能取值请见消息发送角色
properties	是	Object	修改的用户属性集合

方法示例

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 }) -> {Promise}

该方法批量改变或添加某些用户属性，并将属性变化通知给房间中的指定用户。
被通知的用户会收到 TK.EVENT_TYPE.roomUserPropertyChanged 事件
在大房间模式下，事件派发TK.EVENT_TYPE.roomUserPropertyChanged（用户属性改变）有限制, 详情请见 TK.EVENT_TYPE.roomUserPropertyChanged 事件派发

参数名	必填	类型	说明
ids	是	Array	被改变属性的用户ID列表
toID	否	String	被通知的用户。可能取值请见消息发送角色
properties	是	Object	修改的用户属性集合

方法示例

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 }) -> {Promise}

该方法批量改变或添加某些角色的用户属性，并将属性变化通知给房间中的指定用户
被通知的用户会收到 TK.EVENT_TYPE.roomUserPropertyChanged 事件
在大房间模式下，事件派发TK.EVENT_TYPE.roomUserPropertyChanged（用户属性改变）有限制, 详情请见 TK.EVENT_TYPE.roomUserPropertyChanged 事件派发

参数名	必填	类型	说明
roles	是	Array	被改变属性的角色列表，可能取值请见房间角色
toID	是	String	被通知的用户。可能取值请见消息发送角色
properties	是	Object	修改的用户属性集合

方法示例

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 => {})

发布和播放音视频

publishVideo({ videoinputDeviceId }) -> {Promise}

该方法将自己的视频发布出去
房间中的人会收到 TK.EVENT_TYPE.roomUserVideoStateChanged 事件, 解析事件消息后视频为发布状态,可通过调用playVideo方法观看发布者的视频。
如果是多视频模式调用该方法时需要传入设备的ID

参数名	必填	类型	说明
videoinputDeviceId	否	String	[多视频模式必选]视频设备ID

方法示例

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

unpublishVideo({ videoinputDeviceId }) -> {Promise}

该方法停止发布自己的视频
房间中的人会收到 TK.EVENT_TYPE.roomUserVideoStateChanged 事件, 解析事件消息后视频为取消发布状态,可通过调用unplayVideo方法关闭发布者的视频。
如果是多视频模式调用该方法时需要传入设备的ID

参数名	必填	类型	说明
videoinputDeviceId	否	String	[多视频模式必选]视频设备ID

方法示例

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

publishAudio() -> {Promise}

该方法将自己的音频发布出去
房间中的人会收到 TK.EVENT_TYPE.roomUserAudioStateChanged 事件, 解析事件消息后音频为发布状态,可通过调用playAudio方法播放发布者的音频。
方法示例

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

unpublishAudio() -> {Promise}

该方法将自己的音频发布出去
房间中的人会收到 TK.EVENT_TYPE.roomUserAudioStateChanged 事件, 解析事件消息后音频为取消发布状态,可通过调用unplayAudio方法关闭发布者的音频
方法示例

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

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

该方法用于播放指定用户的视频
若播放本地视频，可直接调用
若播放其他用户视频，必须在收到TK.EVENT_TYPE.roomUserVideoStateChanged事件后且视频为发布状态方可调用

参数名	必填	类型	说明
userId	是	String	指定的用户ID。若为""，则播放自己视频
elementId	是	String	dom元素ID。该dom元素用于盛放播放器
options	否	Object	播放配置项。包含属性见下文说明
videoinputDeviceId	否	String	[多视频模式必选]视频设备ID

options

参数	类型	说明
mode	Number	用于表示视频显示模式（是否裁减），取值见视频显示模式, 默认为 `TK_VIDEO_MODE.ASPECT_RATIO_CONTAIN` 不裁剪
mirror	Boolean	是否镜像播放

方法示例

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

unplayVideo({ userId, videoinputDeviceId }) -> {Promise}

该方法用于停止播放指定用户的视频

参数名	必填	类型	说明
userId	是	String	指定的用户ID。若为""，则停止播放自己视频
videoinputDeviceId	否	String	[多视频模式必选]视频设备ID

方法示例

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

playAudio({ userId }) -> {Promise}

该方法用于播放指定用户的音频
若播放其他用户音频，必须在收到TK.EVENT_TYPE.roomUserAudioStateChanged事件后且音频为发布状态方可调用
用户不能播放自己的音频

参数名	必填	类型	说明
userId	是	String	指定的用户ID。

方法示例

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

unplayAudio({ userId }) -> {Promise}

该方法停止播放指定用户的音频

参数名	必填	类型	说明
userId	是	String	指定的用户ID。

方法示例

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

muteAllRemoteAudio(mute)

该方法暂停/恢复播放所有远端用户的音频
当您静音所有用户的远端音频时，SDK 会停止播放所有来自远端的音频流，同时也会停止拉取所有用户的音频数据
在进入房间（joinroom）之前或之后调用本接口均生效，静音状态在退出房间（leaveroom）之后会被重置为 false

参数名	必填	类型	说明
mute	是	Boolean	mute：true: 静音；false：取消静音

方法示例

1	`room.muteAllRemoteAudio(true)`

设置本地音视频属性

getDeviceMgr()

该方法返回设备管理类对象
注：DeviceMgr中的方法可由TK.DeviceMgr直接调用，并非一定要通过此接口获得DeviceMgr对象才能使用
方法示例

1	`var devMgr = room.getDeviceMgr();`

setLocalVideoMirror(isMirror)

该方法设置本地视频是否启用视频镜像
房间默认不启用本地视频镜像

参数名	必填	类型	说明
isMirror	是	Boolean	本地视频是否启用视频镜像
videoinputDeviceId	否	String	[多视频模式必选]视频设备ID

方法示例

1	`room.setLocalVideoMirror(true);`

getVideoProfile()

-该方法获取当前视频分辨率属性信息

参数名	必填	类型	说明
videoinputDeviceId	否	String	[多视频模式必选]视频设备ID

方法示例

1	`var profile = room.getVideoProfile();`

- 返回值

参数名	类型	说明
width	Number	水平分辨率
height	Number	垂直分辨率
maxfps	Number	最大帧率

setVideoProfile({ profile, videoinputDeviceId }) -> {Promise}

该方法设置视频分辨率属性
注：设置的分辨率及帧率不可超过预约房间时设定的最大分辨率的乘积（width*height）及最大帧率，若分辨率超出，则根据比例缩放当前设置的分辨率，若帧率超出，则设置为预约房间时的最大帧率。

参数名	必填	类型	说明
profile	是	Object	视频分辨率属性信息。详细属性见下文说明
videoinputDeviceId	否	String	[多视频模式必选]视频设备ID

profile

参数名	类型	说明
width	Number	水平分辨率
height	Number	垂直分辨率
maxfps	Number	最大帧率

方法示例

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

getAudioVolume({ userId, type }) -> {Promise}

该方法获取指定用户的当前时刻音频采集音量（即麦克风输入音量）
如果您想实时表示本地或远端音量的变化，我们建议您使用registerAudioVolumeListener接口来实时获取

参数名	必填	类型	说明
userId	是	String	指定的用户ID
type	否	String	需要操作媒体类型,默认为`TK.MEDIA_TYPE.DEVICE_AV`, 取值范围见媒体类型

方法示例

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

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

该方法设置指定用户的音频播放音量
此方法在调用playAudio方法后方能生效

参数名	必填	类型	说明
volume	是	Number	播放音量值。取值区间[0,100]
userId	是	String	指定的用户ID
type	否	String	需要操作媒体类型, 默认为`TK.MEDIA_TYPE.DEVICE_AV`, 取值范围见媒体类型

方法示例

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

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

该方法用于获取指定用户的实时音量变化，无需用户自己使用setTimeout或setInterval定时调用getAudioVolume方法，是getAudioVolume 的升级方法。

参数名	必填	类型	说明
userId	是	String	指定的用户ID。若为’’，则监听自己的音量变化
msInterval	是	Number	毫秒级时间间隔。最小值为50
onVolume	是	Function	获取音量回调。取值区间[0,100]
type	否	String	需要操作媒体类型, 默认为`TK.MEDIA_TYPE.DEVICE_AV`, 取值范围见媒体类型

方法示例

1
2
3

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

unregisterAudioVolumeListener({ userId, type }) -> {Promise}

该方法移除指定用户的音量监听器

参数名	必填	类型	说明
userId	是	String	指定的用户ID。若为’’，则移除自己的音量监听器
type	否	String	需要操作媒体类型, 默认为`TK.MEDIA_TYPE.DEVICE_AV`, 取值范围见媒体类型

方法示例

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

disableVideoDevice(tk_disablevideo)

该方法用于改变自己视频设备的禁用状态，房间视频设备默认不禁用
设置视频设备禁用后，将不会打开本地摄像头，无法发布视频数据。
如需发布视频，需要取消禁用后重新调用 publishVideo

参数名	必填	类型	说明
tk_disablevideo	是	Boolean	是否禁用视频设备

方法示例

1	`room.disableVideoDevice (true)`

setAutoProcessDeviceChangeEvent(autoProcess)

该方法设置SDK是否自动处理设备改变（插拔）事件
若设定为自动处理，在单视频模式下，设备插拔后SDK会自动选择设备重新发布本地音视频（若当前正在发布音视频），在多视频模式下会自动将移除的设备取消发布（即：主动执行unpublishVideo,但是不主动unplayVideo）
若设定为非自动处理，则设备拔出后，视频画面会停留在最后一帧。不主动指定为自动处理的情况下，SDK不会自动处理
在多视频模式下，如果移除的是主摄像头设备，则SDK会自动找视频设备列表的第一个设备自动切换主摄像头

参数名	必填	类型	说明
autoProcess	是	Boolean	指定是否自动处理设备改变（插拔）事件

方法示例

1	`room.setAutoProcessDeviceChangeEvent(true)`

分享和播放桌面共享流

startShareScreen(screenInfo) -> {Promise}

该方法开始进行屏幕共享
桌面共享流的接收者会收到 TK.EVENT_TYPE.roomUserScreenStateChanged 事件, 解析事件消息后共享流为发布状态,可通过调用playRemoteScreen方法播放共享者的屏幕视频

参数名	必填	类型	说明
screenInfo	否	Object	共享参数，参数配置见下文

screenInfo

参数名	必填	类型	说明
toID	否	String	共享流接收者，默认为`TK.MSG_TO_ALLUSER`, 可选值见消息发送角色

方法示例

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

stopShareScreen() -> {Promise}

该方法结束屏幕共享
桌面共享流的接收者会收到 TK.EVENT_TYPE.roomUserScreenStateChanged 事件, 解析事件消息后共享流为取消发布状态,可通过调用unplayRemoteScreen方法关闭共享者的屏幕视频
方法示例

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

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

该方法用于播放屏幕共享流
必须在收到TK.EVENT_TYPE.roomUserScreenStateChanged事件后且共享流为发布状态方可调用

参数名	必填	类型	说明
userId	是	String	共享者的用户id
elementId	是	String	dom元素ID。该dom元素用于盛放播放器
options	否	Object	播放配置项，具体参数见下文

options

参数名	必填	类型	说明
mirror	否	Boolean	视频是否镜像显示，默认不镜像
mode	否	String	用于表示视频显示模式（是否裁减），取值见视频显示模式 , 默认为 `TK_VIDEO_MODE.ASPECT_RATIO_CONTAIN` 不裁剪

方法示例

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

unplayRemoteScreen({ userId }) -> {Promise}

该方法用于关闭播放屏幕共享流

参数名	必填	类型	说明
userId	是	String	共享者的用户id

方法示例

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

分享和播放媒体流

共享媒体文件是指将已上传到服务器的媒体文件（音频文件或视频文件）
共享的媒体文件必须是已经上传服务器的，不能共享非服务器上的媒体文件，因为该媒体文件是由服务器进行共享

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

该方法开始共享媒体文件
共享成功后，房间内的人会收到TK.EVENT_TYPE.roomUserMediaStateChanged事件，解析事件消息后媒体流为发布状态,可通过调用playRemoteMedia方法播放媒体流
因为该媒体文件是由服务器进行共享，因此自己收到TK.EVENT_TYPE.roomUserMediaStateChanged后也需要调用playRemoteMedia进行播放

参数名	必填	类型	说明
url	是	String	共享的媒体文件的绝对路径
isVideo	否	Boolean	是否是视频文件，缺省为false
options	否	Object	共享配置项, 说明见下文

options

参数名	必填	类型	说明
toID	否	String	发送给谁 , 默认发送给所有人
attrs	否	Object	流携带的attributes数据

方法示例

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

stopShareMedia({ onlyStopMyself }) -> {Promise}

该方法结束共享媒体文件
结束共享后，房间内的人会收到TK.EVENT_TYPE.roomUserMediaStateChanged事件，解析事件消息后媒体流为取消发布状态,可通过调用unplayRemoteMedia方法关闭媒体流
因为该媒体文件是由服务器进行共享，因此自己收到TK.EVENT_TYPE.roomUserMediaStateChanged后也需要调用unplayRemoteMedia进行关闭

参数名	必填	类型	说明
onlyStopMyself	否	Boolean	是否只停止自己共享的媒体文件

方法示例

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

pauseShareMedia({ pause }) -> {Promise}

该方法暂停共享媒体文件

参数名	必填	类型	说明
pause	是	Boolean	是否暂停（或恢复）共享媒体文件

方法示例

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

seekMedia({ positionPercent }) -> {Promise}

该方法控制共享媒体文件的进度，使媒体文件跳跃到指定的时间点继续播放

参数名	必填	类型	说明
positionPercent	是	Number	指定进度的百分比，取值范围为[0-1]

方法示例

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

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

该方法播放房间中共享的媒体文件
在收到TK.EVENT_TYPE.roomUserMediaStateChanged事件后，若媒体流为发布状态，且媒体流类型为media，则调用此方法观看

参数名	必填	类型	说明
userId	是	String	共享者的用户ID
elementId	是	String	Dom元素ID。该Dom元素用于盛放播放器
options	否	Object	播放配置项，详细配置见下文

options

参数名	必填	类型	说明
mirror	否	Boolean	视频是否镜像显示，默认不镜像
mode	否	String	用于表示视频显示模式（是否裁减），取值见视频显示模式 , 默认为 `TK_VIDEO_MODE.ASPECT_RATIO_CONTAIN` 不裁剪

方法示例

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

unplayRemoteMedia({ userId }) -> {Promise}

该方法停止播放共享的媒体文件
在收到TK.EVENT_TYPE.roomUserMediaStateChanged事件后，若媒体流为取消发布状态，且媒体流类型为media，则调用此方法关闭播放器

参数名	必填	类型	说明
userId	是	String	共享者的用户ID

方法示例

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

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

该方法播放远端共享的媒体文件（拓课客户端用户共享的用户本地媒体文件）
在收到TK.EVENT_TYPE.roomUserMediaStateChanged事件后，若媒体流为发布状态，且媒体流类型为file，则调用此方法观看

参数名	必填	类型	说明
userId	是	String	共享者的用户ID
elementId	是	String	Dom元素ID。该Dom元素用于盛放播放器
options	否	Object	播放配置项，详细配置见下文

options

参数名	必填	类型	说明
mirror	否	Boolean	视频是否镜像显示，默认不镜像
mode	否	String	用于表示视频显示模式（是否裁减），取值见视频显示模式 , 默认为 `TK_VIDEO_MODE.ASPECT_RATIO_CONTAIN` 不裁剪

方法示例

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

unplayRemoteMediaFile({ userId }) -> {Promise}

该方法关闭播放远端共享的媒体文件（拓课客户端用户共享的用户本地媒体文件）
在收到TK.EVENT_TYPE.roomUserMediaStateChanged事件后，若媒体流为取消发布状态，且媒体流类型为file，则调用此方法关闭播放器

参数名	必填	类型	说明
userId	是	String	共享者的用户ID

方法示例

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

startPlayAudioFile({ url, elementId, stageCallback })

该方法本地播放音频资源链接，播放方法经过回声消除，不会产生回音

参数名	必填	类型	说明
url	是	String	音频资源链接，由于浏览器能力限制，不支持 `file://` 协议
elementId	是	String	音频播放器id
stageCallback	否	Function	播放状态回调，目前只回调 'play', 'ended'

方法示例

1 2	`const stageCallback = stage => console.log('stage: ', stage) room.startPlayAudioFile({ url: 'xxxx', elementId: 'yyy', stageCallback: stageCallback })`

stopPlayAudioFile({ elementId })

该方法取消播放音频资源链接，取消播放的元素需要和 startPlayAudioFile 传入的元素id对应

参数名	必填	类型	说明
elementId	是	String	音频播放器id

方法示例

1	`room.stopPlayAudioFile({ elementId: 'yyy' })`

房间状态

switchOnlyAudioRoom({ onlyAudio }) -> {Promise}

该方法切换房间模式到纯音频房间

参数名	必填	类型	说明
onlyAudio	是	Boolean	是否切换纯音频房间

方法示例

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

服务器录制和本地录制

startServerRecord

该方法开始服务器端录制
连续调用两次startServerRecord（即没调用stopServerRecord就再次调用startServerRecord）将以第1次调用为准

参数名	必填	类型	说明
spec	否	Object	录制配置，详细配置信息如下

spec

参数名	类型	说明
recordMode	String	录制模式 (`standard`：标准常规录制), (`mix`: 自定义混流录制)
mixStreamParams	Object	混流模式参数，仅混流模式生效，详细说明如下

mixStreamParams

参数名	类型	说明
template	Number	混流布局模板ID，0等分布局; 1画中画布局; 2自定义布局
backgroundColor	String	颜色值
customConfig	Object	自定义配置，配置说明如下

customConfig

参数名	类型	说明
backgroundColor	String	颜色值，如设置，优先级高于 `mixStreamParams.backgroundColor`
noStreamTimeout_s	Number	停止混流时限，开始混流后，房间中没有用户的流，停止混流时限，单位为（秒:s）
videoLayout	Array	自定义用户的视频流样式，数组中传入用户样式对象`videoLayoutUser`，用户样式对象说明如下

videoLayoutUser

参数名	类型	说明
uid	String	用户id, 若视频流为桌面共享流，则id应为 `uid:screen`
x_coord	Number	窗口x坐标，取值为相对于整个视频宽度百分比
y_coord	Number	窗口y坐标，取值为相对于整个视频高度百分比
width	Number	窗口宽，取值为相对于整个视频宽度百分比
height	Number	窗口高，取值为相对于整个视频高度百分比
alpha	Number	窗口透明度
play_video	Boolean	是否播放视频，默认播放true
play_audio	Boolean	是否播放音频，默认播放true

方法示例

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

该方法停止服务器端录制
方法示例

1	`room.stopServerRecord()`

pauseServerRecord

该方法暂停服务器端录制
方法示例

1	`room.pauseServerRecord()`

resumeServerRecord

该方法恢复服务器端录制
方法示例

1	`room.resumeServerRecord()`

getServerRecordState

该方法获取服务器录制状态，返回录制状态枚举值
录制状态枚举值见服务器录制状态
方法示例

1	`const recordState = room.getServerRecordState()`