xgplayer-flv

xgplayer-flv 可用于播放 FLV 的点播和直播视频流。它可以作为 xgplayer 插件集成到 xgplayer 使用，或单独使用。

支持的功能

点播和直播
H264 和 H265 编码格式(H265支持解析，能否播放取决于浏览器是否支持H265编码格式)
AAC 音频编码
FLV 脚本数据和 SEI 解析
无缝切流
音视频编码参数、播放状态信息暴露

安装

你可以通过 NPM 和 CDN 两种方式安装使用 xgplayer-flv。

NPM 方式安装使用（推荐）

运行下面这个命令进行安装。

npm i -S xgplayer-flv

然后就可以使用了。

import Player from 'xgplayer'
import FlvPlugin from 'xgplayer-flv'
import "xgplayer/dist/index.min.css"

new Player({
    id:'dom-id',
    isLive: true,
    plugins: [FlvPlugin],
    url: 'test.flv',
})

CDN 方式安装使用

在 HTML 文件中加入如下代码。

<script src="//unpkg.com/xgplayer@latest/dist/index.min.js"></script>
<script src="//unpkg.com/xgplayer@latest/dist/index.min.css"></script>
<script src="//unpkg.com/xgplayer-flv@latest/dist/index.min.js"></script>

然后就可以直接在 window 上访问了。

<script>
new Player({
    id:'dom-id',
    isLive: true,
    plugins: [window.FlvPlayer]
})
</script>

快速开始

xgplayer-flv 作为 xgplayer 插件使用，需要引入 xgplayer。如果不了解 xgplayer，可以先去查看相关文档，这里不再重复。

作为 xgplayer 插件，播放 FLV 流只需两步。

检测当前环境是否支持。
将 FLV 插件传给 xgplayer 的 plugins 参数。

import Player from 'xgplayer'
import FlvPlugin from 'xgplayer-flv'
import "xgplayer/dist/index.min.css"


if (FlvPlugin.isSupported()) { // 第一步
    const player = new Player({
        id: 'dom-id',
        url: 'test.flv', // flv 流地址
        isLive: true,
        plugins: [FlvPlugin] // 第二步
    })
}

指南

参数配置

FLV 插件还可以接收一些参数，这些参数需要通过 flv 参数对象传递给 FLV 插件。

import Player from 'xgplayer'
import FlvPlugin from 'xgplayer-flv'
import "xgplayer/dist/index.min.css"


if (FlvPlugin.isSupported()) {
    const player = new Player({
        plugins: [FlvPlugin],
        flv: {
            // flv 插件参数
        }
    })
}

配置网络请求行为

一共有 5 个参数可以配置网络请求的行为。你可以通过下面 4 个参数控制请求重试次数、重试间隔、请求超时时间和 fetch 参数。

import Player from 'xgplayer'
import FlvPlugin from 'xgplayer-flv'
import "xgplayer/dist/index.min.css"


if (FlvPlugin.isSupported()) {
    const player = new Player({
        plugins: [FlvPlugin],
        flv: {
            retryCount: 3, // 重试 3 次，默认值
            retryDelay: 1000, // 每次重试间隔 1 秒，默认值
            loadTimeout: 10000, // 请求超时时间为 10 秒，默认值
            fetchOptions: {
                // 该参数会透传给 fetch，默认值为 undefined
                mode: 'cors'
            }
        }
    })
}

最后一个和网络请求的参数是 maxReaderInterval，它是fetch流式拉流两次接收数据的最大间隔，flv 流数据是一个 Chunk 一个 Chunk 下发，如果两次 Chunk 下发超过了该值，则 Flv 内部会断流并结束播放（可能触发 ended）。该值的默认值为 5000 毫秒，如果直播突然结束，有可能是该值设置比较小。

import Player from 'xgplayer'
import FlvPlugin from 'xgplayer-flv'

if (FlvPlugin.isSupported()) {
    const player = new Player({
        plugins: [FlvPlugin],
        flv: {
            maxReaderInterval: 5000 // 默认值 5000 毫秒
        }
    })
}

