HLS.js 浏览器 HLS 播放完整指南:基于 MSE 的转封装架构、特性矩阵与工程实践
2026/9/21 3:04:24 网站建设 项目流程
  • 音视频
  • 前端

【免费下载链接】hls.js

HLS.js is a JavaScript library that plays HLS in browsers with support for MSE.

项目地址:https://gitcode.com/gh_mirrors/hl/hls.js
点击查看免费下载

HLS.js 是一个用 JavaScript 实现的 HTTP Live Streaming(HLS)客户端库,它直接运行在标准 HTML<video>元素之上,通过 MediaSource Extensions(MSE)在浏览器中完成 HLS 流媒体的拉流、解密、转封装与播放。本文以 hls.js 仓库的 README.md 为主线,结合源码级证据,系统讲解它的工作原理、支持的 HLS 标签与编解码格式、安装嵌入方式、核心 API、浏览器兼容性、构建体系与开发流程,帮助读者掌握用 HLS.js 在 Web 端播放 VOD / 直播 / 低延迟 HLS 的完整实战方案。

HLS.js 是什么:工作原理与核心管道

HLS.js 是一个实现 HTTP Live Streaming 客户端的 JavaScript 库,其播放链路依赖 HTML5 video 元素与 MediaSource Extensions(MSE)两大 Web 标准。它做的事情可以概括为:

将 MPEG-2 Transport Stream 以及 AAC/MP3 裸流**转封装(Transmux)**为 ISO BMFF(即 MP4 分片),再通过 MSE 的SourceBuffer追加进媒体元素进行播放。

关键在于 "Transmux"(转封装)——它只改变容器格式,不解码也不重新编码视频帧,因此开销远小于 Transcode。从源码看,转封装由多种 "demuxer + remuxer" 组合完成,见 src/demux/transmuxer.ts 中的MuxConfig

type MuxConfig = | { demux: typeof MP4Demuxer; remux: typeof PassThroughRemuxer } // fMP4 直通 | { demux: typeof TSDemuxer; remux: typeof MP4Remuxer } // MPEG-2 TS | { demux: typeof AC3Demuxer; remux: typeof MP4Remuxer } // AC-3(full 构建) | { demux: typeof AACDemuxer; remux: typeof MP4Remuxer } // ADTS AAC | { demux: typeof MP3Demuxer; remux: typeof MP4Remuxer }; // MPEG 音频

对应关系清晰可查:MP4 分片走MP4Demuxer + PassThroughRemuxer直接透传;TS 容器(H.264/H.265/ADTS AAC/MP3/AC-3/ID3 元数据)由 src/demux/tsdemuxer.ts 解复用后再由 src/remux/mp4-remuxer.ts 重封装为 fMP4。

转封装默认异步执行在 Web Worker 中(浏览器支持时)。src/demux/transmuxer-worker.ts 在 Worker 内实例化Transmuxer,主线程与 Worker 之间通过postMessage交换transmuxComplete/flush等消息,并使用 Transferable 对象转移ArrayBuffer以降低消息传递开销。这一设计避免了高码率分片解析阻塞 UI 主线程。

此外,HLS.js 也支持 HLS + fMP4(HLS 标准中直接携带 fMP4 分片的形式),这使其能够承载 HEVC、AV1、VP9、Dolby Vision 等现代视频编码(取决于运行环境是否支持)。

功能特性矩阵

