1 /* -*- c-basic-offset: 4 -*- */ 2 3 /* dssi.h 4 5 DSSI version 1.0 6 Copyright (c) 2004, 2009 Chris Cannam, Steve Harris and Sean Bolton 7 8 This library is free software; you can redistribute it and/or 9 modify it under the terms of the GNU Lesser General Public License 10 as published by the Free Software Foundation; either version 2.1 of 11 the License, or (at your option) any later version. 12 13 This library is distributed in the hope that it will be useful, but 14 WITHOUT ANY WARRANTY; without even the implied warranty of 15 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 16 Lesser General Public License for more details. 17 18 You should have received a copy of the GNU Lesser General Public 19 License along with this library; if not, write to the Free Software 20 Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, 21 MA 02110-1301 USA 22 */ 23 24 #ifndef DSSI_INCLUDED 25 #define DSSI_INCLUDED 26 27 #include <ladspa.h> 28 #include <alsa/seq_event.h> 29 30 #define DSSI_VERSION "1.0" 31 #define DSSI_VERSION_MAJOR 1 32 #define DSSI_VERSION_MINOR 0 33 34 #ifdef __cplusplus 35 extern "C" { 36 #endif 37 38 /* 39 There is a need for an API that supports hosted MIDI soft synths 40 with GUIs in Linux audio applications. In time the GMPI initiative 41 should comprehensively address this need, but the requirement for 42 Linux applications to be able to support simple hosted synths is 43 here now, and GMPI is not. This proposal (the "DSSI Soft Synth 44 Interface" or DSSI, pronounced "dizzy") aims to provide a simple 45 solution in a way that we hope will prove complete and compelling 46 enough to support now, yet not so compelling as to supplant GMPI or 47 any other comprehensive future proposal. 48 49 For simplicity and familiarity, this API is based as far as 50 possible on existing work -- the LADSPA plugin API for control 51 values and audio processing, and the ALSA sequencer event types for 52 MIDI event communication. The GUI part of the proposal is quite 53 new, but may also be applicable retroactively to LADSPA plugins 54 that do not otherwise support this synth interface. 55 */ 56 57 typedef struct _DSSI_Program_Descriptor { 58 59 /** Bank number for this program. Note that DSSI does not support 60 MIDI-style separation of bank LSB and MSB values. There is no 61 restriction on the set of available banks: the numbers do not 62 need to be contiguous, there does not need to be a bank 0, etc. */ 63 unsigned long Bank; 64 65 /** Program number (unique within its bank) for this program. 66 There is no restriction on the set of available programs: the 67 numbers do not need to be contiguous, there does not need to 68 be a program 0, etc. */ 69 unsigned long Program; 70 71 /** Name of the program. */ 72 const char * Name; 73 74 } DSSI_Program_Descriptor; 75 76 77 typedef struct _DSSI_Descriptor { 78 79 /** 80 * DSSI_API_Version 81 * 82 * This member indicates the DSSI API level used by this plugin. 83 * If we're lucky, this will never be needed. For now all plugins 84 * must set it to 1. 85 */ 86 int DSSI_API_Version; 87 88 /** 89 * LADSPA_Plugin 90 * 91 * A DSSI synth plugin consists of a LADSPA plugin plus an 92 * additional framework for controlling program settings and 93 * transmitting MIDI events. A plugin must fully implement the 94 * LADSPA descriptor fields as well as the required LADSPA 95 * functions including instantiate() and (de)activate(). It 96 * should also implement run(), with the same behaviour as if 97 * run_synth() (below) were called with no synth events. 98 * 99 * In order to instantiate a synth the host calls the LADSPA 100 * instantiate function, passing in this LADSPA_Descriptor 101 * pointer. The returned LADSPA_Handle is used as the argument 102 * for the DSSI functions below as well as for the LADSPA ones. 103 */ 104 const LADSPA_Descriptor *LADSPA_Plugin; 105 106 /** 107 * configure() 108 * 109 * This member is a function pointer that sends a piece of 110 * configuration data to the plugin. The key argument specifies 111 * some aspect of the synth's configuration that is to be changed, 112 * and the value argument specifies a new value for it. A plugin 113 * that does not require this facility at all may set this member 114 * to NULL. 115 * 116 * This call is intended to set some session-scoped aspect of a 117 * plugin's behaviour, for example to tell the plugin to load 118 * sample data from a particular file. The plugin should act 119 * immediately on the request. The call should return NULL on 120 * success, or an error string that may be shown to the user. The 121 * host will free the returned value after use if it is non-NULL. 122 * 123 * Calls to configure() are not automated as timed events. 124 * Instead, a host should remember the last value associated with 125 * each key passed to configure() during a given session for a 126 * given plugin instance, and should call configure() with the 127 * correct value for each key the next time it instantiates the 128 * "same" plugin instance, for example on reloading a project in 129 * which the plugin was used before. Plugins should note that a 130 * host may typically instantiate a plugin multiple times with the 131 * same configuration values, and should share data between 132 * instances where practical. 133 * 134 * Calling configure() completely invalidates the program and bank 135 * information last obtained from the plugin. 136 * 137 * Reserved and special key prefixes 138 * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 139 * The DSSI: prefix 140 * ---------------- 141 * Configure keys starting with DSSI: are reserved for particular 142 * purposes documented in the DSSI specification. At the moment, 143 * there is one such key: DSSI:PROJECT_DIRECTORY. A host may call 144 * configure() passing this key and a directory path value. This 145 * indicates to the plugin and its UI that a directory at that 146 * path exists and may be used for project-local data. Plugins 147 * may wish to use the project directory as a fallback location 148 * when looking for other file data, or as a base for relative 149 * paths in other configuration values. 150 * 151 * The GLOBAL: prefix 152 * ------------------ 153 * Configure keys starting with GLOBAL: may be used by the plugin 154 * and its UI for any purpose, but are treated specially by the 155 * host. When one of these keys is used in a configure OSC call 156 * from the plugin UI, the host makes the corresponding configure 157 * call (preserving the GLOBAL: prefix) not only to the target 158 * plugin but also to all other plugins in the same instance 159 * group, as well as their UIs. Note that if any instance 160 * returns non-NULL from configure to indicate error, the host 161 * may stop there (and the set of plugins on which configure has 162 * been called will thus depend on the host implementation). 163 * See also the configure OSC call documentation in RFC.txt. 164 */ 165 char *(*configure)(LADSPA_Handle Instance, 166 const char *Key, 167 const char *Value); 168 169 #define DSSI_RESERVED_CONFIGURE_PREFIX "DSSI:" 170 #define DSSI_GLOBAL_CONFIGURE_PREFIX "GLOBAL:" 171 #define DSSI_PROJECT_DIRECTORY_KEY \ 172 DSSI_RESERVED_CONFIGURE_PREFIX "PROJECT_DIRECTORY" 173 174 /** 175 * get_program() 176 * 177 * This member is a function pointer that provides a description 178 * of a program (named preset sound) available on this synth. A 179 * plugin that does not support programs at all should set this 180 * member to NULL. 181 * 182 * The Index argument is an index into the plugin's list of 183 * programs, not a program number as represented by the Program 184 * field of the DSSI_Program_Descriptor. (This distinction is 185 * needed to support synths that use non-contiguous program or 186 * bank numbers.) 187 * 188 * This function returns a DSSI_Program_Descriptor pointer that is 189 * guaranteed to be valid only until the next call to get_program, 190 * deactivate, or configure, on the same plugin instance. This 191 * function must return NULL if passed an Index argument out of 192 * range, so that the host can use it to query the number of 193 * programs as well as their properties. 194 */ 195 const DSSI_Program_Descriptor *(*get_program)(LADSPA_Handle Instance, 196 unsigned long Index); 197 198 /** 199 * select_program() 200 * 201 * This member is a function pointer that selects a new program 202 * for this synth. The program change should take effect 203 * immediately at the start of the next run_synth() call. (This 204 * means that a host providing the capability of changing programs 205 * between any two notes on a track must vary the block size so as 206 * to place the program change at the right place. A host that 207 * wanted to avoid this would probably just instantiate a plugin 208 * for each program.) 209 * 210 * A plugin that does not support programs at all should set this 211 * member NULL. Plugins should ignore a select_program() call 212 * with an invalid bank or program. 213 * 214 * A plugin is not required to select any particular default 215 * program on activate(): it's the host's duty to set a program 216 * explicitly. The current program is invalidated by any call to 217 * configure(). 218 * 219 * A plugin is permitted to re-write the values of its input 220 * control ports when select_program is called. The host should 221 * re-read the input control port values and update its own 222 * records appropriately. (This is the only circumstance in 223 * which a DSSI plugin is allowed to modify its own input ports.) 224 */ 225 void (*select_program)(LADSPA_Handle Instance, 226 unsigned long Bank, 227 unsigned long Program); 228 229 /** 230 * get_midi_controller_for_port() 231 * 232 * This member is a function pointer that returns the MIDI 233 * controller number or NRPN that should be mapped to the given 234 * input control port. If the given port should not have any MIDI 235 * controller mapped to it, the function should return DSSI_NONE. 236 * The behaviour of this function is undefined if the given port 237 * number does not correspond to an input control port. A plugin 238 * that does not want MIDI controllers mapped to ports at all may 239 * set this member NULL. 240 * 241 * Correct values can be got using the macros DSSI_CC(num) and 242 * DSSI_NRPN(num) as appropriate, and values can be combined using 243 * bitwise OR: e.g. DSSI_CC(23) | DSSI_NRPN(1069) means the port 244 * should respond to CC #23 and NRPN #1069. 245 * 246 * The host is responsible for doing proper scaling from MIDI 247 * controller and NRPN value ranges to port ranges according to 248 * the plugin's LADSPA port hints. Hosts should not deliver 249 * through run_synth any MIDI controller events that have already 250 * been mapped to control port values. 251 * 252 * A plugin should not attempt to request mappings from 253 * controllers 0 or 32 (MIDI Bank Select MSB and LSB). 254 */ 255 int (*get_midi_controller_for_port)(LADSPA_Handle Instance, 256 unsigned long Port); 257 258 /** 259 * run_synth() 260 * 261 * This member is a function pointer that runs a synth for a 262 * block. This is identical in function to the LADSPA run() 263 * function, except that it also supplies events to the synth. 264 * 265 * A plugin may provide this function, run_multiple_synths() (see 266 * below), both, or neither (if it is not in fact a synth). A 267 * plugin that does not provide this function must set this member 268 * to NULL. Authors of synth plugins are encouraged to provide 269 * this function if at all possible. 270 * 271 * The Events pointer points to a block of EventCount ALSA 272 * sequencer events, which is used to communicate MIDI and related 273 * events to the synth. Each event is timestamped relative to the 274 * start of the block, (mis)using the ALSA "tick time" field as a 275 * frame count. The host is responsible for ensuring that events 276 * with differing timestamps are already ordered by time. 277 * 278 * See also the notes on activation, port connection etc in 279 * ladpsa.h, in the context of the LADSPA run() function. 280 * 281 * Note Events 282 * ~~~~~~~~~~~ 283 * There are two minor requirements aimed at making the plugin 284 * writer's life as simple as possible: 285 * 286 * 1. A host must never send events of type SND_SEQ_EVENT_NOTE. 287 * Notes should always be sent as separate SND_SEQ_EVENT_NOTE_ON 288 * and NOTE_OFF events. A plugin should discard any one-point 289 * NOTE events it sees. 290 * 291 * 2. A host must not attempt to switch notes off by sending 292 * zero-velocity NOTE_ON events. It should always send true 293 * NOTE_OFFs. It is the host's responsibility to remap events in 294 * cases where an external MIDI source has sent it zero-velocity 295 * NOTE_ONs. 296 * 297 * Bank and Program Events 298 * ~~~~~~~~~~~~~~~~~~~~~~~ 299 * Hosts must map MIDI Bank Select MSB and LSB (0 and 32) 300 * controllers and MIDI Program Change events onto the banks and 301 * programs specified by the plugin, using the DSSI select_program 302 * call. No host should ever deliver a program change or bank 303 * select controller to a plugin via run_synth. 304 */ 305 void (*run_synth)(LADSPA_Handle Instance, 306 unsigned long SampleCount, 307 snd_seq_event_t *Events, 308 unsigned long EventCount); 309 310 /** 311 * run_synth_adding() 312 * 313 * This member is a function pointer that runs an instance of a 314 * synth for a block, adding its outputs to the values already 315 * present at the output ports. This is provided for symmetry 316 * with LADSPA run_adding(), and is equally optional. A plugin 317 * that does not provide it must set this member to NULL. 318 */ 319 void (*run_synth_adding)(LADSPA_Handle Instance, 320 unsigned long SampleCount, 321 snd_seq_event_t *Events, 322 unsigned long EventCount); 323 324 /** 325 * run_multiple_synths() 326 * 327 * This member is a function pointer that runs multiple synth 328 * instances for a block. This is very similar to run_synth(), 329 * except that Instances, Events, and EventCounts each point to 330 * arrays that hold the LADSPA handles, event buffers, and 331 * event counts for each of InstanceCount instances. That is, 332 * Instances points to an array of InstanceCount pointers to 333 * DSSI plugin instantiations, Events points to an array of 334 * pointers to each instantiation's respective event list, and 335 * EventCounts points to an array containing each instantiation's 336 * respective event count. 337 * 338 * A host using this function must guarantee that ALL active 339 * instances of the plugin are represented in each call to the 340 * function -- that is, a host may not call run_multiple_synths() 341 * for some instances of a given plugin and then call run_synth() 342 * as well for others. 'All .. instances of the plugin' means 343 * every instance sharing the same LADSPA label and shared object 344 * (*.so) file (rather than every instance sharing the same *.so). 345 * 'Active' means any instance for which activate() has been called 346 * but deactivate() has not. 347 * 348 * A plugin may provide this function, run_synths() (see above), 349 * both, or neither (if it not in fact a synth). A plugin that 350 * does not provide this function must set this member to NULL. 351 * Plugin authors implementing run_multiple_synths are strongly 352 * encouraged to implement run_synth as well if at all possible, 353 * to aid simplistic hosts, even where it would be less efficient 354 * to use it. 355 */ 356 void (*run_multiple_synths)(unsigned long InstanceCount, 357 LADSPA_Handle *Instances, 358 unsigned long SampleCount, 359 snd_seq_event_t **Events, 360 unsigned long *EventCounts); 361 362 /** 363 * run_multiple_synths_adding() 364 * 365 * This member is a function pointer that runs multiple synth 366 * instances for a block, adding each synth's outputs to the 367 * values already present at the output ports. This is provided 368 * for symmetry with both the DSSI run_multiple_synths() and LADSPA 369 * run_adding() functions, and is equally optional. A plugin 370 * that does not provide it must set this member to NULL. 371 */ 372 void (*run_multiple_synths_adding)(unsigned long InstanceCount, 373 LADSPA_Handle *Instances, 374 unsigned long SampleCount, 375 snd_seq_event_t **Events, 376 unsigned long *EventCounts); 377 } DSSI_Descriptor; 378 379 /** 380 * DSSI supports a plugin discovery method similar to that of LADSPA: 381 * 382 * - DSSI hosts may wish to locate DSSI plugin shared object files by 383 * searching the paths contained in the DSSI_PATH and LADSPA_PATH 384 * environment variables, if they are present. Both are expected 385 * to be colon-separated lists of directories to be searched (in 386 * order), and DSSI_PATH should be searched first if both variables 387 * are set. 388 * 389 * - Each shared object file containing DSSI plugins must include a 390 * function dssi_descriptor(), with the following function prototype 391 * and C-style linkage. Hosts may enumerate the plugin types 392 * available in the shared object file by repeatedly calling 393 * this function with successive Index values (beginning from 0), 394 * until a return value of NULL indicates no more plugin types are 395 * available. Each non-NULL return is the DSSI_Descriptor 396 * of a distinct plugin type. 397 */ 398 399 const DSSI_Descriptor *dssi_descriptor(unsigned long Index); 400 401 typedef const DSSI_Descriptor *(*DSSI_Descriptor_Function)(unsigned long Index); 402 403 /* 404 * Macros to specify particular MIDI controllers in return values from 405 * get_midi_controller_for_port() 406 */ 407 408 #define DSSI_CC_BITS 0x20000000 409 #define DSSI_NRPN_BITS 0x40000000 410 411 #define DSSI_NONE -1 412 #define DSSI_CONTROLLER_IS_SET(n) (DSSI_NONE != (n)) 413 414 #define DSSI_CC(n) (DSSI_CC_BITS | (n)) 415 #define DSSI_IS_CC(n) (DSSI_CC_BITS & (n)) 416 #define DSSI_CC_NUMBER(n) ((n) & 0x7f) 417 418 #define DSSI_NRPN(n) (DSSI_NRPN_BITS | ((n) << 7)) 419 #define DSSI_IS_NRPN(n) (DSSI_NRPN_BITS & (n)) 420 #define DSSI_NRPN_NUMBER(n) (((n) >> 7) & 0x3fff) 421 422 #ifdef __cplusplus 423 } 424 #endif 425 426 #endif /* DSSI_INCLUDED */ 427