--- web/trunk/www.linuxsampler.org/api/draft-linuxsampler-protocol.html 2006/12/15 21:46:48 974 +++ web/trunk/www.linuxsampler.org/api/draft-linuxsampler-protocol.html 2007/10/14 23:39:14 1430 @@ -3,140 +3,140 @@ - +
@@ -145,7 +145,7 @@-This Internet-Draft will expire on June 18, 2007.
+This Internet-Draft will expire on April 17, 2008.-Copyright © The Internet Society (2006).
+Copyright © The IETF Trust (2007).@@ -3201,7 +3307,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:
@@ -3242,7 +3349,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"
@@ -3277,6 +3396,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 @@ -3744,6 +3869,8 @@
@@ -3863,7 +3990,8 @@arbitrary description text about the engine + (note that the character string may contain + escape sequences (Character Set and Escape Sequences))
@@ -3880,6 +4008,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))
@@ -3926,7 +4056,7 @@the instrument name of the loaded instrument + (note: since LSCP 1.2 this character string may contain + escape sequences (Character Set and Escape Sequences))
@@ -4933,9 +5063,661 @@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)
-
TOC |
The front-end can create an additional effect send on a specific sampler channel + by sending the following command: +
++
++CREATE FX_SEND <sampler-channel> <midi-ctrl> [<name>] +
+
+ +
+Where <sampler-channel> is the respective sampler channel + number as returned by the "ADD CHANNEL" (Adding a new sampler channel) + or "LIST CHANNELS" (Getting all created sampler channel list) command, that is the + 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, but MUST be + encapsulated into apostrophes and supports escape sequences as described in chapter + "Character Set and 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 + audio output device, that way you can i.e. first increase the amount of audio + channels on the audio output device for having dedicated effect send output + channels and when "CREATE FX_SEND" is called, those channels will automatically + be picked. You can alter the destination channels however with + "SET FX_SEND AUDIO_OUTPUT_CHANNEL" (Altering effect send's audio routing). + +
+Note: Create effect sends on a sampler channel only when needed, because having effect + sends on a sampler channel will decrease runtime performance, because for implementing channel + effect sends, separate (sampler channel local) audio buffers are needed to render and mix + the voices and route the audio signal afterwards to the master outputs and effect send + outputs (along with their respective effect send levels). A sampler channel without effect + sends however can mix its voices directly into the audio output devices's audio buffers + and is thus faster. + +
+Possible Answers: +
++
++"OK[<fx-send-id>]" - +
+++ + +in case a new effect send could be added to the + sampler channel, where <fx-send-id> reflects the + unique ID of the newly created effect send entity +
+"ERR:<error-code>:<error-message>" - +
+++ + +when a new effect send could not be added, i.e. + due to invalid parameters +
+
+ +
+Examples: +
++
++C: "CREATE FX_SEND 0 91 'Reverb Send'" +
+S: "OK[0]" +
+
+ +
++
++C: "CREATE FX_SEND 0 93" +
+S: "OK[1]" +
+
+ +
+TOC |
The front-end can remove an existing effect send on a specific sampler channel + by sending the following command: +
++
++DESTROY FX_SEND <sampler-channel> <fx-send-id> +
+
+ +
+Where <sampler-channel> is the respective sampler channel + number as returned by the "ADD CHANNEL" (Adding a new sampler channel) + or "LIST CHANNELS" (Getting all created sampler channel list) command, that is the + sampler channel from which the effect send should be removed from and + <fx-send-id> is the respective effect send number 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. +
+Possible Answers: +
++
++"OK" - +
+++ + +on success +
+"ERR:<error-code>:<error-message>" - +
+++ + +in case it failed, providing an appropriate error code and + error message +
+
+ +
+Example: +
++
++C: "DESTROY FX_SEND 0 0" +
+S: "OK" +
+
+ +
+TOC |
The front-end can ask for the amount of effect sends on a specific sampler channel + by sending the following command: +
++
++GET FX_SENDS <sampler-channel> +
+
+ +
+Where <sampler-channel> is the respective sampler channel + number as returned by the "ADD CHANNEL" (Adding a new sampler channel) + or "LIST CHANNELS" (Getting all created sampler channel list) command. +
+Possible Answers: +
++
++The sampler will answer by returning the number of effect + sends on the given sampler channel. +
+
+ +
+Example: +
++
++C: "GET FX_SENDS 0" +
+S: "2" +
+
+ +
+TOC |
The front-end can ask for a list of effect sends on a specific sampler channel + by sending the following command: +
++
++LIST FX_SENDS <sampler-channel> +
+
+ +
+Where <sampler-channel> is the respective sampler channel + number as returned by the "ADD CHANNEL" (Adding a new sampler channel) + or "LIST CHANNELS" (Getting all created sampler channel list) command. +
+Possible Answers: +
++
++The sampler will answer by returning a comma separated list + with all effect sends' numerical IDs on the given sampler + channel. +
+
+ +
+Examples: +
++
++C: "LIST FX_SENDS 0" +
+S: "0,1" +
+
+ +
++
++C: "LIST FX_SENDS 1" +
+S: "" +
+
+ +
+TOC |
The front-end can ask for the current settings of an effect send entity + by sending the following command: +
++
++GET FX_SEND INFO <sampler-channel> <fx-send-id> +
+
+ +
+Where <sampler-channel> 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 and + <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. + +
+Possible Answers: +
++
++The sampler 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 effect send entity + (note that this character string may contain + escape sequences (Character Set and Escape Sequences)) +
+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 - +
+++ + +comma separated list which reflects to which audio + channel of the selected audio output device each + effect send output channel is routed to, e.g. "0,3" would + mean the effect send's output channel 0 is routed to channel + 0 of the audio output device and the effect send's output + channel 1 is routed to the channel 3 of the audio + output device (see + "SET FX_SEND AUDIO_OUTPUT_CHANNEL" (Altering effect send's audio routing) + for details) +
+
+ +
+The mentioned fields above don't have to be in particular order. +
+Example: +
++
++C: "GET FX_SEND INFO 0 0" +
+S: "NAME: Reverb Send" +
+"MIDI_CONTROLLER: 91" +
+"LEVEL: 0.3" +
+"AUDIO_OUTPUT_ROUTING: 2,3" +
+"." +
+
+ +
+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 (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: +
++
++"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 + sampler channel by sending the following command: +
++
++SET FX_SEND AUDIO_OUTPUT_CHANNEL <sampler-chan> <fx-send-id> <audio-src> <audio-dst> +
+
+ +
+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, + <audio-src> is the numerical ID of the effect send's audio channel + which should be rerouted and <audio-dst> is the numerical ID of + the audio channel of the selected audio output device where <audio-src> + should be routed to. +
+Note that effect sends can only route audio to the same audio output + device as assigned to the effect send's sampler channel. Also note that an + effect send entity does always have exactly as much audio channels as its + sampler channel. So if the sampler channel is stereo, the effect send does + have two audio channels as well. Also keep in mind that the amount of audio + channels on a sampler channel might be dependant not only to the deployed + sampler engine on the sampler channel, but also dependant to the instrument + currently loaded. However you can (effectively) turn an i.e. stereo effect + send into a mono one by simply altering its audio routing appropriately. +
+Possible Answers: +
++
++"OK" - +
+++ + +on success +
+"WRN:<warning-code>:<warning-message>" - +
+++ + +if audio output channel 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 AUDIO_OUTPUT_CHANNEL 0 0 0 2" +
+S: "OK" +
+
+ +
+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: @@ -5346,6 +6128,8 @@
@@ -5367,6 +6151,15 @@ +arbitrary textual description about the sampler + (note that the character string may contain + escape sequences (Character Set and Escape Sequences))
INSTRUMENTS_DB_SUPPORT - +
+++ + @@ -5376,6 +6169,94 @@either yes or no, specifies whether the + sampler is build with instruments database support. +
+
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 |
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:
@@ -5686,6 +6570,17 @@+ + +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)) +
+
DEFAULT - +
++@@ -5707,6 +6602,8 @@either true or false, + defines whether this map is the default map
S: "NAME: Standard Map"
+"DEFAULT: true" +
"."
@@ -5730,7 +6627,10 @@
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:
@@ -5780,7 +6680,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>] @@ -5796,11 +6696,13 @@ 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 - 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 @@ -5844,7 +6746,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 @@ -5893,21 +6795,28 @@ 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)).
- 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: @@ -5974,7 +6883,7 @@
-@@ -6227,7 +7138,9 @@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"
@@ -6211,6 +7120,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))"INSTRUMENT_FILE" -
-@@ -6245,7 +7158,8 @@File name of the instrument. +
File name of the instrument + (note that this path may contain + escape sequences (Character Set and Escape Sequences)).
@@ -6263,7 +7177,7 @@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)).
@@ -6372,6 +7286,1868 @@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)
+
++
TOC 6.8. +Managing Instruments Database
+ +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 6.8.1. +Creating a new instrument directory
+ +The front-end can add a new instrument directory to the + instruments database by sending the following command: +
++
++ADD DB_INSTRUMENT_DIRECTORY <dir> +
++ +
+Where <dir> is the absolute path name of the directory + to be created (encapsulated into apostrophes). +
+Possible Answers: +
++
++"OK" - +
+++ + +on success +
+"ERR:<error-code>:<error-message>" - +
+++ + +when the directory could not be created, which + can happen if the directory already exists or the + name contains not allowed symbols +
++ +
+Examples: +
++
++C: "ADD DB_INSTRUMENT_DIRECTORY '/Piano Collection'" +
+S: "OK" +
++ +
+
++
TOC 6.8.2. +Deleting an instrument directory
+ +The front-end can delete a particular instrument directory + from the instruments database by sending the following command: +
++
++REMOVE DB_INSTRUMENT_DIRECTORY [FORCE] <dir> +
++ +
+Where <dir> is the absolute path name of the directory + to delete. The optional FORCE argument can be used to + force the deletion of a non-empty directory and all its content. +
+Possible Answers: +
++
++"OK" - +
+++ + +if the directory is deleted successfully +
+"ERR:<error-code>:<error-message>" - +
+++ + +if the given directory does not exist, or + if trying to delete a non-empty directory, + without using the FORCE argument. +
++ +
+Examples: +
++
++C: "REMOVE DB_INSTRUMENT_DIRECTORY FORCE '/Piano Collection'" +
+S: "OK" +
++ +
+
++
TOC 6.8.3. +Getting amount of instrument directories
+ +The front-end can retrieve the current amount of + directories in a specific directory by sending the following command: +
++
++GET DB_INSTRUMENT_DIRECTORIES [RECURSIVE] <dir> +
++ +
+Where <dir> should be replaced by the absolute path + name of the directory. If RECURSIVE is specified, the number of + all directories, including those located in subdirectories of the + specified directory, will be returned. +
+Possible Answers: +
++
++The current number of instrument directories + in the specified directory. +
+"ERR:<error-code>:<error-message>" - +
+++ + +if the given directory does not exist. +
++ +
+Example: +
++
++C: "GET DB_INSTRUMENT_DIRECTORIES '/'" +
+S: "2" +
++ +
+
++
TOC 6.8.4. +Listing all directories in specific directory
+ +The front-end can retrieve the current list of directories + in specific directory by sending the following command: +
++
++LIST DB_INSTRUMENT_DIRECTORIES [RECURSIVE] <dir> +
++ +
+Where <dir> should be replaced by the absolute path + name of the directory. If RECURSIVE is specified, the absolute path names + of all directories, including those located in subdirectories of the + specified directory, will be returned. +
+Possible Answers: +
++
++A comma separated list of all instrument directories + (encapsulated into apostrophes) in the specified directory. +
+"ERR:<error-code>:<error-message>" - +
+++ + +if the given directory does not exist. +
++ +
+Example: +
++
++C: "LIST DB_INSTRUMENT_DIRECTORIES '/'" +
+S: "'Piano Collection','Percussion Collection'" +
++ +
++
++C: "LIST DB_INSTRUMENT_DIRECTORIES RECURSIVE '/'" +
+S: "'/Piano Collection','/Piano Collection/Acoustic','/Piano Collection/Acoustic/New','/Percussion Collection'" +
++ +
+
++
TOC 6.8.5. +Getting instrument directory information
+ +The front-end can ask for the current settings of an + instrument directory by sending the following command: +
++
++GET DB_INSTRUMENT_DIRECTORY INFO <dir> +
++ +
+Where <dir> should be replaced by the absolute path + name of the directory the front-end is interested in. +
+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: +
++
+++ + +DESCRIPTION - +
+++ + +A brief description of the directory content. + Note that the character string may contain + escape sequences (Character Set and Escape Sequences). +
+CREATED - +
+++ + +The creation date and time of the directory, + represented in "YYYY-MM-DD HH:MM:SS" format +
+MODIFIED - +
+++ + +The date and time of the last modification of the + directory, represented in "YYYY-MM-DD HH:MM:SS" format +
++ +
+The mentioned fields above don't have to be in particular order. +
+Example: +
++
++C: "GET DB_INSTRUMENT_DIRECTORY INFO '/Piano Collection'" +
+S: "DESCRIPTION: Piano collection of instruments in GigaSampler format." +
+"CREATED: 2007-02-05 10:23:12" +
+"MODIFIED: 2007-04-07 12:50:21" +
+"." +
++ +
+
++
TOC 6.8.6. +Renaming an instrument directory
+ +The front-end can alter the name of a specific + instrument directory by sending the following command: +
++
++SET DB_INSTRUMENT_DIRECTORY NAME <dir> <name> +
++ +
+Where <dir> is the absolute path name of the directory and + <name> is the new name for that directory. +
+Possible Answers: +
++
++"OK" - +
+++ + +on success +
+"ERR:<error-code>:<error-message>" - +
+++ + +in case the given directory does not exists, + or if a directory with name equal to the new + name already exists. +
++ +
+Example: +
++
++C: "SET DB_INSTRUMENT_DIRECTORY NAME '/Piano Collection/Acustic' 'Acoustic'" +
+S: "OK" +
++ +
+
++
TOC 6.8.7. +Moving an instrument directory
+ +The front-end can move a specific + instrument directory by sending the following command: +
++
++MOVE DB_INSTRUMENT_DIRECTORY <dir> <dst> +
++ +
+Where <dir> is the absolute path name of the directory + to move and <dst> is the location where the directory will + be moved to. +
+Possible Answers: +
++
++"OK" - +
+++ + +on success +
+"ERR:<error-code>:<error-message>" - +
+++ + +in case a given directory does not exists, + or if a directory with name equal to the name + of the specified directory already exists in + the destination directory. Error is also thrown + when trying to move a directory to a subdirectory + of itself. +
++ +
+Example: +
++
++C: "MOVE DB_INSTRUMENT_DIRECTORY '/Acoustic' '/Piano Collection/Acoustic'" +
+S: "OK" +
++ +
+
++
TOC 6.8.8. +Copying instrument directories
+ +The front-end can copy a specific + instrument directory by sending the following command: +
++
++COPY DB_INSTRUMENT_DIRECTORY <dir> <dst> +
++ +
+Where <dir> is the absolute path name of the directory + to copy and <dst> is the location where the directory will + be copied to. +
+Possible Answers: +
++
++"OK" - +
+++ + +on success +
+"ERR:<error-code>:<error-message>" - +
+++ + +in case a given directory does not exists, + or if a directory with name equal to the name + of the specified directory already exists in + the destination directory. Error is also thrown + when trying to copy a directory to a subdirectory + of itself. +
++ +
+Example: +
++
++C: "COPY DB_INSTRUMENT_DIRECTORY '/Piano Collection/Acoustic' '/Acoustic/Pianos'" +
+S: "OK" +
++ +
+
++
TOC 6.8.9. +Changing the description of directory
+ +The front-end can alter the description of a specific + instrument directory by sending the following command: +
++
++SET DB_INSTRUMENT_DIRECTORY DESCRIPTION <dir> <desc> +
++ +
+Where <dir> is the absolute path name of the directory and + <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: +
++
++"OK" - +
+++ + +on success +
+"ERR:<error-code>:<error-message>" - +
+++ + +in case the given directory does not exists. +
++ +
+Example: +
++
++C: "SET DB_INSTRUMENT_DIRECTORY DESCRIPTION '/Piano Collection' 'A collection of piano instruments in various format.'" +
+S: "OK" +
++ +
+
++
TOC 6.8.10. +Finding directories
+ +The front-end can search for directories + in specific directory by sending the following command: +
++
++FIND DB_INSTRUMENT_DIRECTORIES [NON_RECURSIVE] <dir> <criteria-list> +
++ +
+Where <dir> should be replaced by the absolute path + name of the directory to search in. If NON_RECURSIVE is specified, the + directories located in subdirectories of the specified directory will not + be searched. <criteria-list> is a list of search criterias + in form of "key1=val1 key2=val2 ...". The following criterias are + allowed: +
++ +
NAME='<search-string>' +
++Restricts the search to directories, which names + 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)"). +
++ +
+ + +CREATED='[<date-after>]..[<date-before>]' +
++Restricts the search to directories, which creation + date satisfies the specified period, where <date-after> + and <date-before> are in "YYYY-MM-DD HH:MM:SS" format. + If <date-after> is omitted the search is restricted to + directories created before <date-before>. If + <date-before> is omitted, the search is restricted + to directories created after <date-after>. +
++ +
+ + +MODIFIED='[<date-after>]..[<date-before>]' +
++Restricts the search to directories, which + date of last modification satisfies the specified period, where + <date-after> and <date-before> are in "YYYY-MM-DD HH:MM:SS" + format. If <date-after> is omitted the search is restricted to + directories, which are last modified before <date-before>. If + <date-before> is omitted, the search is restricted to directories, + which are last modified after <date-after>. +
++ +
+ + +DESCRIPTION='<search-string>' +
++Restricts the search to directories with description + 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)"). +
++ +
+ + +Where <search-string> is either a regular expression, or a + word list separated with spaces for OR search and with '+' for AND search. +
+Possible Answers: +
++
++A comma separated list with the absolute path names (encapsulated into + apostrophes) of all directories in the specified directory that satisfy + the supplied search criterias. +
+"ERR:<error-code>:<error-message>" - +
+++ + +if the given directory does not exist. +
++ +
+Example: +
++
++C: "FIND DB_INSTRUMENT_DIRECTORIES '/' NAME='Piano'" +
+S: "'/Piano Collection'" +
++ +
++
++C: "FIND DB_INSTRUMENT_DIRECTORIES '/' CREATED='..2007-04-01 09:30:13'" +
+S: "'/Piano Collection','/Percussions'" +
++ +
+
++
TOC 6.8.11. +Adding instruments to the instruments database
+ +The front-end can add one or more instruments + to the instruments database by sending the following command: +
++
++ADD DB_INSTRUMENTS [NON_MODAL] [<mode>] <db_dir> <file_path> [<instr_index>] +
++ +
+Where <db_dir> is the absolute path name of a directory + (encapsulated into apostrophes) in the instruments database in which + only the new instruments (that are not already in the database) will + be added, <file_path> is the absolute path name of a file or + directory in the file system (encapsulated into apostrophes). In case + an instrument file is supplied, only the instruments in the specified + file will be added to the instruments database. If the optional + <instr_index> (the index of the instrument within the given file) + is supplied too, then only the specified instrument will be added. + In case a directory is supplied, the instruments in that directory + will be added. The OPTIONAL <mode> argument is only applied + when a directory is provided as <file_path> and specifies how the + scanning will be done and has exactly the following possibilities: +
++
++"RECURSIVE" - +
+++ + +All instruments will be processed, including those + in the subdirectories, and the respective subdirectory + tree structure will be recreated in the instruments + database +
+"NON_RECURSIVE" - +
+++ + +Only the instruments in the specified directory + will be added, the instruments in the subdirectories + will not be processed. +
+"FLAT" - +
+++ + +All instruments will be processed, including those + in the subdirectories, but the respective subdirectory + structure will not be recreated in the instruments + database. All instruments will be added directly in + the specified database directory. +
++ +
+The difference between regular and NON_MODAL versions of the command + is that the regular command returns when the scanning is finished + while NON_MODAL version returns immediately and a background process is launched. + The GET DB_INSTRUMENTS_JOB INFO (Getting job status information) + command can be used to monitor the scanning progress. +
+Possible Answers: +
++
++"OK" - +
+++ + +on success when NON_MODAL is not supplied +
+"OK[<job-id>]" - +
+++ + +on success when NON_MODAL is supplied, where <job-id> + is a numerical ID used to obtain status information about the job progress. + See GET DB_INSTRUMENTS_JOB INFO (Getting job status information) + +
+"ERR:<error-code>:<error-message>" - +
+++ + +if an invalid path is specified. +
++ +
+Examples: +
++
++C: "ADD DB_INSTRUMENTS '/Piano Collection' '/home/me/gigs/PMI Bosendorfer 290.gig' 0" +
+S: "OK" +
++ +
+
++
TOC 6.8.12. +Removing an instrument
+ +The front-end can remove a particular instrument + from the instruments database by sending the following command: +
++
++REMOVE DB_INSTRUMENT <instr_path> +
++ +
+Where <instr_path> is the absolute path name + (in the instruments database) of the instrument to remove. +
+Possible Answers: +
++
++"OK" - +
+++ + +if the instrument is removed successfully +
+"ERR:<error-code>:<error-message>" - +
+++ + +if the given path does not exist or + is a directory. +
++ +
+Examples: +
++
++C: "REMOVE DB_INSTRUMENT '/Piano Collection/Bosendorfer 290'" +
+S: "OK" +
++ +
+
++
TOC 6.8.13. +Getting amount of instruments
+ +The front-end can retrieve the current amount of + instruments in a specific directory by sending the following command: +
++
++GET DB_INSTRUMENTS [RECURSIVE] <dir> +
++ +
+Where <dir> should be replaced by the absolute path name + of the directory. If RECURSIVE is specified, the number of all + instruments, including those located in subdirectories of the + specified directory, will be returned. +
+Possible Answers: +
++
++The current number of instruments + in the specified directory. +
+"ERR:<error-code>:<error-message>" - +
+++ + +if the given directory does not exist. +
++ +
+Example: +
++
++C: "GET DB_INSTRUMENTS '/Piano Collection'" +
+S: "2" +
++ +
+
++
TOC 6.8.14. +Listing all instruments in specific directory
+ +The front-end can retrieve the current list of instruments + in specific directory by sending the following command: +
++
++LIST DB_INSTRUMENTS [RECURSIVE] <dir> +
++ +
+Where <dir> should be replaced by the absolute path + name of the directory. If RECURSIVE is specified, the absolute path + names of all instruments, including those located in subdirectories + of the specified directory, will be returned. +
+Possible Answers: +
++
++A comma separated list of all instruments + (encapsulated into apostrophes) in the specified directory. +
+"ERR:<error-code>:<error-message>" - +
+++ + +if the given directory does not exist. +
++ +
+Example: +
++
++C: "LIST DB_INSTRUMENTS '/Piano Collection'" +
+S: "'Bosendorfer 290','Steinway D'" +
++ +
++
++C: "LIST DB_INSTRUMENTS RECURSIVE '/Piano Collection'" +
+S: "'/Piano Collection/Bosendorfer 290','/Piano Collection/Steinway D','/Piano Collection/Lite/Free Piano'" +
++ +
+
++
TOC 6.8.15. +Getting instrument information
+ +The front-end can ask for the current settings of an + instrument by sending the following command: +
++
++GET DB_INSTRUMENT INFO <instr_path> +
++ +
+Where <instr_path> should be replaced by the absolute path + name of the instrument the front-end is interested in. +
+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: +
++
+++ + +INSTRUMENT_FILE - +
+++ + +File name of the instrument. + Note that the character string may contain + escape sequences (Character Set and Escape Sequences). +
+INSTRUMENT_NR - +
+++ + +Index of the instrument within the file. +
+FORMAT_FAMILY - +
+++ + +The format family of the instrument. +
+FORMAT_VERSION - +
+++ + +The format version of the instrument. +
+SIZE - +
+++ + +The size of the instrument in bytes. +
+CREATED - +
+++ + +The date and time when the instrument is added + in the instruments database, represented in + "YYYY-MM-DD HH:MM:SS" format +
+MODIFIED - +
+++ + +The date and time of the last modification of the + instrument's database settings, represented in + "YYYY-MM-DD HH:MM:SS" format +
+DESCRIPTION - +
+++ + +A brief description of the instrument. + Note that the character string may contain + escape sequences (Character Set and Escape Sequences). +
+IS_DRUM - +
+++ + +either true or false, determines whether the + instrument is a drumkit or a chromatic instrument +
+PRODUCT - +
+++ + +The product title of the instrument. + Note that the character string may contain + escape sequences (Character Set and Escape Sequences). +
+ARTISTS - +
+++ + +Lists the artist names. + Note that the character string may contain + escape sequences (Character Set and Escape Sequences). +
+KEYWORDS - +
+++ + +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). +
++ +
+The mentioned fields above don't have to be in particular order. +
+Example: +
++
++C: "GET DB_INSTRUMENT INFO '/Piano Collection/Bosendorfer 290'" +
+S: "INSTRUMENT_FILE: /home/me/gigs/Bosendorfer 290.gig" +
+"INSTRUMENT_NR: 0" +
+"FORMAT_FAMILY: GIG" +
+"FORMAT_VERSION: 2" +
+"SIZE: 2050871870" +
+"CREATED: 2007-02-05 10:23:12" +
+"MODIFIED: 2007-04-07 12:50:21" +
+"DESCRIPTION: " +
+"IS_DRUM: false" +
+"PRODUCT: GRANDIOSO Bosendorfer 290" +
+"ARTISTS: Post Musical Instruments" +
+"KEYWORDS: Bosendorfer" +
+"." +
++ +
+
++
TOC 6.8.16. +Renaming an instrument
+ +The front-end can alter the name of a specific + instrument by sending the following command: +
++
++SET DB_INSTRUMENT NAME <instr> <name> +
++ +
+Where <instr> is the absolute path name of the instrument and + <name> is the new name for that instrument. +
+Possible Answers: +
++
++"OK" - +
+++ + +on success +
+"ERR:<error-code>:<error-message>" - +
+++ + +in case the given instrument does not exists, + or if an instrument with name equal to the new + name already exists. +
++ +
+Example: +
++
++C: "SET DB_INSTRUMENT NAME '/Piano Collection/Bosendorfer' 'Bosendorfer 290'" +
+S: "OK" +
++ +
+
++
TOC 6.8.17. +Moving an instrument
+ +The front-end can move a specific instrument to another directory by + sending the following command: +
++
++MOVE DB_INSTRUMENT <instr> <dst> +
++ +
+Where <instr> is the absolute path name of the instrument + to move and <dst> is the directory where the instrument will + be moved to. +
+Possible Answers: +
++
++"OK" - +
+++ + +on success +
+"ERR:<error-code>:<error-message>" - +
+++ + +in case the given instrument does not exists, + or if an instrument with name equal to the name of the + specified instrument already exists in the destination + directory. +
++ +
+Example: +
++
++C: "MOVE DB_INSTRUMENT '/Piano Collection/Bosendorfer 290' '/Piano Collection/Acoustic'" +
+S: "OK" +
++ +
+
++
TOC 6.8.18. +Copying instruments
+ +The front-end can copy a specific instrument to another directory by + sending the following command: +
++
++COPY DB_INSTRUMENT <instr> <dst> +
++ +
+Where <instr> is the absolute path name of the instrument + to copy and <dst> is the directory where the instrument will + be copied to. +
+Possible Answers: +
++
++"OK" - +
+++ + +on success +
+"ERR:<error-code>:<error-message>" - +
+++ + +in case the given instrument does not exists, + or if an instrument with name equal to the name of the + specified instrument already exists in the destination + directory. +
++ +
+Example: +
++
++C: "COPY DB_INSTRUMENT '/Piano Collection/Bosendorfer 290' '/Acoustic/Pianos/'" +
+S: "OK" +
++ +
+
++
TOC 6.8.19. +Changing the description of instrument
+ +The front-end can alter the description of a specific + instrument by sending the following command: +
++
++SET DB_INSTRUMENT DESCRIPTION <instr> <desc> +
++ +
+Where <instr> is the absolute path name of the instrument and + <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: +
++
++"OK" - +
+++ + +on success +
+"ERR:<error-code>:<error-message>" - +
+++ + +in case the given instrument does not exists. +
++ +
+Example: +
++
++C: "SET DB_INSTRUMENT DESCRIPTION '/Piano Collection/Acoustic/Bosendorfer 290' 'No comment :)'" +
+S: "OK" +
++ +
+
++
TOC 6.8.20. +Finding instruments
+ +The front-end can search for instruments + in specific directory by sending the following command: +
++
++FIND DB_INSTRUMENTS [NON_RECURSIVE] <dir> <criteria-list> +
++ +
+Where <dir> should be replaced by the absolute path + name of the directory to search in. If NON_RECURSIVE is specified, the + directories located in subdirectories of the specified directory will not + be searched. <criteria-list> is a list of search criterias + in form of "key1=val1 key2=val2 ...". The following criterias are + allowed: +
++ +
NAME='<search-string>' +
++Restricts the search to instruments, which names + 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)"). +
++ +
+ + +SIZE=[<min>]..[<max>] +
++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 + search is restricted to instruments with size greater then + or equal to <min>. +
++ +
+ + +CREATED='[<date-after>]..[<date-before>]' +
++Restricts the search to instruments, which creation + date satisfies the specified period, where <date-after> + and <date-before> are in "YYYY-MM-DD HH:MM:SS" format. + If <date-after> is omitted the search is restricted to + instruments created before <date-before>. If + <date-before> is omitted, the search is restricted + to instruments created after <date-after>. +
++ +
+ + +MODIFIED='[<date-after>]..[<date-before>]' +
++Restricts the search to instruments, which + date of last modification satisfies the specified period, where + <date-after> and <date-before> are in "YYYY-MM-DD HH:MM:SS" + format. If <date-after> is omitted the search is restricted to + instruments, which are last modified before <date-before>. If + <date-before> is omitted, the search is restricted to instruments, + which are last modified after <date-after>. +
++ +
+ + +DESCRIPTION='<search-string>' +
++Restricts the search to instruments with description + 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)"). +
++ +
+ + +PRODUCT='<search-string>' +
++Restricts the search to instruments with product info + 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)"). +
++ +
+ + +ARTISTS='<search-string>' +
++Restricts the search to instruments with artists info + 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)"). +
++ +
+ + +KEYWORDS='<search-string>' +
++Restricts the search to instruments with keyword list + 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)"). +
++ +
+ + +IS_DRUM=true | false +
++Either true or false. Restricts the search to + drum kits or chromatic instruments. +
++ +
+ + +FORMAT_FAMILIES='<format-list>' +
++Restricts the search to instruments of the supplied format families, + where <format-list> is a comma separated list of format families. +
++ +
+ + +Where <search-string> is either a regular expression, or a + word list separated with spaces for OR search and with '+' for AND search. +
+Possible Answers: +
++
++A comma separated list with the absolute path names (encapsulated into + apostrophes) of all instruments in the specified directory that satisfy + the supplied search criterias. +
+"ERR:<error-code>:<error-message>" - +
+++ + +if the given directory does not exist. +
++ +
+Example: +
++
++C: "FIND DB_INSTRUMENTS '/Piano Collection' NAME='bosendorfer+290'" +
+S: "'/Piano Collection/Bosendorfer 290'" +
++ +
++
++C: "FIND DB_INSTRUMENTS '/Piano Collection' CREATED='2007-04-01 09:30:13..'" +
+S: "'/Piano Collection/Bosendorfer 290','/Piano Collection/Steinway D'" +
++ +
+
++
TOC 6.8.21. +Getting job status information
+ +The front-end can ask for the current status of a + particular database instruments job by sending the following command: +
++
++GET DB_INSTRUMENTS_JOB INFO <job-id> +
++ +
+Where <job-id> should be replaced by the numerical ID + of the job the front-end is interested in. +
+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: +
++
+++ + +FILES_TOTAL - +
+++ + +The total number of files scheduled for scanning +
+FILES_SCANNED - +
+++ + +The current number of scanned files +
+SCANNING - +
+++ + +The absolute path name of the file which is currently + being scanned +
+STATUS - +
+++ + +An integer value between 0 and 100 indicating the + scanning progress percentage of the file which is + currently being scanned +
++ +
+The mentioned fields above don't have to be in particular order. +
+Example: +
++
++C: "GET DB_INSTRUMENTS_JOB INFO 2" +
+S: "FILES_TOTAL: 12" +
+"FILES_SCANNED: 7" +
+"SCANNING: /home/me/gigs/Bosendorfer 290.gig" +
+"STATUS: 42" +
+"." +
++ +
+
++
TOC 6.8.22. +Formatting the instruments database
+ +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 6.9. +Editing Instruments
+ +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 6.9.1. +Opening an appropriate instrument editor application
+ +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 7. @@ -6472,15 +9248,27 @@
/ UNSUBSCRIBE SP unsubscribe_event
-/ SELECT SP text - -
/ RESET SP reset_instruction
/ CLEAR SP clear_instruction
+/ FIND SP find_instruction + +
+/ MOVE SP move_instruction + +
+/ COPY SP copy_instruction + +
+/ EDIT SP edit_instruction + +
+/ FORMAT SP format_instruction + +
/ RESET
@@ -6496,6 +9284,27 @@CHANNEL
+/ DB_INSTRUMENT_DIRECTORY SP db_path + +
+/ DB_INSTRUMENTS SP NON_MODAL SP scan_mode SP db_path SP filename + +
+/ DB_INSTRUMENTS SP scan_mode SP db_path SP filename + +
+/ DB_INSTRUMENTS SP NON_MODAL SP db_path SP filename + +
+/ DB_INSTRUMENTS SP NON_MODAL SP db_path SP filename SP instrument_index + +
+/ DB_INSTRUMENTS SP db_path SP filename + +
+/ DB_INSTRUMENTS SP db_path SP filename SP instrument_index + +
/ MIDI_INSTRUMENT_MAP
@@ -6508,7 +9317,19 @@subscribe_event =
-CHANNEL_COUNT +
AUDIO_OUTPUT_DEVICE_COUNT + +
+/ AUDIO_OUTPUT_DEVICE_INFO + +
+/ MIDI_INPUT_DEVICE_COUNT + +
+/ MIDI_INPUT_DEVICE_INFO + +
+/ CHANNEL_COUNT
/ VOICE_COUNT @@ -6523,19 +9344,67 @@
/ CHANNEL_INFO
+/ FX_SEND_COUNT + +
+/ FX_SEND_INFO + +
+/ MIDI_INSTRUMENT_MAP_COUNT + +
+/ MIDI_INSTRUMENT_MAP_INFO + +
+/ MIDI_INSTRUMENT_COUNT + +
+/ MIDI_INSTRUMENT_INFO + +
+/ DB_INSTRUMENT_DIRECTORY_COUNT + +
+/ DB_INSTRUMENT_DIRECTORY_INFO + +
+/ DB_INSTRUMENT_COUNT + +
+/ DB_INSTRUMENT_INFO + +
+/ DB_INSTRUMENTS_JOB_INFO + +
/ MISCELLANEOUS
/ TOTAL_VOICE_COUNT
+/ GLOBAL_INFO + +
unsubscribe_event =
-CHANNEL_COUNT +
AUDIO_OUTPUT_DEVICE_COUNT + +
+/ AUDIO_OUTPUT_DEVICE_INFO + +
+/ MIDI_INPUT_DEVICE_COUNT + +
+/ MIDI_INPUT_DEVICE_INFO + +
+/ CHANNEL_COUNT
/ VOICE_COUNT @@ -6550,28 +9419,64 @@
/ CHANNEL_INFO
+/ FX_SEND_COUNT + +
+/ FX_SEND_INFO + +
+/ MIDI_INSTRUMENT_MAP_COUNT + +
+/ MIDI_INSTRUMENT_MAP_INFO + +
+/ MIDI_INSTRUMENT_COUNT + +
+/ MIDI_INSTRUMENT_INFO + +
+/ DB_INSTRUMENT_DIRECTORY_COUNT + +
+/ DB_INSTRUMENT_DIRECTORY_INFO + +
+/ DB_INSTRUMENT_COUNT + +
+/ DB_INSTRUMENT_INFO + +
+/ DB_INSTRUMENTS_JOB_INFO + +
/ MISCELLANEOUS
/ 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
@@ -6598,6 +9503,15 @@
/ MIDI_INSTRUMENT_MAP SP ALL
+/ DB_INSTRUMENT_DIRECTORY SP FORCE SP db_path + +
+/ DB_INSTRUMENT_DIRECTORY SP db_path + +
+/ DB_INSTRUMENT SP db_path + +
@@ -6697,6 +9611,36 @@
/ MIDI_INSTRUMENT_MAP SP INFO SP midi_map
+/ FX_SENDS SP sampler_channel + +
+/ FX_SEND SP INFO SP sampler_channel SP fx_send_id + +
+/ DB_INSTRUMENT_DIRECTORIES SP RECURSIVE SP db_path + +
+/ DB_INSTRUMENT_DIRECTORIES SP db_path + +
+/ DB_INSTRUMENT_DIRECTORY SP INFO SP db_path + +
+/ DB_INSTRUMENTS SP RECURSIVE SP db_path + +
+/ DB_INSTRUMENTS SP db_path + +
+/ DB_INSTRUMENT SP INFO SP db_path + +
+/ DB_INSTRUMENTS_JOB SP INFO SP number + +
+/ VOLUME + +
@@ -6712,6 +9656,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
@@ -6721,9 +9668,36 @@/ 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 + +
+/ DB_INSTRUMENT_DIRECTORY SP NAME SP db_path SP stringval_escaped + +
+/ DB_INSTRUMENT_DIRECTORY SP DESCRIPTION SP db_path SP stringval_escaped + +
+/ DB_INSTRUMENT SP NAME SP db_path SP stringval_escaped + +
+/ DB_INSTRUMENT SP DESCRIPTION SP db_path SP stringval_escaped + +
/ ECHO SP boolean
+/ VOLUME SP volume_value + +
@@ -6742,6 +9716,12 @@
/ MIDI_INPUT_DEVICE SP string
+/ FX_SEND SP sampler_channel SP midi_ctrl + +
+/ FX_SEND SP sampler_channel SP midi_ctrl SP fx_send_name + +
@@ -6766,6 +9746,48 @@
+
find_instruction = +
++DB_INSTRUMENTS SP NON_RECURSIVE SP db_path SP query_val_list + +
+/ DB_INSTRUMENTS SP db_path SP query_val_list + +
+/ DB_INSTRUMENT_DIRECTORIES SP NON_RECURSIVE SP db_path SP query_val_list + +
+/ DB_INSTRUMENT_DIRECTORIES SP db_path SP query_val_list + +
+
+ +
+move_instruction = +
++DB_INSTRUMENT_DIRECTORY SP db_path SP db_path + +
+/ DB_INSTRUMENT SP db_path SP db_path + +
+
+ +
+copy_instruction = +
++DB_INSTRUMENT_DIRECTORY SP db_path SP db_path + +
+/ DB_INSTRUMENT SP db_path SP db_path + +
+
+ +
destroy_instruction =
@@ -6775,6 +9797,9 @@/ MIDI_INPUT_DEVICE SP number
+/ FX_SEND SP sampler_channel SP fx_send_id + +
@@ -6838,6 +9863,36 @@
+
edit_instruction = +
++CHANNEL SP INSTRUMENT SP sampler_channel + +
+
+ +
+format_instruction = +
++INSTRUMENTS_DB + +
+
+ +
+modal_arg = +
++/* epsilon (empty argument) */ + +
+/ NON_MODAL SP + +
+
+ +
key_val_list =
@@ -6892,6 +9947,21 @@/ MIDI_INSTRUMENT_MAPS
+/ FX_SENDS SP sampler_channel + +
+/ DB_INSTRUMENT_DIRECTORIES SP RECURSIVE SP db_path + +
+/ DB_INSTRUMENT_DIRECTORIES SP db_path + +
+/ DB_INSTRUMENTS SP RECURSIVE SP db_path + +
+/ DB_INSTRUMENTS SP db_path + +
@@ -7015,6 +10085,15 @@
+
midi_ctrl = +
++number + +
+
+ +
volume_value =
@@ -7045,6 +10124,15 @@
+
fx_send_id = +
++number + +
+
+ +
engine_name =
@@ -7057,7 +10145,16 @@filename =
-stringval +
path + +
++ +
+db_path = +
++path
@@ -7066,7 +10163,7 @@
map_name =
-stringval +
stringval_escaped
@@ -7075,7 +10172,16 @@
entry_name =
-stringval +
stringval_escaped + +
++ +
+fx_send_name = +
++stringval_escaped
@@ -7111,6 +10217,224 @@
+
query_val_list = +
++string '=' query_val + +
+/ query_val_list SP string '=' query_val + +
+
+ +
+query_val = +
++text_escaped + +
+/ stringval_escaped + +
+
+ +
+scan_mode = +
++RECURSIVE + +
+/ NON_RECURSIVE + +
+/ FLAT + +
+
+ +
+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) +
+
+ 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"). + +
++ 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 |
This chapter will describe all currently defined events supported by LinuxSampler.
-TOC |
Client may want to be notified when the total number of audio output devices on the + back-end changes by issuing the following command: +
++
++SUBSCRIBE AUDIO_OUTPUT_DEVICE_COUNT +
+
+ +
+Server will start sending the following notification messages: +
++
++"NOTIFY:AUDIO_OUTPUT_DEVICE_COUNT:<devices>" +
+
+ +
+where <devices> will be replaced by the new number + of audio output devices. +
+TOC |
Client may want to be notified when changes were made to audio output devices on the + back-end by issuing the following command: +
++
++SUBSCRIBE AUDIO_OUTPUT_DEVICE_INFO +
+
+ +
+Server will start sending the following notification messages: +
++
++"NOTIFY:AUDIO_OUTPUT_DEVICE_INFO:<device-id>" +
+
+ +
+where <device-id> will be replaced by the numerical ID of the audio output device, + which settings has been changed. The front-end will have to send + the respective command to actually get the audio output device info. Because these messages + will be triggered by LSCP commands issued by other clients rather than real + time events happening on the server, it is believed that an empty notification + message is sufficient here. +
+TOC |
Client may want to be notified when the total number of MIDI input devices on the + back-end changes by issuing the following command: +
++
++SUBSCRIBE MIDI_INPUT_DEVICE_COUNT +
+
+ +
+Server will start sending the following notification messages: +
++
++"NOTIFY:MIDI_INPUT_DEVICE_COUNT:<devices>" +
+
+ +
+where <devices> will be replaced by the new number + of MIDI input devices. +
+TOC |
Client may want to be notified when changes were made to MIDI input devices on the + back-end by issuing the following command: +
++
++SUBSCRIBE MIDI_INPUT_DEVICE_INFO +
+
+ +
+Server will start sending the following notification messages: +
++
++"NOTIFY:MIDI_INPUT_DEVICE_INFO:<device-id>" +
+
+ +
+where <device-id> will be replaced by the numerical ID of the MIDI input device, + which settings has been changed. The front-end will have to send + the respective command to actually get the MIDI input device info. Because these messages + will be triggered by LSCP commands issued by other clients rather than real + time events happening on the server, it is believed that an empty notification + message is sufficient here. +
+TOC |
Client may want to be notified when the total number of channels on the @@ -7149,7 +10597,7 @@
TOC |
Client may want to be notified when the number of voices on the @@ -7168,7 +10616,7 @@
-"NOTIFY:VOICE_COUNT:<sampler-channel> <voices> +
"NOTIFY:VOICE_COUNT:<sampler-channel> <voices>"
@@ -7179,7 +10627,7 @@
TOC |
Client may want to be notified when the number of streams on the back-end @@ -7209,7 +10657,7 @@
TOC |
Client may want to be notified when the buffer fill state of a disk stream @@ -7238,9 +10686,9 @@ buffer fill data for this channel as described in Section 6.4.13 (Current fill state of disk stream buffers) as if the "GET CHANNEL BUFFER_FILL PERCENTAGE" (Current fill state of disk stream buffers) command was issued on this channel.
-TOC |
Client may want to be notified when changes were made to sampler channels on the @@ -7271,9 +10719,69 @@ time events happening on the server, it is believed that an empty notification message is sufficient here.
+TOC |
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 |
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 |
Client may want to be notified when the total number of voices on the @@ -7292,7 +10800,7 @@
-"NOTIFY:TOTAL_VOICE_COUNT:<voices> +
"NOTIFY:TOTAL_VOICE_COUNT:<voices>"
@@ -7300,9 +10808,355 @@
where <voices> will be replaced by the new number of all currently active voices.
+TOC |
Client may want to be notified when the number of MIDI instrument maps on the + back-end changes by issuing the following command: +
++
++SUBSCRIBE MIDI_INSTRUMENT_MAP_COUNT +
+
+ +
+Server will start sending the following notification messages: +
++
++"NOTIFY:MIDI_INSTRUMENT_MAP_COUNT:<maps>" +
+
+ +
+where <maps> will be replaced by the new number + of MIDI instrument maps. +
+TOC |
Client may want to be notified when changes were made to MIDI instrument maps on the + back-end by issuing the following command: +
++
++SUBSCRIBE MIDI_INSTRUMENT_MAP_INFO +
+
+ +
+Server will start sending the following notification messages: +
++
++"NOTIFY:MIDI_INSTRUMENT_MAP_INFO:<map-id>" +
+
+ +
+where <map-id> will be replaced by the numerical ID of the MIDI instrument map, + for which information changes occurred. The front-end will have to send + the respective command to actually get the MIDI instrument map info. Because these messages + will be triggered by LSCP commands issued by other clients rather than real + time events happening on the server, it is believed that an empty notification + message is sufficient here. +
+TOC |
Client may want to be notified when the number of MIDI instrument maps on the + back-end changes by issuing the following command: +
++
++SUBSCRIBE MIDI_INSTRUMENT_COUNT +
+
+ +
+Server will start sending the following notification messages: +
++
++"NOTIFY:MIDI_INSTRUMENT_COUNT:<map-id> <instruments>" +
+
+ +
+where <map-id> is the numerical ID of the MIDI instrument map, in which + the nuber of instruments has changed and <instruments> will be replaced by + the new number of MIDI instruments in the specified map. +
+TOC |
Client may want to be notified when changes were made to MIDI instruments on the + back-end by issuing the following command: +
++
++SUBSCRIBE MIDI_INSTRUMENT_INFO +
+
+ +
+Server will start sending the following notification messages: +
++
++"NOTIFY:MIDI_INSTRUMENT_INFO:<map-id> <bank> <program>" +
+
+ +
+where <map-id> will be replaced by the numerical ID of the MIDI instrument map, + in which a MIDI instrument is changed. <bank> and <program> specifies + the location of the changed MIDI instrument in the map. The front-end will have to send + the respective command to actually get the MIDI instrument info. Because these messages + will be triggered by LSCP commands issued by other clients rather than real + time events happening on the server, it is believed that an empty notification + message is sufficient here. +
+TOC |
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 |
Client may want to be notified when the number of instrument + directories in a particular directory in the instruments database + is changed by issuing the following command: +
++
++SUBSCRIBE DB_INSTRUMENT_DIRECTORY_COUNT +
+
+ +
+Server will start sending the following notification messages: +
++
++"NOTIFY:DB_INSTRUMENT_DIRECTORY_COUNT:<dir-path>" +
+
+ +
+where <dir-path> will be replaced by the absolute path + name of the directory in the instruments database, + in which the number of directories is changed. +
+Note that when a non-empty directory is removed, this event + is not sent for the subdirectories in that directory. +
+TOC |
Client may want to be notified when changes were made to directories + in the instruments database by issuing the following command: +
++
++SUBSCRIBE DB_INSTRUMENT_DIRECTORY_INFO +
+
+ +
+Server will start sending the following notification messages: +
++
++"NOTIFY:DB_INSTRUMENT_DIRECTORY_INFO:<dir-path>" +
+
+ +
+where <dir-path> will be replaced by the absolute path name + of the directory, for which information changes occurred. The front-end will have to send + the respective command to actually get the updated directory info. Because these messages + will be triggered by LSCP commands issued by other clients rather than real + time events happening on the server, it is believed that an empty notification + message is sufficient here. +
++
++"NOTIFY:DB_INSTRUMENT_DIRECTORY_INFO:NAME <old-dir-path> <new-name>" +
+
+ +
+where <old-dir-path> is the old absolute path name of the directory + (encapsulated into apostrophes), which name is changes and <new-name> is + the new name of the directory, encapsulated into apostrophes. +
+TOC |
Client may want to be notified when the number of instruments + in a particular directory in the instruments database + is changed by issuing the following command: +
++
++SUBSCRIBE DB_INSTRUMENT_COUNT +
+
+ +
+Server will start sending the following notification messages: +
++
++"NOTIFY:DB_INSTRUMENT_COUNT:<dir-path>" +
+
+ +
+where <dir-path> will be replaced by the absolute path + name of the directory in the instruments database, + in which the number of instruments is changed. +
+Note that when a non-empty directory is removed, this event + is not sent for the instruments in that directory. +
+TOC |
Client may want to be notified when changes were made to instruments + in the instruments database by issuing the following command: +
++
++SUBSCRIBE DB_INSTRUMENT_INFO +
+
+ +
+Server will start sending the following notification messages: +
++
++"NOTIFY:DB_INSTRUMENT_INFO:<instr-path>" +
+
+ +
+where <instr-path> will be replaced by the absolute path name + of the instrument, which settings are changed. The front-end will have to send + the respective command to actually get the updated directory info. Because these messages + will be triggered by LSCP commands issued by other clients rather than real + time events happening on the server, it is believed that an empty notification + message is sufficient here. +
++
++"NOTIFY:DB_INSTRUMENT_INFO:NAME <old-instr-path> <new-name>" +
+
+ +
+where <old-instr-path> is the old absolute path name of the instrument + (encapsulated into apostrophes), which name is changes and <new-name> is + the new name of the instrument, encapsulated into apostrophes. +
+TOC |
Client may want to be notified when the status of particular database + instruments job is changed by issuing the following command: +
++
++SUBSCRIBE DB_INSTRUMENTS_JOB_INFO +
+
+ +
+Server will start sending the following notification messages: +
++
++"NOTIFY:DB_INSTRUMENTS_JOB_INFO:<job-id>" +
+
+ +
+where <job-id> will be replaced by the numerical ID of the job, + which status is changed. The front-end will have to send the respective + command to actually get the status info. Because these messages + will be triggered by LSCP commands issued by other clients rather than real + time events happening on the server, it is believed that an empty notification + message is sufficient here. +
TOC |
Client may want to be notified of miscellaneous and debugging events occurring at @@ -7367,6 +11221,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] | @@ -7397,7 +11253,7 @@
TOC |
-Copyright © The Internet Society (2006).
+Copyright © The IETF Trust (2007).This document is subject to the rights, licenses and restrictions contained in BCP 78, @@ -7406,13 +11262,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.The IETF takes no position regarding the validity or scope of any @@ -7444,3 +11300,4 @@ Funding for the RFC Editor function is provided by the IETF Administrative Support Activity (IASA).