HLS.js 的功能覆盖了 HLS 生态的绝大部分需求,以下为 README 中声明的完整特性清单:

  • VOD 与 Live 播放列表
    • Live 播放列表的 DVR(时移回看)支持
    • 低延迟 HLS(Low-Latency HLS):Partial Segments(部分分片)、Blocking Playlist Reload(阻塞式播放列表重载)、Playlist Delta Updates(Delta 更新)与 Rendition Reports
  • Fragmented MP4 容器
    • 视频:HEVC、AV1、VP9、Dolby Vision(受运行时支持限制)
    • 音频:AC-3、EC-3、FLAC、Opus、ALAC(受运行时支持限制)
    • 支持SUPPLEMENTAL-CODECS属性参与编码选择
  • MPEG-2 TS 容器
    • H.264(ITU-T H.264 / ISO/IEC 14496-10)与 H.265(ITU-T H.265 / ISO/IEC 23008-2,仅 full 构建)基本流
    • ADTS AAC 基本流(ISO/IEC 13818-7)
    • MPEG-1/2 Audio Layer III(MP3)基本流(ISO/IEC 11172-3 / 13818-3)
    • AC-3 / Dolby Digital 基本流(仅 full 构建)
    • 分组化元数据 ID3v2.3.0 基本流
  • AAC 容器(纯音频流)与MPEG Audio 容器(MP3 纯音频流)
  • 定时元数据:ID3(承载于 MPEG-2 TS)、Emsg(CMAF/fMP4)、以及播放列表中的DATERANGE标签;MPEG-2 TS 中的 MISB KLV 元数据可通过enableEmsgKLVMetadata选装开启
  • 加密与 DRM
    • AES-128、AES-256、AES-256-CTR 全分片解密
    • "identity" 格式 SAMPLE-AES 解密(仅限 MPEG-2 TS 分片)
    • EME(Encrypted Media Extensions)DRM 支持:fMP4 分片配合 FairPlay、PlayReady、Widevine CDM
  • 码率/清晰度控制:基于 HTMLMediaElement 分辨率、丢帧率与 HDCP-Level 的 Level 封顶(capping)
  • 字幕与隐藏字幕:CEA-608/708 隐藏字幕、WebVTT 字幕、IMSC1(TTML)字幕(限于 text profile 与 TTML 样式子集)
  • 自适应码流(ABR)
    • 手动与自动画质切换,提供 3 种切换模式(通过 API 控制):
      • Instant switching:在当前播放位置立即切换画质
      • Smooth switching:为下一个已加载分片切换画质
      • Bandwidth conservative switching:为下一个已加载分片切换画质,且不清空缓冲
    • 自动画质模式下,带宽骤降时可紧急降级(emergency switch down)以最小化缓冲
  • 多音轨:支持多变体播放列表中带备选音频的 Alternate Audio Track Rendition(VOD 与 Live)
  • HLS Interstitials:使用DATERANGE标签编排的广告插入与内容替换
  • I-frame 快进播放,包括图像 I-frame(mjpg)rendition
  • 精确 Seek:VOD 与 Live 均可精确到非分片/非关键帧边界
  • 缓冲区内 Seek:无需重新下载分片即可在缓冲与回看缓冲区内定位
  • 内置分析能力
    • 所有内部事件可被监控(网络事件、视频事件)
    • 暴露播放会话指标
    • 支持 Common Media Client Data(CMCD)
  • Content Steering(内容转向)
  • 错误韧性:库内建重试机制;可触发恢复动作以修复 fatal 媒体或网络错误
  • 冗余/故障切换播放列表(Redundant/Failover Playlists)
  • HLS 变量替换(Variable Substitution)

这些功能在源码中均有对应实现:例如 ABR 由 src/controller/abr-controller.ts 驱动、缓冲管理在 src/controller/buffer-controller.ts、DRM 在 src/controller/eme-controller.ts、广告插播在 src/controller/interstitials-controller.ts。所有控制器在 src/hls.ts 的构造函数中被按顺序装配成networkControllerscoreComponents,并通过事件总线(基于EventEmitter,见 src/events.ts)协作。

支持的 HLS 标签清单

HLS.js 的 M3U8 解析器位于 src/loader/m3u8-parser.ts。以下标签被完整支持(标签语义细节参考 HLS 规范 RFC 8216 bis 草案):

