From 04bdde80c543396f1d2c19e5163d922474efab23 Mon Sep 17 00:00:00 2001 From: Robin Gareus Date: Tue, 23 Feb 2016 16:34:49 +0100 Subject: [PATCH] Start documenting Lua scripting --- _manual/24_lua-scripting.html | 14 + _manual/24_lua-scripting/01_brain_dump.html | 404 ++++++++++++++++++++ 2 files changed, 418 insertions(+) create mode 100644 _manual/24_lua-scripting.html create mode 100644 _manual/24_lua-scripting/01_brain_dump.html diff --git a/_manual/24_lua-scripting.html b/_manual/24_lua-scripting.html new file mode 100644 index 0000000..649db7e --- /dev/null +++ b/_manual/24_lua-scripting.html @@ -0,0 +1,14 @@ +--- +layout: default +title: Lua Scripting +--- + +

+Starting with version 4.7.213, Ardour supports Lua scripts. +

+ +

+Lua Integration is Work in Progress and far from complete. +

+ +{% children %} diff --git a/_manual/24_lua-scripting/01_brain_dump.html b/_manual/24_lua-scripting/01_brain_dump.html new file mode 100644 index 0000000..4333509 --- /dev/null +++ b/_manual/24_lua-scripting/01_brain_dump.html @@ -0,0 +1,404 @@ +--- +layout: default +title: Lua Scripting Documentation +--- + +

+This Documention is Work in Progress and far from complete. Also the documented API may be subject to change. +

+ +

Preface

+

+There are cases that a Ardour cannot reasonably cater for with core functionality by itself, either because they're session specific or user specific edge cases. +

+Examples for these include voice-activate (record-arm specific tracks and roll transport depending on signal levels), +rename all regions after a specific timecode, launch an external application when a certain track is soloed, generate automation curves +or simply provide a quick shortcut for a custom batch operation. +

+Cases like this call for means to extend the DAW without actually changing the DAW itself. This is here scripting comes in. +

+"Scripting" refers to tasks that could alternatively be executed step-by-step by a human operator. +

+Lua is a tiny and simple language which is easy to learn, yet allows for comprehensive solutions. +Lua is also a glue language it allows to tie existing component in Ardour together in unprecedented ways, +and most importantly Lua is one of the few scripting-languages which be safely used in a real-time environment. +

+A good introduction to Lua is the book Programming in Lua. The first edition is available online, +but if you have the means buy a copy of the book, which not only helps to support the Lua project, +but provides for a much nicer reading and learning experience. +

+ +

Overview

+

+The core of ardour is a real-time audio engine that runs and processes audio. One interfaces with than engine by sending it commands. +Scripting can be used to interact with or modify active Ardour session. Just like a user uses the Editor/Mixer GUI to modify the state or parameters of the session. +

+Doing this programmatically requires some knowledge about the objects used internally. +Most Ardour C++ objects and their methods are directly exposed to Lua and one can call functions or modify variables: +

+ +
+
+ C++
+ + session->set_transport_speed (1.0); + +
+
+ Lua
+ + Session:set_transport_speed (1.0) + +
+
+
+ +

+You may notice that there is only a small syntactic difference, in this case. +While C++ requires recompiling the application for every change, Lua script can be loaded, written or modified while the application is running. +Lua also abstracts away many of the C++ complexities such as object lifetime, type conversion and null-pointer checks. +

+Close ties with the underlying C++ components is where the power of scripting comes from. +A script can orchestrate interaction of lower-level components which take the bulk of the CPU time of the final program. +

+

+At the time of writing Ardour integrates Lua 5.3.2: Lua 5.3 reference manual. +

+ +

Integration

+

+Like Control surfaces and the GUI, Lua Scripts are confined to certain aspects of the program. Ardour provides the framework and runs Lua (not the other way around). +

+

+In Ardour's case Lua is available: +

