API

[toc]

入门

第一步：设置和支持

首先在您的网页中包含https://cdn.jsdelivr.net/npm/hls.js@latest（或未/hls.js最终）。

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

调用以下静态方法：Hls.isSupported()检查您的浏览器是否支持MediaSource Extensions.

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

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

让我们

• 创建一个
• 创建一个新的HLS对象
• 将视频元素绑定到此HLS对象

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

  <video id="video"></video>
  <script>
    if (Hls.isSupported()) {
      var video = document.getElementById('video');
      var hls = new Hls();
      // bind them together
      hls.attachMedia(video);
      // MEDIA_ATTACHED event is fired by hls object once MediaSource is ready
      hls.on(Hls.Events.MEDIA_ATTACHED, function () {
            console.log("video and hls.js are now bound together !");
      });
    }
  </script>

第三步：加载清单

您需要提供以下清单网址：

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

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

第四步：通过video元素控制

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

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

  video.play();

第五步：错误处理

所有错误都通过一个独特的单一事件发出。

每个错误分类如下：

其类型：

• Hls.ErrorTypes.NETWORK_ERROR 网络相关错误
• Hls.ErrorTypes.MEDIA_ERROR 媒体/视频相关的错误
• Hls.ErrorTypes.OTHER_ERROR 对于所有其他错误

其细节：

请参阅错误详细信息

其死亡：

• false 如果错误不是致命的，hls.js将尝试恢复它
• true 如果错误是致命的，则需要（尝试）恢复它的操作。

详细说明 如下

请参阅下面的示例代码来收听错误：

  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提供了通过这两种方法“尝试”恢复致命的网络和媒体错误的方法：

hls.startLoad()

应调用恢复网络错误。

hls.recoverMediaError()

应调用恢复媒体错误。

错误恢复示例代码

  hls.on(Hls.Events.ERROR, function (event, data) {
    if (data.fatal) {
      switch(data.type) {
      case Hls.ErrorTypes.NETWORK_ERROR:
      // try to recover network error
        console.log("fatal network error encountered, try to recover");
        hls.startLoad();
        break;
      case Hls.ErrorTypes.MEDIA_ERROR:
        console.log("fatal media error encountered, try to recover");
        hls.recoverMediaError();
        break;
      default:
      // cannot recover
        hls.destroy();
        break;
      }
    }
  });

hls.swapAudioCodec()

如果媒体错误在调用后仍然出现hls.recoverMediaError()，调用此方法可能会有助于解决音频编解码器不匹配问题。工作流应该是：

在第一媒体错误：呼叫 hls.recoverMediaError()

如果在第一个媒体错误之后提醒“快速”另一个媒体错误：首先呼叫hls.swapAudioCodec()，然后调用hls.recoverMediaError()。

最后一步：摧毁，切换流

hls.destroy() 应该调用自由使用资源并销毁hls上下文。

微调

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

   var config = {
      autoStartLoad: true,
        startPosition : -1,
      capLevelToPlayerSize: false,
      debug: false,
      defaultAudioCodec: undefined,
      initialLiveManifestSize: 1,
      maxBufferLength: 30,
      maxMaxBufferLength: 600,
      maxBufferSize: 60*1000*1000,
      maxBufferHole: 0.5,
      maxSeekHole: 2,
      lowBufferWatchdogPeriod: 0.5,
      highBufferWatchdogPeriod: 3,
      nudgeOffset: 0.1,
      nudgeMaxRetry : 3,
      maxFragLookUpTolerance: 0.2,
      liveSyncDurationCount: 3,
      liveMaxLatencyDurationCount: 10,
      enableWorker: true,
      enableSoftwareAES: true,
      manifestLoadingTimeOut: 10000,
      manifestLoadingMaxRetry: 1,
      manifestLoadingRetryDelay: 500,
      manifestLoadingMaxRetryTimeout : 64000,
      startLevel: undefined,
      levelLoadingTimeOut: 10000,
      levelLoadingMaxRetry: 4,
      levelLoadingRetryDelay: 500,
      levelLoadingMaxRetryTimeout: 64000,
      fragLoadingTimeOut: 20000,
      fragLoadingMaxRetry: 6,
      fragLoadingRetryDelay: 500,
      fragLoadingMaxRetryTimeout: 64000,
      startFragPrefetch: false,
      appendErrorMaxRetry: 3,
      loader: customLoader,
      fLoader: customFragmentLoader,
      pLoader: customPlaylistLoader,
      xhrSetup: XMLHttpRequestSetupCallback,
      fetchSetup: FetchSetupCallback,
      abrController: customAbrController,
      timelineController: TimelineController,
      enableCEA708Captions: true,
      stretchShortVideoTrack: false,
      forceKeyFrameOnDiscontinuity: true,
      abrEwmaFastLive: 5.0,
      abrEwmaSlowLive: 9.0,
      abrEwmaFastVoD: 4.0,
      abrEwmaSlowVoD: 15.0,
      abrEwmaDefaultEstimate: 500000,
      abrBandWidthFactor: 0.8,
      abrBandWidthUpFactor: 0.7,
      minAutoBitrate: 0
  };

  var hls = new Hls(config);

