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/ladspa.h" 28 #include "seq_event-compat.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 #define DSSI_CUSTOMDATA_EXTENSION_KEY \ 174 DSSI_RESERVED_CONFIGURE_PREFIX "SUPPORTS_CUSTOMDATA" 175 176 /** 177 * get_program() 178 * 179 * This member is a function pointer that provides a description 180 * of a program (named preset sound) available on this synth. A 181 * plugin that does not support programs at all should set this 182 * member to NULL. 183 * 184 * The Index argument is an index into the plugin's list of 185 * programs, not a program number as represented by the Program 186 * field of the DSSI_Program_Descriptor. (This distinction is 187 * needed to support synths that use non-contiguous program or 188 * bank numbers.) 189 * 190 * This function returns a DSSI_Program_Descriptor pointer that is 191 * guaranteed to be valid only until the next call to get_program, 192 * deactivate, or configure, on the same plugin instance. This 193 * function must return NULL if passed an Index argument out of 194 * range, so that the host can use it to query the number of 195 * programs as well as their properties. 196 */ 197 const DSSI_Program_Descriptor *(*get_program)(LADSPA_Handle Instance, 198 unsigned long Index); 199 200 /** 201 * select_program() 202 * 203 * This member is a function pointer that selects a new program 204 * for this synth. The program change should take effect 205 * immediately at the start of the next run_synth() call. (This 206 * means that a host providing the capability of changing programs 207 * between any two notes on a track must vary the block size so as 208 * to place the program change at the right place. A host that 209 * wanted to avoid this would probably just instantiate a plugin 210 * for each program.) 211 * 212 * A plugin that does not support programs at all should set this 213 * member NULL. Plugins should ignore a select_program() call 214 * with an invalid bank or program. 215 * 216 * A plugin is not required to select any particular default 217 * program on activate(): it's the host's duty to set a program 218 * explicitly. The current program is invalidated by any call to 219 * configure(). 220 * 221 * A plugin is permitted to re-write the values of its input 222 * control ports when select_program is called. The host should 223 * re-read the input control port values and update its own 224 * records appropriately. (This is the only circumstance in 225 * which a DSSI plugin is allowed to modify its own input ports.) 226 */ 227 void (*select_program)(LADSPA_Handle Instance, 228 unsigned long Bank, 229 unsigned long Program); 230 231 /** 232 * get_midi_controller_for_port() 233 * 234 * This member is a function pointer that returns the MIDI 235 * controller number or NRPN that should be mapped to the given 236 * input control port. If the given port should not have any MIDI 237 * controller mapped to it, the function should return DSSI_NONE. 238 * The behaviour of this function is undefined if the given port 239 * number does not correspond to an input control port. A plugin 240 * that does not want MIDI controllers mapped to ports at all may 241 * set this member NULL. 242 * 243 * Correct values can be got using the macros DSSI_CC(num) and 244 * DSSI_NRPN(num) as appropriate, and values can be combined using 245 * bitwise OR: e.g. DSSI_CC(23) | DSSI_NRPN(1069) means the port 246 * should respond to CC #23 and NRPN #1069. 247 * 248 * The host is responsible for doing proper scaling from MIDI 249 * controller and NRPN value ranges to port ranges according to 250 * the plugin's LADSPA port hints. Hosts should not deliver 251 * through run_synth any MIDI controller events that have already 252 * been mapped to control port values. 253 * 254 * A plugin should not attempt to request mappings from 255 * controllers 0 or 32 (MIDI Bank Select MSB and LSB). 256 */ 257 int (*get_midi_controller_for_port)(LADSPA_Handle Instance, 258 unsigned long Port); 259 260 /** 261 * run_synth() 262 * 263 * This member is a function pointer that runs a synth for a 264 * block. This is identical in function to the LADSPA run() 265 * function, except that it also supplies events to the synth. 266 * 267 * A plugin may provide this function, run_multiple_synths() (see 268 * below), both, or neither (if it is not in fact a synth). A 269 * plugin that does not provide this function must set this member 270 * to NULL. Authors of synth plugins are encouraged to provide 271 * this function if at all possible. 272 * 273 * The Events pointer points to a block of EventCount ALSA 274 * sequencer events, which is used to communicate MIDI and related 275 * events to the synth. Each event is timestamped relative to the 276 * start of the block, (mis)using the ALSA "tick time" field as a 277 * frame count. The host is responsible for ensuring that events 278 * with differing timestamps are already ordered by time. 279 * 280 * See also the notes on activation, port connection etc in 281 * ladpsa.h, in the context of the LADSPA run() function. 282 * 283 * Note Events 284 * ~~~~~~~~~~~ 285 * There are two minor requirements aimed at making the plugin 286 * writer's life as simple as possible: 287 * 288 * 1. A host must never send events of type SND_SEQ_EVENT_NOTE. 289 * Notes should always be sent as separate SND_SEQ_EVENT_NOTE_ON 290 * and NOTE_OFF events. A plugin should discard any one-point 291 * NOTE events it sees. 292 * 293 * 2. A host must not attempt to switch notes off by sending 294 * zero-velocity NOTE_ON events. It should always send true 295 * NOTE_OFFs. It is the host's responsibility to remap events in 296 * cases where an external MIDI source has sent it zero-velocity 297 * NOTE_ONs. 298 * 299 * Bank and Program Events 300 * ~~~~~~~~~~~~~~~~~~~~~~~ 301 * Hosts must map MIDI Bank Select MSB and LSB (0 and 32) 302 * controllers and MIDI Program Change events onto the banks and 303 * programs specified by the plugin, using the DSSI select_program 304 * call. No host should ever deliver a program change or bank 305 * select controller to a plugin via run_synth. 306 */ 307 void (*run_synth)(LADSPA_Handle Instance, 308 unsigned long SampleCount, 309 snd_seq_event_t *Events, 310 unsigned long EventCount); 311 312 /** 313 * run_synth_adding() 314 * 315 * This member is a function pointer that runs an instance of a 316 * synth for a block, adding its outputs to the values already 317 * present at the output ports. This is provided for symmetry 318 * with LADSPA run_adding(), and is equally optional. A plugin 319 * that does not provide it must set this member to NULL. 320 */ 321 void (*run_synth_adding)(LADSPA_Handle Instance, 322 unsigned long SampleCount, 323 snd_seq_event_t *Events, 324 unsigned long EventCount); 325 326 /** 327 * run_multiple_synths() 328 * 329 * This member is a function pointer that runs multiple synth 330 * instances for a block. This is very similar to run_synth(), 331 * except that Instances, Events, and EventCounts each point to 332 * arrays that hold the LADSPA handles, event buffers, and 333 * event counts for each of InstanceCount instances. That is, 334 * Instances points to an array of InstanceCount pointers to 335 * DSSI plugin instantiations, Events points to an array of 336 * pointers to each instantiation's respective event list, and 337 * EventCounts points to an array containing each instantiation's 338 * respective event count. 339 * 340 * A host using this function must guarantee that ALL active 341 * instances of the plugin are represented in each call to the 342 * function -- that is, a host may not call run_multiple_synths() 343 * for some instances of a given plugin and then call run_synth() 344 * as well for others. 'All .. instances of the plugin' means 345 * every instance sharing the same LADSPA label and shared object 346 * (*.so) file (rather than every instance sharing the same *.so). 347 * 'Active' means any instance for which activate() has been called 348 * but deactivate() has not. 349 * 350 * A plugin may provide this function, run_synths() (see above), 351 * both, or neither (if it not in fact a synth). A plugin that 352 * does not provide this function must set this member to NULL. 353 * Plugin authors implementing run_multiple_synths are strongly 354 * encouraged to implement run_synth as well if at all possible, 355 * to aid simplistic hosts, even where it would be less efficient 356 * to use it. 357 */ 358 void (*run_multiple_synths)(unsigned long InstanceCount, 359 LADSPA_Handle *Instances, 360 unsigned long SampleCount, 361 snd_seq_event_t **Events, 362 unsigned long *EventCounts); 363 364 /** 365 * run_multiple_synths_adding() 366 * 367 * This member is a function pointer that runs multiple synth 368 * instances for a block, adding each synth's outputs to the 369 * values already present at the output ports. This is provided 370 * for symmetry with both the DSSI run_multiple_synths() and LADSPA 371 * run_adding() functions, and is equally optional. A plugin 372 * that does not provide it must set this member to NULL. 373 */ 374 void (*run_multiple_synths_adding)(unsigned long InstanceCount, 375 LADSPA_Handle *Instances, 376 unsigned long SampleCount, 377 snd_seq_event_t **Events, 378 unsigned long *EventCounts); 379 380 /** 381 * set_custom_data() 382 */ 383 int (*set_custom_data)(LADSPA_Handle Instance, 384 void *Data, 385 unsigned long DataLength); 386 387 /** 388 * get_custom_data() 389 */ 390 int (*get_custom_data)(LADSPA_Handle Instance, 391 void **Data, 392 unsigned long *DataLength); 393 394 } DSSI_Descriptor; 395 396 /** 397 * DSSI supports a plugin discovery method similar to that of LADSPA: 398 * 399 * - DSSI hosts may wish to locate DSSI plugin shared object files by 400 * searching the paths contained in the DSSI_PATH and LADSPA_PATH 401 * environment variables, if they are present. Both are expected 402 * to be colon-separated lists of directories to be searched (in 403 * order), and DSSI_PATH should be searched first if both variables 404 * are set. 405 * 406 * - Each shared object file containing DSSI plugins must include a 407 * function dssi_descriptor(), with the following function prototype 408 * and C-style linkage. Hosts may enumerate the plugin types 409 * available in the shared object file by repeatedly calling 410 * this function with successive Index values (beginning from 0), 411 * until a return value of NULL indicates no more plugin types are 412 * available. Each non-NULL return is the DSSI_Descriptor 413 * of a distinct plugin type. 414 */ 415 416 const DSSI_Descriptor *dssi_descriptor(unsigned long Index); 417 418 typedef const DSSI_Descriptor *(*DSSI_Descriptor_Function)(unsigned long Index); 419 420 /* 421 * Macros to specify particular MIDI controllers in return values from 422 * get_midi_controller_for_port() 423 */ 424 425 #define DSSI_CC_BITS 0x20000000 426 #define DSSI_NRPN_BITS 0x40000000 427 428 #define DSSI_NONE -1 429 #define DSSI_CONTROLLER_IS_SET(n) (DSSI_NONE != (n)) 430 431 #define DSSI_CC(n) (DSSI_CC_BITS | (n)) 432 #define DSSI_IS_CC(n) (DSSI_CC_BITS & (n)) 433 #define DSSI_CC_NUMBER(n) ((n) & 0x7f) 434 435 #define DSSI_NRPN(n) (DSSI_NRPN_BITS | ((n) << 7)) 436 #define DSSI_IS_NRPN(n) (DSSI_NRPN_BITS & (n)) 437 #define DSSI_NRPN_NUMBER(n) (((n) >> 7) & 0x3fff) 438 439 #ifdef __cplusplus 440 } 441 #endif 442 443 #endif /* DSSI_INCLUDED */ 444