Multivariant Playlist(多变体播放列表)标签

  • #EXT-X-STREAM-INF:<attribute-list>+<URI>
  • #EXT-X-I-FRAME-STREAM-INF:I-frame 媒体播放列表
  • #EXT-X-MEDIA:<attribute-list>
  • #EXT-X-SESSION-DATA:<attribute-list>
  • #EXT-X-SESSION-KEY:<attribute-list>:EME Key-System 选择与预加载
  • #EXT-X-START:TIME-OFFSET=<n>
  • #EXT-X-CONTENT-STEERING:<attribute-list>:内容转向
  • #EXT-X-DEFINE:<attribute-list>:变量替换(NAME,VALUE,QUERYPARAM属性)

Media Playlist(媒体播放列表)标签

  • #EXTM3U(格式必需标识)
  • #EXT-X-VERSION:<n>(该值会被忽略)
  • #EXT-X-INDEPENDENT-SEGMENTS(被忽略)
  • #EXT-X-I-FRAMES-ONLY
  • #EXTINF:<duration>,[<title>]
  • #EXT-X-ENDLIST
  • #EXT-X-PLAYLIST-TYPE:<type-enum>(见下方 "Not Supported")
  • #EXT-X-MEDIA-SEQUENCE:<n>
  • #EXT-X-TARGETDURATION:<n>
  • #EXT-X-DISCONTINUITY
  • #EXT-X-DISCONTINUITY-SEQUENCE:<n>
  • #EXT-X-BITRATE:<rate>
  • #EXT-X-BYTERANGE:<n>[@<o>]
  • #EXT-X-MAP:<attribute-list>
  • #EXT-X-KEY:<attribute-list>KEYFORMAT="identity",METHOD=SAMPLE-AES仅支持 MPEG-2 TS 分片)
  • #EXT-X-PROGRAM-DATE-TIME:<date-time-msec>
  • #EXT-X-START:TIME-OFFSET=<n>
  • #EXT-X-SERVER-CONTROL:<attribute-list>
  • #EXT-X-PART-INF:PART-TARGET=<n>
  • #EXT-X-PART:<attribute-list>
  • #EXT-X-SKIP:<attribute-list>:Delta 播放列表
  • #EXT-X-RENDITION-REPORT:<attribute-list>
  • #EXT-X-DATERANGE:<attribute-list>:元数据,包含 HLS EXT-X-DATERANGE 广告插播 Schema
  • #EXT-X-DEFINE:<attribute-list>:变量导入与替换(NAME,VALUE,IMPORT,QUERYPARAM属性)
  • #EXT-X-GAP:跳过加载 GAP 分片与 part;当无合适备用节目时跳过仅含 GAP 内容的未缓冲节目

已解析但功能缺失#EXT-X-PRELOAD-HINT:<attribute-list>(解析器会识别该标签,但对应的预加载功能尚未实现)。

不支持的能力与边界

