Skip to content

Latest commit

 

History

History
1137 lines (739 loc) · 23.7 KB

api.md

File metadata and controls

1137 lines (739 loc) · 23.7 KB
Raw

API

jessibuca API 文档

TIPS

这是开源版的API文档，这是开源版的API文档，这是开源版的API文档（三遍），PRO的API文档请联系作者。

Jessibuca(options)

options 支持的参数有：

container

  • 类型：DOM or string
  • 用法：

播放器容器。

若为 string ，则底层调用的是 document.querySelector(container)

源码

let $container = options.container;
if (typeof options.container === 'string') {
    $container = document.querySelector(options.container);
}
if (!$container) {
    throw new Error('Jessibuca need container option');
    return;
}

不建议业务层在container参数上面有额外的css属性样式，尤其是缩放，旋转之类的，这样会导致播放器内部的画面不正常。

可以通过在业务层的div 下面再放一个div作为播放器容器,这样可以规避掉一些问题。

<div id="your-container">
    <div id="player-container"></div>
</div>
new Jessibuca({
    container: '#player-container'
})

videoBuffer

  • 类型：number
  • 默认值：1
  • 用法： 设置缓冲时长，单位秒。

decoder

  • 类型：string
  • 默认值：decoder.js
  • 用法：

worker地址

默认引用的是根目录下面的decoder.js文件 ，decoder.js 与 decoder.wasm文件必须是放在同一个目录下面。

例如vue项目中，jessibuca.js 文件在public/jessibuca/jessibuca.js （decoder.js也在同级目录下）。

需要配置的 decoder 参数是： decoder: '/jessibuca/decoder.js'

如果配置的参数是相对地址，是针对于http地址上面的相对地址。

例如当前页面的是 http://test.com/a/b/c.html

如果new 播放器的时候配置的 decoder的参数是相对地址'./decoder.js'，则会去请求 http://test.com/a/b/decoder.js

forceNoOffscreen（废弃）

  • 类型：boolean
  • 默认值：true
  • 用法：

是否不使用离屏模式（提升渲染能力）

该特性是实验性特性，某些版本的浏览器会出现内存无缘无故变大的情况。谨慎使用。

由于目前浏览器兼容性太差，会出现慕名奇妙的错误问题，目前播放器内部禁用离屏渲染。

hiddenAutoPause

  • 类型：boolean
  • 默认值：false
  • 用法：

见

是否开启当页面的'visibilityState'变为'hidden'的时候，自动暂停播放。

hasAudio

  • 类型：boolean
  • 默认值：true
  • 用法：

是否有音频，如果设置false，则不对音频数据解码，提升性能。

rotate

  • 类型：number
  • 默认值：0
  • 用法：

设置旋转角度，只支持，0(默认) ，180，270 三个值。

isResize

  • 类型：boolean
  • 默认值：true
  • 用法：
  1. 当为true的时候：视频画面做等比缩放后,高或宽对齐canvas区域,画面不被拉伸,但有黑边。 等同于 setScaleMode(1)
  2. 当为false的时候：视频画面完全填充canvas区域,画面会被拉伸。等同于 setScaleMode(0)

video标签(useMSE,useWCS+wcsUseVideoRender)渲染的页面暂不支持这个属性。

isFullResize

  • 类型：boolean
  • 默认值：false
  • 用法：
  1. 当为true的时候：视频画面做等比缩放后,完全填充canvas区域,画面不被拉伸,没有黑边,但画面显示不全。等同于 setScaleMode(2)

video标签(useMSE,useWCS+wcsUseVideoRender)渲染的页面暂不支持这个属性。

isFlv

  • 类型：boolean
  • 默认值：false
  • 用法：
  1. 当为true的时候：ws协议不检验是否以.flv为依据，进行协议解析。

debug

  • 类型：boolean
  • 默认值：false
  • 用法： 是否开启控制台调试打印

timeout

  • 类型：number
  • 默认值：10
  • 用法：
  1. 设置超时时长, 单位秒
  2. 在连接成功之前(loading)和播放中途(heart),如果超过设定时长无数据返回,则回调timeout事件

