[linux-audio-dev] LACPA

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 */