thunder-player-sdk

v1.0.2

Published

4 months ago

Thunder Player SDK - A WebAssembly-based H.264 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 Player SDK

基于 WebAssembly 的 H.264 网页视频播放器 SDK

Thunder Player SDK 是一款高性能的网页视频播放器，使用 WebAssembly 技术实现 H.264 视频解码，支持 .ts、.ls、.uls、.mls 等多种视频格式。

特性

✅ H.264 解码: 基于 FFmpeg + WebAssembly 实现高性能视频解码
✅ 硬件加速: 使用 WebGL 进行 YUV 到 RGB 转换和渲染
✅ 低延迟: Web Workers 多线程架构，解码和渲染互不阻塞
✅ 音频支持: 支持 AAC、MP3 音频格式，使用 Web Audio API 播放
✅ TypeScript: 完整的 TypeScript 类型定义
✅ 事件驱动: 丰富的事件系统，支持播放状态、进度、错误等事件
✅ 认证加密: 支持自定义认证服务器和加密视频流

安装

方式一: npm 安装（推荐）

npm install thunder-player-sdk

方式二: 直接引用

将 SDK 文件复制到项目的 public 目录，然后在 HTML 中引入：

<script src="/sdk/js/common.js"></script>
<script src="/sdk/js/webgl.js"></script>
<script src="/sdk/js/pcm-player.js"></script>
<script src="/sdk/js/http_bridge.js"></script>
<script src="/sdk/js/thunder_module.js"></script>
<script src="/sdk/js/player.js"></script>

快速开始

使用 npm 包（现代构建工具）

import { loadThunderSDK } from 'thunder-player-sdk';

// 1. 加载 SDK
const Player = await loadThunderSDK({
  sdkPath: '/node_modules/thunder-player-sdk/js/',
  enableDebug: true
});

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

// 3. 初始化 SDK（必需）
await player.initSDK({
  appid: 'your-app-id',
  sdk_sn: 'your-sdk-sn',
  authServer: 'https://your-auth-server.com'
});

// 4. 播放视频
const canvas = document.getElementById('video-canvas') as HTMLCanvasElement;
player.play('https://example.com/video.ts', canvas);

// 5. 监听事件
player.on('timeupdate', (data) => {
  console.log(`当前播放时间: ${data.currentTime}秒`);
});

player.on('error', (error) => {
  console.error('播放错误:', error.message);
});

使用传统 script 标签

<!DOCTYPE html>
<html>
<head>
  <title>Thunder Player Demo</title>
</head>
<body>
  <canvas id="video-canvas" width="1920" height="1080"></canvas>

  <!-- 加载 SDK 文件 -->
  <script>
    var Module = {};
    Module.scriptDirectory = '/sdk/js/';
    Module.locateFile = function(path) {
      return '/sdk/js/' + path.split('/').pop();
    };
  </script>
  <script src="/sdk/js/common.js"></script>
  <script src="/sdk/js/webgl.js"></script>
  <script src="/sdk/js/pcm-player.js"></script>
  <script src="/sdk/js/http_bridge.js"></script>
  <script src="/sdk/js/thunder_module.js"></script>
  <script src="/sdk/js/player.js"></script>

  <!-- 使用播放器 -->
  <script>
    const player = new Player();

    player.initSDK({
      appid: 'your-app-id',
      sdk_sn: 'your-sdk-sn',
      authServer: 'https://your-auth-server.com'
    }).then(() => {
      const canvas = document.getElementById('video-canvas');
      player.play('https://example.com/video.ts', canvas);
    });
  </script>
</body>
</html>

API 文档

初始化

`loadThunderSDK(config)`

动态加载 SDK（仅限 npm 包方式）

interface ThunderSDKConfig {
  sdkPath?: string;        // SDK 文件路径，默认 '/sdk/js/'
  enableDebug?: boolean;   // 启用调试日志，默认 false
  authServer?: string;     // 认证服务器地址（可选）
}

const Player = await loadThunderSDK({
  sdkPath: '/node_modules/thunder-player-sdk/js/',
  enableDebug: true
});

`player.initSDK(authParams)`

初始化 SDK 认证（必须在播放前调用）

interface SDKAuthParams {
  appid: string;           // 应用 ID（必需）
  sdk_sn: string;          // SDK 序列号（必需）
  uid?: string;            // 用户 ID（可选）
  authServer?: string;     // 认证服务器地址（可选）
}

await player.initSDK({
  appid: 'your-app-id',
  sdk_sn: 'your-sdk-sn',
  uid: 'user-123',
  authServer: 'https://your-auth-server.com'
});

播放控制

// 播放视频
player.play(url: string, canvas: HTMLCanvasElement): PlayResult;

// 暂停
player.pause(): void;

// 恢复播放
player.resume(): void;

// 停止
player.stop(): Promise<void>;

// 跳转到指定时间（毫秒）
player.seekTo(timeMs: number): void;

音量和速度

// 设置音量 (0.0 - 1.0)
player.setVolume(0.8);

// 获取音量
const volume = player.getVolume();

