--- web/trunk/www.linuxsampler.org/api/draft-linuxsampler-protocol.html 2006/12/27 16:23:46 1002 +++ web/trunk/www.linuxsampler.org/api/draft-linuxsampler-protocol.html 2007/03/29 10:06:37 1137 @@ -3,140 +3,140 @@ - +
@@ -145,7 +145,7 @@-This Internet-Draft will expire on June 30, 2007.
+This Internet-Draft will expire on September 30, 2007.-Copyright © The Internet Society (2006).
+Copyright © The IETF Trust (2007).@@ -5256,6 +5272,25 @@ +optionally dotted number for the channel volume factor - (where a value < 1.0 means attenuation and a value > + (where a value < 1.0 means attenuation and a value > 1.0 means amplification)
MIDI_CONTROLLER - +
+++ + +a value between 0 and 127 reflecting the MIDI controller + which is able to modify the effect send's send level +
+
LEVEL - +
+++ +optionally dotted number reflecting the effect send's + current send level (where a value < 1.0 means attenuation + and a value > 1.0 means amplification) +
+
AUDIO_OUTPUT_ROUTING -
@@ -5289,6 +5324,10 @@S: "NAME: Reverb Send"
+"MIDI_CONTROLLER: 91" +
+"LEVEL: 0.3" +
"AUDIO_OUTPUT_ROUTING: 2,3"
"." @@ -5296,9 +5335,70 @@
-
TOC |
The front-end can alter the current name of an effect + send entity by sending the following command: +
++
++SET FX_SEND NAME <sampler-chan> <fx-send-id> <name> +
+
+ +
+Where <sampler-chan> is the sampler channel number + as returned by the "ADD CHANNEL" (Adding a new sampler channel) + or "LIST CHANNELS" (Getting all created sampler channel list) command, + <fx-send-id> reflects the numerical ID of the effect send entity + as returned by the "CREATE FX_SEND" (Adding an effect send to a sampler channel) + or "LIST FX_SENDS" (Listing all effect sends on a sampler channel) command and + <name> is the new name of the effect send entity, which + does not have to be unique. +
+Possible Answers: +
++
++"OK" - +
+++ + +on success +
+"ERR:<error-code>:<error-message>" - +
+++ + +in case it failed, providing an appropriate error code and error message +
+
+ +
+Example: +
++
++C: "SET FX_SEND NAME 0 0 'Fx Send 1'" +
+S: "OK" +
+
+ +
+TOC |
The front-end can alter the destination of an effect send's audio channel on a specific @@ -5379,9 +5479,152 @@
+
TOC |
The front-end can alter the MIDI controller of an effect + send entity by sending the following command: +
++
++SET FX_SEND MIDI_CONTROLLER <sampler-chan> <fx-send-id> <midi-ctrl> +
+
+ +
+Where <sampler-chan> is the sampler channel number + as returned by the "ADD CHANNEL" (Adding a new sampler channel) + or "LIST CHANNELS" (Getting all created sampler channel list) command, + <fx-send-id> reflects the numerical ID of the effect send entity + as returned by the "CREATE FX_SEND" (Adding an effect send to a sampler channel) + or "LIST FX_SENDS" (Listing all effect sends on a sampler channel) command and + <midi-ctrl> reflects the MIDI controller which shall be + able to modify the effect send's send level. +
+Possible Answers: +
++
++"OK" - +
+++ + +on success +
+"WRN:<warning-code>:<warning-message>" - +
+++ + +if MIDI controller was set, but there are noteworthy + issue(s) related, providing an appropriate warning code and + warning message +
+"ERR:<error-code>:<error-message>" - +
+++ + +in case it failed, providing an appropriate error code and error message +
+
+ +
+Example: +
++
++C: "SET FX_SEND MIDI_CONTROLLER 0 0 91" +
+S: "OK" +
+
+ +
+TOC |
The front-end can alter the current send level of an effect + send entity by sending the following command: +
++
++SET FX_SEND LEVEL <sampler-chan> <fx-send-id> <volume> +
+
+ +
+Where <sampler-chan> is the sampler channel number + as returned by the "ADD CHANNEL" (Adding a new sampler channel) + or "LIST CHANNELS" (Getting all created sampler channel list) command, + <fx-send-id> reflects the numerical ID of the effect send entity + as returned by the "CREATE FX_SEND" (Adding an effect send to a sampler channel) + or "LIST FX_SENDS" (Listing all effect sends on a sampler channel) command and + <volume> is an optionally dotted positive number (a value + smaller than 1.0 means attenuation, whereas a value greater than + 1.0 means amplification) reflecting the new send level. +
+Possible Answers: +
++
++"OK" - +
+++ + +on success +
+"WRN:<warning-code>:<warning-message>" - +
+++ + +if new send level was set, but there are noteworthy + issue(s) related, providing an appropriate warning code and + warning message +
+"ERR:<error-code>:<error-message>" - +
+++ + +in case it failed, providing an appropriate error code and error message +
+
+ +
+Example: +
++
++C: "SET FX_SEND LEVEL 0 0 0.15" +
+S: "OK" +
+
+ +
TOC |
The front-end can reset a particular sampler channel by sending the following command: @@ -5822,6 +6065,94 @@
The mentioned fields above don't have to be in particular order. Other fields might be added in future.
+TOC |
The client can ask for the current global sampler-wide volume + attenuation by sending the following command: +
++
++GET VOLUME +
+
+ +
+Possible Answers: +
++
++The sampler will always answer by returning the optional + dotted floating point coefficient, reflecting the current + global volume attenuation. + +
+
+ +
+Note: it is up to the respective sampler engine whether to obey + that global volume parameter or not, but in general all engines SHOULD + use this parameter. +
+TOC |
The client can alter the current global sampler-wide volume + attenuation by sending the following command: +
++
++SET VOLUME <volume> +
+
+ +
+Where <volume> should be replaced by the optional dotted + floating point value, reflecting the new global volume parameter. + This value might usually be in the range between 0.0 and 1.0, that + is for attenuating the overall volume. +
+Possible Answers: +
++
++"OK" - +
+++ + +on success +
+"WRN:<warning-code>:<warning-message>" - +
+++ + +if the global volume was set, but there are noteworthy + issue(s) related, providing an appropriate warning code and + warning message +
+"ERR:<error-code>:<error-message>" - +
+++ + +in case it failed, providing an appropriate error code and error message +
+
+ +
TOC |
DEFAULT - +
+++ + @@ -6153,6 +6493,8 @@either true or false, + defines whether this map is the default map +
+
S: "NAME: Standard Map"
+"DEFAULT: true" +
"."
@@ -6226,7 +6568,7 @@
-MAP MIDI_INSTRUMENT <map> +
MAP MIDI_INSTRUMENT [NON_MODAL] <map> <midi_bank> <midi_prog> <engine_name> <filename> <instrument_index> <volume_value> [<instr_load_mode>] [<name>] @@ -6246,7 +6588,7 @@ <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 + 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 @@ -6290,7 +6632,7 @@
The instrument will immediately be loaded - into memory in the background when this mapping + into memory 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 @@ -6347,13 +6689,19 @@
- 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. + By default, "MAP MIDI_INSTRUMENT" commands block until the mapping is + completely established in the sampler. The OPTIONAL "NON_MODAL" argument + however causes the respective "MAP MIDI_INSTRUMENT" command to return + immediately, that is to let the sampler establish the mapping in the + background. So this argument might be especially useful for mappings with + a "PERSISTENT" type, because these have to load the respective instruments + immediately and might thus block for a very long time. It is recommended + however to use the OPTIONAL "NON_MODAL" argument only if really necessary, + because it has the following drawbacks: as "NON_MODAL" instructions return + immediately, they may not necessarily return an error i.e. when the given + instrument file turns out to be corrupt, beside that subsequent commands + in a LSCP instruction sequence might fail, because mandatory mappings are + not yet completed.
Possible Answers: @@ -6420,7 +6768,7 @@
-C: "MAP MIDI_INSTRUMENT 1 8 120 gig '/home/joe/foodrums.gig' 0 1.0 PERSISTENT 'Foo Drumkit'" +
C: "MAP MIDI_INSTRUMENT NON_MODAL 1 8 120 gig '/home/joe/foodrums.gig' 0 1.0 PERSISTENT 'Foo Drumkit'"
S: "OK"
@@ -6709,7 +7057,7 @@@@ -6981,6 +7329,12 @@master volume of the instrument as optionally - dotted number (where a value < 1.0 means attenuation + dotted number (where a value < 1.0 means attenuation and a value > 1.0 means amplification)
/ CHANNEL_INFO
+/ FX_SEND_COUNT + +
+/ FX_SEND_INFO + +
/ MIDI_INSTRUMENT_MAP_COUNT
@@ -6999,6 +7353,9 @@/ TOTAL_VOICE_COUNT
+/ GLOBAL_INFO + +
@@ -7032,6 +7389,12 @@
/ CHANNEL_INFO
+/ FX_SEND_COUNT + +
+/ FX_SEND_INFO + +
/ MIDI_INSTRUMENT_MAP_COUNT
@@ -7050,22 +7413,25 @@/ TOTAL_VOICE_COUNT
+/ GLOBAL_INFO + +
map_instruction =
-MIDI_INSTRUMENT SP midi_map SP midi_bank SP midi_prog SP engine_name SP filename SP instrument_index SP volume_value +
MIDI_INSTRUMENT SP modal_arg midi_map SP midi_bank SP midi_prog SP engine_name SP filename SP instrument_index SP volume_value
-/ MIDI_INSTRUMENT SP midi_map SP midi_bank SP midi_prog SP engine_name SP filename SP instrument_index SP volume_value SP instr_load_mode +
/ MIDI_INSTRUMENT SP modal_arg midi_map SP midi_bank SP midi_prog SP engine_name SP filename SP instrument_index SP volume_value SP instr_load_mode
-/ MIDI_INSTRUMENT SP midi_map SP midi_bank SP midi_prog SP engine_name SP filename SP instrument_index SP volume_value SP entry_name +
/ MIDI_INSTRUMENT SP modal_arg midi_map SP midi_bank SP midi_prog SP engine_name SP filename SP instrument_index SP volume_value SP entry_name
-/ MIDI_INSTRUMENT SP midi_map SP midi_bank SP midi_prog SP engine_name SP filename SP instrument_index SP volume_value SP instr_load_mode SP entry_name +
/ MIDI_INSTRUMENT SP modal_arg midi_map SP midi_bank SP midi_prog SP engine_name SP filename SP instrument_index SP volume_value SP instr_load_mode SP entry_name
@@ -7197,6 +7563,9 @@
/ FX_SEND SP INFO SP sampler_channel SP fx_send_id
+/ VOLUME + +
@@ -7221,12 +7590,24 @@
/ MIDI_INSTRUMENT_MAP SP NAME SP midi_map SP map_name
+/ FX_SEND SP NAME SP sampler_channel SP fx_send_id SP fx_send_name + +
/ FX_SEND SP AUDIO_OUTPUT_CHANNEL SP sampler_channel SP fx_send_id SP audio_channel_index SP audio_channel_index
+/ FX_SEND SP MIDI_CONTROLLER SP sampler_channel SP fx_send_id SP midi_ctrl + +
+/ FX_SEND SP LEVEL SP sampler_channel SP fx_send_id SP volume_value + +
/ ECHO SP boolean
+/ VOLUME SP volume_value + +
@@ -7350,6 +7731,18 @@
+
modal_arg = +
++/* epsilon (empty argument) */ + +
+/ NON_MODAL SP + +
+
+ +
key_val_list =
@@ -7834,7 +8227,7 @@
-"NOTIFY:VOICE_COUNT:<sampler-channel> <voices> +
"NOTIFY:VOICE_COUNT:<sampler-channel> <voices>"
@@ -7937,9 +8330,69 @@ time events happening on the server, it is believed that an empty notification message is sufficient here.
-
+
TOC 8.10. +Number of effect sends changed
+ +Client may want to be notified when the number of effect sends on + a particular sampler channel is changed by issuing the following command: +
++
++SUBSCRIBE FX_SEND_COUNT +
++ +
+Server will start sending the following notification messages: +
++
++"NOTIFY:FX_SEND_COUNT:<channel-id> <fx-sends>" +
++ +
+where <channel-id> will be replaced by the numerical ID of the sampler + channel, on which the effect sends number is changed and <fx-sends> will + be replaced by the new number of effect sends on that channel. +
+
++
TOC 8.11. +Effect send information changed
+ +Client may want to be notified when changes were made to effect sends on a + a particular sampler channel by issuing the following command: +
++
++SUBSCRIBE FX_SEND_INFO +
++ +
+Server will start sending the following notification messages: +
++
++"NOTIFY:FX_SEND_INFO:<channel-id> <fx-send-id>" +
++ +
+where <channel-id> will be replaced by the numerical ID of the sampler + channel, on which an effect send entity is changed and <fx-send-id> will + be replaced by the numerical ID of the changed effect send. +
+
++
TOC 8.12. Total number of active voices changed
Client may want to be notified when the total number of voices on the @@ -7958,7 +8411,7 @@
-"NOTIFY:TOTAL_VOICE_COUNT:<voices> +
"NOTIFY:TOTAL_VOICE_COUNT:<voices>"
@@ -7968,7 +8421,7 @@
-
TOC 8.11. +
8.13. Number of MIDI instrument maps changed
Client may want to be notified when the number of MIDI instrument maps on the @@ -7997,7 +8450,7 @@
-
TOC 8.12. +
8.14. MIDI instrument map information changed
Client may want to be notified when changes were made to MIDI instrument maps on the @@ -8030,7 +8483,7 @@
-
TOC 8.13. +
8.15. Number of MIDI instruments changed
Client may want to be notified when the number of MIDI instrument maps on the @@ -8060,7 +8513,7 @@
-
TOC 8.14. +
8.16. MIDI instrument information changed
Client may want to be notified when changes were made to MIDI instruments on the @@ -8092,9 +8545,38 @@ time events happening on the server, it is believed that an empty notification message is sufficient here.
+
++
TOC 8.17. +Global settings changed
+ +Client may want to be notified when changes to the global settings + of the sampler were made by issuing the following command: +
++
++SUBSCRIBE GLOBAL_INFO +
++ +
+Server will start sending the following types of notification messages: +
++
++"NOTIFY:GLOBAL_INFO:VOLUME <volume>" - Notifies that the + golbal volume of the sampler is changed, where <volume> will be + replaced by the optional dotted floating point value, reflecting the + new global volume parameter. +
++ +
-
TOC 8.15. +
8.18. Miscellaneous and debugging events
Client may want to be notified of miscellaneous and debugging events occurring at @@ -8189,7 +8671,7 @@
TOC Full Copyright Statement
-Copyright © The Internet Society (2006).
+Copyright © The IETF Trust (2007).This document is subject to the rights, licenses and restrictions contained in BCP 78, @@ -8198,13 +8680,13 @@
This document and the information contained herein are provided on an “AS IS” basis and THE CONTRIBUTOR, -THE ORGANIZATION HE/SHE REPRESENTS OR IS SPONSORED BY (IF ANY), -THE INTERNET SOCIETY AND THE INTERNET ENGINEERING TASK FORCE DISCLAIM -ALL WARRANTIES, -EXPRESS OR IMPLIED, -INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE -INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED -WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
+THE ORGANIZATION HE/SHE REPRESENTS +OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST +AND THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, +EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT +THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY +IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR +PURPOSE.Intellectual Property
The IETF takes no position regarding the validity or scope of any