2 * Copyright (C) 2016 Robin Gareus <robin@gareus.org>
4 * This program is free software; you can redistribute it and/or
5 * modify it under the terms of the GNU General Public License
6 * as published by the Free Software Foundation; either version 2
7 * of the License, or (at your option) any later version.
9 * This program is distributed in the hope that it will be useful,
10 * but WITHOUT ANY WARRANTY; without even the implied warranty of
11 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
12 * GNU General Public License for more details.
14 * You should have received a copy of the GNU General Public License
15 * along with this program; if not, write to the Free Software
16 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
19 #ifndef _ardour_lua_api_h_
20 #define _ardour_lua_api_h_
24 #include <boost/shared_ptr.hpp>
25 #include <vamp-hostsdk/Plugin.h>
27 #include "evoral/Note.hpp"
29 #include "ardour/libardour_visibility.h"
31 #include "ardour/midi_model.h"
32 #include "ardour/processor.h"
33 #include "ardour/session.h"
39 namespace ARDOUR { namespace LuaAPI {
41 /** convenience constructor for DataType::NIL with managed lifetime
42 * @returns DataType::NIL
44 int datatype_ctor_null (lua_State *lua);
45 /** convenience constructor for DataType::AUDIO with managed lifetime
46 * @returns DataType::AUDIO
48 int datatype_ctor_audio (lua_State *L);
49 /** convenience constructor for DataType::MIDI with managed lifetime
50 * @returns DataType::MIDI
52 int datatype_ctor_midi (lua_State *L);
54 /** Create a null processor shared pointer
56 * This is useful for Track:bounce() to indicate no processing.
58 boost::shared_ptr<ARDOUR::Processor> nil_processor ();
60 /** create a new Lua Processor (Plugin)
62 * @param s Session Handle
63 * @param p Identifier or Name of the Processor
64 * @returns Processor object (may be nil)
66 boost::shared_ptr<ARDOUR::Processor> new_luaproc (ARDOUR::Session *s, const std::string& p);
68 /** return a PluginInfoList (all plugin)
70 std::list<boost::shared_ptr<ARDOUR::PluginInfo> > list_plugins ();
74 * @param id Plugin Name, ID or URI
75 * @param type Plugin Type
76 * @returns PluginInfo or nil if not found
78 boost::shared_ptr<ARDOUR::PluginInfo> new_plugin_info (const std::string& id, ARDOUR::PluginType type);
80 /** create a new Plugin Instance
82 * @param s Session Handle
83 * @param id Plugin Name, ID or URI
84 * @param type Plugin Type
85 * @returns Processor or nil
87 boost::shared_ptr<ARDOUR::Processor> new_plugin (ARDOUR::Session *s, const std::string& id, ARDOUR::PluginType type, const std::string& preset = "");
89 /** set a plugin control-input parameter value
91 * @param proc Plugin-Processor
92 * @param which control-input to set (starting at 0)
93 * @param value value to set
94 * @returns true on success, false on error or out-of-bounds value
96 bool set_processor_param (boost::shared_ptr<ARDOUR::Processor> proc, uint32_t which, float val);
98 /** get a plugin control parameter value
100 * @param proc Plugin-Processor
101 * @param which control port to set (starting at 0, including ports of type input and output))
102 * @param ok boolean variable contains true or false after call returned. to be checked by caller before using value.
105 float get_processor_param (boost::shared_ptr<Processor> proc, uint32_t which, bool &ok);
107 /** reset a processor to its default values (only works for plugins )
109 * This is a wrapper which looks up the Processor by plugin-insert.
111 * @param proc Plugin-Insert
112 * @returns true on success, false when the processor is not a plugin
114 bool reset_processor_to_default (boost::shared_ptr<Processor> proc);
116 /** set a plugin control-input parameter value
118 * This is a wrapper around set_processor_param which looks up the Processor by plugin-insert.
120 * @param proc Plugin-Insert
121 * @param which control-input to set (starting at 0)
122 * @param value value to set
123 * @returns true on success, false on error or out-of-bounds value
125 bool set_plugin_insert_param (boost::shared_ptr<ARDOUR::PluginInsert> pi, uint32_t which, float val);
127 /** get a plugin control parameter value
129 * @param proc Plugin-Insert
130 * @param which control port to query (starting at 0, including ports of type input and output)
131 * @param ok boolean variable contains true or false after call returned. to be checked by caller before using value.
134 float get_plugin_insert_param (boost::shared_ptr<ARDOUR::PluginInsert> pi, uint32_t which, bool &ok);
137 * A convenience function to get a Automation Lists and ParamaterDescriptor
138 * for a given plugin control.
140 * This is equivalent to the following lua code
142 * function (processor, param_id)
143 * local plugininsert = processor:to_insert ()
144 * local plugin = plugininsert:plugin(0)
145 * local _, t = plugin:get_parameter_descriptor(param_id, ARDOUR.ParameterDescriptor ())
146 * local ctrl = Evoral.Parameter (ARDOUR.AutomationType.PluginAutomation, 0, param_id)
147 * local ac = pi:automation_control (ctrl, false)
148 * local acl = ac:alist()
149 * return ac:alist(), ac:to_ctrl():list(), t[2]
153 * Example usage: get the third input parameter of first plugin on the given route
154 * (Ardour starts counting at zero).
156 * local al, cl, pd = ARDOUR.LuaAPI.plugin_automation (route:nth_plugin (0), 3)
158 * @returns 3 parameters: AutomationList, ControlList, ParamaterDescriptor
160 int plugin_automation (lua_State *lua);
163 * A convenience function for colorspace HSL to RGB conversion.
164 * All ranges are 0..1
168 * local r, g, b, a = ARDOUR.LuaAPI.hsla_to_rgba (hue, saturation, luminosity, alpha)
170 * @returns 4 parameters: red, green, blue, alpha (in range 0..1)
172 int hsla_to_rgba (lua_State *lua);
175 * A convenience function to expand RGBA parameters from an integer
177 * convert a Canvas::Color (uint32_t 0xRRGGBBAA) into
178 * double RGBA values which can be passed as parameters to
179 * Cairo::Context::set_source_rgba
183 * local r, g, b, a = ARDOUR.LuaAPI.color_to_rgba (0x88aa44ff)
184 * cairo_ctx:set_source_rgba (ARDOUR.LuaAPI.color_to_rgba (0x11336699)
186 * @returns 4 parameters: red, green, blue, alpha (in range 0..1)
188 int color_to_rgba (lua_State *lua);
192 std::string ascii_dtostr (const double d);
195 * Creates a filename from a series of elements using the correct separator for filenames.
197 * No attempt is made to force the resulting filename to be an absolute path.
198 * If the first element is a relative path, the result will be a relative path.
200 int build_filename (lua_State *lua);
203 * Generic conversion from audio sample count to timecode.
204 * (TimecodeType, sample-rate, sample-pos)
206 int sample_to_timecode (lua_State *L);
209 * Generic conversion from timecode to audio sample count.
210 * (TimecodeType, sample-rate, hh, mm, ss, ff)
212 int timecode_to_sample (lua_State *L);
215 * Use current session settings to convert
216 * audio-sample count into hh, mm, ss, ff
217 * timecode (this include session pull up/down).
219 int sample_to_timecode_lua (lua_State *L);
222 * Use current session settings to convert
223 * timecode (hh, mm, ss, ff) to audio-sample
224 * count (this include session pull up/down).
226 int timecode_to_sample_lua (lua_State *L);
229 /** Vamp Plugin Interface
231 * Vamp is an audio processing plugin system for plugins that extract descriptive information
232 * from audio data - typically referred to as audio analysis plugins or audio feature
233 * extraction plugins.
235 * This interface allows to load a plugins and directly access it using the Vamp Plugin API.
237 * A convenience method is provided to analyze Ardour::Readable objects (Regions).
240 Vamp (const std::string&, float sample_rate);
243 /** Search for all available available Vamp plugins.
244 * @returns list of plugin-keys
246 static std::vector<std::string> list_plugins ();
248 ::Vamp::Plugin* plugin () { return _plugin; }
250 /** high-level abstraction to process a single channel of the given Readable.
252 * If the plugin is not yet initialized, initialize() is called.
254 * if @cb is not nil, it is called with the immediate
255 * Vamp::Plugin::Features on every process call.
258 * @param channel channel to process
259 * @param fn lua callback function
260 * @return 0 on success
262 int analyze (boost::shared_ptr<ARDOUR::Readable> r, uint32_t channel, luabridge::LuaRef fn);
264 /** call plugin():reset() and clear intialization flag */
267 /** initialize the plugin for use with analyze().
269 * This is equivalent to plugin():initialise (1, ssiz, bsiz)
270 * and prepares a plugin for analyze.
271 * (by preferred step and block sizes are used. if the plugin
272 * does not specify them or they're larger than 8K, both are set to 1024)
274 * Manual initialization is only required to set plugin-parameters
275 * which depend on prior initialization of the plugin.
280 * vamp:plugin():setParameter (0, 1.5, nil)
281 * vamp:analyze (r, 0)
286 bool initialized () const { return _initialized; }
288 /** process given array of audio-samples.
290 * This is a lua-binding for vamp:plugin():process ()
292 * @param d audio-data, the vector must match the configured channel count
293 * and hold a complete buffer for every channel as set during
294 * plugin():initialise()
295 * @param rt timestamp matching the provided buffer.
296 * @returns features extracted from that data (if the plugin is causal)
298 ::Vamp::Plugin::FeatureSet process (const std::vector<float*>& d, ::Vamp::RealTime rt);
301 ::Vamp::Plugin* _plugin;
303 samplecnt_t _bufsize;
304 samplecnt_t _stepsize;
309 boost::shared_ptr<Evoral::Note<Temporal::Beats> >
310 new_noteptr (uint8_t, Temporal::Beats, Temporal::Beats, uint8_t, uint8_t);
312 std::list<boost::shared_ptr< Evoral::Note<Temporal::Beats> > >
313 note_list (boost::shared_ptr<ARDOUR::MidiModel>);
317 namespace ARDOUR { namespace LuaOSC {
320 * A Class to send OSC messages.
324 * OSC is kinda special, lo_address is a void* and lo_send() has varags
325 * and typed arguments which makes it hard to bind, even lo_cpp.
328 /** Construct a new OSC transmitter object
329 * @param uri the destination uri e.g. "osc.udp://localhost:7890"
331 Address (std::string uri) {
332 _addr = lo_address_new_from_url (uri.c_str());
335 ~Address () { if (_addr) { lo_address_free (_addr); } }
336 /** Transmit an OSC message
338 * Path (string) and type (string) must always be given.
339 * The number of following args must match the type.
340 * Supported types are:
342 * 'i': integer (lua number)
344 * 'f': float (lua number)
346 * 'd': double (lua number)
348 * 'h': 64bit integer (lua number)
350 * 's': string (lua string)
352 * 'c': character (lua string)
354 * 'T': boolean (lua bool) -- this is not implicily True, a lua true/false must be given
356 * 'F': boolean (lua bool) -- this is not implicily False, a lua true/false must be given
358 * @param lua: lua arguments: path, types, ...
359 * @returns boolean true if successful, false on error.
361 int send (lua_State *lua);
373 int get (lua_State* L);
374 int set (lua_State* L);
377 struct LuaTableEntry {
378 LuaTableEntry (int kt, int vt)
399 std::vector<LuaTableEntry> _data;
401 static void* findclasskey (lua_State *L, const void* key);
403 static void assign (luabridge::LuaRef* rv, T key, const LuaTableEntry& s);
408 #endif // _ardour_lua_api_h_