# xgplayer-hlsxgplayer-hls 可用于播放 HLS 的点播和直播视频流。它可以作为 xgplayer 插件集成到 xgplayer 使用，或以内核形式单独使用。
支持的功能
master m3u8 和 media m3u8 描述文件点播和直播TS 格式视频文件CMAF/FMP4 格式视频文件H264 和 H265 编码格式(H265支持解析，能否播放取决于浏览器是否支持H265编码格式)TS 格式的 SEI 解析AAC 音频编码AES-128 CBC 加密# 安装你可以通过 NPM 和 CDN 两种方式安装使用 xgplayer-hls。
NPM 方式安装使用（推荐）运行下面这个命令进行安装。
npm i -S xgplayer-hls
然后就可以使用了。
import Player from 'xgplayer'
import HlsPlugin from 'xgplayer-hls'
new Player({
plugins: [HlsPlugin]
})
CDN 方式安装使用在 HTML 文件中加入如下代码。
然后就可以直接在 window 上访问了window.HlsPlayer。
# 快速开始xgplayer-hls 作为 xgplayer 插件使用，需要引入 xgplayer。如果不了解 xgplayer，可以先去查看相关文档，这里不再重复。
作为 xgplayer 插件，播放 HLS 流只需两步。
检测当前环境是否支持。将 HLS 插件传给 xgplayer 的 plugins 参数。import Player from 'xgplayer'
import HlsPlugin from 'xgplayer-hls'
let player
if (document.createElement('video').canPlayType('application/vnd.apple.mpegurl')) {
// 原生支持 hls 播放
player = new Player({
el: document.querySelector('.player'),
url: 'test.m3u8'
})
} else if (HlsPlugin.isSupported()) { // 第一步
player = new Player({
el: document.querySelector('.player'),
isLive: false,
url: 'test.m3u8', // hls 流地址
plugins: [HlsPlugin] // 第二步
})
}
上面代码中首先会判断当前环境是否原生支持 hls 播放（如 IOS 系统）如果支持则直接播放 HLS 流而不使用 HLS 插件, 否则检测当前环境是否支持 xgplayer-hls，支持的话通过插件播放
# 指南# 参数HLS 插件还可以接收一些参数，这些参数需要通过 hls 参数对象传递给 HLS 插件。
import Player from 'xgplayer'
import HlsPlugin from 'xgplayer-hls'
if (HlsPlugin.isSupported()) {
const player = new Player({
plugins: [HlsPlugin],
hls: {
// hls 插件参数
}
})
}
# 配置网络请求行为一共有 4 个参数可以配置网络请求的行为。你可以通过下面 4 个参数控制请求重试次数、重试间隔、请求超时时间和 fetch 参数。
import Player from 'xgplayer'
import HlsPlugin from 'xgplayer-hls'
if (HlsPlugin.isSupported()) {
const player = new Player({
plugins: [HlsPlugin],
hls: {
retryCount: 3, // 重试 3 次，默认值
retryDelay: 1000, // 每次重试间隔 1 秒，默认值
loadTimeout: 10000, // 请求超时时间为 10 秒，默认值
fetchOptions: {
// 该参数会透传给 fetch，默认值为 undefined
mode: 'cors'
}
}
})
}
# 配置直播行为一共有 3 个参数为直播特有参数，它们分别控制直播的目标延迟、最大延迟和自动断流。
import Player from 'xgplayer'
import HlsPlugin from 'xgplayer-hls'
if (HlsPlugin.isSupported()) {
const player = new Player({
url: 'live.m3u8',
isLive: true,
plugins: [HlsPlugin],
hls: {
targetLatency: 10, // 直播目标延迟，默认 10 秒
maxLatency: 20, // 直播允许的最大延迟，默认 20 秒
disconnectTime: 0， // 直播断流时间，默认 0 秒，（独立使用时等于 maxLatency）
}
})
}
targetLatency 和 maxLatency 关系是，当直播延迟超过 maxLatency 时，hls 就会将当前播放时间点跳转到 targetLatency 位置。所以配置这两个值的时候需要确保 maxLatency 大于 targetLatency，并且应该大很多，默认值是大两倍。
disconnectTime 是当直播暂停后，直播延迟超过该值就会断流，作为插件使用时该值是 0 秒，用户暂停直播后就会断流，点击播放会重新拉流。但是用户频繁的暂停播放，就会导致频繁的断流和拉流，设置该值可以让短时间的停止播放不断流。
针对点播场景，preloadTime指定允许的预加载buffer的最大长度(单位s)
import Player from 'xgplayer'
import HlsPlugin from 'xgplayer-hls'
if (HlsPlugin.isSupported()) {
const player = new Player({
url: 'vod.m3u8',
isLive: false,
plugins: [HlsPlugin],
hls: {
preloadTime: 30 // 默认值
}
})
}
更多 HLS 参数，请查看 API 参数章节。
# 监听事件HLS 插件会对外抛出一些事件，HLS 插件会通过 xgplayer 对外抛出事件，要监听 HLS 事件，需要监听 xgplayer 上的 core_event 事件。
import Player from 'xgplayer'
import HlsPlugin from 'xgplayer-hls'
const player = new Player({
plugins: [HlsPlugin]
})
player.on('core_event', ({ eventName, ...rest }) => { // eventName: hls 事件名; rest: hls 事件回调函数参数
...
})
HLS 会抛出的事件及回调函数参数，请查看 API 事件章节。
# 处理错误如果发生错误，HLS 插件会通过 xgplayer 的 error 事件，抛出对应错误。错误对象是 xgplayer 中的 Errors 对象。只要 HLS 抛出 error 事件，HLS 内部就会断流并结束视频（可能会触发 ended 事件）。错误类型细化见API 错误描述。
import Player, { Events } from 'xgplayer'
import HlsPlugin from 'xgplayer-hls'
const player = new Player({
plugins: [HlsPlugin]
})
player.on(Events.ERROR, (error) => {
error // xgplayer 中的 Errors 对象
})
# 独立使用在实际的应用场景中，我们会希望使用视频播放器的能力，但不希望与播放器UI库绑定。因此这里我们提供独立使用的方式，仅包含功能，不引入UI。
独立使用方式。
import { Hls } from 'xgplayer-hls'
if (Hls.isSupported()) { // 检测是否支持，和 HlsPlugin 是一个方法
const video = document.createElement('video')
document.body.append(video)
const hls = new Hls({
media: video
// hls 参数
})
hls.load('m3u8 url') // 进行拉流
}
// ----- 自动创建 video 元素
const hls = new Hls()
hls.load('m3u8 url')
document.body.append(hls.media) // hls.media 就是通过参数传入或自动创建的 video 元素
你可以直接通过 Hls 创建一个实例，从而脱离 xgplayer 独立使用。你只需要提供一个 video 元素，如果不提供内部会自动创建一个 video 元素。
值得一提的是，在以插件方式使用 HLS 播放器时，你可以通过 player.plugins.hls.core 访问到hls内核实例，它就是上文中我们独立使用场景下创建的 hls 实例。
import Player from 'xgplayer'
import HlsPlugin from 'xgplayer-hls'
if (HlsPlugin.isSupported()) {
const player = new Player({
el: document.querySelector('.player'),
url: 'test.m3u8',
isLive: true,
plugins: [HlsPlugin]
})
const hls = player.plugins.hls.core
console.log(hls) // hls 上有很多有用的方法和属性
}
你可以通过 HlsPlugin.Hls 或直接导入 Hls 访问到 hls 对象的构造类。
import HlsPlugin, { Hls } from 'xgplayer-hls'
console.log(HlsPlugin.Hls === Hls) // true
hls 对象会抛出很多事件和错误，其实就是作为插件使用时抛出的事件和错误。HlsPlugin 只是将这个对象抛出的事件和错误代理到了 xgplayer。
import { Hls, EVENT } from 'xgplayer-hls'
const hls = new Hls()
const onError = (error) => {}
hls.on(EVENT.ERROR, onError) // 监听错误事件
hls.off(EVENT.ERROR, onError) // 取消监听错误事件
hls.once(EVENT.LOAD_START, (event) => { // 只监听一次开始加载事件
// ...
})
# API# 参数在播放器初始化时，我们可以给播放器传入插件参数以开启不同的播放行为、能力。
import Player from 'xgplayer'
import HlsPlugin from 'xgplayer-hls'
const player = new Player({
plugins: [HlsPlugin],
hls: {} // hls播放参数
})
具体参数如下。
参数名默认值描述bufferBehind10允许当前时间点之前的缓存时长，时间点小于该值的缓存将被清除。preloadTime30[点播]预加载时长，单位秒maxJumpDistance3最大跳洞距离，单位秒retryCount3网络请求重试次数retryDelay1000网络请求重试间隔，单位毫秒loadTimeout10000网络请求超时时间，单位毫秒fetchOptionswindow.fetch 方法的参数startTime0[点播] 开始播放时间，单位秒targetLatency10[直播] 目标延迟，单位秒maxLatency20[直播] 最大延迟，超过该延迟会直接 seek 到 targetLatency 位置，单位秒disconnectTime0[直播] 当暂停停止播放时，多久断流。作为 xgplayer 插件使用时默认值为 0，单位秒# 独立使用场景独立使用场景下，上述的hls 参数是全部支持的，另外加入了几个独立使用场景的参数。
import { Hls } from 'xgplayer-hls'
if (Hls.isSupported()) { // 检测是否支持
const video = document.createElement('video')
document.body.append(video)
const hls = new Hls({
media: video
// hls参数在这里传入
})
hls.load('{hls_url}')
}
独立使用场景下需要额外传入的参数
参数名默认值描述mediaHTMLMediaElement。如果没有该参数将会自动创建 video 元素，可以通过 hls.media 访问到该值urlhls url 地址，如果不在创建时，则必须在调用 load 方法时提供isLivefalse是否是直播# 属性可以通过 player.plugins.hls.core.属性名 的方式访问当前播放器的属性。
属性名参数media传入的 media 参数 （HTMLMediaElement | null）isLive是否是直播version当前 xgplayer-hls 库的版本号当我们独立使用时，访问属性的方式为 hls.属性名，直接从独立使用生成的 hls 实例获取属性即可。
# 方法下面是 hls 播放器提供的方法，我们可以通过如下方式进行方法的调用。
import Player, { Events } from 'xgplayer'
import HlsPlugin from 'xgplayer-hls'
const player = new Player({
plugins: [HlsPlugin]
})
// 开始拉流或者后续播放阶段时获取
player.on(Events.LOAD_START, () => {
console.log(player.plugins.hls.core.speedInfo()) // 调用方法
})
# speedInfospeedInfo(): {speed: number, avgSpeed: number}
获取当前下载速度信息，单位是 bit/s。speed 是最新的速度，avgSpeed 是近几次速度统计的平均值。
这里统计的速度信息可能不准确，因为在有缓存的情况下可能获取一个非常快的速度。如果需要获取最原始的速度，自己处理的话可以不使用该 api，而是监听 EVENT.SPEED ，该事件详情请查看 API 事件章节。
# getStatsgetStats(): StatsInfo
StatsInfo 对象属性如下。
属性类型描述encodeTypestring视频编码格式audioCodecstring音频codec字符串描述，类似mp4.40.2videoCodecstring视频codec字符串描述，类似avc1.640033domainstring拉流域名fpsnumber视频帧率bitratenumber视频实时码率widthnumber视频分辨率宽度heightnumber视频分辨率高度sampleratenumber音频采样率channelCountnumber音频channel数量downloadSpeednumber实时下载速度avgSpeednumber平均速度currentTimenumber当前播放时间点bufferEndnumber当前buffer缓存长度# bufferInfobufferInfo(): BufferInfo
获取当前缓存信息，单位是秒。
BufferInfo 对象属性如下。
属性类型必须存在描述currentTimenumber否当前视频播放时间buffers[[number, number]]是当前 buffer 数组，二维结构，[[开始时间，结束时间]]indexnumber否当前视频播放时间命中缓存，在 buffers 中的下标startnumber否当前视频播放时间命中缓存的开始时间endnumber否当前视频播放时间命中缓存的结束时间nextStartnumber否下一个缓存的开始时间nextEndnumber否下一个缓存的结束时间prevStartnumber否上一个缓存的开始时间prevEndnumber否上一个缓存的开始时间behindnumber否当前视频时间点直接缓存的长度 = currentTime - startremainingnumber否当前视频时间点后方缓存长度 = end - currentTimelengthnumber否当前是缓存总时长 = behind + remaining# playbackQualityplaybackQuality(): PlaybackQuality
获取当前渲染帧信息（根据平台不同可能会没有值）。
PlaybackQuality 对象属性如下。
属性类型必须存在描述droppedVideoFramesnumber否掉帧数量totalVideoFramesnumber否总渲染帧creationTimenumber否当前获取帧信息的时间点，毫秒通过 creationTime 和 totalVideoFrames 可以计算出当前的渲染 fps。
let last = hls.playbackQuality()
fps = 0
setInterval(() => {
const cur = hls.playbackQuality()
if (last) {
fps = Math.round((cur.totalVideoFrames - last.totalVideoFrames) / (cur.creationTime - last.creationTime) * 1000)
}
last = cur
}, 1000)
# loadload(url?: string): Promise
加载或重新加载数据。如果没有提供构造函数 url 参数时，这个 url 为必传参数。
const fn = async () => {
await hls.load() // 第一个视频数据加载好后会 resolve
// 第一个视频数据已经加载完毕
}
# replayreplay(): Promise
重新播放或重新拉流。调用该方法内部会销毁从头开始拉流播放。
# switchURLswitchURL(url: string, startTime = 0): Promise
该方法用于切换视频，第一个参数为新视频地址，第二个参数是新的视频开始播放时间（只在点播生效）。
该方法会在切换视频结束后触发两个事件 SWITCH_URL_SUCCESS 和 SWITCH_URL_FAILED，切换成功和切换失败。
# destroydestroy(): Promise
销毁 hls 实例。
# [静态] isSupportedstatic isSupported(): boolean
用于判断当前环境是否支持 hls 播放
# 事件下面是 hls 对象对外抛出的事件。作为插件使用时，需要监听 xgplayer 的 core_event 事件。
import Player from 'xplgayer'
import HlsPlugin, { Hls, EVENT } from 'xgplayer-hls'
// 作为插件使用
const player = new Player({
plugins: [HlsPlugin]
})
player.on('core_event', ({ eventName, ...rest }) => { // eventName: hls 事件名; rest: hls 事件回调函数参数
// 通过判断eventName来区分内核事件
if (eventName === EVENT.LOAD_START) {
// ...
}
})
hls 对外暴露 EVENT 常量，它是事件名常量，可以使用它来监听事件。
import { Hls, EVENT } from 'xgplayer-hls'
const hls = new Hls()
hls.on(EVENT.TTFB, () => {})
# TTFB分片请求开始到接收到请求响应。回调函数参数对象属性如下。
属性类型必须存在描述urlstring是请求 urlresponseUrlstring是响应 urlelapsednumber是耗时，毫秒# LOAD_START分片在发送请求之前触发，参数为 { url: string }，url 为请求 url 。
# LOAD_RESPONSE_HEADERS接收到请求响应头时触发，参数为 { headers: Headers | Recored
# LOAD_COMPLETE在请求完成后触发，参数为 { url: string }，url 为请求 url 。
# HLS_MANIFEST_LOADED主从m3u8格式时，master m3u8文件加载并解析完成后, 抛出master m3u8解析后的结构, 参数为 { playlist: MasterPlaylist }。
type MasterPlaylist = {
isMaster: boolean,
streams: Array
}
type MasterStream = {
id: number
bitrate: number
width: number
height: number
name: string
url: string
audioCodec: string
videoCodec: string
textCodec: string
audioGroup: string
audioStreams: Array
}
type AudioStream = {
id: number
url: string
group: string
name: string
lang: string
channels: number
segments: Array
}
type MediaSegment = {
sn: boolean // Media Sequence Number
cc: boolean // discontinue number index
url: string
title: string
start: string // segment start time(/s)
duration: string // segment duration(/s)
isInitSegment: boolean
initSegment: MedaiSegment
isLast: boolean
}
# HLS_LEVEL_LOADED二级m3u8加载并解析完成后，抛出解析后的结构， 参数为 { playlist: MediaPlaylist }。
type MediaPlaylist = {
version: number
url: string
type: string
startCC: number
endCC: number
startSN: number
endSN: number
totalDuration: number
targetDuration: number
live: boolean
segments: Array
}
type MediaSegment = {
sn: boolean // Media Sequence Number
cc: boolean // discontinue number index
url: string
title: string
start: string // segment start time(/s)
duration: string // segment duration(/s)
isInitSegment: boolean
initSegment: MedaiSegment
isLast: boolean
}
# LOAD_RETRY请求发生重试时触发。参数如下。
属性类型必须存在描述errorStreamingError是网络错误对象，请查看 API 错误章节retryTimenumber是第几次重试# SPEED当收集到网络速度统计时触发，参数如下。
属性类型必须存在描述timenumber是请求耗时，毫秒byteLengthnumber是下载的字节数# 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, 以毫秒为单位，如果需要以TS格式timescale(90000)为单位的时间戳信息，使用时此值 * 90
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 属性。
# SWITCH_URL_SUCCESSswitchURL 方法调用后，切换 url 成功后触发。
# SWITCH_URL_FAILEDswitchURL 方法调用后，切换 url 失败后触发。
# STREAM_EXCEPTION当解析音视频时，发生错误时触发。一共有 6 种类型的解析异常，它们通过参数的 type 属性进行区别。
hls.on(EVENT.STREAM_EXCEPTION, ({ type, ...info }) => {
type // 异常类型
info // 异常详情
})
type 可以是全大写下划线分隔的字符串，也可以使用 EVENT 常量找到对应字符串。
import { EVENT } from 'xgplayer-hls'
EVENT.LARGE_AV_FIRST_FRAME_GAP_DETECT === 'LARGE_AV_FIRST_FRAME_GAP_DETECT'
// true
# LARGE_AV_FIRST_FRAME_GAP_DETECT音视频偏移过大。详情对象属性如下。
videoBaseDts 视频第一帧的 dtsaudioBasePts 音频第一帧的 ptsbaseDts 等于 Math.min(audioBasePts, videoBaseDts)delta 等于 videoBaseDts - audioBasePts# LARGE_VIDEO_DTS_GAP_DETECT视频两帧之间间隔过大。详情对象属性如下。
time 当前帧的解码时间（秒），与 video 元素时间轴一致dts 修改后的 dtsoriginDts 原始 dtssampleDuration 该帧的时长refSampleDuration 参考帧时长# LARGE_AUDIO_DTS_GAP_DETECT两帧音频间隙过大，不会进行补针。详情对象属性如下。
time 当前帧的播放时间（秒），与 video 元素时间轴一致pts 修改后的 ptsoriginPts 原始 PtssampleDuration 该帧的时长refSampleDuration 参考帧时长# AUDIO_GAP_DETECT两帧音频间隙大，进行补帧。详情对象属性如下。
pts 修改后的 ptsoriginPts 原始 Ptscount 补了多少帧nextPts 补的第一帧的 ptsrefSampleDuration 参考帧时长# AUDIO_OVERLAP_DETECT两帧音频重叠，进行丢帧。详情对象属性如下。
pts 修改后的 ptsoriginPts 原始 Ptscount 补了多少帧nextPts 期望的 ptsrefSampleDuration 参考帧时长# MAX_DTS_DELTA_WITH_NEXT_SEGMENT_DETECT两个视频 Chunk 之间间隙过大，详情对象属性如下。
nextDts 期望的下一帧 dtsfirstSampleDts 该 Chunk 第一帧的 dtssampleDuration 等于 nextDts-firstSampleDts# 独立使用场景在独立使用场景下，上述事件是全部支持的，监听事件的方式与作为插件使用时有所区别
import { Hls, EVENT } from 'xgplayer-hls'
if (Hls.isSupported()) { // 使用静态方法
const hls = new Hls({
media: document.createElement('video')
})
hls.on(EVENT.SEI, (event) => { // 监听事件
// event定义与上述定义一致，不包括eventName属性
})
}