配置直播行为

一共有 3 个参数为直播特有参数，它们分别控制直播的目标延迟、最大延迟和自动断流。

import Player from 'xgplayer'
import FlvPlugin from 'xgplayer-flv'

if (FlvPlugin.isSupported()) {
    const player = new Player({
        plugins: [FlvPlugin],
        flv: {
            targetLatency: 5, // 直播目标延迟，默认 5 秒
            maxLatency:  10, // 直播允许的最大延迟，默认 10 秒
            disconnectTime: 0， // 直播断流时间，默认 0 秒，（独立使用时等于 maxLatency）
        }
    })
}

targetLatency 和 maxLatency 关系是，当直播延迟超过 maxLatency 时，flv 就会将当前播放时间点跳转到 targetLatency 位置。所以配置这两个值的时候需要确保 maxLatency 大于 targetLatency，并且应该大很多，默认值是大两倍。

disconnectTime 表示当用户暂停直播后，播放器过多长时间进行断流处理以避免无效的流量消耗。默认值为0，表示用户暂停直播后，播放器会立即停止拉流，直到用户再次点击播放，播放器进行重新拉流。为了避免用户频繁的暂停播放导致的频繁的断流和拉流，设置该值可以在短时间内频繁的暂停播放不影响拉流。

更多 FLV 参数，请查看 API 参数章节。

监听事件

FLV 插件会对外抛出一些事件，FLV 插件会通过 xgplayer 对外抛出事件，要监听 FLV 事件，需要监听 xgplayer 上的 core_event 事件。

import Player from 'xgplayer'
import FlvPlugin from 'xgplayer-flv'

const player = new Player({
    plugins: [FlvPlugin]
})

player.on('core_event', ({ eventName, ...rest }) => { // eventName: flv 事件名; rest: flv 事件回调函数参数
    ...
})

完整的FLV 事件及回调函数参数，请查看 API 事件章节。

处理错误

如果发生错误，FLV 插件会通过 xgplayer 的 error 事件，抛出对应错误。错误对象是 xgplayer 中的 Errors 对象。只要 FLV 抛出 error 事件，FLV 内部就会断流并结束视频（可能会触发 ended 事件），错误类型细化见API 错误描述。

import Player, { Events } from 'xgplayer'
import FlvPlugin from 'xgplayer-flv'

const player = new Player({
    plugins: [FlvPlugin]
})

player.on(Events.ERROR, (error) => {
    error // xgplayer 中的 Errors 对象
})

完整的FLV错误信息定义，请查看 API 错误章节。

独立使用

在实际的应用场景中，我们会希望使用视频播放器的能力，但不希望与播放器UI库绑定。因此这里我们提供独立使用的方式，仅包含功能，不引入UI。

独立使用方式。

import { Flv } from 'xgplayer-flv'

if (Flv.isSupported()) { // 检测是否支持，和 FlvPlugin 是一个方法
    const video = document.createElement('video')
    document.body.append(video)

    const flv = new Flv({
        media: video
        // flv 参数
    })
    flv.load('flv url') // 进行拉流
}

// ----- 自动创建 video 元素

const flv = new Flv()
flv.load('flv url')
document.body.append(flv.media) // flv.media 就是通过参数传入或自动创建的 video 元素

你可以直接通过 Flv 创建一个实例，从而脱离 xgplayer 独立使用。你只需要提供一个 video 元素，如果不提供内部会自动创建一个 video 元素。

值得一提的是，在以插件方式配合Xgplayer使用FLV播放器时，你可以通过 player.plugins.flv.core 访问到 flv 内核实例，它就是上文中我们独立使用场景下创建的 flv 实例。

import Player from 'xgplayer'
import FlvPlugin from 'xgplayer-flv'

if (FlvPlugin.isSupported()) {
    const player = new Player({
        el: document.querySelector('.player'),
        url: 'test.flv',
        isLive: true,
        plugins: [FlvPlugin]
    })

    const flv = player.plugins.flv.core
    console.log(flv) // flv内核实例
}

