update and cleanup lua example scripts

scripts/editor_test.lua

@@ -1,16 +0,0 @@
-ardour {
-	["type"]    = "EditorAction",
-	name        = "Action Test",
-	license     = "MIT",
-	author      = "Robin Gareus",
-	email       = "robin@gareus.org",
-	site        = "http://gareus.org",
-	description = [[ An Example Ardour Editor Action Plugin.]]
-}
-
-function factory (params)
-	return function ()
-		for n in pairs(_G) do print(n) end
-		print ("----")
-	end
-end

scripts/s_fader_automation.lua

@@ -1,46 +1,53 @@
-ardour { ["type"] = "Snippet", name = "fader automation" }
+ardour { ["type"] = "Snippet", name = "Fader Automation" }
 
 function factory () return function ()
 	local playhead = Session:transport_frame ()
 	local samplerate = Session:nominal_frame_rate ()
 
 	-- get selected tracks
-	rl = Editor:get_selection().tracks:routelist()
+	rl = Editor:get_selection ().tracks:routelist ()
+
 	-- prepare undo operation
 	Session:begin_reversible_command ("Fancy Fade Out")
 	local add_undo = false -- keep track if something has changed
+
 	-- iterate over selected tracks
-	for r in rl:iter() do
-		local ac = r:amp():gain_control() -- ARDOUR:AutomationControl
-		local acl = ac:alist() -- ARDOUR:AutomationControlList (state, high-level)
-		local cl = acl:list()  -- Evoral:ControlList (actual events)
+	for r in rl:iter () do
+		local ac = r:amp ():gain_control () -- ARDOUR:AutomationControl
+		local al = ac:alist () -- ARDOUR:AutomationList (state, high-level)
+		local cl = al:list ()  -- Evoral:ControlList (actual events)
 
-		ac:set_automation_state(ARDOUR.AutoState.Touch)
-
-		if cl:isnil() then
+		if cl:isnil () then
 			goto out
 		end
 
+		-- set automation state to "Touch"
+		ac:set_automation_state (ARDOUR.AutoState.Touch)
+
 		-- query the value at the playhead position
-		local g = cl:eval(playhead)
+		local g = cl:eval (playhead)
 
 		-- get state for undo
-		local before = acl:get_state()
+		local before = al:get_state ()
 
 		-- delete all events after the playhead...
 		cl:truncate_end (playhead)
+
 		-- ...and generate some new ones.
 		for i=0,50 do
+			-- use a sqrt fade-out (the shape is recognizable, and otherwise
+			-- not be possible to achieve with existing ardour fade shapes)
 			cl:add (playhead + i * samplerate / 50,
 			        g * (1 - math.sqrt (i / 50)),
 			        false, true)
 		end
+
 		-- remove dense events
-		cl:thin(20)
+		cl:thin (20)
 
 		-- save undo
-		local after = acl:get_state()
-		Session:add_command (acl:memento_command(before, after))
+		local after = al:get_state ()
+		Session:add_command (al:memento_command (before, after))
 		add_undo = true
 
 		::out::

scripts/s_foreach_track.lua

@@ -1,11 +1,10 @@
-ardour { ["type"] = "Snippet", name = "foreach track" }
+ardour { ["type"] = "Snippet", name = "Foreach Track" }
 
 function factory () return function ()
 	for r in Session:get_tracks():iter() do
 		print (r:name())
 		-- see http://manual.ardour.org/lua-scripting/class_reference/#ARDOUR:Track
 		-- for available methods e.g.
-		--
 		r:set_active (true, nil)
 	end
 end end

scripts/s_plugin_automation.lua

@@ -1,25 +1,33 @@
-ardour { ["type"] = "Snippet", name = "plugin automation2" }
+ardour { ["type"] = "Snippet", name = "Plugin automation" }
 
 function factory () return function ()
+	-- query playhead position and session sample-rate
 	local playhead = Session:transport_frame ()
 	local samplerate = Session:nominal_frame_rate ()
 
+	-- get Track/Bus with RID 3
 	local r = Session:route_by_remote_id(3)
-	-- get AutomationControList, ControlList and ParameterDescriptor
-	local acl, cl, pd = ARDOUR.LuaAPI.plugin_automation (r:nth_plugin (0), 0)
+	-- make sure the track object exists
+	assert (not r:isnil ())
 
-	if not acl:isnil() then
+	-- get AutomationList, ControlList and ParameterDescriptor
+	-- of the first plugin's first parameter
+	-- see http://manual.ardour.org/lua-scripting/class_reference/#ARDOUR:LuaAPI
+	local al, cl, pd = ARDOUR.LuaAPI.plugin_automation (r:nth_plugin (0), 0)
+
+	if not al:isnil () then
 		print ("Parameter Range", pd.lower, pd.upper)
-		print ("Current value", cl:eval(playhead))
+		print ("Current value", cl:eval (playhead))
 
 		-- prepare undo operation
 		Session:begin_reversible_command ("Automatix")
-		local before = acl:get_state()
+		-- remember current AutomationList state
+		local before = al:get_state()
 
 		-- remove future automation
 		cl:truncate_end (playhead)
 
-		-- add new data points after the playhead 1 sec min..max
+		-- add new data points after the playhead 1 sec, min..max
 		-- without guard-points, but with initial (..., false, true)
 		for i=0,10 do
 			cl:add (playhead + i * samplerate / 10,
@@ -28,8 +36,8 @@ function factory () return function ()
 		end
 
 		-- save undo
-		local after = acl:get_state()
-		Session:add_command (acl:memento_command(before, after))
+		local after = al:get_state()
+		Session:add_command (al:memento_command(before, after))
 		Session:commit_reversible_command (nil)
 	end
 end end

scripts/s_selection.lua

@@ -0,0 +1,60 @@
+ardour { ["type"] = "Snippet", name = "Editor Selection" }
+
+function factory () return function ()
+	-- http://manual.ardour.org/lua-scripting/class_reference/#ArdourUI:Selection
+	-- the Ardour Selection can include multiple items
+	-- (regions, tracks, ranges, markers, automation, midi-notes etc)
+	local sel = Editor:get_selection ()
+
+	--
+	-- At the point of writing the following data items are available
+	--
+	
+	-- Range selection, total span of all ranges (0, 0 if no time range is selected)
+	if sel.time:start () < sel.time:end_frame () then
+		print ("Total Range:", sel.time:start (), sel.time:end_frame ())
+	end
+
+	-- Range selection, individual ranges.
+	for ar in sel.time:iter () do
+		-- each of the items is a
+		-- http://manual.ardour.org/lua-scripting/class_reference/#ARDOUR:AudioRange
+		print ("Range:", ar.id, ar.start, ar._end)
+	end
+
+	-- Track/Bus Selection
+	-- http://manual.ardour.org/lua-scripting/class_reference/#ArdourUI:TrackSelection
+	for r in sel.tracks:routelist ():iter () do
+		-- each of the items is a
+		-- http://manual.ardour.org/lua-scripting/class_reference/#ARDOUR:Route
+		print ("Route:", r:name ())
+	end
+
+	-- Region selection
+	-- http://manual.ardour.org/lua-scripting/class_reference/#ArdourUI:RegionSelection
+	for r in sel.regions:regionlist ():iter () do
+		-- each of the items is a
+		-- http://manual.ardour.org/lua-scripting/class_reference/#ARDOUR:Region
+		print ("Region:", r:name ())
+	end
+
+	-- Markers
+	-- http://manual.ardour.org/lua-scripting/class_reference/#ArdourUI:MarkerSelection
+	-- Note: Marker selection is not cleared and currently (Ardour-4.7) points
+	--       to the most recently selected marker.
+	for m in sel.markers:iter () do
+		-- each of the items is a
+		-- http://manual.ardour.org/lua-scripting/class_reference/#ARDOURUI::ArdourMarker
+		print ("Marker:", m:name (), m:position(), m:_type())
+	end
+
+	----------------------------------------------------------
+	-- The total time extents of all selected regions and ranges
+	local ok, ext = Editor:get_selection_extents (0, 0)
+	if ok then
+		print ("Selection Extents:", ext[1], ext[2])
+	else
+		print ("No region or range is selected")
+	end
+
+end end