heartTimeout

  • 类型：number
  • 默认值：5
  • 用法：
  1. 设置超时时长, 单位秒
  2. 播放中途,如果超过设定时长无数据返回,则回调timeout事件

heartTimeoutReplay

  • 类型：boolean
  • 默认值：true
  • 用法： 是否开启心跳超时之后自动再播放

heartTimeout 心跳超时之后自动再播放,不再抛出异常，而直接重新播放视频地址。

heartTimeoutReplayTimes

  • 类型：number
  • 默认值：3
  • 用法： heartTimeoutReplay 重试次数

heartTimeoutReplay 重试失败之后，不再重新播放视频地址。

是整个生命周期中重试的次数。

如果想无限次重试，可以设置为-1

loadingTimeout

  • 类型：number
  • 默认值：10
  • 用法：
  1. 设置超时时长, 单位秒
  2. 在连接成功之前,如果超过设定时长无数据返回,则回调timeout事件

loadingTimeoutReplay

  • 类型：boolean
  • 默认值：true
  • 用法： 是否开启loading超时之后自动再播放

loadingTimeout 心跳超时之后自动再播放,不再抛出异常，而直接重新播放视频地址。

loadingTimeoutReplayTimes

  • 类型：number
  • 默认值：3
  • 用法： loadingTimeoutReplay 重试次数

loadingTimeoutReplay 重试失败之后，不再重新播放视频地址。

如果想无限次重试，可以设置为-1

supportDblclickFullscreen

  • 类型：boolean
  • 默认值：false
  • 用法： 是否支持屏幕的双击事件，触发全屏，取消全屏事件。

点击底部的 controls UI条(里面元素)不会触发全屏事件。

showBandwidth

  • 类型：boolean
  • 默认值：false
  • 用法： 是否显示网速

operateBtns

  • 类型：object
  • 默认值：{ fullscreen:false, screenshot: false, play: false, audio: false, record:false }
  • 用法： 配置操作按钮 其中
  1. fullscreen 是否显示全屏按钮
  2. screenshot 是否显示截图按钮
  3. play 是否显示播放暂停按钮
  4. audio 是否显示声音按钮
  5. record 是否显示录制按钮

keepScreenOn

  • 类型：boolean
  • 默认值：false
  • 用法： 开启屏幕常亮，在手机浏览器上, canvas标签渲染视频并不会像video标签那样保持屏幕常亮。

PC端不会生效，仅手机端生效

isNotMute

  • 类型：boolean
  • 默认值：false
  • 用法： 是否开启声音，默认是关闭声音播放的。

必须通过按钮或者点击事件触发play() 方法，才会播放出声音来，不然还是静音的。 浏览器不允许自动播放的视频自动播放声音。

loadingText

  • 类型：string
  • 默认值：``
  • 用法： 加载过程中文案。

background

  • 类型：string
  • 默认值：``
  • 用法： 背景图片。

useMSE

  • 类型：boolean
  • 默认值：false
  • 用法： 是否开启MediaSource硬解码

视频编码只支持H.264视频（Safari on iOS不支持）

> 不支持 forceNoOffscreen 为 false (开启离屏渲染)

优先级高于useWCS:true

useWCS

  • 类型：boolean
  • 默认值：false
  • 用法： 是否开启Webcodecs硬解码

视频编码只支持H.264视频 (需在chrome 94版本以上，需要https或者localhost环境)

> 支持 forceNoOffscreen 为 false （开启离屏渲染）

如果同时设置了useMSE:true, 则优先使用useMSE

wcsUseVideoRender

  • 类型：boolean
  • 默认值：true
  • 用法： webcodecs硬解码是否通过video标签渲染

> forceNoOffscreen 设置为false之后（通过OffscreenCanvas渲染之），wcsUseVideoRender不会生效。

webcodecs硬解码之后，默认是通过canvas 渲染出来的，可以通过配置通过video标签渲染，提升渲染性能。

现在默认 video标签渲染，提升渲染性能。

