# @clappr/hlsjs-playback 中文文档

规范地址：https://npmcn.com/package/%40clappr/hlsjs-playback/

版本：3\.1\.4
npm 元数据更新时间：2026-10-26T15:19:12.816Z
中文译文更新时间：2026-11-09T23:39:05.050Z
软件包许可：BSD-3-Clause

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40clappr/hlsjs-playback
原文对照：https://npmcn.com/package/%40clappr/hlsjs-playback/?lang=original
项目主页：https://github.com/clappr/hlsjs-playback
源码仓库：https://github.com/clappr/clappr

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：311 kB，12 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：未声明
- 运行依赖：0 个
- peer 依赖：hls\.js ^1，@clappr/core \*
- 首次发布：2019-06-24T22:38:45.094Z
- 最新版本发布：2026-10-26T15:19:12.390Z
- 近 30 天下载量：3015（2026-10-10 至 2026-11-08，npm 官方下载统计）
- 已发布版本数：53（近 12 个月 18 个）

## 中文简介

基于hls.js的 HLS 回放

## 安装

```sh
npm install @clappr/hlsjs-playback
```

也可以使用：`pnpm add @clappr/hlsjs-playback`、`yarn add @clappr/hlsjs-playback`、`bun add @clappr/hlsjs-playback`

## README

# Hlsjs 弹出

