# AudioSourceComponent

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

**类型**: `class`

**头文件**: `XCEngine/Components/AudioSourceComponent.h`

**描述**: 音频源组件，负责在 ECS 实体上播放音频。

## 概述

AudioSourceComponent 是 XCEngine ECS 系统中的音频源组件，附加到游戏实体上后可以播放音频片段（AudioClip）。它支持 3D 空间化定位、音量、音调、循环、展开角度、多普勒效应等丰富的音频播放参数。该组件需要与 AudioListenerComponent 配合使用以实现 3D 空间音效。

## 公共方法

| 方法 | 描述 |
|------|------|
| [`AudioSourceComponent`](constructor.md) | 构造函数 |
| [`~AudioSourceComponent`](destructor.md) | 析构函数 |
| [`Play`](play.md) | 开始播放 |
| [`Pause`](pause.md) | 暂停播放 |
| [`Stop`](stop.md) | 停止播放 |
| [`IsPlaying`](is-playing.md) | 检查是否正在播放 |
| [`IsPaused`](is-paused.md) | 检查是否已暂停 |
| [`SetClip`](set-clip.md) | 设置音频片段 |
| [`GetClip`](get-clip.md) | 获取音频片段 |
| [`SetVolume`](set-volume.md) | 设置音量 |
| [`GetVolume`](get-volume.md) | 获取音量 |
| [`SetPitch`](set-pitch.md) | 设置音调 |
| [`GetPitch`](get-pitch.md) | 获取音调 |
| [`SetPan`](set-pan.md) | 设置声像 |
| [`GetPan`](get-pan.md) | 获取声像 |
| [`SetLooping`](set-looping.md) | 设置循环播放 |
| [`IsLooping`](is-looping.md) | 检查循环状态 |
| [`SetSpatialize`](set-spatialize.md) | 设置是否启用空间化 |
| [`IsSpatialize`](is-spatialize.md) | 检查空间化状态 |
| [`Set3DParams`](set-3d-params.md) | 设置 3D 参数 |
| [`Get3DParams`](get-3d-params.md) | 获取 3D 参数 |
| [`SetDopplerLevel`](set-doppler-level.md) | 设置多普勒等级 |
| [`GetDopplerLevel`](get-doppler-level.md) | 获取多普勒等级 |
| [`SetSpread`](set-spread.md) | 设置展开角度 |
| [`GetSpread`](get-spread.md) | 获取展开角度 |
| [`SetReverbZoneMix`](set-reverb-zone-mix.md) | 设置混响区域混合 |
| [`GetReverbZoneMix`](get-reverb-zone-mix.md) | 获取混响区域混合 |
| [`SetOutputMixer`](set-output-mixer.md) | 设置输出混音器 |
| [`GetOutputMixer`](get-output-mixer.md) | 获取输出混音器 |
| [`SetTime`](set-time.md) | 设置播放时间 |
| [`GetTime`](get-time.md) | 获取播放时间 |
| [`GetDuration`](get-duration.md) | 获取音频时长 |
| [`GetEnergy`](get-energy.md) | 获取音频能量 |
| [`StartEnergyDetect`](start-energy-detect.md) | 开始能量检测 |
| [`StopEnergyDetect`](stop-energy-detect.md) | 停止能量检测 |
| [`IsEnergyDetecting`](is-energy-detecting.md) | 检查能量检测状态 |

## 组件方法

| 方法 | 描述 |
|------|------|
| [`Update`](update.md) | 每帧更新 |
| [`OnEnable`](on-enable.md) | 启用时回调 |
| [`OnDisable`](on-disable.md) | 禁用时回调 |
| [`OnDestroy`](on-destroy.md) | 销毁时回调 |
| [`GetName`](get-name.md) | 获取组件名称 |

## 使用示例

```cpp
#include <XCEngine/Components/AudioSourceComponent.h>
#include <XCEngine/Resources/ResourceManager.h>

using namespace XCEngine::Components;

void PlaySoundEffect(Entity entity, const char* soundPath) {
    AudioSourceComponent* audioSource = entity.AddComponent<AudioSourceComponent>();
    
    auto clip = Resources::ResourceManager::Get().Load<Resources::AudioClip>(soundPath);
    audioSource->SetClip(clip.Get());
    audioSource->SetVolume(0.8f);
    audioSource->SetLooping(false);
    audioSource->SetSpatialize(true);
    
    audioSource->Play();
}

void PlayLoopingMusic(Entity entity, const char* musicPath) {
    AudioSourceComponent* audioSource = entity.AddComponent<AudioSourceComponent>();
    
    auto clip = Resources::ResourceManager::Get().Load<Resources::AudioClip>(musicPath);
    audioSource->SetClip(clip.Get());
    audioSource->SetVolume(0.5f);
    audioSource->SetLooping(true);
    audioSource->SetSpatialize(false);
    
    audioSource->Play();
}
```

## 相关文档

- [Components 模块总览](../components.md) - Components 模块总览
- [AudioListenerComponent](../audio-listener/audio-listener-component.md) - 音频监听器组件
- [AudioSystem 模块](../../audio/audio.md) - 音频系统模块