播放器(回放流/录像流) API

录像流特有的方法和可监听的事件。

参数

playbackForwardMaxRateDecodeIFrame

  • 类型number
  • 默认值4
  • 用法:录像流播放的时候,当倍率达到多少之后,直接只解码I帧数据。

默认是达到4倍率的时候,就直接只解码I帧数据。

const jessibucaPro = new JessibucaPro({
    playbackForwardMaxRateDecodeIFrame: 6 // 当倍率达到6倍的时候,就直接只解码I帧数据。
})

calcPlaybackForwardMaxRateDecodeIFrame

  • 类型boolean
  • 默认值false
  • 用法:根据当前解码器,流的分辨率,来计算当前环境能够支持的最大倍率,超过倍率之后只解码I帧。

设置为true的时候,playbackForwardMaxRateDecodeIFrame 值会失效掉。

const jessibucaPro = new JessibucaPro({
    calcPlaybackForwardMaxRateDecodeIFrame: true // 根据当前解码器,流的分辨率,来计算当前环境能够支持的最大倍率,超过倍率之后只解码I帧。
})

4k 视频倍率支持

解码器分辨率最大倍率
Wasm4k不支持
Wasm 多线程4k不支持
Wasm SIMD4k不支持
Wasm SIMD 多线程4k1倍

SIMD 软解码4k 只支持 3840X2160格式,4096X2160暂不支持

4k 软解码非常吃CPU性能,对于CPU有要求。测试效果不是很明显,不建议使用。

2k 视频倍率支持

解码器分辨率最大倍率
Wasm2k不支持
Wasm 多线程2k1倍
Wasm SIMD2k1倍
Wasm SIMD 多线程2k2倍

1080p 视频倍率支持

解码器分辨率最大倍率
Wasm1080P1倍
Wasm 多线程1080P4倍
Wasm SIMD1080P3倍
Wasm SIMD 多线程1080P4倍

720p 视频倍率支持

解码器分辨率最大倍率
Wasm720p4倍
Wasm 多线程720p16倍
Wasm SIMD720p4倍
Wasm SIMD 多线程720p16倍

playbackCheckStreamEnd

  • 类型boolean
  • 默认值true
  • 用法:录像流播放的时候,是否检查流的结束时间。
  • 说明:如果设置为true,当流的结束时间到达的时候,会触发streamEnd事件,如果设置为false,会在流结束然后播放器将所有的待渲染的页面渲染完毕之后,触发playbackEnd事件。
const jessibucaPro = new JessibucaPro({
    playbackCheckStreamEnd: false
})

isSpecialPlaybackVod

  • 类型boolean
  • 默认值false
  • 用法:配置特殊回放流,支持暂停缓存数据,本地倍率,逐帧播放,不支持seek,会根据流请求结束计算播放时长。

当配置为true的时候,播放器内部会做一些特殊的处理,来支持暂停缓存数据,本地倍率,逐帧播放等功能。

calcPlaybackForwardMaxRateDecodeIFrame:true,// 根据当前解码器,流的分辨率,来计算当前环境能够支持的最大倍率,超过倍率之后只解码I帧。
playbackCheckStreamEnd:false, // 特殊回放流不检查流结束
playbackConfig.controlType:'simple', // 特殊回放流使用简单点播进度条
playbackConfig.isUseFpsRender:true, // 特殊回放流使用固定fps渲染
playbackConfig.isCacheBeforeDecodeForFpsRender:true, // 特殊回放流在解码前缓存数据
playbackConfig.uiUsePlaybackPause:true, // 特殊回放流ui上面使用
playbackConfig.isPlaybackPauseClearCache:false, // 特殊回放流暂停不清除缓存数据

可以看demo ``

