跳转至

房间管理类

房间管理类（Room）

Room

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

  • 方法示例

1
var room = TK.Room()

初始化设置

init

  • 该方法用于初始化Room对象

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

参数名 必填 类型 说明
authKey 是 String 请填写正确的企业Key，或者如果验证模式是token模式，请填写企业域名companyDomain。
onSuccess 是 Function 成功后的回调
onFailure 否 Function 失败后的回调
isCheckDevice 否 Boolean 是否检测设备的可用性，默认true
options 否 Object 初始化配置项，详细可选配置如下
  • options
参数 类型 说明
autoSubscribeAV Boolean 表示当房间中有用户发布音视频后，是否由SDK自动订阅该用户的音视频数据, 默认为 false
isGetFileList Boolean 是否获取文件列表, 默认为 false
tk_multistream Boolean 是否开启多视频模式, 默认为 false
tk_max_reconnect_count Number 发布音视频的最大重连次数，默认无限重连【注：如果需要设置无限重连请不要配置此属性】
tk_getroomfile Boolean 是否获取课件列表，默认为 false
  • 方法示例
1
    room.init(authKey, onSuccess, onFailure,isCheckDevice, options)

uninit

  • 该方法用于重置Room对象到未初始化状态
参数名 必填 类型 说明
onSuccess 是 Function 成功后的回调
onFailure 否 Function 失败后的回调
  • 方法示例
1
room.uninit(onSuccess,onFailure)

checkInit

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

  • 方法示例

1
var isInit = room.checkInit()

进出房间和房间信息

joinroom

  • 调用该方法加入已创建的房间。此方法应为Room类中首先被调用的方法。
参数名 必填 类型 说明
host 是 String web服务器域名（或ip）
port 是 String web服务器端口号
nickName 是 String 用户在房间中的昵称
userId 是 String 用户在房间中的ID，必须唯一。若为空，SDK将自动生成。如果企业通过token模式验证，该参数必须传递值
roomJsonOptions 否 Object 加入房间所需的基本参数。详细参数见下文说明
userJsonOptions 否 Object 用户自定义属性。
  • roomJsonOptions
参数名 类型 说明
serial String 房间ID
password String 房间密码(不同用户角色对应不同密码)
tk_token String [非必选项]企业token验证
tk_privilegeExpiredTs number [非必选项]token过期时间, 默认无限期0
  • 方法示例
1
room.joinroom(host, port, nickName, userId, roomJsonOptions, userJsonOptions)

joinroomEx

  • 调用该方法加入已创建的临时房间。此方法应为Room类中首先被调用的方法。
参数名 必填 类型 说明
roomId 是 String 自定义房间号
nickName 是 String 用户在房间中的昵称
userId 是 String 用户在房间中的ID，必须唯一。若为空，SDK将自动生成。如果企业通过token模式验证，该参数必须传递值
userJsonOptions 否 Object 用户自定义属性。
roomJsonOptions 否 Object 加入房间所需的基本参数。同上
  • 方法示例
1
room.joinRoomEx(roomId, nickName, userId, userJsonOptions, roomJsonOptions )

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

  • 该方法获取指定RoomUser对象

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

参数名 必填 类型 说明
userId 是 String 被获取用户的id
  • 方法示例 
    1
    var user = room.getUser("xxx");

getUsers

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

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

  • 方法示例

1
var users = room.getUsers();
- 返回值

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

getRoomUsers

  • 该方法获取用户列表。

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

参数名 必填 类型 说明
onSuccess 是 Function 成功回调,回调参数返回满足条件用户列表数组和总用户数【注：总人数受roles和search影响，原理同接口getRoomUserNum】
start 否 Number 开始位置，缺省为0
max 否 Number 最大获取个数,缺省为200
roles 否 Array 角色列表，缺省为所有角色，角色取值请见房间角色]
onFailure 否 Function 失败回调
search 否 String 昵称检索的内容，缺省为"" 【注：此处只对于用户昵称进行搜索且为模糊搜索】
order 否 Array 排序规则,详细规则见下文说明
  • order 规则补充说明：
  • 升序使用’asc’,降序使用’desc’
  • 最多3条排序规则，超过的规则将不起效,默认规则为根据加入的时间进行升序（即：order为[{ts:’asc’}]）

  • 规则在前面的优先起效，即order数组下标越小排序优先级越高

  • 方法示例

