视频播放器 Web 版

基于 TypeScript、xgplayer 和 hls.js 的 Web 视频播放器库，支持 HLS 播放、自定义主题色、播放控制、事件订阅和云端 V4～V10 Key 解密。

安装

pnpm install

库入口为 src/main.ts，构建产物输出到 dist/。

快速开始

import { VideoPlayer } from '@codeages/cloud-video-player-web'
import '@codeages/cloud-video-player-web/style.css'

const player = new VideoPlayer({
  id: 'video-player',
  themeColor: '#2563eb',
})

player.on('error', error => {
  console.error(error.code, error.message)
})

await player.play(playUrl, { autoplay: false })

playUrl 是业务接口返回的云播放信息地址。SDK 自动获取播放列表、Key 版本和清晰度，不接受直接媒体地址，也不需要调用方解析云接口。

挂载元素必须在创建播放器前存在：

<div style="height: 405px">
  <div id="video-player"></div>
</div>

配置

VideoPlayerConfig

| 参数 | 类型 | 说明 | | --- | --- | --- | | id | string | 播放器挂载元素 ID。 | | width | number \| string | 默认 '100%'；数字表示像素，字符串支持 CSS 尺寸（包括百分比）。 | | height | number \| string | 默认 '100%'；数字表示像素，使用百分比时父容器必须有明确高度。 | | fullscreen | boolean | 默认 true；设为 false 关闭普通全屏按钮和双击画面全屏。 | | cssFullscreen | boolean | 默认 true；独立控制网页全屏。 | | themeColor | string | 可选主题色，支持浏览器可识别的具体 CSS 颜色。 | | playbackRates | number[] | 默认 [2, 1.5, 1.25, 1, 0.5]，初始倍速为 1。必须非空、包含 1，各项为不重复的正有限数，否则抛出 TypeError。 |

非法颜色、空字符串、var()、currentColor 和依赖外部上下文的颜色会抛出 TypeError。

以上配置仅在创建实例时设置，切换播放资源时保留，不提供运行时修改接口。 默认尺寸由原先的 600 × 337.5 改为填满父容器；旧页面需要为父容器提供明确高度， 或显式传入 width: 600, height: 337.5 保持原尺寸。

后台嵌入示例（父容器需有明确高度）：

const player = new VideoPlayer({
  id: 'video-player',
  width: '100%',
  height: '100%',
  fullscreen: false,
  cssFullscreen: false,
})

PlayOptions

| 参数 | 类型 | 默认值 | 说明 | | --- | --- | --- | --- | | autoplay | boolean | true | 加载新资源后是否自动播放。 |

清晰度与倍速

SDK 通过 JSONP 请求 playUrl，再请求播放列表的 json=1 接口获取清晰度。 清晰度保持云接口返回顺序，第一项作为默认清晰度。列表不足两项时 xgplayer 隐藏菜单，合法空列表使用原播放列表；请求失败或非法数据会明确报错。

清晰度和倍速使用 xgplayer 原生菜单，不提供 selectQuality() 或底层播放器对象。清晰度选择、URL 切换、菜单状态以及切换期间的位置和播放状态处理遵循 xgplayer 原生行为。 加载新资源重置位置、清晰度列表和 Key 版本，同一实例保留用户的倍速、音量及静音选择。

控制栏与纯音频

视频播放时约 3 秒无操作隐藏控制栏，鼠标移动、暂停和结束时显示，菜单展开期间保持显示。 每次加载通过 controlsvisibilitychange 通知初始可见状态，之后仅在实际显隐改变时通知。 HLS 轨道信息明确表示只有音频时，保持控制栏显示；无法可靠识别时沿用默认行为。无需传入 mediaType。 纯音频沿用相同播放链路和默认控件；清晰度菜单取决于云接口返回的列表。 学习上报、完成规则、断点存储和业务弹窗由调用方负责。

播放控制

| 方法 | 说明 | | --- | --- | | play(playUrl?, options?) | 传入云播放信息地址时从零加载新资源；省略或空字符串时继续播放。 | | pause() | 暂停并保留当前进度。 | | stop() | 暂停并归零，取消待完成操作；云请求被取消后，play() 从零重新加载当前资源。 | | seek(seconds) | 跳转到非负秒数；无资源或参数越界时抛出错误。 | | destroy() | 同步销毁实例并释放资源；重复调用安全返回，销毁后不可复用。 | | on(event, handler) | 持续订阅事件，返回取消订阅函数。 | | once(event, handler) | 订阅一次事件，返回取消订阅函数。 | | off(event, handler) | 取消指定订阅。 |