playbackConfig

  • 类型object

  • 默认值{}

  • 参数:TF卡流(录像流)播放配置

    • {array} playList 底部UI 24小时高亮时间端,如在该时间段内,可触发点击事件(controlTypenormal 时生效)
      • {number} start 开始时间戳 例如 1653841634 或者 16538416340000
      • {number} end 结束时间戳 例如 1653843420 或者 16538434200000
      • {string|number|array|object} more 自定义扩展数据,会在点击事件回调中返回
    • {string} controlType 默认值normal 底部UI时间控制条类型,支持 normal 24H进度条,simple点播进度条
    • {boolean} supportWheel 默认值 false 是否支持滚动轴切换精度。 (controlTypenormal 时生效)。
    • {number} duration 默认值0, 录像流总时长,单位秒(s) (controlTypesimple 时生效)
    • {number} startTime (controlTypenormal 时) 默认值playList[0].start, 开始时间戳 例如 1653841634 或者 16538416340000。(controlTypesimple 时) 单位 默认值0, 开始时间 例如 1,60,只是用于UI上面显示的时间的交互设置。
    • {number} isCacheBeforeDecodeForFpsRender 默认值false, 是否在解码前缓存数据
    • {string} showPrecision 默认值 oneHour, 显示精度,支持的参数有:oneHour, halfHour, tenMin, fiveMin。(controlTypesimple 时生效)
    • {boolean} showRateBtn 默认值 false, 是否显示倍速播放按钮
    • {array} rateConfig 默认值 [], 倍速播放配置
      • {number} value 倍速播放倍数
      • {string} label 倍速播放按钮显示的文字
    • {boolean} showControl 默认值 true, 是否显示底部UI时间控制条
    • {boolean} uiUsePlaybackPause 默认值 false, ui上面是否使用 playbackPause 方法
    • {boolean } isUseFpsRender 默认值 false, 是否使用固定的fps渲染,
    • {boolean } isUseLocalCalculateTime 默认值 false, 是否使用本地时间来计算playback时间
    • {number} localOneFrameTimestamp 默认值40, 一帧 40ms, isUseLocalCalculateTime 为 true 生效。(不适合高倍率I帧渲染的场景,当切换成只解码I帧的时候需要更新这个时间戳)。
    • {boolean} useWCS 默认值false, 使用wcs硬解码播放。
    • {boolean} useMSE 默认值false, 使用mse硬解码播放。
    • {boolean} useSIMD 默认值true, 使用wasm(simd)软解码播放。
    • {boolean} isPlaybackPauseClearCache 默认值 true playbackPause()是否清除缓存数据, 只会在isCacheBeforeDecodeForFpsRender:true 才会生效。
    • {boolean} showPrecisionBtn 默认值 true, 是否显示精度切换按钮(24H进度条)。
    • {number} playbackForwardMaxRateDecodeIFrameplaybackForwardMaxRateDecodeIFrame 配置参数
  • 用法: TF卡流时间端配置

isUseFpsRender mse解码暂不支持该配置

例如

直接在new的时候初始化配置(推荐)

jessibucaPro = new JessibucaPro({
    playType: 'playbackTF',
    playbackConfig: {
        playList: [
            {
                start: 16538416340000,
                end: 16538434200000
            },
            {
                start: 1653881963,// 会自动补齐最后四个0
                end: 1653885397 // 会自动补齐最后四个0
            }
        ],
        fps: 25,
        showControl: true,
        uiUsePlaybackPause: true,
        isCacheBeforeDecodeForFpsRender: false,
        isUseFpsRender: false,
        isUseLocalCalculateTime: false,
        localOneFrameTimestamp: 40,
        useWCS: true,
        useMSE: true,
        useSIMD:true,
    }
})

jessibucaPro.playback('url')

在playback方法中初始化配置,会二次初始化播放器,加载速度会慢一些(不推荐)。

jessibucaPro.playback('url', {
    playList: [
        {
            start: 16538416340000,
            end: 16538434200000
        },
        {
            start: 1653881963,// 会自动补齐最后四个0
            end: 1653885397 // 会自动补齐最后四个0
        }
    ],
    fps: 25,
    showControl: true,
    uiUsePlaybackPause: true,
    isCacheBeforeDecodeForFpsRender: false,
    isUseFpsRender: false,
    isUseLocalCalculateTime: false,
    localOneFrameTimestamp: 40,
    useWCS: true,
    useMSE: true,
    useSIMD:true,
})