1
room.getRoomUsers(onSuccess, start, max ,roles , onFailure, search, order)

getRoomUserNum

  • 该方法获取用户总数。
参数名 必填 类型 说明
onSuccess 是 Function 成功回调,
roles 否 Array 角色列表，缺省为所有角色，角色取值请见房间角色
onFailure 否 Function 失败回调
search 否 String 昵称检索的内容，缺省为"" 【注：此处只对于用户昵称进行搜索且为模糊搜索】
  • 方法示例
1
room.getRoomUserNum(onSuccess, roles , onFailure, search)

getUserList

  • 该方法返回房间内当前用户列表和总数
  • 该方法返回 Promise
参数名 必填 类型 说明
options 否 Object 查询条件，参数及说明如下
  • options
参数名 类型 说明
start Number 列表中起始坐标，小班课非大房间模式下不支持
max Number 最大结果个数，小班课非大房间模式下不支持
roles Array 用户角色数组, 会返回符合查询角色的用户列表, 用户角色取值参考房间角色
nicknameScan String 用户昵称中的关键字, 小班课非大房间模式下不支持
  • 方法示例
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
var options = {
  start: 0,
  max: 200,
  roles: [TK.ROOM_ROLE.TEACHER, TK.ROOM_ROLE.STUDENT]
}
room.getUserList(options).then(res => {
  console.log("get user list: ", res.list)
  console.log("room users total num: ", res.total)
}).catch(err => {
  console.error("get user list failed, error: ", err)
})

信令和修改属性

sendMessage

  • 该方法发送聊天消息给指定用户
  • 接收者可通过监听TK.EVENT_TYPE.roomTextMessage事件获取消息内容
  • 发送消息默认节流频率为 1条/秒,如需强制发送，请在 options 中配置 isforceSend: true
参数名 必填 类型 说明
textMessage 是 String 文本消息内容
toId 否 String 消息接收者，缺省为所有人。可能取值请见房间角色
extendJson 否 Object 用户可自定义的扩展数据
options 否 Object 发送消息配置项。包含属性见下文说明
  • options
参数名 类型 说明
isToSender Boolean 是否发送给发送人, 默认为true
toRoles Array 发送给哪些用户角色。接收群体：toID 指定用户与 toRoles 指定身份用户的交集
isforceSend Boolean 是否不限制节流强制发送
  • 方法示例
1
2
3
4
5
6
7
8
9
var extenJson = {
  textfont : ’Arial’,
  fontsize : 14
};
//注意只有发给指定用户/特殊用户且自己需要收到时才传该参数
var options = {
  isToSender : true,
}; 
 room.sendMessage(‘hello world’, TK.MSG_TO_ALLUSER, extenJson, options);

pubMsg

  • 该方法发布用户自定义消息
  • 接收者可通过监听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事件
  • 方法示例
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
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,
};
 room.pubMsg(params);

delMsg

  • 该方法用于删除用户自定义消息
  • 接收者可通过监听TK.EVENT_TYPE.roomDelmsg事件获取消息内容
  • 删除消息的ID必须与pubMsg方法发布的消息ID对应，否则为无效消息，接收者不会收到事件
参数名 必填 类型 说明
name 是 String 消息名
id 是 String 消息ID
toID 是 String 消息接收者。角色取值请见消息发送角色
data 否 Object 消息携带的数据信息（不建议携带数据）
  • 方法示例
1
2
3
4
5
6
7
var params = {
   name : ‘sendTextMsg’,
   id : ‘sendTextMsg’,
   toID : TK.MSG_TO_ALLEXCEPTSENDER,
   data : {}
};
room.delMsg(params);

evictUser

  • 该方法用于将用户请出房间
  • 被请出房间的用户将会收到 TK.EVENT_TYPE.roomParticipantEvicted 事件
参数名 必填 类型 说明
userId 是 String 被请出房间的用户ID
causeJson 否 Object 请出房间的原因。用户自定义（如果包含"reason"参数，则reason必须小于400）
  • 方法示例
1
2
3
4
5
var cause = {
  reason : 100,
  say : ‘good-bye’
};
room.evictUser(‘user-id-123’, cause);

