@gumlet/react-hls-player

中文文档
3.0.0发布于 2026/10/27MITTypeScriptCommonJS构建来源已验证近 30 天下载 7293

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

中文使用文档
文档目录9 节
  1. 演示
  2. 基本重播
  3. 回电
  4. 视频元素和 Shaka 实例
  5. 资源管理
  6. 透视
  7. 回放设置
  8. 道具
  9. 维护者

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

npm version npm downloads

反应组件用于 HLS 和 DASH 数据交换 现场直播和现场直播 回放用途 沙卡玩家 5.1 与 Gumlet 嵌入式玩家相同 ABR, 重试, 并缓冲设置 。 Widevine和FairPlay使用Gumlet的许可证助手.

npm i @gumlet/react-hls-player

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

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

演示

npm start

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

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

基本重播

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* 道具而不是视频元素上的收听器. 每次渲染上的新函数身份不会重建玩家.

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

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 覆盖 .

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

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

<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 之后被应用,所以这些值仍然有效.

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

<ReactHlsPlayer src={src} debug />

道具

其它 视频属性 通过到 <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(),然后锁定最高的变体
drmDrmConfig: 宽宽和平平字段
enableInsights boolean在 URL 解析后启动 Gumlet Insights 。 默认 true
insights已记录入洞见地. 工作空间 ID 和玩家名称/ 版本由此软件包设置
debug boolean装入此列表的调试文件,并将Shaka的日志级别设置为 DEBUG. 默认 false
maxFatalRetries number在放弃之前 致命的重复 默认 3
onReadyload() 已解决
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 (英语)

版本与发布记录

@gumlet/react-hls-player 共发布 5 个版本,首次发布于 2022/11/19;过去 12 个月发布了 3 个版本。最新版本附带 npm provenance 构建来源证明,可追溯到公开的 CI 构建记录。

版本发布日期距今
3.0.0latest2026/10/2720 天前
2.0.12026/10/2027 天前
2.0.02026/09/281 个月前
1.0.12022/11/233 年前
1.0.02022/11/193 年前

关于 @gumlet/react-hls-player 的常见问题

@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 和提交记录判断。