Hls.DefaultConfig get/set

该getter / setter允许检索和覆盖Hls默认配置。默认情况下，此配置将应用于所有实例。

capLevelToPlayerSize

（默认值：false）

• 如果设置为true，则具有限制级别的自适应算法可以通过HTML视频元素维度（宽度和高度）在自动质量中使用。如果多个级别之间的维数相等，则将帽选为具有最大带宽的级别。
• 如果设置为false，级别将不受限制。所有可用的电平可以用于仅考虑带宽的自动质量模式。

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，播放将从VoD的initialTime = 0开始，并根据liveSyncDuration/liveSyncDurationCountLive的配置参数启动
• 否则，播放将从预定义的值开始。（除非在autoStartLoad=false模式中另有说明：在这种情况下，startPosition可以被覆盖hls.startLoad(startPosition)）。

defaultAudioCodec

（默认值：undefined）

如果音频编解码器没有在变体清单中发出信号，或者仅提供流清单，hls.js会尝试通过解析ADTS头中的音频采样率来猜测音频编解码器。如果采样率小于或等于22050Hz，则hls.js假设它是HE-AAC，否则假设它是AAC-LC。这可能会导致错误的猜测，导致音频解码错误，最终导致媒体错误。通过配置这个值可以提示hls.js的默认audiocodec如下：

• mp4a.40.2 （AAC-LC）或
• mp4a.40.5 （HE-AAC）或
• undefined （基于抽样率的猜测）

initialLiveManifestSize

（默认为1）

开始播放Live Stream所需的片段数。

maxBufferLength

（默认值：30秒）

最大缓冲区长度（以秒为单位）。如果缓冲区长度小于该值，则会加载新的片段。这是保证缓冲区长度hls.js将尝试达到，而不管maxBufferSize。

maxBufferSize

（默认值：60 MB）

'最小'最大缓冲区大小（以字节计）。如果前面的缓冲区大小大于此值，则不会加载片段。

maxBufferHole

（默认值：0.5秒）

在搜索下一个片段加载时，hls.js可以处理的“最大”片间缓冲区容差。当切换质量水平时，碎片可能不完全对齐。这可能导致媒体缓冲区中的小重叠或空洞。这个公差系数有助于应对这个问题。

maxSeekHole

（默认值：2秒）

如果播放停止，并且缓冲范围可以在前面使用，maxSeekHole则从当前媒体位置开始不到几秒钟，hls.js将跳过此缓冲区，以达到以下缓冲范围的开始。 maxSeekHole允许配置此可跳转阈值。

maxStarvationDelay

（默认4s）

ABR算法将始终尝试选择应该避免重制的质量级别。如果没有这个标准的质量水平可以被发现（例如，缓冲区长度为1秒，但是以最低质量获取片段预计需要大约2秒...即我们可以预测约1s的拒绝...）那么ABR算法将尝试找到一个应该保证小于maxStarvationDelay缓冲的级别。

maxLoadingDelay

（默认4s）

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

lowBufferWatchdogPeriod

（默认0.5s）

如果媒体元素预期播放，如果currentTime没有移动超过，lowBufferWatchdogPeriod并且如果maxBufferHole先前缓存的时间少于秒，hls.js将尝试微调播放头来恢复播放

highBufferWatchdogPeriod

（默认3s）

如果媒体元素预计播放，如果currentTime没有移动超过，highBufferWatchdogPeriod并且如果maxBufferHole先前已经缓冲了多秒，hls.js将尝试推动播放头来恢复播放

