查看“︁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。

== 脚本类型 ==
{| class="wikitable"
|-
! 类型
! 说明
|-
| 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/Lua Scripting/Class Reference|ARDOUR::Session]]（Routes、Sources、Regions、Playlists、Locations、Tempo map、Undo/Redo、Ports、Transport 等）。GUI 上下文的解释器还有 Editor 对象，提供 undo/redo、开关窗口、选择对象、import audio 等高层操作并持有当前 UI 状态（snap、zoom 等）。

== 相关页面 ==
* [[Ardour/Lua Scripting/Class Reference|Class Reference]]
* [[Ardour/Working-with-plugins/Processor-box|Processor Boxes]]