changeUserProperty

  • 该方法改变或添加某用户属性，并将属性变化通知给房间中的指定用户。
  • 被通知的用户会收到 TK.EVENT_TYPE.roomUserPropertyChanged 事件
  • 在大房间模式下，事件派发TK.EVENT_TYPE.roomUserPropertyChanged（用户属性改变）有限制, 详情请见 TK.EVENT_TYPE.roomUserPropertyChanged事件派发
参数名 必填 类型 说明
userId 是 String 被改变属性的用户ID
toId 是 String 被通知的用户。可能取值请见消息发送角色
properties 是 Object 修改的用户属性集合
  • 方法示例
1
2
3
4
5
6
7
8
9
var self = room.getMySelf();
var prop = {};
if (self.nickname === ‘tester’) {
    prop.nickname : ‘tester-abc’;
}
if (!self. hasOwnProperty(‘age’)) {
    prop.age = 18;
}
room.changeUserProperty(self.id, TK.MSG_TO_ALLUSER, prop);

batchChangeUserProperty

  • 该方法批量改变或添加某些用户属性，并将属性变化通知给房间中的指定用户。
  • 被通知的用户会收到 TK.EVENT_TYPE.roomUserPropertyChanged 事件
  • 在大房间模式下，事件派发TK.EVENT_TYPE.roomUserPropertyChanged（用户属性改变）有限制, 详情请见 TK.EVENT_TYPE.roomUserPropertyChanged 事件派发
参数名 必填 类型 说明
ids 是 Array 被改变属性的用户ID列表
toId 是 String 被通知的用户。可能取值请见消息发送角色
properties 是 Object 修改的用户属性集合
  • 方法示例
1
2
3
4
5
var ids=[ user1.id, user2.id, user3.id ] ; 
var prop = {
  age:20
};
room.batchChangeUserProperty(ids, TK.MSG_TO_ALLUSER, prop);

changeUserPropertyByRole

  • 该方法批量改变或添加某些角色的用户属性，并将属性变化通知给房间中的指定用户
  • 被通知的用户会收到 TK.EVENT_TYPE.roomUserPropertyChanged 事件
  • 在大房间模式下，事件派发TK.EVENT_TYPE.roomUserPropertyChanged（用户属性改变）有限制, 详情请见 TK.EVENT_TYPE.roomUserPropertyChanged 事件派发
参数名 必填 类型 说明
roles 是 Array 被改变属性的角色列表，可能取值请见房间角色
toId 是 String 被通知的用户。可能取值请见消息发送角色
properties 是 Object 修改的用户属性集合
  • 方法示例
1
2
3
4
5
var roles=[TK.ROOM_ROLE.STUDENT, TK.ROOM_ROLE.ASSISTANT] ;
var prop = {
  age:20
};
room.changeUserPropertyByRole(roles, TK.MSG_TO_ALLUSER, prop);

发布和播放音视频

publishVideo

  • 该方法将自己的视频发布出去
  • 房间中的人会收到 TK.EVENT_TYPE.roomUserVideoStateChanged 事件, 解析事件消息后视频为发布状态,可通过调用playVideo方法观看发布者的视频。
  • 如果是多视频模式调用该方法时需要传入设备的ID
参数名 必填 类型 说明
videoinputDeviceId 否 String [多视频模式必选]视频设备ID
  • 方法示例
1
room.publishVideo();

unpublishVideo

  • 该方法停止发布自己的视频
  • 房间中的人会收到 TK.EVENT_TYPE.roomUserVideoStateChanged 事件, 解析事件消息后视频为取消发布状态,可通过调用unplayVideo方法关闭发布者的视频。
  • 如果是多视频模式调用该方法时需要传入设备的ID
参数名 必填 类型 说明
videoinputDeviceId 否 String [多视频模式必选]视频设备ID
  • 方法示例
1
room.unpublishVideo();

publishAudio

  • 该方法将自己的音频发布出去

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

  • 方法示例

1
room.publishAudio();

unpublishAudio

  • 该方法将自己的音频发布出去

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

  • 方法示例

1
room.unpublishAudio();

playVideo

  • 该方法用于播放指定用户的视频
  • 若播放本地视频，可直接调用
  • 若播放其他用户视频，必须在收到TK.EVENT_TYPE.roomUserVideoStateChanged事件后且视频为发布状态方可调用
