@@ -173,11 +173,11 @@ The list of Internet-Draft Shadow Directories can be accessed at http://www.ietf.org/shadow.html.
-This Internet-Draft will expire on November 25, 2007.
+This Internet-Draft will expire on March 14, 2009.-Copyright © The IETF Trust (2007).
+Copyright © The IETF Trust (2008).@@ -3299,7 +3329,8 @@ or "LIST MIDI_INPUT_DEVICES" (Getting all created MIDI input device list) command, <port> by the MIDI port number, <key> by the name of the parameter to change and <value> by the new value for this - parameter. + parameter (encapsulated into apostrophes) or NONE (not encapsulated into apostrophes) + for specifying no value for parameters allowing a list of values.
Possible Answers:
@@ -3340,7 +3371,19 @@
+C: "SET MIDI_INPUT_PORT_PARAMETER 0 0 ALSA_SEQ_BINDINGS='20:0'" +
+S: "OK" +
+
+ +
+
++C: "SET MIDI_INPUT_PORT_PARAMETER 0 0 ALSA_SEQ_BINDINGS=NONE" +
+S: "OK"
@@ -3375,6 +3418,12 @@ number of the sampler channel the instrument should be assigned to. Each sampler channel can only have one instrument.
+Notice: since LSCP 1.2 the <filename> argument supports + escape characters for special characters (see chapter + "Character Set and Escape Sequences (Character Set and Escape Sequences)" + for details) and accordingly backslash characters in the filename + MUST now be escaped as well! +
The difference between regular and NON_MODAL versions of the command is that the regular command returns OK only after the instrument has been fully loaded and the channel is ready to be used while NON_MODAL version @@ -3422,12 +3471,26 @@
-
Example: +
Example (Unix):
+C: LOAD INSTRUMENT '/home/joe/gigs/cello.gig' 0 0 +
+S: OK +
+
+ +
+Example (Windows): +
+
++C: LOAD INSTRUMENT 'D:/MySounds/cello.gig' 0 0 +
+S: OK
@@ -3842,6 +3905,8 @@
@@ -3961,7 +4026,8 @@arbitrary description text about the engine + (note that the character string may contain + escape sequences (Character Set and Escape Sequences))
@@ -3978,6 +4044,8 @@the file name of the loaded instrument, "NONE" if there's no instrument yet loaded for this sampler - channel + channel (note: since LSCP 1.2 this path may contain + escape sequences (Character Set and Escape Sequences))
@@ -5053,7 +5121,9 @@ sampler channel on which the effect send should be created on, <midi-ctrl> is a number between 0..127 defining the MIDI controller which can alter the effect send level and <name> is an optional argument defining a name - for the effect send entity. The name does not have to be unique. + for the effect send entity. The name does not have to be unique, but MUST be + encapsulated into apostrophes and supports escape sequences as described in chapter + "Character Set and Escape Sequences (Character Set and Escape Sequences)".the instrument name of the loaded instrument + (note: since LSCP 1.2 this character string may contain + escape sequences (Character Set and Escape Sequences))
By default, that is as initial routing, the effect send's audio channels are automatically routed to the last audio channels of the sampler channel's @@ -5322,6 +5392,8 @@
@@ -5412,7 +5484,10 @@ 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. + does not have to be unique (name MUST be encapsulated into apostrophes + and supports escape sequences as described in chapter + "Character Set and Escape Sequences (Character Set and Escape Sequences)"). +name of the effect send entity + (note that this character string may contain + escape sequences (Character Set and Escape Sequences))
Possible Answers:
@@ -5676,9 +5751,96 @@-
| TOC |
The front-end can send MIDI events to specific sampler channel + by sending the following command: +
++
++SEND CHANNEL MIDI_DATA <midi-msg> <sampler-chan> <arg1> <arg2> +
+
+ +
+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, + <arg1> and <arg2> arguments depend on the <midi-msg> argument, which + specifies the MIDI message type. Currently, the following MIDI messages are supported: +
++
++"NOTE_ON" - +
+++ + +For turning on MIDI notes, where <arg1> + specifies the key number and <arg2> the velocity + as described in the MIDI specification. +
+"NOTE_OFF" - +
+++ + +For turning a currently playing MIDI note off, where <arg1> + specifies the key number and <arg2> the velocity + as described in the MIDI specification. +
+
+ +
+CAUTION: This command is provided for implementations of virtual MIDI keyboards + and no realtime guarantee whatsoever will be made! +
+Possible Answers: +
++
++"OK" - +
+++ + +on success +
+"ERR:<error-code>:<error-message>" - +
+++ + +in case it failed, providing an appropriate error code and error message +
+
+ +
+Example: +
++
++C: "SEND CHANNEL MIDI_DATA NOTE_ON 0 56 112" +
+S: "OK" +
+
+ +
+| TOC |
The front-end can reset a particular sampler channel by sending the following command: @@ -6013,9 +6175,36 @@
-
| TOC |
The front-end can ask for the current number of active disk streams on + the sampler by sending the following command: +
++
++GET TOTAL_STREAM_COUNT +
+
+ +
+Possible Answers: +
++
++LinuxSampler will answer by returning the number of all active + disk streams on the sampler. +
+
+ +
+| TOC |
The front-end can reset the whole sampler by sending the following command: @@ -6056,7 +6245,7 @@
| TOC |
The client can ask for general informations about the LinuxSampler @@ -6089,6 +6278,8 @@
@@ -6130,7 +6321,7 @@arbitrary textual description about the sampler + (note that the character string may contain + escape sequences (Character Set and Escape Sequences))
| TOC |
The client can ask for the current global sampler-wide volume @@ -6163,7 +6354,7 @@
| TOC |
The client can alter the current global sampler-wide volume @@ -6250,7 +6441,7 @@ cause the sampler to switch to the respective instrument as reflected by the current MIDI instrument map.
-| TOC |
Where <name> is an optional argument allowing to assign a custom name to the new map. MIDI instrument Map - names do not have to be unique. + names do not have to be unique, but MUST be encapsulated + into apostrophes and support escape sequences as described + in chapter "Character Set and Escape Sequences (Character Set and Escape Sequences)". +
Possible Answers:
@@ -6526,6 +6720,8 @@@@ -6581,7 +6777,10 @@custom name of the given map, which does not have to be unique + (note that this character string may contain + escape sequences (Character Set and Escape Sequences))
Where <map> is the numerical ID of the map and <name> the new custom name of the map, which does not - have to be unique. + have to be unique (name MUST be encapsulated into apostrophes + and supports escape sequences as described in chapter + "Character Set and Escape Sequences (Character Set and Escape Sequences)"). +
Possible Answers:
@@ -6647,7 +6846,9 @@ 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), + of the instrument's file to be deployed (encapsulated into apostrophes, + supporting escape sequences as described in chapter + "Character Set and Escape Sequences (Character Set and Escape Sequences)"), <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 @@ -6744,9 +6945,10 @@ 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 + command(s). Finally the OPTIONAL <name> argument allows to set a custom name + (encapsulated into apostrophes, supporting escape sequences as described in chapter + "Character Set and Escape Sequences (Character Set and Escape Sequences)") 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)). @@ -7068,6 +7270,8 @@ changed with the "MAP MIDI_INSTRUMENT" (Create or replace a MIDI instrument map entry) command and does not have to be unique. + (note that this character string may contain + escape sequences (Character Set and Escape Sequences)) @@ -7084,7 +7288,9 @@"INSTRUMENT_FILE" -
-@@ -7102,7 +7308,8 @@File name of the instrument. +
File name of the instrument + (note that this path may contain + escape sequences (Character Set and Escape Sequences)).
@@ -7237,6 +7444,23 @@Name of the loaded instrument as reflected by its file. In contrast to the "NAME" field, the "INSTRUMENT_NAME" field - cannot be changed. + cannot be changed (note that this character string may contain + escape sequences (Character Set and Escape Sequences)).
The following commands describe how to use and manage the instruments database.
+Notice: +
++
++All command arguments representing a path or + instrument/directory name support escape sequences as described in chapter + "Character Set and Escape Sequences (Character Set and Escape Sequences)". + +
+All occurrences of a forward slash in instrument and directory + names are escaped with its hex (\x2f) or octal (\057) escape sequence. + +
+
+ +
| TOC |
DESCRIPTION -
-@@ -7747,7 +7973,9 @@A brief description of the directory content +
A brief description of the directory content. + Note that the character string may contain + escape sequences (Character Set and Escape Sequences).
Where <dir> is the absolute path name of the directory and - <desc> is the new description for the directory. + <desc> is the new description for the directory + (encapsulated into apostrophes, supporting escape sequences as described in chapter + "Character Set and Escape Sequences (Character Set and Escape Sequences)").
Possible Answers:
@@ -7814,7 +8042,9 @@Restricts the search to directories, which names - satisfy the supplied search string. + satisfy the supplied search string (encapsulated into apostrophes, + supporting escape sequences as described in chapter + "Character Set and Escape Sequences (Character Set and Escape Sequences)").
@@ -7857,7 +8087,10 @@
Restricts the search to directories with description - that satisfies the supplied search string. + that satisfies the supplied search string + (encapsulated into apostrophes, supporting escape + sequences as described in chapter + "Character Set and Escape Sequences (Character Set and Escape Sequences)").
@@ -8238,6 +8471,8 @@
@@ -8297,7 +8532,9 @@File name of the instrument. + Note that the character string may contain + escape sequences (Character Set and Escape Sequences).
DESCRIPTION -
-@@ -8314,7 +8551,9 @@A brief description of the instrument +
A brief description of the instrument. + Note that the character string may contain + escape sequences (Character Set and Escape Sequences).
PRODUCT -
-@@ -8322,7 +8561,9 @@The product title of the instrument +
The product title of the instrument. + Note that the character string may contain + escape sequences (Character Set and Escape Sequences).
ARTISTS -
-@@ -8332,6 +8573,8 @@Lists the artist names +
Lists the artist names. + Note that the character string may contain + escape sequences (Character Set and Escape Sequences).
@@ -8572,7 +8815,9 @@Provides a list of keywords that refer to the instrument. Keywords are separated with semicolon and blank. + Note that the character string may contain + escape sequences (Character Set and Escape Sequences).
Where <instr> is the absolute path name of the instrument and - <desc> is the new description for the instrument. + <desc> is the new description for the instrument + (encapsulated into apostrophes, supporting escape sequences as described in chapter + "Character Set and Escape Sequences (Character Set and Escape Sequences)").
Possible Answers:
@@ -8639,7 +8884,9 @@Restricts the search to instruments, which names - satisfy the supplied search string. + satisfy the supplied search string (encapsulated into apostrophes, + supporting escape sequences as described in chapter + "Character Set and Escape Sequences (Character Set and Escape Sequences)").
@@ -8649,7 +8896,7 @@
SIZE=[<min>]..[<max>]
-Restricts the search to instruments, which +
Restricts the search to instruments, which size is in the specified range. If <min> is omitted, the search results are restricted to instruments with size less then or equal to <max>. If <max> is omitted, the @@ -8697,7 +8944,9 @@
Restricts the search to instruments with description - that satisfies the supplied search string. + that satisfies the supplied search string (encapsulated into apostrophes, + supporting escape sequences as described in chapter + "Character Set and Escape Sequences (Character Set and Escape Sequences)").
@@ -8708,7 +8957,9 @@
Restricts the search to instruments with product info - that satisfies the supplied search string. + that satisfies the supplied search string (encapsulated into apostrophes, + supporting escape sequences as described in chapter + "Character Set and Escape Sequences (Character Set and Escape Sequences)").
@@ -8719,7 +8970,9 @@
Restricts the search to instruments with artists info - that satisfies the supplied search string. + that satisfies the supplied search string (encapsulated into apostrophes, + supporting escape sequences as described in chapter + "Character Set and Escape Sequences (Character Set and Escape Sequences)").
@@ -8730,7 +8983,9 @@
Restricts the search to instruments with keyword list - that satisfies the supplied search string. + that satisfies the supplied search string (encapsulated into apostrophes, + supporting escape sequences as described in chapter + "Character Set and Escape Sequences (Character Set and Escape Sequences)").
@@ -8740,7 +8995,7 @@
IS_DRUM=true | false
-Either true or false. Restricts the search to +
Either true or false. Restricts the search to drum kits or chromatic instruments.
@@ -8900,6 +9155,523 @@
+
| TOC |
The front-end can remove all instruments and directories and re-create + the instruments database structure (e.g., in case of a database corruption) + by sending the following command: +
++
++FORMAT INSTRUMENTS_DB +
+
+ +
+Possible Answers: +
++
++"OK" - +
+++ + +on success +
+"ERR:<error-code>:<error-message>" - +
+++ + +If the formatting of the instruments database + failed. +
+
+ +
+| TOC |
The front-end can retrieve the list of all instrument files in the instruments database + that don't exist in the filesystem by sending the following command: +
++
++FIND LOST DB_INSTRUMENT_FILES +
+
+ +
+Possible Answers: +
++
++A comma separated list with the absolute path names + (encapsulated into apostrophes) of all lost instrument files. +
+"ERR:<error-code>:<error-message>" - +
+++ + +in case it failed, providing an appropriate error code and error message. +
+
+ +
+Example: +
++
++C: "FIND LOST DB_INSTRUMENT_FILES" +
+S: "'/gigs/Bosendorfer 290.gig','/gigs/Steinway D.gig','/gigs/Free Piano.gig'" +
+
+ +
+| TOC |
The front-end can substitute all occurrences of an instrument file + in the instruments database with a new one by sending the following command: +
++
++SET DB_INSTRUMENT FILE_PATH <old_path> <new_path> +
+
+ +
+Where <old_path> is the absolute path name of the instrument file + to substitute with <new_path>. +
+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 DB_INSTRUMENT FILE_PATH '/gigs/Bosendorfer 290.gig' '/gigs/pianos/Bosendorfer 290.gig'" +
+S: "OK" +
+
+ +
+| TOC |
The sampler allows to edit instruments while playing with the + sampler by spawning an external (3rd party) instrument editor + application for a given instrument. The 3rd party instrument + editor applications have to place a respective plugin DLL file + into the sampler's plugins directory. The sampler will + automatically try to load all plugin DLLs in that directory on + startup and only on startup! +
+At the moment there is only one command for this feature set, + but this will most probably change in future. +
+| TOC |
The front-end can request to open an appropriate instrument + editor application by sending the following command: +
++
++EDIT CHANNEL INSTRUMENT <sampler-channel> +
+
+ +
+Where <sampler-channel> should be replaced by the + number of the sampler channel as given by the + "ADD CHANNEL" (Adding a new sampler channel) + or "LIST CHANNELS" (Getting all created sampler channel list) + command. +
+The sampler will try to ask all registered instrument + editors (or to be more specific: their sampler plugins) + whether they are capable to handle the instrument on the + given sampler channel. The sampler will simply use the first + instrument editor application which replied with a positive + answer and spawn that instrument editor application within + the sampler's process and provide that application access + to the instrument's data structures, so both applications + can share and access the same instruments data at the same + time, thus allowing to immediately hear changes with the + sampler made by the instrument editor. +
+Note: consequently instrument editors are always spawned + locally on the same machine where the sampler is running + on! +
+Possible Answers: +
++
++"OK" - +
+++ + +when an appropriate instrument editor was + launched +
+"WRN:<warning-code>:<warning-message>" - +
+++ + +when an appropriate instrument editor was + launched, but there are noteworthy issues +
+"ERR:<error-code>:<error-message>" - +
+++ + +when an appropriate instrument editor + could not be launched +
+
+ +
+Examples: +
++
++C: "EDIT CHANNEL INSTRUMENT 0" +
+S: "OK" +
+
+ +
+| TOC |
You can query detailed informations about files located + at the same system where the sampler instance is running on. + Using this command set allows to retrieve file informations + even remotely from another machine. +
+| TOC |
The front-end can retrieve the amount of instruments + within a given instrument file by sending the + following command: +
++
++GET FILE INSTRUMENTS <filename> +
+
+ +
+Where <filename> is the name of the instrument + file (encapsulated into apostrophes, supporting escape + sequences as described in chapter + "Character Set and Escape + Sequences (Character Set and Escape Sequences)"). +
+The sampler will try to ask all sampler engines, + whether they support the given file and ask the first + engine with a positive answer for the amount of + instruments. +
+Possible Answers: +
++
++On success, the sampler will answer by + returning the amount of instruments. + +
+"ERR:<error-code>:<error-message>" - +
+++ + +if the file could not be handled +
+
+ +
+Examples: +
++
++C: "GET FILE INSTRUMENTS 'D:/Sounds/Foo.gig'" +
+S: "10" +
+
+ +
+| TOC |
The front-end can retrieve a list of all instruments + within a given instrument file by sending the + following command: +
++
++LIST FILE INSTRUMENTS <filename> +
+
+ +
+Where <filename> is the name of the instrument + file (encapsulated into apostrophes, supporting escape + sequences as described in chapter + "Character Set and Escape + Sequences (Character Set and Escape Sequences)"). +
+The sampler will try to ask all sampler engines, + whether they support the given file and ask the first + engine with a positive answer for a list of IDs for the + instruments in the given file. +
+Possible Answers: +
++
++On success, the sampler will answer by + returning a comma separated list of + instrument IDs. + +
+"ERR:<error-code>:<error-message>" - +
+++ + +if the file could not be handled +
+
+ +
+Examples: +
++
++C: "LIST FILE INSTRUMENTS 'D:/Sounds/Foo.gig'" +
+S: "0,1,2,3,4,5,6,7,8,9" +
+
+ +
+| TOC |
The front-end can retrieve detailed informations + about a specific instrument within a given instrument + file by sending the following command: +
++
++GET FILE INSTRUMENT INFO <filename> + <instr-id> +
+
+ +
+Where <filename> is the name of the instrument + file (encapsulated into apostrophes, supporting escape + sequences as described in chapter + "Character Set and Escape + Sequences (Character Set and Escape Sequences)") and <instr-id> is the numeric + instrument ID as returned by the + "LIST FILE INSTRUMENTS" (Retrieving all instruments of a file) command. +
+The sampler will try to ask all sampler engines, + whether they support the given file and ask the first + engine with a positive answer for informations about the + specific instrument in the given file. +
+Possible Answers: +
++
++LinuxSampler will answer by sending a <CRLF> separated list. + Each answer line begins with the settings category name + followed by a colon and then a space character <SP> and finally + the info character string to that setting category. At the + moment the following categories are defined: +
++
+++ + +NAME - +
+++ + +name of the instrument as + stored in the instrument file +
+FORMAT_FAMILY - +
+++ + +name of the sampler format + of the given instrument +
+FORMAT_VERSION - +
+++ + +version of the sampler format + the instrumen is stored as +
+PRODUCT - +
+++ + +official product name of the + instrument as stored in the file + +
+ARTISTS - +
+++ + +artists / sample library + vendor of the instrument +
+KEY_BINDINGS - +
+++ + +comma separated list of integer values representing + the instrument's key mapping in the range between 0 .. 127, + reflecting the analog meaning of the MIDI specification. +
+KEYSWITCH_BINDINGS - +
+++ + +comma separated list of integer values representing + the instrument's keyswitch mapping in the range between 0 .. 127, + reflecting the analog meaning of the MIDI specification. +
+
+ +
+The mentioned fields above don't have to be in particular order. +
+Example: +
++
++C: "GET FILE INSTRUMENT INFO 'D:/Sounds/Foo.gig' 0" +
+S: "NAME: Lunatic Loops" +
+"FORMAT_FAMILY: GIG" +
+"FORMAT_VERSION: 3" +
+"PRODUCT: The Backbone Bongo Beats" +
+"ARTISTS: Jimmy the Fish" +
+"." +
+
+ +
| TOC |
/ COPY SP copy_instruction
+/ EDIT SP edit_instruction + +
+/ FORMAT SP format_instruction + +
+SEND SP send_instruction + +
/ RESET
@@ -9030,25 +9811,25 @@CHANNEL
-/ DB_INSTRUMENT_DIRECTORY SP pathname +
/ DB_INSTRUMENT_DIRECTORY SP db_path
-/ DB_INSTRUMENTS SP NON_MODAL SP scan_mode SP pathname SP pathname +
/ DB_INSTRUMENTS SP NON_MODAL SP scan_mode SP db_path SP filename
-/ DB_INSTRUMENTS SP scan_mode SP pathname SP pathname +
/ DB_INSTRUMENTS SP scan_mode SP db_path SP filename
-/ DB_INSTRUMENTS SP NON_MODAL SP pathname SP pathname +
/ DB_INSTRUMENTS SP NON_MODAL SP db_path SP filename
-/ DB_INSTRUMENTS SP NON_MODAL SP pathname SP pathname SP instrument_index +
/ DB_INSTRUMENTS SP NON_MODAL SP db_path SP filename SP instrument_index
-/ DB_INSTRUMENTS SP pathname SP pathname +
/ DB_INSTRUMENTS SP db_path SP filename
-/ DB_INSTRUMENTS SP pathname SP pathname SP instrument_index +
/ DB_INSTRUMENTS SP db_path SP filename SP instrument_index
/ MIDI_INSTRUMENT_MAP @@ -9078,6 +9859,12 @@
/ CHANNEL_COUNT
+/ CHANNEL_MIDI + +
+/ DEVICE_MIDI + +
/ VOICE_COUNT
@@ -9126,6 +9913,9 @@/ MISCELLANEOUS
+/ TOTAL_STREAM_COUNT + +
/ TOTAL_VOICE_COUNT
@@ -9153,6 +9943,12 @@/ CHANNEL_COUNT
+/ CHANNEL_MIDI + +
+/ DEVICE_MIDI + +
/ VOICE_COUNT
@@ -9201,6 +9997,9 @@/ MISCELLANEOUS
+/ TOTAL_STREAM_COUNT + +
/ TOTAL_VOICE_COUNT
@@ -9249,13 +10048,13 @@/ MIDI_INSTRUMENT_MAP SP ALL
-/ DB_INSTRUMENT_DIRECTORY SP FORCE SP pathname +
/ DB_INSTRUMENT_DIRECTORY SP FORCE SP db_path
-/ DB_INSTRUMENT_DIRECTORY SP pathname +
/ DB_INSTRUMENT_DIRECTORY SP db_path
-/ DB_INSTRUMENT SP pathname +
/ DB_INSTRUMENT SP db_path
@@ -9336,6 +10135,9 @@
/ SERVER SP INFO
+/ TOTAL_STREAM_COUNT + +
/ TOTAL_VOICE_COUNT
@@ -9363,22 +10165,22 @@/ FX_SEND SP INFO SP sampler_channel SP fx_send_id
-/ DB_INSTRUMENT_DIRECTORIES SP RECURSIVE SP pathname +
/ DB_INSTRUMENT_DIRECTORIES SP RECURSIVE SP db_path
-/ DB_INSTRUMENT_DIRECTORIES SP pathname +
/ DB_INSTRUMENT_DIRECTORIES SP db_path
-/ DB_INSTRUMENT_DIRECTORY SP INFO SP pathname +
/ DB_INSTRUMENT_DIRECTORY SP INFO SP db_path
-/ DB_INSTRUMENTS SP RECURSIVE SP pathname +
/ DB_INSTRUMENTS SP RECURSIVE SP db_path
-/ DB_INSTRUMENTS SP pathname +
/ DB_INSTRUMENTS SP db_path
-/ DB_INSTRUMENT SP INFO SP pathname +
/ DB_INSTRUMENT SP INFO SP db_path
/ DB_INSTRUMENTS_JOB SP INFO SP number @@ -9387,6 +10189,12 @@
/ VOLUME
+/ FILE SP INSTRUMENTS SP filename + +
+/ FILE SP INSTRUMENT SP INFO SP filename SP instrument_index + +
@@ -9402,6 +10210,9 @@
/ MIDI_INPUT_DEVICE_PARAMETER SP number SP string '=' param_val_list
+/ MIDI_INPUT_PORT_PARAMETER SP number SP number SP string '=' NONE + +
/ MIDI_INPUT_PORT_PARAMETER SP number SP number SP string '=' param_val_list
@@ -9423,16 +10234,19 @@/ FX_SEND SP LEVEL SP sampler_channel SP fx_send_id SP volume_value
-/ DB_INSTRUMENT_DIRECTORY SP NAME SP pathname SP dirname +
/ DB_INSTRUMENT_DIRECTORY SP NAME SP db_path SP stringval_escaped + +
+/ DB_INSTRUMENT_DIRECTORY SP DESCRIPTION SP db_path SP stringval_escaped
-/ DB_INSTRUMENT_DIRECTORY SP DESCRIPTION SP pathname SP stringval +
/ DB_INSTRUMENT SP NAME SP db_path SP stringval_escaped
-/ DB_INSTRUMENT SP NAME SP pathname SP dirname +
/ DB_INSTRUMENT SP DESCRIPTION SP db_path SP stringval_escaped
-/ DB_INSTRUMENT SP DESCRIPTION SP pathname SP stringval +
/ DB_INSTRUMENT SP FILE_PATH SP filename SP filename
/ ECHO SP boolean @@ -9492,16 +10306,19 @@
find_instruction =
-DB_INSTRUMENTS SP NON_RECURSIVE SP pathname SP query_val_list +
DB_INSTRUMENTS SP NON_RECURSIVE SP db_path SP query_val_list + +
+/ DB_INSTRUMENTS SP db_path SP query_val_list
-/ DB_INSTRUMENTS SP pathname SP query_val_list +
/ DB_INSTRUMENT_DIRECTORIES SP NON_RECURSIVE SP db_path SP query_val_list
-/ DB_INSTRUMENT_DIRECTORIES SP NON_RECURSIVE SP pathname SP query_val_list +
/ DB_INSTRUMENT_DIRECTORIES SP db_path SP query_val_list
-/ DB_INSTRUMENT_DIRECTORIES SP pathname SP query_val_list +
/ LOST SP DB_INSTRUMENT_FILES
@@ -9510,10 +10327,10 @@
move_instruction =
-DB_INSTRUMENT_DIRECTORY SP pathname SP pathname +
DB_INSTRUMENT_DIRECTORY SP db_path SP db_path
-/ DB_INSTRUMENT SP pathname SP pathname +
/ DB_INSTRUMENT SP db_path SP db_path
@@ -9522,10 +10339,10 @@
copy_instruction =
-DB_INSTRUMENT_DIRECTORY SP pathname SP pathname +
DB_INSTRUMENT_DIRECTORY SP db_path SP db_path
-/ DB_INSTRUMENT SP pathname SP pathname +
/ DB_INSTRUMENT SP db_path SP db_path
@@ -9606,6 +10423,24 @@
+
edit_instruction = +
++CHANNEL SP INSTRUMENT SP sampler_channel + +
+
+ +
+format_instruction = +
++INSTRUMENTS_DB + +
+
+ +
modal_arg =
@@ -9675,16 +10510,28 @@/ FX_SENDS SP sampler_channel
-/ DB_INSTRUMENT_DIRECTORIES SP RECURSIVE SP pathname +
/ DB_INSTRUMENT_DIRECTORIES SP RECURSIVE SP db_path + +
+/ DB_INSTRUMENT_DIRECTORIES SP db_path
-/ DB_INSTRUMENT_DIRECTORIES SP pathname +
/ DB_INSTRUMENTS SP RECURSIVE SP db_path
-/ DB_INSTRUMENTS SP RECURSIVE SP pathname +
/ DB_INSTRUMENTS SP db_path
-/ DB_INSTRUMENTS SP pathname +
/ FILE SP INSTRUMENTS SP filename + +
+
+ +
+send_instruction = +
++CHANNEL SP MIDI_DATA SP string SP sampler_channel SP number SP number
@@ -9867,28 +10714,19 @@
-
pathname = -
--stringval - -
-
- -
-dirname = +
filename =
-stringval +
path
-
filename = +
db_path =
-stringval +
path
@@ -9897,7 +10735,7 @@
map_name =
-stringval +
stringval_escaped
@@ -9906,7 +10744,7 @@
entry_name =
-stringval +
stringval_escaped
@@ -9915,7 +10753,7 @@
fx_send_name =
-stringval +
stringval_escaped
@@ -9966,10 +10804,10 @@
query_val =
-string +
text_escaped
-/ stringval +
/ stringval_escaped
@@ -9990,6 +10828,205 @@
+
| TOC |
Older versions of this protocol up to and including v1.1 only + supported the standard ASCII character set (ASCII code 0 - 127) + [RFC20] (UCLA, “ASCII format for Network Interchange,” 1969.), all younger versions of this protocol + however support the Extended ASCII character set (ASCII code + 0 - 255). The same group of younger protocols also support + escape sequences, but only for certain, explicitly declared + parts of the protocol. The supported escape sequences are + defined as follows: +
| ASCII Character Sequence | Translated into (Name) |
|---|---|
| \n | +new line | +
| \r | +carriage return | +
| \f | +form feed | +
| \t | +horizontal tab | +
| \v | +vertical tab | +
| \' | +apostrophe | +
| \" | +quotation mark | +
| \\ | +backslash | +
| \OOO | +three digit octal ASCII code of the character | +
| \xHH | +two digit hex ASCII code of the character | +
Notice: due to the transition of certain parts of the + protocol which now support escape sequences, a slight backward + incompatibility to protocols version v1.1 and younger has been + introduced. The only difference is that in parts of the protocol + where escape characters are now supported, a backslash characters + MUST be escaped as well (that is as double backslash), whereas + in the old versions a single backslash was sufficient. +
+The following LSCP commands support escape sequences as part + of their filename / path based arguments and / or may contain + a filename / path with escape sequences in their response: +
++"LOAD INSTRUMENT" (Loading an instrument) +
+"GET CHANNEL INFO" (Getting sampler channel information) +
+"MAP MIDI_INSTRUMENT" (Create or replace a MIDI instrument map entry) +
+"GET MIDI_INSTRUMENT INFO" (Get current settings of MIDI instrument map entry) +
+"ADD DB_INSTRUMENT_DIRECTORY" (Creating a new instrument directory) +
+"ADD DB_INSTRUMENTS" (Adding instruments to the instruments database) +
+"REMOVE DB_INSTRUMENT_DIRECTORY" (Deleting an instrument directory) +
+"REMOVE DB_INSTRUMENT" (Removing an instrument) +
+"GET DB_INSTRUMENT_DIRECTORIES" (Getting amount of instrument directories) +
+"LIST DB_INSTRUMENT_DIRECTORIES" (Listing all directories in specific directory) +
+"GET DB_INSTRUMENT_DIRECTORY INFO" (Getting instrument directory information) +
+"GET DB_INSTRUMENTS" (Getting amount of instruments) +
+"LIST DB_INSTRUMENTS" (Listing all instruments in specific directory) +
+"GET DB_INSTRUMENT INFO" (Getting instrument information) +
+"SET DB_INSTRUMENT_DIRECTORY NAME" (Renaming an instrument directory) +
+"SET DB_INSTRUMENT_DIRECTORY DESCRIPTION" (Changing the description of directory) +
+"SET DB_INSTRUMENT NAME" (Renaming an instrument) +
+"SET DB_INSTRUMENT DESCRIPTION" (Changing the description of instrument) +
+"FIND DB_INSTRUMENTS" (Finding instruments) +
+"FIND DB_INSTRUMENT_DIRECTORIES" (Finding directories) +
+"MOVE DB_INSTRUMENT" (Moving an instrument) +
+"MOVE DB_INSTRUMENT_DIRECTORY" (Moving an instrument directory) +
+"COPY DB_INSTRUMENT" (Copying instruments) +
+"COPY DB_INSTRUMENT_DIRECTORY" (Copying instrument directories) +
+"FIND LOST DB_INSTRUMENT_FILES" (Checking for lost instrument files) +
+"SET DB_INSTRUMENT FILE_PATH" (Replacing an instrument file) +
+"GET FILE INSTRUMENTS" (Retrieving amount of instruments of a file) +
+"LIST FILE INSTRUMENTS" (Retrieving all instruments of a file) +
+"GET FILE INSTRUMENT INFO" (Retrieving informations about one instrument in a file) +
+
+ Note that the forward slash character ('/') has a special meaning in + filename / path based arguments: it acts as separator of the nodes in + the path, thus if a directory- or filename includes a forward slash + (not intended as path node separator), you MUST escape that slash + either with the respective hex escape sequence ("\x2f") or with the + respective octal escape sequence ("\057"). + +
++ Note for Windows: file path arguments in LSCP are expected + to use forward slashes as directory node separator similar + to Unix based operating systems. In contrast to Unix however + a Windows typical drive character is expected to be + prefixed to the path. That is an original Windows file path + like "D:\Sounds\My.gig" would become in LSCP: + "D:/Sounds/My.gig". + +
++ The following LSCP commands even support escape sequences as + part of at least one of their text-based arguments (i.e. entity name, + description) and / or may contain escape sequences in at least one of + their text-based fields in their response: +
++"GET SERVER INFO" (General sampler informations) +
+"GET ENGINE INFO" (Getting information about an engine) +
+"GET CHANNEL INFO" (Getting sampler channel information) +
+"CREATE FX_SEND" (Adding an effect send to a sampler channel) +
+"GET FX_SEND INFO" (Getting effect send information) +
+"SET FX_SEND NAME" (Changing effect send's name) +
+"GET MIDI_INSTRUMENT INFO" (Get current settings of MIDI instrument map entry) +
+"GET MIDI_INSTRUMENT_MAP INFO" (Getting MIDI instrument map information) +
+"ADD MIDI_INSTRUMENT_MAP" (Create a new MIDI instrument map) +
+"MAP MIDI_INSTRUMENT" (Create or replace a MIDI instrument map entry) +
+"SET MIDI_INSTRUMENT_MAP NAME" (Renaming a MIDI instrument map) +
+"GET DB_INSTRUMENT_DIRECTORY INFO" (Getting instrument directory information) +
+"SET DB_INSTRUMENT_DIRECTORY NAME" (Renaming an instrument directory) +
+"SET DB_INSTRUMENT_DIRECTORY DESCRIPTION" (Changing the description of directory) +
+"FIND DB_INSTRUMENT_DIRECTORIES" (Finding directories) +
+"GET DB_INSTRUMENT INFO" (Getting instrument information) +
+"SET DB_INSTRUMENT NAME" (Renaming an instrument) +
+"SET DB_INSTRUMENT DESCRIPTION" (Changing the description of instrument) +
+ +
+ Please note that these lists are manually maintained. If you + find a command that also supports escape sequences we forgot to + mention here, please report it! + +
| TOC |
where <channels> will be replaced by the new number of sampler channels.
-| TOC |
Client may want to be notified when MIDI data arrive on sampler channels on + back-end side, by issuing the following command: +
++
++SUBSCRIBE CHANNEL_MIDI +
+
+ +
+Server will start sending one of the the following notification messages: +
++
++"NOTIFY:CHANNEL_MIDI:<channel-id> NOTE_ON <note> <velocity>" +
+"NOTIFY:CHANNEL_MIDI:<channel-id> NOTE_OFF <note> <velocity>" +
+
+ +
+where <channel-id> will be replaced by the ID of the sampler channel where the MIDI + data arrived. <note> and <velocity> are integer values in the range between + 0 .. 127, reflecting the analog meaning of the MIDI specification. + +
+CAUTION: no guarantee whatsoever will be made that MIDI events are actually all + delivered by this mechanism! With other words: events could be lost at any time! + This restriction was made to keep the RT-safeness of the backend's MIDI and audio + thread unaffected by this feature. +
+| TOC |
Client may want to be notified when MIDI data arrive on MIDI input devices by issuing the following command: +
++
++SUBSCRIBE DEVICE_MIDI +
+
+ +
+Server will start sending one of the the following notification messages: +
++
++"NOTIFY:DEVICE_MIDI:<device-id> <port-id> NOTE_ON <note> <velocity>" +
+"NOTIFY:DEVICE_MIDI:<device-id> <port-id> NOTE_OFF <note> <velocity>" +
+
+ +
+where <device-id> <port-id> will be replaced + by the IDs of the respective MIDI input device and the device's MIDI port where the MIDI + data arrived. <note> and <velocity> are integer values in the range between + 0 .. 127, reflecting the analog meaning of the MIDI specification. + +
+CAUTION: no guarantee whatsoever will be made that MIDI events are actually all + delivered by this mechanism! With other words: events could be lost at any time! + This restriction was made to keep the RT-safeness of the backend's MIDI and audio + thread unaffected by this feature. +
+| TOC |
Client may want to be notified when the number of voices on the @@ -10182,7 +11295,7 @@
| TOC |
Client may want to be notified when the number of streams on the back-end @@ -10212,7 +11325,7 @@
| TOC |
Client may want to be notified when the buffer fill state of a disk stream @@ -10243,7 +11356,7 @@
| TOC |
Client may want to be notified when changes were made to sampler channels on the @@ -10276,10 +11389,10 @@
| TOC |
Client may want to be notified when the number of effect sends on +
Client may want to be notified when the number of effect sends on a particular sampler channel is changed by issuing the following command:
@@ -10306,7 +11419,7 @@
| TOC |
Client may want to be notified when changes were made to effect sends on a @@ -10336,7 +11449,7 @@
| TOC |
Client may want to be notified when the total number of voices on the @@ -10363,9 +11476,38 @@
where <voices> will be replaced by the new number of all currently active voices.
+| TOC |
Client may want to be notified when the total number of disk streams on the + back-end changes by issuing the following command: +
++
++SUBSCRIBE TOTAL_STREAM_COUNT +
+
+ +
+Server will start sending the following notification messages: +
++
++"NOTIFY:TOTAL_STREAM_COUNT:<streams>" +
+
+ +
+where <streams> will be replaced by the new number of + all currently active disk streams. +
| TOC |
Client may want to be notified when the number of MIDI instrument maps on the @@ -10394,7 +11536,7 @@
| TOC |
Client may want to be notified when changes were made to MIDI instrument maps on the @@ -10427,7 +11569,7 @@
| TOC |
Client may want to be notified when the number of MIDI instrument maps on the @@ -10457,7 +11599,7 @@
| TOC |
Client may want to be notified when changes were made to MIDI instruments on the @@ -10491,7 +11633,7 @@
| TOC |
Client may want to be notified when changes to the global settings @@ -10520,7 +11662,7 @@
| TOC |
Client may want to be notified when the number of instrument @@ -10554,7 +11696,7 @@
| TOC |
Client may want to be notified when changes were made to directories @@ -10599,7 +11741,7 @@
| TOC |
Client may want to be notified when the number of instruments @@ -10633,7 +11775,7 @@
| TOC |
Client may want to be notified when changes were made to instruments @@ -10678,7 +11820,7 @@
| TOC |
Client may want to be notified when the status of particular database @@ -10711,7 +11853,7 @@
| TOC |
Client may want to be notified of miscellaneous and debugging events occurring at @@ -10776,6 +11918,8 @@
| TOC |
| [RFC20] | +UCLA, “ASCII format for Network Interchange,” RFC 20, 1969. |
| [RFC2119] | Bradner, S., “Key words for use in RFCs to Indicate Requirement Levels,” RFC 2119, 1997. |
| [RFC2234] | @@ -10806,7 +11950,7 @@
| TOC |
-Copyright © The IETF Trust (2007).
+Copyright © The IETF Trust (2008).This document is subject to the rights, licenses and restrictions contained in BCP 78,