mirror of
https://github.com/motajs/template.git
synced 2026-11-02 15:04:30 +08:00
173 lines
5.6 KiB
Markdown
173 lines
5.6 KiB
Markdown
# AudioPlayer API 文档
|
|
|
|
本文档由 `DeepSeek R1` 模型生成并微调。
|
|
|
|
---
|
|
|
|
## 类描述
|
|
|
|
音频系统的核心控制器，负责管理音频上下文、路由系统、效果器工厂和全局音频参数。支持多音轨管理和 3D 音频空间化配置。
|
|
|
|
```mermaid
|
|
graph LR
|
|
AudioPlayer --> EventEmitter
|
|
|
|
click EventEmitter "https://nodejs.org/api/events.html#class-eventemitter"
|
|
```
|
|
|
|
---
|
|
|
|
## 核心架构
|
|
|
|
```mermaid
|
|
graph TD
|
|
Player[AudioPlayer] --> Sources[音频源工厂]
|
|
Player --> Effects[效果器工厂]
|
|
Player --> Routes[路由系统]
|
|
Player --> Listener[3D 听者配置]
|
|
```
|
|
|
|
---
|
|
|
|
## 属性说明
|
|
|
|
| 属性名 | 类型 | 说明 |
|
|
| ------------- | ------------------------- | ------------------------ |
|
|
| `ac` | `AudioContext` | Web Audio API 上下文实例 |
|
|
| `audioRoutes` | `Map<string, AudioRoute>` | 已注册的音频路由表 |
|
|
| `gain` | `GainNode` | 全局音量控制节点 |
|
|
|
|
---
|
|
|
|
## 方法说明
|
|
|
|
此处暂时只列出方法的简易说明。方法理解难度不高，如果需要可以自行查看代码以及其相关注释来查看如何使用。
|
|
|
|
### 音频源工厂方法
|
|
|
|
| 方法名 | 返回值 | 说明 |
|
|
| ----------------------- | -------------------- | ----------------------------- |
|
|
| `createSource(Source)` | `AudioSource` | 创建自定义音频源 |
|
|
| `createStreamSource()` | `AudioStreamSource` | 创建流式音频源（直播/长音频） |
|
|
| `createElementSource()` | `AudioElementSource` | 基于 HTML5 Audio 元素的音源 |
|
|
| `createBufferSource()` | `AudioBufferSource` | 基于 AudioBuffer 的静态音源 |
|
|
|
|
### 效果器工厂方法
|
|
|
|
| 方法名 | 返回值 | 说明 |
|
|
| ----------------------------- | --------------------- | ---------------------------- |
|
|
| `createEffect(Effect)` | `AudioEffect` | 创建自定义效果器 |
|
|
| `createVolumeEffect()` | `VolumeEffect` | 全局音量控制器 |
|
|
| `createStereoEffect()` | `StereoEffect` | 立体声场控制器 |
|
|
| `createChannelVolumeEffect()` | `ChannelVolumeEffect` | 多声道独立音量控制（6 声道） |
|
|
| `createDelayEffect()` | `DelayEffect` | 精确延迟效果器 |
|
|
| `createEchoEffect()` | `EchoEffect` | 回声效果器（带反馈循环） |
|
|
|
|
### 路由管理方法
|
|
|
|
| 方法名 | 参数 | 说明 |
|
|
| --------------------- | -------------------- | -------------- |
|
|
| `createRoute(source)` | `AudioSource` | 创建新播放路由 |
|
|
| `addRoute(id, route)` | `string, AudioRoute` | 注册命名路由 |
|
|
| `getRoute(id)` | `string` | 获取已注册路由 |
|
|
| `removeRoute(id)` | `string` | 移除指定路由 |
|
|
|
|
### 全局控制方法
|
|
|
|
| 方法名 | 参数 | 说明 |
|
|
| ------------------------------- | ------------------------ | -------------------- |
|
|
| `setVolume(volume)` | `number` (0.0-1.0) | 设置全局音量 |
|
|
| `getVolume()` | - | 获取当前全局音量 |
|
|
| `setListenerPosition(x,y,z)` | `number, number, number` | 设置听者 3D 空间坐标 |
|
|
| `setListenerOrientation(x,y,z)` | `number, number, number` | 设置听者朝向 |
|
|
| `setListenerUp(x,y,z)` | `number, number, number` | 设置听者头顶朝向 |
|
|
|
|
---
|
|
|
|
## 使用示例
|
|
|
|
### 基础音乐播放
|
|
|
|
```typescript
|
|
import { audioPlayer } from '@user/client-modules';
|
|
|
|
// 创建音频源（以音频缓冲为例）
|
|
const bgmSource = audioPlayer.createBufferSource();
|
|
|
|
// 创建播放路由
|
|
const bgmRoute = audioPlayer.createRoute(bgmSource);
|
|
|
|
// 添加效果链
|
|
bgmRoute.addEffect([
|
|
audioPlayer.createStereoEffect(),
|
|
audioPlayer.createVolumeEffect()
|
|
]);
|
|
|
|
// 播放控制
|
|
audioPlayer.play('bgm');
|
|
audioPlayer.pause('bgm');
|
|
```
|
|
|
|
### 3D 环境音效
|
|
|
|
```typescript
|
|
import { audioPlayer } from '@user/client-modules';
|
|
|
|
// 配置3D听者
|
|
audioPlayer.setListenerPosition(0, 0, 0); // 听者在原点
|
|
audioPlayer.setListenerOrientation(0, 0, -1); // 面朝屏幕内
|
|
|
|
// 创建环境音源
|
|
const ambientSource = audioPlayer.createBufferSource();
|
|
await ambientSource.setBuffer(/* 这里填写音频缓冲 */);
|
|
|
|
// 配置3D音效路由
|
|
const ambientRoute = audioPlayer.createRoute(ambientSource);
|
|
const stereo = audioPlayer.createStereoEffect();
|
|
stereo.setPosition(5, 2, -3); // 音源位于右前方高处
|
|
ambientRoute.addEffect(stereo);
|
|
|
|
// 循环播放
|
|
ambientRoute.setLoop(true);
|
|
audioPlayer.addRoute('ambient', ambientRoute);
|
|
audioPlayer.play('ambient');
|
|
```
|
|
|
|
---
|
|
|
|
## 生命周期管理
|
|
|
|
```mermaid
|
|
sequenceDiagram
|
|
participant User
|
|
participant AudioPlayer
|
|
participant AudioContext
|
|
|
|
User->>AudioPlayer: new AudioPlayer()
|
|
AudioPlayer->>AudioContext: 创建音频上下文
|
|
User->>AudioPlayer: createRoute()
|
|
AudioPlayer->>AudioRoute: 实例化路由
|
|
User->>AudioPlayer: play()
|
|
AudioPlayer->>AudioContext: 启动音频时钟
|
|
loop 播放周期
|
|
AudioPlayer->>AudioRoute: 更新状态
|
|
end
|
|
User->>AudioPlayer: stop()
|
|
AudioPlayer->>AudioRoute: 释放资源
|
|
AudioPlayer->>AudioContext: 关闭上下文
|
|
```
|
|
|
|
---
|
|
|
|
## 注意事项
|
|
|
|
1. **空间音频配置**
|
|
3D 效果需统一坐标系：
|
|
|
|
```txt
|
|
(0,0,0) 屏幕中心
|
|
X+ → 右
|
|
Y+ ↑ 上
|
|
Z+ ⊙ 朝向用户
|
|
```
|