参数名 必填 类型 说明
userId 是 String 指定的用户ID。若为""，则播放自己视频
elementId 是 String dom元素ID。该dom元素用于盛放播放器
options 否 Object 播放配置项。包含属性见下文说明
onFailure 否 Function 失败回调
videoinputDeviceId 否 String [多视频模式必选]视频设备ID
onSuccess 否 Function 成功回调
  • options
参数 类型 说明
loader Boolean 用于表示未加载到视频数据时是否显示‘加载中’样式,默认为 true
mode Number 用于表示视频显示模式（是否裁减），取值见 视频显示模式, 默认为 TK_VIDEO_MODE.ASPECT_RATIO_CONTAIN 不裁剪
  • 方法示例
1
2
3
4
5
room.playVideo(‘user-id-123’, ‘element-id-123’, {}, function(err) {
 console.error(‘play video failed. error: ’ + err);
}, "", function() {
console.log("play video success")
});

unplayVideo

  • 该方法用于停止播放指定用户的视频
参数名 必填 类型 说明
userId 是 String 指定的用户ID。若为""，则停止播放自己视频
onFailure 否 Function 失败回调
videoinputDeviceId 否 String [多视频模式必选]视频设备ID
options 否 Object 播放配置项。包含属性见下文说明
onSuccess 否 Function 成功回调
  • options
参数 类型 说明
mediaType String 用于获取视频播放器的保存ID，取值见媒体流类型, 默认为 TK.STREAM_VIDEO
  • 方法示例
1
2
3
4
5
room.unplayVideo(‘user-id-123’, function(err) {
  console.error(‘stop playing video failed. error: ’ + err);
}, "", {}, function(){
  console.log("stop play video success")
});

playAudio

  • 该方法用于播放指定用户的音频
  • 若播放其他用户音频，必须在收到TK.EVENT_TYPE.roomUserAudioStateChanged事件后且音频为发布状态方可调用
  • 用户不能播放自己的音频
参数名 必填 类型 说明
userId 是 String 指定的用户ID。
onFailure 否 Function 失败回调
onSuccess 否 Function 成功回调
  • 方法示例
1
2
3
4
5
room.playAudio(‘user-id-123’, function(err) {
  console.error(‘play audio failed. error: ’ + err);
}, function(){
  console.log("play audio success")
});

unplayAudio

  • 该方法停止播放指定用户的音频
参数名 必填 类型 说明
userId 是 String 指定的用户ID。
onFailure 否 Function 失败回调
onSuccess 否 Function 成功回调
  • 方法示例
1
2
3
4
5
room.unplayAudio (‘user-id-123’, function(err) {
  console.error(‘stop play audio failed. error: ’ + err);
}, function() {
  console.log("stop play audio success")
});

设置本地音视频属性

getDeviceMgr

  • 该方法返回设备管理类对象

  • 注：DeviceMgr中的方法可由TK.DeviceMgr直接调用，并非一定要通过此接口获得DeviceMgr对象才能使用

  • 方法示例

1
var devMgr = room.getDeviceMgr();

setLocalVideoMirror

  • 该方法设置本地视频是否启用视频镜像
  • 房间默认不启用本地视频镜像
参数名 必填 类型 说明
isMirror 是 Boolean 本地视频是否启用视频镜像
videoinputDeviceId 否 String [多视频模式必选]视频设备ID
  • 方法示例
1
room.setLocalVideoMirror(true);

getVideoProfile

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

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

1
var profile = room.getVideoProfile (true);
- 返回值

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

setVideoProfile

  • 该方法设置视频分辨率属性
  • 注：设置的分辨率及帧率不可超过预约房间时设定的最大分辨率的乘积（width*height）及最大帧率，若分辨率超出，则根据比例缩放当前设置的分辨率，若帧率超出，则设置为预约房间时的最大帧率。
参数名 必填 类型 说明
profile 是 Object 视频分辨率属性信息。详细属性见下文说明
onFailure 否 Function 失败回调
videoinputDeviceId 否 String [多视频模式必选]视频设备ID
onSuccess 否 Function 成功回调
  • profile
