侧边栏壁纸
博主头像
邱少羽梦 博主等级

90后北漂程序员,认真写好每一行代码

  • 累计撰写 59 篇文章
  • 累计创建 65 个标签
  • 累计收到 43 条评论

目 录CONTENT

文章目录
程序员专栏

hls.js 官方 API 中文文档

邱少羽梦
邱少羽梦
2025-02-13 / 0 评论 / 0 点赞 / 57 阅读 / 104995 字 / 正在检测是否收录...
温馨提示：
本文最后更新于 2025-03-12，若内容或图片失效，请留言反馈。部分素材来自网络，若不小心影响到您的利益，请联系我们删除。

HLS.js v1 API

请参阅 API 参考 获取 "hls.js" 包中可用的完整接口列表。

快速开始

第一步：设置与支持

首先，在网页中包含 https://cdn.jsdelivr.net/npm/hls.js@1（或 /hls.js 用于未压缩版本）。

<script src="//cdn.jsdelivr.net/npm/hls.js@1"></script>

调用静态方法 Hls.isSupported() 来检查浏览器是否支持 MediaSource Extensions 以及任何基线编解码器。

<script src="https://cdn.jsdelivr.net/npm/hls.js@1"></script>
<script>
  if (Hls.isSupported()) {
    console.log('Hello HLS.js!');
  }
</script>

如果你想在不测试基线编解码器的情况下测试 MSE 支持，可以使用 isMSESupported：

if (
  Hls.isMSESupported() &&
  Hls.getMediaSource().isTypeSupported('video/mp4;codecs="av01.0.01M.08"')
) {
  console.log('Hello AV1 playback! AVC who?');
}

第二步：实例化 Hls 对象并将其绑定到 <video> 元素

让我们：

  • 创建一个 <video> 元素
  • 创建一个新的 HLS 对象
  • 将视频元素绑定到该 HLS 对象
<script src="https://cdn.jsdelivr.net/npm/hls.js@1"></script>

<video id="video"></video>
<script>
  if (Hls.isSupported()) {
    var video = document.getElementById('video');

    // 如果你使用的是 ESM 版本的库（hls.mjs），
    // 如果你希望使用 Web Worker，应在此处指定 "workerPath" 配置选项。
    // 请注意，打包工具（如 webpack）可能会默认使用 ESM 版本。
    var hls = new Hls();

    // 将它们绑定在一起
    hls.attachMedia(video);
    // MEDIA_ATTACHED 事件在 MediaSource 准备就绪时由 hls 对象触发
    hls.on(Hls.Events.MEDIA_ATTACHED, function () {
      console.log('video and hls.js are now bound together !');
    });
  }
</script>

第三步：加载清单文件

你需要提供清单文件的 URL，如下所示：

<script src="https://cdn.jsdelivr.net/npm/hls.js@1"></script>

<video id="video"></video>
<script>
  if (Hls.isSupported()) {
    var video = document.getElementById('video');
    var hls = new Hls();
    hls.on(Hls.Events.MEDIA_ATTACHED, function () {
      console.log('video and hls.js are now bound together !');
    });
    hls.on(Hls.Events.MANIFEST_PARSED, function (event, data) {
      console.log(
        'manifest loaded, found ' + data.levels.length + ' quality level',
      );
    });
    hls.loadSource('http://my.streamURL.com/playlist.m3u8');
    // 将它们绑定在一起
    hls.attachMedia(video);
  }
</script>

第四步：通过 <video> 元素控制

视频通过 HTML <video> 元素进行控制。

可以无缝使用 HTMLVideoElement 的控制和事件。

video.play();

第五步：错误处理

所有错误都通过一个唯一的事件进行通知。

每个错误都按错误类型、错误详细信息以及是否致命进行分类：

  • 错误类型：
    • Hls.ErrorTypes.NETWORK_ERROR 用于网络相关错误
    • Hls.ErrorTypes.MEDIA_ERROR 用于媒体/视频相关错误
    • Hls.ErrorTypes.KEY_SYSTEM_ERROR 用于 EME 相关错误
    • Hls.ErrorTypes.MUX_ERROR 用于解复用/复用相关错误
    • Hls.ErrorTypes.OTHER_ERROR 用于所有其他错误
  • 错误详细信息：
  • 错误是否致命：
    • false 如果错误不致命，HLS.js 将尝试恢复。
    • true 如果错误致命，所有恢复尝试均已执行。有关如何配置重试的详细信息，请参阅 LoadPolicies。

完整详细信息在 下文 中描述。

查看以下示例代码以监听错误：

hls.on(Hls.Events.ERROR, function (event, data) {
  var errorType = data.type;
  var errorDetails = data.details;
  var errorFatal = data.fatal;

  switch (data.details) {
    case Hls.ErrorDetails.FRAG_LOAD_ERROR:
      // ....
      break;
    default:
      break;
  }
});

致命错误恢复

HLS.js 提供了几种方法，用于在 HTMLMediaElement 中发生解码错误时尝试恢复播放：

hls.recoverMediaError()

重置 MediaSource 并从最后一个已知的播放位置重新开始流媒体。

错误恢复示例代码
hls.on(Hls.Events.ERROR, function (event, data) {
  if (data.fatal) {
    switch (data.type) {
      case Hls.ErrorTypes.MEDIA_ERROR:
        console.log('fatal media error encountered, try to recover');
        hls.recoverMediaError();
        break;
      case Hls.ErrorTypes.NETWORK_ERROR:
        console.error('fatal network error encountered', data);
        // 所有重试和媒体选项均已用尽。
        // 立即尝试重新开始加载可能会导致循环加载。
        // 考虑修改加载策略以最适合你的资源和网络条件（manifestLoadPolicy、playlistLoadPolicy、fragLoadPolicy）。
        break;
      default:
        // 无法恢复
        hls.destroy();
        break;
    }
  }
});
hls.swapAudioCodec()

在处理用户代理无法正确处理 HE-AAC 和 AAC 音频（mp4a.40.5 和 mp4a.40.2）编解码器和媒体时，可以使用 hls.swapAudioCodec() 代替 hls.recoverMediaError()。

这不再需要，也不推荐使用。如果你发现需要它的情况，请 提交一个 bug 并提供重现步骤。

最后一步：销毁、切换流

应调用 hls.destroy() 以释放使用的资源并销毁 hls 上下文。

微调

可以在实例化 Hls 对象时提供配置参数。

var config = {
  autoStartLoad: true,
  startPosition: -1,
  debug: false,
  capLevelOnFPSDrop: false,
  capLevelToPlayerSize: false,
  defaultAudioCodec: undefined,
  initialLiveManifestSize: 1,
  maxBufferLength: 30,
  maxMaxBufferLength: 600,
  backBufferLength: Infinity,
  frontBufferFlushThreshold: Infinity,
  maxBufferSize: 60 * 1000 * 1000,
  maxBufferHole: 0.1,
  highBufferWatchdogPeriod: 2,
  nudgeOffset: 0.1,
  nudgeMaxRetry: 3,
  maxFragLookUpTolerance: 0.25,
  liveSyncDurationCount: 3,
  liveSyncOnStallIncrease: 1,
  liveMaxLatencyDurationCount: Infinity,
  liveDurationInfinity: false,
  preferManagedMediaSource: false,
  enableWorker: true,
  enableSoftwareAES: true,
  fragLoadPolicy: {
    default: {
      maxTimeToFirstByteMs: 9000,
      maxLoadTimeMs: 100000,
      timeoutRetry: {
        maxNumRetry: 2,
        retryDelayMs: 0,
        maxRetryDelayMs: 0,
      },
      errorRetry: {
        maxNumRetry: 5,
        retryDelayMs: 3000,
        maxRetryDelayMs: 15000,
        backoff: 'linear',
      },
    },
  },
  startLevel: undefined,
  audioPreference: {
    characteristics: 'public.accessibility.describes-video',
  },
  subtitlePreference: {
    lang: 'en-US',
  },
  startFragPrefetch: false,
  testBandwidth: true,
  progressive: false,
  lowLatencyMode: true,
  fpsDroppedMonitoringPeriod: 5000,
  fpsDroppedMonitoringThreshold: 0.2,
  appendErrorMaxRetry: 3,
  loader: customLoader,
  fLoader: customFragmentLoader,
  pLoader: customPlaylistLoader,
  xhrSetup: XMLHttpRequestSetupCallback,
  fetchSetup: FetchSetupCallback,
  abrController: AbrController,
  bufferController: BufferController,
  capLevelController: CapLevelController,
  fpsController: FPSController,
  timelineController: TimelineController,
  enableDateRangeMetadataCues: true,
  enableMetadataCues: true,
  enableID3MetadataCues: true,
  enableWebVTT: true,
  enableIMSC1: true,
  enableCEA708Captions: true,
  stretchShortVideoTrack: false,
  maxAudioFramesDrift: 1,
  forceKeyFrameOnDiscontinuity: true,
  abrEwmaFastLive: 3.0,
  abrEwmaSlowLive: 9.0,
  abrEwmaFastVoD: 3.0,
  abrEwmaSlowVoD: 9.0,
  abrEwmaDefaultEstimate: 500000,
  abrEwmaDefaultEstimateMax: 5000000,
  abrBandWidthFactor: 0.95,
  abrBandWidthUpFactor: 0.7,
  abrMaxWithRealBitrate: false,
  maxStarvationDelay: 4,
  maxLoadingDelay: 4,
  minAutoBitrate: 0,
  emeEnabled: false,
  licenseXhrSetup: undefined,
  drmSystems: {},
  drmSystemOptions: {},
  requestMediaKeySystemAccessFunc: requestMediaKeySystemAccess,
  cmcd: {
    sessionId: uuid(),
    contentId: hash(contentURL),
    useHeaders: false,
  },
};

var hls = new Hls(config);

Hls.DefaultConfig get/set

该 getter/setter 允许获取和覆盖 Hls 的默认配置。此配置将默认应用于所有实例。

capLevelToPlayerSize

（默认值：false）

  • 如果设置为 true，自适应算法将根据 HTML 视频元素的尺寸（宽度和高度）限制在自动质量模式下可用的级别。如果多个级别的尺寸相同，则选择带宽最大的级别。在某些设备上，视频元素的尺寸将乘以设备像素比。使用 ignoreDevicePixelRatio 可以基于视频元素的大小进行严格的级别限制。
  • 如果设置为 false，级别将不受限制。所有可用级别都可以在自动质量模式下使用，仅考虑带宽。

capLevelOnFPSDrop

（默认值：false）

  • 当设置为 true 时，如果在 config.fpsDroppedMonitoringPeriod 期间掉帧的数量超过了 config.fpsDroppedMonitoringThreshold 设置的比率，则质量级别将下降并限制在该较低级别。
  • 当设置为 false 时，级别将不受限制。所有可用级别都可以在自动质量模式下使用，仅考虑带宽。

ignoreDevicePixelRatio

（默认值：false）

  • 当设置为 true 时，与播放器大小相关的计算将忽略浏览器的 devicePixelRatio。
  • 当设置为 false 时，与播放器大小相关的计算将尊重浏览器的 devicePixelRatio。

maxDevicePixelRatio

（默认值：Number.POSITIVE_INFINITY）

  • 当设置时，与播放器大小相关的计算将限制浏览器的 devicePixelRatio 为该指定值。

debug

（默认值：false）

设置 config.debug = true; 将在 JS 控制台上打开调试日志。

也可以提供一个自定义的日志记录器对象：config.debug = customLogger;。

autoStartLoad

（默认值：true）

  • 如果设置为 true，在触发 Hls.Events.MANIFEST_PARSED 事件后，将自动加载初始级别播放列表和第一个片段。
  • 如果设置为 false，则需要显式调用 API (hls.startLoad(startPosition=-1)) 来开始质量级别/片段的加载。

startPosition

（默认值：-1）

  • 如果设置为 -1，对于点播内容，播放将从 initialTime=0 开始；对于直播内容，将根据 liveSyncDuration/liveSyncDurationCount 配置参数开始播放。
  • 否则，播放将从预定义的值开始。（除非在 autoStartLoad=false 模式下另有说明：在这种情况下，可以使用 hls.startLoad(startPosition) 覆盖 startPosition）。

defaultAudioCodec

（默认值：undefined）

用于覆盖多变量播放列表的音频编解码器，或者在仅加载媒体播放列表时提供一个编解码器。

HLS.js 从 mp4 的 stsd 或 MPEG-TS 中的 ADTS 对象类型解析轨道编解码器。如果使用在片段中找到的值时出现错误，它将回退到多变量播放列表或 defaultAudioCodec 中找到的编解码器。

此选项不再需要，也不推荐使用。如果您发现有需要的情况，请提交一个 bug 并提供重现步骤。

initialLiveManifestSize

（默认值：1）

开始直播流播放所需的片段数量。在当前播放列表中有 N 个片段可用后，缓冲将开始。如果您希望播放从直播边缘的 liveSyncDurationCount 片段开始，请将 initialLiveManifestSize 设置为 liveSyncDurationCount 或更高。

