mlua-pulse 0.1.0

# 错误处理


## 你会学到什么


- 使用 `PulseResult<T>` 和 `PulseError` 处理 Rust 侧错误。
- 在 Lua 侧用 `pcall` 捕获无效参数和导出失败。
- 识别常见错误来源：音名、时值、音量、采样、MIDI、效果、合成器、生成器、导出。
- 把错误展示给用户，而不是吞掉。

## 适合谁读


宿主开发者、测试编写者和 API 贡献者读本章。用户脚本经常写错路径、参数或效果名，好的错误处理会节省大量排查时间。

## 前置知识


- [嵌入 Lua](embedding-lua.md)
- [Rust 构造器](rust-builders.md)

## 心智模型


Rust 侧返回 `PulseResult<T>`，Lua 侧把错误转换为 `mlua::Error`。用户脚本可以用 `pcall` 捕获；宿主程序可以把错误打印成清楚的诊断。

边界验证应该尽早发生。无效音量、无效 pan、负时值、错误采样 slice、未知效果，都应该在构造或导出前后给出稳定错误。

## 最小可运行例子


```lua
local ok, err = pcall(function()
  pulse.sequence()
    :notes({pulse.note("C4")})
    :durations({})
    :instrument("electric_piano")
end)

if not ok then
  print("pulse error:", err)
end
```

Rust 侧：

```rust
fn run() -> mlua_pulse::PulseResult<()> {
    let sequence = mlua_pulse::composition::PulseSequence::new()
        .with_volume(0.5)?;
    let _ = sequence;
    Ok(())
}
```

## 参数和边界


常见边界：duration 必须大于 0；sequence 事件数量要匹配 durations；volume 范围 `[0, 2]`；pan 范围 `[-1, 1]`；velocity 范围 `[0, 1]`；tempo 必须大于 0；sample rate 必须大于 0；FLAC 位深支持 16 或 24；MIDI velocity gain 范围 `(0, 16]`；MIDI min velocity 范围 `[0, 1]`。

常见名称错误：invalid note、invalid mode、invalid chord、invalid instrument、invalid drum、invalid effect、invalid synth、invalid generator、unsupported export format。

采样常见错误：rate 为 0、time_stretch 为 0、start_at 为负、slice 结束小于开始、fade 为负、loop_for 为 0、volume 或 pan 越界。

## 常见陷阱


不要把 `pcall` 包住后只打印“失败”。错误文本里通常有具体字段和值，例如 `invalid sample option rate: 0`。

不要在文档里承诺未实现的自动修复。比如 MIDI 导出无法保存音频效果，这是格式限制，不是错误处理能解决的问题。

不要让测试依赖模糊错误。测试应检查稳定片段，例如错误类型或关键文本。

## 进阶用法


宿主可以把 Lua 文件名、示例名和输出路径附加到错误上下文中。这样用户看到的不是孤立的 `invalid effect`，而是“在 examples/foo/script.lua 导出 output/foo.wav 时 invalid effect”。

如果你新增 API，请同时新增错误边界测试、LuaLS 注解说明和参考文档。用户最关心的不是“函数存在”，而是出错时知道怎么改。

## 相关章节


- [Lua API](../06-reference/lua-api.md)
- [Rust API](../06-reference/rust-api.md)
- [故障排查](../04-export/troubleshooting.md)
- [Cargo 特性](features.md)