参数名 类型 说明
width Number 水平分辨率
height Number 垂直分辨率
maxfps Number 最大帧率
  • 方法示例
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
var profile = {
    width : 80,
    height : 60,
  maxfps : 10
};
room.setVideoProfile(profile, function(err) {
  console.error("set video profile failed", err)
}, "",function() {
  console.log("set video profile success")
});

getAudioVolume

  • 该方法获取指定用户的当前时刻音频采集音量（即麦克风输入音量）
  • 如果您想实时表示本地或远端音量的变化，我们建议您使用registerAudioVolumeListener接口来实时获取
参数名 必填 类型 说明
userId 是 String 指定的用户ID
onVolume 是 Function 获取音量回调。参数为当前时刻音量值。取值区间[0,100]
onFailure 否 Function 失败回调
type 否 String 需要操作媒体类型,默认为TK.MEDIA_TYPE.DEVICE_AV, 取值范围见媒体类型
  • 方法示例
1
2
3
room.getAudioVolume(room.getMySelf().id, function(vol) {
  console.log(‘current volume: ’ + vol);
});

setRemoteAudioVolume

  • 该方法设置指定用户的音频播放音量
  • 此方法在调用playAudio方法后方能生效
参数名 必填 类型 说明
volume 是 Number 播放音量值。取值区间[0,100]
userId 是 String 指定的用户ID
onFailure 否 Function 失败回调
type 否 String 需要操作媒体类型, 默认为TK.MEDIA_TYPE.DEVICE_AV, 取值范围见媒体类型
onSuccess 否 Function 成功回调
  • 方法示例
1
2
3
4
5
room.setRemoteAudioVolume(80, "userId-xxx", (error) => {
  console.error("error: ", error)
}, "", function() {
  console.log("set volume success")
})

registerAudioVolumeListener

  • 该方法用于获取指定用户的实时音量变化，无需用户自己使用setTimeout或setInterval定时调用getAudioVolume方法，是getAudioVolume 的升级方法。
参数名 必填 类型 说明
userId 是 String 指定的用户ID。若为’’，则监听自己的音量变化
msInterval 是 Number 毫秒级时间间隔。最小值为50
onVolume 是 Function 获取音量回调。取值区间[0,100]
onFailure 否 Function 失败回调
type 否 String 需要操作媒体类型, 默认为TK.MEDIA_TYPE.DEVICE_AV, 取值范围见媒体类型
  • 方法示例
1
2
3
room.registerAudioVolumeListener (room.getMySelf().id, 80, function(vol, userId) {
  console.log(‘user: ’ + userId + ‘. volume: ’ + vol);
});

unregisterAudioVolumeListener

  • 该方法移除指定用户的音量监听器
参数名 必填 类型 说明
userId 是 String 指定的用户ID。若为’’，则移除自己的音量监听器
onFailure 否 Function 失败回调
type 否 String 需要操作媒体类型, 默认为TK.MEDIA_TYPE.DEVICE_AV, 取值范围见媒体类型
onSuccess 否 Function 成功回调
  • 方法示例
1
2
3
4
5
room.unregisterAudioVolumeListener (room.getMySelf().id, (error) => {
  console.error("error: ", error)
},"", function(){
  console.log("unregister success")
})

disableVideoDevice

  • 该方法用于改变自己视频设备的禁用状态，房间视频设备默认不禁用
  • 设置视频设备禁用后，将不会打开本地摄像头，无法发布视频数据。
  • 如需发布视频，需要取消禁用后重新调用 publishVideo
参数名 必填 类型 说明
tk_disablevideo 是 Boolean 是否禁用视频设备
  • 方法示例
1
room.disableVideoDevice (true)

setAutoProcessDeviceChangeEvent

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

分享和播放桌面共享流

startShareScreen

  • 该方法开始进行屏幕共享
  • 桌面共享流的接收者会收到 TK.EVENT_TYPE.roomUserScreenStateChanged 事件, 解析事件消息后共享流为发布状态,可通过调用playRemoteScreen方法播放共享者的屏幕视频
参数名 必填 类型 说明
screenInfo 否 Object 共享参数，参数配置见下文
onFailure 否 Function 失败回调
onSuccess 否 Function 成功回调
  • screenInfo
参数名 必填 类型 说明
toID 否 String 共享流接收者，默认为TK.MSG_TO_ALLUSER, 可选值见 消息发送角色
  • 方法示例
