# Audio 模块概览

**命名空间**: `XCEngine::Audio`

**类型**: `module`

**描述**: XCEngine 的音频系统模块，提供完整的音频播放、3D 空间化、效果处理和混音功能。

## 概述

Audio 模块是 XCEngine 的音频子系统，支持多通道音频播放、3D 空间化定位（HRTF）、音频效果处理（混响、均衡器、FFT）、以及基于 WASAPI 的 Windows 音频后端。该模块设计为与 ECS 组件系统集成，通过 AudioSourceComponent 和 AudioListenerComponent 实现音频源的播放和空间化处理。

## 模块内容

### 核心系统

| 组件 | 文件 | 描述 |
|------|------|------|
| [AudioSystem](audio-system/audio-system.md) | `AudioSystem.h` | 音频系统单例，管理所有音频源和后端 |
| [AudioMixer](audio-mixer/audio-mixer.md) | `AudioMixer.h` | 音频混音器，支持效果链和 3D 参数 |
| [IAudioBackend](i-audio-backend/i-audio-backend.md) | `IAudioBackend.h` | 音频后端抽象接口 |
| [IAudioEffect](i-audio-effect/i-audio-effect.md) | `IAudioEffect.h` | 音频效果接口基类 |

### 音频效果

| 组件 | 文件 | 描述 |
|------|------|------|
| [FFTFilter](fft-filter/fft-filter.md) | `FFTFilter.h` | FFT 频谱分析滤波器 |
| [Reverbation](reverbation/reverbation.md) | `Reverbation.h` | 混响效果器（ Schroeder 算法的并行 Comb 滤波器 + AllPass 滤波器） |
| [Equalizer](equalizer/equalizer.md) | `Equalizer.h` | 多频段参数均衡器 |
| [HRTF](hrtf/hrtf.md) | `HRTF.h` | 基于头部相关传输函数的 3D 空间化 |

### Windows 后端

| 组件 | 文件 | 描述 |
|------|------|------|
| [WASAPIBackend](wasapi-backend/wasapi-backend.md) | `WASAPI/WASAPIBackend.h` | Windows WASAPI 音频后端实现 |

### 配置与类型

| 组件 | 文件 | 描述 |
|------|------|------|
| [AudioConfig](audio-config/audio-config.md) | `AudioConfig.h` | 音频系统配置 |
| [Audio3DParams](audio-3d-params/audio-3d-params.md) | `AudioTypes.h` | 3D 空间化参数 |
| [AudioBufferDesc](audio-buffer-desc/audio-buffer-desc.md) | `AudioTypes.h` | 音频缓冲区描述符 |
| [SpatializerParams](spatializer-params/spatializer-params.md) | `AudioTypes.h` | 空间化计算参数 |

### 枚举类型

| 枚举 | 描述 |
|------|------|
| [AudioResourceType](enums/audio-resource-type.md) | 音频资源类型 |
| [AudioLoadState](enums/audio-load-state.md) | 音频加载状态 |
| [AudioFormat](enums/audio-format.md) | 音频格式（WAV, OGG, MP3, FLAC, AAC） |
| [SpeakerMode](enums/speaker-mode.md) | 扬声器模式（Mono, Stereo, Surround51, Surround71 等） |
| [AudioChannel](enums/audio-channel.md) | 音频通道（FrontLeft, FrontRight, FrontCenter, LFE 等） |
| [PlayState](enums/play-state.md) | 播放状态（Stopped, Playing, Paused） |
| [StopMode](enums/stop-mode.md) | 停止模式（Immediate, AllowFadeOut） |
| [PanMode](enums/pan-mode.md) | 声像模式（Pan3D, Pan2D） |
| [VolumeSource](enums/volume-source.md) | 音量来源（Direct, PathOcclusion, Transmission, Obstruction） |

## 使用示例

```cpp
#include <XCEngine/Audio/AudioSystem.h>
#include <XCEngine/Audio/AudioMixer.h>
#include <XCEngine/Audio/Equalizer.h>
#include <XCEngine/Audio/Reverbation.h>

using namespace XCEngine::Audio;

void InitializeAudioSystem() {
    AudioConfig config;
    config.sampleRate = 48000;
    config.channels = 2;
    config.bitsPerSample = 16;
    config.speakerMode = SpeakerMode::Stereo;
    config.bufferSize = 8192;
    config.bufferCount = 2;

    AudioSystem::Get().Initialize(config);
}

void SetupAudioWithEffects() {
    AudioMixer* mixer = new AudioMixer();
    
    Reverbation* reverb = new Reverbation();
    reverb->SetRoomSize(0.5f);
    reverb->SetWetMix(0.3f);
    reverb->SetDryMix(0.7f);
    
    Equalizer* eq = new Equalizer();
    eq->SetBandCount(4);
    eq->SetBandFrequency(0, 100.0f);
    eq->SetBandGain(0, 3.0f);
    
    mixer->AddEffect(eq);
    mixer->AddEffect(reverb);
    mixer->SetVolume(0.8f);
}

void UpdateListener(const Math::Vector3& pos, const Math::Quaternion& rot) {
    AudioSystem::Get().SetListenerTransform(pos, rot);
}
```

## 相关文档

- [Resources 模块 - AudioClip](../resources/audioclip/audio-clip.md) - 音频资源管理
- [Components 模块 - AudioSourceComponent](../components/audio-source/audio-source-component.md) - 音频源组件
- [Components 模块 - AudioListenerComponent](../components/audio-listener/audio-listener-component.md) - 音频监听器组件