以下为 README 明确列出的不支持项,接入前请先对照排查:

  • #EXT-X-PLAYLIST-TYPE不用于根据 "Expires" 响应头决定媒体播放列表是否重载
  • 变体过滤/选择中不使用REQ-VIDEO-LAYOUT属性
  • "identity" 格式SAMPLE-AES密钥仅适用于 MPEG-2 TS 分片;fmp4、aac、mp3、vtt 等分片不支持
  • 加密的 MPEG-2 TS 分片不支持 FairPlay Streaming、PlayReady、Widevine
  • FairPlay Streaming 遗留密钥不支持(com.apple.fps.1_0请使用 Safari 原生播放)
  • ClearKey(org.w3.clearkey)支持不完整:key system 可被识别,但无法向 EME 控制器提供 key ID/密钥值对,因此不存在 license 或 session 路径
  • EC-3(Dolby Digital Plus)不支持 MPEG-2 TS 与无容器(纯音频)基本流;EC-3 仅在 fMP4 分片中受支持
  • MPEG-2 TS 中的 HEVC 与 AC-3 被排除在light构建之外(见构建常量__USE_M2TS_ADVANCED_CODECS__

Server-Side Rendering(SSR)与 Node.js 运行时

在 Node.js 中require该库是安全的——什么都不会发生。库会导出一个哑对象(dummy object),保证require不抛错,但 HLS.js 在 Node.js 中不可实例化。这使 SSR 框架(如 Next.js/Nuxt 的服务器端渲染)可以安全地静态引入 hls.js。

浏览器兼容性与运行时基线

HLS.js只兼容支持 MSE API 且接受video/MP4MIME 类型输入的浏览器。官方支持矩阵:

  • Chrome 47+(桌面)
  • Firefox 51+(桌面)
  • Windows 10+ 的 Edge
  • macOS 10.11+ 的 Safari 10+
  • iPadOS 13+ 的 Safari
  • iOS 17.1+ 的 Safari:自 hls.js v1.5.0 起通过 Managed Media Source(MMS)支持
  • Chrome for Android 5+
  • Firefox for Android 5+

这些版本是构建 UMD bundle 时传给@babel/preset-env的目标。UMD bundle 共享ES2016 运行时基线:ES5 风格语法 + 原生 ES2016 全局对象(MapSetPromiseArray.fromUint8Array.fromArray.prototype.includes等)。为控制包体积,不打包任何core-jspolyfill

值得注意的基线差异:CMCD 等可选功能会引入 ES2017 API(如Object.entries),因此 full UMD bundle 实际要求 ES2017 能力的运行时;而lightbundle 不包含这些功能,保持在 ES2016 基线。低于该基线的浏览器需要在使用 HLS.js 之前自行提供缺失全局对象的 polyfill。

dist/的两种分发变体

  • UMDdist/hls.jsdist/hls.min.jsdist/hls.light.jsdist/hls.light.min.js):可直接通过<script>标签嵌入(暴露全局Hls),或经package.jsonmain字段由require('hls.js')解析。配套的dist/hls.worker.js是打包好的转封装 Web Worker。
  • ESMdist/hls.mjsdist/hls.light.mjs及压缩版dist/hls.min.mjsdist/hls.light.min.mjs):import 'hls.js'module字段解析到未压缩的dist/hls.mjs,适合交给打包器二次压缩;.min.mjs用于通过<script type="module">从 CDN 直接加载。ESM 以@babel/preset-envesmodules: true为目标(约 Chrome 61+、Firefox 60+、Safari 10.1+、Edge 16+),使用 ES2015+ 语法但低于 ES2019(无Array.prototype.flatMapObject.fromEntries等)。

重要差异:ESM 构建不内联转封装 Web Worker。UMD 构建内联了 Worker,但dist/hls.mjsdist/hls.min.mjs没有,因此若不指定workerPath,转封装将运行在主线程。可按如下方式指定独立发布的 Worker:

const hls = new Hls({ workerPath: 'https://cdn.jsdelivr.net/npm/hls.js@1/dist/hls.worker.js', });

如果你直接从src/导入,或在自己的构建中包含未转译的运行时依赖,将绕过 Babel 管道、自行承担转译责任——这些源码模块可能使用到发布包中已被 tree-shaking 移除的 ES2019+ API。

另请注意:Safari(iOS、iPadOS、macOS)本身支持通过 video 标签的普通srcURL 播放 HLS。若目标平台既无 MSE 也无原生 HLS 支持,则该平台无法播放 HLS。若期望覆盖 HLS.js 兼容范围之外的多平台(App、智能电视、机顶盒),流媒体必须严格遵循 RFC 8216 规范。

安装与嵌入:三种接入方式

安装

npm install --save hls.js

若希望跟踪开发分支(master),可安装 canary 频道:

npm install hls.js@canary

方式一:脚本标签直接嵌入(优先 HLS.js MSE 播放)