1
2
3
4
5
room.startShareScreen({}, function(err){
  console.error("share screen error: ", err)
}, function() {
  console.log("share screen success")
})

stopShareScreen

  • 该方法结束屏幕共享
  • 桌面共享流的接收者会收到 TK.EVENT_TYPE.roomUserScreenStateChanged 事件, 解析事件消息后共享流为取消发布状态,可通过调用unplayRemoteScreen方法关闭共享者的屏幕视频
参数名 必填 类型 说明
onFailure 否 Function 失败回调
onSuccess 否 Function 成功回调
  • 方法示例
1
2
3
4
5
room.stopShareScreen(function(err) {
  console.error("stop share error: ", err)
}, function() {
  console.log("stop share success")
})

playRemoteScreen

  • 该方法用于播放屏幕共享流
  • 必须在收到TK.EVENT_TYPE.roomUserScreenStateChanged事件后且共享流为发布状态方可调用
参数名 必填 类型 说明
userId 是 String 共享者的用户id
elementId 是 String dom元素ID。该dom元素用于盛放播放器
options 否 Object 播放配置项，具体参数见下文
onFailure 否 Function 失败回调
onSuccess 否 Function 成功回调
  • options
参数名 必填 类型 说明
mirror 否 Boolean 视频是否镜像显示，默认不镜像
mode 否 String 用于表示视频显示模式（是否裁减），取值见视频显示模式 , 默认为 TK_VIDEO_MODE.ASPECT_RATIO_CONTAIN 不裁剪
loader 否 Boolean 未加载到视频数据时是否显示‘加载中’样式,默认为 true
  • 方法示例
1
2
3
4
5
room.playRemoteScreen("user-1233", "user-123-dom", {}, function(err){
  console.error("play screen error:", err)
}, function() {
  console.log("play screen success")
})

unplayRemoteScreen

  • 该方法用于关闭播放屏幕共享流
参数名 必填 类型 说明
userId 是 String 共享者的用户id
onFailure 否 Function 失败回调
onSuccess 否 Function 成功回调
  • 方法示例
1
2
3
4
5
room.unplayRemoteScreen("user-1233", function(err) {
  console.error("stop play screen error: ", err)
}, function(){
  console.log("stop play screen success")
})

分享和播放媒体流

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

startShareMedia

  • 该方法开始共享媒体文件
  • 共享成功后，房间内的人会收到TK.EVENT_TYPE.roomUserMediaStateChanged事件，解析事件消息后媒体流为发布状态,可通过调用playRemoteMedia方法播放媒体流
  • 因为该媒体文件是由服务器进行共享，因此自己收到TK.EVENT_TYPE.roomUserMediaStateChanged后也需要调用playRemoteMedia进行播放
参数名 必填 类型 说明
url 是 String 共享的媒体文件的绝对路径
isVideo 否 Boolean 是否是视频文件，缺省为false
onFailure 否 Function 失败回调
options 否 Object 共享配置项, 说明见下文
onSuccess 否 Function 成功回调
  • options
参数名 必填 类型 说明
toID 否 String 发送给谁 , 默认发送给所有人
attrs 否 Object 流携带的attributes数据
  • 方法示例
1
2
3
4
5
room.startShareMedia("xxx-url", false, function(err) {
  console.error("share media error:", err)
}, {}, function(){
  console.log("share media success")
})

stopShareMedia

  • 该方法结束共享媒体文件
  • 结束共享后，房间内的人会收到TK.EVENT_TYPE.roomUserMediaStateChanged事件，解析事件消息后媒体流为取消发布状态,可通过调用unplayRemoteMedia方法关闭媒体流
  • 因为该媒体文件是由服务器进行共享，因此自己收到TK.EVENT_TYPE.roomUserMediaStateChanged后也需要调用unplayRemoteMedia进行关闭
参数名 必填 类型 说明
onFailure 否 Function 失败回调
onSuccess 否 Function 成功回调
options 否 Object 配置项，说明见下文
  • options
参数名 必填 类型 说明
onlyStopMyself 否 Boolean 是否只停止自己共享的媒体文件
  • 方法示例
1
2
3
4
5
room.stopShareMedia(function(err) {
  console.error("stop share media error:", err)
}, function() {
  console.log("stop share media success")
})

pauseShareMedia

  • 该方法暂停共享媒体文件
