@netless/combine-player
v1.1.6
Published
同步 白板回放 和 video 的项目
Downloads
75
Readme
@netless/combine-player
同步 白板回放 和 video 的项目
此项目用于代替 white-web-sdk
中的同步功能,[email protected]
版本后将取消同步功能,并有此项目接手。
由来
因 white-web-sdk
在同步过程中,没有很好的适配 video
丢帧的问题。如果在 white-web-sdk
里修复丢帧,将会增加代码的复杂度,所以把同步功能单独抽成一个 project
来进行维护。
安装
yarn
yarn add @netless/combine-player
npm
npm install @netless/combine-player
快速上手
const CombinePlayerFactory = require("@netless/combine-player");
whiteWebSdk.replayRoom({room: "$UUID", roomToken: "$ROOM_TOKEN"})
.then(async (player) => {
const factoryParams = {
url: "https://my-domain/assets/rtc-record.mp4",
videoDOM: videoDom, // 用于存放视频播放器的 div 节点
};
const combinePlayer = new CombinePlayerFactory(player, factoryParams).create();
});
// 用户点击播放时触发函数
const playButton = () => {
combinePlayer.play();
}
兼容
如果您的项目之前使用了 [email protected]
之前的版本来做同步,并因为业务需求想进行升级时,则需要参考下面的说明,来替换您的项目代码
在使用此项目后,您不应该在直接操作 white-web-sdk
里的 player
对象,而应该操作 combinePlayer
对象。
初始化
在 [email protected]
之前的版本中,我们一直推荐您在页面加载完成的时候,去调用: player.seekToProgressTime(0)
,来进行初始化回放数据。
而现在这一步操作已经被集成到 @netless/combine-player
里了,您不需要在去调用 player.seekToProgressTime(0)
,如果因为历史问题,必须要调用的话,也请调用 combinePlayer.seek(0)
。
成员属性
playbackSpeed
此方法目前由 @netless/combine-player
的 playbackRate
属性代替。
其用法为:
combinePlayer.playbackRate;
timeDuration
此方法目前由 @netless/combine-player
的 timeDuration
属性代替。
其用法为:
combinePlayer.timeDuration.duration;
其返回值和之前的不一致,详情请参考: timeDuration
成员方法
player.play()
此方法目前由 @netless/combine-player
的 play
方法代替。
其用法为:
combinePlayer.play();
player.pause()
此方法目前由 @netless/combine-player
的 pause
方法代替。
其用法为:
combinePlayer.pause();
player.seekToProgressTime(progressTime)
此方法目前由 @netless/combine-player
的 seek
方法代替。
其用法为:
combinePlayer.seek(ms);
player.stop()
此方法目前由 @netless/combine-player
的 stop
方法代替。
其用法为:
combinePlayer.stop();
注意事项
进度
如果您想获取整体的回放进度,可继续使用 player.progressTime
来进行获取,因 @netless/combine-player
本身就是负责同步的,所以 回放
和 video
的进度是一致的。
状态
如果您想获取当前回放的进度,您可以继续使用 player.phase
来获取,当然最好(十分推荐)是使用 @netless/combine-player
的成员方法来进行获取。
关于 @netless/combine-player
的状态获取,可参考: combinedStatus、setOnStatusChange
如果想保留之前的状态判断,可以通过以下代码进行转换:
switch (combinedStatus) {
case PublicCombinedStatus.PauseBuffering:
case PublicCombinedStatus.PlayingBuffering:
case PublicCombinedStatus.PauseSeeking:
case PublicCombinedStatus.PlayingSeeking: {
return PlayerPhase.Buffering;
}
case PublicCombinedStatus.Playing: {
return PlayerPhase.Playing;
}
case PublicCombinedStatus.Pause: {
return PlayerPhase.Pause;
}
case PublicCombinedStatus.Stopped: {
return PlayerPhase.Stopped;
}
case PublicCombinedStatus.Disabled: {
throw new Error("...");
}
}
接口
实例
const combinePlayerFactory = new CombinePlayerFactory(player, videoOptions, debug);
参数
player
其中 player
为 replayRoom
方法创建,具体可见: 构造 Player 对象
videoOptions
interface VideoOptions {
readonly url: string;
readonly videoElementID?: string;
readonly videoDOM?: HTMLVideoElement;
readonly videoJsOptions?: VideoJsPlayerOptions;
}
url(required)
选择要回放视频的 video 地址,以便进行同步
videoElementID(optional)
表明要选择哪一个 video DOM
元素的 id
如果此 id
的元素不是 video
将会报错
如果同时传入
videoElementID
和videoDOM
程序将会报错
videoDOM(optional)
表明要选择哪一个 video DOM
元素
如果元素不是 video
将会报错
如果
videoElementID
和videoDOM
都没传入,程序将自动创建一个video
元素。您可以通过:getVideoDOM
方法来获取此元素,详情可参考: getVideoDOM
videoJsOptions(optional)
video.js 实例化时的参数,详情可见: Video.js Options
默认情况下 @netless/combine-player
将会传入:
{
preload: "auto"
}
debug(optional)
是否开启 debug
模式,此模式将会把 @netless/combine-player
运行时的日志打印到 console
里
其默认值为: false
成员方法
getVideoDOM
获取 video
的 DOM
元素
const combinePlayerFactory = new CombinePlayerFactory(player, videoOptions, debug);
combinePlayerFactory.getVideoDOM();
create
创建 combinePlayer
对象
const combinePlayerFactory = new CombinePlayerFactory(player, videoOptions, debug);
combinePlayerFactory.create();
其成员方法参考: combinePlayer
combinePlayer
const combinePlayerFactory = new CombinePlayerFactory(player, videoOptions, debug);
const combinePlayer = combinePlayerFactory.create();
成员属性
playbackRate
获取/修改播放倍率,其默认值为: 1
// 获取当前播放速率
combinePlayer.playbackRate;
// 改变播放速率
combinePlayer.playbackRate = 2
timeDuration
获得回放总时长,其返回类型为:
interface TimeDuration {
readonly duration: number;
readonly video: number;
readonly whiteboard: number;
}
duration
取 video
和 whiteboard
最小值
video
video
的总时长
whiteboard
白板回放的总时长
combinedStatus
当前回放的组合状态。默认状态为: PauseBuffering
其返回值类型为:
enum PublicCombinedStatus {
PauseSeeking = "PauseSeeking",
PlayingSeeking = "PlayingSeeking",
Pause = "Pause",
PauseBuffering = "PauseBuffering",
PlayingBuffering = "PlayingBuffering",
Playing = "Playing",
Ended = "Ended",
Disabled = "Disabled",
Stopped = "Stopped",
}
PauseSeeking
当在暂停状态时,用户进行 seek,会到达此状态
详情可参考: seek
PlayingSeeking
当在播放状态时,用户进行 seek,会到达此状态
详情可参考: seek
Pause
当用户调用了 pause 方法时,会到达此状态
PauseBuffering
当当前是暂停状态,并且视频后面没有可播放的帧数据时,会到达此状态
PlayingBuffering
当当前正在播放时,下一帧没有可播放的帧数据时,会到达此状态
Playing
用户调用了 play 方法时,或用户调用了 seek
,并 seek
结束后,会到达此状态
Ended
白板回放
和 video
中有一端播放完毕,会到达此状态
Disabled
当出现意外时(有可能是@netless/combine-player
出现了 bug),会到达此状态。
Stopped
用户调用了 stop 方法时,会到达此状态
成员方法
play
开始播放及同步
combinePlayer.play();
pause
暂停播放
combinePlayer.pause();
seek
切换进度。该值会改变当前状态。
由于该方法需要发起网络请求,因此改变不会立即生效。
在等待过程中,当前状态会变为: PauseSeeking
或 PlayingSeeking
当 seek
结束后,状态会变为: Playing
或 Ended
combinePlayer.seek(ms);
stop
停止。当前状态会变为 Stopped
,此后 @netless/combine-player
实例将拒绝一切业务操作。
combinePlayer.stop();
setOnStatusChange
添加状态改变监听器,当状态发生改成时,会触发此方法
combinePlayer.setOnStatusChange((status, message) => {
console.log("[combinePlayer] 状态发生改变: ", status, message);
});
removeStatusChange
移除指定的状态改变监听器
const combinePlayerStatusChanged = (status: PublicCombinedStatus, message?: string) => {
console.log("[combinePlayer] 状态发生改变: ", status, message);
}
combinePlayer.setOnStatusChange(combinePlayerStatusChanged);
combinePlayer.removeStatusChange(combinePlayerStatusChanged);
removeAllStatusChange
移除所有的状态改变监听器
combinePlayer.removeAllStatusChange();
调用流程
@netless/combine-player
内部有一个队列,只有上一个完成,才会执行下一个。例如:
combinePlayer.play();
combinePlayer.seek(1000 * 10);
combinePlayer.pause();
上面代码的实际执行流程为:
等待回放到达 Playing
后,再去 seek
到 10
秒钟,等 seek
结束后,再去让回放暂停。