init: 2.B

docs/api/user-client-modules/AudioDecoder.md

@@ -0,0 +1,142 @@
+# AudioDecoder API 文档
+
+本文档由 `DeepSeek R1` 模型生成并微调。
+
+---
+
+## 类描述
+
+音频解码系统的核心抽象类，为不同音频格式提供统一的解码接口。主要处理浏览器原生不支持音频格式的解码任务（如 iOS 平台的 Ogg 格式）。
+
+---
+
+## 静态成员说明
+
+### `decoderMap`
+
+```typescript
+declare const decoderMap: Map<AudioType, new () => AudioDecoder>;
+```
+
+解码器注册表，存储格式类型与解码器类的映射关系
+
+---
+
+## 静态方法说明
+
+### `AudioDecoder.registerDecoder`
+
+```typescript
+function registerDecoder(
+    type: AudioType,
+    decoder: new () => AudioDecoder
+): void;
+```
+
+注册自定义解码器到全局解码器系统
+
+| 参数    | 类型                     | 说明           |
+| ------- | ------------------------ | -------------- |
+| type    | `AudioType`              | 音频格式类型   |
+| decoder | `new () => AudioDecoder` | 解码器构造函数 |
+
+---
+
+### `AudioDecoder.decodeAudioData`
+
+```typescript
+function decodeAudioData(
+    data: Uint8Array,
+    player: AudioPlayer
+): Promise<AudioBuffer | null>;
+```
+
+核心解码入口方法，自动选择最佳解码方案
+
+| 参数   | 类型          | 说明             |
+| ------ | ------------- | ---------------- |
+| data   | `Uint8Array`  | 原始音频字节数据 |
+| player | `AudioPlayer` | 音频播放器实例   |
+
+**处理流程**：
+
+1. 通过文件头检测音频类型
+2. 优先使用浏览器原生解码能力
+3. 无原生支持时查找注册的自定义解码器
+4. 返回标准 `AudioBuffer` 格式数据
+
+---
+
+## 抽象方法说明
+
+### `abstract create`
+
+```typescript
+function create(): Promise<void>;
+```
+
+初始化解码器实例（需分配 WASM 内存等资源）
+
+---
+
+### `abstract destroy`
+
+```typescript
+function destroy(): void;
+```
+
+销毁解码器实例（需释放资源）
+
+---
+
+### `abstract decode`
+
+```typescript
+function decode(data: Uint8Array): Promise<IAudioDecodeData | undefined>;
+```
+
+流式解码方法（分块处理）
+
+| 参数 | 类型         | 说明         |
+| ---- | ------------ | ------------ |
+| data | `Uint8Array` | 音频数据分块 |
+
+---
+
+### `abstract decodeAll`
+
+```typescript
+function decodeAll(data: Uint8Array): Promise<IAudioDecodeData | undefined>;
+```
+
+全量解码方法（单次处理完整文件）
+
+---
+
+### `abstract flush`
+
+```typescript
+function flush(): Promise<IAudioDecodeData | undefined>;
+```
+
+冲刷解码器缓冲区，获取残留数据
+
+---
+
+## 数据结构
+
+### IAudioDecodeData
+
+```typescript
+interface IAudioDecodeData {
+    channelData: Float32Array[]; // 各声道 PCM 数据
+    samplesDecoded: number; // 已解码采样数
+    sampleRate: number; // 采样率 (Hz)
+    errors: IAudioDecodeError[]; // 解码错误集合
+}
+```
+
+## 内置解码器
+
+-   `VorbisDecoder`: 解码 ogg vorbis 音频。
+-   `OpusDecoder`: 解码 ogg opus 音频。