StreamModeSession 类
StreamModeSession
是 Stream 模式下的房间管理模块,所有和房间有关系的操作都通过这个模块来实现。
构造函数
import * as QNRTC from "pili-rtc-web";
const myRoom = new StreamModeSession();
无论重复几次加入离开房间,确保一个页面只能有一个房间模块的实例
如果您所在的网络环境不支持 UDP
通信,可以在实例化时修改底层的媒体传输方式
const myRoom = new StreamModeSession({
transportPolicy: "preferUdp",
});
一共支持 3 个值,forceUdp
表示强制使用 UDP
传输, forceTcp
表示强制使用 TCP
传输, preferUdp
表示默认使用 UDP
, 当检测到 UDP
不通时回落到 TCP
,默认值为 forceUdp
。
userId
string
| undefined
类型 表示自己在房间中的 userId
,只有成功加入房间后才有值
roomName
string
| undefined
类型 表示当前房间的名称,只有成功加入房间后才有值
users
User>
类型 Array<表示房间当前的用户列表,具体每个 User
的详细信息可以参考 User 模块。如果没有加入房间,将会返回空列表。
roomState
number
类型 表示当前房间的连接状态,如果房间不是已连接的状态,除了离开房间/加入房间以外的方法都不能调用。如果想感知房间的 roomState
变化,可以通过监听 room-state-change
事件来实现,具体参见页面下方的 事件列表
enum RoomState {
Idle = 0, // 未连接
Connecting = 1, // 正在连接
Connected = 2, // 已连接
Reconnecting = 3, // 正在重新连接
}
stream
Stream | undefined
类型 表示自己已经发布的 Stream
对象,如果没有发布,则为 undefined
subscribeUsers
{ [userId: string]: Stream }
类型 表示自己所有已经订阅了的用户的 Stream 对象,比如我已经订阅了用户 user1
, 我可以通过如下方式拿到他的远端 Stream
对象
const user1Stream = myRoom.subscribeUsers["user1"];
joinRoomWithToken(roomToken, userData)
加入房间
string
roomToken: 加入房间的凭证 token,详细可以参考 加入房间
string
| undefined
userData: 用户的额外数据
User>>
返回: Promise<Array<异步操作完成后,会返回当前加入房间的用户列表
publish(stream)
发布媒体对象
Stream
stream:传入 Stream
对象,将这些媒体数据发布到房间中。不能重复调用,一次只能发布一个 Stream
。
可以通过 getLocalStream 采集本地的
Stream
对象。
Promise<void>
返回: 异步操作完成后,认为发布成功
unpublish()
取消发布
Promise<void>
返回: 异步操作完成后,认为取消发布成功
取消发布后,SDK 不会自动释放对应的
Stream
对象,还可以正常播放,如果想手动释放,参考释放媒体对象
subscribe(userId)
订阅远端的目标用户
string
userId 想要订阅用户的 userId
Stream>
返回: Promise<异步操作完成后,会返回和提供 userId
对应的 Stream
对象
unsubscribe(userId)
取消订阅
string
userId 想要取消订阅用户的 userId
Promise<void>
返回: 异步操作完成后,认为取消订阅成功
取消订阅后,SDK 会自动释放对应的
Stream
对象
mute(muteaudio, mutevideo)
将自己本地已经发布的 Stream
对象静音或者取消静音,这个静音动作会被广播给全房间,其他用户可以通过 user-mute
事件来感知。
boolean
muteaudio 是否静音音频,默认 false
boolean
mutevideo 是否黑屏视频,默认 false
视频和音频都可以设置 mute,mute 操作的本质就是保留数据通道但是不发送数据,视频 mute 后会黑屏。
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";
}
setDefaultMergeStream(width, height, jobId?)
开启默认合流,默认合流布局的逻辑是 覆盖画面 和 尽量等分,具体的合流使用可以参考 合流转推
number
width: 默认合流输出的画面宽度,一般和控制台或者服务端设置的对应
number
height: 默认合流输出的画面高度,一般和控制台或者服务端设置的对应
string
可选
jobId: 指定这个默认合流的合流 Job,关于 Job 的介绍查看 createMergeJob,大部分情况不需要设置这个值
请确保一个房间在同一时刻只有一个用户调用此方法
setMergeStreamLayout(userId, opt)
通过指定 userId
的方式将将指定用户的画面和声音加入到合流之中
指定的用户必须处于正在发布
的状态,否则不会有任何作用。
string
userId: 指定用户的 userId
MergeOptions
opt: MergeOptions
的形式如下:
MergeOptions {
x: number, // 指定该用户画面位于合流画面 x 轴的位置
y: number, // 指定该用户画面位于合流画面 y 轴的位置
w: number, // 指定该用户画面在合流画面上的宽度
h: number, // 指定该用户画面在合流画面上的高度
z: number, // 指定这个 Track 在合流画面的覆盖等级(zIndex)
hidden: boolean, // 是否不合流视频,默认为 false
muted: boolean, // 是否不合流音频,默认为 false
id?: string, // 可选,指定 jobId, 大部分情况不需要传入
}
Promise<void>
返回:注意!设置合流只对用户的单次发布有效,如果用户取消发布重新发布后没有再次设置,新的流不会沿用之前的配置。需要再次调用一次这个 API。
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);
})
user-publish 房间中有其他用户发布
事件参数
- user: User 该用户对象
myRoom.on("user-publish", user => {
console.log("user-publish!", user);
})
user-unpublish 房间中有其他用户取消发布
事件参数
- user: User 该用户对象
myRoom.on("user-unpublish", user => {
console.log("user-unpublish!", user);
})
user-mute 房间中其他用户的修改了静音状态
事件参数
- data:
{userId: string, muteAudio: boolean, muteVideo: boolean}
关于设置静音可以参考 mute
myRoom.on("user-mute", user => {
console.log("user", user.userId, "mute", user.muteAudio, user.muteVideo);
})
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 会自动清空重置房间,如果有需要可以重新调用加入房间