直接在页面中引入dist/hls.jsdist/hls.min.js。该方案优先使用 HLS.js 的 MSE 播放,而非浏览器原生 HLS 播放:

<script src="https://cdn.jsdelivr.net/npm/hls.js@1"></script> <!-- 或者使用主分支上的最新版本 --> <!-- <script src="https://cdn.jsdelivr.net/npm/hls.js@canary"></script> --> <video id="video"></video> <script> var video = document.getElementById('video'); var videoSrc = 'https://test-streams.mux.dev/x36xhzz/x36xhzz.m3u8'; if (Hls.isSupported()) { var hls = new Hls(); hls.loadSource(videoSrc); hls.attachMedia(video); } // HLS.js 无法运行在没有启用 Media Source Extensions (MSE) 的平台上。 // // 当浏览器内置 HLS 支持时(用 canPlayType 检测), // 可以直接把 HLS manifest(即 .m3u8 URL)通过 src 属性交给 video 元素, // 这走的是普通 video 元素的内置能力,不经过 HLS.js。 else if (video.canPlayType('application/vnd.apple.mpegurl')) { video.src = videoSrc; } </script>

方式二:先检测原生支持、再回退到 HLS.js

交换两个条件分支即可实现"原生优先、HLS.js 兜底":

注意:video.canPlayType('application/vnd.apple.mpegurl')在 Safari、Chrome 等浏览器中会返回非空字符串("maybe"),但并非所有浏览器对 HLS 内容的支持都可靠——例如 Chrome 147 报告支持却可能无法原生播放某些流。除非你确实需要原生播放,否则推荐默认方案(先Hls.isSupported())。

<script src="https://cdn.jsdelivr.net/npm/hls.js@1"></script> <!-- 或者使用主分支上的最新版本 --> <!-- <script src="https://cdn.jsdelivr.net/npm/hls.js@canary"></script> --> <video id="video"></video> <script> var video = document.getElementById('video'); var videoSrc = 'https://test-streams.mux.dev/x36xhzz/x36xhzz.m3u8'; // // 仅在浏览器具备 ManagedMediaSource(如现代 Safari)时才走原生 HLS, // 因为那里的原生播放支持良好;其他浏览器可能报告支持却无法可靠播放某些流。 // if ( video.canPlayType('application/vnd.apple.mpegurl') && 'ManagedMediaSource' in window ) { video.src = videoSrc; // // 不走原生 HLS 时,检查 HLS.js 是否受支持 // } else if (Hls.isSupported()) { var hls = new Hls(); hls.loadSource(videoSrc); hls.attachMedia(video); } </script>

方式三:确保视频时间的精确对应

HLS 转封装原始视频文件时,常常会把首帧的时间往前推一点。如果你需要原始视频帧时间与 HLS 流时间精确一致,需要把这部分偏移计算出来并加以补偿:

let tOffset = 0; const getAppendedOffset = (eventName, { frag }) => { if (frag.type === 'main' && frag.sn !== 'initSegment' && frag.elementaryStreams.video) { const { start, startDTS, startPTS, maxStartPTS, elementaryStreams } = frag; tOffset = elementaryStreams.video.startPTS - start; hls.off(Hls.Events.BUFFER_APPENDED, getAppendedOffset); console.log('video timestamp offset:', tOffset, { start, startDTS, startPTS, maxStartPTS, elementaryStreams }); } } hls.on(Hls.Events.BUFFER_APPENDED, getAppendedOffset); // 然后按偏移补偿,例如: const video = document.querySelector('video'); video.addEventListener('timeupdate', () => setTime(Math.max(0, video.currentTime - tOffset)) const seek = (t) => video.currentTime = t + tOffset; const getDuration = () => video.duration - tOffset;

更多嵌入与 API 示例见 docs/API.md。

核心 API 与关键配置

Hls 类:能力检测与实例化

