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 参考、Rust API 参考和采样与 MIDI。

30 秒快速开始

Rust 侧注册 Lua 模块：

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 侧写一条旋律并导出：

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 开始。README 只保留入口，详细解释都放在 wiki 分卷里。

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

示例运行

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

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

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

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，其中列出了 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，包含 LuaLS 可读取的类型、字段、参数、返回值和中文说明。它是编辑器补全文件，不承担长篇教程职责；教程和 API 解释请读 wiki/06-reference/lua-api.md。

VS Code LuaLS 配置示例：

{
  "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 计算路径

示例：

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 版本互斥，同时启用会符号冲突。

验证命令

常规验证：

cargo fmt --check
cargo test
git diff --check

特性组合验证：

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 编曲更清晰，或让离线导出更可靠。

mlua-pulse 0.1.0