autoWasm

  • 类型：boolean
  • 默认值：true
  • 用法： 在使用MSE或者Webcodecs 播放H265的时候，是否自动降级到wasm模式。

设置为false 则直接关闭播放，抛出Error 异常，设置为true 则会自动切换成wasm模式播放。

hotKey

  • 类型：boolean
  • 默认值：false
  • 用法： 是否开启键盘快捷键

目前支持的键盘快捷键有：esc -> 退出全屏；arrowUp -> 声音增加；arrowDown -> 声音减少；

wasmDecodeErrorReplay

  • 类型：boolean
  • 默认值：true
  • 用法： 是否开启解码失败重新播放

wasm解码报错之后，不再抛出异常，而是直接重新播放视频地址。

controlAutoHide

  • 类型：boolean
  • 默认值：false
  • 用法： 底部控制台是否自动隐藏

只有鼠标聚焦到播放器内部才会显示，移除之后，会消失。

recordType

  • 类型：string
  • 默认值：webm
  • 用法： 默认录制的视频格式

支持 webm,mp4 参数

useWebFullScreen

  • 类型：boolean
  • 默认值：false
  • 用法：是否使用web全屏(旋转90度)（只会在移动端生效）。

如果手机设置了自动选择，建议不要开启。

web全屏使用的是css方式实现的伪全屏，实现的是横屏播放的。如果手机设置了自动旋转，建议不要使用这个功能。

ios上面不支持系统级别的全屏方法，推荐使用这个参数。

autoUseSystemFullScreen

  • 类型：boolean
  • 默认值：true
  • 用法：是否自动使用系统全屏

如果设置了true，播放器会检查是否支持系统提供的全屏API，如果支持，就会优先使用系统全屏API，否则使用web全屏API（useWebFullScreen）。

方法

setDebug(flag)

  • 参数：
    • {boolean} flag
  • 用法： 是否开启控制台调试打印
// 开启
jessibuca.setDebug(true)
// 关闭
jessibuca.setDebug(false)

mute()

  • 用法： 静音
jessibuca.mute()

cancelMute()

  • 用法： 取消静音
jessibuca.cancelMute()

iPhone，chrome等要求自动播放时，音频必须静音，需要由一个真实的用户交互操作来恢复，不能使用代码。

audioResume()

  • 用法： 留给上层用户操作来触发音频恢复的方法。

iPhone，chrome等要求自动播放时，音频必须静音，需要由一个真实的用户交互操作来恢复，不能使用代码。

https://developers.google.com/web/updates/2017/09/autoplay-policy-changes

setTimeout(time)

  • 参数：
    • {number} time
  • 用法：

设置超时时长, 单位秒 在连接成功之前和播放中途,如果超过设定时长无数据返回,则回调timeout事件

jessibuca.setTimeout(10)

jessibuca.on('timeout', function () {
    //
});

setScaleMode(mode)

  • 参数：

    • {number} mode

  • 用法：

  1. 0 视频画面完全填充canvas区域,画面会被拉伸 等同于参数 isResize 为false
  2. 1 视频画面做等比缩放后,高或宽对齐canvas区域,画面不被拉伸,但有黑边 等同于参数 isResize 为true
  3. 2 视频画面做等比缩放后,完全填充canvas区域,画面不被拉伸,没有黑边,但画面显示不全 等同于参数 isFullResize 为true

video标签(useMSE,useWCS+wcsUseVideoRender)渲染的页面暂不支持这个方法。

jessibuca.setScaleMode(0)

jessibuca.setScaleMode(1)

jessibuca.setScaleMode(2)

pause()

  • 返回：
    • {Promise}
  • 用法： 暂停播放
jessibuca.pause().then(() => {
    console.log('pause success')

    jessibuca.play().then(() => {

    }).catch((e) => {

    })

}).catch((e) => {
    console.log('pause error', e);
})

可以在pause 之后，再调用 play()方法就继续播放之前的流。

close()（废弃）

  • 用法： 关闭视频,不释放底层资源
  • 返回：
    • {Promise}