maxBufferLength

（默认值：30 秒）

最大缓冲长度（以秒为单位）。如果缓冲长度小于此值，将加载新的片段。这是 HLS.js 将尝试达到的保证缓冲长度，无论 maxBufferSize 如何。

backBufferLength

（默认值：Infinity）

播放后保留的缓冲媒体的最大持续时间（以秒为单位）。超过此持续时间的任何视频缓冲将被清除。Infinity 表示对后缓冲长度没有限制；0 保留最小量。最小量等于片段的持续时间，以确保当前播放不会中断。请记住，浏览器可以并且会自行从缓冲区中清除媒体，因此在 Infinity 设置下，HLS.js 将让浏览器执行其需要的操作。（参考：MSE 规范中的编码帧清除）。

frontBufferFlushThreshold

（默认值：Infinity）

从播放位置开始保留的缓冲媒体的最大持续时间（以秒为单位），超过此值将清除不连续的前向范围。Infinity 表示不会主动清除；此值将始终至少为 maxBufferLength。

maxBufferSize

（默认值：60 MB）

“最小”最大缓冲区大小（以字节为单位）。如果缓冲区大小超过此值，将不会加载任何片段。

maxBufferHole

（默认值：0.1 秒）

HLS.js 在搜索下一个要加载的片段时可以容忍的最大片段间缓冲区间隙。在切换质量级别时，片段可能不会完全对齐。这可能导致媒体缓冲区中出现小的重叠或间隙。此容忍因子有助于应对这种情况。

maxStarvationDelay

（默认值：4 秒）

ABR 算法将始终尝试选择一个应避免重新缓冲的质量级别。如果找不到符合此条件的质量级别（例如，假设缓冲区长度为 1 秒，但预计以最低质量获取片段需要大约 2 秒……即我们可以预测大约 1 秒的重新缓冲……），则 ABR 算法将尝试找到一个应保证少于 maxStarvationDelay 的缓冲的质量级别。

maxLoadingDelay

（默认值：4 秒）

在自动启动级别选择中使用的最大视频加载延迟：在该模式下，ABR 控制器将确保视频加载时间（即以最低质量级别获取第一个片段的时间 + 以适当质量级别获取片段的时间）小于 maxLoadingDelay。

lowBufferWatchdogPeriod（已弃用）

lowBufferWatchdogPeriod 已被弃用。请使用 highBufferWatchdogPeriod 代替。

detectStallWithCurrentTimeMs

（默认值：1250 毫秒）

在 HLS.js 报告卡顿之前，播放可以进行的最大时间，而 currentTime 没有前进。请注意，在启动和搜索之外，当附加的 HTMLMediaElement 分派了 "waiting" 事件时，卡顿会立即被检测到。detectStallWithCurrentTimeMs 用于在未分派 "waiting" 事件且 currentTime 未能以合理间隔前进时。

highBufferWatchdogPeriod

（默认值：3 秒）

如果媒体元素预期播放，并且 currentTime 在超过 highBufferWatchdogPeriod 的时间内没有移动，并且如果前面缓冲了超过 maxBufferHole 秒的内容，HLS.js 将跳过缓冲区间隙，或尝试推动播放头以恢复播放。

nudgeOffset

（默认值：0.1 秒）

如果播放在第一次推动播放头后继续卡顿，currentTime 将按照 nudgeOffset 进一步推动，以尝试恢复播放。 media.currentTime += <推动重试次数> * nudgeOffset

nudgeMaxRetry

（默认值：3）

在 HLS.js 引发致命错误 BUFFER_STALLED_ERROR 之前，播放头（currentTime）推动的最大次数。

nudgeOnVideoHole

（默认值：true）

HLS.js 是否应在检测到视频 SourceBuffer 缓冲时间范围中的间隙或空洞时执行 seek nudge 操作以刷新渲染管道。此操作仅在检测到空洞时音频已缓冲的情况下执行。更多信息请参阅 gap-controller 中的 nudgeOnVideoHole 以及问题 https://issues.chromium.org/issues/40280613#comment10 和 https://github.com/video-dev/hls.js/issues/5631。

maxFragLookUpTolerance

（默认值：0.25 秒）

此容差因子用于片段查找期间。 不再检查 buffered.end 是否位于 [start, end] 范围内，而是通过检查 [start - maxFragLookUpTolerance, end - maxFragLookUpTolerance] 范围来完成片段查找。

此容差因子用于处理以下情况：

buffered.end = 9.991
frag[0] : [0,10]
frag[1] : [10,20]

buffered.end 位于 frag[0] 范围内，但由于我们接近 frag[1]，因此应选择 frag[1]。

如果 maxFragLookUpTolerance = 0.2，则查找将调整为：

frag[0] : [-0.2,9.8]
frag[1] : [9.8,19.8]

此时，buffered.end 位于 frag[1] 范围内，frag[1] 将按预期成为下一个加载的片段。

maxMaxBufferLength

（默认值：600 秒）

最大缓冲长度（以秒为单位）。即使尚未达到 maxBufferSize，HLS.js 也永远不会超过此值。

HLS.js 尝试缓冲到最大字节数（默认 60 MB），而不是缓冲到最大秒数。这是为了模拟浏览器的行为（当浏览器检测到视频缓冲区大小达到字节限制时，缓冲区回收算法将启动）。

maxBufferLength 是 HLS.js 尝试实现的最小保证缓冲长度，即使该值超过了 60 MB 的内存大小。 maxMaxBufferLength 作为上限值，因为如果比特率非常低，可能需要超过一小时的缓冲才能填满 60 MB。

liveSyncDurationCount

（默认值：3）

直播延迟边缘，以 EXT-X-TARGETDURATION 的倍数表示。 如果设置为 3，播放将从片段 N-3 开始，N 是直播播放列表的最后一个片段。 减少此值可能会导致播放卡顿。

liveSyncOnStallIncrease

（默认值：1）

每次播放卡顿后，hls.targetLatency 的计算增量（以秒为单位）。 当配置中指定了 liveSyncDuration 时，hls.targetLatency 计算为 liveSyncDuration 加上 liveSyncOnStallIncrease 乘以卡顿次数。 否则，hls.targetLatency 计算为 liveSyncDurationCount 乘以 EXT-X-TARGETDURATION 加上 liveSyncOnStallIncrease 乘以卡顿次数。 减少此值意味着每次卡顿对 hls.targetLatency 的影响将更小。

liveMaxLatencyDurationCount

（默认值：Infinity）

允许的最大直播延迟，以 EXT-X-TARGETDURATION 的倍数表示。 如果设置为 10，当要加载的下一个片段早于 N-10 时，播放器将回退到 liveSyncDurationCount，N 是直播播放列表的最后一个片段。 如果设置，此值必须严格大于 liveSyncDurationCount。 值过于接近 liveSyncDurationCount 可能会导致播放卡顿。

liveSyncDuration

（默认值：undefined）

liveSyncDurationCount 的替代参数，以秒为单位而不是片段数量。 如果在配置对象中定义了此参数，liveSyncDuration 将优先于默认的 liveSyncDurationCount。 你不能在配置对象中同时定义此参数和 liveSyncDurationCount 或 liveMaxLatencyDurationCount。 值过低（低于约 3 个片段时长）可能会导致播放卡顿。

liveMaxLatencyDuration

（默认值：undefined）

liveMaxLatencyDurationCount 的替代参数，以秒为单位而不是片段数量。 如果在配置对象中定义了此参数，liveMaxLatencyDuration 将优先于默认的 liveMaxLatencyDurationCount。 如果设置，此值必须严格大于 liveSyncDuration，且 liveSyncDuration 也必须定义。 你不能在配置对象中同时定义此参数和 liveSyncDurationCount 或 liveMaxLatencyDurationCount。 值过于接近 liveSyncDuration 可能会导致播放卡顿。

maxLiveSyncPlaybackRate

（默认值：1，最小值：1，最大值：2）

当设置为大于 1 的值时，latency-controller 将调整 video.playbackRate，最高可达 maxLiveSyncPlaybackRate，以追赶直播流的目标延迟。hls.targetLatency 基于 liveSyncDuration|Count 或清单中的 PART-|HOLD-BACK。

默认值为 1，禁用播放速率调整。将 maxLiveSyncPlaybackRate 设置为大于 1 的值以启用直播边缘的播放速率调整。

liveDurationInfinity

（默认值：false）

将当前媒体源时长覆盖为 Infinity，用于直播广播。 如果你正在构建一个依赖于现代浏览器原生 UI 功能的播放器，此功能非常有用。 如果你想在 iOS Safari、Safari、Android Google Chrome 等环境中拥有原生直播 UI，请将此值设置为 true。

liveBackBufferLength（已弃用）

liveBackBufferLength 已被弃用。请改用 backBufferLength。

preferManagedMediaSource

（默认值：true）

HLS.js 默认使用 Managed Media Source API（ManagedMediaSource 全局对象）而不是 MediaSource 全局对象（如果存在）。将此设置为 false 将仅在 MediaSource 未定义时使用 ManagedMediaSource。

enableWorker

（默认值：true）

启用 WebWorker（如果浏览器支持）以进行 TS 解复用/MP4 重封装，以提高性能并避免延迟/掉帧。

workerPath

（默认值：null）

提供 hls.worker.js 的路径，作为基于 IIFE 库包装函数注入 worker 的替代方案。当 workerPath 定义为字符串时，transmuxer 接口将使用解析后的 workerPath URL 初始化 WebWorker。

使用库的 ESM 版本（hls.mjs）时，此选项是使用 WebWorker 的必需条件。

enableSoftwareAES

（默认值：true）

启用 JavaScript 版本的 AES 解密，作为 WebCrypto API 的备用方案。

startLevel

（默认值：undefined）

设置时，使用此级别作为默认的 hls.startLevel。请注意，通过 API 设置的 startLevel 优先于 config.startLevel 配置参数。startLevel 应设置为 0 到 hls.levels 最大索引之间的值。

fragLoadingTimeOut / manifestLoadingTimeOut / levelLoadingTimeOut（已弃用）

（默认值：片段为 20000ms，级别和清单为 10000ms）

x-LoadingTimeOut 设置已被弃用。请改用 LoadPolicy 设置。

fragLoadingMaxRetry / manifestLoadingMaxRetry / levelLoadingMaxRetry（已弃用）

（默认值：6 / 1 / 4）

x-LoadingMaxRetry 设置已被弃用。请改用 LoadPolicy 设置。

fragLoadingMaxRetryTimeout / manifestLoadingMaxRetryTimeout / levelLoadingMaxRetryTimeout（已弃用）

（默认值：64000 ms）

x-LoadingMaxRetryTimeout 设置已被弃用。请改用 LoadPolicy 设置。

最大片段/清单/密钥重试超时（以毫秒为单位）。 此值用作 loading retry delays 指数增长的上限值，即重试延迟不能大于此值，但总时间将基于总重试次数。

fragLoadingRetryDelay / manifestLoadingRetryDelay / levelLoadingRetryDelay（已弃用）

（默认值：1000 ms）

x-LoadingRetryDelay 设置已被弃用。请改用 LoadPolicy 设置。

XMLHttpRequest 错误与第一次重试加载之间的初始延迟（以毫秒为单位）。 任何 I/O 错误将触发重试，间隔为 500ms、1s、2s、4s、8s，...，上限为 fragLoadingMaxRetryTimeout / manifestLoadingMaxRetryTimeout / levelLoadingMaxRetryTimeout 值（指数退避）。

fragLoadPolicy / keyLoadPolicy / certLoadPolicy / playlistLoadPolicy / manifestLoadPolicy / steeringManifestLoadPolicy / interstitialAssetListLoadPolicy

LoadPolicies 指定了特定类型资源的请求超时以及请求错误或超时后的重试次数和时间的默认设置。

  • manifestLoadPolicy：多变量播放清单请求的 LoadPolicy
  • playlistLoadPolicy：媒体播放清单请求的 LoadPolicy
  • fragLoadPolicy：片段和部分请求的 LoadPolicy
  • keyLoadPolicy：密钥请求的 LoadPolicy
  • certLoadPolicy：许可证服务器证书请求的 LoadPolicy
  • steeringManifestLoadPolicy：内容引导清单请求的 LoadPolicy
  • interstitialAssetListLoadPolicy：插播资源列表请求的 LoadPolicy

*某些超时设置会根据部分时长或目标为低延迟部分请求进行调整。

每个 LoadPolicy 包含一组上下文。目前仅支持 default 属性。它包含该资源类型的 LoaderConfig。未来版本可能支持除 default 之外的其他策略上下文。

HLS.js 配置定义了以下默认策略。每个策略都可以在播放器实例化时通过用户配置覆盖：

