[linux-audio-dev] LACPA

From: Ralf Beck <musical_snake@email-addr-hidden>
Date: Sun Apr 23 2006 - 10:12:25 EEST

Since people seem to see the necessity for some more functionality
within plugins, i want
to present LACPA (Linux Audio Cluster Plugin Api), which was intended to
be the
plugin api of the linux audio cluster (which i never finished due to the
lack of time).

Its main features:
* usable for midi/audio plugins (one plugin could be a host for other
plugins as well)
* sampleaccurate timeinfo for sequencers, tempo-synched
effects/instruments, video
* fixed size audiobuffers (good for use with networks and frequency
domain effects)
* extensible while keeping binary downward compatability
* no dependencies between host's and plugin's gui (plugins guis are
supposed to run in their own process)

BTW, by adding a control type "message", the realtime message part of
LACPA could be easily
added to LADSPA without breaking existing hosts .

Ralf

#ifndef LACPA
#define LACPA

#ifdef __cplusplus
extern "C" {
#endif

/* return value for all functions */

#define LACPA_NOT_PROCESSED 0
#define LACPA_PROCESSED 1

typedef float LACPA_FRAME; /* audio type -1.0 .. +1.0 */
typedef float LACPA_CONTROL; /* control type 0.0 .. 1.0 */

/* opaque plugin type */
typedef void * LACPA_PLUGIN;

/* initialise is called by host immediately after loading the library:
   PARAMETERS:
   plug2host: callback for plug -> host non-realtime messages
*/

int (*initialise)(int (*plug2host)(LACPA_PLUGIN plug, int msg, void *arg, void *ret));

/* create a new plugin instance
   Note:
     a plugin is initially suspended and has its editor closed
*/
 
LACPA_PLUGIN (*create)(void);

/* delete a plugin instance
   PARAMETERS:
   plug : plugin instance returne by create()
*/

int (*delete)(LACPA_PLUGIN plug);

/* callback to be used by the plugin to send a
   non-realtime message to the host.
   Must be supplied by the host in initialise().

   PARAMETERS:
   plug: plugin instance returned by create()
   msgtype: non-realtime plug -> host message type
   arg: pointer to message specific arguments
   ret: pointer for returning values

   int (*plug2host)(LACPA_PLUGIN plug, int msgtype, void *arg, void *ret);

   Following plug -> host messages are currently defined:
   LACPA_EDIT_OFF: arg = NULL, ret = NULL: editor window has been closed
   LACPA_IO_CHANGE: arg = NULL, ret = NULL: plugin changed its inputs or outputs
               In response to this the host is supposed to suspend the plugin and
               reread the i/o configuration
*/

#define LACPA_EDIT_OFF 1
#define LACPA_IO_CHANGE 2

/* non-realtime host to plugin messages
   PARAMETERS:
   plug: plugin instance returned by create()
   msgtype: non-realtime host -> plugin message type
   arg: message specific arguments
   ret: returned values
*/

   int (*host2plug)(LACPA_PLUGIN instance, int msgtype, void *arg, void *ret);
 
/* Following plug -> host messages are currently defined:
   LACPA_VENDOR_SPECIFIC: used for vendor specific messages
   LACPA_PROCESS_START: arg = NULL, ret = NULL: process will be called from now
   LACPA_PROCESS_STOP: arg = NULL, ret = NULL: process will not be called from now
   LACPA_PLUGIN_NAME: arg = NULL, ret = char * = name of plugin
   LACPA_PLUGIN_CATEGORY: arg = NULL, ret = char * = name of plugin category
   LACPA_PLUGIN_VENDOR: arg = NULL, ret = char * = name of plugin vendor
   LACPA_SAMPLERATE: arr = int samplerate, ret = NULL: set the samplerate (called while suspended)
   LACPA_BUFFERSIZE: arg = int buffersize, ret = NULL: set the buffersize (called while suspended)
   LACPA_NUM_PARAMETERS: arg = NULL, ret = int = number of controls
   LACPA_CONTROL_VALUE: arg = struct control, ret = char * = human readable of the value (e.g. "-20")
   LACPA_CONTROL_UNIT: arg = int index, ret = char * = human readable unit of value (e.g. "dB")
   LACPA_CONTROL_NAME: arg = int index, ret = char * = name of control (e.g. "Gain")
   LACPA_NUM_INPUTS: arg = NULL, ret = int = number of inputs
   LACPA_NUM_OUTPUTS: arg = NULL, ret = int = number of outputs
   LACPA_INPUT_NAME: arg = int index, ret = char * = name of audio channel (e.g. "left input")
   LACPA_OUTPUT_NAME: arg = int index, ret = char * = name of audio channel (e.g. "left output")
   LACPA_TICKS_PER_BEAT: arg int tpb: set the ticks per beat (sequencer resolution)
   LACPA_SMPTE_TYPE: arg int smpte: set the SMPTE type (see below)
   LACPA_LATENCY: arg = NULL, ret = int latency: get plugin latency in samples
   LACPA_EDITOR_ON: arg = NULL, ret = NULL: instruct plugin to open its editor window
   LACPA_EDITOR_OFF: arg = NULL, ret = NULL: instruct plugin to close its editor window
*/

#define LACPA_VENDOR_SPECIFIC 0
#define LACPA_PROCESS_START 1
#define LACPA_PROCESS_STOP 2
#define LACPA_PLUGIN_NAME 3
#define LACPA_PLUGIN_CATEGORY 4
#define LACPA_PLUGIN_VENDOR 5
#define LACPA_SAMPLERATE 6
#define LACPA_BUFFERSIZE 7
#define LACPA_NUM_CONTROLS 8
#define LACPA_CONTROL_NAME 9
#define LACPA_CONTROL_UNIT 10
#define LACPA_CONTROL_VALUE_STRING 11
#define LACPA_NUM_INPUTS 12
#define LACPA_NUM_OUTPUTS 13
#define LACPA_INPUT_NAME 14
#define LACPA_OUTPUT_NAME 15
#define LACPA_TICKS_PER_BEAT 16
#define LACPA_SMPTE_TYPE 17
#define LACPA_LATENCY 18
#define LACPA_EDITOR_ON 19
#define LACPA_EDITOR_OFF 20
                           
/* SMPTE types */

#define LACPA_SMPTE_24 1
#define LACPA_SMPTE_25 2
#define LACPA_SMPTE_30 3
#define LACPA_SMPTE_29d 4
#define LACPA_SMPTE_30d 5

/* realtime processing routine
   PARAMETERS:
   plug: plugin instance returned by create()
   inmsg: pointer to linked list of realtime messages for plugin
   outmsg: pointer to pointer to linked list for realtime messages produced by plugin
   in: pointer to array of pointers to input buffers
   out: pointer to array of pointers to output buffers
*/

struct lacpa_rt_msg;
typedef struct lacpa_rt_msg *LACPA_MSG;

int (*process)(LACPA_PLUGIN plug,
               LACPA_MSG *inmsg, LACPA_MSG **outmsg,
               LACPA_FRAME **in, LACPA_FRAME **out);

/* realtime messages to be sent to/from plugin through process():

   LACPA_MIDI: 1-3 byte midi messages
   LACPA_SYSEX: Midi sysex message
   LACPA_CTRL: control, range 0.0 - 1.0
   LACPA_BBT: Timeinfo in Beats/Bar/Ticks
   LACPA_SMPTE: Timeinfo in SMPTE FRAMES
   -- more to be added as needed
*/

#define LACPA_MIDI 0
#define LACPA_SYSEX 1
#define LACPA_CTRL 2
#define LACPA_BBT 3
#define LACPA_SMPTE 4

struct lacpa_midi {
   int port;
   char data[4];
};

struct lacpa_sysex {
    int port;
    char *sysex;
};

struct lacpa_ctrl {
    int index;
    LACPA_CONTROL value;
};

struct lacpa_tempo {
     float tempo;
};

struct lacpa_bbt {
     int bar;
     int beat;
     int tick;
};

struct lacpa_smpte {
   int hour;
   int minute;
   int second;
   int frame;
};

struct lacpa_rt_msg {
     LACPA_MSG next; /* next message in list */
     int type; /* type of realtime message */
     int frame; /* frame number within current process buffer */
     union {
       struct lacpa_midi m;
       struct lacpa_sysex x;
       struct lacpa_ctrl p;
       struct lacpa_tempo t;
       struct lacpa_bbt b;
       struct lacpa_smpte s;
     } lacpa_msg;
};

#ifdef __cplusplus
}
#endif

#endif /* LACPA */
Received on Sun Apr 23 12:15:14 2006

This archive was generated by hypermail 2.1.8 : Sun Apr 23 2006 - 12:15:14 EEST