其他不在时间段的区域,显示是表示没有数据段。不绑定点击时间回调事件。其他在时间区域内的区间点击是有事件响应的。

isCacheBeforeDecodeForFpsRender 为 true 时,会在解码前缓存数据,针对于有些特殊的流,在原本播放器只需要一倍率播放的情况下, 但是服务器端推流是2倍或者以上,这种建议设置为true,防止解码之后缓存,导致内存溢出。

方法

playback(url,options)

  • 参数

    • {string} url
    • {object} optionsplaybackConfig配置参数
  • 返回

    • {Promise}
  • 用法: 播放录像流视频

推荐在new JessibucaPro()的时候,传入playbackConfig以及 playType参数。 这样可以不会二次初始化播放器,提升加载速度。

catch方法里面的错误处理,主要是为了处理加载失败的情况(直接影响初始化),播放异常的情况需要通过监听playFailedAndPaused事件来处理。

当播放失败的时候,触发playFailedAndPaused事件。所以如果要处理重播逻辑,只需要统一在playFailedAndPaused事件里面处理就可以了,不需要在catch里面处理。

jessibucaPro.playback('http://example.com/xxx.flv', {
    playList: [
        {
            start: 16538416340000,
            end: 16538434200000
        },
        {
            start: 1653881963,// 会自动补齐最后四个0
            end: 1653885397 // 会自动补齐最后四个0
        }
    ],
    showControl: true,
    uiUsePlaybackPause: true,
    isCacheBeforeDecodeForFpsRender: false,
    isUseFpsRender: false,
    isUseLocalCalculateTime: false,
    localOneFrameTimestamp: 40
}).then(()=>{
    // 这里只是初始化成功,并不代表流已经开始播放成功。因为请求地址是个异步响应,同时也有重播的逻辑,所以这里统一是表示加载成功。
    // 如果需要检查播放失败,可以查看`playVodFailedAndPaused`事件。
    // 如果想要监听播放成功,可以监听`start`事件。
    console.log('initialized and ready to play');
}).catch((err) => {
    //  加载失败,表示后续都没法播放了。需要检查下播放环境,比如worker加载挂了。
    console.log(err)
})

forward(rate) (废弃)

已经废弃,建议使用 playbackForward(rate) 方法


jessibucaPro.forward(2).then(() => {
    console.log('forward')
}).catch((err) => {
    console.log(err)
})

playbackForward(rate)

  • 参数

    • {number} rate
  • 返回

    • {Promise}
  • 用法: 快放 1倍,2倍,4倍,8倍,16倍,支持范围 1 - 16 正整数倍率, 不支持小数(isSpecialPlaybackVod 场景下,支持0.1到0.9倍速播放)。

如果配置了rateConfig参数,UI也会同步跟着修改倍数显示。

暂不支持 0.1 到 0.9 倍速播放 (isSpecialPlaybackVod 场景下,支持0.1到0.9倍速播放)

只支持正整数倍率,不支持类似1.5、2.5、3.5倍速播放


jessibucaPro.playbackForward(2).then(() => {
    console.log('forward')
}).catch((err) => {
    console.log(err)
})

normal()(废弃)

已经废弃,建议使用 playbackNormal() 方法

jessibuca.normal().then(() => {
    console.log('normal')
}).catch((err) => {
    console.log(err)
})

playbackNormal()

  • 返回
    • {Promise}
  • 用法:快放->恢复
jessibuca.playbackNormal().then(() => {
    console.log('normal')
}).catch((err) => {
    console.log(err)
})

playbackPause(isPause)

  • 参数

    • {boolean} isPause 默认:false
  • 返回

    • {Promise}
  • 用法: 录像流暂停,只是停止渲染画面,继续接收流数据,不触发超时机制

如果 playbackPause(true) 等同于调用pause() 方法


jessibucaPro.playbackPause(true).then(() => {
    console.log('pause success')
}).catch((err) => {
    console.log(err)
})

playbackResume()

  • 返回

    • {Promise}
  • 用法: 录像流暂停->恢复播放

