ARDOUR::LuaAPI Namespace Reference

Classes
class	Vamp
class	Rubberband

Functions
int	datatype_ctor_null (lua_State *lua)
int	datatype_ctor_audio (lua_State *L)
int	datatype_ctor_midi (lua_State *L)
std::shared_ptr< Processor >	new_send (Session *s, std::shared_ptr< ARDOUR::Route > r, std::shared_ptr< ARDOUR::Processor > p)
std::shared_ptr< ARDOUR::Processor >	nil_processor ()
std::shared_ptr< ARDOUR::Processor >	new_luaproc_with_time_domain (ARDOUR::Session *s, const std::string &p, Temporal::TimeDomain td)
std::shared_ptr< ARDOUR::Processor >	new_luaproc (ARDOUR::Session *s, const std::string &p)
std::list< std::shared_ptr< ARDOUR::PluginInfo > >	list_plugins ()
std::string	dump_untagged_plugins ()
std::shared_ptr< ARDOUR::PluginInfo >	new_plugin_info (const std::string &id, ARDOUR::PluginType type)
std::shared_ptr< ARDOUR::Processor >	new_plugin_with_time_domain (ARDOUR::Session *s, const std::string &id, ARDOUR::PluginType type, Temporal::TimeDomain td, const std::string &preset="")
std::shared_ptr< ARDOUR::Processor >	new_plugin (ARDOUR::Session *s, const std::string &id, ARDOUR::PluginType type, const std::string &preset="")
bool	set_processor_param (std::shared_ptr< ARDOUR::Processor > proc, uint32_t which, float value)
float	get_processor_param (std::shared_ptr< Processor > proc, uint32_t which, bool &ok)
bool	reset_processor_to_default (std::shared_ptr< Processor > proc)
bool	set_plugin_insert_param (std::shared_ptr< ARDOUR::PluginInsert > pi, uint32_t which, float value)
float	get_plugin_insert_param (std::shared_ptr< ARDOUR::PluginInsert > pi, uint32_t which, bool &ok)
bool	set_plugin_insert_property (std::shared_ptr< ARDOUR::PluginInsert > pi, std::string const &uri, luabridge::LuaRef value)
int	get_plugin_insert_property (lua_State *p)
int	plugin_automation (lua_State *lua)
int	desc_scale_points (lua_State *p)
bool	set_automation_data (std::shared_ptr< ARDOUR::AutomationControl > ac, luabridge::LuaRef tbl, double thin=-1)
int	hsla_to_rgba (lua_State *lua)
int	color_to_rgba (lua_State *lua)
std::string	ascii_dtostr (const double d)
int	build_filename (lua_State *lua)
int	sample_to_timecode (lua_State *L)
int	timecode_to_sample (lua_State *L)
int	sample_to_timecode_lua (lua_State *L)
int	timecode_to_sample_lua (lua_State *L)
int	simple_export (lua_State *L)
bool	wait_for_process_callback (size_t n_cycles, int64_t timeout_ms)
void	segfault ()
std::vector< std::string >	env ()
std::shared_ptr< Evoral::Note< Temporal::Beats > >	new_noteptr (uint8_t, Temporal::Beats, Temporal::Beats, uint8_t, uint8_t)
std::list< std::shared_ptr< Evoral::Note< Temporal::Beats > > >	note_list (std::shared_ptr< ARDOUR::MidiModel >)
std::list< std::shared_ptr< Evoral::Event< Temporal::Beats > > >	sysex_list (std::shared_ptr< ARDOUR::MidiModel >)
std::list< std::shared_ptr< Evoral::PatchChange< Temporal::Beats > > >	patch_change_list (std::shared_ptr< ARDOUR::MidiModel >)

Function Documentation

ascii_dtostr()

std::string ARDOUR::LuaAPI::ascii_dtostr

(

const double

d

)

build_filename()

int ARDOUR::LuaAPI::build_filename

(

lua_State *

lua

)

Creates a filename from a series of elements using the correct separator for filenames.

No attempt is made to force the resulting filename to be an absolute path. If the first element is a relative path, the result will be a relative path.

color_to_rgba()

int ARDOUR::LuaAPI::color_to_rgba

(

lua_State *

lua

)

A convenience function to expand RGBA parameters from an integer

convert a Canvas::Color (uint32_t 0xRRGGBBAA) into double RGBA values which can be passed as parameters to Cairo::Context::set_source_rgba

Example:

local r, g, b, a = ARDOUR.LuaAPI.color_to_rgba (0x88aa44ff)
cairo_ctx:set_source_rgba (ARDOUR.LuaAPI.color_to_rgba (0x11336699)

Returns

4 parameters: red, green, blue, alpha (in range 0..1)

datatype_ctor_audio()

int ARDOUR::LuaAPI::datatype_ctor_audio

(

lua_State *

L

)

convenience constructor for DataType::AUDIO with managed lifetime

Returns

DataType::AUDIO

datatype_ctor_midi()

int ARDOUR::LuaAPI::datatype_ctor_midi

(

lua_State *

L

)

convenience constructor for DataType::MIDI with managed lifetime

Returns

DataType::MIDI

datatype_ctor_null()

int ARDOUR::LuaAPI::datatype_ctor_null

(

lua_State *

lua

)

convenience constructor for DataType::NIL with managed lifetime

Returns

DataType::NIL

desc_scale_points()

int ARDOUR::LuaAPI::desc_scale_points

(

lua_State *

p

)

dump_untagged_plugins()

std::string ARDOUR::LuaAPI::dump_untagged_plugins

(

)

Write a list of untagged plugins to a file, so we can bulk-tag them

Returns

path to XML file or empty string on error

env()

std::vector<std::string> ARDOUR::LuaAPI::env

(

)

Return system environment variables (POSIX environ)

get_plugin_insert_param()

float ARDOUR::LuaAPI::get_plugin_insert_param	(	std::shared_ptr< ARDOUR::PluginInsert >	pi,
		uint32_t	which,
		bool &	ok
	)

get a plugin control parameter value

Parameters

pi	Plugin-Insert
which	control port to query (starting at 0, including ports of type input and output)
ok	boolean variable contains true or false after call returned. to be checked by caller before using value.

Returns

value

get_plugin_insert_property()

int ARDOUR::LuaAPI::get_plugin_insert_property

(

lua_State *

p

)

get a plugin property (LV2 plugins only)

Parameters

p	two arguments: Plugin-Insert, URI of the property

Returns

value, depending on datatype or nil if property is not found

get_processor_param()

float ARDOUR::LuaAPI::get_processor_param	(	std::shared_ptr< Processor >	proc,
		uint32_t	which,
		bool &	ok
	)

get a plugin control parameter value

Parameters

proc	Plugin-Processor
which	control port to set (starting at 0, including ports of type input and output))
ok	boolean variable contains true or false after call returned. to be checked by caller before using value.

Returns

value

hsla_to_rgba()

int ARDOUR::LuaAPI::hsla_to_rgba

(

lua_State *

lua

)

A convenience function for colorspace HSL to RGB conversion. All ranges are 0..1

Example:

local r, g, b, a = ARDOUR.LuaAPI.hsla_to_rgba (hue, saturation, luminosity, alpha)

Returns

4 parameters: red, green, blue, alpha (in range 0..1)

list_plugins()

std::list<std::shared_ptr<ARDOUR::PluginInfo> > ARDOUR::LuaAPI::list_plugins

(

)

List all installed plugins

new_luaproc()

std::shared_ptr<ARDOUR::Processor> ARDOUR::LuaAPI::new_luaproc	(	ARDOUR::Session *	s,
		const std::string &	p
	)

new_luaproc_with_time_domain()

std::shared_ptr<ARDOUR::Processor> ARDOUR::LuaAPI::new_luaproc_with_time_domain	(	ARDOUR::Session *	s,
		const std::string &	p,
		Temporal::TimeDomain	td
	)

create a new Lua Processor (Plugin)

Parameters

s	Session Handle
p	Identifier or Name of the Processor
td	Time domain (audio or beats) for any automation data

Returns

Processor object (may be nil)

new_noteptr()

std::shared_ptr<Evoral::Note<Temporal::Beats> > ARDOUR::LuaAPI::new_noteptr	(	uint8_t	,
		Temporal::Beats	,
		Temporal::Beats	,
		uint8_t	,
		uint8_t
	)

new_plugin()

std::shared_ptr<ARDOUR::Processor> ARDOUR::LuaAPI::new_plugin	(	ARDOUR::Session *	s,
		const std::string &	id,
		ARDOUR::PluginType	type,
		const std::string &	preset = ""
	)

new_plugin_info()

std::shared_ptr<ARDOUR::PluginInfo> ARDOUR::LuaAPI::new_plugin_info	(	const std::string &	id,
		ARDOUR::PluginType	type
	)

search a Plugin

Parameters

id	Plugin Name, ID or URI
type	Plugin Type

Returns

PluginInfo or nil if not found

new_plugin_with_time_domain()

std::shared_ptr<ARDOUR::Processor> ARDOUR::LuaAPI::new_plugin_with_time_domain	(	ARDOUR::Session *	s,
		const std::string &	id,
		ARDOUR::PluginType	type,
		Temporal::TimeDomain	td,
		const std::string &	preset = ""
	)

create a new Plugin Instance

Parameters

s	Session Handle
id	Plugin Name, ID or URI
type	Plugin Type
preset	name of plugin-preset to load, leave empty "" to not load any preset after instantiation
td	Time domain for any automation data

Returns

Processor or nil

new_send()

std::shared_ptr<Processor> ARDOUR::LuaAPI::new_send	(	Session *	s,
		std::shared_ptr< ARDOUR::Route >	r,
		std::shared_ptr< ARDOUR::Processor >	p
	)

add a new [external] Send to the given Route

Parameters

s	Session Handle
r	Route to add Send to
p	add send before given processor (or nil_processor to add at the end)

nil_processor()

std::shared_ptr<ARDOUR::Processor> ARDOUR::LuaAPI::nil_processor

(

)

Create a null processor shared pointer

This is useful for Track:bounce() to indicate no processing.

