# 项目范围
## 你会学到什么
- 理解 `mlua-pulse` 为什么把“离线音频导出”放在第一位。
- 分清音乐理论、编曲 DSL、合成、效果、采样、MIDI、PCM 和播放的边界。
- 知道哪些能力属于当前项目，哪些能力不应该塞进这个 crate。
- 遇到采样、空间音频、播放、GPU 这类需求时，能判断它们是否服务于导出。
## 适合谁读
如果你要评估这个 crate 能不能放进自己的工具链，或者准备继续给项目加功能，先读本章。它也适合被用户问题打断时回头确认方向：`mlua-pulse` 不是一个实时宿主，它是一个让 Lua 描述音乐并导出文件的离线创作层。
## 前置知识
- [Wiki 总目录](../README.md)
- [心智模型](mental-model.md)
## 心智模型
`mlua-pulse` 的核心句子是：用 Lua 写音乐结构，用 Rust 注册和验证 API，用 `tunes` 生成声音，最后导出成稳定文件。项目的所有设计都应该服务这条链路。
```text
Lua 编曲脚本 -> pulse 模块 -> Song/Phrase/Sequence -> tunes 渲染 -> WAV/FLAC/MIDI/PCM
```
因此，音乐理论层不是为了做一套完整乐理百科，而是为了让用户能快速把 `"C4"`、`"ionian"`、`"maj7"` 变成可渲染的频率材料。合成层不是为了替代专业软音源，而是为了让示例和脚本在没有外部插件时也能导出可听的音色。采样和 MIDI 的意义也不是资产管理，而是让已有素材能放进同一条时间线。
播放 API 只是一条预览支路。它可以帮助用户本机试听，但不能成为项目的稳定性核心，因为播放依赖声卡、系统音频后端和运行环境。导出不依赖声卡，适合测试、批处理和自动化。
## 最小可运行例子
```lua
local pulse = require("pulse")
local song = pulse.song()
:tempo(100)
:add(
pulse.sequence()
:notes({pulse.note("C4"), pulse.note("E4"), pulse.note("G4")})
:durations({0.25, 0.25, 0.5})
:instrument("electric_piano")
:volume(0.5)
)
song:export_wav("output/scope-check.wav", {
normalize = "rms",
target_db = -18.0,
true_peak_db = -1.0,
})
```
这个例子覆盖了项目范围内最重要的闭环：Lua API、乐理转换、编曲容器、音色选择、离线渲染和导出文件。
## 参数和边界
项目范围内的能力包括：音名、音阶、希腊调式、和弦、移调、MIDI 音符互转；`Sequence`、`Phrase`、`Song`、`DrumGrid`、`DrumMachine`；150+ 乐器、100+ 鼓声；FM、加法、波表、Karplus-Strong、颗粒合成；延迟、混响、滤波、压缩、限制、合唱、相位、EQ；50+ 生成器；采样片段；MIDI 导入导出；WAV/FLAC 导出；响度标准化；`pulse.PcmChunk` userdata 流；本机播放预览。
项目范围外的能力包括：实时插件宿主、DAW 传输同步、复杂声卡路由、完整采样库索引、在线素材市场、与导出无关的 3D 空间音频。空间音频只有在能明确改善离线导出作品时才值得重新讨论。
## 常见陷阱
最常见的偏离是把播放当成核心。播放失败不代表导出失败；CI、服务器和无声卡环境通常应该只运行导出测试。
第二个偏离是把 MIDI 当成音频。MIDI 导出不会保存采样、混响、压缩、母带响度标准化；它只保存 MIDI 文件能表达的符号事件。
第三个偏离是把响度标准化当成“自动好听”。标准化只调整最终电平，不能修复已经削波、刺耳或频段拥挤的混音。
## 进阶用法
设计新 API 时可以用一个问题筛选：它是否让 Lua 作曲更清楚，或让导出结果更可靠？如果答案是否定的，应放在宿主程序、外部工具或后续 crate 中。
对于采样系统，最有价值的是裁剪、循环、淡入淡出、音高/时间调整和稳定导出。对于 GPU，最有价值的是在长曲、密集合成或批量导出时作为可选加速请求，而不是改变音乐语义。
## 相关章节
- [心智模型](mental-model.md)
- [WAV、FLAC、MIDI](../04-export/wav-flac-midi.md)
- [性能](../04-export/performance.md)
- [Cargo 特性](../05-rust-integration/features.md)