核心类是Hls(见 src/hls.ts),其静态方法承担能力检测职责:

  • Hls.isSupported():检测 MSE 是否可用且isTypeSupported对任一基线编码通过。src/is-supported.ts 的实现显示,它会对avc1.42E01E,mp4a.40.2av01.0.01M.08vp09.00.50.08视频组合以及mp4a.40.2fLaC音频组合调用mediaSource.isTypeSupported
  • Hls.isMSESupported():仅检测 MSE API 本身是否存在且 SourceBuffer 原型上具备appendBuffer/remove方法。
  • Hls.getMediaSource():返回用于 MSE 播放的全局对象(ManagedMediaSource、MediaSource 或 WebKitMediaSource 之一)。
  • Hls.Events/Hls.ErrorTypes/Hls.ErrorDetails:事件名与错误类型的命名空间,供hls.on(...)订阅使用。

实例的核心方法(源码签名均可在 src/hls.ts 中查到):

API说明
hls.loadSource(url)设置源 URL(相对或绝对均可),随后触发 manifest 加载
hls.attachMedia(video)将 Hls.js 挂载到媒体元素;换源时会自动 detach 并重新 attach
hls.detachMedia()从媒体元素卸载
hls.startLoad(position?)开始加载数据,position默认 -1(从最早点开始)
hls.stopLoad()停止加载
hls.destroy()销毁实例并释放引用
hls.recoverMediaError()媒体元素出错时一键 detach + re-attach 并恢复
hls.swapAudioCodec()交换可能的音频编码(如立体声与 5.1 之间)
hls.on/once/off事件订阅,事件对象见Hls.Events

画质切换相关的属性(对应 README 中"3 种切换模式"):

  • hls.currentLevel = n:立即切换,会清空当前缓冲尽快替换画质(播放会短暂中断以重新缓冲);设为-1回到自动选择。对应 "Instant switching"。
  • hls.nextLevel = n:为下一个已加载分片切换画质,不中断播放;可能中止当前加载并冲刷当前播放分片区域之外的缓冲。对应 "Smooth switching"。
  • hls.loadLevel = n:以保守方式为下一个已加载数据切换画质,不清空缓冲,但会中断当前加载;实际生效要等已有缓冲播完。对应 "Bandwidth conservative switching"。
  • hls.nextLoadLevel:为下一个分片设置画质,完全"非破坏性",等待当前加载完成后再切换。
  • 另有用到的startLevelfirstLevelautoLevelCappingmaxHdcpLevelbandwidthEstimate等。

这些 setter 在源码中都写入了levelController.manualLevel并配合streamControllerimmediateLevelSwitch()/nextLevelSwitch()工作,实现上述三种语义差异。

常用配置项与默认值

Hls 实例的配置 = 用户传入的userConfig覆盖在Hls.DefaultConfig之上合并而成。Hls.DefaultConfig可以静态读写以修改所有后续实例的默认值。默认配置定义在 src/config.ts 的hlsDefaultConfig中,以下为高频配置项及其默认值:

配置项默认值作用
autoStartLoadtrue设置源后是否自动开始加载
startPosition-1自动开始加载的起始位置
debugfalse开启日志输出
maxBufferLength30最大缓冲时长(秒)
backBufferLengthInfinity保留在缓冲中的回看时长
maxBufferSize60 * 1000 * 1000最大缓冲字节数(60 MB)
maxBufferHole0.1容忍的缓冲空洞(秒)
maxFragLookUpTolerance0.25分片查找容差
liveSyncDurationCount3直播同步的 target duration 倍数
liveSyncDurationundefined直播同步点距 live edge 的秒数
liveMaxLatencyDurationCountInfinity直播最大延迟(按 target duration 计数)
liveSyncOnStallIncrease1直播失速增加时同步
maxLiveSyncPlaybackRate1追赶直播用的最大播放速率
lowLatencyModetrue低延迟 HLS 模式
enableWorkertrue是否在 Web Worker 中执行转封装
workerPathnull自定义 Worker 路径(ESM 构建必需)
enableSoftwareAEStrue软件 AES 解密开关
abrEwmaDefaultEstimate5e5ABR 默认带宽估计(500 kbps)
abrBandWidthFactor0.95ABR 带宽因子
abrBandWidthUpFactor0.7ABR 升档带宽因子
minAutoBitrate0自动模式下可选的最小码率
capLevelToPlayerSizefalse是否按播放器尺寸封顶画质
capLevelOnFPSDropfalse丢帧时是否封顶画质
emeEnabledfalse是否启用 EME DRM
drmSystems{}DRM 系统配置(licenseUrl 等)
cmcdundefinedCMCD 客户端数据配置
enableDateRangeMetadataCuestrue是否生成 DATERANGE 元数据 cue
enableEmsgMetadataCuestrue是否生成 Emsg 元数据 cue
enableEmsgKLVMetadatafalse是否解析 TS 中 MISB KLV 元数据
progressivefalse渐进式流媒体模式
startLevelundefined起始画质等级(-1 表示自动)

此外还有完整的加载策略体系:certLoadPolicykeyLoadPolicymanifestLoadPolicyplaylistLoadPolicyfragLoadPolicysteeringManifestLoadPolicy等,分别控制证书/密钥/主清单/媒体播放列表/分片/转向清单的maxTimeToFirstByteMsmaxLoadTimeMstimeoutRetryerrorRetry参数(默认值见 src/config.ts)。例如分片加载fragLoadPolicy默认maxTimeToFirstByteMs: 10000maxLoadTimeMs: 120000、超时重试最多 4 次、错误重试最多 6 次——这正是 README 所述"库内建重试机制"的落地之处。

CORS 与视频控制

所有 HLS 资源必须带有允许GET请求的 CORS 头。由于 HLS.js 通过fetch/XHR拉取 manifest、分片与密钥,跨域资源缺少 CORS 头将直接导致加载失败。

视频本身通过标准 HTML<video>元素的HTMLVideoElement方法、事件与可选 UI 控件(<video controls>)进行控制——HLS.js 不接管播放控制,只负责提供媒体数据。

开发与构建体系

起步

git clone https://github.com/video-dev/hls.js.git cd hls.js # 克隆或拉取代码后,确保依赖最新 npm install ci # 启动 demo 页开发服务器(文件监听时重新编译,但不写实际 dist 产物) npm run dev # 修改代码后运行 sanity-check,验证提交前的全部检查 npm run sanity-check

开发服务器监听 8000 端口,启动后可访问http://localhost:8000/demo/查看 demo。提交 PR 前请阅读 CONTRIBUTING.md。

构建任务

构建所有 flavor(适合生产/CI):

npm install ci npm run build

仅构建 debug 产物:

npm run build:debug

构建并监听(适用于自定义开发环境,例如在子模块/子项目中由其他服务器托管):

npm run build:watch

只构建指定 flavor(已知配置:fullfullMinfullEsmfullEsmMinlightlightMinlightEsmlightEsmMinworkerdemo):

npm run build -- --configType fullMin # 可重复 --configType 构建多个

这些 flavor 由 rollup.config.js 读取build-config.js中的配置列表,configType筛选后执行对应的 Rollup 构建。

报告构建产物dist/文件大小,并对照 dist-size-budget.json 中的预算检查(CI 也运行同一检查):

npm run size npm run size:check

light 构建的裁剪范围

hls.light.*.js不包含:备选音轨(alternate-audio)、字幕、CMCD、EME(DRM)、变量替换、Interstitials、I-frame trick-play、Media Capabilities,以及 MPEG-2 TS 高级编码(HEVC 与 AC-3)。Content Steering 包含在内。此外 light 构建中下列类型不可用:

  • AudioStreamController
  • AudioTrackController
  • CuesInterface
  • EMEController
  • SubtitleStreamController
  • SubtitleTrackController
  • TimelineController
  • CMCDController
  • InterstitialsController
  • InterstitialsManager
  • IFrameController
  • HlsIFramesOnly
  • HlsImageIFramesOnly