废弃，推荐使用destroy()方法

内部就是调用的destroy()方法

jessibuca.close().then(() => {
    console.log('close success')
}).catch((e) => {
    console.log('close error', e);
});

destroy()

  • 用法： 关闭视频，释放底层资源
  • 返回：
    • {Promise}
jessibuca.destroy().then(()=>{
    // todo: next
})

// 或者
await jessibuca.destroy();

clearView()

  • 用法： 清理画布为黑色背景
jessibuca.clearView()

video标签(useMSE,useWCS+wcsUseVideoRender)渲染的页面暂不支持这个方法。

play([url],[options])

  • 参数：

    • {string} url url 地址
    • {object} options 额外参数
      • {object} headers http 请求头

  • 返回：

    • {Promise}

  • 用法： 播放视频

jessibuca.play('url').then(() => {
    console.log('play success')
}).catch((e) => {
    console.log('play error', e)
})

//  http 授权认证。
jessibuca.play('url',{headers:{'Authorization':'test111'}}).then(() => {
    console.log('play success')
}).catch((e) => {
    console.log('play error', e)
})


//
jessibuca.play()

resize()

  • 用法： 重新调整视图大小

setBufferTime(time)

  • 参数：

    • {number} time

  • 用法： 设置最大缓冲时长，单位秒，播放器会自动消除延迟。

等同于 videoBuffer 参数。

// 设置 200ms 缓冲
jessibuca.setBufferTime(0.2)

setRotate(deg)

  • 参数：
    • {number} deg
  • 用法： 设置旋转角度，支持，0(默认), 90, 180, 270 四个值。

可用于实现监控画面小窗和全屏效果，由于iOS没有全屏API，此方法可以模拟页面内全屏效果而且多端效果一致。

注意，当旋转90度后，用户也会旋转手机，这时如果手机未锁定方向，画面又可能因为浏览器旋转导致画面又旋转了。可以监听页面旋转事件，将角度又旋转回0

jessibuca.setRotate(0)

jessibuca.setRotate(90)

jessibuca.setRotate(180)

jessibuca.setRotate(270)

setVolume(volume)

  • 参数：

    • {number} volume

  • 用法：

  1. 设置音量大小，取值0 — 1
  2. 当为0时，完全无声
  3. 当为1时，最大音量，默认值

区别于 mute 和 cancelMute 方法，虽然设置setVolume(0) 也能达到 mute方法，但是mute 方法是不调用底层播放音频的，能提高性能。而setVolume(0)只是把声音设置为0 ，以达到效果。

jessibuca.setVolume(0.2)

jessibuca.setVolume(0)

jessibuca.setVolume(1)

hasLoaded()

  • 返回值：boolean
  • 用法： 返回是否加载完毕

仅为兼容老的2.x语法，3.x版本不需要这个事件。

var result = jessibuca.hasLoaded()
console.log(result) // true

setKeepScreenOn()

  • 用法： 开启屏幕常亮，在手机浏览器上, canvas标签渲染视频并不会像video标签那样保持屏幕常亮。 H5目前在chrome\edge 84, android chrome 84及以上有原生亮屏API, 需要是https页面 其余平台为模拟实现，此时为兼容实现，并不保证所有浏览器都支持
jessibuca.setKeepScreenOn()

setFullscreen(flag)

  • 参数：

    • {boolean} flag

  • 用法： 全屏(取消全屏)播放视频

iOS不支持，iPadOS13后支持

推荐iOS端配置上 useWebFullScreen 这个参数。

jessibuca.setFullscreen(true)
//
jessibuca.setFullscreen(false)

screenshot(filename, format, quality,type)

  • 参数：
    • {string} filename
    • {string} format
    • {number} quality
    • {string} type
  • 用法：

截图，调用后弹出下载框保存截图

  1. filename: 可选参数, 保存的文件名, 默认 时间戳
  2. format : 可选参数, 截图的格式，可选png或jpeg或者webp ,默认 png
  3. quality: 可选参数, 当格式是jpeg或者webp时，压缩质量，取值0 ~ 1 ,默认 0.92
  4. type: 可选参数, 可选download或者base64或者blob，默认download
