|
@@ -153,7 +153,7 @@ The list of Internet-Draft Shadow Directories can be accessed at http://www.ietf.org/shadow.html.
-This Internet-Draft will expire on May 29, 2007.
+This Internet-Draft will expire on May 30, 2007.
@@ -318,6 +318,20 @@
Reset sampler
6.6.4.
General sampler informations
+ 6.7.
+MIDI Instrument Mapping
+ 6.7.1.
+Create or replace a MIDI instrument map entry
+ 6.7.2.
+Getting ammount of MIDI instrument map entries
+ 6.7.3.
+Getting indeces of all MIDI instrument map entries
+ 6.7.4.
+Remove an entry from the MIDI instrument map
+ 6.7.5.
+Get current settings of MIDI instrument map entry
+ 6.7.6.
+Clear MIDI instrument map
7.
Command Syntax
8.
@@ -336,9 +350,9 @@
Total number of active voices changed
8.7.
Miscellaneous and debugging events
-9.
+9.
Security Considerations
-10.
+10.
Acknowledgments
11.
References
@@ -5138,6 +5152,562 @@
The mentioned fields above don't have to be in particular order. Other fields might be added in future.
+| TOC |
The MIDI protocol provides a way to switch between instruments + by sending so called MIDI bank select and MIDI program change + messages which are essentially just numbers. The following commands + allow to actually map arbitrary MIDI bank select / program change + numbers with real instruments. +
+By default, that is when the sampler is launched, this map will + be empty, thus the sampler will simply ignore all program change + messages. The front-end has to explicitly add entries to the map + so the sampler knows how to react on a given program change + message, that is by switching to the respectively defined engine + type and loading the respective instrument. +
+Also note per MIDI specification a bank select message does not + cause to switch to another instrument. Instead when receiving a + bank select message the bank value will be stored and a subsequent + program change message (which may occur at any time) will finally + cause the sampler to switch to the respective instrument as + reflected by the current MIDI instrument map. +
+| TOC |
The front-end can create a new or replace an existing entry + in the sampler's MIDI instrument map by sending the following + command: +
++
++MAP MIDI_INSTRUMENT <midi_bank_msb> + <midi_bank_lsb> <midi_prog> <engine_name> + <filename> <instrument_index> <volume_value> + [<instr_load_mode>] [<name>] +
+
+ +
+Where <midi_bank_msb> is an integer value between + 0..127 reflecting the MIDI bank select MSB (coarse) index, + <midi_bank_lsb> an integer value between 0..127 reflecting + the MIDI bank select LSB (fine) index, <midi_prog> an + integer value between 0..127 reflecting the MIDI program change + index, <engine_name> a sampler engine name as returned by + the "LIST AVAILABLE_ENGINES" (Getting all available engines) + command (not encapsulated into apostrophes), <filename> the name + of the instrument's file to be deployed (encapsulated into apostrophes), <instrument_index> the index (integer value) of the instrument + within the given file, <volume_value> reflects the master + volume of the instrument as optionally dotted number (where a + value < 1.0 means attenuation and a value > 1.0 means + amplification). This parameter easily allows to adjust the + volume of all intruments within a custom instrument map + without having to adjust their instrument files. The + OPTIONAL <instr_load_mode> argument defines the life + time of the instrument, that is when the instrument should + be loaded, when freed and has exactly the following + possibilities: +
++
++"ON_DEMAND" - +
+++ + +The instrument will be loaded when needed, + that is when demanded by at least one sampler + channel. It will immediately be freed from memory + when not needed by any sampler channel anymore. +
+"ON_DEMAND_HOLD" - +
+++ + +The instrument will be loaded when needed, + that is when demanded by at least one sampler + channel. It will be kept in memory even when + not needed by any sampler channel anymore. + Instruments with this mode are only freed + when the sampler is reset or all mapping + entries with this mode (and respective + instrument) are explicitly changed to + "ON_DEMAND" and no sampler channel is using + the instrument anymore. +
+"PERSISTENT" - +
+++ + +The instrument will immediately be loaded + into memory in the background when this mapping + command is sent and the instrument is kept all + the time. Instruments with this mode are + only freed when the sampler is reset or all + mapping entries with this mode (and + respective instrument) are explicitly + changed to "ON_DEMAND" and no sampler + channel is using the instrument anymore. +
+not supplied - +
+++ + +In case there is no <instr_load_mode> + argument given, it will be up to the + InstrumentManager to decide which mode to use. + Usually it will use "ON_DEMAND" if an entry + for the given instrument does not exist in + the InstrumentManager's list yet, otherwise + if an entry already exists, it will simply + stick with the mode currently reflected by + the already existing entry, that is it will + not change the mode. +
+
+ +
++ The <instr_load_mode> argument thus allows to define an + appropriate strategy (low memory consumption vs. fast + instrument switching) for each instrument individually. Note, the + following restrictions apply to this argument: "ON_DEMAND_HOLD" and + "PERSISTENT" have to be supported by the respective sampler engine + (which is technically the case when the engine provides an + InstrumentManager for its format). If this is not the case the + argument will automatically fall back to the default value + "ON_DEMAND". Also the load mode of one instrument may + automatically change the laod mode of other instrument(s), i.e. + because the instruments are part of the same file and the + engine does not allow a way to manage load modes for them + individually. Due to this, in case the frontend shows the + load modes of entries, the frontend should retrieve the actual + mode by i.e. sending + "GET MIDI_INSTRUMENT INFO" (Get current settings of MIDI instrument map entry) + command(s). Finally the OPTIONAL <name> argument allows to + set a custom name (encapsulated into apostrophes) for the mapping + entry, useful for frontends for displaying an appropriate name for + mapped instruments (using + "GET MIDI_INSTRUMENT INFO" (Get current settings of MIDI instrument map entry)). + +
++ The "MAP MIDI_INSTRUMENT" command + will immediately return, thus it will not block when an + instrument is to be loaded due to a "PERSISTENT" type + entry as instruments are loaded in the background. As a + consequence this command may not necessarily return an error + i.e. when the given instrument file does not exist or may + turn out to be corrupt. + +
+Possible Answers: +
++
++"OK" - +
+++ + +usually +
+"ERR:<error-code>:<error-message>" - +
+++ + +when the given engine does not exist or a value + is out of range +
+
+ +
+Examples: +
++
++C: "MAP MIDI_INSTRUMENT 3 0 0 gig '/usr/share/Steinway D.gig' 0 0.8 PERSISTENT" +
+S: "OK" +
+
+ +
++
++C: "MAP MIDI_INSTRUMENT 127 4 50 gig '/home/john/foostrings.gig' 7 1.0" +
+S: "OK" +
+
+ +
++
++C: "MAP MIDI_INSTRUMENT 0 0 0 gig '/usr/share/piano.gig' 0 1.0 'Normal Piano'" +
+S: "OK" +
+C: "MAP MIDI_INSTRUMENT 1 0 0 gig '/usr/share/piano.gig' 0 0.25 'Silent Piano'" +
+S: "OK" +
+
+ +
++
++C: "MAP MIDI_INSTRUMENT 99 8 120 gig '/home/joe/foodrums.gig' 0 1.0 PERSISTENT 'Foo Drumkit'" +
+S: "OK" +
+
+ +
+| TOC |
The front-end can query the amount of currently existing MIDI + instrument map entries by sending the following + command: +
++
++GET MIDI_INSTRUMENTS +
+
+ +
+Possible Answers: +
++
++LinuxSampler will answer by sending the current number of + entries in the sampler's MIDI instrument map. +
+
+ +
+Example: +
++
++C: "GET MIDI_INSTRUMENTS" +
+S: "634" +
+
+ +
+| TOC |
The front-end can query a list of all currently existing MIDI + instrument map entries by sending the following command: +
++
++LIST MIDI_INSTRUMENTS +
+
+ +
+Possible Answers: +
++
++LinuxSampler will answer by sending a comma separated + list of MIDI bank MSB (coarse) - MIDI bank LSB (fine) - + MIDI program triples, where each triple is encapsulated + into curly braces. The list is returned in one single + line. Each triple just reflects the key of the respective + map entry, thus subsequent + "GET MIDI_INSTRUMENT INFO" (Get current settings of MIDI instrument map entry) + command(s) are necessary to retrieve detailed informations + about each entry. +
+
+ +
+Example: +
++
++C: "LIST MIDI_INSTRUMENTS" +
+S: "{0,0,0},{0,0,1},{120,0,3},{120,0,4},{23,127,127}" +
+
+ +
+| TOC |
The front-end can delete an entry from the MIDI instrument + map by sending the following command: +
++
++UNMAP MIDI_INSTRUMENT <midi_bank_msb> <midi_bank_lsb> <midi_prog> +
+
+ +
++ Where <midi_bank_msb> is an integer value between 0..127 + reflecting the MIDI bank MSB (coarse) value, <midi_bank_lsb> + an integer value between 0..127 reflecting the MIDI bank LSB + (fine) value and <midi_prog> an integer value between + 0..127 reflecting the MIDI program value of the map entrie's key + index triple. + +
+Possible Answers: +
++
++"OK" - +
+++ + +usually +
+"ERR:<error-code>:<error-message>" - +
+++ + +when index out of bounds +
+
+ +
+Example: +
++
++C: "UNMAP MIDI_INSTRUMENT 2 40 127" +
+S: "OK" +
+
+ +
+| TOC |
The front-end can retrieve the current settings of a certain + instrument map entry by sending the following command: +
++
++GET MIDI_INSTRUMENT INFO <midi_bank_msb> <midi_bank_lsb> <midi_prog> +
+
+ +
++ Where <midi_bank_msb> is an integer value between 0..127 + reflecting the MIDI bank MSB (coarse) value, <midi_bank_lsb> + an integer value between 0..127 reflecting the MIDI bank LSB + (fine) value and <midi_prog> an integer value between + 0..127 reflecting the MIDI program value of the map entrie's key + index triple. + +
+Possible Answers: +
++
++LinuxSampler will answer by sending a <CRLF> + separated list. Each answer line begins with the + information category name followed by a colon and then + a space character <SP> and finally the info + character string to that info category. At the moment + the following categories are defined: +
+"NAME" - +
+++ + +Name for this MIDI instrument map entry (if defined). + This name shall be used by frontends for displaying a + name for this mapped instrument. It can be set and + changed with the + "MAP MIDI_INSTRUMENT" (Create or replace a MIDI instrument map entry) + command and does not have to be unique. +
+"ENGINE_NAME" - +
+++ + +Name of the engine to be deployed for this + instrument. +
+"INSTRUMENT_FILE" - +
+++ + +File name of the instrument. +
+"INSTRUMENT_NR" - +
+++ + +Index of the instrument within the file. +
+"INSTRUMENT_NAME" - +
+++ + +Name of the loaded instrument as reflected by its file. + In contrast to the "NAME" field, the "INSTRUMENT_NAME" field + cannot be changed. +
+"LOAD_MODE" - +
+++ + +Life time of instrument + (see "MAP MIDI_INSTRUMENT" (Create or replace a MIDI instrument map entry) for details about this setting). +
+"VOLUME" - +
+++ + +master volume of the instrument as optionally + dotted number (where a value < 1.0 means attenuation + and a value > 1.0 means amplification) +
+The mentioned fields above don't have to be in particular order. +
+
+ +
+Example: +
++
++C: "GET MIDI_INSTRUMENT INFO 3 45 120" +
+S: "NAME: Drums for Foo Song" +
+"ENGINE_NAME: GigEngine" +
+"INSTRUMENT_FILE: /usr/share/joesdrumkit.gig" +
+"INSTRUMENT_NR: 0" +
+"INSTRUMENT_NAME: Joe's Drumkit" +
+"LOAD_MODE: PERSISTENT" +
+"VOLUME: 1.0" +
+"." +
+
+ +
+| TOC |
The front-end can clear the whole MIDI instrument map, that + is delete all entries by sending the following command: +
++
++CLEAR MIDI_INSTRUMENTS +
+
+ +
+Possible Answers: +
++
++"OK" - +
+++ + +always +
+
+ +
+Example: +
++
++C: "CLEAR MIDI_INSTRUMENTS" +
+S: "OK" +
+
+ +
| TOC |
ADD SP CHANNEL
+/ MAP SP map_instruction + +
+/ UNMAP SP unmap_instruction + +
/ GET SP get_instruction
@@ -5219,7 +5795,8 @@/ LOAD SP load_instruction
-/ REMOVE SP CHANNEL SP sampler_channel +
/ REMOVE SP remove_instruction +
/ SET SP set_instruction @@ -5234,7 +5811,10 @@
/ SELECT SP text
-/ RESET SP CHANNEL SP sampler_channel +
/ RESET SP reset_instruction + +
+/ CLEAR SP clear_instruction
/ RESET @@ -5300,6 +5880,42 @@
+
map_instruction = +
++MIDI_INSTRUMENT SP midi_bank_msb SP midi_bank_lsb SP midi_prog SP engine_name SP filename SP instrument_index SP volume_value + +
+/ MIDI_INSTRUMENT SP midi_bank_msb SP midi_bank_lsb SP midi_prog SP engine_name SP filename SP instrument_index SP volume_value SP instr_load_mode + +
+/ MIDI_INSTRUMENT SP midi_bank_msb SP midi_bank_lsb SP midi_prog SP engine_name SP filename SP instrument_index SP volume_value SP entry_name + +
+/ MIDI_INSTRUMENT SP midi_bank_msb SP midi_bank_lsb SP midi_prog SP engine_name SP filename SP instrument_index SP volume_value SP instr_load_mode SP entry_name + +
+
+ +
+unmap_instruction = +
++MIDI_INSTRUMENT SP midi_bank_msb SP midi_bank_lsb SP midi_prog + +
+
+ +
+remove_instruction = +
++CHANNEL SP sampler_channel + +
+
+ +
get_instruction =
@@ -5381,6 +5997,12 @@/ TOTAL_VOICE_COUNT_MAX
+/ MIDI_INSTRUMENTS + +
+/ MIDI_INSTRUMENT SP INFO SP midi_bank_msb SP midi_bank_lsb SP midi_prog + +
@@ -5426,6 +6048,24 @@
+
reset_instruction = +
++CHANNEL SP sampler_channel + +
+
+ +
+clear_instruction = +
++MIDI_INSTRUMENTS + +
+
+ +
destroy_instruction =
@@ -5534,6 +6174,9 @@/ AVAILABLE_AUDIO_OUTPUT_DRIVERS
+/ MIDI_INSTRUMENTS + +
@@ -5558,6 +6201,21 @@
+
instr_load_mode = +
++ON_DEMAND + +
+/ ON_DEMAND_HOLD + +
+/ PERSISTENT + +
+
+ +
device_index =
@@ -5615,6 +6273,33 @@
+
midi_bank_msb = +
++number + +
+
+ +
+midi_bank_lsb = +
++number + +
+
+ +
+midi_prog = +
++number + +
+
+ +
volume_value =
@@ -5663,6 +6348,15 @@
+
entry_name = +
++stringval + +
+
+ +
param_val_list =
@@ -5904,7 +6598,7 @@ wants to send to the client. Client MAY display this data to the user AS IS to facilitate debugging. -
+
TOC 9. Security Considerations
@@ -5913,7 +6607,7 @@ connect, running LinuxSampler might be a security risk for the host system the LinuxSampler instance is running on. -
+
TOC 10. Acknowledgments