XCEngine/docs/api/resources/audioclip/audioclip.md

# AudioClip

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

**类型**: `class`

**头文件**: `XCEngine/Resources/AudioClip/AudioClip.h`

**描述**: 音频片段资源类，管理音频样本数据、格式信息和播放参数。

## 概述

`AudioClip` 是 XCEngine 中的音频资源类，继承自 `IResource`。它管理音频的原始样本数据、采样率、通道数、位深度、时长、格式类型和播放参数。

## 头文件

```cpp
#include <XCEngine/Resources/AudioClip/AudioClip.h>
```

## 枚举类型

### AudioFormat

音频格式枚举。

| 值 | 描述 |
|----|------|
| `Unknown` | 未知格式 |
| `WAV` | WAV 格式 |
| `OGG` | OGG Vorbis 格式 |
| `MP3` | MP3 格式 |
| `FLAC` | FLAC 无损格式 |

### AudioType

音频类型枚举。

| 值 | 描述 |
|----|------|
| `SoundEffect` | 音效 |
| `Music` | 音乐 |
| `Voice` | 语音 |
| `Ambient` | 环境音 |

## 公共方法

### 构造与析构

| 方法 | 描述 |
|------|------|
| [AudioClip](constructor.md) | 默认构造函数 |
| [~AudioClip](destructor.md) | 析构函数 |

### 基础属性

| 方法 | 描述 |
|------|------|
| `ResourceType GetType() const` | 返回 `ResourceType::AudioClip` |
| `const Containers::String& GetName() const` | 获取音频名称 |
| `const Containers::String& GetPath() const` | 获取音频路径 |
| `ResourceGUID GetGUID() const` | 获取全局唯一标识符 |
| [IsValid](is-valid.md) | 检查音频是否有效 |
| [GetMemorySize](get-memory-size.md) | 获取内存大小 |
| [Release](release.md) | 释放音频引用 |

### 音频数据

| 方法 | 描述 |
|------|------|
| [SetAudioData](setaudiodata.md) | 设置音频数据（需先设置采样率、通道数、位深度，自动计算时长） |
| [GetAudioData](get-audio-data.md) | 获取音频数据指针 |

### 音频参数

| 方法 | 描述 |
|------|------|
| [SetSampleRate](set-sample-rate.md) | 设置采样率（Hz） |
| [GetSampleRate](get-sample-rate.md) | 获取采样率 |
| [SetChannels](set-channels.md) | 设置通道数（1=单声道, 2=立体声） |
| [GetChannels](get-channels.md) | 获取通道数 |
| [SetBitsPerSample](set-bits-per-sample.md) | 设置位深度（8/16/24/32） |
| [GetBitsPerSample](get-bits-per-sample.md) | 获取位深度 |
| [SetDuration](set-duration.md) | 设置时长（秒） |
| [GetDuration](get-duration.md) | 获取时长（秒） |

### 格式与类型

| 方法 | 描述 |
|------|------|
| [SetAudioFormat](set-audio-format.md) | 设置音频格式 |
| [GetAudioFormat](get-audio-format.md) | 获取音频格式 |
| [SetAudioType](set-audio-type.md) | 设置音频类型 |
| [GetAudioType](get-audio-type.md) | 获取音频类型 |

### 3D 和循环

| 方法 | 描述 |
|------|------|
| [SetIs3D](set-is-3d.md) | 设置是否为 3D 音频 |
| [Is3D](is-3d.md) | 检查是否为 3D 音频 |
| [SetLoop](set-loop.md) | 设置是否循环播放 |
| [IsLoop](is-loop.md) | 检查是否循环播放 |

### RHI 资源

| 方法 | 描述 |
|------|------|
| [GetRHIResource](get-rhi-resource.md) | 获取 RHI 音频缓冲区 |
| [SetRHIResource](set-rhi-resource.md) | 设置 RHI 音频缓冲区 |

## 实现说明

**注意**: 
- `AudioLoader::Load()` 加载 WAV 文件时仅设置格式，不解析 WAV 头信息来设置采样率、通道数和位深度。这些字段需要手动设置或通过 `SetAudioData()` 的自动计算（需先设置 `m_sampleRate`、`m_channels`、`m_bitsPerSample`）。
- `AudioLoader::ParseWAVData()` 为 stub，始终返回 true。
- `AudioLoader::DetectAudioFormat()` 不检测 AIFF/AIF 格式的文件头，仅依赖扩展名判断。

## 使用示例

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

using namespace XCEngine::Resources;

// 加载音频
ResourceHandle<AudioClip> sfx = ResourceManager::Get().Load<AudioClip>("sounds/explosion.wav");
ResourceHandle<AudioClip> music = ResourceManager::Get().Load<AudioClip>("music/background.ogg");

// 设置参数
sfx->SetAudioType(AudioType::SoundEffect);
sfx->SetSampleRate(44100);
sfx->SetChannels(2);
sfx->SetBitsPerSample(16);
sfx->SetDuration(1.5f);
sfx->SetLoop(false);

// 3D 音频
sfx->SetIs3D(false);
music->SetIs3D(false);

// 获取信息
uint32_t sampleRate = sfx->GetSampleRate();
float duration = sfx->GetDuration();
bool loop = sfx->IsLoop();
```

## 相关文档

- [IResource](../iresource/iresource.md) - 资源基类
- [ResourceManager](../resource-manager/resource-manager.md) - 资源管理器
- [Resources 总览](../resources.md) - 返回模块总览