jessibuca.screenshot("test", "png", 0.5)


const base64 = jessibuca.screenshot("test", "png", 0.5, 'base64')


const fileBlob = jessibuca.screenshot("test", 'blob')

startRecord(fileName,fileType)

  • 参数：

    • {string} filename
    • {string} fileType

  • 用法： 开始录制。

  1. fileName: 可选，默认时间戳
  2. fileType: 可选，默认webm，支持webm 和mp4 格式
jessibuca.startRecord('xxx', 'webm')

stopRecordAndSave()

  • 用法： 暂停录制并下载。
jessibuca.stopRecordAndSave()

isPlaying()

  • 返回值：boolean
  • 用法： 返回是否正在播放中状态。
var result = jessibuca.isPlaying()
console.log(result) // true

isMute()

  • 返回值：boolean
  • 用法： 返回是否静音。
var result = jessibuca.isMute()
console.log(result) // true

isRecording()

  • 返回值：boolean
  • 用法： 返回是否正在录制。
var result = jessibuca.isRecording()
console.log(result) // true

toggleControlBar(isShow)

  • 用法： 切换底部控制条 隐藏/显示
  • 参数：
    • {boolean} isShow 是否显示
// 显示
jessibuca.toggleControlBar(true)
// 隐藏
jessibuca.toggleControlBar(false)

// 切换 隐藏/显示
jessibuca.toggleControlBar()

getControlBarShow()

  • 用法： 获取底部控制条是否显示
  • 返回：{boolean}
const isShow = jessibuca.getControlBarShow()

on(event, callback)

  • 参数：
    • {string} event
    • {function} callback
  • 用法： 监听方法
jessibuca.on("load", function () {
    console.log('load')
})

事件

load

监听 jessibuca 初始化事件。

仅为兼容老的2.x语法，3.x版本不需要这个事件。

这个事件需要结合loaded属性一起使用。

3.x版本不需要这个事件。可以直接写play()方法。

jessibuca.on("load", function () {
    console.log('load')
})

推荐写法

if(jessibuca.loaded){
    console.log('load')
}
else {
    jessibuca.on("load", function () {
        console.log('load')
    })
}

timeUpdate

当前视频帧pts，单位毫秒ms

jessibuca.on('timeUpdate', function (ts) {
    console.log('timeUpdate', ts);
})

videoInfo

当解析出视频信息时回调，2个回调参数

  1. width：视频宽
  2. height：视频高
  3. encTypeCode 视频编码类型(10:h264,12:h265)
  4. encType 视频编码类型(字符串)
jessibuca.on("videoInfo", function (data) {
    console.log('width:', data.width, 'height:', data.width)
})

audioInfo

当解析出音频信息时回调，2个回调参数

  1. numOfChannels：声频通道
  2. sampleRate 采样率
  3. encTypeCode 音频编码类型(10:aac,7:ALAW(g711a),8:MULAW(g711u))
  4. encType 音频编码类型(字符串)
jessibuca.on("audioInfo", function (data) {
    console.log('numOfChannels:', data.numOfChannels, 'sampleRate', data.sampleRate)
})

log

信息，包含错误信息

jessibuca.on("log", function (data) {
    console.log('data:', data)
})

error

错误信息

目前已有的错误信息：

  1. jessibuca.ERROR.playError ;播放错误，url 为空的时候，调用play方法
  2. jessibuca.ERROR.fetchError ;http 请求失败
  3. jessibuca.ERROR.websocketError; websocket 请求失败
  4. jessibuca.ERROR.webcodecsH265NotSupport; webcodecs 解码 h265 失败
  5. jessibuca.ERROR.mediaSourceH265NotSupport; mediaSource 解码 h265 失败
  6. jessibuca.ERROR.wasmDecodeError ; wasm 解码失败
jessibuca.on("error", function (error) {
    if (error === jessibuca.ERROR.fetchError) {
        //
    } else if (error === jessibuca.ERROR.webcodecsH265NotSupport) {
        //
    }
    console.log('error:', error)
})

