@taole/giftstage 0.1.4

package/README.md

@@ -0,0 +1,458 @@
+# GiftStage
+
+统一的 Web 礼物播放框架，支持：
+
+- `SVGA`
+- `VAP / VAPX`
+- 透明视频 `AlphaVideo`
+
+底层支持：
+
+- `WebGPU`
+- `WebGL2`
+- `WebGL1` 兼容兜底
+
+适用场景：
+
+- 直播间礼物
+- 大批同屏动画
+- 需要统一接入 `SVGA / VAP / 透明视频` 的业务场景
+
+## npm 包信息
+
+- 包名：`@taole/giftstage`
+- npm：`npm i @taole/giftstage`
+- ESM 导入：
+
+```ts
+import { GiftStage } from '@taole/giftstage';
+```
+
+- CommonJS 导入：
+
+```js
+const { GiftStage } = require('@taole/giftstage');
+```
+
+## 特性
+
+- 统一 API：`addGift()` 即可播放三类礼物
+- `SVGA` 支持 Worker 解析、atlas 缓存、slot 替换
+- `VAP / AlphaVideo` 支持实验性的 `WebCodecs` 和稳定的 `HTMLVideoElement` 双路径
+- 同源视频播放实例、纹理、资源复用
+- 内存 LRU 缓存，默认 `128MB`
+- `IndexedDB` 磁盘 LRU 缓存，默认 `2048MB`
+- `x / y` 支持百分比定位
+- `width / height` 支持按礼物原始尺寸自动补全
+
+## 安装
+
+```bash
+npm install
+```
+
+安装发布包：
+
+```bash
+npm i @taole/giftstage
+```
+
+## 开发
+
+```bash
+npm run dev
+```
+
+## 构建
+
+```bash
+npm run build
+```
+
+Demo 构建：
+
+```bash
+npm run build:demo
+```
+
+## 快速开始
+
+```ts
+import { GiftStage } from '@taole/giftstage';
+
+const container = document.getElementById('app')!;
+
+const stage = new GiftStage({
+  container,
+  preferWebGPU: true,
+});
+
+await stage.ready;
+
+await stage.addGift({
+  type: 'svga',
+  source: 'https://example.com/demo.svga',
+  x: 100,
+  y: 100,
+  loop: 0,
+});
+```
+
+## 核心 API
+
+### `new GiftStage(options)`
+
+创建礼物舞台。
+
+常用配置：
+
+- `container: HTMLElement`
+  挂载容器。
+
+- `resolution?: number`
+  指定 canvas backing store 分辨率倍率。默认跟随 `devicePixelRatio`。
+
+- `antialias?: boolean`
+  是否开启抗锯齿。
+
+- `preferWebGPU?: boolean`
+  是否优先使用 `WebGPU`。
+
+- `forceWebGL1?: boolean`
+  强制走 `WebGL1`，用于兼容性验证。
+
+- `preferWebCodecs?: boolean`
+  实验性特性。默认关闭；显式传 `true` 时才会尝试用 `WebCodecs` 播放 `VAP / AlphaVideo`。
+
+- `shareIdenticalVideoPlayback?: boolean`
+  是否复用近同时起播的同源视频播放实例。默认开启。
+
+- `sharedVideoPlaybackWindowMs?: number`
+  同源视频共享播放窗口，默认 `100ms`。
+
+- `webCodecsVideoAtlas?: { width: number; height: number }`
+  实验性 `WebCodecs` 视频共享 atlas 配置。
+
+- `webCodecsDecodeInWorker?: boolean`
+  实验性 `WebCodecs` 选项，控制是否在 Worker 中执行解码。
+
+- `webCodecsMaxDecodedFrames?: number`
+  实验性 `WebCodecs` 选项，控制保留的最大解码帧数。
+
+- `webCodecsDecodeAheadFrames?: number`
+  实验性 `WebCodecs` 选项，控制前向解码帧数。
+
+- `svgaParseInWorker?: boolean`
+  是否在 Worker 中解析 SVGA。
+
+- `maxConcurrentParse?: number`
+  资源下载 / 解析 / 图像解码的并发数。
+  不传时自动跟随 `navigator.hardwareConcurrency`。
+
+- `onError?: (error: Error) => void`
+  统一错误回调。
+
+### `await stage.ready`
+
+等待底层后端和运行环境初始化完成。建议在第一次 `addGift()` 前等待。
+
+### `stage.addGift(options)`
+
+插入一个礼物，返回：
+
+```ts
+Promise<GiftHandle>
+```
+
+### `stage.removeGift(id)`
+
+按 ID 移除礼物。
+
+### `stage.removeAll()`
+
+移除全部礼物。
+
+### `stage.pause()`
+
+暂停舞台。
+
+### `stage.resume()`
+
+恢复舞台。
+
+### `stage.destroy()`
+
+销毁舞台并释放资源。
+
+## `addGift()` 参数
+
+### 通用参数
+
+- `type: 'svga' | 'vap' | 'alphaVideo'`
+- `source: string | ArrayBuffer`
+- `x: number | \`${number}%\``
+- `y: number | \`${number}%\``
+- `width?: number`
+- `height?: number`
+- `objectFit?: 'contain' | 'fill'`
+- `loop?: number`
+  - `0` 表示无限循环
+- `mute?: boolean`
+- `onComplete?: (gift) => void`
+
+飞行动画相关：
+
+- `flyTo?: { x: number; y: number }`
+- `scaleTo?: number`
+- `flyDuration?: number`
+- `easing?: (t: number) => number`
+- `onFlyComplete?: (gift) => void`
+
+### 宽高默认行为
+
+`width / height` 现在是可选参数，规则如下：
+
+- 两个都传：按传入值显示
+- 只传 `width`：`height` 按礼物原始宽高比自动补全
+- 只传 `height`：`width` 按礼物原始宽高比自动补全
+- 两个都不传：默认使用礼物原始宽高
+- 如果两个都不传，且礼物原始宽高大于当前画布，则会按画布尺寸等比缩小后再显示
+
+例如：
+
+```ts
+await stage.addGift({
+  type: 'svga',
+  source: 'https://example.com/demo.svga',
+  x: '50%',
+  y: '50%',
+  loop: 0,
+});
+```
+
+这时会使用该礼物的原始尺寸；如果原始尺寸超出舞台，则自动缩放到舞台内。
+
+### 百分比坐标
+
+`x / y` 支持百分比，例如：
+
+```ts
+await stage.addGift({
+  type: 'svga',
+  source: 'https://example.com/demo.svga',
+  x: '50%',
+  y: '50%',
+  width: 300,
+  height: 300,
+  loop: 0,
+});
+```
+
+语义是：
+
+- `x: '50%'` 按容器宽度的 `50%` 定位，并减去自身一半宽度
+- `y: '50%'` 按容器高度的 `50%` 定位，并减去自身一半高度
+
+也就是接近：
+
+```css
+left: 50%;
+top: 50%;
+transform: translate(-50%, -50%);
+```
+
+如果是数值，则继续按原来的像素坐标语义处理。
+
+## 三类礼物示例
+
+### 播放 SVGA
+
+```ts
+await stage.addGift({
+  type: 'svga',
+  source: 'https://example.com/demo.svga',
+  x: 20,
+  y: 20,
+  width: 300,
+  height: 300,
+  loop: 1,
+});
+```
+
+### 播放 VAP
+
+```ts
+await stage.addGift({
+  type: 'vap',
+  source: 'https://example.com/demo.mp4',
+  config: 'https://example.com/demo.json',
+  x: 20,
+  y: 20,
+  width: 400,
+  height: 220,
+  loop: 0,
+});
+```
+
+### 播放透明视频
+
+```ts
+await stage.addGift({
+  type: 'alphaVideo',
+  source: 'https://example.com/demo.mp4',
+  x: 20,
+  y: 20,
+  width: 400,
+  height: 220,
+  loop: 0,
+});
+```
+
+## Slot 替换
+
+### SVGA
+
+使用 `svgaSlots`：
+
+```ts
+await stage.addGift({
+  type: 'svga',
+  source: 'https://example.com/demo.svga',
+  x: 0,
+  y: 0,
+  width: 400,
+  height: 400,
+  svgaSlots: {
+    avatar: { image: avatarImage },
+    title: {
+      text: 'Hello',
+      color: '#ff0000',
+      mode: 'dynamic',
+    },
+  },
+});
+```
+
+支持：
+
+- `TexImageSource`
+- 文本配置
+- 图片配置
+
+### VAP / VAPX
+
+使用 `vapSlots`：
+
+```ts
+await stage.addGift({
+  type: 'vap',
+  source: 'https://example.com/demo.mp4',
+  config: 'https://example.com/demo.json',
+  x: 0,
+  y: 0,
+  width: 400,
+  height: 400,
+  vapSlots: {
+    welcome01: '欢迎进入房间',
+    avatar_left: 'https://example.com/avatar.png',
+  },
+});
+```
+
+支持：
+
+- 文本字符串
+- 图片 URL
+- `TexImageSource`
+- 结构化文本 / 图片对象
+
+## 后端策略
+
+默认回退顺序：
+
+1. `WebGPU`
+2. `WebGL2`
+3. `WebGL1`
+
+说明：
+
+- `WebGPU` 仅在浏览器支持相关必要能力时启用
+- `WebGL1` 主要用于兼容兜底，不以性能最优为目标
+- demo 中可手动强制切换到 `WebGL1`
+
+## 缓存策略
+
+### 内存缓存
+
+- 默认 `128MB`
+- LRU 淘汰
+
+缓存内容包括：
+
+- 原始资源字节
+- 文本 / JSON
+- `SVGA` worker payload
+- `SVGA` atlas 资产
+
+### `IndexedDB` 磁盘缓存
+
+- 默认 `2048MB`
+- LRU 淘汰
+- 读取命中会刷新最近访问时间
+- 超出预算时按最久未使用记录淘汰
+
+异常情况处理：
+
+- `IndexedDB` 不可用、事务失败、写入失败、容量不足时，会自动降级
+- 损坏的 `SVGA` 磁盘缓存会自动删除并重新生成
+
+## 项目结构
+
+主要目录：
+
+- `src/`
+  核心源码
+- `docs/`
+  设计与汇总文档
+- `publish/`
+  发布脚本
+- `static/`
+  demo 依赖资源
+- `tests/`
+  测试
+
+## 对外导出
+
+入口文件：
+
+- [src/index.ts](</D:/MyDocuments/UnityProjects/SVGAPlayer-Unity/gift-stage/src/index.ts>)
+
+主要导出：
+
+- `GiftStage`
+- `createBackend`
+- `WebGPUBackend`
+- `WebGL2Backend`
+- `WebGL1Backend`
+- `parseSVGA`
+- `buildAtlas`
+- `parseVAPConfig`
+- 相关类型定义
+
+## Demo
+
+Demo 入口：
+
+- [index.html](</D:/MyDocuments/UnityProjects/SVGAPlayer-Unity/gift-stage/index.html>)
+
+可用于验证：
+
+- `SVGA / VAP / AlphaVideo` 播放
+- slot 替换
+- `WebGPU / WebGL2 / WebGL1` 切换
+- 大批同屏压测
+
+## 相关文档
+
+- 优化汇总：
+  [docs/giftstage-optimization-summary.md](</D:/MyDocuments/UnityProjects/SVGAPlayer-Unity/gift-stage/docs/giftstage-optimization-summary.md>)