mlua-pulse 0.1.0

Lua-friendly music composition and audio export bindings built on tunes and mlua
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135

# mlua-pulse Wiki


这里是 `mlua-pulse` 的多卷文档中心。根 README 负责让你知道项目是什么、怎么跑；wiki 负责把编曲、音色、生成、导出、Rust 集成和 API 查阅讲清楚。

`mlua-pulse` 的核心模型很朴素：Lua 写作品结构，Rust 注册模块并调用 `tunes` 渲染，最终得到 WAV、FLAC、MIDI 或 `pulse.PcmChunk` userdata 形式的原始 PCM。播放只用于本机预览，导出才是交付路径。

## 文档树


下面的代码块保留完整路径，便于搜索和测试；后面的链接使用 wiki 内相对路径。

```text
wiki/README.md
wiki/00-overview/project-scope.md
wiki/00-overview/mental-model.md
wiki/00-overview/glossary.md
wiki/01-lua-composition/getting-started.md
wiki/01-lua-composition/theory.md
wiki/01-lua-composition/arrangement.md
wiki/01-lua-composition/rhythm-drums.md
wiki/01-lua-composition/samples-midi.md
wiki/01-lua-composition/full-song-workflows.md
wiki/02-sound-design/instruments.md
wiki/02-sound-design/synthesis.md
wiki/02-sound-design/effects.md
wiki/02-sound-design/mixing.md
wiki/03-generation/generators.md
wiki/03-generation/mapping.md
wiki/03-generation/recipes.md
wiki/04-export/wav-flac-midi.md
wiki/04-export/loudness.md
wiki/04-export/pcm-streaming.md
wiki/04-export/performance.md
wiki/04-export/troubleshooting.md
wiki/05-rust-integration/embedding-lua.md
wiki/05-rust-integration/rust-builders.md
wiki/05-rust-integration/features.md
wiki/05-rust-integration/error-handling.md
wiki/06-reference/lua-api.md
wiki/06-reference/rust-api.md
wiki/06-reference/examples.md
```

总览卷：

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

Lua 编曲卷：

- [快速开始](01-lua-composition/getting-started.md)
- [音乐理论](01-lua-composition/theory.md)
- [序列、乐句与编排](01-lua-composition/arrangement.md)
- [节奏与鼓机](01-lua-composition/rhythm-drums.md)
- [采样与 MIDI](01-lua-composition/samples-midi.md)
- [完整作品工作流](01-lua-composition/full-song-workflows.md)

声音设计卷：

- [乐器目录](02-sound-design/instruments.md)
- [合成算法](02-sound-design/synthesis.md)
- [效果链](02-sound-design/effects.md)
- [混音](02-sound-design/mixing.md)

生成式编曲卷：

- [生成器目录](03-generation/generators.md)
- [映射方法](03-generation/mapping.md)
- [生成配方](03-generation/recipes.md)

导出与工程化卷：

- [WAV、FLAC、MIDI](04-export/wav-flac-midi.md)
- [响度标准化](04-export/loudness.md)
- [PCM 流](04-export/pcm-streaming.md)
- [性能](04-export/performance.md)
- [故障排查](04-export/troubleshooting.md)

Rust 集成卷：

- [嵌入 Lua](05-rust-integration/embedding-lua.md)
- [Rust 构造器](05-rust-integration/rust-builders.md)
- [Cargo 特性](05-rust-integration/features.md)
- [错误处理](05-rust-integration/error-handling.md)

参考卷：

- [Lua API](06-reference/lua-api.md)
- [Rust API](06-reference/rust-api.md)
- [示例索引](06-reference/examples.md)

## 学习路径


Lua 新手路径：先读 [项目范围](00-overview/project-scope.md)，再读 [快速开始](01-lua-composition/getting-started.md)、[音乐理论](01-lua-composition/theory.md)、[序列、乐句与编排](01-lua-composition/arrangement.md)，最后读 [WAV、FLAC、MIDI](04-export/wav-flac-midi.md) 和 [响度标准化](04-export/loudness.md)。

有编曲基础的用户路径：直接从 [完整作品工作流](01-lua-composition/full-song-workflows.md) 开始，遇到音色问题跳到 [合成算法](02-sound-design/synthesis.md) 和 [效果链](02-sound-design/effects.md)，导出前读 [混音](02-sound-design/mixing.md)。

Rust 集成者路径：读 [心智模型](00-overview/mental-model.md)、[嵌入 Lua](05-rust-integration/embedding-lua.md)、[Cargo 特性](05-rust-integration/features.md)，需要绕过 Lua 时读 [Rust 构造器](05-rust-integration/rust-builders.md) 和 [Rust API](06-reference/rust-api.md)。

导出排错路径：先查 [故障排查](04-export/troubleshooting.md)，再按症状跳到 [响度标准化](04-export/loudness.md)、[PCM 流](04-export/pcm-streaming.md) 或 [性能](04-export/performance.md)。

## 能力地图


| 能力 | 主要章节 |
| --- | --- |
| 音名、音阶、调式、和弦、移调 | [音乐理论](01-lua-composition/theory.md) |
| 序列、段落、完整作品 | [序列、乐句与编排](01-lua-composition/arrangement.md) |
| 鼓声、808、欧几里得节奏 | [节奏与鼓机](01-lua-composition/rhythm-drums.md) |
| 采样片段和 MIDI 导入 | [采样与 MIDI](01-lua-composition/samples-midi.md) |
| 乐器和合成 | [乐器目录](02-sound-design/instruments.md)、[合成算法](02-sound-design/synthesis.md) |
| 延迟、混响、动态、调制、滤波 | [效果链](02-sound-design/effects.md) |
| 数学序列生成音乐素材 | [生成器目录](03-generation/generators.md)、[映射方法](03-generation/mapping.md) |
| WAV、FLAC、MIDI、PCM、播放 | [导出与工程化卷](04-export/wav-flac-midi.md) |
| Rust 嵌入和模块构建 | [Rust 集成卷](05-rust-integration/embedding-lua.md) |

## 遇到问题时从这里开始


| 症状 | 先读 |
| --- | --- |
| 导出的 MIDI 很小声 | [响度标准化](04-export/loudness.md) |
| FLAC 比 WAV 大 | [WAV、FLAC、MIDI](04-export/wav-flac-midi.md) |
| 有电流声或爆音 | [混音](02-sound-design/mixing.md)、[故障排查](04-export/troubleshooting.md) |
| 合成器刺耳 | [合成算法](02-sound-design/synthesis.md)、[混音](02-sound-design/mixing.md) |
| 长曲导出很慢 | [性能](04-export/performance.md) |
| 无声卡环境播放失败 | [故障排查](04-export/troubleshooting.md) |
| 不知道示例怎么跑 | [示例索引](06-reference/examples.md) |
| LuaLS 没有补全 | [Lua API](06-reference/lua-api.md) |

## 和 README、LuaLS 注解、示例目录的关系


根 README 是门面，适合复制安装命令和找到文档入口。wiki 是教材，适合系统学习和排错。`types/pulse.meta.lua` 是 LuaLS 注解，适合编辑器补全和悬停，不适合承担教程职责。`examples/<name>/` 是可运行乐谱，每个目录都有 `main.rs`、`script.lua` 和 `output/`。

## 维护规则


新增 API 时，请同步更新 `types/pulse.meta.lua`、[Lua API](06-reference/lua-api.md) 或 [Rust API](06-reference/rust-api.md)。新增示例时，请同步更新 [示例索引](06-reference/examples.md)。涉及导出、响度、PCM 或性能的变更，请同步更新 `04-export/` 卷，并运行 `cargo test --test lua_api`。