浏览器可能因自动播放策略拒绝 play()，调用方应处理 Promise 拒绝：

try {
  await player.play()
} catch (error) {
  // 提示用户手动播放或重试
}

play(playUrl) 在两阶段云请求、播放保护通过并发起媒体加载后完成，实际就绪由 canplay 通知。 云请求每次超时为 10 秒；失败时 Promise 拒绝并发出 fatal CLOUD_LOAD_ERROR（source: 'cloud'）。 加载期间的 pause() 和 seek() 保留最新意图；停止、切换资源或销毁以 AbortError 取消旧请求。

事件

状态事件包括：play、playing、pause、stop、ended、loadedmetadata、canplay、waiting、timeupdate、durationchange、seeking 和 seeked。

这些事件返回：

interface VideoPlayerState {
  currentTime: number
  duration: number | null
  paused: boolean
  ended: boolean
}

error 事件返回 VideoPlayerError，通过 source、code、message 和 fatal 区分云接口、媒体、HLS 或播放保护错误。

| 事件 | 载荷 | | --- | --- | | ratechange | { playbackRate: number }，实际媒体倍速变化。 | | controlsvisibilitychange | { visible: boolean }，控制栏实际显隐。 |

destroy 事件无数据，每个实例仅通知一次，随后自动清理所有订阅：

player.on('destroy', () => {
  // 实例已不可用
})
player.destroy()

公开 destroy() 在底层销毁调用结束后、返回前通知。底层主动销毁或销毁抛错时也会通知， 但不保证通知时 DOM 已全部清理；底层销毁异常原样抛出。销毁监听器异常被隔离。 销毁会取消待执行定位和播放检测，检测中的 play() 以 AbortError 拒绝。 销毁后 play() 拒绝、seek() 抛错，pause()、stop() 和新增订阅为空操作。

播放限制

• 支持 hls.js 时优先使用 hls.js，否则回退到浏览器原生 HLS。
• 构建目标为 Chrome 69+ 和 Safari 13+。
• 加载新资源前会检测已知下载扩展和 SourceBuffer 覆盖；命中时拒绝播放。
• 云播放接口必须支持 JSONP；SDK 自动取得 Key 版本，仅支持原生 HLS 的浏览器无法解密自定义 21 字节 Key。
• 这是不兼容的接口重构：旧的直接媒体地址及手工清晰度、Key 参数已移除，调用方改传业务接口返回的 playUrl。

开发

本地演示需要在 .env.local 配置 PLAY_INFO_AUTHORIZATION，不要提交真实令牌。

pnpm dev      # 启动演示页
pnpm test     # 运行单元测试
pnpm test:browser # 本地视频、音频和加密 HLS 的真实浏览器回归
pnpm build    # 类型检查并构建库与声明文件
pnpm preview  # 预览构建结果

演示页只从业务接口取得 playUrl，然后调用 player.play(playUrl, { autoplay: false })，与 LMS 接入方式一致。 可用 /?playUrl=... 指定其他云播放信息地址。视频和纯音频使用相同入口。 地址含查询参数时需 URL 编码；不要在文档、截图或提交内容中保存授权地址。

浏览器回归需要 Node.js 22.18+、FFmpeg 和 Chrome，或运行 pnpm exec playwright install chromium 安装测试浏览器。 可用 CHROME_PATH 指定 Chrome 路径。测试会生成并清理临时媒体，截图输出到被 Git 忽略的 .browser-results/。 运行 pnpm exec playwright install webkit 后，可用 BROWSER=webkit pnpm test:browser 回归 WebKit；这不替代真实 Safari 的版本验收。 真实云端演示回归使用 CLOUD_DEMO_URL=http://127.0.0.1:5173 pnpm test:cloud，要求该地址已启动开发服务器且授权有效。

源码按职责组织：player/ 提供公开门面，playback/ 统一协调播放操作，cloud/ 解析资源， adapters/xgplayer/ 隔离底层实例，plugins/hls/ 管理流与解密，protection/ 和 ui/ 分别处理检测与交互。 公开入口和调用方式不变；内部模块不作为包导出。