manifestLoadPolicy: {
  default: {
    maxTimeToFirstByteMs: Infinity,
    maxLoadTimeMs: 20000,
    timeoutRetry: {
      maxNumRetry: 2,
      retryDelayMs: 0,
      maxRetryDelayMs: 0,
    },
    errorRetry: {
      maxNumRetry: 1,
      retryDelayMs: 1000,
      maxRetryDelayMs: 8000,
    },
  },
},
playlistLoadPolicy: {
  default: {
    maxTimeToFirstByteMs: 10000,
    maxLoadTimeMs: 20000,
    timeoutRetry: {
      maxNumRetry: 2,
      retryDelayMs: 0,
      maxRetryDelayMs: 0,
    },
    errorRetry: {
      maxNumRetry: 2,
      retryDelayMs: 1000,
      maxRetryDelayMs: 8000,
    },
  },
},
fragLoadPolicy: {
  default: {
    maxTimeToFirstByteMs: 10000,
    maxLoadTimeMs: 120000,
    timeoutRetry: {
      maxNumRetry: 4,
      retryDelayMs: 0,
      maxRetryDelayMs: 0,
    },
    errorRetry: {
      maxNumRetry: 6,
      retryDelayMs: 1000,
      maxRetryDelayMs: 8000,
    },
  },
},
keyLoadPolicy: {
  default: {
    maxTimeToFirstByteMs: 8000,
    maxLoadTimeMs: 20000,
    timeoutRetry: {
      maxNumRetry: 1,
      retryDelayMs: 1000,
      maxRetryDelayMs: 20000,
      backoff: 'linear',
    },
    errorRetry: {
      maxNumRetry: 8,
      retryDelayMs: 1000,
      maxRetryDelayMs: 20000,
      backoff: 'linear',
    },
  },
},
certLoadPolicy: {
  default: {
    maxTimeToFirstByteMs: 8000,
    maxLoadTimeMs: 20000,
    timeoutRetry: null,
    errorRetry: null,
  },
},
steeringManifestLoadPolicy: {
  default: {
    maxTimeToFirstByteMs: 10000,
    maxLoadTimeMs: 20000,
    timeoutRetry: {
      maxNumRetry: 2,
      retryDelayMs: 0,
      maxRetryDelayMs: 0,
    },
    errorRetry: {
      maxNumRetry: 1,
      retryDelayMs: 1000,
      maxRetryDelayMs: 8000,
    },
  },
},
interstitialAssetListLoadPolicy: {
  default: {
    maxTimeToFirstByteMs: 10000,
    maxLoadTimeMs: 20000,
    timeoutRetry: {
      maxNumRetry: 0,
      retryDelayMs: 0,
      maxRetryDelayMs: 0,
    },
    errorRetry: {
      maxNumRetry: 0,
      retryDelayMs: 1000,
      maxRetryDelayMs: 8000,
    },
  },
}

LoaderConfig

每个 LoaderConfig 具有以下属性：

maxTimeToFirstByteMs: number

最大首次字节时间（以毫秒为单位）。如果在此时间内没有字节或 readyState 变化，将触发资源的网络超时错误。

非有限值和 0 将被忽略，导致仅对整个请求使用单个 maxLoadTimeMs 超时计时器。

maxLoadTimeMs: number

加载资源的最大时间（以毫秒为单位）。如果请求未在时间内完成，将触发资源的网络超时错误。

timeoutRetry: RetryConfig | null

超时错误的重试规则。指定 null 表示在超时错误后不重试该资源类型。

errorRetry: RetryConfig | null

网络 I/O 错误的重试规则。指定 null 表示在超时错误后不重试该资源类型。

RetryConfig

每个 RetryConfig 具有以下属性：

maxNumRetry: number

最大重试次数。发生错误后，请求将重试此次数，然后采取其他恢复措施。例如，在重试片段或播放清单请求此次数后*，如果仍然出错，播放器将尝试切换到其他级别或回退到其他路径以恢复播放。

当没有有效的恢复选项时，错误将升级为致命错误，播放器将停止加载所有媒体和资源类型。

*导致卡顿的请求可能会在所有重试完成之前触发级别切换。

retryDelayMs: number

重试前的等待时间（以毫秒为单位）。添加延迟是为了防止播放器对响应请求有困难的服务器造成过载。

重试延迟 = 2^retryCount _ retryDelayMs（指数）或 retryCount _ retryDelayMs（线性）

maxRetryDelayMs: number

重试之间的最大延迟（以毫秒为单位）。每次重试时，延迟将增加到 maxRetryDelayMs。

backoff?: 'exponential' | 'linear'

用于确定重试退避时长：重试延迟 = 2^retryCount * retryDelayMs（指数）。

shouldRetry

（默认值：内部 shouldRetry 函数，类型：(retryConfig: RetryConfig | null | undefined, retryCount: number, isTimeout: boolean, httpStatus: number | undefined,retry: boolean) => boolean）

覆盖默认的 shouldRetry 检查。

startFragPrefetch

（默认值：false）

在媒体尚未附加时开始预加载起始片段。

testBandwidth

（默认值：true）

你必须同时设置 startLevel = -1 才能使此选项生效。否则，HLS.js 将加载清单中的第一个级别并从那里开始播放。如果设置 startLevel = -1，将下载最低级别的片段以建立带宽估计，然后选择第一个自动级别。 如果你希望提供自己的估计或使用默认的 abrEwmaDefaultEstimate，请禁用此测试。

progressive

（默认值：false）

启用使用 fetch loader 进行流式分段数据传输（实验性功能）。

lowLatencyMode

（默认值：true）

启用低延迟 HLS 部分播放列表和分段加载，并在播放列表的 PART-HOLD-BACK 处开始直播流，而不是 HOLD-BACK。

fpsDroppedMonitoringPeriod

（默认值：5000）

默认的 fpsController 用于观察 fpsDroppedMonitoringThreshold 的时间周期。

fpsDroppedMonitoringThreshold

（默认值：0.2）

在 fpsDroppedMonitoringPeriod 内，丢帧数与总帧数的比率，达到此比率时，默认的 fpsController 会触发 FPS_DROP 事件。

appendErrorMaxRetry

（默认值：3）

在出错时，sourceBuffer.appendBuffer() 的最大重试次数。在播放 UHD 流时，当内部缓冲区已满时，可能会发生此类错误（会触发“配额超出”错误）。在这种情况下，我们需要等待浏览器清除一些数据后才能正确追加缓冲区。

loader

（默认值：基于标准 XMLHttpRequest 的 URL 加载器）

使用自定义加载器覆盖标准 URL 加载器。可以使用 Hls.DefaultConfig.loader 导出的内部实现进行组合和包装。对于 P2P 或测试（stubbing）可能很有用。

如果你想同时覆盖片段和播放列表加载器，请使用此选项。

注意：如果使用了 fLoader 或 pLoader，它们会覆盖 loader！

var customLoader = function () {
  /**
     * 调用 load() 将开始检索位于给定 URL 的内容（HTTP GET）。
     *
     * @param {object} context - 加载器上下文
     * @param {string} context.url - 目标 URL
     * @param {string} context.responseType - 加载器响应类型（arraybuffer 或播放列表的默认响应类型）
     * @param {number} [context.rangeStart] - 开始字节范围偏移量
     * @param {number} [context.rangeEnd] - 结束字节范围偏移量
     * @param {Boolean} [context.progressData] - 如果 onProgress 应报告加载内容的部分块，则为 true
     * @param {object} config - 加载器配置参数
     * @param {number} config.maxRetry - 最大重试次数
     * @param {number} config.timeout - 超时时间，超过此时间后将触发 `onTimeOut` 回调（如果加载仍未完成）
     * @param {number} config.retryDelay - I/O 错误后与下一次连接重试之间的延迟（毫秒）。这是为了避免向服务器发送过多请求
     * @param {number} config.maxRetryDelay - 最大连接重试延迟（毫秒）
     * @param {object} callbacks - 加载器回调
     * @param {onSuccessCallback} callbacks.onSuccess - 成功加载 URL 时触发的回调。
     * @param {onProgressCallback} callbacks.onProgress - 加载过程中触发的回调。
     * @param {onErrorCallback} callbacks.onError - 加载片段时遇到任何 I/O 错误时触发的回调。
     * @param {onTimeoutCallback} callbacks.onTimeout - 加载在特定时间后仍未完成时触发的回调。

      @callback onSuccessCallback
      @param response {object} - 响应数据
      @param response.url {string} - 响应 URL（可能已被重定向）
      @param response.data {string/arraybuffer/sharedarraybuffer} - 响应数据（响应类型应与 context.responseType 一致）
      @param stats {LoadStats} - 加载统计信息
      @param stats.aborted {boolean} - 一旦请求被中止，必须设置为 true
      @param stats.loaded {number} - 已加载的字节数
      @param stats.total {number} - 总字节数
      @param stats.retry {number} - 执行的重试次数
      @param stats.chunkCount {number} - 块进度事件的数量
      @param stats.bwEstimate {number} - 下载带宽（比特/秒）
      @param stats.loading { start: 0, first: 0, end: 0 }
      @param stats.parsing { start: 0, end: 0 }
      @param stats.buffering { start: 0, first: 0, end: 0 }
      @param context {object} - 加载器上下文
      @param networkDetails {object} - 加载器网络详细信息（默认加载器的 xhr）

      @callback onProgressCallback
      @param stats {LoadStats} - 加载统计信息
      @param context {object} - 加载器上下文
      @param data {string/arraybuffer/sharedarraybuffer} - onProgress 数据（仅在 context.progressData === true 时定义）
      @param networkDetails {object} - 加载器网络详细信息（默认加载器的 xhr）

      @callback onErrorCallback
      @param error {object} - 错误数据
      @param error.code {number} - 错误状态码
      @param error.text {string} - 错误描述
      @param context {object} - 加载器上下文
      @param networkDetails {object} - 加载器网络详细信息（默认加载器的 xhr）

      @callback onTimeoutCallback
      @param stats {LoadStats} - 加载统计信息
      @param context {object} - 加载器上下文

   */
  this.load = function (context, config, callbacks) {};

  /** 中止任何正在进行的加载。 */
  this.abort = function () {};

  /** 销毁加载上下文。 */
  this.destroy = function () {};
};

fLoader

（默认值：undefined）

此选项允许操作片段加载器。 注意：这将覆盖默认的 loader，以及你自定义的加载器函数（见上文）。

var customFragmentLoader = function () {
  // 参见 `loader` 的详细信息。
};

pLoader

（默认值：undefined）

此选项允许操作播放列表加载器。 注意：这将覆盖默认的 loader，以及你自定义的加载器函数（见上文）。

var customPlaylistLoader = function () {
  // 参见 `loader` 的详细信息。
};

如果你只想对现有加载器实现进行轻微调整，也可以覆盖它，参见以下示例：

// 特殊的播放列表后处理函数
function process(playlist) {
  return playlist;
}

class pLoader extends Hls.DefaultConfig.loader {
  constructor(config) {
    super(config);
    var load = this.load.bind(this);
    this.load = function (context, config, callbacks) {
      if (context.type == 'manifest') {
        var onSuccess = callbacks.onSuccess;
        callbacks.onSuccess = function (response, stats, context) {
          response.data = process(response.data);
          onSuccess(response, stats, context);
        };
      }
      load(context, config, callbacks);
    };
  }
}

var hls = new Hls({
  pLoader: pLoader,
});

xhrSetup

（默认值：undefined）

用于默认基于 XHR 的加载器的 XMLHttpRequest 自定义回调。

xhrSetup 应该是一个带有两个参数 (xhr: XMLHttpRequest, url: string) 的函数。如果指定了 xhrSetup，默认加载器将在调用 xhr.send() 之前调用它。这允许用户在发送请求之前轻松修改 XMLHttpRequest 实例。可以选择返回一个 Promise 以在发送请求之前等待。

注意：如果回调以需要先打开 XMLHttpRequest 的方式修改 XMLHttpRequest 实例，则应在 xhrSetup 中调用 xhr.open()。如果 xhrSetup 抛出错误，错误将被捕获，并在打开 GET 请求后第二次调用 xhrSetup。

var config = {
  xhrSetup: function (xhr, url) {
    xhr.withCredentials = true; // 发送 cookies
  },
};

fetchSetup

（默认值：undefined）

用于基于 Fetch 的加载器的 Fetch 自定义回调。

参数应该是一个带有两个参数（context 和 Request Init Params）的函数。如果指定了 fetchSetup 并且使用了 Fetch 加载器，fetchSetup 将被触发以实例化 Request 对象。这允许用户轻松调整 Fetch 加载器。参见以下示例。

var config = {
  fetchSetup: function (context, initParams) {
    // 始终发送 cookies，即使是跨域调用。
    initParams.credentials = 'include';
    return new Request(context.url, initParams);
  },
};

videoPreference

（默认值：undefined）

这些设置决定是否应在 SDR 视频之前选择 HDR 视频。还可以指定允许的 VIDEO-RANGE 值及其优先级顺序。