你可以通过 FlvPlugin.Flv 或直接导入 Flv 访问到 flv 对象的构造类。

import FlvPlugin, { Flv } from 'xgplayer-flv'

console.log(FlvPlugin.Flv === Flv) // true

flv 对象会抛出很多事件和错误，其实就是作为插件使用时抛出的事件和错误。FlvPlugin 只是将这个对象抛出的事件和错误代理到了 xgplayer。

import { Flv, EVENT } from 'xgplayer-flv'

const flv = new Flv()

const onError = (error) => {}
flv.on(EVENT.ERROR, onError) // 监听错误事件
flv.off(EVENT.ERROR, onError) // 取消监听错误事件

flv.once(EVENT.LOAD_START, (event) => { // 只监听一次开始加载事件
    // ...
})

API

参数

在播放器初始化时，我们可以给播放器传入插件参数以开启不同的播放行为、能力。

import Player from 'xgplayer'
import FlvPlugin from 'xgplayer-flv'

const player = new Player({
    plugins: [FlvPlugin],
    flv: {} // flv播放参数
})

具体参数如下。

参数名	默认值	描述
bufferBehind	10	允许当前时间点之前的缓存时长，时间点小于该值的缓存将被清除。
preloadTime	5	目标延迟，弃用，推荐使用targetLatency
maxJumpDistance	3	最大跳洞距离，单位秒
retryCount	3	网络请求重试次数
retryDelay	1000	网络请求重试间隔，单位毫秒
loadTimeout	10000	网络请求超时时间，单位毫秒
fetchOptions		window.fetch 方法的参数
maxReaderInterval	5000	请求两次下发数据间隔最大等待时间，超过会直接断流。单位毫秒
analyzeDuration	20000	流分析时长，如果超过这个时间，将丢弃还未接收到的音频流或视频流，单位毫秒
maxLatency	10	[直播] 最大延迟，超过该延迟会直接 seek 到 targetLatency 位置，单位秒
targetLatency	5	[直播] 目标延迟，单位秒
disconnectTime	maxLatency	[直播] 当暂停停止播放时，多长时间终止拉流以节省流量，单位为秒。默认值为 0，代表暂停时会直接断流。

独立使用场景

独立使用场景下，上述的flv参数是全部支持的，另外加入了几个独立使用场景的参数。

import { Flv } from 'xgplayer-flv'

if (Flv.isSupported()) { // 检测是否支持
    const video = document.createElement('video')
    document.body.append(video)

    const flv = new Flv({
        media: video
        // flv参数在这里传入
    })
    flv.load('{flv_url}')
}

独立使用场景下需要额外传入的参数。

参数名	默认值	描述
media		HTMLMediaElement。如果没有该参数将会自动创建 video 元素，可以通过 flv.media 访问到该值
url		flv url 地址，如果不在创建时，则必须在调用 load 方法时提供
isLive	false	是否是直播

属性

可以通过 player.plugins.flv.core.属性名 的方式访问当前播放器的属性。

属性名	参数
media	传入的 media 参数（`HTMLMediaElement \| null`）
isLive	是否是直播
version	当前 xgplayer-flv 库的版本号

当我们独立使用时，访问属性的方式为 flv.属性名，直接从独立使用生成的flv实例获取属性即可。

方法

下面是 flv 播放器提供的方法，我们可以通过如下方式进行方法的调用。

import Player, { Events } from 'xgplayer'
import FlvPlugin from 'xgplayer-flv'

const player = new Player({
    plugins: [FlvPlugin]
})

// 开始拉流或者后续播放阶段时获取
player.on(Events.LOAD_START, () => {
    console.log(player.plugins.flv.core.speedInfo()) // 调用方法
    console.log(player.plugins.flv.core.getStats())
})

speedInfo

speedInfo(): {speed: number, avgSpeed: number}

获取当前下载速度信息，单位是 bit/s。speed 是最新的速度，avgSpeed 是近几次速度统计的平均值。

getStats

getStats(): StatsInfo

StatsInfo 对象属性如下。

