TrackModeSession 类
TrackModeSession
是 Track 模式下的房间管理模块,所有和房间有关系的操作都通过这个模块来实现。
构造函数
import * as QNRTC from "pili-rtc-web";
const myRoom = new TrackModeSession();
无论重复几次加入离开房间,确保一个页面只能有一个房间模块的实例
userId
string
| undefined
类型 表示自己在房间中的 userId
,只有成功加入房间后才有值
roomName
string
| undefined
类型 表示当前房间的名称,只有成功加入房间后才有值
users
User>
类型 Array<表示房间当前的用户列表,具体每个 User
的详细信息可以参考 User 模块。如果没有加入房间,将会返回空列表。
trackInfoList
TrackInfo>
类型 Array<表示房间中当前所有其他人的 TrackInfo
,每次房间中有人发布或者取消发布,这个值都会自动更新。
roomState
number
类型 表示当前房间的连接状态,如果房间不是已连接的状态,除了离开房间/加入房间以外的方法都不能调用。如果想感知房间的 roomState
变化,可以通过监听 room-state-change
事件来实现,具体参见页面下方的 事件列表
enum RoomState {
Idle = 0, // 未连接
Connecting = 1, // 正在连接
Connected = 2, // 已连接
Reconnecting = 3, // 正在重新连接
}
publishedTracks
Track>
类型 Array<房间中自己所有已经发布的 Track
对象列表
subscribedTracks
Track>
类型 Array<房间中自己所有已经订阅的 Track
对象列表
mergeStreamTracks
Array<string>
类型 房间中已经添加到合流画面中的 trackId
列表, 关于合流的详细细节可以参考 合流转推
joinRoomWithToken(roomToken, userData)
加入房间
string
roomToken: 加入房间的凭证 token,详细可以参考 加入房间
string
| undefined
userData: 用户的额外数据
User>>
返回: Promise<Array<异步操作完成后,会返回当前加入房间的用户列表
publish(tracks)
发布媒体对象
Track>
tracks: Array<传入 Track
对象,将这些媒体数据发布到房间中。
可以通过 getLocalTracks 采集本地的
Track
对象。
Promise<void>
返回: 异步操作完成后,认为发布成功
unpublish(trackIds)
取消发布
Array<string>
trackIds: 想要取消发布的 trackId
列表,trackId
可以通过 TrackInfo 来获取
取消发布后,SDK 不会自动释放对应的
Track
对象,还可以正常播放,如果想手动释放,参考释放媒体对象
Promise<void>
返回: 异步操作完成后,认为取消发布成功
subscribe(trackIds)
订阅远端的 Track
Array<string>
trackIds: 想要订阅的 trackId
列表,trackId
可以通过 TrackInfo 来获取
Track>
返回: Promise<异步操作完成后,会返回和提供 trackId
对应的 Track
对象
unsubscribe(trackIds)
取消订阅
Array<string>
trackIds: 想要取消订阅的 trackId
列表,trackId
可以通过 TrackInfo 来获取
Promise<void>
返回: 异步操作完成后,认为取消订阅成功
取消订阅后,SDK 会自动释放对应的
Track
对象
muteTracks(tracks)
将自己本地已经发布的 Track
对象静音或者取消静音,这个静音动作会被广播给全房间,其他用户可以通过 mute-tracks
事件来感知。
Array<{trackId: string, muted: boolean}>
tracks: 一个列表,每个列表项有一个 trackId
和 muted
项,表示这个 Track
的静音状态。
视频 Track 和音频 Track 都可以设置静音,静音操作的本质就是保留数据通道但是不发送数据,视频 Track 静音后会黑屏。
kickoutUser(userId)
将指定的目标用户踢出房间,只有拥有管理员权限的用户才能调用此方法,用户的权限是在加入房间时提供的 roomToken
中指定的。
string
userId: 目标用户的用户名
Promise<void>
返回 异步操作完成后,认为踢出房间成功
createMergeJob(id, option)
创建一个默认合流以外的合流 Job。默认情况下,一个房间只能合成一路 RTMP 流,这一路 RTMP 的设定是通过 七牛控制台 或者通过 服务端 API 来配置。在部分特殊场景下,可能需要一个房间合成多路 RTMP 流,此时就可以使用这个 API 创建一个新的合流 Job。
string
id: 指定这个合流 Job 的 ID,不同的合流 Job 通过这个 id 来区分,在合流 API 中,如果没有传入 JobID,就认为使用默认的合流。
MergeJobOption
option: 配置这个合流 Job,具体配置可以见下:
Promise<void>
返回 异步操作完成后,认为创建合流 Job 成功
MergeJobOption {
publishUrl: string; // 这个 JOB 最终输出的 RTMP 地址
height?: number; // 输出画面的宽度
width?: number; // 输出画面的高度
fps?: number; // 输出流的帧率
kbps?: number; // 输出流的码率
audioOnly?: boolean; // 是否只合流音频,默认 false
// 合流画面伸缩模式,分别是充满容器、适应于容器、拉伸以充满容器
stretchMode?: "aspectFill" | "aspectFit" | "scaleToFit";
// 水印设置, WaterMark 的配置见下
watermarks?: Array<WaterMark>;
}
WaterMark {
w: number; // 水印的宽度
h: number; // 水印的高度
x: number; // 水印的水平位置
y: number; // 水印的垂直位置
file: string; // 水印的图片地址
}
setDefaultMergeStream(width, height, jobId?)
开启默认合流,默认合流布局的逻辑是 覆盖画面 和 尽量等分,具体的合流使用可以参考 合流转推
number
width: 默认合流输出的画面宽度,一般和控制台或者服务端设置的对应
number
height: 默认合流输出的画面高度,一般和控制台或者服务端设置的对应
string
可选
jobId: 指定这个默认合流的合流 Job,关于 Job 的介绍查看 createMergeJob,大部分情况不需要设置这个值
请确保一个房间在同一时刻只有一个用户调用此方法
addMergeStreamTracks(mergeOpts, jobId?)
通过指定 trackId
的方式将将指定的 Track
加入到合流画面之中
Array<TrackMergeOptions>
mergeOpts: TrackMergeOptions
的形式如下:
TrackMergeOptions {
trackId: string, // 指定要加入合流画面的 trackId
x: number, // 指定这个 Track 位于合流画面 x 轴的位置
y: number, // 指定这个 Track 位于合流画面 y 轴的位置
w: number, // 指定这个 Track 在合流画面上的宽度
h: number, // 指定这个 Track 在合流画面上的高度
z: number, // 指定这个 Track 在合流画面的覆盖等级(zIndex)
}
如果指定的 Track
是音频 Track,则 x
,y
,w
,h
,z
可以不填。
string
可选
jobId: 指定需要添加 Track 的合流 Job,关于 Job 的介绍查看 createMergeJob,大部分情况不需要设置这个值
当第一次调用这个方法成功的时候,就认为合流开始
removeMergeStreamTracks(trackIds)
通过 trackId
将之前指定的 Track
从合流画面中删除
Array<string>
trackIds: 指定的 trackId
列表
string
可选
jobId: 指定需要删除 Track 的合流 Job,关于 Job 的介绍查看 createMergeJob,大部分情况不需要设置这个值
stopMergeStream(jobId?)
string
可选
jobId: 指定一个合流 Job 停止合流,关于 Job 的介绍查看 createMergeJob,大部分情况不需要设置这个值
停止合流
leaveRoom()
离开房间,切断和房间以及流媒体服务的连接,释放所有订阅媒体的资源,roomState
会被重新置为 未连接
。如果需要重新加入房间,再次调用 joinRoomWithToken 即可
事件列表
room-state-change 房间状态改变
事件参数
- roomState: RoomState 当前的房间状态
myRoom.on("room-state-change", roomState => {
console.log("current roomState is", roomState);
})
user-join 房间有除自己以外的新用户加入
事件参数
- user: User 新加入的用户对象
myRoom.on("user-join", user => {
console.log("new user!", user);
})
user-leave 房间有除自己以外的用户离开
事件参数
- user: User 离开的用户对象
myRoom.on("user-leave", user => {
console.log("user leave!", user);
})
track-add 房间中有其他用户发布了 Track
事件参数
- tracks: Array<TrackInfo> 新发布 Track 的 TrackInfo
myRoom.on("track-add", tracks => {
console.log("new tracks", tracks);
})
track-remove 房间中有其他用户取消发布了 Track
事件参数
- tracks: Array<TrackInfo> 取消发布 Track 的 TrackInfo
myRoom.on("track-remove", tracks => {
console.log("track removed", tracks);
})
mute-tracks 房间中其他用户的 Track 修改了静音状态
事件参数
- tracks:
Array<{trackId: string, muted: boolean}>
关于设置静音可以参考 muteTracks
myRoom.on("mute-tracks", tracks => {
for (const track of tracks) {
console.log("track", track.trackId, "muted", track.muted);
}
})
disconnect 其他原因导致和房间连接断开且不可恢复
事件参数
- code:
number
断开连接的原因 - data:
any
不同断开连接的原因的data
字段不同,具体见下面的表格
原因 | code | data |
---|---|---|
被管理员踢出房间 | 10006 | { userId: string } userId 是操作踢人的用户 |
断线重连超时 | 10004 | 无 |
该用户在其他页面或终端登录 | 10022 | 无 |
token 过期 | 10002 | 无 |
房间人数已满 | 10011 | 无 |
myRoom.on("disconnect", (code, data) => {
if (code === 10006) {
console.log("被", data.userId, "踢出房间");
}
})
disconnect 触发后,SDK 会自动清空重置房间,如果有需要可以重新调用加入房间