代码质量与测试

  • Linter(ESLint)
npm run lint # 运行检查 npm run lint:fix # 自动修复 npm run lint:quiet # 仅报错(忽略警告)
  • 格式化(Prettier)
npm run prettier
  • 类型检查
npm run type-check
  • 自动化测试(Mocha/Karma)
npm test # 运行全部测试 npm run test:unit # 单元测试(Karma,可在真实浏览器中运行) npm run test:unit:watch # 单元测试 watch 模式 npm run test:func # 功能(集成)测试

单元测试覆盖位于 tests/unit,功能测试位于 tests/functional。一次提交前的完整质量门禁为npm run sanity-check,它依次执行 lint、prettier 校验、类型检查、构建、es-check、文档生成与单元测试。

生态与集成

已知集成 HLS.js 的播放器

以下播放器集成了 HLS.js 用于 HLS 播放(README 所列):JW Player、Akamai Adaptive Media Player(AMP)、BridTV Player、Clappr、Flowplayer(经 flowplayer-hlsjs)、MediaElement.js、KalturaPlayer(经 kaltura-player-js)、Videojs(经 videojs-hlsjs / videojs-hls.js / videojs-contrib-hls.js 等多个 SourceHandler 插件)、Fluid Player、OpenPlayerJS、CDNBye(基于 WebRTC Datachannel 的 hls.js P2P 引擎)、M3U IPTV、ArtPlayer、IPTV Player。

生产环境使用者

README 中列出的生产环境使用者包括 adultswim、Akamai、Canal+、Dailymotion、freshlive、mux、foxsports.com.au、globo、gunosy、NYTimes、peer5、qbrick、radiantmediaplayer、rts、snapstream、streamamg、streamshark、tablo、streamroot、ted、clevercast、Viacom、vk、jwplayer、kaltura、showmax、1tv、zdf、brid、cdn77、r7、p2p-media-loader、kayosports、flosports、axon、rutube、labra-flex、streamfizz 等。另外有 Chrome/Firefox 浏览器插件(native-hls)支持从地址栏直接播放 m3u8 链接。

深入阅读:设计与 API 文档

  • 架构设计总览:docs/design.md 介绍了项目的模块划分、事件流与错误处理设计。
  • API 与用法文档(含代码示例):docs/API.md,其中覆盖了从"支持检测 → 实例化 → 绑定视频元素 → 加载 manifest → 错误处理 → 销毁/切换流"的完整五步流程,以及capLevelToPlayerSizemaxBufferLengthliveSyncDuration等全部细粒度配置项、recoverMediaError()等 fatal 错误恢复方式的示例代码。
  • 类型定义:构建产物中的dist/hls.d.ts提供了完整的 TypeScript 类型;仓库内的 API 报告见 api-extractor/report/hls.js.api.md。

许可

HLS.js 以 Apache 2.0 协议发布,详见 LICENSE。该协议允许自由使用、修改与分发(含商用场景),同时保留版权与许可声明要求。

  • 音视频
  • 前端

【免费下载链接】hls.js

HLS.js is a JavaScript library that plays HLS in browsers with support for MSE.

项目地址:https://gitcode.com/gh_mirrors/hl/hls.js
点击查看免费下载
上一篇:突破Kafka-Docker性能瓶颈:3大核心优化策略让消息吞吐提升300%
下一篇:AssetRipper 实战指南:从 Unity 游戏资源提取到导出可复用项目

创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考

需要专业的网站建设服务?

联系我们获取免费的网站建设咨询和方案报价,让我们帮助您实现业务目标

立即咨询