属性	类型	描述
encodeType	string	视频编码格式
audioCodec	string	音频codec字符串描述，类似mp4.40.2
videoCodec	string	视频codec字符串描述，类似avc1.640033
domain	string	拉流域名
fps	number	视频帧率
bitrate	number	视频实时码率
width	number	视频分辨率宽度
height	number	视频分辨率高度
samplerate	number	音频采样率
channelCount	number	音频channel数量
downloadSpeed	number	实时下载速度
avgSpeed	number	平均速度
currentTime	number	当前播放时间点
bufferEnd	number	当前buffer缓存长度

bufferInfo

bufferInfo(): BufferInfo

获取当前缓存信息，单位是秒。

BufferInfo 对象属性如下。

属性	类型	必须存在	描述
currentTime	number	否	当前视频播放时间
buffers	[[number, number]]	是	当前 buffer 数组，二维结构，[[开始时间，结束时间]]
index	number	否	当前视频播放时间命中缓存，在 buffers 中的下标
start	number	否	当前视频播放时间命中缓存的开始时间
end	number	否	当前视频播放时间命中缓存的结束时间
nextStart	number	否	下一个缓存的开始时间
nextEnd	number	否	下一个缓存的结束时间
prevStart	number	否	上一个缓存的开始时间
prevEnd	number	否	上一个缓存的开始时间
behind	number	否	当前视频时间点直接缓存的长度 = currentTime - start
remaining	number	否	当前视频时间点后方缓存长度 = end - currentTime
length	number	否	当前是缓存总时长 = behind + remaining

playbackQuality

playbackQuality(): PlaybackQuality

获取当前渲染帧信息（根据平台不同可能会没有值）。

PlaybackQuality 对象属性如下。

属性	类型	必须存在	描述
droppedVideoFrames	number	否	掉帧数量
totalVideoFrames	number	否	总渲染帧
creationTime	number	否	当前获取帧信息的时间点，毫秒

通过 creationTime 和 totalVideoFrames 可以计算出当前的渲染 fps。

let last = flv.playbackQuality()

fps = 0
setInterval(() => {
  const cur = flv.playbackQuality()
  if (last) {
    fps = Math.round((cur.totalVideoFrames - last.totalVideoFrames) / (cur.creationTime - last.creationTime) * 1000)
  }
  last = cur
}, 1000)

load

load(url?: string): Promise<void>

加载或重新加载数据。如果没有提供构造函数 url 参数时，这个 url 为必传参数。

replay

replay(): Promise<void>

重新播放或重新拉流。调用该方法内部会销毁从头开始拉流播放。该方法源码简化后版本如下。

async replay() {
    await this.load()
    return this.media.play()
}

switchURL

switchURL(url: string, seamless): Promise<void>

该方法用于切换视频，第一个参数为新视频地址，第二个参数为是否使用无缝切换。

该方法会在切换视频结束后触发两个事件 SWITCH_URL_SUCCESS 和 SWITCH_URL_FAILED，切换成功和切换失败。

destroy

destroy(): Promise<void>

销毁 flv 实例。

[静态] isSupported

static isSupported(): boolean

用于判断当前环境是否支持 flv 播放, 通过判断环境是否支持MediaSource

事件

通过监听 xgplayer 的 core_event 事件以获取内核事件信息。

import Player from 'xplgayer'
import FlvPlugin, { Flv, EVENT } from 'xgplayer-flv'

const player = new Player({
    plugins: [FlvPlugin]
})

player.on('core_event', ({ eventName, ...rest }) => { // eventName: flv 事件名; rest: flv 事件回调函数参数
    // 通过判断eventName来区分内核事件
    if (eventName === EVENT.LOAD_START) {
        // ...
    }
})

flv 对外暴露 EVENT 常量，它是事件名常量，可以使用它来监听事件。

import { Flv, EVENT } from 'xgplayer-flv'

const flv = new Flv()

flv.on(EVENT.TTFB, () => {})

TTFB

接收到请求首字节响应。回调函数参数对象属性如下。

属性	类型	必须存在	描述
url	string	是	请求 url
responseUrl	string	是	响应 url
elapsed	number	是	耗时，毫秒

