--- linuxsampler/trunk/Documentation/lscp.xml 2007/09/30 21:33:26 1362 +++ linuxsampler/trunk/Documentation/lscp.xml 2007/10/14 23:23:06 1428 @@ -16,7 +16,7 @@ to an annoying "missing Normative/Informative References" error message --> - + LinuxSampler Control Protocol (draft) + channel (note: since LSCP 1.2 this path may contain + escape sequences) INSTRUMENT_NR - @@ -2537,7 +2540,9 @@ INSTRUMENT_NAME - - the instrument name of the loaded instrument + the instrument name of the loaded instrument + (note: since LSCP 1.2 this character string may contain + escape sequences) INSTRUMENT_STATUS - @@ -3255,7 +3260,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". 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 @@ -3445,7 +3452,9 @@ NAME - - name of the effect send entity + name of the effect send entity + (note that this character string may contain + escape sequences) MIDI_CONTROLLER - @@ -3508,7 +3517,10 @@ as returned by the "CREATE FX_SEND" or "LIST FX_SENDS" 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"). + Possible Answers: @@ -3959,7 +3971,9 @@ DESCRIPTION - - arbitrary textual description about the sampler + arbitrary textual description about the sampler + (note that the character string may contain + escape sequences) VERSION - @@ -4075,7 +4089,7 @@ cause the sampler to switch to the respective instrument as reflected by the current MIDI instrument map. -
+
The front-end can add a new MIDI instrument map by sending the following command: @@ -4085,7 +4099,10 @@ 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". + Possible Answers: @@ -4256,7 +4273,9 @@ NAME - custom name of the given map, - which does not have to be unique + which does not have to be unique + (note that this character string may contain + escape sequences) DEFAULT - @@ -4292,7 +4311,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"). + Possible Answers: @@ -4423,9 +4445,10 @@ load modes of entries, the frontend should retrieve the actual mode by i.e. sending "GET MIDI_INSTRUMENT INFO" - 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") for the + mapping entry, useful for frontends for displaying an appropriate name for mapped instruments (using "GET MIDI_INSTRUMENT INFO"). @@ -4649,7 +4672,9 @@ name for this mapped instrument. It can be set and changed with the "MAP MIDI_INSTRUMENT" - command and does not have to be unique. + command and does not have to be unique. + (note that this character string may contain + escape sequences) "ENGINE_NAME" - @@ -4660,7 +4685,9 @@ "INSTRUMENT_FILE" - - File name of the instrument. + File name of the instrument + (note that this path may contain + escape sequences). "INSTRUMENT_NR" - @@ -4672,7 +4699,8 @@ 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). "LOAD_MODE" - @@ -5969,7 +5997,7 @@ editor application by sending the following command: - EDIT INSTRUMENT <sampler-channel> + EDIT CHANNEL INSTRUMENT <sampler-channel> Where <sampler-channel> should be replaced by the @@ -6021,7 +6049,7 @@ Examples: - C: "EDIT INSTRUMENT 0" + C: "EDIT CHANNEL INSTRUMENT 0" S: "OK" @@ -6514,7 +6542,7 @@ edit_instruction = - INSTRUMENT SP sampler_channel + CHANNEL SP INSTRUMENT SP sampler_channel @@ -6712,19 +6740,19 @@ map_name = - stringval + stringval_escaped entry_name = - stringval + stringval_escaped fx_send_name = - stringval + stringval_escaped @@ -6736,6 +6764,7 @@ + param_val = string @@ -6758,7 +6787,7 @@ query_val = - textval_escaped + text_escaped / stringval_escaped @@ -6807,6 +6836,74 @@ 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" + "GET CHANNEL INFO" + "MAP MIDI_INSTRUMENT" + "GET MIDI_INSTRUMENT INFO" + "ADD DB_INSTRUMENT_DIRECTORY" + "ADD DB_INSTRUMENTS" + "REMOVE DB_INSTRUMENT_DIRECTORY" + "REMOVE DB_INSTRUMENT" + "GET DB_INSTRUMENT_DIRECTORIES" + "LIST DB_INSTRUMENT_DIRECTORIES" + "GET DB_INSTRUMENT_DIRECTORY INFO" + "GET DB_INSTRUMENTS" + "LIST DB_INSTRUMENTS" + "GET DB_INSTRUMENT INFO" + "SET DB_INSTRUMENT_DIRECTORY NAME" + "SET DB_INSTRUMENT_DIRECTORY DESCRIPTION" + "SET DB_INSTRUMENT NAME" + "SET DB_INSTRUMENT DESCRIPTION" + "FIND DB_INSTRUMENTS" + "FIND DB_INSTRUMENT_DIRECTORIES" + "MOVE DB_INSTRUMENT" + "MOVE DB_INSTRUMENT_DIRECTORY" + "COPY DB_INSTRUMENT" + "COPY DB_INSTRUMENT_DIRECTORY" + + 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" + "GET ENGINE INFO" + "GET CHANNEL INFO" + "CREATE FX_SEND" + "GET FX_SEND INFO" + "SET FX_SEND NAME" + "GET MIDI_INSTRUMENT INFO" + "GET MIDI_INSTRUMENT_MAP INFO" + "ADD MIDI_INSTRUMENT_MAP" + "MAP MIDI_INSTRUMENT" + "SET MIDI_INSTRUMENT_MAP NAME" + "GET DB_INSTRUMENT_DIRECTORY INFO" + "SET DB_INSTRUMENT_DIRECTORY NAME" + "SET DB_INSTRUMENT_DIRECTORY DESCRIPTION" + "FIND DB_INSTRUMENT_DIRECTORIES" + "GET DB_INSTRUMENT INFO" + "SET DB_INSTRUMENT NAME" + "SET DB_INSTRUMENT DESCRIPTION" + "FIND DB_INSTRUMENTS" + + 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! +