thunder-hw-player

v2.1.4

Published

3 months ago

Thunder HW Player - A WebAssembly-based H.264 hardware-accelerated video player for web browsers

0High
0Medium
0Low

yuezheng2006

video-player h264 avc wasm webassembly ffmpeg webgl web-audio typescript video-streaming ts-player ls-player mls-player

Thunder HW Player

基于 WebAssembly 的 H.264 硬件加速网页视频播放器

Thunder HW Player 是一款高性能的网页视频播放器，使用 WebAssembly 技术实现 H.264 视频解码，支持硬件加速渲染。

特性

✅ H.264 (AVC) 视频解码 - 基于 FFmpeg + WebAssembly
✅ WebGL 硬件加速渲染 - YUV 到 RGB 实时转换
✅ Web Workers 多线程架构 - 解码和下载并行处理
✅ AAC/MP3 音频支持 - Web Audio API 播放
✅ TypeScript 完整支持 - 提供完整类型定义
✅ 事件驱动 API - 灵活的事件监听机制
✅ ESM + CommonJS 双模式支持 - 兼容 Vue 2/3、Vite、Webpack

安装

npm install thunder-hw-player

快速开始

Vue 3 + Vite (ESM)

import ThunderPlayer from 'thunder-hw-player'

// 1. 创建播放器实例
const player = new ThunderPlayer()

// 2. 初始化 SDK
await player.init({
  appid: 'your-app-id',
  sk: 'your-secret-key'
})

// 3. 设置 Canvas 元素
const canvas = document.getElementById('video-canvas')
player.setCanvas(canvas)

// 4. 播放视频
player.play('https://example.com/video.ts')

// 5. 监听事件
player.on('timeupdate', (data) => {
  console.log(`播放进度: ${data.progress}%`)
})

Vue 2 + Vue CLI / Webpack (CommonJS)

// ⚠️ Vue 2 + Webpack 用户必须先配置 SDK 路径
const { ThunderPlayer, configureSdk } = require('thunder-hw-player')

// 1. 配置 SDK 路径（必须在使用前调用）
configureSdk({
  sdkBasePath: '/sdk/js/',  // SDK 文件的访问路径
  enableDebug: true
})

// 2. 创建播放器实例
const player = new ThunderPlayer()

// 3. 初始化 SDK
await player.init({
  appid: 'your-app-id',
  sk: 'your-secret-key'
})

// 4. 设置 Canvas 并播放
player.setCanvas(canvas)
player.play('https://example.com/video.ts')

Vue 2 + Webpack 额外步骤：

将 node_modules/thunder-hw-player/js/ 目录复制到 public/sdk/js/
配置 vue.config.js 添加 COOP/COEP 响应头

详见 Vue 2 集成指南

API

初始化

`player.init(config)`

await player.init({
  appid: string,      // 必需：应用ID
  sk: string,         // 必需：密钥
  authServer?: string // 可选：认证服务器
})

Canvas 设置

`player.setCanvas(canvas)`

设置 Canvas 元素（必须在播放前调用）

player.setCanvas(canvas: HTMLCanvasElement)

播放控制

`player.play(url)`

播放视频

player.play(url: string)
// 必须先调用 setCanvas() 设置 Canvas

`player.pause()`

暂停播放

`player.resume()`

继续播放

`player.stop()`

停止播放

await player.stop()

`player.seekTo(time)`

跳转到指定时间

player.seekTo(timeMs: number) // 毫秒

音量控制

`player.setVolume(volume)`

设置音量

player.setVolume(0.8) // 0.0 - 1.0

`player.getVolume()`

获取音量

const volume = player.getVolume() // 返回 0.0 - 1.0

播放速度

`player.setPlaybackSpeed(speed)`

设置播放速度

player.setPlaybackSpeed(1.5) // 0.1 - 10.0

`player.getPlaybackSpeed()`

获取播放速度

const speed = player.getPlaybackSpeed()

状态获取

`player.getState()`

获取播放器状态

const state = player.getState()
// 0: Idle
// 1: Playing
// 2: Paused
// 3: Seeking
// 4: Cleaning

`player.getCurrentTime()`

获取当前播放时间（秒）

`player.getDuration()`

获取视频总时长（秒）

`player.getProgress()`

获取播放进度（0.0 - 1.0）

`player.getCurrentFps()`

获取当前帧率

`player.getMediaInfo()`

获取完整媒体信息

const info = player.getMediaInfo()
// {
//   duration: number
//   currentTime: number
//   progress: number
//   video: { width, height, codec, pixelFormat }
//   audio: { codec, channels, sampleRate }
//   state: string
//   bufferInfo: { audioFrames, videoFrames, bufferTime }
// }

事件监听

`player.on(event, callback)`

注册事件监听

player.on('timeupdate', (data) => {
  console.log(data.currentTime, data.duration, data.progress)
})

player.on('loadedmetadata', (data) => {
  console.log(data.video, data.audio, data.duration)
})

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

支持的事件

play - 开始播放
pause - 暂停
resume - 恢复播放
stop - 停止
ended - 播放结束
timeupdate - 时间更新
loadedmetadata - 元数据加载完成
error - 错误
statechange - 状态变化