格式为 { preferHDR: boolean, allowedVideoRanges: ('SDR' | 'PQ' | 'HLG')[], videoCodec: string }

  • 如果未指定 allowedVideoRanges，则允许所有视频范围。
  • 如果定义了 preferHDR，则使用该值过滤 allowedVideoRanges。
  • 否则，检查窗口是否支持 HDR 并将 preferHDR 设置为结果。

当设置了 preferHDR 时，跳过检查窗口是否支持 HDR，而是使用提供的值通过动态范围确定级别选择偏好。preferHDR === true 的值将尝试在使用 SDR 级别之前使用 HDR 级别。

allowedVideoRanges 可以将播放限制为有限的 VIDEO-RANGE 传输函数集，并设置其选择优先级。例如，要忽略所有 HDR 变体，请将 allowedVideoRanges 设置为 ['SDR']。或者，要忽略所有 HLG 变体，请将 allowedVideoRanges 设置为 ['SDR', 'PQ']。要优先选择 PQ 变体而不是 HLG，请将 allowedVideoRanges 设置为 ['SDR', 'HLG', 'PQ']。

videoCodec 将初始选择限制为特定编解码器，前提是找到基线变体（allowedVideoRanges 中的 1080p 30fps 或更低）。

audioPreference

（默认值：undefined）

设置用于在启动时查找和选择最佳匹配音频轨道的偏好。该选择可以基于可用的音频组来影响起始级别的选择。audioPreference 接受音频轨道对象（MediaPlaylist）、AudioSelectionOption（要匹配的轨道字段）或 undefined 的值。如果未设置或设置为 undefined，HLS.js 将在启动时自动选择默认轨道。

subtitlePreference

（默认值：undefined）

设置用于在启动时查找和选择最佳匹配字幕轨道的偏好。subtitlePreference 接受字幕轨道对象（MediaPlaylist）、SubtitleSelectionOption（要匹配的轨道字段）或 undefined 的值。如果未设置或设置为 undefined，HLS.js 将不会启用字幕，除非有默认或强制选项。

abrController

（默认值：内部 ABR 控制器）

自定义的自适应比特率流控制器。

参数应该是一个提供 getter/setter 和 destroy() 方法的类：

  • get/set nextAutoLevel：返回下一个自动质量级别/强制返回下一个自动质量级别（当前用于紧急切换）
  • destroy()：应清理所有使用的资源

为了使 hls.bandwidthEstimate() 从你的自定义控制器返回估计值，它还需要满足 abrController.bwEstimator.getEstimate()。

bufferController

（默认值：内部缓冲区控制器）

自定义的缓冲区控制器。

负责管理 SourceBuffers 的类。

capLevelController

（默认值：内部级别限制控制器）

自定义的级别限制控制器。

负责根据播放器大小设置 hls.autoLevelCapping 以限制 ABR 级别选择的类。通过将 capLevelToPlayerSize 设置为 true 来启用默认的级别限制控制器。

fpsController

（默认值：内部 fps 控制器）

自定义的 fps 控制器。

负责监控帧速率并在丢帧超过配置阈值时触发 FPS_DROP 事件的类。通过将 capLevelOnFPSDrop 设置为 true 来启用默认的 fps 控制器。

timelineController

（默认值：内部轨道时间线控制器）

自定义的文本轨道同步控制器。

参数应该是一个带有 destroy() 方法的类：

  • destroy()：应清理所有使用的资源

enableDateRangeMetadataCues

（默认值：true）

是否为 EXT-X-DATERANGE 播放列表标签添加、更新和删除元数据 TextTrack 中的 cues。

参数应为布尔值。

enableEmsgMetadataCues

（默认值：true）

是否为 CMAF 事件消息（emsg）框中的 ID3 定时元数据添加、更新和删除元数据 TextTrack 中的 cues。

参数应为布尔值。

enableEmsgKLVMetadata

（默认值：false）

是否提取 CMAF 事件消息（emsg）框中的 KLV 定时元数据并通过 FRAG_PARSING_METADATA 传递。

参数应为布尔值。

enableID3MetadataCues

（默认值：true）

是否为音频和 MPEG-TS 容器中的 ID3 定时元数据添加、更新和删除元数据 TextTrack 中的 cues。

参数应为布尔值。

enableWebVTT

（默认值：true）

是否在 HLS 上启用 WebVTT 字幕。

参数应为布尔值。

enableIMSC1

（默认值：true）

是否在 HLS 上启用 IMSC1 字幕。

参数应为布尔值。

enableCEA708Captions

（默认值：true）

是否启用 CEA-708 字幕。

参数应为布尔值。

captionsTextTrack1Label

（默认值：English）

为 CEA-708 字幕轨道 1 生成的文本轨道的标签。这将显示在浏览器的原生字幕和字幕菜单中。

参数应为字符串。

captionsTextTrack1LanguageCode

（默认值：en）

为 CEA-708 字幕轨道 1 生成的文本轨道的 RFC 3066 语言代码。

参数应为字符串。

captionsTextTrack2Label

（默认值：Spanish）

为 CEA-708 字幕轨道 2 生成的文本轨道的标签。这将显示在浏览器的原生字幕和字幕菜单中。

参数应为字符串。

captionsTextTrack2LanguageCode

（默认值：es）

为 CEA-708 字幕轨道 2 生成的文本轨道的 RFC 3066 语言代码。

参数应为字符串。

captionsTextTrack3Label

（默认值：Unknown CC）

为 CEA-708 字幕轨道 3 生成的文本轨道的标签。这将显示在浏览器的原生字幕和字幕菜单中。

参数应为字符串。

captionsTextTrack3LanguageCode

（默认值：``）

为 CEA-708 字幕轨道 3 生成的文本轨道的 RFC 3066 语言代码。

参数应为字符串。

captionsTextTrack4Label

（默认值：Unknown CC）

为 CEA-708 字幕轨道 4 生成的文本轨道的标签。这将显示在浏览器的原生字幕和字幕菜单中。

参数应为字符串。

captionsTextTrack4LanguageCode

（默认值：``）

为 CEA-708 字幕轨道 4 生成的文本轨道的 RFC 3066 语言代码。

参数应为字符串。

renderTextTracksNatively

（默认值：true）

是否使用 HTMLMediaElement 的 TextTracks 原生渲染字幕。当你想要使用 Hls.Events.NON_NATIVE_TEXT_TRACKS_FOUND 和 Hls.Events.CUES_PARSED 事件处理轨道和轨道 cues 的渲染时，禁用原生字幕渲染。

参数应为布尔值。

stretchShortVideoTrack

（默认值：false）

如果某个片段的视频轨道比音频轨道短，且差值大于 maxBufferHole，则延长最后一帧视频的持续时间以匹配音频轨道的持续时间。 这有助于在某些情况下继续播放，否则可能会卡住。

参数应为布尔值

maxAudioFramesDrift

（默认值：1）

浏览器对音频帧的时间非常严格。 它们通常一个接一个地播放音频帧，而不管 fmp4 中广告的时间戳。 如果音频时间戳不一致（连续的音频帧相距太近或太远），音频很容易漂移。 HLS.js 会重新标记音频帧，使连续音频帧之间的距离保持恒定。 如果距离大于允许的最大漂移，HLS.js 将：

  1. 如果距离太小，则丢弃下一个音频帧（如果下一个音频帧的时间戳小于预期时间戳 - 最大允许漂移）
  2. （仅限 AAC）如果距离太大，则插入静音帧（下一个音频帧的时间戳大于预期时间戳 + 最大允许漂移）

参数应为表示允许漂移的最大音频帧数的整数。 请记住，一个音频帧是 1024 个音频样本（如果使用 AAC），在 44.1 kHz 下，1024/44100 = 23ms

forceKeyFrameOnDiscontinuity

（默认值：true）

是否在间断后的第一个 AVC 样本中强制插入关键帧。 如果设置为 true，则在间断后，将丢弃没有任何关键帧的 AVC 样本，直到找到包含关键帧的样本。 如果设置为 false，则保留所有 AVC 样本，这有助于避免流中的空洞。 将此参数设置为 false 在切换级别或跳转时也可能导致解码异常。

参数应为布尔值

abrEwmaFastLive

（默认值：3.0）

快速比特率指数移动平均半衰期，用于计算直播流的平均比特率。 估计值的一半基于过去 abrEwmaFastLive 秒的样本历史。 每个样本的权重由片段加载持续时间决定。

参数应为大于 0 的浮点数

abrEwmaSlowLive

（默认值：9.0）

慢速比特率指数移动平均半衰期，用于计算直播流的平均比特率。 估计值的一半基于过去 abrEwmaSlowLive 秒的样本历史。 每个样本的权重由片段加载持续时间决定。

参数应为大于 abrEwmaFastLive 的浮点数

abrEwmaFastVoD

（默认值：3.0）

快速比特率指数移动平均半衰期，用于计算点播流的平均比特率。 估计值的一半基于过去 abrEwmaFastVoD 秒的样本历史。 每个样本的权重由片段加载持续时间决定。

参数应为大于 0 的浮点数

abrEwmaSlowVoD

（默认值：9.0）

慢速比特率指数移动平均半衰期，用于计算点播流的平均比特率。 估计值的一半基于过去 abrEwmaSlowVoD 秒的样本历史。 每个样本的权重由片段加载持续时间决定。

参数应为大于 abrEwmaFastVoD 的浮点数

abrEwmaDefaultEstimate

（默认值：500000）

在收集片段带宽样本之前，默认的带宽估计值（以比特/秒为单位）。

abrEwmaDefaultEstimateMax

（默认值：5000000）

限制从多变量播放列表中找到的第一个变体的更新带宽估计值的最大值。

abrBandWidthFactor

（默认值：0.95）

应用于测量带宽平均值的比例因子，用于确定是否可以保持在当前或更低的质量级别。 如果 abrBandWidthFactor * 带宽平均值 > 级别.比特率，则 ABR 可以切换到该级别，前提是该级别等于或小于当前级别。

abrBandWidthUpFactor

（默认值：0.7）

应用于测量带宽平均值的比例因子，用于确定是否可以切换到更高的质量级别。 如果 abrBandWidthUpFactor * 带宽平均值 > 级别.比特率，则 ABR 可以切换到该质量级别。

abrMaxWithRealBitrate

（默认值：false）

ABR 中使用的最大比特率基于平均测量比特率 即，如果变体清单中某个级别的比特率为 2Mb/s，但该级别的平均测量比特率为 2.5Mb/s， 则如果配置值设置为 true，ABR 将使用 2.5 Mb/s 作为该质量级别。

minAutoBitrate

（默认值：0）

返回自动级别选择算法可能使用的上限/最小带宽值。 当浏览器或浏览器标签不在焦点且带宽下降时非常有用

emeEnabled

（默认值：false）

设置为 true 以启用 DRM 密钥系统访问和许可证检索。

widevineLicenseUrl（已弃用）

（默认值：undefined）

widevineLicenseUrl 已被弃用。请使用 drmSystems['com.widevine.alpha'].licenseUrl 代替。

licenseXhrSetup

（默认值：undefined，类型 (xhr: XMLHttpRequest, url: string, keyContext: MediaKeySessionContext, licenseChallenge: Uint8Array) => void | Uint8Array | Promise<Uint8Array | void>）

用于修改许可证请求的预处理函数。可以根据操作条件、当前密钥会话和密钥系统，在发送许可证请求之前修改许可证请求的 URL、请求头和有效载荷。

var config = {
  licenseXhrSetup: function (xhr, url, keyContext, licenseChallenge) {
    let payload = licenseChallenge;

    // 发送带有请求的 cookie
    xhr.withCredentials = true;

    // 调用 open 以更改方法（默认是 POST）、修改 URL 或设置请求头
    xhr.open('POST', url, true);

    // 在 xhr.open 之后调用 xhr.setRequestHeader，否则 licenseXhrSetup 将抛出异常并在 HLS.js 调用 xhr.open 后第二次调用
    if (keyContext.keySystem === 'com.apple.fps') {
      xhr.setRequestHeader('Content-Type', 'application/json');
      payload = JSON.stringify({
        keyData: base64Encode(keyContext.decryptdata?.keyId),
        licenseChallenge: base64Encode(licenseChallenge),
      });
    } else {
      xhr.setRequestHeader('Content-Type', 'application/octet-stream');
    }

    // 返回所需的 payload 或 Promise<Uint8Array>。
    // 不返回值或返回 `undefined` 或 `Promise<void>` 将导致使用 `licenseChallenge`。
    return fetchDRMToken(this.authData).then((result) => {
      xhr.setRequestHeader('token', token);
      return payload;
    });
  },
};

licenseResponseCallback

（默认值：undefined，类型 (xhr: XMLHttpRequest, url: string, keyContext: MediaKeySessionContext) => data: ArrayBuffer）

用于在将许可证响应传递给密钥会话（MediaKeySession.update）之前对其进行修改的后处理函数。

