Crate mlua_pulse 

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

Rust API 入口

大多数最终用户会通过 Lua 使用本 crate。Rust 侧通常只需要创建 mlua::Lua，调用 register_package_loader，然后执行 Lua 编曲脚本。

let lua = mlua::Lua::new();
mlua_pulse::register_package_loader(&lua)?;
lua.load(
    r#"
    local pulse = require("pulse")
    assert(math.abs(pulse.note("A4") - 440.0) < 0.01)
    "#
).exec()?;

需要直接在 Rust 中构造作品时，可以使用 composition、export、 files、effects、synthesis 和 generators 模块。

Re-exports

pub use error::PulseError;

pub use error::PulseResult;

Modules

composition

Lua DSL 背后的作品、段落、旋律序列和采样片段构建器。 Song, phrase, sequence, and sample-clip builders used by the Lua DSL.

drums

鼓声目录、步进鼓网格、分层鼓别名和 808 鼓机便捷构建器。 Drum catalogs, step grids, layered drum aliases, and 808-style helpers.

effects

可应用到轨道或 master 的离线效果链。 Track and master effects exposed to Lua and converted into tunes effects.

error

crate 内部错误类型和统一结果别名。 Error and result types shared by the Rust API and Lua bindings.

export

WAV/FLAC 导出选项、响度标准化和导出辅助函数。

files

按文件扩展名分派导出、FLAC/MIDI 辅助函数和 MIDI 导入包装。

generators

tunes::sequences 的 Lua 友好生成器目录和选项解析。 Algorithmic sequence generator catalog and wrappers.

instruments

tunes 乐器预置到 Lua 稳定别名的映射。

midi

MIDI 音符号与频率之间的安全转换函数。

playback

基于 tunes::engine::AudioEngine 的简单播放预览层。 Lightweight playback preview wrappers around tunes::engine::AudioEngine.

rhythm

欧几里得节奏、命名节奏和鼓模式字符串解析。

synthesis

FM、加法、波表、Karplus-Strong 和颗粒合成配置。 Lua-facing synthesis algorithm options and conversion helpers.

theory

音名、音阶、和弦、调式目录和移调工具。

Functions

register

Builds the Lua-facing pulse module table.

register_package_loader

Registers pulse so Lua code can call require("pulse").