@netless/combine-player
同步 白板回放 和 video 的项目
此项目用于代替 white-web-sdk 中的同步功能，white-web-sdk@2.11.2 版本后将取消同步功能，并有此项目接手。
由来
因 white-web-sdk 在同步过程中，没有很好的适配 video 丢帧的问题。如果在 white-web-sdk 里修复丢帧，将会增加代码的复杂度，所以把同步功能单独抽成一个 project 来进行维护。
安装
yarn
yarn add @netless/combine-playernpm
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();
}兼容
如果您的项目之前使用了 white-web-sdk@2.11.2 之前的版本来做同步，并因为业务需求想进行升级时，则需要参考下面的说明，来替换您的项目代码
在使用此项目后，您不应该在直接操作 white-web-sdk 里的 player 对象，而应该操作 combinePlayer 对象。
初始化
在 white-web-sdk@2.11.2 之前的版本中，我们一直推荐您在页面加载完成的时候，去调用: 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 = 2timeDuration
获得回放总时长，其返回类型为:
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 结束后，再去让回放暂停。