nudgeOffset

（默认为0.1秒）

如果在第一个播放头微调之后播放继续停止，则即时更新后的currentTime将会在nudgeOffset之后更快地尝试恢复播放。media.currentTime + =（nb nudge retry -1）* nudgeOffset

nudgeMaxRetry

（默认3）

hb.js引发一个致命的BUFFER_STALLED_ERROR之前，微软重试的最大数量

maxFragLookUpTolerance

（默认为0.2s）

在片段查找期间使用此容差因子。而不是检查buffered.end是否位于[start，end]范围内，Frag查找将通过在[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

（默认600s）

最大缓冲区长度，以秒为单位。Hls.js永远不会超过这个值，即使maxBufferSize还没有达到。

hls.js尝试缓冲最大字节数（默认为60 MB），而不是缓冲到最大nb秒。这是为了模仿浏览器行为（缓冲区驱逐算法是在浏览器检测到视频缓冲区大小达到字节数限制后开始的）

maxBufferLength是hls.js将尝试实现的最小保证缓冲区长度，即使该值超过字节数量为60 MB的内存。 maxMaxBufferLength作为上限值，就像比特率真的很低，您可能需要超过一个小时的缓冲区来填充60 MB。

liveSyncDurationCount

（默认值：3）

实时延迟的边缘，以多重表示EXT-X-TARGETDURATION。如果设置为3，播放将从片段N-3开始，N是现场播放列表的最后片段。减小此值可能会导致播放失速。

liveMaxLatencyDurationCount

（默认值：Infinity）

最大延迟允许从生活的边缘，表示为多个EXT-X-TARGETDURATION。如果设置为10，播放器将在liveSyncDurationCount每次要加载的下一个片段都比N-10更早的时候回复，N是现场播放列表的最后片段。如果设置，该值必须严格优于liveSyncDurationCount 太靠近的值liveSyncDurationCount可能导致播放失速。

liveSyncDuration

（默认值：undefined）

替代参数liveSyncDurationCount，以秒表示，段数。如果在配置对象中定义，liveSyncDuration将优先于默认值liveSyncDurationCount。您不能定义这个参数，要么liveSyncDurationCount或者liveMaxLatencyDurationCount在您的配置对象在同一时间。值太低（低于〜3段持续时间）可能导致播放停顿。

liveMaxLatencyDuration

（默认值：undefined）

替代参数liveMaxLatencyDurationCount，以秒表示，段数。如果在配置对象中定义，liveMaxLatencyDuration将优先于默认值liveMaxLatencyDurationCount。如果设置，此值必须严格优于liveSyncDuration必须定义的值。您不能定义这个参数，要么liveSyncDurationCount或者liveMaxLatencyDurationCount在您的配置对象在同一时间。太靠近的值liveSyncDuration很可能导致播放失速。

enableWorker

（默认值：true）

启用WebWorker（如果在浏览器中可用）用于TS解复用/ MP4重新配置，以提高性能并避免滞后/帧丢失。

enableSoftwareAES

（默认值：true）

启用使用JavaScript版本AES解密来回溯WebCrypto API。

startLevel

（默认值：undefined）

设置时，使用此级别作为默认的hls.startLevel。请记住，使用API​​设置的startLevel优先于config.startLevel配置参数。

fragLoadingTimeOut/ manifestLoadingTimeOut/levelLoadingTimeOut

（默认值：片段的60000ms /级别和清单的10000ms）

URL装载程序超时 如果加载持续时间超过此超时，则会触发超时回调。不进行任何操作：加载操作不会被取消/中止。捕获此事件的应用程序取决于需要。

fragLoadingMaxRetry/ manifestLoadingMaxRetry/levelLoadingMaxRetry

（默认值：6/ 1/ 4）

最大负载重试次数。

fragLoadingMaxRetryTimeout/ manifestLoadingMaxRetryTimeout/levelLoadingMaxRetryTimeout

（默认值：64000ms）

在满足I / O错误的情况下，最大的frag / manifest / key重试超时（以毫秒为单位）。

fragLoadingRetryDelay/ manifestLoadingRetryDelay/levelLoadingRetryDelay

（默认值：1000ms）

XMLHttpRequest错误和第一次加载重试之间的初始延迟（以ms为单位）。任何I / O错误将触发每500ms，1s，2s，4s，8s，...上限重试到fragLoadingMaxRetryTimeout/ manifestLoadingMaxRetryTimeout/ levelLoadingMaxRetryTimeoutvalue（指数回退）。

预览开始片段虽然媒体未附加。

startFragPrefetch

（默认值：false）

开始预取开始片段，尽管媒体尚未附加。

appendErrorMaxRetry

（默认值：3）

sourceBuffer.appendBuffer()错误后重试的最大次数。当内部缓冲区已满时，这种错误可能发生在与UHD流的循环中。（配额超出错误将被触发）。在这种情况下，我们需要等待浏览器驱赶一些数据才能正确附加缓冲区。

loader

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

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

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

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

  var customLoader = function () {
    /**
     * Calling load() will start retrieving content located at given URL (HTTP GET).
     *
     * @param {object} context - loader context
     * @param {string} context.url - target URL
     * @param {string} context.responseType - loader response type (arraybuffer or default response type for playlist)
     * @param {number} [context.rangeStart] - start byte range offset
     * @param {number} [context.rangeEnd] - end byte range offset
     * @param {Boolean} [context.progressData] - true if onProgress should report partial chunk of loaded content
     * @param {object} config - loader config params
     * @param {number} config.maxRetry - Max number of load retries
     * @param {number} config.timeout - Timeout after which `onTimeOut` callback will be triggered (if loading is still not finished after that delay)
     * @param {number} config.retryDelay - Delay between an I/O error and following connection retry (ms). This to avoid spamming the server
     * @param {number} config.maxRetryDelay - max connection retry delay (ms)
     * @param {object} callbacks - loader callbacks
     * @param {onSuccessCallback} callbacks.onSuccess - Callback triggered upon successful loading of URL.
     * @param {onProgressCallback} callbacks.onProgress - Callback triggered while loading is in progress.
     * @param {onErrorCallback} callbacks.onError - Callback triggered if any I/O error is met while loading fragment.
     * @param {onTimeoutCallback} callbacks.onTimeout - Callback triggered if loading is still not finished after a certain duration.

      @callback onSuccessCallback
      @param response {object} - response data
      @param response.url {string} - response URL (which might have been redirected)
      @param response.data {string/arraybuffer} - response data (reponse type should be as per context.responseType)
      @param stats {object} - loading stats
      @param stats.trequest {number} - performance.now() just after load() has been called
      @param stats.tfirst {number} - performance.now() of first received byte
      @param stats.tload {number} - performance.now() on load complete
      @param stats.loaded {number} - nb of loaded bytes
      @param [stats.bw] {number} - download bandwidth in bit/s
      @param stats.total {number} - total nb of bytes
      @param context {object} - loader context
      @param networkDetails {object} - loader network details (the xhr for default loaders)

      @callback onProgressCallback
      @param stats {object} - loading stats
      @param stats.trequest {number} - performance.now() just after load() has been called
      @param stats.tfirst {number} - performance.now() of first received byte
      @param stats.loaded {number} - nb of loaded bytes
      @param [stats.total] {number} - total nb of bytes
      @param [stats.bw] {number} - current download bandwidth in bit/s (monitored by ABR controller to control emergency switch down)
      @param context {object} - loader context
      @param data {string/arraybuffer} - onProgress data (should be defined only if context.progressData === true)
      @param networkDetails {object} - loader network details (the xhr for default loaders)

      @callback onErrorCallback
      @param error {object} - error data
      @param error.code {number} - error status code
      @param error.text {string} - error description
      @param context {object} - loader context
      @param networkDetails {object} - loader network details (the xhr for default loaders)

      @callback onTimeoutCallback
      @param stats {object} - loading stats
      @param context {object} - loader context

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

    /** Abort any loading in progress. */
    this.abort = function () {};

    /** Destroy loading context. */
    this.destroy = function () {};
  }

fLoader

（默认值：undefined）

这使得能够操纵片段装载器。注意：这将覆盖默认值loader，以及您自己的加载器功能（见上文）。

  var customFragmentLoader = function() {
    // See `loader` for details.
  }

pLoader

（默认值：undefined）

这使得能够操纵播放列表加载器。注意：这将覆盖默认值loader，以及您自己的加载器功能（见上文）。

  var customPlaylistLoader = function() {
    // See `loader` for details.
  }

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

// special playlist post processing function
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）

XMLHttpRequest 默认的基于XHR的加载程序的定制回调。

参数应该是一个有两个参数的函数(xhr: XMLHttpRequest, url: string)。如果xhrSetup指定，默认加载程序将在调用之前调用它xhr.send()。这允许用户轻松修改/设置XHR。见下面的例子。

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

fetchSetup

（默认值：undefined）

Fetch 基于Fetch的加载程序的定制回调。

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

  var config = {
    fetchSetup: function(context, initParams) {
      // Always send cookies, even for cross-origin calls.
      initParams.credentials = 'include';
      return new Request(context.url,initParams);
    }
  }

abrController

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

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

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

• get / set nextAutoLevel：返回下一个自动质量级别/强制下一个应该返回的自动质量级别（当前用于紧急切换）
• get / set autoLevelCapping：可以由ABR Controller使用的capping / max level值
• destroy()：应清理所有使用的资源

timelineController

（默认值：内部跟踪时间轴控制器）

定制文本轨道同步控制器。

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

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

enableCEA708Captions

（默认值：true）

是否启用CEA-708字幕

参数应该是一个布尔值

captionsTextTrack1Label

（默认值：English）

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

参数应该是一个字符串

captionsTextTrack1LanguageCode

（默认值：en）

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

参数应该是一个字符串

captionsTextTrack2Label

（默认值：Spanish）

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

参数应该是一个字符串

captionsTextTrack2LanguageCode

（默认值：es）

为CEA-708标题轨道生成的文本轨道的RFC 3066语言代码。

参数应该是一个字符串

stretchShortVideoTrack

（默认值：false）

如果片段的视频轨道比其音轨短min(maxSeekHole, maxBufferHole)，则扩展最终视频帧的持续时间以匹配音轨的持续时间。这有助于在某些情况下继续播放，否则可能会卡住。

参数应该是一个布尔值

forceKeyFrameOnDiscontinuity

（默认值：true）

在不连续性之后是否强制在第一AVC样本中具有关键帧。如果设置为true，则在不连续之后，没有任何关键帧的AVC采样将被丢弃，直到找到包含关键帧的样本。如果设置为false，将保留所有AVC样本，这有助于避免流中的漏洞。将此参数设置为false也可以在切换级别或寻找时产生解码异常。

参数应该是一个布尔值

abrEwmaFastLive

（默认值：5.0）

快速比特率指数移动平均半衰期，用于计算Live流的平均比特率。估计的一半是基于样品历史记录的最后一个abrEwmaFastLive秒。每个样本被片段加载持续时间加权。

参数应该是大于0的float

abrEwmaSlowLive

（默认值：9.0）

慢比特率指数移动平均半衰期，用于计算Live流的平均比特率。一半的估计是基于最近的abrEwmaSlowLive秒的采样历史。每个样本被片段加载持续时间加权。

参数应该是一个大于abrEwmaFastLive的float

abrEwmaFastVoD

（默认值：4.0）

快速比特率指数移动平均半衰期，用于计算VoD流的平均比特率。估计的一半是基于样本历史的最后一个abrEwmaFastVoD秒。每个样本被片段加载持续时间加权。

参数应该是大于0的float

abrEwmaSlowVoD

（默认值：15.0）

慢比特率指数移动平均半衰期，用于计算VoD流的平均比特率。一半的估计是基于最后一个abrEwmaSlowVoD秒的样本历史记录。每个样本被片段加载持续时间加权。

参数应该是大于abrEwmaFastVoD的float

abrEwmaDefaultEstimate

（默认值：500000）

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

参数应该是一个float

abrBandWidthFactor

（默认值：0.8）

应用于测量带宽平均值的比例因子，以确定是否可以保持当前或较低的质量水平。如果abrBandWidthFactor * bandwidth average < level.bitrateABR可以切换到该级别，只要它等于或小于当前级别。

abrBandWidthUpFactor

（默认值：0.7）

应用于测量带宽平均值的比例因子，以确定是否可以切换到更高的质量水平。如果abrBandWidthUpFactor * bandwidth average < level.bitrateABR可以切换到该质量级别。

abrMaxWithRealBitrate

（默认值：false）

在ABR中通过avg测量的比特率使用的最大比特率，即如果给定级别的变体清单中发送的比特率为2Mb / s，则在该级别上测量的平均比特率为2.5Mb / s，则如果配置值设置为true，ABR将使用2.5Mb / s为这个质量水平。

minAutoBitrate

（默认值：0）

返回自动电平选择算法可以使用的封顶/最小带宽值。当浏览器的浏览器或选项卡不在焦点并且带宽下降时有用

视频绑定/解除绑定API

hls.attachMedia(videoElement)

调用此方法将：

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

hls.detachMedia()

Calling this method will:

调用此方法将：

• 从hls实例中取消绑定VideoElement，
• 在MediaSource上表示流的结尾
• 重置视频源（video.src = ''）

hls.media

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

质量开关控制API

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

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.startLevel

get / set：开始级别索引（将要播放的第一个片段的级别）。

• 如果不被用户覆盖：清单中出现的第一级将被用作开始级别。
• 如果-1：自动启动级别选择，播放将从级别匹配下载带宽开始（从下载第一段确定）。

默认值为hls.firstLevel。

hls.autoLevelEnabled

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

hls.autoLevelCapping

• get / set：ABR Controller可以使用的Capping / max level值。

默认值为-1（无级别封顶）。

版本控制

Hls.version

静态getter：返回hls.js dist版本号。

网络加载控制API

默认情况下，hls.js将自动开始加载质量级别的播放列表，并且Hls.Events.MANIFEST_PARSED已经触发事件之后的片段（并且附加了视频元素）。

但是如果config.autoStartLoad设置为false，则需要调用以下方法手动启动播放列表和片段加载：

hls.startLoad(startPosition=-1)

启动/重新启动播放列表/片段加载。这只有在MANIFEST_PARSED事件被触发并且视频元素已被附加到hls对象时才有效。

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

hls.stopLoad()

停止播放列表/片段加载。可以通过电话来恢复hls.startLoad()

音频跟踪控制API

hls.audioTracks

get：在清单中暴露的音轨数组

hls.audioTrack

get / set：音轨id（返回）

直播API

hls.liveSyncPosition

get：实时同步点的位置（即实时位置的边缘减去安全延迟定义hls.config.liveSyncDuration）

运行时事件

Hls.js会发出一堆事件，可以注册如下：

hls.on(Hls.Events.LEVEL_LOADED,function(event,data) {
  var level_duration = data.details.totalduration;
});

活动的完整列表如下：

装载机组成

您可以通过静态吸气剂导出您自己实现的内部加载器定义Hls.DefaultConfig.loader。

例：

import Hls from 'hls.js';

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

    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);
    };
  }
});