参数名 必填 类型 说明
bPause 是 Boolean 是否暂停（或恢复）共享媒体文件
onFailure 否 Function 失败回调
onSuccess 否 Function 成功回调
  • 方法示例
1
2
3
4
5
room.pauseShareMedia(true,function(err) {
  console.error("pause share media error:", err)
}, function() {
  console.log("pause share media success")
})

seekMedia

  • 该方法控制共享媒体文件的进度，使媒体文件跳跃到指定的时间点继续播放
参数名 必填 类型 说明
positionPercent 是 Number 指定进度的百分比，取值范围为[0-1]
onFailure 否 Function 失败回调
onSuccess 否 Function 成功回调
  • 方法示例
1
2
3
4
5
room.seekMedia(0.5,function(err) {
  console.error("seek media error:", err)
}, function() {
  console.log("seek media success")
})

playRemoteMedia

  • 该方法播放房间中共享的媒体文件
  • 在收到TK.EVENT_TYPE.roomUserMediaStateChanged事件后，若媒体流为发布状态，且媒体流类型为media，则调用此方法观看
参数名 必填 类型 说明
userId 是 String 共享者的用户ID
elementId 是 String Dom元素ID。该Dom元素用于盛放播放器
options 否 Object 播放配置项，详细配置见下文
onFailure 否 Function 失败回调
onSuccess 否 Function 成功回调
  • options
参数名 必填 类型 说明
mirror 否 Boolean 视频是否镜像显示，默认不镜像
mode 否 String 用于表示视频显示模式（是否裁减），取值见 视频显示模式 , 默认为 TK_VIDEO_MODE.ASPECT_RATIO_CONTAIN 不裁剪
loader 否 Boolean 未加载到视频数据时是否显示‘加载中’样式,默认为 true
  • 方法示例
1
2
3
4
5
room.playRemoteMedia("user-123", "user-123-dom",{},function(err) {
  console.error("playRemoteMedia error:", err)
}, function() {
  console.log("playRemoteMedia success")
})

unplayRemoteMedia

  • 该方法停止播放共享的媒体文件
  • 在收到TK.EVENT_TYPE.roomUserMediaStateChanged事件后，若媒体流为取消发布状态，且媒体流类型为media，则调用此方法关闭播放器
参数名 必填 类型 说明
userId 是 String 共享者的用户ID
onFailure 否 Function 失败回调
onSuccess 否 Function 成功回调
  • 方法示例
1
2
3
4
5
room.unplayRemoteMedia("user-123", function(err) {
  console.error("unplayRemoteMedia error:", err)
}, function() {
  console.log("unplayRemoteMedia success")
})

playRemoteMediaFile

  • 该方法播放远端共享的媒体文件（拓课客户端用户共享的用户本地媒体文件）
  • 在收到TK.EVENT_TYPE.roomUserMediaStateChanged事件后，若媒体流为发布状态，且媒体流类型为file，则调用此方法观看
参数名 必填 类型 说明
userId 是 String 共享者的用户ID
elementId 是 String Dom元素ID。该Dom元素用于盛放播放器
options 否 Object 播放配置项，详细配置见下文
onFailure 否 Function 失败回调
onSuccess 否 Function 成功回调
  • options
参数名 必填 类型 说明
mirror 否 Boolean 视频是否镜像显示，默认不镜像
mode 否 String 用于表示视频显示模式（是否裁减），取值见 视频显示模式 , 默认为 TK_VIDEO_MODE.ASPECT_RATIO_CONTAIN 不裁剪
loader 否 Boolean 未加载到视频数据时是否显示‘加载中’样式,默认为 true
  • 方法示例
1
2
3
4
5
room.playRemoteMediaFile("user-123", "user-123-dom",{},function(err) {
  console.error("playRemoteMediaFile error:", err)
}, function() {
  console.log("playRemoteMediaFile success")
})

unplayRemoteMediaFile

  • 该方法关闭播放远端共享的媒体文件（拓课客户端用户共享的用户本地媒体文件）
  • 在收到TK.EVENT_TYPE.roomUserMediaStateChanged事件后，若媒体流为取消发布状态，且媒体流类型为file，则调用此方法关闭播放器
参数名 必填 类型 说明
userId 是 String 共享者的用户ID
onFailure 否 Function 失败回调
onSuccess 否 Function 成功回调
  • 方法示例
