Ardour/Lua Scripting
更多操作
自 4.7.213 起，Ardour 支持 Lua 脚本。本文档为进行中内容，API 可能变化。
脚本用于扩展 DAW 而无需修改本体：session/user 特定的 edge case（如 voice-activate record-arm 与 roll、按 timecode 重命名 region、solo 某 track 时启动外部应用、生成 automation curve、批量操作快捷方式）。
Overview
Ardour 核心是实时 audio engine，通过发送命令与之交互。多数 Ardour C++ 对象与 method 直接暴露给 Lua，例如 C++ 的 session->set_transport_speed(1.0) 在 Lua 中为 Session:set_transport_speed(1.0)。Ardour 集成 Lua 5.3.5。
脚本类型
| 类型 | 说明 |
|---|---|
| Editor Action Scripts | 用户触发的动作（菜单/快捷键），用于 batch 处理；共 10 个 slot，可绑定键盘快捷键 |
| Editor Hooks/Callbacks | Editor/Mixer GUI 事件触发的动作 |
| Session Scripts | 每个 audio cycle 调用的脚本（session、real-time） |
| DSP Scripts | Audio/MIDI processor，即带 session 访问权限的 plugin（per track/bus、real-time） |
| Script Console | Action Script 的命令行（Menu → Window → Scripting） |
另有 commandline 模式：独立工具 luasession 从命令行直接访问 session（无 GUI），仅提供 load_session / close_session 并暴露 AudioEngine。
Managing scripts
脚本存于 $ARDOUR_DATA_PATH 的 scripts 文件夹（Linux: $HOME/.config/ardour8/scripts；macOS: $HOME/Library/Preferences/Ardour8/scripts；Windows: %localappdata%\ardour8\scripts），文件须以 .lua 结尾。
- Editor Action/Hooks：Menu → Edit → Scripted Actions → Manage（或工具栏右上 action-script 按钮）
- Session Scripts：Menu → Session → Scripting → Add/Remove Script
- DSP Scripts：像普通 plugin 一样添加到 mixer strip 的 processor box
Script layout
- 每个脚本必须有 ardour descriptor table，必填键：name 与 type（大小写敏感的键；type 取值 DSP / Session / EditorHook / EditorAction），可选 author、license、description。
- 脚本须提供 factory 函数（可带 instantiation 参数），返回实际执行的 Lua closure。
- DSP 脚本另需 dsp_run(ins, outs, n_samples) 或 dsp_runmap(...)，以及 dsp_ioconfig() 等配置函数；plugin 参数经全局 CtrlPorts 处理，MIDI 数据经全局 mididata 传入。
Concepts
- 无绑定 constructor：由 Lua 请求 Ardour 创建对象并取回引用。
- 加载后的脚本随 session 保存（不含外部文件引用），保证 session 可移植。
- 脚本本身从不直接执行，只提供 factory。
- 不能使用外部 Lua 模块，脚本必须自包含。
- 多线程上下文被隔离：Editor Action 在 GUI thread 单解释器；每个 Hook callback 有独立解释器（GUI thread）；Session 脚本在主 real-time thread；每个 DSP 脚本在 DSP thread 有独立实例。各上下文可用接口不同——real-time 上下文无法创建 track/导入 audio，GUI thread 无法修改 audio buffer。
Accessing Ardour objects
全局变量 Session 暴露 ARDOUR::Session（Routes、Sources、Regions、Playlists、Locations、Tempo map、Undo/Redo、Ports、Transport 等）。GUI 上下文的解释器还有 Editor 对象，提供 undo/redo、开关窗口、选择对象、import audio 等高层操作并持有当前 UI 状态（snap、zoom 等）。