错误

完整的错误列表如下所示：

网络错误

• Hls.ErrorDetails.MANIFEST_LOAD_ERROR - 由于网络错误，清单加载失败时引发

数据：{type：NETWORK_ERROR，details：Hls.ErrorDetails.MANIFEST_LOAD_ERROR，fatal：true，url：manifest URL，response：{code：error code，text：error text}，loader：URL loader}

• Hls.ErrorDetails.MANIFEST_LOAD_TIMEOUT - 由于超时，清单加载失败时引发

data：{type：NETWORK_ERROR，details：Hls.ErrorDetails.MANIFEST_LOAD_TIMEOUT，fatal：true，url：manifest URL，loader：URL loader}

• Hls.ErrorDetails.MANIFEST_PARSING_ERROR - 当清单解析未能找到适当的内容时引发

data：{type：NETWORK_ERROR，details：Hls.ErrorDetails.MANIFEST_PARSING_ERROR，fatal：true，url：manifest URL，reason：parsing error reason}

• Hls.ErrorDetails.LEVEL_LOAD_ERROR - 由于网络错误导致级别加载失败时引发

数据：{type：NETWORK_ERROR，details：Hls.ErrorDetails.LEVEL_LOAD_ERROR，fatal：true，url：level URL，response：{code：error code，text：error text}，loader：URL loader}