+ +
+
Editor Action Scripts
User initiated actions (menu, shortcuts) for batch processing
+
Editor Hooks/Callbacks
Event triggered actions for the Editor/Mixer GUI
+
Session Scripts
Scripts called at the start of every audio cycle (session, real-time)
+
DSP Scripts
Audio/Midi processor - plugins with access to the Ardour session (per track/bus, real-time)
+
Script Console
Action Script commandline
+
+ +

+There are is also a special mode: +

+
+
Commandline Tool
Replaces the complete Editor GUI, direct access to libardour (no GUI) from the commandline.
+ Be aware that the vast majority of complex functionality is provided by the Editor UI.
+
+ +

Managing Scripts

+ +

+Ardour searches for Lua scripts in the scripts folder in $ARDOUR_DATA_PATH, +Apart from scripts included directly with Ardour, this includes

+ + + + +
GNU/Linux$HOME/.config/ardour4/scripts
Mac OS X$HOME/Library/Preferences/Ardour4/scripts
Windows%localappdata%\ardour4\scripts
+ +

Files must end with .lua file extension.

+ +

Scripts are managed via the GUI

+
+
Editor Action Scripts
Menu → Edit → Scripted Actions → Manage
+
Editor Hooks/Callbacks
Menu → Edit → Scripted Actions → Manage
+
Session Scripts
Menu → Session → Scripting → Add/Remove Script
+
DSP Scripts
Mixer-strip → context menu (right click) → New Lua Proc
+
Script Console
Menu → Window → Scripting
+
+ +

Script Layout

+ + + +

A minimal example script looks like:

+
+

+	ardour {
+	  ["type"]    = "EditorAction",
+	  name        = "Rewind",
+	}
+
+	function factory (unused_params)
+	  return function ()
+	   Session:goto_start()  -- rewind the transport
+	  end
+	end
+
+
+ +

+The common part for all scripts is the "Descriptor". It's a Lua function which returns a table (key/values) with the following keys (the keys are case-sensitive): +

+
+
type [required]
one of "DSP", "Session", "EditorHook", "EditorAction" (the type is not case-sensitive)
+
name [required]
Name/Title of the script
+
authorYour Name +
license The license of the script (e.g. "GPL" or "MIT") +
descriptionA longer text explaining to the user what the script does +
+ +

+Scripts that come with Ardour (currently mostly examples) can be found in the Source Tree. +

+ +

Action Scripts

+

Action scripts are the simplest form. An anonymous Lua function is called whenever the action is triggered. A simple action script is shown above.

+

There are 10 action script slots available, each of which is a standard GUI action available from the menu and hence can be bound to a keyboard shortcut

+ +

Session Scripts

+

Session scripts similar to Actions Scripts, except the anonymous function is called periodically every process cycle. +The function receives a single parameter - the number of audio samples which are processed in the given cycle

+
+

+ardour {
+  ["type"]    = "session",
+  name        = "Example Session Script",
+  description = [[
+  An Example Ardour Session Script.
+  This example stops the transport after rolling for a specific time.]]
+}
+
+
+-- instantiation options, these are passed to the "factory" method below
+function sess_params ()
+  return
+  {
+    ["print"]  = { title = "Debug Print (yes/no)", default = "no", optional = true },
+    ["time"] = { title = "Timeout (sec)", default = "90", optional = false },
+  }
+end
+
+function factory (params)
+  return function (n_samples)
+    local p = params["print"] or "no"
+    local timeout = params["time"] or 90
+    a = a or 0
+    if p ~= "no" then print (a, n_samples, Session:frame_rate (), Session:transport_rolling ()) end -- debug output (not rt safe)
+    if (not Session:transport_rolling()) then
+      a = 0
+      return
+    end
+    a = a + n_samples
+    if (a > timeout * Session:frame_rate()) then
+      Session:request_transport_speed(0.0, true)
+    end
+  end
+end
+
+
+ +

Action Hooks

+

Action hook scripts must define an additional function which returns a Set of Signal that which trigger the callback (documenting available slots and their parameters remains to be done).

+
+

+ardour {
+  ["type"]    = "EditorHook",
+  name        = "Hook Example",
+  description = "Rewind On Solo Change, Write a file when regions are moved.",
+}
+
+function signals ()
+  s = LuaSignal.Set()
+  s:add (
+    {
+      [LuaSignal.SoloActive] = true,
+      [LuaSignal.RegionPropertyChanged] = true
+    }
+  )
+  return s
+end
+
+function factory (params)
+  return function (signal, ref, ...)
+    -- print (signal, ref, ...)
+
+    if (signal == LuaSignal.SoloActive) then
+      Session:goto_start()
+    end
+
+    if (signal == LuaSignal.RegionPropertyChanged) then
+      obj,pch = ...
+      file = io.open ("/tmp/test" ,"a")
+      io.output (file
+      io.write (string.format ("Region: '%s' pos-changed: %s, length-changed: %s\n",
+        obj:name (),
+        tostring (pch:containsFramePos (ARDOUR.Properties.Start)),
+        tostring (pch:containsFramePos (ARDOUR.Properties.Length))
+        ))
+      io.close (file)
+    end
+  end
+end
+
+
+ +

DSP Scripts

+

See the scripts folder for examples for now.

+

Some notes for further doc:

+ + +

Accessing Ardour Objects

+

+The top most object in Ardour is the ARDOUR::Session. +Fundamentally, a Session is just a collection of other things: +Routes (tracks, busses), Sources (Audio/Midi), Regions, Playlists, Locations, Tempo map, Undo/Redo history, Ports, Transport state & controls, etc. +

+Every Lua interpreter can access it via the global variable Session. +

+GUI context interpreters also have an additional object in the global environment: The Ardour Editor. The Editor provides access to high level functionality which is otherwise triggered via GUI interaction such as undo/redo, open/close windows, select objects, drag/move regions. It also holds the current UI state: snap-mode, zoom-range, etc. +The Editor also provides complex operations such as "import audio" which under the hood, creates a new Track, adds a new Source Objects (for every channel) with optional resampling, creates both playlist and regions and loads the region onto the Track all the while displaying a progress information to the user. +

+ +

+Documenting the bound C++ methods and class hierarchy is somewhere on the ToDo list. +Meanwhile luabindings.cc is the best we can offer. +

+ +

Concepts

+ +

+Ardour is a highly multithreaded application and interaction between the different threads, particularly real-time threads, needs to to be done with care. +This part has been abstracted away by providing separate Lua interpreters in different contexts and restricting available interaction: +

+ +

+The available interfaces differ between contexts. e.g. it is not possible to create new tracks or import audio from real-time context; while it is not possible to modify audio buffers from the GUI thread. +

+ +

Current State

+Fully functional, yet still in a prototyping stage: + + + + +

Examples

+

Apart from the scripts included with the source-code here are a few examples without further comments... + +

Editor Console Examples

+
+

+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
+
+
+route = Session:route_by_remote_id(1)
+processor = route:nth_plugin(0)
+plugininsert = processor:to_insert()
+
+plugin = plugininsert:plugin(0)
+print (plugin:label())
+print (plugin:parameter_count())
+
+x = ARDOUR.ParameterDescriptor ()
+_, t = plugin:get_parameter_descriptor(2, x) -- port #2
+paramdesc = t[2]
+print (paramdesc.lower)
+
+ctrl = ARDOUR.EvoralParameter(ARDOUR.AutomationType.PluginAutomation, 0, 2)
+ac = plugininsert:automation_control(ctrl, false)
+print (ac:get_value ())
+ac:set_value(1.0, PBD.GroupControlDisposition.NoGroup)
+
+
+ +

Commandline Session

+

The standalone tool luasession allows one to access an Ardour session directly from the commandline. +Interaction is limited by the fact that most actions in Ardour are provided by the Editor GUI. +

+luasession provides only two special functions load_session and close_session and exposes the AudioEngine instance as global variable. +

+ +
+

+for i,_ in AudioEngine:available_backends():iter() do print (i.name) end
+
+backend = AudioEngine:set_backend("ALSA", "", "")
+print (AudioEngine: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 (AudioEngine: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()
+close_session()
+
+
+