// 设置播放速度 (0.1 - 10.0)
player.setPlaybackSpeed(1.5);

// 获取播放速度
const speed = player.getPlaybackSpeed();

获取状态

// 获取播放状态
const state = player.getState(); // PlayerState enum

// 获取当前时间（秒）
const currentTime = player.getCurrentTime();

// 获取总时长（秒）
const duration = player.getDuration();

// 获取播放进度 (0.0 - 1.0)
const progress = player.getProgress();

// 获取下载进度 (0.0 - 1.0)
const downloadProgress = player.getDownloadProgress();

// 获取完整媒体信息
const mediaInfo = player.getMediaInfo();

// 获取缓冲区信息
const bufferInfo = player.getBufferInfo();

// 获取当前 FPS
const fps = player.getCurrentFps();

事件监听

// 监听事件
player.on('play', () => {
  console.log('开始播放');
});

player.on('pause', () => {
  console.log('暂停播放');
});

player.on('timeupdate', (data) => {
  console.log(`播放进度: ${data.progress}%`);
});

player.on('loadedmetadata', (data) => {
  console.log('视频信息:', data.video);
  console.log('音频信息:', data.audio);
});

player.on('error', (error) => {
  console.error('播放错误:', error.message);
});

// 移除事件监听
player.off('timeupdate', callback);

支持的事件

| 事件名 | 说明 | 数据类型 | |--------|------|----------| | play | 开始播放 | {} | | pause | 暂停 | {} | | resume | 恢复播放 | {} | | stop | 停止 | {} | | ended | 播放结束 | {} | | timeupdate | 时间更新 | { currentTime, duration, progress } | | loadedmetadata | 元数据加载完成 | { video, audio, duration } | | loadingstart | 开始加载 | {} | | loadingend | 加载结束 | {} | | error | 错误 | { code, message, details } | | statechange | 状态变化 | { state } |

资源管理

// 销毁播放器，释放资源
player.destroy();

配置代理服务器

SDK 需要认证服务器来处理加密视频流。为了避免 CORS 问题，建议配置本地代理。

Vite 配置示例

// vite.config.js
export default defineConfig({
  server: {
    proxy: {
      '/wauth': {
        target: 'https://your-auth-server.com',
        changeOrigin: true,
        secure: false
      }
    }
  }
});

Webpack 配置示例

// webpack.config.js
module.exports = {
  devServer: {
    proxy: {
      '/wauth': {
        target: 'https://your-auth-server.com',
        changeOrigin: true,
        secure: false
      }
    }
  }
};

支持的格式

视频格式

H.264 (AVC)

音频格式

容器格式

.ts - MPEG-TS 流
.ls - Lightning Stream
.uls - Ultra Lightning Stream
.mls - Multi Lightning Stream

浏览器兼容性

| 浏览器 | 最低版本 | |--------|----------| | Chrome | 87+ | | Firefox | 78+ | | Safari | 14+ | | Edge | 87+ |

要求:

WebAssembly 支持
Web Workers
WebGL 2.0
Web Audio API
SharedArrayBuffer (需要 HTTPS + COOP/COEP 头部)

HTTPS 和安全头部

SDK 使用 SharedArrayBuffer，需要设置以下 HTTP 头部：

Cross-Origin-Opener-Policy: same-origin
Cross-Origin-Embedder-Policy: require-corp

Vite 配置

export default defineConfig({
  server: {
    headers: {
      'Cross-Origin-Opener-Policy': 'same-origin',
      'Cross-Origin-Embedder-Policy': 'require-corp'
    }
  }
});

Nginx 配置

add_header Cross-Origin-Opener-Policy "same-origin";
add_header Cross-Origin-Embedder-Policy "require-corp";

常见问题

1. SDK 加载失败

问题: 控制台显示 "加载失败: /sdk/js/xxx.js"

解决:

确认 SDK 文件路径正确
检查 sdkPath 配置是否正确
确保文件可以通过 HTTP 访问（不能是 file:// 协议）

2. WASM 模块加载失败

问题: "Could not load WASM module"

解决:

确保 thunder_module.wasm 文件存在
配置正确的 Module.locateFile 函数
确保服务器返回正确的 MIME 类型 application/wasm

3. SharedArrayBuffer 不可用

问题: "SharedArrayBuffer is not defined"

解决:

使用 HTTPS 协议
设置 COOP/COEP 头部
检查浏览器是否支持 SharedArrayBuffer

4. 认证失败

问题: HTTP 401 认证错误

解决:

确认 appid 和 sdk_sn 正确
检查认证服务器地址
配置代理服务器避免 CORS

TypeScript 支持

SDK 提供完整的 TypeScript 类型定义：

import {
  loadThunderSDK,
  Player,
  PlayerState,
  SDKAuthParams,
  MediaInfo
} from 'thunder-player-sdk';

const Player = await loadThunderSDK();
const player: Player = new Player();

许可证

ISC License

技术支持

项目地址: https://g.ktvsky.com/architecture/thunderwebplayer
问题反馈: https://g.ktvsky.com/architecture/thunderwebplayer/issues