1 /* 2 * Copyright (C) 2016-2019 Robin Gareus <robin@gareus.org> 3 * Copyright (C) 2017 Paul Davis <paul@linuxaudiosystems.com> 4 * 5 * This program is free software; you can redistribute it and/or modify 6 * it under the terms of the GNU General Public License as published by 7 * the Free Software Foundation; either version 2 of the License, or 8 * (at your option) any later version. 9 * 10 * This program is distributed in the hope that it will be useful, 11 * but WITHOUT ANY WARRANTY; without even the implied warranty of 12 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 13 * GNU General Public License for more details. 14 * 15 * You should have received a copy of the GNU General Public License along 16 * with this program; if not, write to the Free Software Foundation, Inc., 17 * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. 18 */ 19 #ifndef _ardour_lua_api_h_ 20 #define _ardour_lua_api_h_ 21 22 #include <string> 23 #include <lo/lo.h> 24 #include <boost/shared_ptr.hpp> 25 #include <boost/enable_shared_from_this.hpp> 26 #include <rubberband/RubberBandStretcher.h> 27 #include <vamp-hostsdk/Plugin.h> 28 29 #include "evoral/Note.h" 30 31 #include "ardour/libardour_visibility.h" 32 33 #include "ardour/audioregion.h" 34 #include "ardour/midi_model.h" 35 #include "ardour/processor.h" 36 #include "ardour/session.h" 37 38 namespace ARDOUR { 39 class Readable; 40 } 41 42 namespace ARDOUR { namespace LuaAPI { 43 44 /** convenience constructor for DataType::NIL with managed lifetime 45 * @returns DataType::NIL 46 */ 47 int datatype_ctor_null (lua_State *lua); 48 /** convenience constructor for DataType::AUDIO with managed lifetime 49 * @returns DataType::AUDIO 50 */ 51 int datatype_ctor_audio (lua_State *L); 52 /** convenience constructor for DataType::MIDI with managed lifetime 53 * @returns DataType::MIDI 54 */ 55 int datatype_ctor_midi (lua_State *L); 56 57 /** add a new [external] Send to the given Route 58 * 59 * @param s Session Handle 60 * @param r Route to add Send to 61 * @param p add send before given processor (or \ref nil_processor to add at the end) 62 */ 63 boost::shared_ptr<Processor> new_send (Session* s, boost::shared_ptr<ARDOUR::Route> r, boost::shared_ptr<ARDOUR::Processor> p); 64 65 /** Create a null processor shared pointer 66 * 67 * This is useful for Track:bounce() to indicate no processing. 68 */ 69 boost::shared_ptr<ARDOUR::Processor> nil_processor (); 70 71 /** create a new Lua Processor (Plugin) 72 * 73 * @param s Session Handle 74 * @param p Identifier or Name of the Processor 75 * @returns Processor object (may be nil) 76 */ 77 boost::shared_ptr<ARDOUR::Processor> new_luaproc (ARDOUR::Session *s, const std::string& p); 78 79 /** List all installed plugins */ 80 std::list<boost::shared_ptr<ARDOUR::PluginInfo> > list_plugins (); 81 82 /** Write a list of untagged plugins to a file, so we can bulk-tag them 83 * @returns path to XML file or empty string on error 84 */ 85 std::string dump_untagged_plugins (); 86 87 /** search a Plugin 88 * 89 * @param id Plugin Name, ID or URI 90 * @param type Plugin Type 91 * @returns PluginInfo or nil if not found 92 */ 93 boost::shared_ptr<ARDOUR::PluginInfo> new_plugin_info (const std::string& id, ARDOUR::PluginType type); 94 95 /** create a new Plugin Instance 96 * 97 * @param s Session Handle 98 * @param id Plugin Name, ID or URI 99 * @param type Plugin Type 100 * @param preset name of plugin-preset to load, leave empty "" to not load any preset after instantiation 101 * @returns Processor or nil 102 */ 103 boost::shared_ptr<ARDOUR::Processor> new_plugin (ARDOUR::Session *s, const std::string& id, ARDOUR::PluginType type, const std::string& preset = ""); 104 105 /** set a plugin control-input parameter value 106 * 107 * @param proc Plugin-Processor 108 * @param which control-input to set (starting at 0) 109 * @param value value to set 110 * @returns true on success, false on error or out-of-bounds value 111 */ 112 bool set_processor_param (boost::shared_ptr<ARDOUR::Processor> proc, uint32_t which, float value); 113 114 /** get a plugin control parameter value 115 * 116 * @param proc Plugin-Processor 117 * @param which control port to set (starting at 0, including ports of type input and output)) 118 * @param ok boolean variable contains true or false after call returned. to be checked by caller before using value. 119 * @returns value 120 */ 121 float get_processor_param (boost::shared_ptr<Processor> proc, uint32_t which, bool &ok); 122 123 /** reset a processor to its default values (only works for plugins ) 124 * 125 * This is a wrapper which looks up the Processor by plugin-insert. 126 * 127 * @param proc Plugin-Insert 128 * @returns true on success, false when the processor is not a plugin 129 */ 130 bool reset_processor_to_default (boost::shared_ptr<Processor> proc); 131 132 /** set a plugin control-input parameter value 133 * 134 * This is a wrapper around set_processor_param which looks up the Processor by plugin-insert. 135 * 136 * @param pi Plugin-Insert 137 * @param which control-input to set (starting at 0) 138 * @param value value to set 139 * @returns true on success, false on error or out-of-bounds value 140 */ 141 bool set_plugin_insert_param (boost::shared_ptr<ARDOUR::PluginInsert> pi, uint32_t which, float value); 142 143 /** get a plugin control parameter value 144 * 145 * @param pi Plugin-Insert 146 * @param which control port to query (starting at 0, including ports of type input and output) 147 * @param ok boolean variable contains true or false after call returned. to be checked by caller before using value. 148 * @returns value 149 */ 150 float get_plugin_insert_param (boost::shared_ptr<ARDOUR::PluginInsert> pi, uint32_t which, bool &ok); 151 152 /** 153 * A convenience function to get a Automation Lists and ParamaterDescriptor 154 * for a given plugin control. 155 * 156 * This is equivalent to the following lua code 157 * @code 158 * function (processor, param_id) 159 * local plugininsert = processor:to_insert () 160 * local plugin = plugininsert:plugin(0) 161 * local _, t = plugin:get_parameter_descriptor(param_id, ARDOUR.ParameterDescriptor ()) 162 * local ctrl = Evoral.Parameter (ARDOUR.AutomationType.PluginAutomation, 0, param_id) 163 * local ac = pi:automation_control (ctrl, false) 164 * local acl = ac:alist() 165 * return ac:alist(), ac:to_ctrl():list(), t[2] 166 * end 167 * @endcode 168 * 169 * Example usage: get the third input parameter of first plugin on the given route 170 * (Ardour starts counting at zero). 171 * @code 172 * local al, cl, pd = ARDOUR.LuaAPI.plugin_automation (route:nth_plugin (0), 3) 173 * @endcode 174 * @returns 3 parameters: AutomationList, ControlList, ParamaterDescriptor 175 */ 176 int plugin_automation (lua_State *lua); 177 178 /* 179 * A convenience function to get a scale-points from a ParamaterDescriptor 180 * @param p a ParameterDescriptor 181 * @returns Lua Table with "name" -> value pairs 182 */ 183 int desc_scale_points (lua_State* p); 184 185 /** 186 * A convenience function for colorspace HSL to RGB conversion. 187 * All ranges are 0..1 188 * 189 * Example: 190 * @code 191 * local r, g, b, a = ARDOUR.LuaAPI.hsla_to_rgba (hue, saturation, luminosity, alpha) 192 * @endcode 193 * @returns 4 parameters: red, green, blue, alpha (in range 0..1) 194 */ 195 int hsla_to_rgba (lua_State *lua); 196 197 /** 198 * A convenience function to expand RGBA parameters from an integer 199 * 200 * convert a Canvas::Color (uint32_t 0xRRGGBBAA) into 201 * double RGBA values which can be passed as parameters to 202 * Cairo::Context::set_source_rgba 203 * 204 * Example: 205 * @code 206 * local r, g, b, a = ARDOUR.LuaAPI.color_to_rgba (0x88aa44ff) 207 * cairo_ctx:set_source_rgba (ARDOUR.LuaAPI.color_to_rgba (0x11336699) 208 * @endcode 209 * @returns 4 parameters: red, green, blue, alpha (in range 0..1) 210 */ 211 int color_to_rgba (lua_State *lua); 212 213 /** 214 */ 215 std::string ascii_dtostr (const double d); 216 217 /** 218 * Creates a filename from a series of elements using the correct separator for filenames. 219 * 220 * No attempt is made to force the resulting filename to be an absolute path. 221 * If the first element is a relative path, the result will be a relative path. 222 */ 223 int build_filename (lua_State *lua); 224 225 /** 226 * Generic conversion from audio sample count to timecode. 227 * (TimecodeType, sample-rate, sample-pos) 228 */ 229 int sample_to_timecode (lua_State *L); 230 231 /** 232 * Generic conversion from timecode to audio sample count. 233 * (TimecodeType, sample-rate, hh, mm, ss, ff) 234 */ 235 int timecode_to_sample (lua_State *L); 236 237 /** 238 * Use current session settings to convert 239 * audio-sample count into hh, mm, ss, ff 240 * timecode (this include session pull up/down). 241 */ 242 int sample_to_timecode_lua (lua_State *L); 243 244 /** 245 * Use current session settings to convert 246 * timecode (hh, mm, ss, ff) to audio-sample 247 * count (this include session pull up/down). 248 */ 249 int timecode_to_sample_lua (lua_State *L); 250 251 /** 252 * Delay execution until next prcess cycle starts. 253 * @param n_cycles process-cycles to wait for. 254 * 0: means wait until next cycle-start, otherwise skip given number of cycles. 255 * @param timeout_ms wait at most this many milliseconds 256 * @return true on success, false if timeout was reached or engine was not running 257 */ 258 bool wait_for_process_callback (size_t n_cycles, int64_t timeout_ms); 259 260 /** Crash Test Dummy */ 261 void segfault (); 262 263 class Vamp { 264 /** Vamp Plugin Interface 265 * 266 * Vamp is an audio processing plugin system for plugins that extract descriptive information 267 * from audio data - typically referred to as audio analysis plugins or audio feature 268 * extraction plugins. 269 * 270 * This interface allows to load a plugins and directly access it using the Vamp Plugin API. 271 * 272 * A convenience method is provided to analyze Ardour::Readable objects (Regions). 273 */ 274 public: 275 Vamp (const std::string&, float sample_rate); 276 ~Vamp (); 277 278 /** Search for all available available Vamp plugins. 279 * @returns list of plugin-keys 280 */ 281 static std::vector<std::string> list_plugins (); 282 plugin()283 ::Vamp::Plugin* plugin () { return _plugin; } 284 285 /** high-level abstraction to process a single channel of the given Readable. 286 * 287 * If the plugin is not yet initialized, initialize() is called. 288 * 289 * if \p fn is not nil, it is called with the immediate 290 * Vamp::Plugin::Features on every process call. 291 * 292 * @param r readable 293 * @param channel channel to process 294 * @param fn lua callback function or nil 295 * @return 0 on success 296 */ 297 int analyze (boost::shared_ptr<ARDOUR::Readable> r, uint32_t channel, luabridge::LuaRef fn); 298 299 /** call plugin():reset() and clear intialization flag */ 300 void reset (); 301 302 /** initialize the plugin for use with analyze(). 303 * 304 * This is equivalent to plugin():initialise (1, ssiz, bsiz) 305 * and prepares a plugin for analyze. 306 * (by preferred step and block sizes are used. if the plugin 307 * does not specify them or they're larger than 8K, both are set to 1024) 308 * 309 * Manual initialization is only required to set plugin-parameters 310 * which depend on prior initialization of the plugin. 311 * 312 * @code 313 * vamp:reset () 314 * vamp:initialize () 315 * vamp:plugin():setParameter (0, 1.5, nil) 316 * vamp:analyze (r, 0) 317 * @endcode 318 */ 319 bool initialize (); 320 initialized()321 bool initialized () const { return _initialized; } 322 323 /** process given array of audio-samples. 324 * 325 * This is a lua-binding for vamp:plugin():process () 326 * 327 * @param d audio-data, the vector must match the configured channel count 328 * and hold a complete buffer for every channel as set during 329 * plugin():initialise() 330 * @param rt timestamp matching the provided buffer. 331 * @returns features extracted from that data (if the plugin is causal) 332 */ 333 ::Vamp::Plugin::FeatureSet process (const std::vector<float*>& d, ::Vamp::RealTime rt); 334 335 private: 336 ::Vamp::Plugin* _plugin; 337 float _sample_rate; 338 samplecnt_t _bufsize; 339 samplecnt_t _stepsize; 340 bool _initialized; 341 342 }; 343 344 class Rubberband : public Readable , public boost::enable_shared_from_this<Rubberband> 345 { 346 public: 347 Rubberband (boost::shared_ptr<AudioRegion>, bool percussive); 348 ~Rubberband (); 349 bool set_strech_and_pitch (double stretch_ratio, double pitch_ratio); 350 bool set_mapping (luabridge::LuaRef tbl); 351 boost::shared_ptr<AudioRegion> process (luabridge::LuaRef cb); 352 boost::shared_ptr<Readable> readable (); 353 354 /* readable API */ readable_length()355 samplecnt_t readable_length () const { return _read_len; } n_channels()356 uint32_t n_channels () const { return _n_channels; } 357 samplecnt_t read (Sample*, samplepos_t pos, samplecnt_t cnt, int channel) const; 358 359 private: 360 Rubberband (Rubberband const&); // no copy construction 361 bool read_region (bool study); 362 bool retrieve (float**); 363 void cleanup (bool abort); 364 boost::shared_ptr<AudioRegion> finalize (); 365 366 boost::shared_ptr<AudioRegion> _region; 367 368 uint32_t _n_channels; 369 samplecnt_t _read_len; 370 samplecnt_t _read_start; 371 samplecnt_t _read_offset; 372 373 std::vector<boost::shared_ptr<AudioSource> > _asrc; 374 375 RubberBand::RubberBandStretcher _rbs; 376 std::map<size_t, size_t> _mapping; 377 378 double _stretch_ratio; 379 double _pitch_ratio; 380 381 luabridge::LuaRef* _cb; 382 boost::shared_ptr<Rubberband> _self; 383 static const samplecnt_t _bufsize; 384 }; 385 386 boost::shared_ptr<Evoral::Note<Temporal::Beats> > 387 new_noteptr (uint8_t, Temporal::Beats, Temporal::Beats, uint8_t, uint8_t); 388 389 std::list<boost::shared_ptr< Evoral::Note<Temporal::Beats> > > 390 note_list (boost::shared_ptr<ARDOUR::MidiModel>); 391 392 } } /* namespace */ 393 394 namespace ARDOUR { namespace LuaOSC { 395 /** OSC transmitter 396 * 397 * A Class to send OSC messages. 398 */ 399 class Address { 400 /* 401 * OSC is kinda special, lo_address is a void* and lo_send() has varags 402 * and typed arguments which makes it hard to bind, even lo_cpp. 403 */ 404 public: 405 /** Construct a new OSC transmitter object 406 * @param uri the destination uri e.g. "osc.udp://localhost:7890" 407 */ Address(std::string uri)408 Address (std::string uri) { 409 _addr = lo_address_new_from_url (uri.c_str()); 410 } 411 ~Address()412 ~Address () { if (_addr) { lo_address_free (_addr); } } 413 /** Transmit an OSC message 414 * 415 * Path (string) and type (string) must always be given. 416 * The number of following args must match the type. 417 * Supported types are: 418 * 419 * 'i': integer (lua number) 420 * 421 * 'f': float (lua number) 422 * 423 * 'd': double (lua number) 424 * 425 * 'h': 64bit integer (lua number) 426 * 427 * 's': string (lua string) 428 * 429 * 'c': character (lua string) 430 * 431 * 'T': boolean (lua bool) -- this is not implicily True, a lua true/false must be given 432 * 433 * 'F': boolean (lua bool) -- this is not implicily False, a lua true/false must be given 434 * 435 * @param lua: lua arguments: path, types, ... 436 * @returns boolean true if successful, false on error. 437 */ 438 int send (lua_State *lua); 439 private: 440 lo_address _addr; 441 }; 442 443 } 444 445 class LuaTableRef { 446 public: 447 LuaTableRef (); 448 ~LuaTableRef (); 449 450 int get (lua_State* L); 451 int set (lua_State* L); 452 453 private: 454 struct LuaTableEntry { LuaTableEntryLuaTableEntry455 LuaTableEntry (int kt, int vt) 456 : keytype (kt) 457 , valuetype (vt) 458 { } 459 460 int keytype; 461 std::string k_s; 462 unsigned int k_n; 463 464 int valuetype; 465 // LUA_TUSERDATA 466 const void* c; 467 void* p; 468 // LUA_TBOOLEAN 469 bool b; 470 // LUA_TSTRING: 471 std::string s; 472 // LUA_TNUMBER: 473 double n; 474 }; 475 476 std::vector<LuaTableEntry> _data; 477 478 static void* findclasskey (lua_State *L, const void* key); 479 template<typename T> 480 static void assign (luabridge::LuaRef* rv, T key, const LuaTableEntry& s); 481 }; 482 483 } /* namespace */ 484 485 #endif // _ardour_lua_api_h_ 486