A 类 [克莱普](https://github.com/clappr/clappr) 播放以 HTTP Live Streaming (HLS) 为基础的播放 [hls.js (英语)](https://github.com/video-dev/hls.js)。 。 。 .

[![CI](https://github.com/clappr/clappr/actions/workflows/ci.yml/badge.svg)](https://github.com/clappr/clappr/actions/workflows/ci.yml) [![npm version](https://img.shields.io/npm/v/@clappr/hlsjs-playback.svg?color=cb3837)](https://www.npmjs.com/package/@clappr/hlsjs-playback) [![License](https://img.shields.io/github/license/clappr/clappr)](https://github.com/clappr/clappr/blob/main/LICENSE) [![minified size](https://img.shields.io/bundlephobia/min/@clappr/hlsjs-playback)](https://bundlephobia.com/package/@clappr/hlsjs-playback) [![jsDelivr monthly downloads](https://img.shields.io/jsdelivr/npm/hm/@clappr/hlsjs-playback?color=orange)](https://www.jsdelivr.com/package/npm/@clappr/hlsjs-playback)

> **3.0.0中出现突破变化 -** `hls.js` 不再捆绑。 现在所有文物都期待 你提供它。 见下文移徙说明.

## 使用量

你可以从JSDelivr那里使用:

```html
<script src="https://cdn.jsdelivr.net/npm/@clappr/core@latest/dist/clappr-core.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/hls.js@1/dist/hls.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/@clappr/hlsjs-playback@3/dist/hlsjs-playback.min.js"></script>
```

或作为 npm 包 :

`yarn add @clappr/hlsjs-playback hls.js@^1`

### 要装载的文物

| 假设 | 艺术 |
| --- | --- |
| `<script>` / CDN, 之后为 `@clappr/core` 财务报告和审定财务报表 `hls.js` | `dist/hlsjs-playback.min.js` |
| Bundler, 普通JS / UMD 条目 | `dist/hlsjs-playback.js` (包装) `main`(中文(简体) ) |
| Bundler,无害环境管理条目 | `dist/hlsjs-playback.esm.js` (包装) `module`(中文(简体) ) |

**移徙说明(3.0+):** 现在所有文物都期待 `hls.js` 从页面或捆绑。 如果装入 `hlsjs-playback.min.js` 使用单一脚本标签,添加 `hls.js` 在它开始之前 如果您为避免被捆绑的复制而别名深道, 请将该条目从捆绑者那里删除 `resolve.alias` (网包)或等同(网络) `resolve.alias`滚动 `alias`)——默认条目现在是外部的:

```diff
- '@clappr/hlsjs-playback': '@clappr/hlsjs-playback/dist/hlsjs-playback.external.js',
```

那就加点 `HlsjsPlayback` 输入您的玩家实例插件列表 :

```javascript
var player = new Clappr.Player({
  source: 'https://bitdash-a.akamaihd.net/content/sintel/hls/playlist.m3u8',
  plugins: [HlsjsPlayback]
})
```

## 配置

播放的选项如下:

```javascript
var player = new Clappr.Player({
  source: 'https://bitdash-a.akamaihd.net/content/sintel/hls/playlist.m3u8',
  plugins: [HlsjsPlayback],
  hlsUseNextLevel: false,
  hlsMinimumDvrSize: 60,
  hlsRecoverAttempts: 16,
  hlsPlayback: {
    preload: true,
    customListeners: []
  },
  playback: {
    extrapolatedWindowNumSegments: 2,
    triggerFatalErrorOnResourceDenied: false,
    hlsjsConfig: {
      // hls.js specific options
    }
  }
})
```

#### hls 使用下一个级别

> 默认值 : `false`

HLS 回放的默认行为是使用 [hls. 当前级别](https://github.com/video-dev/hls.js/blob/master/docs/API.md#hlscurrentlevel) 切换当前关卡。 要改变此行为并强制 HLS 播放使用 [下一级](https://github.com/video-dev/hls.js/blob/master/docs/API.md#hlsnextlevel),添加 `hlsUseNextLevel: true` 以嵌入参数.

#### hls 最小DvrSize 码

> 默认值 : `60 (seconds)`

在 Clappr 活模式下定义活动搜索最小 DVR 大小的选项 .

#### 推算出 WindowNum 组件

> 默认值 : `2`

配置起始时间外推窗口的大小, 以多个分块来测量 .

应该是2或2以上,或者0 才能禁用. 如果一次从播放列表的开头删除一个以上的片段,它就应该增加到2以上.

例如:如果播放列表被缓存了10秒,每5秒会添加/删除新的块.

#### hls 恢复尝试

> 默认值 : `16`

这个 `hls.js` 有一些致命错误的恢复方法。 此选项为这些错误设置最大回收尝试号 .

#### 触发 Fatal Error 在资源上升级

> 默认值 : `false`

如果设置此选项为真, 如果解密密钥 http 响应码大于或等于 400 , 播放会触发致命错误事件 。 此选项用于尝试复制 iOS 设备行为, 内部使用 html5 视频回放 .

#### hls 弹出

> 很快(在新的断开更改版本中),所有与此回放相关的选项都会被声明在游戏范围中 `options` 对象必须在此新范围内宣布 !

组合所有直接相关的选项 `HlsjsPlayback` 相会相会.

```javascript
var player = new Clappr.Player(
  {
    ...
    hlsPlayback: {
      preload: true,
      customListeners: [],
    },
  });
```

#### `hlsPlayback.preload`

> 默认值 : `true`

配置来源是否在 `HLS.JS` 内部参考设置或仅在第一出戏后.

#### `hlsPlayback.customListeners`

包含特定参数的听众对象阵列 `HLS.JS` 举个例子.

```javascript
var player = new Clappr.Player(
  {
    ...
    hlsPlayback: {
      ...
      customListeners: [
        // "hlsFragLoaded" is the value of HlsjsPlayback.HLSJS.Events.FRAG_LOADED constant.
        { eventName: 'hlsFragLoaded', callback: (event, data) => { console.log('>>>>>> data: ', data) }, once: true }
      ],
    },
  });
```

听者对象参数为:

-   `eventName`: 一个有效的事件名称 `hls.js` [事件 API](https://github.com/video-dev/hls.js/blob/master/docs/API.md#runtime-events)· ;
-   `callback`:当事件听到时,应该召回的召回.
-   `once`: 如果听众需要一次有效, 要配置的旗帜 .

#### hlsjs 图形

作为 `HlsjsPlayback` 是基于 `hls.js`,有可能使用可用的 `hls.js` 相会也. 你可以检查出来 [这里](https://github.com/video-dev/hls.js/blob/master/docs/API.md#fine-tuning)。 。 。 .

要使用这些设置,请使用 `hlsjsConfig` 对象.

示例

```javascript
var player = new Clappr.Player(
  {
    ...
    playback: {
      hlsjsConfig: {
        debug: true, // https://github.com/video-dev/hls.js/blob/master/docs/API.md#debug
        enableworker: false, // https://github.com/video-dev/hls.js/blob/master/docs/API.md#enableworker
        ...
      },
    },
  });
```

## 发展

输入工程目录并安装依赖 :

`yarn install`

修改并运行测试( Vitest) :

`yarn test`

构建自己的版本( Vite 库模式) :

`yarn build`

检查结果 `dist/` 文件夹.

启动本地服务器 :

`yarn start`

此命令将在端口 8080 启动 Vite dev 服务器 。 您可以使用 HlsjsPlayback 在 http://localhost: 8080/ 上使用 Clappr- core 检查样本页面

## 释放

要发布新版本, 首先通过运行创建新标签 :

`npm version [patch | minor | major]`

选择 `patch`, (中文(简体) ), `minor`,或 `major` 根据新版本的修改.

之后,通过运行向国家预防机制发布新版本:

`npm publish`

请检查新版本 [npmjs @ clappr/hlsjs- playback (英语)](https://www.npmjs.com/package/@clappr/hlsjs-playback)。 。 。 .

## 常见问题

### @clappr/hlsjs-playback 是什么？

基于hls\.js的 HLS 回放

### 如何安装 @clappr/hlsjs-playback？

在项目目录运行 npm install @clappr/hlsjs-playback，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：hls\.js（^1）、@clappr/core（\*）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @clappr/hlsjs-playback 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/clappr\_\_hlsjs-playback 是否存在。

### @clappr/hlsjs-playback 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @clappr/hlsjs-playback 可以商用吗？

@clappr/hlsjs-playback 使用 BSD-3-Clause 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。另外不得用原作者名义为衍生产品背书。以上为概括，不构成法律意见，请以许可原文为准。

### @clappr/hlsjs-playback 的下载量有多少？

根据 npm 官方下载统计，@clappr/hlsjs-playback 在 2026/10/10 – 2026/11/08 这 30 天内被下载 3,015 次，日均约 101 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @clappr/hlsjs-playback 还在维护吗？

最新版本 3\.1\.4 发布于 2026/10/26（14 天前）；至今共发布 53 个版本，其中过去 12 个月发布了 18 个；首次发布于 2019/06/25。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。