kBps

当前网速， 单位KB 每秒1次,

jessibuca.on("kBps", function (data) {
    console.log('kBps:', data)
})

start

渲染开始

如果需要在start 之后调用截图方法，需要写一个延迟方法去执行。因为代码中无法感应到画面被渲染出来了。

jessibuca.on("start", function () {
    console.log('start render')

    // 如果有截图需求。需要延迟一下，因为代码中无法感应到画面被渲染出来了。
    // 1s 之后截图
    setTimeout(function () {
        jessibuca.screenshot('xxx')
    }, 1 * 1000)
})

timeout

当设定的超时时间内无数据返回,则回调

  1. jessibuca.TIMEOUT.loadingTimeout ; 同loadingTimeout
  2. jessibuca.TIMEOUT.delayTimeout ; 同delayTimeout
jessibuca.on("timeout", function (error) {
    console.log('timeout:', error)
})

loadingTimeout

当play()的时候，如果没有数据返回，则回调

jessibuca.on("loadingTimeout", function () {
    console.log('timeout')
})

delayTimeout

当播放过程中，如果超过timeout之后没有数据渲染，则抛出异常。

jessibuca.on("delayTimeout", function () {
    console.log('timeout')
})

fullscreen

当前是否全屏

jessibuca.on("fullscreen", function (flag) {
    console.log('is fullscreen', flag)
})

webFullscreen

当前是否web全屏

jessibuca.on("webFullscreen", function (flag) {
    console.log('is webFullscreen', flag)
})

play

触发播放事件

jessibuca.on("play", function (flag) {
    console.log('play')
})

pause

触发暂停事件

jessibuca.on("pause", function (flag) {
    console.log('pause')
})

mute

触发声音事件，返回boolean值

jessibuca.on("mute", function (flag) {
    console.log('is mute', flag)
})

volume

触发音量事件，返回音量值

jessibuca.on("volume", function (volume) {
    console.log('volume', volume)
})

stats

流状态统计，流开始播放后回调，每秒1次。

  1. buf: 当前缓冲区时长，单位毫秒,
  2. fps: 当前视频帧率,
  3. abps: 当前音频码率，单位byte,
  4. vbps: 当前视频码率，单位byte，
  5. ts:当前视频帧pts，单位毫秒
jessibuca.on("stats", function (s) {
    console.log("stats is", s)
})

performance

渲染性能统计，流开始播放后回调，每秒1次。

  • 0: 表示卡顿
  • 1: 表示流畅
  • 2: 表示非常流程
jessibuca.on("performance", function (performance) {
    console.log("performance is", performance)
})

recordStart

录制开始的事件

jessibuca.on("recordStart", function () {
    console.log("record start")
})

recordEnd

录制结束的事件

jessibuca.on("recordEnd", function () {
    console.log("record end")
})

recordingTimestamp

录制的时候，返回的录制时长，1s一次

jessibuca.on("recordingTimestamp", function (timestamp) {
    console.log("recordingTimestamp is", timestamp)
})

playToRenderTimes

监听调用play方法 经过 初始化-> 网络请求-> 解封装 -> 解码 -> 渲染 一系列过程的时间消耗

jessibuca.on("playToRenderTimes", function (times) {
    console.log("playToRenderTimes is", times)
})

数据结构如下。

{
    playInitStart: '', //1
    playStart: '', // 2
    streamStart: '', //3
    streamResponse: '', // 4
    demuxStart: '', // 5
    decodeStart: '', // 6
    videoStart: '', // 7
    playTimestamp: '',// playStart- playInitStart
    streamTimestamp: '',// streamStart - playStart
    streamResponseTimestamp: '',// streamResponse - streamStart
    demuxTimestamp: '', // demuxStart - streamResponse
    decodeTimestamp: '', // decodeStart - demuxStart
    videoTimestamp: '',// videoStart - decodeStart
    allTimestamp: '' // videoStart - playInitStart
}

支持作者

第一作者

V3版本作者

群