jessibucaPro.playbackResume().then(() => {
    console.log('resume success')
}).catch((err) => {
    console.log(err)
})

updatePlaybackForwardMaxRateDecodeIFrame(rate)

  • 参数
    • {number} rate 支持范围 1 - 8 整数
  • 返回
    • {void} 更新TF卡流只解码i帧播放倍率,支持playback()之前调用。

setPlaybackStartTime(timestamp)

  • 参数
    • {number} timestamp (controlTypenormal 时) 时间戳,针对于24H的时间戳。(controlTypesimple 时) 时间戳,针对于时间段的时间戳。
  • 返回
    • {void}

请求完服务器端seek之后,把seek之后的时间传递给播放器,用于UI上面展示更新之后的时间。

(controlTypenormal 时)的场景

如果是通过点击UI上面的时间,会得到对象时分秒,然后转换成时间戳const timestamp = new Date().setHours(hour,min,second,0),然后调用setPlaybackStartTime(timestamp)方法。

(controlTypesimple 时)的场景

如果是通过点击UI上面的时间,会得到一个从0开始的相对的秒的时间(类似点播逻辑),然后调用setPlaybackStartTime(timestamp)方法。

会存在一种场景,就是seek之后,流媒体服务器端还有一小戳的seek之前的数据推给前端,因为前端24H UI 上面的时间戳是根据流里面的时间戳做当对值得到的。 所以如果立马触发setPlaybackStartTime方法的话,会就有可能因为还是seek之前的时间戳,等seek之后的时间戳到来的时候,UI上面的时间会直接跳的不对。

解决方案:延迟些时间去触发setPlaybackStartTime方法。大概500ms左右。

setTimeout(() => {
    jessibucaPro.setPlaybackStartTime(timestamp)
}, 500)

getPlaybackCurrentRate()

  • 返回
    • {number}

获取当前TF卡流播放的倍率。

var rate = jessibucaPro.getPlaybackCurrentRate();

playbackClearCacheBuffer()

  • 返回
    • {void}

清除缓存的数据,用于seek之后,清除之前的数据。

jessibucaPro.playbackClearCacheBuffer()

updatePlaybackLocalOneFrameTimestamp(timestamp)

  • 参数
    • {number} timestamp 单位ms
  • 返回
    • {void}

更新localOneFrameTimestamp 字段 例如 40 ms

当播放器以倍率播放的时候,如果超过了playbackForwardMaxRateDecodeIFrame 设置的倍率,这个时候只会解码i帧的数据。就会导致localOneFrameTimestamp字段不准确。

所以当切换倍率超过限制之后,就需要触发这个方法,去更新localOneFrameTimestamp字段。

jessibucaPro.updatePlaybackLocalOneFrameTimestamp(40)

isPlaybackPause()

  • 返回值boolean
  • 用法: 返回是否正在回放暂停中状态。
var result = jessibucaPro.isPlaybackPause()

isPlaybackPaused()

等同于 isPlaybackPause() 方法

var result = jessibucaPro.isPlaybackPaused()

setPlaybackShowPrecision(showPrecision)

  • 参数{boolean} showPrecision 默认:oneHour
  • 返回{void}
  • 用法: 设置显示精度

controlTypenormal 时生效

支持的参数有:'oneHour', 'halfHour', 'tenMin', 'fiveMin'。

显示的精度有:

  • oneHour: 1小时
  • halfHour: 30分钟
  • tenMin: 10分钟
  • fiveMin: 5分钟

// 设置显示精度 1小时
jessibucaPro.setPlaybackShowPrecision('oneHour')
// 设置显示精度 30分钟
jessibucaPro.setPlaybackShowPrecision('halfHour')
// 设置显示精度 10分钟
jessibucaPro.setPlaybackShowPrecision('tenMin')
// 设置显示精度 5分钟
jessibucaPro.setPlaybackShowPrecision('fiveMin')

playbackCurrentTimeScroll()

  • 返回{void}
  • 用法: 滚动到当前时间
  • 场景: 当前时间不在可视区域的时候,可以调用这个方法,滚动到当前时间。

