# @gumlet/react-hls-player 中文文档

规范地址：https://npmcn.com/package/%40gumlet/react-hls-player/

版本：3\.0\.0
npm 元数据更新时间：2026-10-27T12:34:26.576Z
中文译文更新时间：2026-11-17T03:37:49.357Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：53.5 kB，20 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- 运行依赖：2 个
- peer 依赖：react \>=18，react-dom \>=18
- 首次发布：2022-11-18T18:28:26.394Z
- 最新版本发布：2026-10-27T12:34:25.878Z
- 近 30 天下载量：7293（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：5（近 12 个月 3 个）

## 中文简介

使用 Shaka 播放器对 HLS 和 DASH 进行回放, 使用 Gumlet Widevine 和 FairPlay

## 安装

```sh
npm install @gumlet/react-hls-player
```

也可以使用：`pnpm add @gumlet/react-hls-player`、`yarn add @gumlet/react-hls-player`、`bun add @gumlet/react-hls-player`

## README

# @gumlet/ react-hls- player (英语)

[![npm version](https://img.shields.io/npm/v/@gumlet/react-hls-player?style=flat-square)](https://www.npmjs.com/package/@gumlet/react-hls-player) [![npm downloads](https://img.shields.io/npm/dm/@gumlet/react-hls-player?style=flat-square)](https://www.npmjs.com/package/@gumlet/react-hls-player)

反应组件用于 **HLS 和 DASH 数据交换** 现场直播和现场直播 回放用途 [沙卡玩家](https://github.com/shaka-project/shaka-player) 5.1 与 Gumlet 嵌入式玩家相同 ABR, 重试, 并缓冲设置 。 Widevine和FairPlay使用Gumlet的许可证助手.

```bash
npm i @gumlet/react-hls-player
```

要求数 **反应 18+**。取决于 **夏卡球员 5.1**。 。 。 .

第3版取代了hls.js. `hlsConfig`, (中文(简体) ), `getHLSRef`,以及 `preferNativeHls` 不见了 使用 `playerConfig`, (中文(简体) ), `getPlayerRef`,以及 `drm` 换句话说.

## 演示

```bash
npm start
```

在端口8000上打开示例. 它播放一个Gumlet播放列表的样本,并将每个召回记录写入视频下的活动日志. `onTimeUpdate` 财务报告和审定财务报表 `onProgress` 进行采样,使日志可以读取.

-   **装入**,或者在流中的 URL 字段中输入,应用 URL 和任何 Widevine 或 FairPlay URI 并挂载玩家。 之后再用这个 **销毁视频**。 。 。 .
-   切换框 `muted`, (中文(简体) ), `autoPlay`,以及 `startHighestRes`。 。 。 .
-   将 DRM 字段留为空白, 用于清晰的回放 .

## 基本重播

```javascript
import React from 'react';
import { createRoot } from 'react-dom/client';
import ReactHlsPlayer from '@gumlet/react-hls-player';

createRoot(document.getElementById('app')).render(
  <ReactHlsPlayer
    src="https://video.gumlet.io/5f462c1561cf8a766464ffc4/635789f017629894d4d125a4/main.m3u8"
    autoPlay={false}
    muted
    controls
    playsInline
    loop
    width="100%"
    height="auto"
  />
);
```

沙卡负载 `src`。路径必须是 `/{collection_id}/{asset_id}/main.m3u8` 或者说 `main.mpd` 任何一个主机。 报告缺失的收集编号或资产编号 `onError` 在夏卡创造之前抛出。 URL没有设置在 `<video>` 键. `autoPlay` 电话 `play()` 之后 `load()` 决定。 说对了 `muted` 当浏览器用声音屏蔽自动播放时. `loop`, (中文(简体) ), `playsInline`, (中文(简体) ), `poster`, (中文(简体) ), `preload`, (中文(简体) ), `crossOrigin`, (中文(简体) ), `width`,以及 `height` 是普通的视频属性.

变化 `muted` 或者说 `autoPlay` 更新元素而不创建新的 Shaka 实例。 变化 `src` 或者说 `drm` 已经.

## 回电

过 `on*` 道具而不是视频元素上的收听器. 每次渲染上的新函数身份不会重建玩家.

```javascript
import React, { useState } from 'react';
import ReactHlsPlayer from '@gumlet/react-hls-player';

function PlayerWithLog({ src }) {
  const [log, setLog] = useState([]);

  function append(name, payload) {
    setLog((rows) => [
      ...rows,
      payload == null ? name : `${name} ${JSON.stringify(payload)}`,
    ]);
  }

  return (
    <>
      <ReactHlsPlayer
        src={src}
        controls
        muted
        playsInline
        onReady={() => append('onReady')}
        onPlay={() => append('onPlay')}
        onPause={() => append('onPause')}
        onPlaying={() => append('onPlaying')}
        onEnded={() => append('onEnded')}
        onWaiting={() => append('onWaiting')}
        onTimeUpdate={({ currentTime, duration }) =>
          append('onTimeUpdate', { currentTime, duration })
        }
        onProgress={({ percent }) => append('onProgress', { percent })}
        onSeeked={({ currentTime, duration }) =>
          append('onSeeked', { currentTime, duration })
        }
        onVolumeChange={({ volume, muted }) =>
          append('onVolumeChange', { volume, muted })
        }
        onManifestParsed={() => append('onManifestParsed')}
        onQualityChange={({ level, height, bitrate }) =>
          append('onQualityChange', { level, height, bitrate })
        }
        onError={(error) => append('onError', error)}
      />
      <pre>{log.join('\n')}</pre>
    </>
  );
}
```

`onReady` 财务报告和审定财务报表 `onManifestParsed` 两者的火当 `player.load()` 决定. `onQualityChange` 运行在沙卡 `adaptation`· ; `bitrate` 是活动变体的带宽. `onError` 报告Shaka错误(`source: 'shaka'`)和媒介元素错误(`source: 'video'`) (中文(简体) ).

## 视频元素和 Shaka 实例

| Prop | 你得到的东西 |
| --- | --- |
| `playerRef` 编号 : `ref` | 这个 `<video>` 要素(`play()`, (中文(简体) ), `pause()`, (中文(简体) ), `currentTime`(中文(简体) ) |
| `getPlayerRef` | 萨卡 `Player`调用 `null` 当那个例子被摧毁的时候. |

`playerRef` 是可选的。 组件在省略时会保留一个内部参考器. 活动玩家也是 `window.shaka` 财务报告和审定财务报表 `window.shakaPlayer`。 。 。 .

```javascript
import React from 'react';
import ReactHlsPlayer from '@gumlet/react-hls-player';

function MyCustomComponent() {
  const playerRef = React.useRef(null);

  return (
    <ReactHlsPlayer
      playerRef={playerRef}
      getPlayerRef={(player) => {
        if (player == null) {
          return;
        }
      }}
      src="https://video.gumlet.io/5f462c1561cf8a766464ffc4/635789f017629894d4d125a4/main.m3u8"
      controls
    />
  );
}
```

## 资源管理

两者均使用 FairPlay `fairplayLicenseUri` 财务报告和审定财务报表 `fairplayCertificateUri` 已经设定。 回放在Shaka MSE上(`streaming.useNativeHlsForFairPlay: false`) (中文(简体) ). 许可证申请是JSON `{ spc }` 和回应是JSON `{ ckc }`。 。 。 .

否则 `widevineLicenseUri` 配置 `com.widevine.alpha`。 。 。 . `widevineRobustness` 实值 `L1`, (中文(简体) ), `L2`, (中文(简体) ), `custom`,或为默认梯度省略. `organizationId` 财务报告和审定财务报表 `collectionId` 应用与嵌入式玩家相同的 org 覆盖 .

```javascript
<ReactHlsPlayer
  src={src}
  drm={{
    widevineLicenseUri: 'https://widevine.gumlet.com/licence/example',
    widevineRobustness: 'L1',
    organizationId: 'org-id',
    collectionId: 'collection-id',
    fairplayLicenseUri: 'https://fairplay.gumlet.com/licence/example',
    fairplayCertificateUri: 'https://fairplay.gumlet.com/certificate/example',
  }}
/>
```

当两个 FairPlay URI 都存在时, Widevine 不配置用于该负载.

## 透视

默认内视值( O)`enableInsights`) (中文(简体) ). 每个回放的URL在Shaka开始前都会被解析,包括解析出真知灼见后. `workspace_id` 是收藏的编号. `customVideoId` 资产编号,除非你通过 `insights.customVideoId`。 。 。 .

```javascript
<ReactHlsPlayer
  src="https://video.gumlet.io/collection-id/asset-id/main.m3u8"
  insights={{
    property_id: 'property-id',
    customVideoTitle: 'Episode 3',
    customData1: 'experiment-a',
    userId: 'viewer-1',
  }}
/>
```

`customPlayerName` 实值 `gumlet-react-hls-player` 财务报告和审定财务报表 `customPlayerVersion` 是这个软件包的版本。 这些不能被推翻. `workspace_id` 这不是道具.

`insights` 接受字段 `@gumlet/insights-js-core` 静态文档 : `property_id`, (中文(简体) ), `debug`, (中文(简体) ), `test`, (中文(简体) ), `page_url`, (中文(简体) ), `sessionID`, (中文(简体) ), `userID`, (中文(简体) ), `sendSessionRequest`, (中文(简体) ), `deviceData`, (中文(简体) ), `playerData`, (中文(简体) ), `disable_analytics_v2`, (中文(简体) ), `getUUID`, (中文(简体) ), `customData1` 结束 `customData10`视频字段`customVideoId`, (中文(简体) ), `customVideoTitle`, (中文(简体) ), `customVideoDurationMillis`, (中文(简体) ), `customVideoSeries`, (中文(简体) ), `customVideoProducer`, (中文(简体) ), `customVideoLanguage`, (中文(简体) ), `customVideoVariant`, (中文(简体) ), `customVideoVariantName`, (中文(简体) ), `customContentType`, (中文(简体) ), `customEncodingVariant`),用户字段(`userId`, (中文(简体) ), `userName`, (中文(简体) ), `userEMail` 或者说 `userEmail`, (中文(简体) ), `userPhone`, (中文(简体) ), `userProfileImage`,地址字段, `userCity`, (中文(简体) ), `userState`, (中文(简体) ), `userCountry`, (中文(简体) ), `userZipcode`),加 (中文(简体) ) `customPageType` 财务报告和审定财务报表 `experimentName`。 。 。 .

```javascript
<ReactHlsPlayer src={src} enableInsights={false} />
```

## 回放设置

每个负载都应用嵌入式玩家的Shaka设置:

-   带有3 Mbps 默认估计的 ABR 和网络信息 API 关闭
-   重复:6次尝试、1次基准延迟、30次超时
-   部分重试:6次尝试,500ms基延迟,20s超时
-   `rebufferingGoal: 4`, (中文(简体) ), `bufferingGoal: 20`
-   `manifest.disableText` 财务报告和审定财务报表 `StubTextDisplayer`,所以莎卡不会接管本土 `<track>` 标题

`startHighestRes` 保持ABR关闭时 `load()` 运行,然后选择最高的可播放变体。 一张相片 `aspectRatio` 例如 `9:16` 关机 `restrictToElementSize`。 。 。 .

`playerConfig` 是一个可选的部分 Shaka `PlayerConfiguration`。它首先应用。 嵌入设置和 DRM 之后被应用,所以这些值仍然有效.

```javascript
<ReactHlsPlayer
  src={src}
  aspectRatio="16:9"
  startHighestRes
  playerConfig={{ streaming: { bufferingGoal: 30 } }}
/>
```

致命 Shaka 错误( 严重性) `CRITICAL`(电话) `load(src)` 再来一次 `maxFatalRetries` (默认 3). DRM 代码 `6000–6010` 财务报告和审定财务报表 `3014–3016` 报告而不重审.

一个 `.m3u8` URL 负载 `shaka-player.hls.js`。一个 `.mpd` URL 负载 `shaka-player.dash.js`。 。 。 . `debug` 加载构建调试文件并将其日志级别设定为 DEBUG. 离开它为匹配的释放构建。 这是分开的 `insights.debug`。 。 。 .

```javascript
<ReactHlsPlayer src={src} debug />
```

## 道具

其它 [视频属性](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/video) 通过到 `<video>`时,除 `onPlay`, (中文(简体) ), `onPause`, (中文(简体) ), `onPlaying`, (中文(简体) ), `onWaiting`, (中文(简体) ), `onEnded`, (中文(简体) ), `onError`, (中文(简体) ), `onTimeUpdate`, (中文(简体) ), `onProgress`, (中文(简体) ), `onSeeked`,以及 `onVolumeChange`。这些是上面输入的回调.

| Prop | 说明 |
| --- | --- |
| `src` `string`页:1 | `/{collection_id}/{asset_id}/main.m3u8` 或者说 `main.mpd`任意主机 |
| `autoPlay` `boolean` | 打电话 `play()` 之后 `load()` 决定。 默认 `false` |
| `muted` `boolean` | 关闭前的元素 `play()` |
| `controls` `boolean` | 原地控制系统 默认 `false` |
| `loop`, (中文(简体) ), `playsInline`, (中文(简体) ), `poster`, (中文(简体) ), `preload`, (中文(简体) ), `crossOrigin`, (中文(简体) ), `width`, (中文(简体) ), `height` | 路过 `<video>` |
| `playerConfig` | 部分 Shaka 配置, 在嵌入设置前应用 |
| `playerRef` | 参考 `<video>` 元素(同节点为 `ref`(中文(简体) ) |
| `ref` | 这个 `<video>` 元素 |
| `getPlayerRef` | `(player: shaka.Player | null) => void` |
| `aspectRatio` `string` | 外观 `W:H` 或者说 `W/H` 禁用 ABR 软件 `restrictToElementSize` |
| `startHighestRes` `boolean` | 自动呼吸通过 `load()`,然后锁定最高的变体 |
| `drm` | `DrmConfig`: 宽宽和平平字段 |
| `enableInsights` `boolean` | 在 URL 解析后启动 Gumlet Insights 。 默认 `true` |
| `insights` | 已记录入洞见地. 工作空间 ID 和玩家名称/ 版本由此软件包设置 |
| `debug` `boolean` | 装入此列表的调试文件,并将Shaka的日志级别设置为 DEBUG. 默认 `false` |
| `maxFatalRetries` `number` | 在放弃之前 致命的重复 默认 `3` |
| `onReady` | `load()` 已解决 |
| `onPlay`, (中文(简体) ), `onPause`, (中文(简体) ), `onPlaying`, (中文(简体) ), `onEnded`, (中文(简体) ), `onWaiting` | 视频播放状态 |
| `onTimeUpdate` | `{ currentTime, duration }` |
| `onProgress` | `{ percent }` 从 `currentTime / duration` |
| `onSeeked` | `{ currentTime, duration }` |
| `onVolumeChange` | `{ volume, muted }` |
| `onManifestParsed` | 燃烧 `onReady` 何时 `load()` 决定 |
| `onQualityChange` | `{ level, height, bitrate }` 适应后 |
| `onError` | `{ fatal, source, data?, mediaError?, message? }` |

导出类型 : `HlsPlayerProps`, (中文(简体) ), `DrmConfig`, (中文(简体) ), `InsightsConfig`, (中文(简体) ), `AnalyticsConfig`, (中文(简体) ), `PlayerConfig`, (中文(简体) ), `TimeEventData`, (中文(简体) ), `ProgressEventData`, (中文(简体) ), `VolumeEventData`, (中文(简体) ), `QualityChangeData`, (中文(简体) ), `PlayerErrorData`。 。 。 .

## 维护者

这个图书馆由 [Gumlet.com (英语)](https://www.gumlet.com/)

[![](https://assets.gumlet.com/public/img/logo.png)](https://www.gumlet.com/)

## 常见问题

### @gumlet/react-hls-player 是什么？

使用 Shaka 播放器对 HLS 和 DASH 进行回放, 使用 Gumlet Widevine 和 FairPlay

### 如何安装 @gumlet/react-hls-player？

在项目目录运行 npm install @gumlet/react-hls-player，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（\>=18）、react-dom（\>=18）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @gumlet/react-hls-player 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @gumlet/react-hls-player 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @gumlet/react-hls-player 可以商用吗？

@gumlet/react-hls-player 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @gumlet/react-hls-player 的下载量有多少？

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

### @gumlet/react-hls-player 还在维护吗？

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

