alpha-video-player-js 1.1.0 → 1.3.0

package/README.md

@@ -1,191 +1,179 @@
 # alpha-video-player-js
 
-## 简介
+[中文文档](./README.zh-CN.md) · [Demo](https://trp1119.github.io/alpha-video-player-js-demo)
 
-alpha-video-player-js 是一个 Web 视频动画特效播放 sdk，可以通过制作 Alpha 通道分离的视频素材，在 Web 端通过 WebGL 或 Canvas 重新实现 RGB 通道和 Alpha 通道的融合，从而实现播放带透明通道的视频。
+`alpha-video-player-js` is a zero-dependency web SDK for playing videos with transparency. It rebuilds an alpha video frame on a `<canvas>` by combining its RGB image with a grayscale alpha mask. Use it for high-fidelity motion effects that are more complex than APNG or Lottie.
 
-- 零依赖
+## Highlights
 
-- 接入体积小（gzip 约 5KB 量级，以构建产物为准）
-- 还原度高
-- 兼容 WebGL（GPU） 及 Canvas（CPU） 降级，性能优异
-- 支持 横向 - RGB 通道视频在前、横向 - RGB 通道视频在后、纵向 - RGB 通道视频在前、纵向 - RGB 通道视频在后 四类视频融合
+- WebGL rendering with a Canvas 2D fallback.
+- Native `<video>` playback for regular, opaque videos.
+- Supports horizontal and vertical RGB/alpha layouts, including reversed layouts.
+- Supports scaled alpha masks and alignment on the secondary axis.
+- Framework components for Vue 3, Vue 2.7+, and React.
+- No runtime dependencies; framework packages are optional peer dependencies.
 
-## 使用
-
-### 安装
+## Installation
 
 ```bash
-npm i alpha-video-player-js
+npm install alpha-video-player-js
 ```
 
-### 创建实例
+## Quick start
+
+The container needs an explicit size when `width` and `height` are not supplied.
 
 ```ts
-import AlphaVideoPlayerJs from 'alpha-video-player-js'
+import AlphaVideoPlayer from 'alpha-video-player-js'
+
+const container = document.querySelector<HTMLElement>('#player')!
+
+const player = new AlphaVideoPlayer({
+  container,
+  src: 'https://example.com/alpha-video.mp4',
+  width: 320,
+  height: 180,
+  muted: true,
+  loop: true,
+  autoShow: true,
+})
+
+await player.play()
+```
+
+For autoplay, keep the video muted and handle the rejected `play()` promise; browsers may still enforce autoplay policies.
+
+## Alpha video format
+
+An alpha video stores two images in each ordinary MP4 frame:
 
-const player = new AlphaVideoPlayerJs(config)
+- **RGB region**: the visible color image.
+- **Alpha region**: a grayscale mask. Its red channel becomes the output alpha (`white = opaque`, `black = transparent`).
+
+`orientation` determines how the regions are packed and `side` determines where the RGB region is located:
+
+| `orientation` | `side: 'front'` | `side: 'back'` |
+| --- | --- | --- |
+| `landscape` | RGB left, alpha right | Alpha left, RGB right |
+| `portrait` | RGB top, alpha bottom | Alpha top, RGB bottom |
+
+### Scaled alpha masks
+
+`alphaScale` is the alpha mask's width and height relative to the RGB image:
+
+```text
+1   equal-size RGB and alpha regions (default)
+0.5 alpha is half the RGB width and half the RGB height
+0   no alpha mask; play the source as a native opaque video
 ```
 
-### 实例参数
-
-| 参数          | 含义                               | 默认值    | 是否必传 |
-| ------------- | ---------------------------------- | --------- | -------- |
-| container     | dom 容器                           | -         | 是       |
-| src           | 播放地址                           | -         | 否（无则仅创建画布，可后续 `setSrc`） |
-| width         | 渲染宽度（默认取容器宽度）         | -         | 否       |
-| height        | 渲染高度（默认取容器高度）         | -         | 否       |
-| crossOrigin   | 跨域视频：`anonymous` \| `use-credentials` | `anonymous` | 否   |
-| muted         | 是否静音播放                       | true      | 否       |
-| loop          | 是否循环播放                       | false     | 否       |
-| playbackRate  | 播放速率                           | 1         | 否       |
-| fps           | 限帧（0 表示不额外限帧）           | 0         | 否       |
-| videoFrame    | 是否使用 `requestVideoFrameCallback` 驱动帧循环 | false | 否 |
-| orientation   | 视频排布方式 `landscape` \| `portrait` | landscape | 否   |
-| side          | RGB 通道区域位置 `front` \| `back` | front     | 否       |
-| autoShow      | 可播放后自动绘制首帧               | false     | 否       |
-| autoClear     | 播放结束后是否清空画布             | true      | 否       |
-| autoDestroy   | 播放结束后是否自动销毁实例         | false     | 否       |
-| autoResize    | 元数据加载后是否按视频比例调整 canvas：`contain` \| `width` \| `height` \| `false` | `contain` | 否 |
-| debug         | 是否在控制台输出调试信息           | false     | 否       |
-| onInitSuccess | 初始化成功回调                     | -         | 否       |
-| onInitError   | 初始化失败回调                     | -         | 否       |
-| onLoad        | 元数据加载完成回调                 | -         | 否       |
-| onCanPlay     | 可以播放回调（首次）               | -         | 否       |
-| onPlay        | 开始播放回调                       | -         | 否       |
-| onLoop        | 循环再次可播放时回调               | -         | 否       |
-| onPause       | 暂停播放回调                       | -         | 否       |
-| onEnded       | 结束播放回调                       | -         | 否       |
-| onError       | 错误回调，参数为 `unknown`（见下「错误处理」） | - | 否 |
-| onDestroy     | 销毁实例回调                       | -         | 否       |
-
-### 实例属性
-
-| 属性    | 含义       | 类型    |
-| ------- | ---------- | ------- |
-| playing | 是否播放中 | Boolean |
-| loop    | 是否循环   | Boolean |
-
-### 实例方法
-
-| 方法                          | 含义             | 参数                |
-| ----------------------------- | ---------------- | ------------------- |
-| play(config?)                 | 播放/继续播放，返回 `Promise`；失败时 reject 原始错误 | 可选，同实例参数的部分字段 |
-| pause()                       | 暂停播放         | -                   |
-| destroy()                     | 销毁实例         | -                   |
-| reset()                       | 重置播放进度     | -                   |
-| setSrc(src)                   | 设置播放地址     | 播放地址（string）  |
-| setCurrentTime(time)          | 设置播放进度     | 秒（number）        |
-| setMute(muted)                | 设置是否静音     | boolean             |
-| setLoop(loop)                 | 设置是否循环     | boolean             |
-| setPlaybackRate(playbackRate) | 设置播放倍速     | number              |
-
-### 错误处理
-
-- **`play()` 失败**（如自动播放策略拒绝等）：`Promise` 会被 **reject**，reject 的值为浏览器抛出的**原始错误**（常见为 `DOMException`）；同时若配置了 **`onError`**，也会用**同一引用**调用一次。
-- **`<video>` 媒体错误**（地址无效、解码失败、跨域等）：通过 **`onError`** 传入（多为 `Event` / `ErrorEvent`），随后实例会 **`destroy()`**。
-
-示例（在创建实例时传入 `onError`）：
+When `alphaScale < 1`, use `alphaAlign` to locate the mask on the secondary axis: `start` means top for `landscape` / left for `portrait`; `end` means bottom / right.
 
 ```ts
-const player = new AlphaVideoPlayerJs({
+new AlphaVideoPlayer({
   container,
   src,
-  onError: (err) => {
-    console.error(err)
-  },
+  orientation: 'landscape',
+  side: 'front',
+  alphaScale: 0.5,
+  alphaAlign: 'start',
 })
-
-try {
-  await player.play()
-} catch (e) {
-  // play 失败时与 onError 为同一 err 引用
-  console.error(e)
-}
 ```
 
-## 框架组件
-
-除了 JS 版本外，还提供了 Vue 3、Vue 2（2.7+）、React 的封装组件，通过子路径导入：
+## Core API
+
+### Configuration
+
+| Option | Type / default | Description |
+| --- | --- | --- |
+| `container` | `HTMLElement` | **Required.** Mount target. |
+| `src` | `string` | Video URL. Optional at construction; call `setSrc()` later. |
+| `poster` | `string` | Poster image. A transparent fallback is used by default. |
+| `width`, `height` | `number` | Logical render size; defaults to container dimensions. |
+| `crossOrigin` | `'anonymous'` | CORS mode: `'anonymous'` or `'use-credentials'`. |
+| `muted` | `true` | Whether the video is muted. |
+| `loop` | `false` | Loop playback. |
+| `playbackRate` | `1` | Playback speed. |
+| `fps` | `0` | Animation-frame cap; `0` means uncapped. |
+| `videoFrame` | `false` | Prefer `requestVideoFrameCallback` when supported. |
+| `orientation` | `'landscape'` | Alpha-video packing direction. |
+| `side` | `'front'` | RGB region position. |
+| `alphaScale` | `1` | Alpha mask scale from `0` to `1`; `0` uses native video. |
+| `alphaAlign` | `'start'` | Scaled mask alignment: `'start'` or `'end'`. |
+| `autoShow` | `false` | Draw the first frame once playable. |
+| `autoClear` | `true` | Clear the canvas when playback ends. |
+| `autoDestroy` | `false` | Destroy the player when playback ends. |
+| `autoResize` | `'contain'` | Resize mode: `'contain'`, `'width'`, `'height'`, or `false`. |
+| `debug` | `false` | Print debug output. |
+
+Callbacks: `onInitSuccess`, `onInitError`, `onLoad`, `onCanPlay`, `onPlay`, `onLoop`, `onPause`, `onEnded`, `onError`, and `onDestroy`.
+
+### Instance methods and properties
+
+| Member | Description |
+| --- | --- |
+| `playing` | Read-only boolean that reports whether playback is active. |
+| `loop` | Read-only boolean that reports loop state. |
+| `play(config?)` | Starts or resumes playback and returns a `Promise`. The optional config overrides applicable settings. |
+| `pause()` | Pauses playback and stops the frame loop. |
+| `reset()` | Resets playback progress. |
+| `setSrc(src)` | Changes the video source. |
+| `setCurrentTime(seconds)` | Seeks to a time in seconds. |
+| `setMute(muted)` | Changes mute state. |
+| `setLoop(loop)` | Changes loop state. |
+| `setPlaybackRate(rate)` | Changes playback speed. |
+| `destroy()` | Releases DOM, canvas, and rendering resources. Do not reuse the instance afterward. |
+
+`play()` rejects with the browser's original error (for example, a `DOMException` from autoplay restrictions) and also invokes `onError` with that same value. Media load/decode failures are delivered through `onError` and then destroy the instance.
+
+## Framework components
+
+All component packages expose the same player options except `container`, which the component owns. Their refs expose `play`, `pause`, `destroy`, `reset`, `setSrc`, `setCurrentTime`, `setMute`, `setLoop`, `setPlaybackRate`, and `getPlayer`.
 
 ### Vue 3
 
-```ts
+```vue
+<script setup lang="ts">
+import { ref } from 'vue'
 import AlphaVideoPlayer from 'alpha-video-player-js/vue3'
-```
+import type { IAlphaVideoPlayerRef } from 'alpha-video-player-js/vue3'
+
+const player = ref<IAlphaVideoPlayerRef | null>(null)
+</script>
 
-```html
 <template>
-  <!-- 需要自定义定位/背景时，在外层包一层；组件根节点仅为无 class 的 div -->
-  <div class="player-wrap" :style="{ width: '250px', height: '133px' }">
+  <div style="width: 320px; height: 180px">
     <AlphaVideoPlayer
-      ref="playerRef"
-      src="https://example.com/video.mp4"
-      :width="250"
-      :height="133"
+      ref="player"
+      src="https://example.com/alpha-video.mp4"
+      :width="320"
+      :height="180"
       :muted="true"
-      :loop="false"
-      :playback-rate="playbackRate"
-      orientation="landscape"
-      side="front"
-      @initSuccess="onReady"
-      @error="onError"
+      :loop="true"
+      @initSuccess="player?.play()"
     />
   </div>
-  <!-- 倍速滑块：须用 v-model.number，否则 range 会得到字符串，与 playbackRate 的 Number 类型不符 -->
-  <input v-model.number="playbackRate" type="range" min="0.5" max="2" step="0.5" />
 </template>
-
-<script setup lang="ts">
-import { ref } from 'vue'
-import AlphaVideoPlayer from 'alpha-video-player-js/vue3'
-
-const playerRef = ref()
-const playbackRate = ref(1)
-
-const onReady = () => {
-  playerRef.value?.play()
-}
-
-const onError = (e: unknown) => {
-  console.error(e)
-}
-</script>
 ```
 
-### Vue 2（2.7+）
+Use `v-model.number` for numeric form controls such as `playbackRate`; native range inputs otherwise produce strings. After calling a component ref's `destroy()`, remount the component (for example, change its `:key`) to create a new player.
 
-```ts
-import AlphaVideoPlayer from 'alpha-video-player-js/vue2'
-```
+### Vue 2.7+
 
-```html
+```vue
 <template>
   <AlphaVideoPlayer
     ref="player"
-    src="https://example.com/video.mp4"
+    :src="src"
     :muted="true"
-    orientation="landscape"
-    side="front"
-    @init-success="onReady"
-    @error="onError"
+    @init-success="$refs.player.play()"
   />
 </template>
 
 <script>
 import AlphaVideoPlayer from 'alpha-video-player-js/vue2'
 
-export default {
-  components: { AlphaVideoPlayer },
-  methods: {
-    onReady() {
-      this.$refs.player.play()
-    },
-    onError(e) {
-      console.error(e)
-    },
-  },
-}
+export default { components: { AlphaVideoPlayer } }
 </script>
 ```
 
@@ -194,44 +182,41 @@ export default {
 ```tsx
 import { useRef } from 'react'
 import AlphaVideoPlayer from 'alpha-video-player-js/react'
-import type { AlphaVideoPlayerRef } from 'alpha-video-player-js/react'
-
-function App() {
-  const playerRef = useRef<AlphaVideoPlayerRef>(null)
+import type { IAlphaVideoPlayerRef } from 'alpha-video-player-js/react'
 
+export function Effect() {
+  const player = useRef<IAlphaVideoPlayerRef>(null)
   return (
     <AlphaVideoPlayer
-      ref={playerRef}
-      src="https://example.com/video.mp4"
+      ref={player}
+      src="https://example.com/alpha-video.mp4"
       muted
-      orientation="landscape"
-      side="front"
-      onInitSuccess={() => playerRef.current?.play()}
-      onError={(e) => console.error(e)}
+      loop
+      onInitSuccess={() => player.current?.play()}
     />
   )
 }
 ```
 
-### 组件说明
+The React component also accepts `className` and `style`. Components reactively synchronize changes to `src`, `muted`, `loop`, and `playbackRate`; changing packing options (`orientation`, `side`, `alphaScale`, `alphaAlign`) requires remounting.
+
+### TypeScript exports
+
+| Import path | Types |
+| --- | --- |
+| `alpha-video-player-js` | `IAlphaVideoPlayer`, `IConfig`, `IOptionalConfig`, `IOrientation`, `ISide`, `IAlphaAlign` |
+| `alpha-video-player-js/vue3`, `.../vue2` | `IAlphaVideoPlayer`, `IAlphaVideoPlayerRef` |
+| `alpha-video-player-js/react` | `IAlphaVideoPlayerProps`, `IAlphaVideoPlayerRef` |
 
-- **Props**：与 JS 版的配置项一一对应（去除 `container`，组件内部自动管理）。其中 **`playbackRate` 为 `number`**，在模板里绑定表单控件时勿传入字符串（例如 `<input type="range">` 配合 **`v-model.number`**，或 `:playback-rate="Number(x)"`）。
-- **根节点与布局**：组件只渲染一个**无业务 class** 的根 `div`；若需要与业务一致的绝对定位、背景图上的对齐等，请在**外层元素**上写样式，并通过 **`width` / `height` props**（及 `orientation` / `side` 等）控制画布与拼合逻辑。
-- **销毁后再次挂载**：调用 ref 上的 `destroy()` 后实例已清空，不会在同一次挂载中自动重新 `init`；需要再次初始化时，可对组件使用 **`:key` 递增**或 **`v-if` 切换**，以重新挂载（演示项目 `alpha-video-player-js-demo` 的 `Item.vue` 即采用 `:key` 方案）。
-- **事件/回调**：
-  - Vue 3：`@initSuccess`、`@initError`、`@load`、`@canPlay`、`@play`、`@loop`、`@pause`、`@ended`、`@error`、`@destroy`
-  - Vue 2：`@init-success`、`@init-error`、`@load`、`@can-play`、`@play`、`@loop`、`@pause`、`@ended`、`@error`、`@destroy`
-  - React：`onInitSuccess`、`onInitError`、`onLoad`、`onCanPlay`、`onPlay`、`onLoop`、`onPause`、`onEnded`、`onError`、`onDestroy`
-- **实例方法**（通过 ref 调用）：`play()`、`pause()`、`destroy()`、`reset()`、`setSrc()`、`setCurrentTime()`、`setMute()`、`setLoop()`、`setPlaybackRate()`、`getPlayer()`
-- **响应式 props**：`src`、`muted`、`loop`、`playbackRate` 变更时自动同步到播放器实例。
-- **生命周期**：组件挂载时自动初始化，卸载时自动销毁。
-- **peerDependencies**：vue / react / react-dom 均为可选，只需安装你使用的框架。
+If you need both a framework ref and the core instance type, import them from the same framework subpath. This avoids incompatibility when tooling resolves separate generated declarations.
 
-## 原理
+## Development
 
-- WebGLRender 使用 webgl texture 获取 video RGB 通道视频 和 Alpha 通道视频纹理，并在 shader 中进行自定义融合
-- CanvasRender 使用 canvas2d getImageData 获取 video RGB 通道视频 和 Alpha 通道视频图片元数据，并进行自定义融合
+```bash
+npm run dev    # Watch with Rollup
+npm run build  # Production bundles and declarations
+```
 
-## 示例
+## License
 
-https://trp1119.github.io/alpha-video-player-js-demo
+[ISC](./package.json)

package/README.zh-CN.md

@@ -0,0 +1,154 @@
+# alpha-video-player-js（中文文档）
+
+[English](./README.md) · [在线演示](https://trp1119.github.io/alpha-video-player-js-demo)
+
+`alpha-video-player-js` 是零运行时依赖的 Web 透明视频播放 SDK。它把同一 MP4 帧内的 RGB 画面与灰度 Alpha 遮罩重新合成到 `<canvas>`，用于播放高还原度的透明视频动效。
+
+## 特性
+
+- 优先使用 WebGL，Canvas 2D 自动降级。
+- `alphaScale: 0` 时自动使用原生 `<video>` 播放普通不透明视频。
+- 支持横向、纵向、RGB 在前/后四类拼合格式，以及缩放 Alpha 遮罩。
+- 提供 Vue 3、Vue 2.7+、React 组件入口。
+- 零运行时依赖。
+
+## 安装与快速使用
+
+```bash
+npm install alpha-video-player-js
+```
+
+```ts
+import AlphaVideoPlayer from 'alpha-video-player-js'
+
+const player = new AlphaVideoPlayer({
+  container: document.querySelector<HTMLElement>('#player')!,
+  src: 'https://example.com/alpha-video.mp4',
+  width: 320,
+  height: 180,
+  muted: true,
+  loop: true,
+  autoShow: true,
+})
+
+await player.play()
+```
+
+未传 `width` / `height` 时，容器必须有可计算的尺寸。浏览器自动播放策略可能拒绝 `play()`，请处理其 Promise 拒绝。
+
+## 素材格式
+
+每帧视频由 RGB 区和 Alpha 区组成：RGB 区为彩色画面，Alpha 区为灰度遮罩，其 R 通道被用作输出透明度（白色不透明，黑色透明）。
+
+| `orientation` | `side: 'front'` | `side: 'back'` |
+| --- | --- | --- |
+| `landscape` | RGB 在左，Alpha 在右 | Alpha 在左，RGB 在右 |
+| `portrait` | RGB 在上，Alpha 在下 | Alpha 在上，RGB 在下 |
+
+`alphaScale` 表示 Alpha 遮罩相对 RGB 的宽高缩放：`1` 为等尺寸（默认），`0.5` 为宽高各一半，`0` 表示普通不透明视频。缩小遮罩可由 `alphaAlign` 对齐：横向布局的 `start/end` 分别为上/下；纵向布局分别为左/右。
+
+```ts
+new AlphaVideoPlayer({
+  container,
+  src,
+  orientation: 'landscape',
+  side: 'front',
+  alphaScale: 0.5,
+  alphaAlign: 'start',
+})
+```
+
+## 核心配置
+
+| 配置 | 默认值 | 说明 |
+| --- | --- | --- |
+| `container` | — | **必填**，挂载容器。 |
+| `src` | — | 视频地址；可稍后用 `setSrc()` 设置。 |
+| `poster` | 透明封面 | 视频封面。 |
+| `width` / `height` | 容器尺寸 | 逻辑渲染尺寸。 |
+| `crossOrigin` | `'anonymous'` | `'anonymous'` 或 `'use-credentials'`。 |
+| `muted` / `loop` / `playbackRate` | `true` / `false` / `1` | 播放状态与倍速。 |
+| `fps` / `videoFrame` | `0` / `false` | 帧率上限；是否优先用 `requestVideoFrameCallback`。 |
+| `orientation` / `side` | `'landscape'` / `'front'` | 素材拼合方式。 |
+| `alphaScale` / `alphaAlign` | `1` / `'start'` | 遮罩缩放与副轴对齐。 |
+| `autoShow` / `autoClear` / `autoDestroy` | `false` / `true` / `false` | 首帧、结束清理、自动销毁。 |
+| `autoResize` | `'contain'` | `'contain'`、`'width'`、`'height'` 或 `false`。 |
+| `debug` | `false` | 是否输出调试日志。 |
+
+回调：`onInitSuccess`、`onInitError`、`onLoad`、`onCanPlay`、`onPlay`、`onLoop`、`onPause`、`onEnded`、`onError`、`onDestroy`。
+
+## 实例 API
+
+`playing` 与 `loop` 为只读状态；其余公开方法包括：
+
+```ts
+player.play(config?)
+player.pause()
+player.reset()
+player.setSrc(src)
+player.setCurrentTime(seconds)
+player.setMute(muted)
+player.setLoop(loop)
+player.setPlaybackRate(rate)
+player.destroy()
+```
+
+`play()` 失败时会 reject 浏览器的原始错误，并以相同值调用 `onError`。媒体加载、解码或跨域失败也会通过 `onError` 上报，然后销毁实例。`destroy()` 后不要复用该实例。
+
+## 框架组件
+
+组件入口分别为 `alpha-video-player-js/vue3`、`alpha-video-player-js/vue2` 和 `alpha-video-player-js/react`。组件接收除 `container` 外的全部核心配置，ref 暴露 `play`、`pause`、`destroy`、`reset`、`setSrc`、`setCurrentTime`、`setMute`、`setLoop`、`setPlaybackRate` 与 `getPlayer`。
+
+### Vue 3
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue'
+import AlphaVideoPlayer from 'alpha-video-player-js/vue3'
+import type { IAlphaVideoPlayerRef } from 'alpha-video-player-js/vue3'
+
+const player = ref<IAlphaVideoPlayerRef | null>(null)
+</script>
+
+<template>
+  <AlphaVideoPlayer ref="player" :src="src" :muted="true" @initSuccess="player?.play()" />
+</template>
+```
+
+`playbackRate` 等数字型表单绑定请用 `v-model.number`。手动调用组件 ref 的 `destroy()` 后，应通过 `:key` 或 `v-if` 重新挂载组件。
+
+### React
+
+```tsx
+import { useRef } from 'react'
+import AlphaVideoPlayer from 'alpha-video-player-js/react'
+import type { IAlphaVideoPlayerRef } from 'alpha-video-player-js/react'
+
+export function Effect({ src }: { src: string }) {
+  const player = useRef<IAlphaVideoPlayerRef>(null)
+  return <AlphaVideoPlayer ref={player} src={src} muted onInitSuccess={() => player.current?.play()} />
+}
+```
+
+React 组件额外支持 `className` 与 `style`。`src`、`muted`、`loop`、`playbackRate` 会响应式同步；`orientation`、`side`、`alphaScale`、`alphaAlign` 变更时需要重新挂载。
+
+## 类型导入
+
+| 导入路径 | 类型 |
+| --- | --- |
+| `alpha-video-player-js` | `IAlphaVideoPlayer`、`IConfig`、`IOptionalConfig`、`IOrientation`、`ISide`、`IAlphaAlign` |
+| `.../vue3`、`.../vue2` | `IAlphaVideoPlayer`、`IAlphaVideoPlayerRef` |
+| `.../react` | `IAlphaVideoPlayerProps`、`IAlphaVideoPlayerRef` |
+
+同时使用框架 ref 与核心实例类型时，请从同一个框架子路径导入，避免生成声明文件被拆分解析时的类型不兼容。
+
+## 开发
+
+```bash
+npm run dev
+npm run build
+```
+
+## 许可证
+
+[ISC](./package.json)

package/dist/alpha-video-player-js.d.ts

@@ -3,6 +3,8 @@ interface IConfig {
     width?: number;
     height?: number;
     src?: string;
+    /** 视频封面；未传时使用内置透明封面规避 Android WebView 默认 poster 的 CORS 问题 */
+    poster?: string;
     /** 跨域视频资源；默认 anonymous */
     crossOrigin?: 'anonymous' | 'use-credentials';
     muted?: boolean;
@@ -11,17 +13,21 @@ interface IConfig {
     fps?: number;
     orientation?: IOrientation;
     side?: ISide;
+    /** Alpha 遮罩宽高相对 RGB 内容的缩放比例；0 表示普通不透明视频 */
+    alphaScale?: number;
+    /** Alpha 缩小后在副轴上的对齐方式 */
+    alphaAlign?: IAlphaAlign;
     videoFrame?: boolean;
     debug?: boolean;
     autoShow?: boolean;
     autoClear?: boolean;
     autoDestroy?: boolean;
     /**
-     * 视频加载后按比例自适应 canvas 尺寸（默认 'contain'）。
-     * - 'contain'：自动判断，确保视频完整填入 canvas 盒子（类似 object-fit: contain）
+     * 视频加载后按比例自适应渲染目标尺寸（默认 'contain'）。
+     * - 'contain'：自动判断，确保视频完整填入容器盒子（类似 object-fit: contain）
      * - 'width'：固定宽度，按视频比例自动调整高度
      * - 'height'：固定高度，按视频比例自动调整宽度
-     * - false：不自适应，canvas 保持初始尺寸
+     * - false：不自适应，渲染目标保持初始尺寸
      */
     autoResize?: 'width' | 'height' | 'contain' | false;
     onInitSuccess?: () => void;
@@ -39,6 +45,7 @@ interface IConfig {
 type IOptionalConfig = Omit<IConfig, 'container' | 'src'> & Partial<Pick<IConfig, 'container' | 'src'>>;
 type IOrientation = 'landscape' | 'portrait';
 type ISide = 'front' | 'back';
+type IAlphaAlign = 'start' | 'end';
 
 declare class Render {
     private render;
@@ -55,5 +62,7 @@ declare class Render {
     setLoop(loop: boolean): void;
     setPlaybackRate(playbackRate: number): void;
 }
+/** 核心类实例类型（`new Render(...)` 的实例），便于业务侧标注 ref / getPlayer() 等 */
+type IAlphaVideoPlayer = InstanceType<typeof Render>;
 
-export { type IConfig, Render as default };
+export { type IAlphaAlign, type IAlphaVideoPlayer, type IConfig, type IOptionalConfig, type IOrientation, type ISide, Render as default };