• Hls.ErrorDetails.LEVEL_LOAD_TIMEOUT - 由于超时，级别加载失败时引发

data：{type：NETWORK_ERROR，details：Hls.ErrorDetails.LEVEL_LOAD_TIMEOUT，fatal：true，url：level URL，loader：URL loader}

• Hls.ErrorDetails.LEVEL_SWITCH_ERROR - 电平切换失败时升高

data：{type：OTHER_ERROR，details：Hls.ErrorDetails.LEVEL_SWITCH_ERROR，fatal：false，level：failed level index，reason：failure reason}

• Hls.ErrorDetails.FRAG_LOAD_ERROR - 由于网络错误，片段加载失败时引发

data：{type：NETWORK_ERROR，details：Hls.ErrorDetails.FRAG_LOAD_ERROR，fatal：trueor false，frag：fragment object，response：{code：error code，text：error text}}

• Hls.ErrorDetails.FRAG_LOOP_LOADING_ERROR - 在检测到循环中要求的相同片段时提高

data：{type：NETWORK_ERROR，details：Hls.ErrorDetails.FRAG_LOOP_LOADING_ERROR，fatal：trueor false，frag：fragment object}

• Hls.ErrorDetails.FRAG_LOAD_TIMEOUT - 由于超时，片段加载失败时引发

