mlua-pulse 0.1.0

# 快速开始


## 你会学到什么


- 了解每个示例目录为什么都有 `main.rs`、`script.lua` 和 `output/`。
- 在 Lua 中加载 `pulse` 并导出第一段 WAV。
- 知道为什么示例推荐 `cargo run --release --example <name>`。
- 建立“先小声、再混音、最后标准化”的导出习惯。

## 适合谁读


第一次打开项目、想马上听到声音的人先读本章。它不假设你熟悉 Rust，也不假设你会 DSP；你只需要知道 Lua 脚本会由 Rust 启动器执行。

## 前置知识


- [项目范围](../00-overview/project-scope.md)
- [心智模型](../00-overview/mental-model.md)

## 心智模型


示例目录是最小工程单元：

```text
examples/foundation_loop/
  main.rs
  script.lua
  output/
```

`main.rs` 做宿主工作：创建 `mlua::Lua`、调用 `mlua_pulse::register_package_loader(&lua)`、执行同目录的 `script.lua`。`script.lua` 做音乐工作：`require("pulse")`，创建 sequence、drum grid、phrase、song，然后导出。`output/` 是导出目标，避免文件散在仓库根目录。

这种结构的好处是每个示例都能独立运行、独立修改、独立输出。学习时先复制一个示例目录，比从空工程开始更稳。

## 最小可运行例子


```lua
local pulse = require("pulse")

local melody = pulse.sequence()
  :notes({pulse.note("C4"), pulse.note("E4"), pulse.note("G4"), pulse.note("C5")})
  :durations({0.25, 0.25, 0.25, 0.75})
  :instrument("electric_piano")
  :volume(0.5)
  :velocity(0.6)

local song = pulse.song()
  :tempo(112)
  :add(melody)
  :master_effect("limiter", "standard")

song:export_wav("output/first-song.wav", {
  sample_rate = 44100,
  normalize = "rms",
  target_db = -18.0,
  true_peak_db = -1.0,
})
```

从仓库根目录运行现有示例：

```powershell
cargo run --release --example foundation_loop
```

## 参数和边界


`pulse.note("C4")` 返回频率；`:notes` 接收频率数组；`:durations` 的数量必须和音符数量一致，并且每个时值必须大于 0。`:volume` 可以超过 1，但新手建议从 `0.25..0.7` 开始；`:velocity` 范围是 `0..1`。

导出选项里的 `normalize = "rms"` 会在最终渲染后统一响度，`target_db` 通常设为 `-18..-16`，`true_peak_db` 建议 `-1`。这些设置不能修复已经削波的混音，所以轨道音量仍然要保守。

## 常见陷阱


debug 构建能跑，但长曲、FLAC、颗粒合成会慢很多。示例文档统一推荐 `--release`，这是实际使用路径。

不要把输出路径写到仓库根目录。示例统一用 `output/...`，既清楚也便于清理。

不要一开始就把每轨音量设成 `1.0`。多轨叠加会很快过载，听起来像电流声或刺耳爆音。

## 进阶用法


学会最小导出后，可以把 `melody` 换成 `phrase`：

```lua
local phrase = pulse.phrase()
  :add(melody)
  :repeat_times(4)

pulse.song()
  :tempo(112)
  :add_phrase(phrase)
  :export_wav("output/phrase.wav", { normalize = "rms" })
```

完整作品应从短小动机开始，用 phrase 重复和变化，而不是手写几百个音符。

## 相关章节


- [音乐理论](theory.md)
- [序列、乐句与编排](arrangement.md)
- [WAV、FLAC、MIDI](../04-export/wav-flac-midi.md)
- [示例索引](../06-reference/examples.md)