# 故障排查
## 你会学到什么
- 按症状定位太小声、电流声、刺耳、FLAC 大、MIDI 小声和导出慢。
- 区分编曲问题、混音问题、导出格式问题和环境问题。
- 找到对应章节继续深入处理。
## 适合谁读
当你已经能运行示例，但听感或导出结果不对时读本章。它是排错入口，不替代每个专题章节。
## 前置知识
- [混音](../02-sound-design/mixing.md)
- [响度标准化](loudness.md)
## 心智模型
排错时先看症状属于哪一层：
```text
Lua 参数 -> 编曲密度 -> 音色/效果 -> 渲染/标准化 -> 文件格式 -> 播放环境
```
越靠前的问题，越不应该靠最后的 limiter 或 normalize 解决。越靠后的问题，越不应该回头乱改音乐材料。
## 最小可运行例子
```lua
song:export_wav("output/check.wav", {
sample_rate = 44100,
normalize = "rms",
target_db = -16.0,
true_peak_db = -1.0,
})
```
如果这类标准设置仍然难听，优先检查轨道音量、音色、效果和段落密度。
## 参数和边界
声音太小：检查轨道音量是否过低，再使用 `normalize = "rms"`。如果是 MIDI 文件太小声，调 `midi_velocity_gain` 和 `midi_min_velocity`。
电流声或爆音：先降低轨道音量，减少极短时值，控制 FM/颗粒/高频合成器，添加 limiter 作为保护。已经削波的音频无法被标准化完全修复。
刺耳：降低亮音色音量，使用低通 filter，把 cutoff 从 `2400..4200` 试起，减少 delay/reverb mix。
FLAC 大：检查位深是否 24-bit，内容是否短、噪声多、颗粒多或瞬态强。FLAC 不保证比 WAV 小。
导出慢：使用 `cargo run --release --example <name>`，减少 debug 渲染，必要时尝试 `--features gpu`。
播放失败但导出成功：播放依赖本机声卡和系统后端；导出是核心路径，不需要声卡。
## 常见陷阱
不要看到 MIDI 小声就改 `target_db`。MIDI 不吃音频标准化。
不要看到 FLAC 大就认为导出坏了。先对比位深、时长和内容。
不要看到播放失败就认为作品无法导出。无声卡环境应运行导出示例和测试，而不是播放预览。
## 进阶用法
建立排错顺序：先导出只含鼓和低音的 WAV，再逐层加入和声、旋律、装饰。哪一层加入后出问题，就回到那一层处理音量、音区、合成和效果。
对于完整曲子，可以先导出每个 phrase 的短版，确认段落各自不刺耳，再导出全曲。这样比直接听三分钟成品更容易定位。
## 相关章节
- [混音](../02-sound-design/mixing.md)
- [WAV、FLAC、MIDI](wav-flac-midi.md)
- [PCM 流](pcm-streaming.md)
- [性能](performance.md)