data：{type：NETWORK_ERROR，details：Hls.ErrorDetails.FRAG_LOAD_TIMEOUT，fatal：trueor false，frag：fragment object}

• Hls.ErrorDetails.FRAG_PARSING_ERROR - 当片段解析失败时引发

数据：{type：NETWORK_ERROR，details：Hls.ErrorDetails.FRAG_PARSING_ERROR，fatal：trueor false，reason：failure reason}

媒体错误

• Hls.ErrorDetails.MANIFEST_INCOMPATIBLE_CODECS_ERROR - 当清单只包含与MediaSource Engine不兼容的编解码器的质量级别时引发。

数据：{type：MEDIA_ERROR，details：Hls.ErrorDetails.MANIFEST_INCOMPATIBLE_CODECS_ERROR，fatal：true，url：manifest URL}

• Hls.ErrorDetails.BUFFER_ADD_CODEC_ERROR - 当MediaSource无法添加新的sourceBuffer时引发

data：{type：MEDIA_ERROR，details：Hls.ErrorDetails.BUFFER_ADD_CODEC_ERROR，fatal：false，err：MediaSource引发的错误，mimeType：发生故障的mimeType}

• Hls.ErrorDetails.BUFFER_APPEND_ERROR - 调用缓冲区附加时异常引发时引发