controlTypenormal 时生效

jessibucaPro.playbackCurrentTimeScroll()

playbackNextFrame()

  • 返回{Promise}
  • 用法: 逐帧播放下一帧
  • 场景: 适用于isSpecialPlaybackVod 场景下, 逐帧播放下一帧。
jessibucaPro.playbackNextFrame().then(() => {
    console.log('playback next frame success')
}).catch((err) => {
    console.log(err)
})

playbackExitNextFrameAndPlay()

  • 返回{Promise}
  • 用法: 退出逐帧播放,恢复正常播放
  • 场景: 适用于isSpecialPlaybackVod 场景下
jessibucaPro.playbackExitNextFrameAndPlay().then(() => {
    console.log('exit next frame and play success')
}).catch((err) => {
    console.log(err)
})

playbackNextIFrame()

  • 返回{Promise}
  • 用法: 播放到下一个I帧(关键帧)
  • 场景: 适用于isSpecialPlaybackVod 场景下
jessibucaPro.playbackNextIFrame().then(() => {
    console.log('playback next I frame success')
}).catch((err) => {
    console.log(err)
})

playbackExitNextIFrameAndPlay()

  • 返回{Promise}
  • 用法: 退出播放到下一个I帧(关键帧),恢复正常播放
  • 场景: 适用于isSpecialPlaybackVod 场景下
jessibucaPro.playbackExitNextIFrameAndPlay().then(() => {
    console.log('exit next I frame and play success')
}).catch((err) => {
    console.log(err)
})

事件

playbackSeek

当点击播放器上面的时间进度条,响应的事件

controlTypenormal 时 数据结构如下。

  • 回调参数
    • {Object} data 回调数据
      • {number} ts 时间戳
      • {number} hour 小时
      • {number} min 分钟
      • {number} second
      • {string|number|array|object} more 自定义扩展数据
{
    "ts":"时间戳",
    "hour": 1,
    "min": 2,
    "second": 0,
    "more": "自定义扩展数据"
}

controlTypesimple 时 数据结构如下。

  • 回调参数
    • {Object} data 回调数据
      • {number} ts 时间戳

ts: 从0开始的相对的秒的时间

{
    "ts": 1
}

demo


jessibucaPro.on('playbackSeek', (data) => {
    // value 为当前的时间
    // 可以与服务器端发送seek的请求。
    // 然后更新播放器的时间显示
})

//or
jessibucaPro.on(JessibucaPro.EVENTS.playbackStats, (data) => {
    // value 为当前的时间
    // 可以与服务器端发送seek的请求。
    // 然后更新播放器的时间显示
    // 也可以通过value.more 获取到自定义扩展数据
})

playbackStats

录像流的 stats数据,1s回调一次

  • 回调参数
    • {Object} value 回调数据
      • {string} fps 帧率
      • {string} rate 当前倍率
      • {string} start 开始时间(流里面的时间戳)
      • {string} end 结束时间(流里面的时间戳)
      • {string} timestamp 经历时长
      • {string} dataTimestamp end-start,表示1s内播放的流的时间长度
      • {string} audioBufferSize 音频缓存大小
      • {string} videoBufferSize 视频缓存大小
      • {string} ts 等同于(end 字段)
{
    "fps": "", // 帧率
    "rate": "", // 当前倍率
    "start": "", // 开始时间(流里面的时间戳)
    "end": "",// 结束时间(流里面的时间戳)
    "timestamp": "", //经历时长
    "dataTimestamp": "",//end-start,表示1s内播放的流的时间长度
    "audioBufferSize": "",// 音频缓存大小
    "videoBufferSize": "",// 视频缓存大小
    "ts": "" // 等同于(end 字段)
}

demo

jessibucaPro.on('playbackStats', (value) => {

})
// or
jessibucaPro.on(JessibucaPro.EVENTS.playbackStats, (value) => {

})

记录播放器1s(timestamp)内的帧率(fps),当前的倍率(rate),从start时间(流的时间戳)end时间(流的时间戳),播放了多少时长(dataTimestamp),缓存了多少音视频(audioBufferSize,videoBufferSize)数据