note_list()

std::list<std::shared_ptr< Evoral::Note<Temporal::Beats> > > ARDOUR::LuaAPI::note_list

(

std::shared_ptr< ARDOUR::MidiModel >

)

patch_change_list()

std::list<std::shared_ptr< Evoral::PatchChange<Temporal::Beats> > > ARDOUR::LuaAPI::patch_change_list

(

std::shared_ptr< ARDOUR::MidiModel >

)

plugin_automation()

int ARDOUR::LuaAPI::plugin_automation

(

lua_State *

lua

)

A convenience function to get a Automation Lists and ParameterDescriptor for a given plugin control.

This is equivalent to the following lua code

function (processor, param_id)
 local plugininsert = processor:to_insert ()
 local plugin = plugininsert:plugin(0)
 local _, t = plugin:get_parameter_descriptor(param_id, ARDOUR.ParameterDescriptor ())
 local ctrl = Evoral.Parameter (ARDOUR.AutomationType.PluginAutomation, 0, param_id)
 local ac = pi:automation_control (ctrl, false)
 local acl = ac:alist()
 return ac:alist(), ac:to_ctrl():list(), t[2]
end

Example usage: get the third input parameter of first plugin on the given route (Ardour starts counting at zero).

local al, cl, pd = ARDOUR.LuaAPI.plugin_automation (route:nth_plugin (0), 3)

Returns

3 parameters: AutomationList, ControlList, ParameterDescriptor

reset_processor_to_default()

bool ARDOUR::LuaAPI::reset_processor_to_default

(

std::shared_ptr< Processor >

proc

)

reset a processor to its default values (only works for plugins )

This is a wrapper which looks up the Processor by plugin-insert.

Parameters

proc	Plugin-Insert

Returns

true on success, false when the processor is not a plugin

sample_to_timecode()

int ARDOUR::LuaAPI::sample_to_timecode

(

lua_State *

L

)

Generic conversion from audio sample count to timecode. (TimecodeType, sample-rate, sample-pos)

sample_to_timecode_lua()

int ARDOUR::LuaAPI::sample_to_timecode_lua

(

lua_State *

L

)

Use current session settings to convert audio-sample count into hh, mm, ss, ff timecode (this include session pull up/down).

segfault()

void ARDOUR::LuaAPI::segfault

(

)

Crash Test Dummy

set_automation_data()

bool ARDOUR::LuaAPI::set_automation_data	(	std::shared_ptr< ARDOUR::AutomationControl >	ac,
		luabridge::LuaRef	tbl,
		double	thin = -1
	)

set_plugin_insert_param()

bool ARDOUR::LuaAPI::set_plugin_insert_param	(	std::shared_ptr< ARDOUR::PluginInsert >	pi,
		uint32_t	which,
		float	value
	)

set a plugin control-input parameter value

This is a wrapper around set_processor_param which looks up the Processor by plugin-insert.

Parameters

pi	Plugin-Insert
which	control-input to set (starting at 0)
value	value to set

Returns

true on success, false on error or out-of-bounds value

set_plugin_insert_property()

bool ARDOUR::LuaAPI::set_plugin_insert_property	(	std::shared_ptr< ARDOUR::PluginInsert >	pi,
		std::string const &	uri,
		luabridge::LuaRef	value
	)

set a plugin property (LV2 plugins only)

Parameters

pi	Plugin-Insert
uri	the identifier of the parameter
value	the value to set (boolean, integer, float, string/path)

Returns

true on success, false if the given plugin has no property with the given URI

set_processor_param()

bool ARDOUR::LuaAPI::set_processor_param	(	std::shared_ptr< ARDOUR::Processor >	proc,
		uint32_t	which,
		float	value
	)

set a plugin control-input parameter value

Parameters

proc	Plugin-Processor
which	control-input to set (starting at 0)
value	value to set

Returns

true on success, false on error or out-of-bounds value

simple_export()

int ARDOUR::LuaAPI::simple_export

(

lua_State *

L

)

create a SimpleExport Object for the current session

sysex_list()

std::list<std::shared_ptr< Evoral::Event<Temporal::Beats> > > ARDOUR::LuaAPI::sysex_list

(

std::shared_ptr< ARDOUR::MidiModel >

)

timecode_to_sample()

int ARDOUR::LuaAPI::timecode_to_sample

(

lua_State *

L

)

Generic conversion from timecode to audio sample count. (TimecodeType, sample-rate, hh, mm, ss, ff)

timecode_to_sample_lua()

int ARDOUR::LuaAPI::timecode_to_sample_lua

(

lua_State *

L

)

Use current session settings to convert timecode (hh, mm, ss, ff) to audio-sample count (this include session pull up/down).

wait_for_process_callback()

bool ARDOUR::LuaAPI::wait_for_process_callback	(	size_t	n_cycles,
		int64_t	timeout_ms
	)

Delay execution until next process cycle starts.

Parameters

n_cycles	process-cycles to wait for. 0: means wait until next cycle-start, otherwise skip given number of cycles.
timeout_ms	wait at most this many milliseconds

Returns

true on success, false if timeout was reached or engine was not running