- 音视频
- 前端
【免费下载链接】hls.js
HLS.js is a JavaScript library that plays HLS in browsers with support for MSE.
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)以最小化缓冲
- 手动与自动画质切换,提供 3 种切换模式(通过 API 控制):
- 多音轨:支持多变体播放列表中带备选音频的 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 的构造函数中被按顺序装配成networkControllers与coreComponents,并通过事件总线(基于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 全局对象(Map、Set、Promise、Array.from、Uint8Array.from、Array.prototype.includes等)。为控制包体积,不打包任何core-jspolyfill。
值得注意的基线差异:CMCD 等可选功能会引入 ES2017 API(如Object.entries),因此 full UMD bundle 实际要求 ES2017 能力的运行时;而lightbundle 不包含这些功能,保持在 ES2016 基线。低于该基线的浏览器需要在使用 HLS.js 之前自行提供缺失全局对象的 polyfill。
dist/的两种分发变体
- UMD(
dist/hls.js、dist/hls.min.js、dist/hls.light.js、dist/hls.light.min.js):可直接通过<script>标签嵌入(暴露全局Hls),或经package.json的main字段由require('hls.js')解析。配套的dist/hls.worker.js是打包好的转封装 Web Worker。 - ESM(
dist/hls.mjs、dist/hls.light.mjs及压缩版dist/hls.min.mjs、dist/hls.light.min.mjs):import 'hls.js'经module字段解析到未压缩的dist/hls.mjs,适合交给打包器二次压缩;.min.mjs用于通过<script type="module">从 CDN 直接加载。ESM 以@babel/preset-env的esmodules: true为目标(约 Chrome 61+、Firefox 60+、Safari 10.1+、Edge 16+),使用 ES2015+ 语法但低于 ES2019(无Array.prototype.flatMap、Object.fromEntries等)。
重要差异:ESM 构建不内联转封装 Web Worker。UMD 构建内联了 Worker,但
dist/hls.mjs与dist/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.js或dist/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.2、av01.0.01M.08、vp09.00.50.08视频组合以及mp4a.40.2、fLaC音频组合调用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:为下一个分片设置画质,完全"非破坏性",等待当前加载完成后再切换。- 另有用到的
startLevel、firstLevel、autoLevelCapping、maxHdcpLevel、bandwidthEstimate等。
这些 setter 在源码中都写入了levelController.manualLevel并配合streamController的immediateLevelSwitch()/nextLevelSwitch()工作,实现上述三种语义差异。
常用配置项与默认值
Hls 实例的配置 = 用户传入的userConfig覆盖在Hls.DefaultConfig之上合并而成。Hls.DefaultConfig可以静态读写以修改所有后续实例的默认值。默认配置定义在 src/config.ts 的hlsDefaultConfig中,以下为高频配置项及其默认值:
| 配置项 | 默认值 | 作用 |
|---|---|---|
autoStartLoad | true | 设置源后是否自动开始加载 |
startPosition | -1 | 自动开始加载的起始位置 |
debug | false | 开启日志输出 |
maxBufferLength | 30 | 最大缓冲时长(秒) |
backBufferLength | Infinity | 保留在缓冲中的回看时长 |
maxBufferSize | 60 * 1000 * 1000 | 最大缓冲字节数(60 MB) |
maxBufferHole | 0.1 | 容忍的缓冲空洞(秒) |
maxFragLookUpTolerance | 0.25 | 分片查找容差 |
liveSyncDurationCount | 3 | 直播同步的 target duration 倍数 |
liveSyncDuration | undefined | 直播同步点距 live edge 的秒数 |
liveMaxLatencyDurationCount | Infinity | 直播最大延迟(按 target duration 计数) |
liveSyncOnStallIncrease | 1 | 直播失速增加时同步 |
maxLiveSyncPlaybackRate | 1 | 追赶直播用的最大播放速率 |
lowLatencyMode | true | 低延迟 HLS 模式 |
enableWorker | true | 是否在 Web Worker 中执行转封装 |
workerPath | null | 自定义 Worker 路径(ESM 构建必需) |
enableSoftwareAES | true | 软件 AES 解密开关 |
abrEwmaDefaultEstimate | 5e5 | ABR 默认带宽估计(500 kbps) |
abrBandWidthFactor | 0.95 | ABR 带宽因子 |
abrBandWidthUpFactor | 0.7 | ABR 升档带宽因子 |
minAutoBitrate | 0 | 自动模式下可选的最小码率 |
capLevelToPlayerSize | false | 是否按播放器尺寸封顶画质 |
capLevelOnFPSDrop | false | 丢帧时是否封顶画质 |
emeEnabled | false | 是否启用 EME DRM |
drmSystems | {} | DRM 系统配置(licenseUrl 等) |
cmcd | undefined | CMCD 客户端数据配置 |
enableDateRangeMetadataCues | true | 是否生成 DATERANGE 元数据 cue |
enableEmsgMetadataCues | true | 是否生成 Emsg 元数据 cue |
enableEmsgKLVMetadata | false | 是否解析 TS 中 MISB KLV 元数据 |
progressive | false | 渐进式流媒体模式 |
startLevel | undefined | 起始画质等级(-1 表示自动) |
此外还有完整的加载策略体系:certLoadPolicy、keyLoadPolicy、manifestLoadPolicy、playlistLoadPolicy、fragLoadPolicy、steeringManifestLoadPolicy等,分别控制证书/密钥/主清单/媒体播放列表/分片/转向清单的maxTimeToFirstByteMs、maxLoadTimeMs、timeoutRetry与errorRetry参数(默认值见 src/config.ts)。例如分片加载fragLoadPolicy默认maxTimeToFirstByteMs: 10000、maxLoadTimeMs: 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(已知配置:full、fullMin、fullEsm、fullEsmMin、light、lightMin、lightEsm、lightEsmMin、worker、demo):
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:checklight 构建的裁剪范围
hls.light.*.js不包含:备选音轨(alternate-audio)、字幕、CMCD、EME(DRM)、变量替换、Interstitials、I-frame trick-play、Media Capabilities,以及 MPEG-2 TS 高级编码(HEVC 与 AC-3)。Content Steering 包含在内。此外 light 构建中下列类型不可用:
AudioStreamControllerAudioTrackControllerCuesInterfaceEMEControllerSubtitleStreamControllerSubtitleTrackControllerTimelineControllerCMCDControllerInterstitialsControllerInterstitialsManagerIFrameControllerHlsIFramesOnlyHlsImageIFramesOnly
代码质量与测试
- 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 → 错误处理 → 销毁/切换流"的完整五步流程,以及
capLevelToPlayerSize、maxBufferLength、liveSyncDuration等全部细粒度配置项、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.
相关推荐
HLS.js实战指南:从零构建浏览器直播播放器
HLS.js实战指南:从零构建浏览器直播播放器 HLS.js是一款强大的JavaScript库,能够在支持MSE(媒体源扩展)的浏览器中播放HLS(HTTP直播
音视频前端在 Next.js 中集成 HLS.js 实现跨浏览器 HLS 视频播放
在 Next.js 中集成 HLS.js 实现跨浏览器 HLS 视频播放 导读 本指南围绕 Next.js 官方示例仓库中的 examples/with hls
前端后端Web框架SSR前端构建突破浏览器限制:HLS.js与MSE打造无缝流媒体播放体验
突破浏览器限制:HLS.js与MSE打造无缝流媒体播放体验 你是否遇到过网页视频加载缓慢、频繁缓冲或画质忽高忽低的问题?作为运营或开发人员,如何在各种浏览器中提
音视频前端
创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考