@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 结束后，再去让回放暂停。