1
2
3
4
5
room.unplayRemoteMediaFile("user-123", function(err) {
  console.error("unplayRemoteMediaFile error:", err)
}, function() {
  console.log("unplayRemoteMediaFile success")
})

房间文件管理

getFileList

  • 该方法获取文件列表，返回文件信息数组

  • 若调用init时options未配置tk_getroomfile: true，sdk不会自动获取课件列表，此时返回空数组[]

  • 方法示例

1
var fileList = room.getFileList()

getFileinfo

  • 该方法获取文件信息，返回文件信息对象
  • 根据文件id从文件列表中获取文件信息，如果文件列表没有对应的文件，则返回undefined
参数名 必填 类型 说明
fileid 是 Number 文件id
  • 方法示例
1
var fileInfo = room.getFileinfo(123)

uploadRoomFile

  • 该方法用于上传文件
参数名 必填 类型 说明
filename 是 String 文件名
filetype 是 String 文件类型
filedata 是 Object 文件数据，File对象
onSuccess 是 Function 成功回调。第一个参数为code，表示上传的状态码（状态码为0）; 第二个参数response表示上传成功服务器返回的数据
onProgress 否 Function 上传进度回调，第一个参数为evt，表示上传进度的event对象,第二个参数progress表示上传的百分比（0-100）
onFailure 否 Function 上传失败的回调，第一个参数为code，表示上传失败的错误码，详情请参考全局错误码
options 否 Object 上传配置项，详细配置见下文
  • options
参数名 必填 类型 说明
isWritedb 否 Boolean 是否写入数据库，缺省为false
ischeckRoomConnected 否 Boolean 是否检测房间连接情况，缺省为true
  • 方法示例
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
room.uploadRoomFile(""xx.mp4"", "mp4", filedata, 
(code, res) => {
  console.log("upload success: ", code, res)
}, 
(e, progress) => {
  console.log("upload progress: ", progress + "%")
},
(code, error) => {
  console.error("upload error: ", code , error)
})

deleteRoomFile

  • 该方法用于删除文件
参数名 必填 类型 说明
fileid 是 Number 文件id
onSuccess 是 Function 成功回调，第一个参数为code，表删除文件的状态码（状态码为0）,第二个参数response表示删除文件成功服务器返回的数据
onFailure 否 Function 上传失败的回调，第一个参数为code，表示删除文件失败的错误码，详情请参考全局错误码
  • 方法示例
1
2
3
4
5
6
7
room.deleteRoomFile(1234, 
(code, res) => {
  console.log("delete success:", code, res)
}, 
(code, error) => {
  console.error("delete error:", code, error)
})

房间状态和线路

switchOnlyAudioRoom

  • 该方法切换房间模式到纯音频房间
参数名 必填 类型 说明
isSwitch 是 Boolean 是否切换纯音频房间
  • 方法示例
1
room.switchOnlyAudioRoom(true)

requestServerList

  • 该方法用于获取可用服务器信息，获取后用户可根据自己实际位置调用switchServer选择不同服务器，以提升房间会话体验。
参数名 必填 类型 说明
host 是 String 服务器域名
port 是 Number 服务器端口
onSuccess 是 Function 成功回调，回调参数为请求所得服务器列表数组
onFailure 否 Function 失败回调
options 否 Object 配置项，详细说明如下
  • options
参数名 类型 说明
protocol String 协议类型。取值为 http 或 https，默认为 https
  • 方法示例
1
2
3
4
5
6
7
room.requestServerList("www.xxx.com", 443, 
(res) => {
  console.log("request server list: ", res)
}, 
(code, error) => {
  console.error("request error: ", code, error)
})

switchServer

  • 该方法用于将当前使用的服务器切换为serverName指定的服务器。由于服务器地理位置不同，可能造成使用不同服务器时，在房间中的会话体验不同，请用户根据自己的情况，合理选择。
参数名 必填 类型 说明
serverName 是 String 服务器名称。通过requestServerList接口获得
  • 方法示例
1
room.switchServer("xxx")

服务器录制和本地录制

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
  • 方法示例
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
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()

© 2016-2023 北京拓课网络科技有限公司 版权所有  京ICP备17018423号-1 京公网安备11010502043461号