`player.off(event, callback)`

移除事件监听

player.off('timeupdate', callback)
player.off('timeupdate') // 移除所有该事件的监听器

资源释放

`player.destroy()`

销毁播放器，释放所有资源

player.destroy()

支持格式

| 类型 | 格式 | |------|------| | 视频编码 | H.264 (AVC) | | 音频编码 | AAC, MP3 | | 容器格式 | MPEG-TS (.ts), Lightning Stream (.ls, .uls, .mls) |

浏览器要求

| 浏览器 | 最低版本 | 说明 | |--------|----------|------| | Chrome | 91+ | ✅ 推荐 | | Edge | 91+ | ✅ 推荐 | | Firefox | 89+ | ✅ 支持 | | Safari | 15+ | ✅ 支持 |

环境要求:

✅ HTTPS 或 localhost 环境
✅ 支持 WebAssembly
✅ 支持 SharedArrayBuffer（需要 COOP/COEP 头部）

服务器配置:

# Nginx 示例
add_header Cross-Origin-Opener-Policy same-origin;
add_header Cross-Origin-Embedder-Policy require-corp;

Vue 2 + Webpack 集成

⚠️ Vue 2 + Webpack 环境需要额外配置，因为 Web Worker 文件必须通过 HTTP 路径访问。

步骤 1: 复制 SDK 文件

cp -r node_modules/thunder-hw-player/js public/sdk/

或在 package.json 中添加自动化脚本：

{
  "scripts": {
    "postinstall": "cp -r node_modules/thunder-hw-player/js public/sdk/"
  }
}

步骤 2: 配置响应头

// vue.config.js
module.exports = {
  devServer: {
    headers: {
      'Cross-Origin-Opener-Policy': 'same-origin',
      'Cross-Origin-Embedder-Policy': 'require-corp'
    }
  }
}

步骤 3: 使用 SDK

// main.js
const { ThunderPlayer, configureSdk } = require('thunder-hw-player')

configureSdk({ sdkBasePath: '/sdk/js/' })

<template>
  <canvas ref="canvas" width="1280" height="720"></canvas>
</template>

<script>
const { ThunderPlayer } = require('thunder-hw-player')

export default {
  data() {
    return { player: null }
  },
  async mounted() {
    this.player = new ThunderPlayer()
    await this.player.init({ appid: 'your-app-id', sk: 'your-sk' })
    this.player.setCanvas(this.$refs.canvas)
    this.player.play('https://example.com/video.ts')
  },
  beforeDestroy() {
    this.player?.destroy()
  }
}
</script>

版本历史

v2.1.4 (2025-12-03)

🐛 修复 getCurrentTime() 返回 0 的问题 - 底层播放器的获取时间方法是 getAudioPts()，不是 getSyncClockTime()
📦 同步最新 player 源码和 WASM 模块

v2.1.3 (2025-11-27)

📚 简化 Vue 2 集成文档，更易理解

v2.1.2 (2025-11-27)

📚 更新文档版本历史

v2.1.1 (2025-11-27)

🐛 尝试修复 getCurrentTime() 方法（但调用了不存在的 getSyncClockTime()，问题未解决）
🔧 优化 SDK 路径修复脚本，确保 Worker 文件正确加载
📦 同步最新 player 源码和 WASM 模块

v2.1.0 (2025-11-27)

✨ 新增 CommonJS 支持 - 兼容 Vue 2 + Webpack 环境
✨ 新增 configureSdk({ sdkBasePath }) 配置项
✨ 支持 window.THUNDER_SDK_PATH 全局配置
📦 package.json 添加 exports 字段，支持条件导出
📚 新增 Vue 2 集成文档

v2.0.0 (2025-01-14)

💥 Breaking Change: 移除 play() 方法的 canvas 参数
✨ 新增 setCanvas() 方法，必须在播放前调用
✅ API 更简洁明确，职责分离

v1.1.0

✨ 新增 setCanvas() API
✅ play() 的 canvas 参数改为可选

v1.0.x

🎉 首次发布
✅ H.264 视频解码
✅ WebGL 硬件加速
✅ 完整的 TypeScript 支持

常见问题

Q: 如何处理 SharedArrayBuffer 错误？

A: 确保服务器设置了正确的 COOP/COEP 头部（见上文"服务器配置"）

Q: 支持哪些视频格式？

A: 仅支持 H.264 编码的视频，容器格式支持 MPEG-TS 和 Lightning Stream

Q: 如何获取完整文档？

A: 查看完整 API 文档

模块格式

| 格式 | 入口文件 | 适用环境 | |------|---------|---------| | ESM | index.js | Vue 3 + Vite, 现代浏览器 | | CommonJS | index.cjs.js | Vue 2 + Webpack, Node.js |

npm 会根据你的环境自动选择正确的入口文件。

技术支持

npm: https://www.npmjs.com/package/thunder-hw-player
版本: 2.1.3
许可证: ISC

许可证

ISC License

Made with ❤️ by Thunder Player Team

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme