Redesign Session+Route Template Meta Script API

Remove special-cased script types. Allow Action-Scripts to be re-used
for session-setup or route-templates.

6 files changed, 90 insertions, 30 deletions

diff --git a/scripts/_route_template_example.lua b/scripts/_route_template_example.lua
index 9018fc0dda..0f460de25c 100644
--- a/scripts/_route_template_example.lua
+++ b/scripts/_route_template_example.lua
@@ -1,11 +1,52 @@
 ardour {
-	["type"]    = "TrackSetup",
-	name        = "Route Test",
-	description = [[ FOR TESTING AND PROTOTYING ONLY ]]
+	["type"]    = "EditorAction",
+	name        = "Generic Audio Track",
+	description = [[Example ]]
 }
 
--- DON'T COUNT ON THIS TO REMAIN AS IS.
--- This may turn into a factory method, re-usable as ActionScript.
-function session_setup ()
-	Session:new_audio_track (1, 1, nil, 1, "Hello",  ARDOUR.PresentationInfo.max_order, ARDOUR.TrackMode.Normal)
+-- If a route_setup function is present in an Editor Action Script
+-- the script is also listed in the "add track/bus" dialog as meta-template
+--
+-- The function is expected to return a Lua table. The table may be empty.
+function route_setup ()
+	local e = Session:engine()
+	local _, t = e:get_backend_ports ("", ARDOUR.DataType("audio"), ARDOUR.PortFlags.IsOutput | ARDOUR.PortFlags.IsPhysical, C.StringVector())
+	return
+	{
+		-- keys control which AddRouteDialog controls are made sensitive.
+		-- The following keys accept a default value to pre-seed the dialog
+		['how_many'] = t[4]:size(),
+		['name'] = 'Audio',
+		['channels'] = 2,
+		-- these keys just need to be set (to something other than nil)
+		['insert_at'] = ARDOUR.PresentationInfo.max_order,
+		['group'] = false,
+		--[[
+		['track_mode'] = ARDOUR.TrackMode.Normal,
+		['strict_io'] = true,
+		--]]
+	}
 end
+
+-- The Script can be used as EditorAction in which case it can
+-- optionally provide instantiation parmaters
+function action_params ()
+	return
+	{
+		['how_many'] = { title = "How Many tracks to add", default = "1" },
+		["name"]     = { title = "Track Name Prefix", default = "Audio" },
+	}
+end
+
+
+function factory (params) return function ()
+	local p         = params or route_setup ()
+	local name      = p["name"] or 'Audio'
+	local how_many  = p["how_many"] or 1
+	local channels  = p["channels"] or 1
+	local insert_at = p["insert_at"] or ARDOUR.PresentationInfo.max_order;
+	local group     = p["group"] or nil
+
+	Session:new_audio_track (channels, channels, group, how_many, name, insert_at, ARDOUR.TrackMode.Normal)
+
+end end
diff --git a/scripts/_template_band.lua b/scripts/_template_band.lua
index bf73261217..ccfb26d7c6 100644
--- a/scripts/_template_band.lua
+++ b/scripts/_template_band.lua
@@ -1,5 +1,5 @@
 ardour {
-	["type"]    = "SessionSetup",
+	["type"]    = "SessionInit",
 	name        = "Live Band Recording Session",
 	description = [[
 This template helps create the tracks for a typical pop/rock band.
@@ -10,7 +10,7 @@ Each track comes with its pre-assigned grouping, routing, EQ and plugins.
 ]]
 }
 
-function session_setup ()
+function factory () return function ()
 
 	--prompt the user for the tracks they'd like to instantiate
 	local dialog_options = {
@@ -92,4 +92,4 @@ function session_setup ()
 	Editor:access_action("Editor","fit_all_tracks")
 
 	Session:save_state("");
-end
+end end
diff --git a/scripts/_template_example.lua b/scripts/_template_example.lua
index bf895dccf2..9656fd1473 100644
--- a/scripts/_template_example.lua
+++ b/scripts/_template_example.lua
@@ -1,5 +1,5 @@
 ardour {
-	["type"]    = "SessionSetup",
+	["type"]    = "SessionInit",
 	name        = "Recording Session",
 	description = [[Add as many mono tracks to the new session as there are physical audio inputs and optionally record-arm them.]]
 }
@@ -7,21 +7,28 @@ ardour {
 ---- For use with templates: Session Template setup-hook
 --
 -- If a script named 'template.lua' exists in a session-template folder
--- the `session_setup` function of the script is called after
--- creating the session from the template.
+-- the function produced by the 'factory' function of the script is called
+-- once after creating the session from the template.
 --
 -- (e.g. ~/.config/ardour5/templates/Template-Name/template.lua)
 --
 --
----- For use as meta-session
+---- For use as meta-session (specic session-setup scripts)
 --
--- Every Lua script in the script-folder of type "SessionSetup"
+-- Every Lua script in the script-folder of type "SessionInit"
 -- is listed as implicit template in the new-session dialog.
--- The scripts 'session_setup' function  is called once after
--- creating a new, empty session.
+-- The function produced by the scripts `factory` function is called
+-- once after creating a new, empty session.
 --
+---- For use as meta-session (general purpose Actions)
+--
+-- In some cases normal action scripts can also serve as session-setup
+-- To include those ActionScripts in the template-list the script needs
+-- to implement an additional function
+--      function session_setup () return true end;
+-- The script's factory will be called without any parameters
 
-function session_setup ()
+function factory () return function ()
 	local e = Session:engine()
 	-- from the engine's POV readable/capture ports are "outputs"
 	local _, t = e:get_backend_ports ("", ARDOUR.DataType("audio"), ARDOUR.PortFlags.IsOutput | ARDOUR.PortFlags.IsPhysical, C.StringVector())
@@ -50,4 +57,4 @@ function session_setup ()
 	end
 
 	Session:save_state("");
-end
+end end
diff --git a/scripts/_tracks_band.lua b/scripts/_tracks_band.lua
index 346a17cd9b..e7b9084d35 100644
--- a/scripts/_tracks_band.lua
+++ b/scripts/_tracks_band.lua
@@ -1,5 +1,5 @@
 ardour {
-	["type"]    = "TrackSetup",
+	["type"]    = "EditorAction",
 	name        = "Live Band Recording Session",
 	description = [[
 This template helps create the tracks for a typical pop/rock band.
@@ -11,10 +11,12 @@ Each track will be pre-assigned with a color.
 Optionally, tracks may be assigned to sensible Groups ( vocals, guitars, drums )
 
 Optionally, tracks may be assigned Gates and other plugins.
-    ]]
+]]
 }
 
-function session_setup ()
+function route_setup () return {} end
+
+function factory () return function ()
 
     --prompt the user for the tracks they'd like to instantiate
 	local dialog_options = {
@@ -334,4 +336,4 @@ function session_setup ()
     Editor:access_action("Editor","fit_all_tracks")
 
 	Session:save_state("");
-end
+end end
diff --git a/scripts/_tracks_generic_audio.lua b/scripts/_tracks_generic_audio.lua
index 96034647b7..28d174ae8b 100644
--- a/scripts/_tracks_generic_audio.lua
+++ b/scripts/_tracks_generic_audio.lua
@@ -1,5 +1,5 @@
 ardour {
-	["type"]    = "TrackSetup",
+	["type"]    = "EditorAction",
 	name        = "Add tracks",
 	description = [[
 This template creates audio tracks.
@@ -12,7 +12,17 @@ You will be prompted for:
 ]]
 }
 
-function session_setup ()
+function route_setup ()
+	return
+	{
+		['Insert_at'] = ARDOUR.PresentationInfo.max_order;
+	}
+end
+
+function factory (params) return function ()
+	local p         = params or route_setup ()
+	local insert_at = p["insert_at"] or ARDOUR.PresentationInfo.max_order;
+
 	local e = Session:engine()
 	-- from the engine's POV readable/capture ports are "outputs"
 	local _, t = e:get_backend_ports ("", ARDOUR.DataType("audio"), ARDOUR.PortFlags.IsOutput | ARDOUR.PortFlags.IsPhysical, C.StringVector())
@@ -31,11 +41,11 @@ function session_setup ()
 	end
 
 	-- create tracks
-	local tl = Session:new_audio_track (1, 1, nil, rv['tracks'], "",  ARDOUR.PresentationInfo.max_order, ARDOUR.TrackMode.Normal)
+	local tl = Session:new_audio_track (1, 1, nil, rv['tracks'], "", insert_at, ARDOUR.TrackMode.Normal)
 	-- and optionally record-arm them
 	if rv['recarm'] then
 		for track in tl:iter() do
 			track:rec_enable_control ():set_value (1, PBD.GroupControlDisposition.NoGroup)
 		end
 	end
-end
+end end
diff --git a/scripts/session_template_advanced.lua b/scripts/session_template_advanced.lua
index 3e8d95f5b2..d9f0a03ed2 100644
--- a/scripts/session_template_advanced.lua
+++ b/scripts/session_template_advanced.lua
@@ -1,11 +1,11 @@
 ardour {
-	["type"]    = "SessionSetup",
+	["type"]    = "SessionInit",
 	name        = "Advanced Session",
 	description = [[Allows to configure master-bus and autoconnect]],
 	master_bus  = 0
 }
 
-function session_setup ()
+function factory () return function ()
 
 	local auto_connect_in = {
 		[0] = "Manually",
@@ -56,4 +56,4 @@ function session_setup ()
 	ARDOUR.config():set_output_auto_connect (rv['ac_output'])
 
 	Session:save_state("");
-end
+end end