Ardour Lua Scripting

Lua is a lightweight programming language which lends itself nicely to embedded into other applications.

In Ardour's case Lua is available:

• DSP Scripts - audio processor - plugins with access to the session
• Session Scripts - realtime, called at the start of every audio cycle
• Editor Action Scripts - user accessible actions (menu, bindings)
• Editor Hooks - event triggered actions, GUI thread
• Script Console - GUI thread (for development)

small, lean, rt-safe, easily bindable.

• Ardour calls Lua (not the other way 'round).
• There are no bound constructors. ie. Lua asks Ardour to create objects (e.g. add a new track), then receives a reference to the object to modify it.
• Scripts, once loaded, are saved with the Session (no reference to external files)
• Lua Scripts are never executed directly. They provide a “factory” method which can have instantiation parameters.
• All Lua interpreters except the DSP-scripts are singleton instances.
  • Session Scripts: The process-callback run all registered scripts in sequence. Session Script have limited access to the Session (realtime-safe). Scripts are registered/unregistered from Menu → Session → Scripting → Add/Remove Script
  • Editor Action Scripts: These are called from the GUI (explicit user action). 10 Slots are available from Menu → Edit → Scripted Actions. Editor Action Scripts have complete access to the Session and to the Editor.
  • Editor Hooks: They're automatically triggered Action Scripts, connect to signals (block the GUI thread while running). – currently not implemented
  • DSP scripts: are like regular plugins with a generic GUI. The context menu for each Route allows to add them. Using Plugin Controls, these are the only scripts that a user can interact with once they're instantiated.
  • ..except the Script Console, which is currently a separate interpreter (Menu > Window > Scripting) which allows to interactively run Lua code. This interpreter is volatile. The state is not saved with the session.

• Descriptor: Name, Author, Description, URL,…
• Factory function: a function which returns the actual script.
• [optional]: list of parameters for the “factory”.

DSP-plugins have additional list of automatable parameters.

An minimal example script looks like:

ardour {
  ["type"]    = "EditorAction",
  name        = "Rewind",
}
  
function factory (params)
  return function ()
    Session:goto_start()
  end
end

Lua has direct access to Ardour internals: C++ classes, methods, data and functions. So writing elaborate scripts requires some knowledge about Ardour's internal interfaces. However the vast majority of simple actions can be done nearly self-contained in Lua.

To access methods or data of specific instances, use a colon ”:”, e.g. Lua Session:get_tracks() is equivalent to C++ _session→get_tracks().

Static variables, static functions, enums or C++ singletons directly access the Object. e.g. Lua: ARDOUR.AudioEngine.create() calls C++ ARDOUR::AudioEngine::create() or Lua: Editing.ImportDistinctFiles refers to the C++ enum Editing::ImportDistinctFiles.

see also Programming in Lua, Object-Oriented Programming.

print (Session:route_by_remote_id(1):name())

a = Session:route_by_remote_id(1);
print (a:name());

print(Session:get_tracks():size())

for i, v in ipairs(Session:unknown_processors():table()) do print(v) end
for i, v in ipairs(Session:get_tracks():table()) do print(v:name()) end

for t in Session:get_tracks():iter() do print(t:name()) end
for r in Session:get_routes():iter() do print(r:name()) end


Session:tempo_map():add_tempo(ARDOUR.Tempo(100,4), ARDOUR.BBT_TIME(4,1,0))


Editor:set_zoom_focus(Editing.ZoomFocusRight)
print(Editing.ZoomFocusRight);
Editor:set_zoom_focus(1)


files = ARDOUR.StringVector();
files:push_back("/home/rgareus/data/coding/ltc-tools/smpte.wav")
pos = -1
Editor:do_import(files, Editing.ImportDistinctFiles, Editing.ImportAsTrack, ARDOUR.SrcQuality.SrcBest, pos, ARDOUR.PluginInfo())

#or in one line:
Editor:do_import(ARDOUR.StringVector():add({"/path/to/file.wav"}), Editing.ImportDistinctFiles, Editing.ImportAsTrack, ARDOUR.SrcQuality.SrcBest, -1, ARDOUR.PluginInfo())

# called when a new session is loaded:
function new_session (name) print("NEW SESSION:", name) end

There's a standalone tool luasession' which allows to access an Ardour session directly from the commandline. Interaction is limited by the fact that most actions are provided by the Ardour Editor/GUI. The tool provides only two special functions load_session and close_session''.

A = ARDOUR.AudioEngine.create()
for i,_ in A:available_backends():iter() do print (i.name) end              
backend = A:set_backend("ALSA", "", "")
print (A:current_backend_name())
for i,_ in backend:enumerate_devices():iter() do print (i.name) end
backend:set_input_device_name("HDA Intel PCH")
backend:set_output_device_name("HDA Intel PCH")
print (backend:buffer_size())
print (A:get_last_backend_error())

s = load_session ("/home/rgareus/Documents/ArdourSessions/lua2/", "lua2")
s:request_transport_speed (1.0)
print (s:transport_rolling())
s:goto_start()
unload_session()