data：{type：MEDIA_ERROR，details：Hls.ErrorDetails.BUFFER_APPEND_ERROR，fatal：true，parent：parent stream controller}

• Hls.ErrorDetails.BUFFER_APPENDING_ERROR - 在缓冲区追加期间引发异常时引发

资料：{type：MEDIA_ERROR，details：Hls.ErrorDetails.BUFFER_APPENDING_ERROR，fatal：false}

• Hls.ErrorDetails.BUFFER_STALLED_ERROR - 当缓冲区用尽数据时播放被卡住时提高

data：{type：MEDIA_ERROR，details：Hls.ErrorDetails.BUFFER_STALLED_ERROR，fatal：false，parent：parent stream controller}

• 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：hole duration}

对象

水平

一个 Level 对象表示一个给定的质量水平。它包含质量等级相关信息，从清单检索，如：

• 级别比特率
• 使用的编解码器
• 视频宽/高
• 级别名称
• 级别的URL
• 请参见Level下面的示例对象：

{
  url: [ 'http://levelURL.com', 'http://levelURLfailover.com' ],
  bitrate: 246440,
  name: "240",
  codecs: "mp4a.40.5,avc1.42000d",
  width: 320,
  height: 136,
}

• url 是一个数组，如果在清单中找到故障切换/冗余流，则可能包含多个项目。

LevelDetails

一个 LevelDetails 对象包含播放列表水平解析后检索的水平细节，但是它们被指定如下：

• 协议版本
• 播放列表类型
• 启动序列号
• 结束序列号
• 水平总持续时间
• 级片段目标持续时间
• 数组碎片信息
• 这个级别是否是现场播放列表？

请参阅下面的示例对象，在相应的LEVEL_LOADED事件触发后可用：

{
  version: 3,
  type: 'VOD', // null if EXT-X-PLAYLIST-TYPE not present
  startSN: 0,
  endSN: 50,
  totalduration: 510,
  targetduration: 10,
  fragments: Array(51),
  live: false
}

分段

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

• 片段网址
• 片段持续时间
• 片段序列号
• 片段起始偏移
• 级标识符

参见下面的示例对象：

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