96 lines
2.6 KiB
Markdown
96 lines
2.6 KiB
Markdown
# P0-9: IAudioService 需求详细文档
|
||
|
||
## 对齐说明
|
||
|
||
本文档以 `docs/requirements/p0-requirements-set.md` 为准。P0 音频系统提供基础 BGM/SFX 能力和轻量 `IAudioHandle`，但不做完整音频框架。
|
||
|
||
## 目标
|
||
|
||
提供基础音频播放能力，包括 BGM 播放/停止、SFX 播放、音量控制、静音、简单 SFX AudioSource 池和 BGM 淡入淡出。
|
||
|
||
## 接口
|
||
|
||
```csharp
|
||
public interface IAudioService
|
||
{
|
||
IAudioHandle PlayBgm(string key, bool loop = true, float fadeIn = 0f);
|
||
IAudioHandle PlaySfx(string key);
|
||
void StopBgm(float fadeOut = 0f);
|
||
void SetBgmVolume(float volume);
|
||
void SetSfxVolume(float volume);
|
||
void SetMute(bool mute);
|
||
}
|
||
|
||
public interface IAudioHandle
|
||
{
|
||
void Stop(float fadeOut = 0f);
|
||
bool IsPlaying { get; }
|
||
}
|
||
```
|
||
|
||
## 行为规则
|
||
|
||
- 同一时间只有一首 BGM。
|
||
- 播放新 BGM 时停止旧 BGM。
|
||
- `fadeIn` 和 `fadeOut` 使用线性插值。
|
||
- SFX 可同时播放多个。
|
||
- SFX 使用简单 AudioSource 池。
|
||
- 音量参数 clamp 到 `[0, 1]`。
|
||
- 最终音量 = 通道音量 * 静音系数。
|
||
- 音频资源通过 `IResourceService` 加载。
|
||
- 播放失败时抛异常并包含 key。
|
||
|
||
## SFX 池
|
||
|
||
```csharp
|
||
public sealed class AudioServiceConfig
|
||
{
|
||
public int SfxPoolSize = 10;
|
||
public bool ReuseOldestWhenExhausted = true;
|
||
}
|
||
```
|
||
|
||
规则：
|
||
|
||
- 池未满时创建或复用 AudioSource。
|
||
- 池耗尽且允许复用时，复用最早播放完毕或最旧的 AudioSource。
|
||
- 池耗尽且不允许复用时，记录警告并跳过本次 SFX。
|
||
|
||
## 暂不做
|
||
|
||
- 单个音频 Pause/Resume。
|
||
- 单个音频 Volume。
|
||
- AudioMixer 分组。
|
||
- 3D 空间音频。
|
||
- 动态音乐。
|
||
- 语音/对话系统。
|
||
- 音频配置表。
|
||
- 编辑器音频检查工具。
|
||
|
||
## 验收标准
|
||
|
||
| # | 标准 | 通过条件 |
|
||
|---|------|---------|
|
||
| 1 | BGM 播放 | PlayBgm 后 BGM 正常播放 |
|
||
| 2 | BGM 切换 | 播放新 BGM 时旧 BGM 停止 |
|
||
| 3 | BGM 淡入 | fadeIn > 0 时线性渐入 |
|
||
| 4 | BGM 停止 | StopBgm 后 BGM 停止 |
|
||
| 5 | BGM 淡出 | fadeOut > 0 时线性渐出后停止 |
|
||
| 6 | SFX 播放 | PlaySfx 后音效播放 |
|
||
| 7 | SFX 并发 | 多个 SFX 可同时播放 |
|
||
| 8 | SFX 池 | 多次播放不无限创建 AudioSource |
|
||
| 9 | Handle Stop | handle.Stop 后对应音频停止 |
|
||
| 10 | IsPlaying | 播放中 true，停止后 false |
|
||
| 11 | 音量 clamp | 超出范围时自动 clamp |
|
||
| 12 | 静音 | SetMute(true) 后所有音频静音 |
|
||
| 13 | 加载失败 | 不存在 key 抛异常并包含 key |
|
||
|
||
## 依赖关系
|
||
|
||
```text
|
||
IAudioService
|
||
├── IResourceService
|
||
├── Unity AudioSource / AudioClip
|
||
└── 可选 MonoBehaviour Update/Coroutine 驱动 fade
|
||
```
|