LOAD_START

在发送请求之前触发，参数为 { url: string }，url 为请求 url 。

LOAD_RESPONSE_HEADERS

接收到请求响应头时触发，参数为 { headers: Headers | Recored<string, string>} 。如果当前环境支持 fetch 则 headers 为 Response.headers，否则是普通对象。

LOAD_COMPLETE

在请求完成后触发，参数为 { url: string }，url 为请求 url 。

LOAD_RETRY

请求发生重试时触发。参数对象属性如下。

属性	类型	必须存在	描述
error	StreamingError	是	网络错误对象，请查看 API 错误章节
retryTime	number	是	第几次重试

KEYFRAME

解析到关键帧触发，参数为 { pts: numer }，pts 为修正后的 pts。

METADATA_PARSED

视频元数据被第一次解析到时触发参数被分为两种类型 video 和 audio，它们的具体属性也不同。

interface EventVideo {
    type: 'video';
    meta: {
        codec: string; // 视频编码字符串
        timescale: number; // 视频原始时间尺度
        width: number; // 视频宽度
        height: number; // 视频高度
        baseDts?: number; // 视频轨道到的 base dts，会在元数据变化的时候可能不同
        sarRatio?: [number, number]; // 视频宽高比
    }
}

interface EventAudio {
    type: 'audio';
    meta: {
        codec: string; // 音频编码字符串
        channelCount: number; // 音频通道数
        sampleRate: number; // 音频采样率
    }
}

SEI

当解析到视频 sei 时触发，参数如下：

interface Event {
    originPts: number; // 原始 pts
    pts: number; // 修正后的 pts
    time: number; // 该 sei 在当前视频中的时间点，单位秒
    data: {
        payload: Uint8Array; // sei 数据
        type: number; // sei 类型
        size: number; // sei 大小
        uuid: string; // sei uuid，不存在则为空字符串
    },

    sei: { // 弃用，不建议使用该属性
        code: number; // sei 类型
        content: Uint8Array; // sei 数据
        dts: number; // sei 修正后的 pts
    }
}

SEI_IN_TIME

根据当前视频播放时间抛出 sei，触发该事件表示该 sei 将在当前时间点展示。

它的回调函数参数同 SEI 事件，但是它不包含 sei 属性。

FLV_SCRIPT_DATA

当解析到 flv 脚本数据时触发。参数属性如下。

属性	类型	必须存在	描述
originPts	number	是	原始 pts
pts	number	是	修正后的 pts
time	number	是	该 sei 在当前视频中的时间点，单位秒
data	Object	是	脚本数据

SWITCH_URL_SUCCESS

switchURL 方法调用后，切换 url 成功后触发。

SWITCH_URL_FAILED

switchURL 方法调用后，切换 url 失败后触发。

STREAM_EXCEPTION

对FLV数据进行解封装时，当解析到音视频存在缺失、时间戳跳变等异常情况是抛出。一共有 6 种类型的解析异常，它们通过参数的 type 属性进行区别。

flv.on(EVENT.STREAM_EXCEPTION, ({ type, ...info }) => {
    type // 异常类型
    info // 异常详情
})

type 可以是全大写下划线分隔的字符串，也可以使用 EVENT 常量找到对应字符串。

import { EVENT } from 'xgplayer-flv'

EVENT.LARGE_AV_FIRST_FRAME_GAP_DETECT === 'LARGE_AV_FIRST_FRAME_GAP_DETECT'
// true

LARGE_AV_FIRST_FRAME_GAP_DETECT

音视频偏移过大。详情对象属性如下。

videoBaseDts 视频第一帧的 dts
audioBasePts 音频第一帧的 pts
baseDts 等于 Math.min(audioBasePts, videoBaseDts)
delta 等于 videoBaseDts - audioBasePts

LARGE_VIDEO_DTS_GAP_DETECT

视频两帧之间间隔过大。详情对象属性如下。

time 当前帧的解码时间（秒），与 video 元素时间轴一致
dts 修改后的 dts
originDts 原始 dts
sampleDuration 该帧的时长
refSampleDuration 参考帧时长

