mlua-pulse 0.1.0

# mlua-pulse


`mlua-pulse` 是一个基于 `tunes = "1.1.0"` 和 `mlua = "0.11.6"` 的 Rust crate，用来把 Lua 变成可编曲、可合成、可离线导出的音乐脚本环境。你在 Lua 里写旋律、和弦、鼓、段落、采样、MIDI、合成器、效果链和响度选项，Rust 宿主负责注册 `pulse` 模块，并把作品稳定导出为 WAV、FLAC、MIDI 或流式 PCM。

## 项目定位


本项目只围绕“编曲到导出”的闭环展开。导出音频是核心能力；播放 API 只用于本机预览。采样可以作为编曲素材，MIDI 可以导入后再编排，GPU 特性可以作为离线渲染加速请求，但项目不试图变成实时 DAW 宿主、完整采样库管理器或空间音频引擎。

MIDI 和采样都可以作为编曲素材加入 `song` 或 `phrase`。采样片段支持裁剪、循环、反向、淡入淡出、音高/时间处理、轨道音量、声像和效果；导入 MIDI 可以变成可重复的 `MidiClip`，并参与 WAV、FLAC、PCM、播放和可表达内容的 MIDI 导出。详细语义见 [Lua API 参考](wiki/06-reference/lua-api.md)、[Rust API 参考](wiki/06-reference/rust-api.md) 和 [采样与 MIDI](wiki/01-lua-composition/samples-midi.md)。

## 30 秒快速开始


Rust 侧注册 Lua 模块：

```rust
fn main() -> mlua::Result<()> {
    let lua = mlua::Lua::new();
    mlua_pulse::register_package_loader(&lua)?;
    lua.load(
        r#"
        local pulse = require("pulse")
        local song = pulse.song()
        assert(song ~= nil)
        "#
    ).exec()
}
```

Lua 侧写一条旋律并导出：

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

local melody = pulse.sequence()
  :notes(pulse.scale("C4", "ionian"))
  :durations({0.25, 0.25, 0.25, 0.25, 0.5, 0.5, 0.5, 1.0})
  :instrument("electric_piano")
  :volume(0.55)
  :velocity(0.62)
  :effect("delay", "eighth_note")

pulse.song()
  :tempo(112)
  :add(melody)
  :master_effect("eq", "warm")
  :master_effect("limiter", "standard")
  :export_wav("output/first-song.wav", {
    sample_rate = 44100,
    normalize = "rms",
    target_db = -16.0,
    true_peak_db = -1.0,
  })
```

## 文档地图


完整教材和参考文档从 [wiki/README.md](wiki/README.md) 开始。README 只保留入口，详细解释都放在 wiki 分卷里。

| 卷册 | 入口 | 适合谁 |
| --- | --- | --- |
| 总览 | [wiki/00-overview/project-scope.md](wiki/00-overview/project-scope.md) | 想先确认项目边界、数据流和术语的人 |
| Lua 编曲 | [wiki/01-lua-composition/getting-started.md](wiki/01-lua-composition/getting-started.md) | 用 Lua 写歌、写 loop、写完整段落的人 |
| 声音设计 | [wiki/02-sound-design/instruments.md](wiki/02-sound-design/instruments.md) | 关心音色、合成、效果链、混音的人 |
| 算法生成 | [wiki/03-generation/generators.md](wiki/03-generation/generators.md) | 用数学序列、L 系统、元胞自动机生成素材的人 |
| 导出工程 | [wiki/04-export/wav-flac-midi.md](wiki/04-export/wav-flac-midi.md) | 处理 WAV、FLAC、MIDI、响度、PCM、性能和故障的人 |
| Rust 集成 | [wiki/05-rust-integration/embedding-lua.md](wiki/05-rust-integration/embedding-lua.md) | 把 `mlua-pulse` 嵌入 Rust 程序或构建 Lua 模块的人 |
| 参考百科 | [wiki/06-reference/lua-api.md](wiki/06-reference/lua-api.md) | 查 Lua API、Rust API 和所有示例的人 |

## 示例运行


每个示例都是一个独立目录：

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

`main.rs` 注册 `pulse` 并执行同目录 Lua 脚本；`script.lua` 写编曲；`output/` 存放导出的 WAV、FLAC、MIDI。长曲、颗粒合成和 FLAC 编码请优先使用 release 构建：

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

完整示例索引见 [wiki/06-reference/examples.md](wiki/06-reference/examples.md)，其中列出了 `foundation_loop`、`capability_expansion`、`algorithm_generators`、`synthesis_algorithms`、`effects_chain`、`phrase_arrangement`、`playback`、`solo_piano`、`mini_symphony`、`fresh_pop`、`kaze_ensemble`、`farewell_ensemble`、`hardcore_edm`、`kawaii_bass_3min`、`moonlight_golden_hall`。

## LuaLS 注解


仓库提供 [types/pulse.meta.lua](types/pulse.meta.lua)，包含 LuaLS 可读取的类型、字段、参数、返回值和中文说明。它是编辑器补全文件，不承担长篇教程职责；教程和 API 解释请读 [wiki/06-reference/lua-api.md](wiki/06-reference/lua-api.md)。

VS Code LuaLS 配置示例：

```json
{
  "Lua.workspace.library": [
    "${workspaceFolder}/types"
  ],
  "Lua.runtime.version": "Lua 5.4"
}
```

## Cargo 特性


特性分三层：**Lua 运行时版本**（互斥，每次只启用一个）、**Lua 获取方式**和**可选开关**。

| 特性 | 含义 |
| --- | --- |
| `default = ["lua54", "vendored"]` | 默认 Lua 5.4 并从源码编译，适合 Rust 程序嵌入 |
| `lua51` / `lua52` / `lua53` / `lua54` / `lua55` | 选择对应标准 Lua 版本（互斥） |
| `luajit` / `luajit52` | LuaJIT，后者兼容 Lua 5.2 语义 |
| `luau` | Roblox Luau 方言 |
| `vendored = ["mlua/vendored"]` | 让所选 Lua 从源码编译，无需系统 Lua 开发库 |
| `module = ["mlua/module"]` | 构建为动态 Lua 模块（cdylib），不要与 `vendored` 同用 |
| `gpu = ["tunes/gpu"]` | 请求 `tunes` 的 GPU 计算路径 |

示例：

```powershell
cargo build
cargo build --no-default-features --features luajit,vendored
cargo build --no-default-features --features lua53,module
cargo run --release --features gpu --example foundation_loop
```

不要用 `cargo check --all-features` 或 `cargo clippy --all-features` 验证本 crate；多个 Lua 版本互斥，同时启用会符号冲突。

## 验证命令


常规验证：

```powershell
cargo fmt --check
cargo test
git diff --check
```

特性组合验证：

```powershell
cargo check --no-default-features --features lua53,vendored
cargo check --no-default-features --features lua54,module
cargo check --features gpu
cargo doc --no-deps
```

模块构建需要带上一个 Lua 版本特性，且不要同时开 `vendored`。

## 项目边界


`mlua-pulse` 提供音乐理论、Lua 链式 DSL、150+ 乐器别名、100+ 鼓声、FM/加法/波表/Karplus-Strong/颗粒合成、效果链、50+ 生成器、采样片段、MIDI 导入导出、WAV/FLAC 导出、响度标准化、原始 PCM userdata 流和播放预览。

它不承诺实时宿主调度、复杂声卡路由、外部插件托管、完整采样库管理或与导出无关的空间音频系统。判断一个能力是否属于本项目，最简单的标准是：它是否让 Lua 编曲更清晰，或让离线导出更可靠。