mlua-pulse 0.1.0

# Rust API


## 查阅方式


本章面向 Rust 集成者。想学习宿主模式请读 [嵌入 Lua](../05-rust-integration/embedding-lua.md)，想直接构造作品请读 [Rust 构造器](../05-rust-integration/rust-builders.md)。本章按模块列出公开入口和导出影响。

crate 名称是 `mlua-pulse`，库名是 `mlua_pulse`。核心依赖为 `tunes = "1.1.0"` 和 `mlua = "0.11.6"`。

## 模块与职责


| 模块 | 职责 |
| --- | --- |
| `lua` | `register` 与 `register_package_loader` |
| `theory` | 音名、音阶、和弦、移调 |
| `composition` | `PulseSequence`、`PulsePhrase`、`PulseSong`、采样、MIDI clip |
| `drums` | 鼓声目录、`PulseDrumGrid`、`PulseDrumMachine` |
| `effects` | 效果目录和 `PulseEffect` 构造 |
| `synthesis` | FM、加法、波表、Karplus-Strong、颗粒合成 |
| `generators` | 数学和生成式序列 |
| `export` | `ExportOptions`、响度标准化、WAV 导出 |
| `files` | 按扩展名导出、FLAC、MIDI、MIDI 导入 |
| `playback` | 本机播放预览 |
| `error` | `PulseError` 与 `PulseResult<T>` |

## 类型与函数


| 名称 | 何时使用 | 参数 | 返回 | 导出影响 |
| --- | --- | --- | --- | --- |
| `mlua_pulse::register` | 手动获得 Lua 模块表 | `&mlua::Lua` | `mlua::Table` | 不导出，只注册 API |
| `mlua_pulse::register_package_loader` | 让 Lua `require("pulse")` | `&mlua::Lua` | `()` | 示例默认入口 |
| `theory::scale` | Rust 侧生成音阶 | root、mode | `Vec<f32>` | 可进入 sequence |
| `PulseSequence::new` | 构造旋律或和声 | 无 | `PulseSequence` | 音频和 MIDI 都可表达 |
| `PulsePhrase::new` | 构造段落 | 无 | `PulsePhrase` | 加入 song 后展开 |
| `PulseSong::new` | 构造作品 | 无 | `PulseSong` | 导出入口 |
| `PulseSampleClip::new` | 引用采样 | path | `PulseSampleClip` | 音频导出渲染，MIDI 不嵌入 |
| `PulseMidiClip` | 编排导入 MIDI | imported.as_clip() | clip | 音频渲染或 MIDI 符号导出 |
| `ExportOptions::new` | 配置导出 | 无 | `ExportOptions` | 影响 WAV/FLAC/MIDI/PCM |
| `files::export_with_options` | 按扩展名导出 | song、path、options | `PulseResult<()>` | 分派 WAV/FLAC/MIDI |

## 构造器速查


`PulseSequence` 常用方法：`with_notes`、`with_chords`、`with_durations`、`with_instrument`、`with_synth`、`with_start_at`、`with_volume`、`with_pan`、`with_velocity`、`with_effect`、`transposed`。

`PulsePhrase` 常用方法：`add_sequence`、`add_drum_grid`、`add_sample_clip`、`add_midi_clip`、`with_repeat_times`。

`PulseSong` 常用方法：`with_tempo`、`add_sequence`、`add_drum_grid`、`add_phrase`、`add_sample_clip`、`add_midi_clip`、`with_master_effect`、`to_tunes_composition`、`to_mixer`。

`ExportOptions` 常用方法：`with_gpu`、`with_sample_rate`、`with_peak_normalization`、`with_rms_normalization`、`with_flac_bits_per_sample`、`with_midi_velocity_gain`、`with_midi_min_velocity`。

### `PulseMidiClip`


`PulseMidiClip` 来自导入后的 MIDI mixer，常见流程是 `let imported_clip = files::import_midi("input.mid")?.as_clip();`，再通过 `PulseSong::new().add_midi_clip(imported_clip)` 或 `PulsePhrase::new().add_midi_clip(imported_clip)` 放进编曲时间线。

音频导出会渲染 MIDI 音符、鼓事件、轨道音量、声像和效果；MIDI 导出不会嵌入采样音频，也不会保存混响、压缩、滤波、母带限制或响度标准化这类音频处理结果。

## 错误条件


Rust 侧统一使用：

```rust
pub type PulseResult<T> = Result<T, PulseError>;
```

常见错误来源包括无效音名、未知调式、未知和弦、无效 duration、音量声像力度越界、未知乐器、未知鼓声、未知效果、未知合成器、未知生成器、采样参数无效、导出扩展名不支持、文件读写失败、未启用 `gpu` 却请求 GPU。

不要在宿主里吞掉 `PulseError`。它们通常包含用户需要修正的字段和值。

## 示例


```rust
use mlua_pulse::composition::{PulsePhrase, PulseSequence, PulseSong};
use mlua_pulse::effects::{effect_from_options, EffectOptions};
use mlua_pulse::export::ExportOptions;
use mlua_pulse::{files, theory};

fn main() -> mlua_pulse::PulseResult<()> {
    let sequence = PulseSequence::new()
        .with_notes(theory::scale("C4", "ionian")?)
        .with_durations(vec![0.25, 0.25, 0.25, 0.25, 0.5, 0.5, 0.5, 1.0])
        .with_instrument("electric_piano")
        .with_volume(0.5)?;

    let phrase = PulsePhrase::new()
        .add_sequence(sequence)
        .with_repeat_times(2)?;

    let song = PulseSong::new()
        .with_tempo(112.0)?
        .add_phrase(phrase)
        .with_master_effect(effect_from_options("limiter", EffectOptions::Preset("standard".into()))?);

    let options = ExportOptions::new().with_rms_normalization(-16.0, -1.0)?;
    files::export_with_options(&song, "output/rust-api.wav", options)
}
```

## Cargo 特性


默认特性是 `lua54` + `vendored`（Lua 5.4，源码编译）。切换 Lua 版本用 `--no-default-features --features <版本>,vendored`，例如 `lua53`、`luajit`、`luau`。动态 Lua 模块使用 `--no-default-features --features lua54,module`。GPU 请求使用 `--features gpu`。不要用 `cargo check --all-features`，因为多个 Lua 版本互斥，同时启用会符号冲突。

## 相关章节


- [嵌入 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)