LARGE_AUDIO_DTS_GAP_DETECT

两帧音频间隙过大，不会进行补针。详情对象属性如下。

time 当前帧的播放时间（秒），与 video 元素时间轴一致
pts 修改后的 pts
originPts 原始 Pts
sampleDuration 该帧的时长
refSampleDuration 参考帧时长

AUDIO_GAP_DETECT

两帧音频间隙大，进行补帧。详情对象属性如下。

pts 修改后的 pts
originPts 原始 Pts
count 补了多少帧
nextPts 补的第一帧的 pts
refSampleDuration 参考帧时长

AUDIO_OVERLAP_DETECT

两帧音频重叠，进行丢帧。详情对象属性如下。

pts 修改后的 pts
originPts 原始 Pts
count 补了多少帧
nextPts 期望的 pts
refSampleDuration 参考帧时长

MAX_DTS_DELTA_WITH_NEXT_SEGMENT_DETECT

两个视频 Chunk 之间间隙过大，详情对象属性如下。

nextDts 期望的下一帧 dts
firstSampleDts 该 Chunk 第一帧的 dts
sampleDuration 等于 nextDts-firstSampleDts

独立使用场景

在独立使用场景下，上述事件是全部支持的，监听事件的方式与作为插件使用时有所区别

import { Flv, EVENT } from 'xgplayer-flv'


if (Flv.isSupported()) { // 使用静态方法

    const flv = new Flv({
        media: document.createElement('video')
    })

    flv.on(EVENT.SEI, (event) => { // 监听事件
    // event定义与上述定义一致，不包括eventName属性
    })
}

西瓜播放器 HTML5 video video.js 播放器 HTML5播放器 mp4 hls hls.js flv flv.js dash dash.js 无缝切换

# xgplayer-flv

# 安装

# 快速开始

# 指南

# 参数配置

# 配置网络请求行为

# 配置直播行为

# 监听事件

# 处理错误

# 独立使用

# API

# 参数

# 独立使用场景

# 属性

# 方法

# speedInfo

# getStats

# bufferInfo

# playbackQuality

# load

# replay

# switchURL

# destroy

# [静态] isSupported

# 事件

# TTFB

# LOAD_START

# LOAD_RESPONSE_HEADERS

# LOAD_COMPLETE

# LOAD_RETRY

# KEYFRAME

# METADATA_PARSED

# SEI

# SEI_IN_TIME

# FLV_SCRIPT_DATA

# SWITCH_URL_SUCCESS

# SWITCH_URL_FAILED

# STREAM_EXCEPTION

# LARGE_AV_FIRST_FRAME_GAP_DETECT

# LARGE_VIDEO_DTS_GAP_DETECT

# LARGE_AUDIO_DTS_GAP_DETECT

# AUDIO_GAP_DETECT

# AUDIO_OVERLAP_DETECT

# MAX_DTS_DELTA_WITH_NEXT_SEGMENT_DETECT

# 独立使用场景

xgplayer-flv

安装

快速开始

指南

参数配置

配置网络请求行为

配置直播行为

监听事件

处理错误

独立使用

API

参数

独立使用场景

属性

方法

speedInfo

getStats

bufferInfo

playbackQuality

load

replay

switchURL

destroy

[静态] isSupported

事件

TTFB

LOAD_START

LOAD_RESPONSE_HEADERS

LOAD_COMPLETE

LOAD_RETRY

KEYFRAME

METADATA_PARSED

SEI

SEI_IN_TIME

FLV_SCRIPT_DATA

SWITCH_URL_SUCCESS

SWITCH_URL_FAILED

STREAM_EXCEPTION

LARGE_AV_FIRST_FRAME_GAP_DETECT

LARGE_VIDEO_DTS_GAP_DETECT

LARGE_AUDIO_DTS_GAP_DETECT

AUDIO_GAP_DETECT

AUDIO_OVERLAP_DETECT

MAX_DTS_DELTA_WITH_NEXT_SEGMENT_DETECT

独立使用场景