var config = {
  licenseResponseCallback: function (xhr, url, keyContext) {
      const keySystem = keyContext.keySystem;
      const response = xhr.response;
      if (keyContext.keySystem === 'com.apple.fps') {
        try {
          const responseObject = JSON.parse(
            new TextDecoder().decode(response).trim();
          );
          const keyResponse = responseObject['fairplay-streaming-response']['streaming-keys'][0];
          return base64Decode(keyResponse.ckc);
        } catch (error) {
          console.error(error);
        }
      }
      return response;
  }

drmSystems

（默认值：{}）

根据您的 DRM 提供商定义给定密钥系统的许可证设置。例如：

drmSystems: {
  'com.apple.fps': {
    licenseUrl: 'https://your-fps-license-server/path',
    serverCertificateUrl: 'https://your-fps-license-server/certificate/path',
  },
  'com.widevine.alpha': {
    licenseUrl: 'https://your-widevine-license-server/path'
  }
}

支持的密钥系统包括 'com.apple.fps'、'com.microsoft.playready'、'com.widevine.alpha' 和 'org.w3.clearkey'。通过自定义 requestMediaKeySystemAccessFunc 可以映射到密钥系统访问请求中的其他值。

当加载带有 DRM 密钥的内容时，播放器只会请求访问 drmSystems 中定义的密钥系统的会话密钥或播放列表密钥。

`drmSystems[KEY-SYSTEM].generateRequest

（默认值：undefined，类型 (initDataType: string, initData: ArrayBuffer | null, keyContext: MediaKeySessionContext) => { initDataType: string; initData: ArrayBuffer | null } | undefined）

用于在调用 MediaKeySession generateRequest 之前映射或生成播放列表密钥的 initData。

drmSystemOptions

（默认值：{}）

定义可选的 MediaKeySystemConfiguration 参数，这些参数将传递给 requestMediaKeySystemAccess。例如：

{
  audioRobustness: 'SW_SECURE_CRYPTO',
  videoRobustness: 'SW_SECURE_CRYPTO',
  audioEncryptionScheme: null,
  videoEncryptionScheme: null,
  persistentState: 'not-allowed';
  distinctiveIdentifier: 'not-allowed';
  sessionTypes: ['temporary'];
  sessionType: 'temporary';
}

使用默认参数时，每个选项将指定为 ''（即不需要特定的鲁棒性）。

requestMediaKeySystemAccessFunc

（默认值：返回 window.navigator.requestMediaKeySystemAccess.bind(window.navigator) 或 null 的函数）

允许自定义 window.navigator.requestMediaKeySystemAccess。这可以用于将密钥系统访问请求从支持的值映射到自定义值：

var hls new Hls({
  requestMediaKeySystemAccessFunc: (keySystem, supportedConfigurations) => {
    if (keySystem === 'com.microsoft.playready') {
      keySystem = 'com.microsoft.playready.recommendation';
    }
    return navigator.requestMediaKeySystemAccess(keySystem, supportedConfigurations);
  }
});

cmcd

当定义了 cmcd 对象时，Common Media Client Data (CMCD) 数据将传递到所有媒体请求（清单、播放列表、音视频片段、定时文本）。其配置值为：

  • sessionId：CMCD 会话 ID。如果未提供，则会自动生成一个。
  • contentId：CMCD 内容 ID。
  • useHeaders：在请求头中发送 CMCD 数据，而不是作为查询参数。默认为 false。
  • includeKeys：可选的 CMCD 键数组。当存在时，只有这些 CMCD 字段将包含在每个请求中。

enableInterstitialPlayback

（默认值：true）

可以通过将此设置为 false 来禁用插播播放，而无需禁用解析或计划更新和缓冲到事件，从而允许自定义播放和广告管理器使用插播数据。

interstitialAppendInPlace

（默认值：true）

使用此选项可以通过将其设置为 false 来关闭插播的“就地”追加。

“就地”追加是在单个时间线上执行的，使用与主媒体相同的 SourceBuffers 和 MediaSource。默认值为 true，允许 HLS.js 根据每个插播事件的计划开始和恢复时间以及其与主播放列表媒体的对齐方式来决定使用哪种模式。

即使为 true，HLS.js 也可能根据需要重置 MediaSource 和时间线以进行插播播放。InterstitialEvent 实例的 appendInPlace 属性指示用于追加插播资源的模式。一旦插播的第一个 INTERSTITIAL_ASSET_PLAYER_CREATED 事件触发，appendInPlace 的值将保持不变。

interstitialLiveLookAhead

(默认值: 10)

在播放直播边缘时，提前请求预定的插播广告的时间（以秒为单位）。

默认值为 10，意味着 HLS.js 将开始请求插播广告的 ASSET-LIST 和 ASSET-URI，其 START-DATE 在主变体播放列表结束时的 program-date-time 的 10 秒内，同时前向缓冲区在同一范围内的目标持续时间之内。

视频绑定/解绑 API

hls.attachMedia(HTMLMediaElement | MediaAttachingData)

调用此方法将：

  • 绑定 videoElement 和 hls 实例，
  • 创建 MediaSource 并将其设置为视频源
  • 一旦 MediaSource 对象成功创建，将触发 MEDIA_ATTACHED 事件。

hls.detachMedia()

调用此方法将：

  • 从 hls 实例中解绑 VideoElement，
  • 在 MediaSource 上发出流结束信号
  • 重置视频源 (video.src = '')

hls.transferMedia(): MediaAttachingData

以非破坏性的方式解绑并返回 MediaSource 和 SourceBuffers，格式可以传递给 hls.attachMedia(MediaAttachingData)。这用于附加与主播放器相同的 SourceBuffer 的插播广告播放器。

hls.media

  • get: 从 hls 实例返回绑定的 videoElement

质量切换控制 API

默认情况下，hls.js 会自动处理质量切换，使用基于片段加载比特率和变体清单中公开的质量级别带宽的启发式方法。 也可以使用以下 API 手动控制质量切换。

hls.levels

  • get: 返回可用质量级别的数组。

hls.currentLevel

  • get: 返回当前播放质量级别。
  • set: 立即触发质量级别切换到新质量级别。这将中止当前片段请求（如果有），刷新整个缓冲区，并获取与当前位置和请求的质量级别匹配的片段。

设置为 -1 以进行自动级别选择。

hls.nextLevel

  • get: 返回下一个播放质量级别（下一个缓冲片段的质量级别）。如果下一个片段尚未缓冲，则返回 -1。
  • set: 触发下一个片段的质量级别切换。这可能会刷新已经缓冲的下一个片段。

设置为 -1 以进行自动级别选择。

hls.loadLevel

  • get: 返回最后加载的片段质量级别。
  • set: 设置下一个加载片段的质量级别。

设置为 -1 以进行自动级别选择。

hls.nextLoadLevel

  • get: 返回将用于加载下一个片段的质量级别。
  • set: 强制下一个加载片段的质量级别。质量级别仅对该片段强制生效。 在该质量级别的片段加载后，hls.loadLevel 将生效。

hls.firstLevel

  • get: 第一个级别索引（多变量播放列表中第一个变体的索引）。

hls.firstAutoLevel

  • get: 返回未由 startLevel 覆盖时将用于加载第一个片段的质量级别。

hls.startLevel

  • get/set: 开始级别索引（将播放的第一个片段的级别）。
    • 如果未被用户覆盖：将使用清单中出现的第一个级别作为开始级别。
    • 如果为 -1：自动开始级别选择，播放将从与下载带宽匹配的级别开始（由第一个片段的下载确定）。

默认值为 hls.firstLevel。

hls.autoLevelEnabled

  • get: 告知是否启用了自动级别选择。

hls.autoLevelCapping

  • get/set: ABR 控制器可以使用的上限/最大级别值。

默认值为 -1（无级别上限）。

hls.maxHdcpLevel

  • get/set: 自动级别选择允许选择的最大 HDCP-LEVEL。必须是有效的 HDCP-LEVEL 值（'NONE', 'TYPE-0', 'TYPE-1', 'TYPE-2'），或 null（默认值）。当发生 KEY_SYSTEM_STATUS_OUTPUT_RESTRICTED 错误时，hls.maxHdcpLevel 会自动设置为下一个最低值。要防止手动选择具有特定 HDCP-LEVEL 属性值的级别，请在 MANIFEST_LOADED 或错误时使用 hls.removeLevel()。

默认值为 null（无基于 HDCP-LEVEL 的级别上限）

hls.capLevelToPlayerSize

  • get: 启用或禁用级别上限。如果在之前启用后禁用，将立即调用 nextLevelSwitch。
  • set: 是否启用级别上限。

默认值通过配置中的 capLevelToPlayerSize 设置。

hls.bandwidthEstimate

get: 返回当前带宽估计值（以比特/秒为单位），如果可用。否则，返回 NaN。

set: 使用设置的值作为新的默认估计值重置 EwmaBandWidthEstimator。这将更新 config.abrEwmaDefaultEstimate 的值。

hls.removeLevel(levelIndex)

从加载的级别列表中删除一个级别。 这可以用于从用户或 HLS.js 可以选择的级别列表中删除经常出错的再现或播放列表 URL。

以这种方式修改级别将触发 Hls.Events.LEVELS_UPDATED 事件。

版本控制

Hls.version

静态 getter: 返回 hls.js@version 字符串（dist 构建版本或 src VERSION 构建常量）。

网络加载控制 API

默认情况下，HLS.js 会在触发 Hls.Events.MANIFEST_PARSED 事件后自动开始加载质量级别播放列表和片段。

但是，如果 config.autoStartLoad 设置为 false，则需要调用 hls.startLoad() 来手动开始播放列表和片段的加载。

hls.startLoad(startPosition=-1,skipSeekToStartPosition=false)

开始/重新开始播放列表/片段加载。这仅在触发 MANIFEST_PARSED 事件后有效。

startPosition 是播放列表中的初始位置。 如果 startPosition 未设置为 -1，它允许覆盖默认的 startPosition 为您想要的位置（例如，它将绕过 hls.config.liveSync* 配置参数，以便用户可以从任何位置开始播放）。

一旦媒体被附加，HLS.js 将寻找到开始位置。传入 skipSeekToStartPosition 为 true 允许在附加时从开始位置开始加载而不进行寻道。这用于当多个播放器为重叠主内容的插播广告缓冲媒体到同一源时。

hls.stopLoad()

停止播放列表/片段加载。稍后可以通过调用 hls.startLoad() 恢复。

hls.startPosition

get : 返回在媒体缓冲之前用于加载的已解析的 startPosition 目标（数字），并且一旦媒体被缓冲，播放将从该位置开始。

hls.pauseBuffering()

暂停片段缓冲（与 ManagedMediaSource 流事件内部使用）。

hls.resumeBuffering()

恢复片段缓冲（与 ManagedMediaSource 流事件内部使用）。

hls.bufferingEnabled

get : 返回一个布尔值，指示是否已通过 pauseBuffering() 和 resumeBuffering() 切换片段加载。

hls.bufferedToEnd

get : 返回一个布尔值，指示是否已附加 EOS（媒体从 currentTime 到流结束已缓冲）。

hls.inFlightFragments

get: 返回一个对象，包含每个流控制器的状态和正在加载的片段（或 null）。

示例：

{
  main: {
    frag: <Fragment Object>,
    state: "FRAG_LOADING"
  },
  audio: {
    frag: <Fragment Object>,
    state: "PARSED"
  },
  subtitle: {
    frag: null,
    state: "IDLE"
  }
}

hls.url

get : 传递给 hls.loadSource() 的当前 HLS 资产的字符串，否则为 null

音轨控制 API

hls.setAudioOption(audioOption)

查找并选择最佳匹配的音轨，必要时进行级别切换。更新 hls.config.audioPreference。返回选定的音轨，如果未找到匹配的音轨，则返回 null。

hls.allAudioTracks

get : 多变量播放列表中找到的所有支持音轨的数组

hls.audioTracks

get : 活动音轨组 ID 中支持音轨的数组

hls.audioTrack

get/set : hls.audioTracks 中选定音轨的索引

字幕轨控制 API

hls.setSubtitleOption(subtitleOption)

查找并选择最佳匹配的字幕轨，必要时进行级别切换。更新 hls.config.subtitlePreference。返回选定的字幕轨，如果未找到匹配的字幕轨，则返回 null。

hls.allSubtitleTracks

get : 多变量播放列表中找到的所有字幕轨的数组

hls.subtitleTracks

get : 活动字幕组 ID 中字幕轨的数组

hls.subtitleTrack

get/set : hls.subtitleTracks 中选定字幕轨的索引。如果没有字幕轨可见，则返回 -1。设置为 -1 以禁用所有字幕轨。

hls.subtitleDisplay

(默认值: true)

get/set : 如果设置为 true，活动字幕轨模式将设置为 showing，浏览器将显示活动字幕。如果设置为 false，模式将设置为 hidden。

直播流 API

hls.liveSyncPosition

get : 直播同步点的位置（即直播边缘位置减去由 hls.config.liveSyncDuration 定义的安全延迟）。 如果播放在滑动窗口外卡顿，或延迟超过 liveMaxLatencyDuration，HLS.js 将向前寻找到 liveSyncPosition 以重新与流同步。

hls.latency

get : 直播边缘的估计位置（以秒为单位）（即直播播放列表边缘加上时间同步播放列表提前） 在加载第一个播放列表之前返回 0

hls.maxLatency

get : 在播放器向前寻找到 hls.liveSyncPosition 之前与边缘的最大距离 使用 liveMaxLatencyDurationCount（目标持续时间的倍数）或 liveMaxLatencyDuration 配置 在加载第一个播放列表之前返回 0

hls.targetLatency

get/set : 由延迟控制器计算出的与边缘的目标距离

当在配置中指定了 liveSyncDuration 时， targetLatency 计算为 liveSyncDuration 加上 liveSyncOnStallIncrease 乘以卡顿次数。 否则 targetLatency 计算为 liveSyncDurationCount 乘以 EXT-X-TARGETDURATION 加上 liveSyncOnStallIncrease 乘以卡顿次数。

设置 targetLatency 将卡顿次数重置为 0 并将 liveSyncDuration 设置为新值。 注意：如果初始配置指定了 liveSyncDurationCount 而不是 liveSyncDuration， 设置 targetLatency 将为 liveSyncDuration 分配一个新值。该值将用于从现在开始计算 targetLatency，并且 liveSyncDurationCount 将被忽略。

hls.drift

get : 当前直播播放列表边缘前进的速率，如果没有则为 1

hls.playingDate

get: 活动级别的 Program Date Time 相对于 media.currentTime 的日期时间值（如果存在）

插播广告

HLS.js 支持播放带有 Interstitial EXT-X-DATERANGE 标签的 X-ASSET-URI 和 X-ASSET-LIST m3u8 播放列表。InterstitialsManager 提供播放状态以及寻道和跳过控制。有各种事件可以通知应用程序插播广告计划的变化和播放状态。以下是它们的工作原理概述。

插播广告配置选项

插播广告管理器

hls.interstitialsManager

  • get: 返回 InterstitialsManager（或 null），其中包含有关当前节目的信息。

数据包括插播广告事件的列表及其资产列表、事件和主要片段项目的计划、哪些项目和资产正在缓冲和播放的信息、当前缓冲媒体的播放器实例以及负责资产流的播放器队列。

使用 skip() 跳过当前插播广告。使用 primary、playout 和 integrated 获取 currentTime、duration 并在相应的时间线上寻道。

interface InterstitialsManager {
  events: InterstitialEvent[]; // 从最新媒体播放列表更新中解析出的插播广告（事件）数组
  schedule: InterstitialScheduleItem[]; // 代表计划节目的主要和事件项目的数组，具有开始和结束时间
  playerQueue: HlsAssetPlayer[]; // 用于预加载和流式传输插播广告资产内容的子 Hls 实例数组
  bufferingPlayer: HlsAssetPlayer | null; // 分配给流式传输前向缓冲区边缘媒体的子 Hls 实例
  bufferingAsset: InterstitialAssetItem | null; // 当前正在流式传输的插播广告资产
  bufferingItem: InterstitialScheduleItem | null; // 当前正在流式传输的主要项目或事件项目
  bufferingIndex: number; // `bufferingItem` 在 `schedule` 数组中的索引
  playingAsset: InterstitialAssetItem | null; // 当前正在流式传输的插播广告资产
  playingItem: InterstitialScheduleItem | null; // 当前正在播放的主要项目或事件项目
  playingIndex: number; // `playingItem` 在 `schedule` 数组中的索引
  waitingIndex: number; // 其资产列表正在加载的项目在 `schedule` 数组中的索引
  primary: PlayheadTimes; // 基于主要内容的播放头映射和 seekTo 方法
  playout: PlayheadTimes; // 基于 `schedule` 数组中所有项目的播放的播放头映射和 seekTo 方法
  integrated: PlayheadTimes; // 将 X-TIMELINE-OCCUPIES 属性应用于每个事件项目的播放头映射和 seekTo 方法
  skip: () => void; // 用于跳过当前正在播放的事件项目的方法，前提是它不受跳跃限制
}

type PlayheadTimes = {
  bufferedEnd: number; // 相对于计划节目中播放头的缓冲区结束时间
  currentTime: number; // 计划节目中的当前播放头时间
  duration: number; // 计划节目结束的时间
  seekableStart: number; // 媒体可用的最早时间（映射到主要媒体播放列表中第一个片段的开始）
  seekTo: (time: number) => void; // 用于寻道到计划节目中指定时间的方法
};

插播事件

INTERSTITIALS_UPDATED 在解析带有插播 EXT-X-DATERANGE 标签的播放列表以及插播资源持续时间或调度发生任何更改后触发。它包括插播事件列表、预定的播放片段、任何选定时间线的调度持续时间，以及自上次更新以来删除的插播 EXT-X-DATERANGE（仅限直播）。

interface InterstitialsUpdatedData {
  events: InterstitialEvent[];
  schedule: InterstitialScheduleItem[];
  durations: InterstitialScheduleDurations;
  removedIds: string[];
}

当缓冲区达到事件的预定日期时，插播内容将被加载。这将通过 INTERSTITIALS_BUFFERED_TO_BOUNDARY 信号通知。

interface InterstitialsBufferedToBoundaryData {
  events: InterstitialEvent[];
  schedule: InterstitialScheduleItem[];
  bufferingIndex: number;
  playingIndex: number;
}

如果插播 EXT-X-DATERANGE 包含 X-ASSET-LIST，ASSET_LIST_LOADING 和 ASSET_LIST_LOADED 将触发（或非致命的 ERROR，带有 ErrorDetails.ASSET_LIST_(LOAD_(ERROR|TIMEOUT)|PARSING_ERROR)）。

一旦资源列表/URI 已知，将创建播放器实例以预加载由 INTERSTITIAL_ASSET_PLAYER_CREATED 信号通知的资源。此时，资源播放器已配置并请求 HLS 播放列表。HLS.js 将在轮到它缓冲或播放媒体时将媒体元素转移给此播放器，除非此时附加了另一个播放器。

interface InterstitialAssetPlayerCreatedData {
  asset: InterstitialAssetItem;
  assetListIndex: number;
  assetListResponse?: AssetListJSON;
  event: InterstitialEvent;
  player: HlsAssetPlayer;
}

InterstitialEvent: appendInPlace 属性指示用于附加插播资源的模式。

HLS.js 确定插播是否将在单个时间线上“就地”附加，使用与主播放器相同的 SourceBuffers 和 MediaSource，或者是否为每个资源重置 MediaSource 和持续时间。将额外的媒体元素附加到资源播放器会导致它们在播放前重置。当媒体元素共享时（默认情况下），模式根据每个插播事件的预定开始和恢复时间以及它与主播放列表媒体的对齐方式确定。

INTERSTITIAL_STARTED 和 INTERSTITIAL_ENDED 标记进入和退出预定的插播事件项。每当播放或跳转到插播 DATERANGE 或从中退出时，这些事件都会触发。

INTERSTITIAL_ASSET_STARTED 和 INTERSTITIAL_ASSET_ENDED 标记插播中资源的进入和退出。

interface InterstitialAssetStartedData {
  asset: InterstitialAssetItem;
  assetListIndex: number;
  event: InterstitialEvent;
  schedule: InterstitialScheduleItem[];
  scheduleIndex: number;
  player: HlsAssetPlayer;
}

interface InterstitialAssetEndedData {
  asset: InterstitialAssetItem;
  assetListIndex: number;
  event: InterstitialEvent;
  schedule: InterstitialScheduleItem[];
  scheduleIndex: number;
  player: HlsAssetPlayer;
}

在资源处于活动状态时，应在资源播放器上执行自适应控制和流状态。使用 hls.interstitialsManager 进行集成的播放状态、跳转和跳过插播。

INTERSTITIALS_PRIMARY_RESUMED 在播放从插播或播放开始时进入主调度项时触发。

INTERSTITIAL_ASSET_ERROR 在错误导致资源无法播放或提前结束时触发。预计播放将回退到主内容。这应伴随着调度更新以及 InterstitialAssetItem 和 InterstitialEvent 上的 error 属性（当所有资源都失败时）。

type InterstitialAssetErrorData = {
  asset: InterstitialAssetItem | null;
  assetListIndex: number;
  event: InterstitialEvent | null;
  schedule: InterstitialScheduleItem[] | null;
  scheduleIndex: number;
  player: HlsAssetPlayer | null;
} & ErrorData;

插播对象和类

  • InterstitialEvent 表示解析后的插播事件的类。
  • InterstitialScheduleItem 节目调度中的一个项或片段。可以是 InterstitialScheduleEventItem 或 InterstitialSchedulePrimaryItem。
  • InterstitialAssetItem 在 InterstitialEvent 的 assetList 中解析和调度的资源。
  • HlsAssetPlayer 用于包装用于流式传输插播资源的 Hls 实例的类。

附加数据

hls.latestLevelDetails

  • get: 返回最后加载的级别（变体）的 LevelDetails，或在加载媒体播放列表之前返回 null。

hjs.loadLevelObj

  • get: 返回所选级别（变体）的 Level 对象，或在选择级别之前或级别被移除后返回 null。

hls.sessionId

get: 返回分配给 Hls 实例的会话 UUID。用作默认的 CMCD 会话 ID。

运行时事件

hls.js 触发了一系列事件，可以按如下方式注册和注销：

function onLevelLoaded(event, data) {
  var level_duration = data.details.totalduration;
}
// 订阅事件
hls.on(Hls.Events.LEVEL_LOADED, onLevelLoaded);
// 取消订阅事件
hls.off(Hls.Events.LEVEL_LOADED, onLevelLoaded);
// 仅订阅一次事件
hls.once(Hls.Events.LEVEL_LOADED, onLevelLoaded);

完整的事件列表如下：

  • Hls.Events.MEDIA_ATTACHING - 在 MediaSource 附加到媒体元素之前触发
    • 数据: { media }
  • Hls.Events.MEDIA_ATTACHED - 在 MediaSource 成功附加到媒体元素时触发
    • 数据: { media }
  • Hls.Events.MEDIA_DETACHING - 在从媒体元素分离 MediaSource 之前触发
    • 数据: { }
  • Hls.Events.MEDIA_DETACHED - 在 MediaSource 从媒体元素分离时触发
    • 数据: { }
  • Hls.Events.BUFFER_RESET - 在缓冲区即将重置时触发
    • 数据: { }
  • Hls.Events.BUFFER_CODECS - 在我们知道需要缓冲区以推送的编解码器时触发
    • 数据: { audio? : [Track], video? : [Track] }
  • Hls.Events.BUFFER_CREATED - 在创建 sourcebuffers 时触发
    • 数据: { tracks : { audio? : [Track], video? : [Track], audiovideo?: [Track] } } interface Track { id: 'audio' | 'main', buffer?: SourceBuffer, container: string, codec?: string, initSegment?: Uint8Array, levelCodec?: string, metadata?: any }
  • Hls.Events.BUFFER_APPENDING - 在将片段附加到缓冲区时触发
  • 数据: { parent, type, frag, part, chunkMeta, data }
  • Hls.Events.BUFFER_APPENDED - 在将媒体片段附加到缓冲区完成后触发
    • 数据: { parent : 触发 BUFFER_APPENDING 的播放列表类型, type, frag, part, chunkMeta, timeRanges : { video?: TimeRange, audio?: TimeRange, audiovideo?: TimeRange } }
  • Hls.Events.BUFFER_EOS - 在流结束时触发，我们希望通知媒体缓冲区将不再有数据
    • 数据: { type: SourceBufferName }
  • Hls.Events.BUFFER_FLUSHING - 在应刷新媒体缓冲区时触发
    • 数据: { startOffset, endOffset, type: SourceBufferName }
  • Hls.Events.BUFFER_FLUSHED - 在媒体缓冲区已刷新时触发
    • 数据: { type: SourceBufferName }
  • Hls.Events.BACK_BUFFER_REACHED - 在达到由 backBufferLength 配置选项定义的后缓冲区时触发
    • 数据: { bufferEnd: number }
  • Hls.Events.MANIFEST_LOADING - 在开始加载清单时触发
    • 数据: { url : 清单URL }
  • Hls.Events.MANIFEST_LOADED - 在清单加载完成后触发
    • 数据: { levels : [可用质量级别], audioTracks : [可用音轨], captions? [可用隐藏字幕媒体], subtitles?: [可用字幕轨道], url : 清单URL, stats : [LoaderStats], sessionData: [解析的 #EXT-X-SESSION-DATA], networkDetails: [用于调试的 Loader 特定对象（XMLHttpRequest 或 fetch Response）]}
  • Hls.Events.MANIFEST_PARSED - 在清单解析完成后触发
    • 数据: { levels : [ 可用质量级别 ], firstLevel : 清单中出现的第一个质量级别的索引, audioTracks, subtitleTracks, stats, audio: boolean, video: boolean, altAudio: boolean }
  • Hls.Events.STEERING_MANIFEST_LOADED - 在内容转向清单加载完成后触发
    • 数据: { url: 转向清单 URL, steeringManifest: SteeringManifest 对象 } }
  • Hls.Events.LEVEL_SWITCHING - 在请求切换级别时触发
    • 数据: { level 和 Level 对象属性（请参阅 下面 了解更多信息） }
  • Hls.Events.LEVEL_SWITCHED - 在级别切换生效时触发
    • 数据: { level : 新级别的 id }
  • Hls.Events.LEVEL_LOADING - 在请求级别播放列表时触发（除非它是通过 hls.loadSource() 加载的唯一媒体播放列表）
    • 数据: { url : 级别 URL, level : 正在加载的级别的 id, deliveryDirectives: LL-HLS 交付指令或 null（当不支持阻塞重新加载时） }
  • Hls.Events.LEVEL_LOADED - 在级别播放列表加载完成时触发
    • 数据: { details : LevelDetails, level : 加载的级别的 id, stats : [LoadStats] }
  • Hls.Events.LEVEL_UPDATED - 在级别的详细信息基于先前的详细信息更新后触发，加载完成后
    • 数据: { details : LevelDetails, level : 更新的级别的 id }
  • Hls.Events.LEVEL_PTS_UPDATED - 在解析片段后级别的 PTS 信息更新时触发
    • 数据: { details : LevelDetails, level : 更新的级别的 id, drift: 解析最后一个片段时观察到的 PTS 漂移, type, start, end }
  • Hls.Events.LEVELS_UPDATED - 在调用 removeLevel() 后删除级别时触发
    • 数据: { levels : [ 可用质量级别 ] }
  • Hls.Events.AUDIO_TRACKS_UPDATED - 在音轨列表更新时触发
    • 数据: { audioTracks : 音轨 }
  • Hls.Events.AUDIO_TRACK_SWITCHING - 在请求切换音轨时触发
    • 数据: { id : 音轨 id, type : 播放列表类型 ('AUDIO' | 'main'), url : 音轨 URL }
  • Hls.Events.AUDIO_TRACK_SWITCHED - 在音轨切换实际发生时触发
    • 数据: { id : 音轨 id }
  • Hls.Events.AUDIO_TRACK_LOADING - 在开始加载音轨时触发
    • 数据: { url : 音轨 URL, id : 音轨 id }
  • Hls.Events.AUDIO_TRACK_LOADED - 在音轨加载完成时触发
    • 数据: { details : LevelDetails, id : 音轨 id, stats : [LoadStats] }
  • Hls.Events.SUBTITLE_TRACKS_UPDATED - 在字幕轨道列表更新时触发
    • 数据: { subtitleTracks : 字幕轨道 }
  • Hls.Events.SUBTITLE_TRACK_SWITCH - 在字幕轨道切换发生时触发
    • 数据: { id : 字幕轨道 id, type? : 播放列表类型 ('SUBTITLES' | 'CLOSED-CAPTIONS'), url? : 字幕轨道 URL }
  • Hls.Events.SUBTITLE_TRACK_LOADING - 在开始加载字幕轨道时触发
    • 数据: { url : 音轨 URL, id : 音轨 id }
  • Hls.Events.SUBTITLE_TRACK_LOADED - 在字幕轨道加载完成时触发
    • 数据: { details : LevelDetails, id : 字幕轨道 id, stats : [LoadStats] }
  • Hls.Events.SUBTITLE_FRAG_PROCESSED - 在字幕片段处理完成时触发
    • 数据: { success : boolean, frag : [处理的片段对象], error?: [解析字幕时的错误（如果有）] }
  • Hls.Events.INIT_PTS_FOUND - 在找到第一个时间戳时触发
    • 数据: { d : 解复用器 id, initPTS: initPTS, timescale: timescale, frag : 片段对象 }
  • Hls.Events.FRAG_LOADING - 在开始加载片段时触发
    • 数据: { frag : 片段对象, targetBufferTime: number | null [我们期望用此片段缓冲的未缓冲时间] }
  • Hls.Events.FRAG_LOAD_PROGRESS - [已弃用]
  • Hls.Events.FRAG_LOAD_EMERGENCY_ABORTED - 标识因紧急切换而中止片段加载
    • 数据: { frag : 片段对象 }
  • Hls.Events.FRAG_LOADED - 在片段加载完成时触发
    • 数据: { frag : 片段对象, payload : 片段有效负载, stats : [LoadStats]}
  • Hls.Events.FRAG_DECRYPTED - 在片段解密完成时触发
    • 数据: { id : 解复用器 id, frag : 片段对象, payload : 片段有效负载, stats : { tstart, tdecrypt}}
  • Hls.Events.FRAG_PARSING_INIT_SEGMENT - 在从片段中提取 Init Segment 时触发
    • 数据: { id: 解复用器 id, frag : 片段对象, moov : moov MP4 盒子, codecs : 解析片段时找到的编解码器 }
  • Hls.Events.FRAG_PARSING_USERDATA - 在解析 sei 文本完成时触发
    • 数据: { id : 解复用器 id, frag: 片段对象, samples : [ sei 样本 pes ], details: LevelDetails }
  • Hls.Events.FRAG_PARSING_METADATA - 在解析元数据完成时触发（ID3 / CMAF KLV）
    • 数据: { id: 解复用器 id, frag : 片段对象, samples : [ type 字段与 Hls.MetadataSchema 枚举中的值对齐。pes - pts 和 dts 时间戳是相对的，值以秒为单位], details: LevelDetails }
  • Hls.Events.FRAG_PARSING_DATA - [已弃用]
  • Hls.Events.FRAG_PARSED - 在片段解析完成时触发
    • 数据: { frag : 片段对象, partIndex }
  • Hls.Events.FRAG_BUFFERED - 在片段重混 MP4 盒子全部附加到 SourceBuffer 时触发
    • 数据: { id: 解复用器 id, frag : 片段对象, stats : [LoadStats] }
  • Hls.Events.FRAG_CHANGED - 在与当前视频位置匹配的片段发生变化时触发
    • 数据: { id : 解复用器 id, frag : 片段对象 }
  • Hls.Events.FPS_DROP - 在上一个监控周期内 FPS 下降超过给定阈值时触发
    • 数据: { curentDropped : 上一个监控周期内丢帧数, currentDecoded : 上一个监控周期内解码帧数, totalDroppedFrames : 此视频元素上的总丢帧数 }
  • Hls.Events.FPS_DROP_LEVEL_CAPPING - 在 FPS 下降触发自动级别限制时触发
    • 数据: { level: fps 控制器建议的新自动级别限制, droppedLevel : 丢帧过多的级别将被限制 }
  • Hls.Events.ERROR - 错误事件的标识符
    • 数据: { type : 错误类型, details : 错误详细信息, fatal : 错误是否致命, 其他错误特定数据 }
  • Hls.Events.DESTROYING - 在 hls.js 实例开始销毁时触发。与 MEDIA_DETACHED 不同，因为可能希望分离并重新附加视频到 hls.js 实例以处理中插广告等
    • 数据: { }
  • Hls.Events.KEY_LOADING - 在开始加载解密密钥时触发
    • 数据: { frag : 片段对象 }
  • Hls.Events.KEY_LOADED - 在解密密钥加载完成时触发
    • 数据: { frag : 片段对象 }
  • Hls.Events.STREAM_STATE_TRANSITION - [已弃用]
  • Hls.Events.NON_NATIVE_TEXT_TRACKS_FOUND - 当 renderTextTracksNatively 为 false 时，当发现新的字幕或字幕轨道时，此事件将触发，代替将 TextTrack 添加到视频元素。
    • 数据: { tracks: Array<{ label, kind, default, subtitleTrack }> }
  • Hls.Events.CUES_PARSED - 当 renderTextTracksNatively 为 false 时，当解析新的字幕或字幕提示时，此事件将触发。
    • 数据: { type, cues, track } }

创建自定义加载器

你可以通过静态属性 Hls.DefaultConfig.loader 使用内部加载器定义来实现自己的加载器。

示例：

let myHls = new Hls({
  pLoader: function (config) {
    let loader = new Hls.DefaultConfig.loader(config);

    Object.defineProperties(this, {
      stats: {
        get: () => loader.stats,
      },
      context: {
        get: () => loader.context,
      },
    });

    this.abort = () => loader.abort();
    this.destroy = () => loader.destroy();
    this.load = (context, config, callbacks) => {
      let { type, url } = context;

      if (type === 'manifest') {
        console.log(`Manifest ${url} will be loaded.`);
      }

      loader.load(context, config, callbacks);
    };
  },
});

或者，支持 ES6 类的环境可以直接扩展加载器：

import Hls from 'hls.js';

let myHls = new Hls({
  pLoader: class CustomLoader extends Hls.DefaultConfig.loader {
    load(context, config, callbacks) {
      let { type, url } = context;

      // 自定义行为

      super.load(context, config, callbacks);
    }
  },
});

错误

完整的错误列表如下：

网络错误

  • Hls.ErrorDetails.MANIFEST_LOAD_ERROR - 当清单加载因网络错误失败时触发
    • 数据: { type : NETWORK_ERROR, details : Hls.ErrorDetails.MANIFEST_LOAD_ERROR, fatal : true, url : 清单 URL, response : { code: 错误代码, text: 错误信息 }, loader : URL 加载器 }
  • Hls.ErrorDetails.MANIFEST_LOAD_TIMEOUT - 当清单加载因超时失败时触发
    • 数据: { type : NETWORK_ERROR, details : Hls.ErrorDetails.MANIFEST_LOAD_TIMEOUT, fatal : true, url : 清单 URL, loader : URL 加载器 }
  • Hls.ErrorDetails.MANIFEST_PARSING_ERROR - 当清单解析未能找到合适内容时触发
    • 数据: { type : NETWORK_ERROR, details : Hls.ErrorDetails.MANIFEST_PARSING_ERROR, fatal : true, url : 清单 URL, reason : 解析错误原因 }
  • Hls.ErrorDetails.LEVEL_EMPTY_ERROR - 当加载的级别不包含任何片段时触发（适用于级别、音频和字幕轨道）
    • 数据: { type : NETWORK_ERROR, details : Hls.ErrorDetails.LEVEL_EMPTY_ERROR, url: 播放列表 URL, reason: 错误原因, level: 错误级别的索引或未定义, parent: PlaylistLevelType }
  • Hls.ErrorDetails.LEVEL_LOAD_ERROR - 当级别加载因网络错误失败时触发
    • 数据: { type : NETWORK_ERROR, details : Hls.ErrorDetails.LEVEL_LOAD_ERROR, fatal : true, url : 级别 URL, response : { code: 错误代码, text: 错误信息 }, loader : URL 加载器 }
  • Hls.ErrorDetails.LEVEL_LOAD_TIMEOUT - 当级别加载因超时失败时触发
    • 数据: { type : NETWORK_ERROR, details : Hls.ErrorDetails.LEVEL_LOAD_TIMEOUT, fatal : false, url : 级别 URL, loader : URL 加载器 }
  • Hls.ErrorDetails.LEVEL_PARSING_ERROR - 当播放列表解析失败或发现无效内容时触发（适用于级别、音频和字幕轨道）
    • 数据: { type : NETWORK_ERROR, details : Hls.ErrorDetails.LEVEL_PARSING_ERROR, fatal : false, url : 级别 URL, error: 错误, parent: PlaylistLevelType }
  • Hls.ErrorDetails.AUDIO_TRACK_LOAD_ERROR - 当音频播放列表加载因网络错误失败时触发
    • 数据: { type : NETWORK_ERROR, details : Hls.ErrorDetails.AUDIO_TRACK_LOAD_ERROR, fatal : false, url : 音频 URL, response : { code: 错误代码, text: 错误信息 }, loader : URL 加载器 }
  • Hls.ErrorDetails.AUDIO_TRACK_LOAD_TIMEOUT - 当音频播放列表加载因超时失败时触发
    • 数据: { type : NETWORK_ERROR, details : Hls.ErrorDetails.AUDIO_TRACK_LOAD_TIMEOUT, fatal : false, url : 音频 URL, loader : URL 加载器 }
  • Hls.ErrorDetails.SUBTITLE_LOAD_ERROR - 当字幕播放列表加载因网络错误失败时触发
    • 数据: { type : NETWORK_ERROR, details : Hls.ErrorDetails.SUBTITLE_LOAD_ERROR, fatal : false, url, response : { code: 错误代码, text: 错误信息 }, loader : URL 加载器 }
  • Hls.ErrorDetails.SUBTITLE_TRACK_LOAD_TIMEOUT - 当字幕播放列表加载因超时失败时触发
    • 数据: { type : NETWORK_ERROR, details : Hls.ErrorDetails.SUBTITLE_TRACK_LOAD_TIMEOUT, fatal : false, url, loader : URL 加载器 }
  • Hls.ErrorDetails.FRAG_LOAD_ERROR - 当片段加载因网络错误失败时触发
    • 数据: { type : NETWORK_ERROR, details : Hls.ErrorDetails.FRAG_LOAD_ERROR, fatal : true 或 false, frag : 片段对象, response : { code: 错误代码, text: 错误信息 } }
  • Hls.ErrorDetails.FRAG_LOAD_TIMEOUT - 当片段加载因超时失败时触发
    • 数据: { type : NETWORK_ERROR, details : Hls.ErrorDetails.FRAG_LOAD_TIMEOUT, fatal : true 或 false, frag : 片段对象 }
  • Hls.ErrorDetails.KEY_LOAD_ERROR - 当解密密钥加载因网络错误失败时触发
    • 数据: { type : NETWORK_ERROR, details : Hls.ErrorDetails.KEY_LOAD_ERROR, fatal : false, frag : 片段对象, response : { code: 错误代码, text: 错误信息 } }
  • Hls.ErrorDetails.KEY_LOAD_TIMEOUT - 当解密密钥加载因超时失败时触发
    • 数据: { type : NETWORK_ERROR, details : Hls.ErrorDetails.KEY_LOAD_TIMEOUT, fatal : true, frag : 片段对象 }

媒体错误

  • Hls.ErrorDetails.MANIFEST_INCOMPATIBLE_CODECS_ERROR - 当清单仅包含与 MediaSource Engine 不兼容的编解码器的质量级别时触发
    • 数据: { type : MEDIA_ERROR, details : Hls.ErrorDetails.MANIFEST_INCOMPATIBLE_CODECS_ERROR, fatal : true, url : 清单 URL }
  • Hls.ErrorDetails.FRAG_DECRYPT_ERROR - 当片段解密失败时触发
    • 数据: { type : MEDIA_ERROR, details : Hls.ErrorDetails.FRAG_DECRYPT_ERROR, fatal : true, reason : 失败原因 }
  • Hls.ErrorDetails.FRAG_PARSING_ERROR - 当片段解析失败时触发
    • 数据: { type : MEDIA_ERROR, details : Hls.ErrorDetails.FRAG_PARSING_ERROR, fatal : true 或 false, reason : 失败原因 }
  • Hls.ErrorDetails.FRAG_GAP - 当遇到带有 GAP 标签或带有 GAP=YES 属性的片段时，跳过片段加载时触发
    • 数据: { type : MEDIA_ERROR, details : Hls.ErrorDetails.FRAG_GAP, fatal : false, frag : 片段对象, part? : 部分对象（如果有） }
  • Hls.ErrorDetails.BUFFER_ADD_CODEC_ERROR - 当 MediaSource 无法添加新的 sourceBuffer 时触发
    • 数据: { type : MEDIA_ERROR, details : Hls.ErrorDetails.BUFFER_ADD_CODEC_ERROR, fatal : false, error : MediaSource 引发的错误, mimeType: 发生失败的 mimeType }
  • Hls.ErrorDetails.BUFFER_INCOMPATIBLE_CODECS_ERROR - 当无法根据轨道编解码器创建 MediaSource 时触发
    • 数据: { type : MEDIA_ERROR, details : Hls.ErrorDetails.BUFFER_INCOMPATIBLE_CODECS_ERROR, fatal : true, reason : 失败原因 }
  • Hls.ErrorDetails.BUFFER_APPEND_ERROR - 当调用 buffer append 时引发异常时触发
    • 数据: { type : MEDIA_ERROR, details : Hls.ErrorDetails.BUFFER_APPEND_ERROR, fatal : true 或 false, parent : 父流控制器 }
  • Hls.ErrorDetails.BUFFER_APPENDING_ERROR - 当在 buffer appending 过程中引发异常时触发
    • 数据: { type : MEDIA_ERROR, details : Hls.ErrorDetails.BUFFER_APPENDING_ERROR, fatal : false }
  • Hls.ErrorDetails.BUFFER_STALLED_ERROR - 当播放因缓冲区数据不足而卡住时触发
    • 数据: { type : MEDIA_ERROR, details : Hls.ErrorDetails.BUFFER_STALLED_ERROR, fatal : true 或 false, buffer : 缓冲区长度（可选） }
  • Hls.ErrorDetails.BUFFER_FULL_ERROR - 当媒体缓冲区已满，无法再追加数据时触发。此错误通过减少最大缓冲区长度来恢复。
    • 数据: { type : MEDIA_ERROR, details : Hls.ErrorDetails.BUFFER_FULL_ERROR, fatal : false }
  • Hls.ErrorDetails.BUFFER_SEEK_OVER_HOLE - 当 hls.js 跳过缓冲区空洞以解除播放卡住时触发，
    • 数据: { type : MEDIA_ERROR, details : Hls.ErrorDetails.BUFFER_SEEK_OVER_HOLE, fatal : false, hole : 空洞持续时间 }
  • Hls.ErrorDetails.BUFFER_NUDGE_ON_STALL - 当播放卡住时触发，尽管 currentTime 在缓冲区内
    • 数据: { type : MEDIA_ERROR, details : Hls.ErrorDetails.BUFFER_NUDGE_ON_STALL, fatal : true|false }
    • 前几次 nudge 不致命，但如果达到 config.nudgeMaxRetry 尝试次数且播放器仍然卡住，则 BUFFER_NUDGE_ON_STALL 致命

Mux 错误

  • Hls.ErrorDetails.REMUX_ALLOC_ERROR - 当在 remuxing 过程中内存分配失败时触发
    • 数据: { type : MUX_ERROR, details : Hls.ErrorDetails.REMUX_ALLOC_ERROR, fatal : false, bytes : mdat 大小, reason : 失败原因 }

EME 密钥系统错误

  • Hls.ErrorDetails.KEY_SYSTEM_NO_KEYS - EME 通用错误
    • 数据: { type : KEY_SYSTEM_ERROR, details : Hls.ErrorDetails.KEY_SYSTEM_NO_KEYS, fatal : true, error: 错误 }
  • Hls.ErrorDetails.KEY_SYSTEM_NO_ACCESS - EME MediaKeyFunc requestMediaKeySystemAccess(keySystem, supportedConfigurations) 无法访问密钥系统
    • 数据: { type : KEY_SYSTEM_ERROR, details : Hls.ErrorDetails.KEY_SYSTEM_NO_ACCESS, fatal : true, error: 错误 }
  • Hls.ErrorDetails.KEY_SYSTEM_NO_SESSION - MediaKeySession generateRequest(initDataType, initData) 失败
    • 数据: { type : KEY_SYSTEM_ERROR, details : Hls.ErrorDetails.KEY_SYSTEM_NO_SESSION, fatal : false, error: 错误 }
  • Hls.ErrorDetails.KEY_SYSTEM_NO_CONFIGURED_LICENSE - 播放器配置缺少 drmSystems 密钥系统许可证选项
    • 数据: { type : KEY_SYSTEM_ERROR, details : Hls.ErrorDetails.KEY_SYSTEM_NO_CONFIGURED_LICENSE, fatal : false }
  • Hls.ErrorDetails.KEY_SYSTEM_LICENSE_REQUEST_FAILED - 密钥系统许可证请求失败（第一次状态 4xx 失败，或 3 次尝试后失败（EMEController MAX_LICENSE_REQUEST_FAILURES））
    • 数据: { type : KEY_SYSTEM_ERROR, details : Hls.ErrorDetails.KEY_SYSTEM_LICENSE_REQUEST_FAILED, fatal : true, networkDetails: XMLHttpRequest }
  • Hls.ErrorDetails.KEY_SYSTEM_SERVER_CERTIFICATE_REQUEST_FAILED - 密钥系统证书请求失败
    • 数据: { type : KEY_SYSTEM_ERROR, details : Hls.ErrorDetails.KEY_SYSTEM_SERVER_CERTIFICATE_REQUEST_FAILED, fatal : true, networkDetails: XMLHttpRequest }
  • Hls.ErrorDetails.KEY_SYSTEM_SERVER_CERTIFICATE_UPDATE_FAILED - MediaKeys.setServerCertificate(certificateData) 失败
    • 数据: { type : KEY_SYSTEM_ERROR, details : Hls.ErrorDetails.KEY_SYSTEM_SERVER_CERTIFICATE_UPDATE_FAILED, fatal : true, error: 错误 }
  • Hls.ErrorDetails.KEY_SYSTEM_SESSION_UPDATE_FAILED - MediaKeySession update(licenseResponse|acknowledged) 失败
    • 数据: { type : KEY_SYSTEM_ERROR, details : Hls.ErrorDetails.KEY_SYSTEM_SESSION_UPDATE_FAILED, fatal : true, error: 错误 }
  • Hls.ErrorDetails.KEY_SYSTEM_STATUS_OUTPUT_RESTRICTED - 密钥会话的 HDCP 级别输出受限
    • 数据: { type : KEY_SYSTEM_ERROR, details : Hls.ErrorDetails.KEY_SYSTEM_STATUS_OUTPUT_RESTRICTED, fatal : false }
  • Hls.ErrorDetails.KEY_SYSTEM_STATUS_INTERNAL_ERROR - 密钥会话状态更改为 "internal-error"
    • 数据: { type : KEY_SYSTEM_ERROR, details : Hls.ErrorDetails.KEY_SYSTEM_STATUS_INTERNAL_ERROR, fatal : true }

其他错误

  • Hls.ErrorDetails.LEVEL_SWITCH_ERROR - 当级别切换失败时触发
    • 数据: { type : OTHER_ERROR, details : Hls.ErrorDetails.LEVEL_SWITCH_ERROR, fatal : false, level : 失败级别的索引, reason : 失败原因 }
  • Hls.ErrorDetails.INTERNAL_EXCEPTION - 当在 hls.js 内部事件处理程序中发生异常时触发
    • 数据: { type : OTHER_ERROR, details : Hls.ErrorDetails.INTERNAL_EXCEPTION, fatal : true 或 false, event : 事件对象或字符串, err : { message : 错误信息 } }
  • Hls.ErrorDetails.UNKNOWN - 未分类错误

对象

Level

Level 对象表示一个给定的质量级别。 它包含从清单中检索到的与质量级别相关的信息，例如：

  • 级别比特率
  • 使用的编解码器
  • 视频宽度/高度
  • 级别名称
  • 级别 URL

参见下面的 Level 对象示例：

{
  audioCodec: "mp4a.40.2"
  audioGroupIds: <string[]> | undefined,
  bitrate: 3000000,
  codecSet: "avc1,mp4a",
  details: <LevelDetails> | undefined
  fragmentError: 0,
  frameRate: 30,
  height: 720,
  loadError: 0
  name: "720p",
  realBitrate: 0,
  supportedPromise: undefined,
  supportedResult: {supported: true, configurations: <MediaDecodingConfiguration[]>, decodingInfoResults: <MediaCapabilitiesDecodingInfo[]>}
  textGroupIds: <string[]> | undefined,
  unknownCodecs: [],
  url: [ "http://levelURL.com", "http://levelURLfailover.com" ],
  videoCodec: "avc1.66.30",
  width: 1280,
  attrs: <AttrList>,
  audioGroupId: undefined,
  averageBitrate: 2962000,
  codecs: "avc1.66.30,mp4a.40.2",
  maxBitrate: 3000000,
  pathwayId: ".",
  score: 0,
  textGroupId: "subs",
  uri: "http://levelURL.com",
  urlId: 0,
  videoRange: "SDR"
}
  • url 是一个数组，如果清单中存在故障转移/冗余流，则可能包含多个项目。

LevelDetails

LevelDetails 对象包含在解析播放列表后获取的级别详细信息，具体如下：

  • 协议版本
  • 播放列表类型
  • 起始序列号
  • 结束序列号
  • 级别总时长
  • 级别片段目标时长
  • 片段信息数组
  • 该级别是否为直播播放列表

在触发相应的 LEVEL_LOADED 事件后，可用的示例对象如下：

{
  version: 3,
  type: 'VOD', // 如果不存在 EXT-X-PLAYLIST-TYPE，则为 null
  startSN: 0,
  endSN: 50,
  totalduration: 510,
  targetduration: 10,
  fragments: Array(51),
  live: false
}

Fragment

Fragment 对象包含与片段相关的信息，例如：

  • 片段 URL
  • 片段时长
  • 片段序列号
  • 片段起始偏移量
  • 级别标识符

示例对象如下：

{
  duration: 10,
  level: 3,
  cc: 0
  sn: 35,
  start: 30,
  url: 'http://fragURL.com'
}

参考链接

0
hls.js HLS web组件 JavaScript 前端 VideoPlayer

  1. 支付宝打赏

    qrcode alipay

  2. 微信打赏

    qrcode weixin

  3. QQ打赏

    qrcode qq
版权归属： 邱少羽梦
本文链接： https://www.qiushaocloud.top/2025/02/13/hls.js-guan-fang-api-zhong-wen-wen-dang
许可协议： 本文使用《署名-非商业性使用-相同方式共享 4.0 国际 (CC BY-NC-SA 4.0)》协议授权

评论区