init: 2.B

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

@@ -0,0 +1,184 @@
+# AudioSource API 文档
+
+本文档由 `DeepSeek R1` 模型生成并微调。
+
+---
+
+## 类描述
+
+音频系统的源头抽象类，定义了音频播放的核心控制接口。支持多种音频源类型，包括流媒体、HTML 音频元素和静态音频缓冲。
+
+```mermaid
+graph LR
+    AudioPlayer --> EventEmitter
+
+    click EventEmitter "https://nodejs.org/api/events.html#class-eventemitter"
+```
+
+---
+
+## 抽象成员说明
+
+| 成员          | 类型        | 说明                     |
+| ------------- | ----------- | ------------------------ |
+| `output`      | `AudioNode` | 音频输出节点（必须实现） |
+| `duration`    | `number`    | 音频总时长（秒）         |
+| `currentTime` | `number`    | 当前播放时间（秒）       |
+| `playing`     | `boolean`   | 播放状态标识             |
+
+---
+
+## 核心方法说明
+
+### `abstract play`
+
+```typescript
+function play(when?: number): void;
+```
+
+启动音频播放时序
+
+| 参数 | 类型     | 说明                                            |
+| ---- | -------- | ----------------------------------------------- |
+| when | `number` | 预定播放时间（基于 `AudioContext.currentTime`） |
+
+---
+
+### `abstract stop`
+
+```typescript
+function stop(): number;
+```
+
+停止播放并返回停止时刻
+
+---
+
+### `abstract connect`
+
+```typescript
+function connect(target: IAudioInput): void;
+```
+
+连接至音频处理管线
+
+| 参数   | 类型          | 说明                |
+| ------ | ------------- | ------------------- |
+| target | `IAudioInput` | 下游处理节点/效果器 |
+
+---
+
+### `abstract setLoop`
+
+```typescript
+function setLoop(loop: boolean): void;
+```
+
+设置循环播放模式
+
+---
+
+## 事件系统
+
+| 事件名 | 参数 | 触发时机       |
+| ------ | ---- | -------------- |
+| `play` | -    | 开始播放时     |
+| `end`  | -    | 自然播放结束时 |
+
+---
+
+## 自定义音频源示例
+
+### 网络实时通话源
+
+```typescript
+class WebRTCAudioSource extends AudioSource {
+    private mediaStream: MediaStreamAudioSourceNode;
+    output: AudioNode;
+
+    constructor(ac: AudioContext, stream: MediaStream) {
+        super(ac);
+        this.mediaStream = ac.createMediaStreamSource(stream);
+        this.output = this.mediaStream;
+    }
+
+    get duration() {
+        return Infinity;
+    } // 实时流无固定时长
+    get currentTime() {
+        return this.ac.currentTime;
+    }
+
+    play() {
+        this.mediaStream.connect(this.output);
+        this.playing = true;
+        this.emit('play');
+    }
+
+    stop() {
+        this.mediaStream.disconnect();
+        this.playing = false;
+        return this.ac.currentTime;
+    }
+
+    connect(target: IAudioInput) {
+        this.output.connect(target.input);
+    }
+
+    setLoop() {} // 实时流不支持循环
+}
+
+// 使用示例
+navigator.mediaDevices.getUserMedia({ audio: true }).then(stream => {
+    const source = new WebRTCAudioSource(audioContext, stream);
+    source.connect(effectsChain);
+    source.play();
+});
+```
+
+---
+
+## 内置实现说明
+
+### AudioStreamSource（流媒体源）
+
+```mermaid
+graph LR
+    Network[网络数据流] --> Buffer[缓冲区]
+    Buffer --> Decoder[音频解码器]
+    Decoder --> Output[实时音频节点]
+```
+
+-   支持渐进式加载
+-   动态缓冲管理
+-   适用于浏览器自身不支持的音频类型
+
+### AudioElementSource（HTML 音频元素源）
+
+```mermaid
+graph LR
+    AudioTag[audio 元素] -->|音频流| Output[媒体元素源节点]
+```
+
+-   基于 HTML5 Audio 元素
+-   支持跨域资源
+-   自动处理音频格式兼容
+
+### AudioBufferSource（静态音频缓冲源）
+
+```mermaid
+graph LR
+    File[音频文件] --> Decode[解码为 AudioBuffer]
+    Decode --> Output[缓冲源节点]
+```
+
+-   完整音频数据预加载
+-   精确播放控制
+-   支持内存音频播放
+
+---
+
+## 注意事项
+
+1. **时间精度**  
+   所有时间参数均以 `AudioContext.currentTime` 为基准，精度可达 0.01 秒