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 "ardour/libardour_visibility.h"
  28
  29 #include "ardour/processor.h"
  30 #include "ardour/session.h"
  31
  32 namespace ARDOUR {
  33         class Readable;
  34 }
  35
  36 namespace ARDOUR { namespace LuaAPI {
  37
  38         /** convenience constructor for DataType::NIL with managed lifetime
  39          * @returns DataType::NIL
  40          */
  41         int datatype_ctor_null (lua_State *lua);
  42         /** convenience constructor for DataType::AUDIO with managed lifetime
  43          * @returns DataType::AUDIO
  44          */
  45         int datatype_ctor_audio (lua_State *L);
  46         /** convenience constructor for DataType::MIDI with managed lifetime
  47          * @returns DataType::MIDI
  48          */
  49         int datatype_ctor_midi (lua_State *L);
  50
  51         /** Create a null processor shared pointer
  52          *
  53          * This is useful for Track:bounce() to indicate no processing.
  54          */
  55         boost::shared_ptr<ARDOUR::Processor> nil_processor ();
  56
  57         /** create a new Lua Processor (Plugin)
  58          *
  59          * @param s Session Handle
  60          * @param p Identifier or Name of the Processor
  61          * @returns Processor object (may be nil)
  62          */
  63         boost::shared_ptr<ARDOUR::Processor> new_luaproc (ARDOUR::Session *s, const std::string& p);
  64
  65         /** search a Plugin
  66          *
  67          * @param id Plugin Name, ID or URI
  68          * @param type Plugin Type
  69          * @returns PluginInfo or nil if not found
  70          */
  71         boost::shared_ptr<ARDOUR::PluginInfo> new_plugin_info (const std::string& id, ARDOUR::PluginType type);
  72
  73         /** create a new Plugin Instance
  74          *
  75          * @param s Session Handle
  76          * @param id Plugin Name, ID or URI
  77          * @param type Plugin Type
  78          * @returns Processor or nil
  79          */
  80         boost::shared_ptr<ARDOUR::Processor> new_plugin (ARDOUR::Session *s, const std::string& id, ARDOUR::PluginType type, const std::string& preset = "");
  81
  82         /** set a plugin control-input parameter value
  83          *
  84          * @param proc Plugin-Processor
  85          * @param which control-input to set (starting at 0)
  86          * @param value value to set
  87          * @returns true on success, false on error or out-of-bounds value
  88          */
  89         bool set_processor_param (boost::shared_ptr<ARDOUR::Processor> proc, uint32_t which, float val);
  90
  91         /** get a plugin control parameter value
  92          *
  93          * @param proc Plugin-Processor
  94          * @param which control port to set (starting at 0, including ports of type input and output))
  95          * @param ok boolean variable contains true or false after call returned. to be checked by caller before using value.
  96          * @returns value
  97          */
  98         float get_processor_param (boost::shared_ptr<Processor> proc, uint32_t which, bool &ok);
  99
 100         /** set a plugin control-input parameter value
 101          *
 102          * This is a wrapper around set_processor_param which looks up the Processor by plugin-insert.
 103          *
 104          * @param proc Plugin-Insert
 105          * @param which control-input to set (starting at 0)
 106          * @param value value to set
 107          * @returns true on success, false on error or out-of-bounds value
 108          */
 109         bool set_plugin_insert_param (boost::shared_ptr<ARDOUR::PluginInsert> pi, uint32_t which, float val);
 110
 111         /** get a plugin control parameter value
 112          *
 113          * @param proc Plugin-Insert
 114          * @param which control port to query (starting at 0, including ports of type input and output)
 115          * @param ok boolean variable contains true or false after call returned. to be checked by caller before using value.
 116          * @returns value
 117          */
 118         float get_plugin_insert_param (boost::shared_ptr<ARDOUR::PluginInsert> pi, uint32_t which, bool &ok);
 119
 120         /**
 121          * A convenience function to get a Automation Lists and ParamaterDescriptor
 122          * for a given plugin control.
 123          *
 124          * This is equivalent to the following lua code
 125          * @code
 126          * function (processor, param_id)
 127          *  local plugininsert = processor:to_insert ()
 128          *  local plugin = plugininsert:plugin(0)
 129          *  local _, t = plugin:get_parameter_descriptor(param_id, ARDOUR.ParameterDescriptor ())
 130          *  local ctrl = Evoral.Parameter (ARDOUR.AutomationType.PluginAutomation, 0, param_id)
 131          *  local ac = pi:automation_control (ctrl, false)
 132          *  local acl = ac:alist()
 133          *  return ac:alist(), ac:to_ctrl():list(), t[2]
 134          * end
 135          * @endcode
 136          *
 137          * Example usage: get the third input parameter of first plugin on the given route
 138          * (Ardour starts counting at zero).
 139          * @code
 140          * local al, cl, pd = ARDOUR.LuaAPI.plugin_automation (route:nth_plugin (0), 3)
 141          * @endcode
 142          * @returns 3 parameters: AutomationList, ControlList, ParamaterDescriptor
 143          */
 144         int plugin_automation (lua_State *lua);
 145
 146         /**
 147          * A convenience function for colorspace HSL to RGB conversion.
 148          * All ranges are 0..1
 149          *
 150          * Example:
 151          * @code
 152          * local r, g, b, a = ARDOUR.LuaAPI.hsla_to_rgba (hue, saturation, luminosity, alpha)
 153          * @endcode
 154          * @returns 4 parameters: red, green, blue, alpha (in range 0..1)
 155          */
 156         int hsla_to_rgba (lua_State *lua);
 157
 158         /* Creates a filename from a series of elements using the correct separator for filenames.
 159          *
 160          * No attempt is made to force the resulting filename to be an absolute path.
 161          * If the first element is a relative path, the result will be a relative path.
 162          */
 163         int build_filename (lua_State *lua);
 164
 165         class Vamp {
 166         /** Vamp Plugin Interface
 167          *
 168          * Vamp is an audio processing plugin system for plugins that extract descriptive information
 169          * from audio data - typically referred to as audio analysis plugins or audio feature
 170          * extraction plugins.
 171          *
 172          * This interface allows to load a plugins and directly access it using the Vamp Plugin API.
 173          *
 174          * A convenience method is provided to analyze Ardour::Readable objects (Regions).
 175          */
 176                 public:
 177                         Vamp (const std::string&, float sample_rate);
 178                         ~Vamp ();
 179
 180                         /** Search for all available available Vamp plugins.
 181                          * @returns list of plugin-keys
 182                          */
 183                         static std::vector<std::string> list_plugins ();
 184
 185                         ::Vamp::Plugin* plugin () { return _plugin; }
 186
 187                         /** high-level abstraction to process a single channel of the given Readable.
 188                          *
 189                          * If the plugin is not yet initialized, initialize() is called.
 190                          *
 191                          * if @cb is not nil, it is called with the immediate
 192                          * Vamp::Plugin::Features on every process call.
 193                          *
 194                          * @param r readable
 195                          * @param channel channel to process
 196                          * @param fn lua callback function
 197                          * @return 0 on success
 198                          */
 199                         int analyze (boost::shared_ptr<ARDOUR::Readable> r, uint32_t channel, luabridge::LuaRef fn);
 200
 201                         /** call plugin():reset() and clear intialization flag */
 202                         void reset ();
 203
 204                         /** initialize the plugin for use with analyze().
 205                          *
 206                          * This is equivalent to plugin():initialise (1, 512, 1024)
 207                          * and prepares a plugin for analyze.
 208                          *
 209                          * Manual initialization is only required to set plugin-parameters
 210                          * which depend on prior initialization of the plugin.
 211                          *
 212                          * @code
 213                          * vamp:reset ()
 214                          * vamp:initialize ()
 215                          * vamp:plugin():setParameter (0, 1.5, nil)
 216                          * vamp:analyze (r, 0)
 217                          * @endcode
 218                          */
 219                         bool initialize ();
 220
 221                         bool initialized () const { return _initialized; }
 222
 223                         /** process given array of audio-samples.
 224                          *
 225                          * This is a lua-binding for vamp:plugin():process ()
 226                          *
 227                          * @param d audio-data, the vector must match the configured channel count
 228                          *    and hold a complete buffer for every channel as set during
 229                          *    plugin():initialise()
 230                          * @param rt timestamp matching the provided buffer.
 231                          * @returns features extracted from that data (if the plugin is causal)
 232                          */
 233                         ::Vamp::Plugin::FeatureSet process (const std::vector<float*>& d, ::Vamp::RealTime rt);
 234
 235                 private:
 236                         ::Vamp::Plugin* _plugin;
 237                         float           _sample_rate;
 238                         framecnt_t      _bufsize;
 239                         framecnt_t      _stepsize;
 240                         bool            _initialized;
 241
 242         };
 243
 244 } } /* namespace */
 245
 246 namespace ARDOUR { namespace LuaOSC {
 247         /** OSC transmitter
 248          *
 249          * A Class to send OSC messages.
 250          */
 251         class Address {
 252                 /*
 253                  * OSC is kinda special, lo_address is a void* and lo_send() has varags
 254                  * and typed arguments which makes it hard to bind, even lo_cpp.
 255                  */
 256                 public:
 257                         /** Construct a new OSC transmitter object
 258                          * @param uri the destination uri e.g. "osc.udp://localhost:7890"
 259                          */
 260                         Address (std::string uri) {
 261                                 _addr = lo_address_new_from_url (uri.c_str());
 262                         }
 263
 264                         ~Address () { if (_addr) { lo_address_free (_addr); } }
 265                         /** Transmit an OSC message
 266                          *
 267                          * Path (string) and type (string) must always be given.
 268                          * The number of following args must match the type.
 269                          * Supported types are:
 270                          *
 271                          *  'i': integer (lua number)
 272                          *
 273                          *  'f': float (lua number)
 274                          *
 275                          *  'd': double (lua number)
 276                          *
 277                          *  'h': 64bit integer (lua number)
 278                          *
 279                          *  's': string (lua string)
 280                          *
 281                          *  'c': character (lua string)
 282                          *
 283                          *  'T': boolean (lua bool) -- this is not implicily True, a lua true/false must be given
 284                          *
 285                          *  'F': boolean (lua bool) -- this is not implicily False, a lua true/false must be given
 286                          *
 287                          * @param lua: lua arguments: path, types, ...
 288                          * @returns boolean true if successful, false on error.
 289                          */
 290                         int send (lua_State *lua);
 291                 private:
 292                         lo_address _addr;
 293         };
 294
 295 }
 296
 297 class LuaTableRef {
 298         public:
 299                 LuaTableRef ();
 300                 ~LuaTableRef ();
 301
 302                 int get (lua_State* L);
 303                 int set (lua_State* L);
 304
 305         private:
 306                 struct LuaTableEntry {
 307                         LuaTableEntry (int kt, int vt)
 308                                 : keytype (kt)
 309                                 , valuetype (vt)
 310                         { }
 311
 312                         int keytype;
 313                         std::string k_s;
 314                         unsigned int k_n;
 315
 316                         int valuetype;
 317                         // LUA_TUSERDATA
 318                         const void* c;
 319                         void* p;
 320                         // LUA_TBOOLEAN
 321                         bool b;
 322                         // LUA_TSTRING:
 323                         std::string s;
 324                         // LUA_TNUMBER:
 325                         double n;
 326                 };
 327
 328                 std::vector<LuaTableEntry> _data;
 329
 330                 static void* findclasskey (lua_State *L, const void* key);
 331                 template<typename T>
 332                 static void assign (luabridge::LuaRef* rv, T key, const LuaTableEntry& s);
 333 };
 334
 335 } /* namespace */
 336
 337 #endif // _ardour_lua_api_h_