然后最终的ts字段,等同于end字段,表示当前播放器播放到了哪个时间戳的

playbackTimestamp

录像流的当前播放的时间,1s回调一次

controlTypenormal 时 数据结构如下。

  • 回调参数
    • {Object} data 回调数据
      • {string} hour 小时
      • {string} min 分钟
      • {string} second
      • {string} ts 时间戳
{
    "hour": "",
    "min": "",
    "second": "",
    "ts": ""
}

默认的时间是从playbackList的第一个开始的。

controlTypesimple 时 数据结构如下。

  • 回调参数
    • {Object} data 回调数据
      • {string} ts 时间戳

ts: 从0开始的相对的秒的时间

{
    "ts": ""
}

默认的时间是从0开始的。

demo

jessibucaPro.on('playbackTimestamp', (data) => {

})
//or
jessibucaPro.on(JessibucaPro.EVENTS.playbackTimestamp, (data) => {

})

playbackPauseOrResume

录像流的ui配置了 playbackPause 方法之后,当触发 playbackPause方法,会触发事件,方便业务层做与服务器端通讯

  • 回调参数
    • {boolean} isPause 回调数据, 当前的状态 true 暂停,false 播放

demo

jessibucaPro.on('playbackPauseOrResume', (isPause) => {
    if (isPause === true) {
        // pause 播放 -> 暂停
    } else {
        //  resume 暂停 -> 播放
    }
})

//or
jessibucaPro.on(JessibucaPro.EVENTS.playbackPauseOrResume, (isPause) => {
    if (isPause === true) {
        // pause 播放 -> 暂停
    } else {
        //  resume 暂停 -> 播放
    }
})

playbackPreRateChange

录像流的ui配置了rateConfig 之后 ,当在ui上面选择了倍率之后,会触发playbackPreRateChange事件,方便业务层做与服务器端通讯。

  • 回调参数
    • {number} value 回调数据, 当前的倍速

jessibucaPro.on('playbackPreRateChange', (value) => {
    // value 为当前的倍速
    // 可以与服务器端发送倍率的请求。
    // 然后更新播放器的倍率显示
})

// or
jessibucaPro.on(JessibucaPro.EVENTS.playbackPreRateChange, (value) => {
    // value 为当前的倍速
    // 可以与服务器端发送倍率的请求。
    // 然后更新播放器的倍率显示
})

playbackRateChange

当播放器的倍率发生变化的时候,会触发playbackRateChange事件。

  • 回调参数
    • {number} value 回调数据, 当前的倍速

jessibucaPro.on('playbackRateChange', (value) => {
    // value 为当前的倍速
})

// or
jessibucaPro.on(JessibucaPro.EVENTS.playbackRateChange, (value) => {
    // value 为当前的倍速
})

playbackShowPrecisionChange

当播放器的显示精度发生变化的时候,会触发playbackShowPrecisionChange事件。

  • 回调参数
    • {string} value 回调数据, 当前的显示精度 oneHour, halfHour, tenMin, fiveMin
jeesibucaPro.on('playbackShowPrecisionChange', (value) => {
    // value 为当前的显示精度 oneHour, halfHour, tenMin, fiveMin
    // 可以与服务器端发送显示精度的请求。
    // 然后更新播放器的显示精度显示
})

// or
jeesibucaPro.on(JessibucaPro.EVENTS.playbackShowPrecisionChange, (value) => {
    // value 为当前的显示精度 oneHour, halfHour, tenMin, fiveMin
    // 可以与服务器端发送显示精度的请求。
    // 然后更新播放器的显示精度显示
})

playbackEnd

录像流播放结束的时候,会触发playbackEnd事件。

需要配置 playbackCheckStreamEnd: false 才会触发该事件。

// 配置参数
const jessibucaPro = new JessibucaPro({
    playbackCheckStreamEnd: false
})
// 监听事件
jeesibucaPro.on('playbackCheckStreamEnd', () => {

})

// or
jeesibucaPro.on(JessibucaPro.EVENTS.playbackCheckStreamEnd, () => {

})