libs/ardour/ardour/lua_api.h

   1 /*
   2  * Copyright (C) 2016 Robin Gareus <robin@gareus.org>
   3  *
   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.
   8  *
   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.
  13  *
  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.
  17  *
  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 <vamp-hostsdk/Plugin.h>
  26
  27 #include "evoral/Note.hpp"
  28
  29 #include "ardour/libardour_visibility.h"
  30
  31 #include "ardour/midi_model.h"
  32 #include "ardour/processor.h"
  33 #include "ardour/session.h"
  34
  35 namespace ARDOUR {
  36         class Readable;
  37 }
  38
  39 namespace ARDOUR { namespace LuaAPI {
  40
  41         /** convenience constructor for DataType::NIL with managed lifetime
  42          * @returns DataType::NIL
  43          */
  44         int datatype_ctor_null (lua_State *lua);
  45         /** convenience constructor for DataType::AUDIO with managed lifetime
  46          * @returns DataType::AUDIO
  47          */
  48         int datatype_ctor_audio (lua_State *L);
  49         /** convenience constructor for DataType::MIDI with managed lifetime
  50          * @returns DataType::MIDI
  51          */
  52         int datatype_ctor_midi (lua_State *L);
  53
  54         /** Create a null processor shared pointer
  55          *
  56          * This is useful for Track:bounce() to indicate no processing.
  57          */
  58         boost::shared_ptr<ARDOUR::Processor> nil_processor ();
  59
  60         /** create a new Lua Processor (Plugin)
  61          *
  62          * @param s Session Handle
  63          * @param p Identifier or Name of the Processor
  64          * @returns Processor object (may be nil)
  65          */
  66         boost::shared_ptr<ARDOUR::Processor> new_luaproc (ARDOUR::Session *s, const std::string& p);
  67
  68         /** return a PluginInfoList (all plugin)
  69          */
  70         std::list<boost::shared_ptr<ARDOUR::PluginInfo> > list_plugins ();
  71
  72         /** search a Plugin
  73          *
  74          * @param id Plugin Name, ID or URI
  75          * @param type Plugin Type
  76          * @returns PluginInfo or nil if not found
  77          */
  78         boost::shared_ptr<ARDOUR::PluginInfo> new_plugin_info (const std::string& id, ARDOUR::PluginType type);
  79
  80         /** create a new Plugin Instance
  81          *
  82          * @param s Session Handle
  83          * @param id Plugin Name, ID or URI
  84          * @param type Plugin Type
  85          * @returns Processor or nil
  86          */
  87         boost::shared_ptr<ARDOUR::Processor> new_plugin (ARDOUR::Session *s, const std::string& id, ARDOUR::PluginType type, const std::string& preset = "");
  88
  89         /** set a plugin control-input parameter value
  90          *
  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
  95          */
  96         bool set_processor_param (boost::shared_ptr<ARDOUR::Processor> proc, uint32_t which, float val);
  97
  98         /** get a plugin control parameter value
  99          *
 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.
 103          * @returns value
 104          */
 105         float get_processor_param (boost::shared_ptr<Processor> proc, uint32_t which, bool &ok);
 106
 107         /** reset a processor to its default values (only works for plugins )
 108          *
 109          * This is a wrapper which looks up the Processor by plugin-insert.
 110          *
 111          * @param proc Plugin-Insert
 112          * @returns true on success, false when the processor is not a plugin
 113          */
 114         bool reset_processor_to_default (boost::shared_ptr<Processor> proc);
 115
 116         /** set a plugin control-input parameter value
 117          *
 118          * This is a wrapper around set_processor_param which looks up the Processor by plugin-insert.
 119          *
 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
 124          */
 125         bool set_plugin_insert_param (boost::shared_ptr<ARDOUR::PluginInsert> pi, uint32_t which, float val);
 126
 127         /** get a plugin control parameter value
 128          *
 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.
 132          * @returns value
 133          */
 134         float get_plugin_insert_param (boost::shared_ptr<ARDOUR::PluginInsert> pi, uint32_t which, bool &ok);
 135
 136         /**
 137          * A convenience function to get a Automation Lists and ParamaterDescriptor
 138          * for a given plugin control.
 139          *
 140          * This is equivalent to the following lua code
 141          * @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]
 150          * end
 151          * @endcode
 152          *
 153          * Example usage: get the third input parameter of first plugin on the given route
 154          * (Ardour starts counting at zero).
 155          * @code
 156          * local al, cl, pd = ARDOUR.LuaAPI.plugin_automation (route:nth_plugin (0), 3)
 157          * @endcode
 158          * @returns 3 parameters: AutomationList, ControlList, ParamaterDescriptor
 159          */
 160         int plugin_automation (lua_State *lua);
 161
 162         /**
 163          * A convenience function for colorspace HSL to RGB conversion.
 164          * All ranges are 0..1
 165          *
 166          * Example:
 167          * @code
 168          * local r, g, b, a = ARDOUR.LuaAPI.hsla_to_rgba (hue, saturation, luminosity, alpha)
 169          * @endcode
 170          * @returns 4 parameters: red, green, blue, alpha (in range 0..1)
 171          */
 172         int hsla_to_rgba (lua_State *lua);
 173
 174         /**
 175          * A convenience function to expand RGBA parameters from an integer
 176          *
 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
 180          *
 181          * Example:
 182          * @code
 183          * local r, g, b, a = ARDOUR.LuaAPI.color_to_rgba (0x88aa44ff)
 184          * cairo_ctx:set_source_rgba (ARDOUR.LuaAPI.color_to_rgba (0x11336699)
 185          * @endcode
 186          * @returns 4 parameters: red, green, blue, alpha (in range 0..1)
 187          */
 188         int color_to_rgba (lua_State *lua);
 189
 190         /**
 191          */
 192         std::string ascii_dtostr (const double d);
 193
 194         /**
 195          * Creates a filename from a series of elements using the correct separator for filenames.
 196          *
 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.
 199          */
 200         int build_filename (lua_State *lua);
 201
 202         /**
 203          * Generic conversion from audio sample count to timecode.
 204          * (TimecodeType, sample-rate, sample-pos)
 205          */
 206         int sample_to_timecode (lua_State *L);
 207
 208         /**
 209          * Generic conversion from timecode to audio sample count.
 210          * (TimecodeType, sample-rate, hh, mm, ss, ff)
 211          */
 212         int timecode_to_sample (lua_State *L);
 213
 214         /**
 215          * Use current session settings to convert
 216          * audio-sample count into hh, mm, ss, ff
 217          * timecode (this include session pull up/down).
 218          */
 219         int sample_to_timecode_lua (lua_State *L);
 220
 221         /**
 222          * Use current session settings to convert
 223          * timecode (hh, mm, ss, ff) to audio-sample
 224          * count (this include session pull up/down).
 225          */
 226         int timecode_to_sample_lua (lua_State *L);
 227
 228         class Vamp {
 229         /** Vamp Plugin Interface
 230          *
 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.
 234          *
 235          * This interface allows to load a plugins and directly access it using the Vamp Plugin API.
 236          *
 237          * A convenience method is provided to analyze Ardour::Readable objects (Regions).
 238          */
 239                 public:
 240                         Vamp (const std::string&, float sample_rate);
 241                         ~Vamp ();
 242
 243                         /** Search for all available available Vamp plugins.
 244                          * @returns list of plugin-keys
 245                          */
 246                         static std::vector<std::string> list_plugins ();
 247
 248                         ::Vamp::Plugin* plugin () { return _plugin; }
 249
 250                         /** high-level abstraction to process a single channel of the given Readable.
 251                          *
 252                          * If the plugin is not yet initialized, initialize() is called.
 253                          *
 254                          * if @cb is not nil, it is called with the immediate
 255                          * Vamp::Plugin::Features on every process call.
 256                          *
 257                          * @param r readable
 258                          * @param channel channel to process
 259                          * @param fn lua callback function
 260                          * @return 0 on success
 261                          */
 262                         int analyze (boost::shared_ptr<ARDOUR::Readable> r, uint32_t channel, luabridge::LuaRef fn);
 263
 264                         /** call plugin():reset() and clear intialization flag */
 265                         void reset ();
 266
 267                         /** initialize the plugin for use with analyze().
 268                          *
 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)
 273                          *
 274                          * Manual initialization is only required to set plugin-parameters
 275                          * which depend on prior initialization of the plugin.
 276                          *
 277                          * @code
 278                          * vamp:reset ()
 279                          * vamp:initialize ()
 280                          * vamp:plugin():setParameter (0, 1.5, nil)
 281                          * vamp:analyze (r, 0)
 282                          * @endcode
 283                          */
 284                         bool initialize ();
 285
 286                         bool initialized () const { return _initialized; }
 287
 288                         /** process given array of audio-samples.
 289                          *
 290                          * This is a lua-binding for vamp:plugin():process ()
 291                          *
 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)
 297                          */
 298                         ::Vamp::Plugin::FeatureSet process (const std::vector<float*>& d, ::Vamp::RealTime rt);
 299
 300                 private:
 301                         ::Vamp::Plugin* _plugin;
 302                         float           _sample_rate;
 303                         samplecnt_t      _bufsize;
 304                         samplecnt_t      _stepsize;
 305                         bool            _initialized;
 306
 307         };
 308
 309         boost::shared_ptr<Evoral::Note<Temporal::Beats> >
 310                 new_noteptr (uint8_t, Temporal::Beats, Temporal::Beats, uint8_t, uint8_t);
 311
 312         std::list<boost::shared_ptr< Evoral::Note<Temporal::Beats> > >
 313                 note_list (boost::shared_ptr<ARDOUR::MidiModel>);
 314
 315 } } /* namespace */
 316
 317 namespace ARDOUR { namespace LuaOSC {
 318         /** OSC transmitter
 319          *
 320          * A Class to send OSC messages.
 321          */
 322         class Address {
 323                 /*
 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.
 326                  */
 327                 public:
 328                         /** Construct a new OSC transmitter object
 329                          * @param uri the destination uri e.g. "osc.udp://localhost:7890"
 330                          */
 331                         Address (std::string uri) {
 332                                 _addr = lo_address_new_from_url (uri.c_str());
 333                         }
 334
 335                         ~Address () { if (_addr) { lo_address_free (_addr); } }
 336                         /** Transmit an OSC message
 337                          *
 338                          * Path (string) and type (string) must always be given.
 339                          * The number of following args must match the type.
 340                          * Supported types are:
 341                          *
 342                          *  'i': integer (lua number)
 343                          *
 344                          *  'f': float (lua number)
 345                          *
 346                          *  'd': double (lua number)
 347                          *
 348                          *  'h': 64bit integer (lua number)
 349                          *
 350                          *  's': string (lua string)
 351                          *
 352                          *  'c': character (lua string)
 353                          *
 354                          *  'T': boolean (lua bool) -- this is not implicily True, a lua true/false must be given
 355                          *
 356                          *  'F': boolean (lua bool) -- this is not implicily False, a lua true/false must be given
 357                          *
 358                          * @param lua: lua arguments: path, types, ...
 359                          * @returns boolean true if successful, false on error.
 360                          */
 361                         int send (lua_State *lua);
 362                 private:
 363                         lo_address _addr;
 364         };
 365
 366 }
 367
 368 class LuaTableRef {
 369         public:
 370                 LuaTableRef ();
 371                 ~LuaTableRef ();
 372
 373                 int get (lua_State* L);
 374                 int set (lua_State* L);
 375
 376         private:
 377                 struct LuaTableEntry {
 378                         LuaTableEntry (int kt, int vt)
 379                                 : keytype (kt)
 380                                 , valuetype (vt)
 381                         { }
 382
 383                         int keytype;
 384                         std::string k_s;
 385                         unsigned int k_n;
 386
 387                         int valuetype;
 388                         // LUA_TUSERDATA
 389                         const void* c;
 390                         void* p;
 391                         // LUA_TBOOLEAN
 392                         bool b;
 393                         // LUA_TSTRING:
 394                         std::string s;
 395                         // LUA_TNUMBER:
 396                         double n;
 397                 };
 398
 399                 std::vector<LuaTableEntry> _data;
 400
 401                 static void* findclasskey (lua_State *L, const void* key);
 402                 template<typename T>
 403                 static void assign (luabridge::LuaRef* rv, T key, const LuaTableEntry& s);
 404 };
 405
 406 } /* namespace */
 407
 408 #endif // _ardour_lua_api_h_