mlua-pulse 0.1.0

# 示例索引


## 查阅方式


本章列出仓库当前全部示例。每个示例都是目录，不是单个 Lua 文件：`main.rs` 是 Rust 启动器，`script.lua` 是编曲脚本，`output/` 是导出目录。运行示例时优先使用 `--release`，尤其是完整曲子、FLAC、颗粒合成和三分钟作品。

通用结构：

```text
examples/<name>/
  main.rs
  script.lua
  output/
```

## 运行总览


| 示例 | 命令 | 学习重点 |
| --- | --- | --- |
| `foundation_loop` | `cargo run --release --example foundation_loop` | 最小 loop、WAV 导出 |
| `capability_expansion` | `cargo run --release --example capability_expansion` | 乐器、鼓机、FLAC、MIDI |
| `algorithm_generators` | `cargo run --release --example algorithm_generators` | 生成器、映射、算法旋律 |
| `synthesis_algorithms` | `cargo run --release --example synthesis_algorithms` | FM、加法、拨弦、颗粒、波表 |
| `effects_chain` | `cargo run --release --example effects_chain` | 轨道效果和 master 效果 |
| `phrase_arrangement` | `cargo run --release --example phrase_arrangement` | phrase、repeat、段落编排 |
| `playback` | `cargo run --release --example playback` | 播放预览和无声卡保护 |
| `solo_piano` | `cargo run --release --example solo_piano` | 钢琴小品和 MIDI 导出 |
| `mini_symphony` | `cargo run --release --example mini_symphony` | 小型管弦合奏 |
| `fresh_pop` | `cargo run --release --example fresh_pop` | 小清新流行结构 |
| `kaze_ensemble` | `cargo run --release --example kaze_ensemble` | 合奏化主题风格练习 |
| `farewell_ensemble` | `cargo run --release --example farewell_ensemble` | 慢速抒情合奏 |
| `hardcore_edm` | `cargo run --release --example hardcore_edm` | 808、FM growl、硬核电子 |
| `kawaii_bass_3min` | `cargo run --release --example kawaii_bass_3min` | 不少于三分钟的 Kawaii Bass |
| `moonlight_golden_hall` | `cargo run --release --example moonlight_golden_hall` | 月光奏鸣曲风格的大厅合奏 |

## 每个示例怎么读


`foundation_loop`：从 `examples/foundation_loop/script.lua` 开始，观察 `pulse.sequence()`、`pulse.drum_machine("808")`、`song:export_wav` 如何组成闭环。练习：把 `electric_piano` 换成 `music_box`，把 tempo 改成 96。

`capability_expansion`：展示更多目录能力，例如 `pulse.instruments()`、`pulse.euclidean`、`export_flac`、`export_midi`。练习：换一种鼓声别名，并调 `midi_velocity_gain`。

`algorithm_generators`：展示 `pulse.generate`、`pulse.map_to_scale`、`pulse.normalize`。练习：把 `fibonacci` 换成 `primes`，把音阶换成 `minor_pentatonic`。

`synthesis_algorithms`：集中展示 `:synth("fm", "bell")`、`:synth("additive", ...)`、`:synth("karplus_strong", ...)`、`:synth("granular", ...)`、`:synth("wavetable")`。练习：降低 FM 音量并加低通 filter，比较刺耳感变化。

`effects_chain`：展示 `:effect("filter", ...)`、`:effect("compressor", ...)`、`:master_effect("reverb", ...)`、`:master_effect("limiter", ...)`。练习：把 reverb mix 降低，听清晰度变化。

`phrase_arrangement`：展示 `pulse.phrase()`、`:repeat_times(2)`、`:add_phrase`、WAV/MIDI 导出。练习：新增一个 bridge phrase，只保留 pad 和轻鼓。

`playback`：默认导出预览 WAV，只有设置环境变量时才尝试真实播放。练习：先确认 `output/playback-preview.wav`，再在有声卡环境中启用播放。

`solo_piano`：完整钢琴曲示例，使用 `acoustic_piano` 和 `electric_piano`，同时导出 MIDI。练习：把副段落整体移高八度，但降低 velocity。

`mini_symphony`：包含 `strings`、`brass_section`、`flute` 等管弦层。练习：让铜管只在高潮进入，降低整体混浊度。

`fresh_pop`：小清新流行示例，使用 `electric_piano`、`warm_pad` 和轻鼓。练习：把 chorus 的 pad 音量略升，把 verse 鼓减半。

`kaze_ensemble`：合奏化主题练习，包含 `acoustic_guitar`、`flute`、`pizzicato_strings`、`soft_kick`，并导出 FLAC/MIDI。练习：把 flute 旋律换成 oboe，比较情绪差异。

`farewell_ensemble`：慢速抒情合奏，使用 `slow_strings`、`oboe`、`cello`、`acoustic_piano` 和 `mellow_filter`。练习：降低弦乐音量，让钢琴主题更靠前。

`hardcore_edm`：硬核电子示例，使用 `drum_machine("808")`、`bass_808` 和 `:synth("fm", "growl")`。练习：把 low-pass cutoff 从 1000 调到 700，观察刺耳感。

`kawaii_bass_3min`：三分钟完整示例，脚本中有 `local section_beats = 16.0`、`local section_repeats = 24` 和 `assert(duration_seconds >= 180.0)`。练习：只改每个 section 的音色和 fill，不改总时长。

`moonlight_golden_hall`：大厅版月光风格示例，包含 `acoustic_piano`、`slow_strings`、`brass_section`、`choir_aahs` 和大空间 reverb。练习：降低 choir 音量，避免盖住钢琴主题。

## 示例


运行示例后，检查对应目录下的 `output/`：

```powershell
cargo run --release --example foundation_loop
Get-ChildItem examples/foundation_loop/output
```

如果某个示例导出慢，先确认命令里有 `--release`。如果导出音频刺耳，读 [混音](../02-sound-design/mixing.md) 和 [故障排查](../04-export/troubleshooting.md)。

## 相关章节


- [快速开始](../01-lua-composition/getting-started.md)
- [完整作品工作流](../01-lua-composition/full-song-workflows.md)
- [性能](../04-export/performance.md)
- [Lua API](lua-api.md)