/[svn]/linuxsampler/trunk/Documentation/lscp.xml

Diff of /linuxsampler/trunk/Documentation/lscp.xml

Parent Directory | Revision Log | View Patch Patch

-revision 1250 by schoenebeck,
Fri Jun 22 14:21:03 2007 UTC
+revision 1782 by iliev,
Tue Sep 30 02:16:41 2008 UTC
 Line 16
       to an annoying "missing Normative/Informative References" error message -->
  <?rfc strict="no" ?>
- <rfc category="std" ipr="full3978" docName="LSCP 1.2cvs">
+ <rfc category="std" ipr="full3978" docName="LSCP 1.4">
      <front>
-         <title>LinuxSampler Control Protocol (draft)</title>
+         <title>LinuxSampler Control Protocol</title>
          <author initials='C.S.' surname="Schoenebeck" fullname='C.
  Schoenebeck'>
              <organization>
 Line 34 
 Schoenebeck'>
                  <email>schoenebeck at software minus engineering dot org</email>
              </address>
          </author>
-         <date month="June" year="2007"/>
+         <date month="September" year="2008"/>
          <workgroup>LinuxSampler Developers</workgroup>
          <keyword>LSCP</keyword>
          <abstract>
 Line 2061 
 Schoenebeck'>
                      or <xref target="LIST MIDI_INPUT_DEVICES">"LIST MIDI_INPUT_DEVICES"</xref>
                      command, &lt;port&gt; by the MIDI port number, &lt;key&gt; by the name of
                      the parameter to change and &lt;value&gt; by the new value for this
-                     parameter.</t>
+                     parameter (encapsulated into apostrophes) or NONE (not encapsulated into apostrophes)
+                     for specifying no value for parameters allowing a list of values.</t>
                      <t>Possible Answers:</t>
                      <t>
-Line 2088 
 Schoenebeck'>
+Line 2089 
 Schoenebeck'>
                      <t>Example:</t>
                      <t>
                          <list>
-                             <t></t>
+                             <t>C: "SET MIDI_INPUT_PORT_PARAMETER 0 0 ALSA_SEQ_BINDINGS='20:0'"</t>
+                             <t>S: "OK"</t>
+                         </list>
+                     </t>
+                     <t>
+                         <list>
+                             <t>C: "SET MIDI_INPUT_PORT_PARAMETER 0 0 ALSA_SEQ_BINDINGS=NONE"</t>
+                             <t>S: "OK"</t>
                          </list>
                      </t>
                  </section>
-Line 2154 
 Schoenebeck'>
+Line 2162 
 Schoenebeck'>
                              </t>
                          </list>
                      </t>
-                     <t>Example:</t>
+                     <t>Example (Unix):</t>
                      <t>
                          <list>
-                             <t></t>
+                             <t>C: LOAD INSTRUMENT '/home/joe/gigs/cello.gig' 0 0</t>
+                             <t>S: OK</t>
+                         </list>
+                     </t>
+                     <t>Example (Windows):</t>
+                     <t>
+                         <list>
+                             <t>C: LOAD INSTRUMENT 'D:/MySounds/cello.gig' 0 0</t>
+                             <t>S: OK</t>
                          </list>
                      </t>
                  </section>
-Line 2435 
 Schoenebeck'>
+Line 2451 
 Schoenebeck'>
                                  <list>
                                      <t>DESCRIPTION -
                                          <list>
-                                             <t>arbitrary description text about the engine</t>
+                                             <t>arbitrary description text about the engine
+                                             (note that the character string may contain
+                                             <xref target="character_set">escape sequences</xref>)</t>
                                          </list>
                                      </t>
                                       <t>VERSION -
-Line 2519 
 Schoenebeck'>
+Line 2537 
 Schoenebeck'>
                                          <list>
                                              <t>the file name of the loaded instrument, "NONE" if
                                              there's no instrument yet loaded for this sampler
-                                             channel</t>
+                                             channel (note: since LSCP 1.2 this path may contain
+                                             <xref target="character_set">escape sequences</xref>)</t>
                                          </list>
                                      </t>
                                      <t>INSTRUMENT_NR -
-Line 2529 
 Schoenebeck'>
+Line 2548 
 Schoenebeck'>
                                      </t>
                                      <t>INSTRUMENT_NAME -
                                          <list>
-                                             <t>the instrument name of the loaded instrument</t>
+                                             <t>the instrument name of the loaded instrument
+                                             (note: since LSCP 1.2 this character string may contain
+                                             <xref target="character_set">escape sequences</xref>)</t>
                                          </list>
                                      </t>
                                      <t>INSTRUMENT_STATUS -
-Line 3247 
 Schoenebeck'>
+Line 3268 
 Schoenebeck'>
                      sampler channel on which the effect send should be created on, &lt;midi-ctrl&gt;
                      is a number between 0..127 defining the MIDI controller which can alter the
                      effect send level and &lt;name&gt; is an optional argument defining a name
-                     for the effect send entity. The name does not have to be unique.</t>
+                     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
+                     "<xref target="character_set">Character Set and Escape Sequences</xref>".</t>
                      <t>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
-Line 3437 
 Schoenebeck'>
+Line 3460 
 Schoenebeck'>
                                  <list>
                                      <t>NAME -
                                          <list>
-                                             <t>name of the effect send entity</t>
+                                             <t>name of the effect send entity
+                                             (note that this character string may contain
+                                              <xref target="character_set">escape sequences</xref>)</t>
                                          </list>
                                      </t>
                                      <t>MIDI_CONTROLLER -
-Line 3500 
 Schoenebeck'>
+Line 3525 
 Schoenebeck'>
                      as returned by the <xref target="CREATE FX_SEND">"CREATE FX_SEND"</xref>
                      or <xref target="LIST FX_SENDS">"LIST FX_SENDS"</xref> command and
                      &lt;name&gt; is the new name of the effect send entity, which
-                     does not have to be unique.</t>
+                     does not have to be unique (name MUST be encapsulated into apostrophes
+                     and supports escape sequences as described in chapter
+                     "<xref target="character_set">Character Set and Escape Sequences</xref>").
+                     </t>
                      <t>Possible Answers:</t>
                      <t>
-Line 3683 
 Schoenebeck'>
+Line 3711 
 Schoenebeck'>
                      </t>
                  </section>
+                 <section title="Sending MIDI messages to sampler channel" anchor="SEND CHANNEL MIDI_DATA">
+                     <t>The front-end can send MIDI events to specific sampler channel
+                     by sending the following command:</t>
+                     <t>
+                         <list>
+                             <t>SEND CHANNEL MIDI_DATA &lt;midi-msg&gt; &lt;sampler-chan&gt; &lt;arg1&gt; &lt;arg2&gt;</t>
+                         </list>
+                     </t>
+                     <t>Where &lt;sampler-chan&gt; is the sampler channel number
+                     as returned by the <xref target="ADD CHANNEL">"ADD CHANNEL"</xref>
+                     or <xref target="LIST CHANNELS">"LIST CHANNELS"</xref> command,
+                     &lt;arg1&gt; and &lt;arg2&gt; arguments depend on the &lt;midi-msg&gt; argument, which
+                     specifies the MIDI message type. Currently, the following MIDI messages are supported:</t>
+                     <t>
+                         <list>
+                             <t>"NOTE_ON" -
+                                 <list>
+                                     <t>For turning on MIDI notes, where &lt;arg1&gt;
+                                     specifies the key number and &lt;arg2&gt; the velocity
+                                     as described in the MIDI specification.</t>
+                                 </list>
+                             </t>
+                             <t>"NOTE_OFF" -
+                                 <list>
+                                     <t>For turning a currently playing MIDI note off, where &lt;arg1&gt;
+                                     specifies the key number and &lt;arg2&gt; the velocity
+                                     as described in the MIDI specification.</t>
+                                 </list>
+                             </t>
+                         </list>
+                     </t>
+                     <t>CAUTION: This command is provided for implementations of virtual MIDI keyboards
+                     and no realtime guarantee whatsoever will be made!</t>
+                     <t>Possible Answers:</t>
+                     <t>
+                         <list>
+                             <t>"OK" -
+                                 <list>
+                                     <t>on success</t>
+                                 </list>
+                             </t>
+                             <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
+                                 <list>
+                                     <t>in case it failed, providing an appropriate error code and error message</t>
+                                 </list>
+                             </t>
+                         </list>
+                     </t>
+                     <t>Example:</t>
+                     <t>
+                         <list>
+                             <t>C: "SEND CHANNEL MIDI_DATA NOTE_ON 0 56 112"</t>
+                             <t>S: "OK"</t>
+                         </list>
+                     </t>
+                 </section>
                  <section title="Resetting a sampler channel" anchor="RESET CHANNEL">
                      <t>The front-end can reset a particular sampler channel by sending the following command:</t>
                      <t>
-Line 3904 
 Schoenebeck'>
+Line 3989 
 Schoenebeck'>
                      </t>
                  </section>
+                 <section title="Current number of active disk streams" anchor="GET TOTAL_STREAM_COUNT">
+                     <t>The front-end can ask for the current number of active disk streams on
+                     the sampler by sending the following command:</t>
+                     <t>
+                         <list>
+                             <t>GET TOTAL_STREAM_COUNT</t>
+                         </list>
+                     </t>
+                     <t>Possible Answers:</t>
+                     <t>
+                         <list>
+                             <t>LinuxSampler will answer by returning the number of all active
+                             disk streams on the sampler.</t>
+                         </list>
+                     </t>
+                 </section>
                  <section title="Reset sampler" anchor="RESET">
                      <t>The front-end can reset the whole sampler by sending the following command:</t>
                      <t>
-Line 3951 
 Schoenebeck'>
+Line 4054 
 Schoenebeck'>
                                  <list>
                                      <t>DESCRIPTION -
                                          <list>
-                                             <t>arbitrary textual description about the sampler</t>
+                                             <t>arbitrary textual description about the sampler
+                                             (note that the character string may contain
+                                             <xref target="character_set">escape sequences</xref>)</t>
                                          </list>
                                      </t>
                                      <t>VERSION -
-Line 4067 
 Schoenebeck'>
+Line 4172 
 Schoenebeck'>
                  cause the sampler to switch to the respective instrument as
                  reflected by the current MIDI instrument map.</t>
-                 <section title="Create a new MIDI instrument map" anchor="ADD MIDI_INSTRUMENT MAP">
+                 <section title="Create a new MIDI instrument map" anchor="ADD MIDI_INSTRUMENT_MAP">
                      <t>The front-end can add a new MIDI instrument map by sending
                      the following command:</t>
                      <t>
-Line 4077 
 Schoenebeck'>
+Line 4182 
 Schoenebeck'>
                      </t>
                      <t>Where &lt;name&gt; is an optional argument allowing to
                      assign a custom name to the new map. MIDI instrument Map
-                     names do not have to be unique.</t>
+                     names do not have to be unique, but MUST be encapsulated
+                     into apostrophes and support escape sequences as described
+                     in chapter "<xref target="character_set">Character Set and Escape Sequences</xref>".
+                     </t>
                      <t>Possible Answers:</t>
                      <t>
-Line 4248 
 Schoenebeck'>
+Line 4356 
 Schoenebeck'>
                                      <t>NAME -
                                          <list>
                                              <t>custom name of the given map,
-                                             which does not have to be unique</t>
+                                             which does not have to be unique
+                                             (note that this character string may contain
+                                              <xref target="character_set">escape sequences</xref>)</t>
                                          </list>
                                      </t>
                                      <t>DEFAULT -
-Line 4284 
 Schoenebeck'>
+Line 4394 
 Schoenebeck'>
                      </t>
                      <t>Where &lt;map&gt; is the numerical ID of the map and
                      &lt;name&gt; the new custom name of the map, which does not
-                     have to be unique.</t>
+                     have to be unique (name MUST be encapsulated into apostrophes
+                     and supports escape sequences as described in chapter
+                     "<xref target="character_set">Character Set and Escape Sequences</xref>").
+                     </t>
                      <t>Possible Answers:</t>
                      <t>
-Line 4415 
 Schoenebeck'>
+Line 4528 
 Schoenebeck'>
                      load modes of entries, the frontend should retrieve the actual
                      mode by i.e. sending
                      <xref target="GET MIDI_INSTRUMENT INFO">"GET MIDI_INSTRUMENT INFO"</xref>
-                     command(s). Finally the OPTIONAL &lt;name&gt; argument allows to
+                     command(s). Finally the OPTIONAL &lt;name&gt; argument allows to set a custom name
-                     set a custom name (encapsulated into apostrophes) for the mapping
+                     (encapsulated into apostrophes, supporting escape sequences as described in chapter
-                     entry, useful for frontends for displaying an appropriate name for
+                     "<xref target="character_set">Character Set and Escape Sequences</xref>") for the
+                     mapping entry, useful for frontends for displaying an appropriate name for
                      mapped instruments (using
                      <xref target="GET MIDI_INSTRUMENT INFO">"GET MIDI_INSTRUMENT INFO"</xref>).
                      </t>
-Line 4641 
 Schoenebeck'>
+Line 4755 
 Schoenebeck'>
                                      name for this mapped instrument. It can be set and
                                      changed with the
                                      <xref target="MAP MIDI_INSTRUMENT">"MAP MIDI_INSTRUMENT"</xref>
-                                     command and does not have to be unique.</t>
+                                     command and does not have to be unique.
+                                     (note that this character string may contain
+                                     <xref target="character_set">escape sequences</xref>)</t>
                                  </list>
                              </t>
                              <t>"ENGINE_NAME" -
-Line 4652 
 Schoenebeck'>
+Line 4768 
 Schoenebeck'>
                              </t>
                              <t>"INSTRUMENT_FILE" -
                                  <list>
-                                     <t>File name of the instrument.</t>
+                                     <t>File name of the instrument
+                                     (note that this path may contain
+                                     <xref target="character_set">escape sequences</xref>).</t>
                                  </list>
                              </t>
                              <t>"INSTRUMENT_NR" -
-Line 4664 
 Schoenebeck'>
+Line 4782 
 Schoenebeck'>
                                  <list>
                                      <t>Name of the loaded instrument as reflected by its file.
                                      In contrast to the "NAME" field, the "INSTRUMENT_NAME" field
-                                     cannot be changed.</t>
+                                     cannot be changed (note that this character string may contain
+                                     <xref target="character_set">escape sequences</xref>).</t>
                                  </list>
                              </t>
                              <t>"LOAD_MODE" -
-Line 4752 
 Schoenebeck'>
+Line 4871 
 Schoenebeck'>
              <section title="Managing Instruments Database" anchor="Managing Instruments Database">
                  <t>The following commands describe how to use and manage
                  the instruments database.</t>
+                 <t>Notice:</t>
+                     <t>
+                         <list>
+                             <t>All command arguments representing a path or
+                             instrument/directory name support escape sequences as described in chapter
+                             "<xref target="character_set">Character Set and Escape Sequences</xref>".
+                             </t>
+                             <t>All occurrences of a forward slash in instrument and directory
+                                names are escaped with its hex (\x2f) or octal (\057) escape sequence.
+                             </t>
+                         </list>
+                     </t>
                  <section title="Creating a new instrument directory" anchor="ADD DB_INSTRUMENT_DIRECTORY">
                      <t>The front-end can add a new instrument directory to the
-Line 4929 
 Schoenebeck'>
+Line 5060 
 Schoenebeck'>
                                  <list>
                                      <t>DESCRIPTION -
                                          <list>
-                                             <t>A brief description of the directory content</t>
+                                             <t>A brief description of the directory content.
+                                             Note that the character string may contain
+                                             <xref target="character_set">escape sequences</xref>.</t>
                                          </list>
                                      </t>
                                      <t>CREATED -
-Line 5093 
 Schoenebeck'>
+Line 5226 
 Schoenebeck'>
                          </list>
                      </t>
                      <t>Where &lt;dir&gt; is the absolute path name of the directory and
-                     &lt;desc&gt; is the new description for the directory.</t>
+                     &lt;desc&gt; is the new description for the directory
+                     (encapsulated into apostrophes, supporting escape sequences as described in chapter
+                     "<xref target="character_set">Character Set and Escape Sequences</xref>").</t>
                      <t>Possible Answers:</t>
                      <t>
-Line 5138 
 Schoenebeck'>
+Line 5273 
 Schoenebeck'>
                        <t>NAME='&lt;search-string&gt;'
                            <list>
                                <t>Restricts the search to directories, which names
-                               satisfy the supplied search string.</t>
+                               satisfy the supplied search string (encapsulated into apostrophes,
+                               supporting escape sequences as described in chapter
+                               "<xref target="character_set">Character Set and Escape Sequences</xref>").</t>
                            </list>
                        </t>
-Line 5169 
 Schoenebeck'>
+Line 5306 
 Schoenebeck'>
                        <t>DESCRIPTION='&lt;search-string&gt;'
                            <list>
                                <t>Restricts the search to directories with description
-                               that satisfies the supplied search string.</t>
+                               that satisfies the supplied search string
+                               (encapsulated into apostrophes, supporting escape
+                               sequences as described in chapter
+                               "<xref target="character_set">Character Set and Escape Sequences</xref>").</t>
                            </list>
                        </t>
                      </t>
-Line 5210 
 Schoenebeck'>
+Line 5350 
 Schoenebeck'>
                      to the instruments database by sending the following command:</t>
                      <t>
                          <list>
-                             <t>ADD DB_INSTRUMENTS [NON_MODAL] [&lt;mode&gt;] &lt;db_dir&gt; &lt;file_path&gt; [&lt;instr_index&gt;]</t>
+                             <t>ADD DB_INSTRUMENTS [NON_MODAL] [&lt;mode&gt;[ FILE_AS_DIR]] &lt;db_dir&gt; &lt;file_path&gt; [&lt;instr_index&gt;]</t>
                          </list>
                      </t>
                      <t>Where &lt;db_dir&gt; is the absolute path name of a directory
-Line 5255 
 Schoenebeck'>
+Line 5395 
 Schoenebeck'>
                          </list>
                      </t>
+                  <t> If FILE_AS_DIR argument is supplied, all instruments in an instrument
+                  file will be added to a separate directory in the instruments database, which
+                  name will be the name of the instrument file with the file extension stripped off.
+                  </t>
                   <t>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.
-Line 5430 
 Schoenebeck'>
+Line 5574 
 Schoenebeck'>
                                  <list>
                                      <t>INSTRUMENT_FILE -
                                          <list>
-                                             <t>File name of the instrument.</t>
+                                             <t>File name of the instrument.
+                                             Note that the character string may contain
+                                             <xref target="character_set">escape sequences</xref>.</t>
                                          </list>
                                      </t>
                                      <t>INSTRUMENT_NR -
-Line 5469 
 Schoenebeck'>
+Line 5615 
 Schoenebeck'>
                                      </t>
                                      <t>DESCRIPTION -
                                          <list>
-                                             <t>A brief description of the instrument</t>
+                                             <t>A brief description of the instrument.
+                                             Note that the character string may contain
+                                             <xref target="character_set">escape sequences</xref>.</t>
                                          </list>
                                      </t>
                                      <t>IS_DRUM -
-Line 5480 
 Schoenebeck'>
+Line 5628 
 Schoenebeck'>
                                      </t>
                                      <t>PRODUCT -
                                          <list>
-                                             <t>The product title of the instrument</t>
+                                             <t>The product title of the instrument.
+                                             Note that the character string may contain
+                                             <xref target="character_set">escape sequences</xref>.</t>
                                          </list>
                                      </t>
                                      <t>ARTISTS -
                                          <list>
-                                             <t>Lists the artist names</t>
+                                             <t>Lists the artist names.
+                                             Note that the character string may contain
+                                             <xref target="character_set">escape sequences</xref>.</t>
                                          </list>
                                      </t>
                                      <t>KEYWORDS -
                                          <list>
                                              <t>Provides a list of keywords that refer to the instrument.
-                                             Keywords are separated with semicolon and blank.</t>
+                                             Keywords are separated with semicolon and blank.
+                                             Note that the character string may contain
+                                             <xref target="character_set">escape sequences</xref>.</t>
                                          </list>
                                      </t>
                                  </list>
-Line 5648 
 Schoenebeck'>
+Line 5802 
 Schoenebeck'>
                          </list>
                      </t>
                      <t>Where &lt;instr&gt; is the absolute path name of the instrument and
-                     &lt;desc&gt; is the new description for the instrument.</t>
+                     &lt;desc&gt; is the new description for the instrument
+                     (encapsulated into apostrophes, supporting escape sequences as described in chapter
+                     "<xref target="character_set">Character Set and Escape Sequences</xref>").</t>
                      <t>Possible Answers:</t>
                      <t>
-Line 5693 
 Schoenebeck'>
+Line 5849 
 Schoenebeck'>
                        <t>NAME='&lt;search-string&gt;'
                            <list>
                                <t>Restricts the search to instruments, which names
-                               satisfy the supplied search string.</t>
+                               satisfy the supplied search string (encapsulated into apostrophes,
+                               supporting escape sequences as described in chapter
+                               "<xref target="character_set">Character Set and Escape Sequences</xref>").</t>
                            </list>
                        </t>
-Line 5735 
 Schoenebeck'>
+Line 5893 
 Schoenebeck'>
                        <t>DESCRIPTION='&lt;search-string&gt;'
                            <list>
                                <t>Restricts the search to instruments with description
-                               that satisfies the supplied search string.</t>
+                               that satisfies the supplied search string (encapsulated into apostrophes,
+                               supporting escape sequences as described in chapter
+                               "<xref target="character_set">Character Set and Escape Sequences</xref>").</t>
                            </list>
                        </t>
                        <t>PRODUCT='&lt;search-string&gt;'
                            <list>
                                <t>Restricts the search to instruments with product info
-                               that satisfies the supplied search string.</t>
+                               that satisfies the supplied search string (encapsulated into apostrophes,
+                               supporting escape sequences as described in chapter
+                               "<xref target="character_set">Character Set and Escape Sequences</xref>").</t>
                            </list>
                        </t>
                        <t>ARTISTS='&lt;search-string&gt;'
                            <list>
                                <t>Restricts the search to instruments with artists info
-                               that satisfies the supplied search string.</t>
+                               that satisfies the supplied search string (encapsulated into apostrophes,
+                               supporting escape sequences as described in chapter
+                               "<xref target="character_set">Character Set and Escape Sequences</xref>").</t>
                            </list>
                        </t>
                        <t>KEYWORDS='&lt;search-string&gt;'
                            <list>
                                <t>Restricts the search to instruments with keyword list
-                               that satisfies the supplied search string.</t>
+                               that satisfies the supplied search string (encapsulated into apostrophes,
+                               supporting escape sequences as described in chapter
+                               "<xref target="character_set">Character Set and Escape Sequences</xref>").</t>
                            </list>
                        </t>
-Line 5870 
 Schoenebeck'>
+Line 6036 
 Schoenebeck'>
                      </t>
                  </section>
+                 <section title="Formatting the instruments database" anchor="FORMAT INSTRUMENTS_DB">
+                     <t>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:</t>
+                     <t>
+                         <list>
+                             <t>FORMAT INSTRUMENTS_DB</t>
+                         </list>
+                     </t>
+                     <t>Possible Answers:</t>
+                     <t>
+                         <list>
+                             <t>"OK" -
+                                 <list>
+                                     <t>on success</t>
+                                 </list>
+                             </t>
+                             <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
+                                 <list>
+                                     <t>If the formatting of the instruments database
+                                     failed.</t>
+                                 </list>
+                             </t>
+                         </list>
+                     </t>
+                 </section>
+                 <section title="Checking for lost instrument files" anchor="FIND LOST DB_INSTRUMENT_FILES">
+                     <t>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:</t>
+                     <t>
+                         <list>
+                             <t>FIND LOST DB_INSTRUMENT_FILES</t>
+                         </list>
+                     </t>
+                     <t>Possible Answers:</t>
+                     <t>
+                         <list>
+                             <t>A comma separated list with the absolute path names
+                             (encapsulated into apostrophes) of all lost instrument files.</t>
+                             <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
+                                 <list>
+                                     <t>in case it failed, providing an appropriate error code and error message.</t>
+                                 </list>
+                             </t>
+                         </list>
+                     </t>
+                     <t>Example:</t>
+                     <t>
+                         <list>
+                             <t>C: "FIND LOST DB_INSTRUMENT_FILES"</t>
+                             <t>S: "'/gigs/Bosendorfer 290.gig','/gigs/Steinway D.gig','/gigs/Free Piano.gig'"</t>
+                         </list>
+                     </t>
+                 </section>
+                 <section title="Replacing an instrument file" anchor="SET DB_INSTRUMENT FILE_PATH">
+                     <t>The front-end can substitute all occurrences of an instrument file
+                     in the instruments database with a new one by sending the following command:</t>
+                     <t>
+                         <list>
+                             <t>SET DB_INSTRUMENT FILE_PATH &lt;old_path&gt; &lt;new_path&gt;</t>
+                         </list>
+                     </t>
+                     <t>Where &lt;old_path&gt; is the absolute path name of the instrument file
+                     to substitute with &lt;new_path&gt;.</t>
+                     <t>Possible Answers:</t>
+                     <t>
+                         <list>
+                             <t>"OK" -
+                                 <list>
+                                     <t>on success</t>
+                                 </list>
+                             </t>
+                             <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
+                                 <list>
+                                     <t>in case it failed, providing an appropriate error code and error message.</t>
+                                 </list>
+                             </t>
+                         </list>
+                     </t>
+                     <t>Example:</t>
+                     <t>
+                         <list>
+                             <t>C: "SET DB_INSTRUMENT FILE_PATH '/gigs/Bosendorfer 290.gig' '/gigs/pianos/Bosendorfer 290.gig'"</t>
+                             <t>S: "OK"</t>
+                         </list>
+                     </t>
+                 </section>
              </section>
-         </section>
+             <section title="Editing Instruments" anchor="editing_instruments">
+                 <t>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!</t>
+                 <t>At the moment there is only one command for this feature set,
+                 but this will most probably change in future.</t>
+                 <section title="Opening an appropriate instrument editor application" anchor="EDIT INSTRUMENT">
+                     <t>The front-end can request to open an appropriate instrument
+                     editor application by sending the following command:</t>
+                     <t>
+                         <list>
+                             <t>EDIT CHANNEL INSTRUMENT &lt;sampler-channel&gt;</t>
+                         </list>
+                     </t>
+                     <t>Where &lt;sampler-channel&gt; should be replaced by the
+                     number of the sampler channel as given by the
+                     <xref target="ADD CHANNEL">"ADD CHANNEL"</xref>
+                     or <xref target="LIST CHANNELS">"LIST CHANNELS"</xref>
+                     command.</t>
+                     <t>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.</t>
+                     <t>Note: consequently instrument editors are always spawned
+                     locally on the same machine where the sampler is running
+                     on!</t>
+                     <t>Possible Answers:</t>
+                     <t>
+                         <list>
+                             <t>"OK" -
+                                 <list>
+                                     <t>when an appropriate instrument editor was
+                                     launched</t>
+                                 </list>
+                             </t>
+                             <t>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
+                                 <list>
+                                     <t>when an appropriate instrument editor was
+                                     launched, but there are noteworthy issues</t>
+                                 </list>
+                             </t>
+                             <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
+                                 <list>
+                                     <t>when an appropriate instrument editor
+                                     could not be launched</t>
+                                 </list>
+                             </t>
+                         </list>
+                     </t>
+                     <t>Examples:</t>
+                     <t>
+                         <list>
+                             <t>C: "EDIT CHANNEL INSTRUMENT 0"</t>
+                             <t>S: "OK"</t>
+                         </list>
+                     </t>
+                 </section>
+             </section>
+             <section title="Managing Files" anchor="file_management">
+                 <t>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.</t>
+                 <section title="Retrieving amount of instruments of a file" anchor="GET FILE INSTRUMENTS">
+                     <t>The front-end can retrieve the amount of instruments
+                     within a given instrument file by sending the
+                     following command:</t>
+                     <t>
+                         <list>
+                             <t>GET FILE INSTRUMENTS &lt;filename&gt;</t>
+                         </list>
+                     </t>
+                     <t>Where &lt;filename&gt; is the name of the instrument
+                     file (encapsulated into apostrophes, supporting escape
+                     sequences as described in chapter
+                     "<xref target="character_set">Character Set and Escape
+                         Sequences</xref>").</t>
+                     <t>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.</t>
+                     <t>Possible Answers:</t>
+                     <t>
+                         <list>
+                             <t>On success, the sampler will answer by
+                                returning the amount of instruments.
+                             </t>
+                             <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
+                                 <list>
+                                     <t>if the file could not be handled</t>
+                                 </list>
+                             </t>
+                         </list>
+                     </t>
+                     <t>Examples:</t>
+                     <t>
+                         <list>
+                             <t>C: "GET FILE INSTRUMENTS 'D:/Sounds/Foo.gig'"</t>
+                             <t>S: "10"</t>
+                         </list>
+                     </t>
+                 </section>
+                 <section title="Retrieving all instruments of a file" anchor="LIST FILE INSTRUMENTS">
+                     <t>The front-end can retrieve a list of all instruments
+                     within a given instrument file by sending the
+                     following command:</t>
+                     <t>
+                         <list>
+                             <t>LIST FILE INSTRUMENTS &lt;filename&gt;</t>
+                         </list>
+                     </t>
+                     <t>Where &lt;filename&gt; is the name of the instrument
+                     file (encapsulated into apostrophes, supporting escape
+                     sequences as described in chapter
+                     "<xref target="character_set">Character Set and Escape
+                         Sequences</xref>").</t>
+                     <t>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.</t>
+                     <t>Possible Answers:</t>
+                     <t>
+                         <list>
+                             <t>On success, the sampler will answer by
+                                returning a comma separated list of
+                                instrument IDs.
+                             </t>
+                             <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
+                                 <list>
+                                     <t>if the file could not be handled</t>
+                                 </list>
+                             </t>
+                         </list>
+                     </t>
+                     <t>Examples:</t>
+                     <t>
+                         <list>
+                             <t>C: "LIST FILE INSTRUMENTS 'D:/Sounds/Foo.gig'"</t>
+                             <t>S: "0,1,2,3,4,5,6,7,8,9"</t>
+                         </list>
+                     </t>
+                 </section>
+                 <section title="Retrieving informations about one instrument in a file" anchor="GET FILE INSTRUMENT INFO">
+                     <t>The front-end can retrieve detailed informations
+                     about a specific instrument within a given instrument
+                     file by sending the following command:</t>
+                     <t>
+                         <list>
+                             <t>GET FILE INSTRUMENT INFO &lt;filename&gt;
+                             &lt;instr-id&gt;</t>
+                         </list>
+                     </t>
+                     <t>Where &lt;filename&gt; is the name of the instrument
+                     file (encapsulated into apostrophes, supporting escape
+                     sequences as described in chapter
+                     "<xref target="character_set">Character Set and Escape
+                         Sequences</xref>") and &lt;instr-id&gt; is the numeric
+                     instrument ID as returned by the
+                     <xref target="LIST FILE INSTRUMENTS">
+                     "LIST FILE INSTRUMENTS"</xref> command.</t>
+                     <t>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.</t>
+                     <t>Possible Answers:</t>
+                     <t>
+                         <list>
+                             <t>LinuxSampler will answer by sending a &lt;CRLF&gt; separated list.
+                             Each answer line begins with the settings category name
+                             followed by a colon and then a space character &lt;SP&gt; and finally
+                             the info character string to that setting category. At the
+                             moment the following categories are defined:</t>
+                             <t>
+                                 <list>
+                                     <t>NAME -
+                                         <list>
+                                             <t>name of the instrument as
+                                             stored in the instrument file</t>
+                                         </list>
+                                     </t>
+                                     <t>FORMAT_FAMILY -
+                                         <list>
+                                             <t>name of the sampler format
+                                             of the given instrument</t>
+                                         </list>
+                                     </t>
+                                     <t>FORMAT_VERSION -
+                                         <list>
+                                             <t>version of the sampler format
+                                             the instrumen is stored as</t>
+                                         </list>
+                                     </t>
+                                     <t>PRODUCT -
+                                         <list>
+                                             <t>official product name of the
+                                             instrument as stored in the file
+                                             </t>
+                                         </list>
+                                     </t>
+                                     <t>ARTISTS -
+                                         <list>
+                                             <t>artists / sample library
+                                             vendor of the instrument</t>
+                                         </list>
+                                     </t>
+                                     <t>KEY_BINDINGS -
+                                         <list>
+                                             <t>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.</t>
+                                         </list>
+                                     </t>
+                                     <t>KEYSWITCH_BINDINGS -
+                                         <list>
+                                             <t>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.</t>
+                                         </list>
+                                     </t>
+                                 </list>
+                             </t>
+                         </list>
+                     </t>
+                     <t>The mentioned fields above don't have to be in particular order.</t>
+                     <t>Example:</t>
+                     <t>
+                         <list>
+                             <t>C: "GET FILE INSTRUMENT INFO 'D:/Sounds/Foo.gig' 0"</t>
+                             <t>S: "NAME: Lunatic Loops"</t>
+                             <t>&nbsp;&nbsp;&nbsp;"FORMAT_FAMILY: GIG"</t>
+                             <t>&nbsp;&nbsp;&nbsp;"FORMAT_VERSION: 3"</t>
+                             <t>&nbsp;&nbsp;&nbsp;"PRODUCT: The Backbone Bongo Beats"</t>
+                             <t>&nbsp;&nbsp;&nbsp;"ARTISTS: Jimmy the Fish"</t>
+                             <t>&nbsp;&nbsp;&nbsp;"."</t>
+                         </list>
+                     </t>
+                 </section>
+             </section>
+         </section>
          <section title="Command Syntax" anchor="command_syntax">
              <t>The grammar of the control protocol as descibed in <xref target="control_commands"/>
              is defined below using Backus-Naur Form (BNF as described in <xref target="RFC2234"/>)
-Line 5959 
 Schoenebeck'>
+Line 6488 
 Schoenebeck'>
                  </t>
                  <t>/ EDIT SP edit_instruction
                  </t>
+                 <t>/ FORMAT SP format_instruction
+                 </t>
+                 <t>/ SEND SP send_instruction
+                 </t>
                  <t>/ RESET
                  </t>
                  <t>/ QUIT
-Line 5969 
 Schoenebeck'>
+Line 6502 
 Schoenebeck'>
          <list>
                  <t>CHANNEL
                  </t>
-                 <t>/ DB_INSTRUMENT_DIRECTORY SP pathname
+                 <t>/ DB_INSTRUMENT_DIRECTORY SP db_path
+                 </t>
+                 <t>/ DB_INSTRUMENTS SP NON_MODAL SP scan_mode SP db_path SP filename
                  </t>
-                 <t>/ DB_INSTRUMENTS SP NON_MODAL SP scan_mode SP pathname SP pathname
+                 <t>/ DB_INSTRUMENTS SP NON_MODAL SP scan_mode SP FILE_AS_DIR SP db_path SP filename
                  </t>
-                 <t>/ DB_INSTRUMENTS SP scan_mode SP pathname SP pathname
+                 <t>/ DB_INSTRUMENTS SP scan_mode SP db_path SP filename
                  </t>
-                 <t>/ DB_INSTRUMENTS SP NON_MODAL SP pathname SP pathname
+                 <t>/ DB_INSTRUMENTS SP scan_mode SP FILE_AS_DIR SP db_path SP filename
                  </t>
-                 <t>/ DB_INSTRUMENTS SP NON_MODAL SP pathname SP pathname SP instrument_index
+                 <t>/ DB_INSTRUMENTS SP NON_MODAL SP db_path SP filename
                  </t>
-                 <t>/ DB_INSTRUMENTS SP pathname SP pathname
+                 <t>/ DB_INSTRUMENTS SP NON_MODAL SP db_path SP filename SP instrument_index
                  </t>
-                 <t>/ DB_INSTRUMENTS SP pathname SP pathname SP instrument_index
+                 <t>/ DB_INSTRUMENTS SP db_path SP filename
+                 </t>
+                 <t>/ DB_INSTRUMENTS SP db_path SP filename SP instrument_index
                  </t>
                  <t>/ MIDI_INSTRUMENT_MAP
                  </t>
-Line 6001 
 Schoenebeck'>
+Line 6538 
 Schoenebeck'>
                  </t>
                  <t>/ CHANNEL_COUNT
                  </t>
+                 <t>/ CHANNEL_MIDI
+                 </t>
+                 <t>/ DEVICE_MIDI
+                 </t>
                  <t>/ VOICE_COUNT
                  </t>
                  <t>/ STREAM_COUNT
-Line 6033 
 Schoenebeck'>
+Line 6574 
 Schoenebeck'>
                  </t>
                  <t>/ MISCELLANEOUS
                  </t>
+                 <t>/ TOTAL_STREAM_COUNT
+                 </t>
                  <t>/ TOTAL_VOICE_COUNT
                  </t>
                  <t>/ GLOBAL_INFO
-Line 6051 
 Schoenebeck'>
+Line 6594 
 Schoenebeck'>
                  </t>
                  <t>/ CHANNEL_COUNT
                  </t>
+                 <t>/ CHANNEL_MIDI
+                 </t>
+                 <t>/ DEVICE_MIDI
+                 </t>
                  <t>/ VOICE_COUNT
                  </t>
                  <t>/ STREAM_COUNT
-Line 6083 
 Schoenebeck'>
+Line 6630 
 Schoenebeck'>
                  </t>
                  <t>/ MISCELLANEOUS
                  </t>
+                 <t>/ TOTAL_STREAM_COUNT
+                 </t>
                  <t>/ TOTAL_VOICE_COUNT
                  </t>
                  <t>/ GLOBAL_INFO
-Line 6115 
 Schoenebeck'>
+Line 6664 
 Schoenebeck'>
                  </t>
                  <t>/ MIDI_INSTRUMENT_MAP SP ALL
                  </t>
-                 <t>/ DB_INSTRUMENT_DIRECTORY SP FORCE SP pathname
+                 <t>/ DB_INSTRUMENT_DIRECTORY SP FORCE SP db_path
                  </t>
-                 <t>/ DB_INSTRUMENT_DIRECTORY SP pathname
+                 <t>/ DB_INSTRUMENT_DIRECTORY SP db_path
                  </t>
-                 <t>/ DB_INSTRUMENT SP pathname
+                 <t>/ DB_INSTRUMENT SP db_path
                  </t>
          </list>
  </t>
-Line 6173 
 Schoenebeck'>
+Line 6722 
 Schoenebeck'>
                  </t>
                  <t>/ SERVER SP INFO
                  </t>
+                 <t>/ TOTAL_STREAM_COUNT
+                 </t>
                  <t>/ TOTAL_VOICE_COUNT
                  </t>
                  <t>/ TOTAL_VOICE_COUNT_MAX
-Line 6191 
 Schoenebeck'>
+Line 6742 
 Schoenebeck'>
                  </t>
                  <t>/ FX_SEND SP INFO SP sampler_channel SP fx_send_id
                  </t>
-                 <t>/ DB_INSTRUMENT_DIRECTORIES SP RECURSIVE SP pathname
+                 <t>/ DB_INSTRUMENT_DIRECTORIES SP RECURSIVE SP db_path
                  </t>
-                 <t>/ DB_INSTRUMENT_DIRECTORIES SP pathname
+                 <t>/ DB_INSTRUMENT_DIRECTORIES SP db_path
                  </t>
-                 <t>/ DB_INSTRUMENT_DIRECTORY SP INFO SP pathname
+                 <t>/ DB_INSTRUMENT_DIRECTORY SP INFO SP db_path
                  </t>
-                 <t>/ DB_INSTRUMENTS SP RECURSIVE SP pathname
+                 <t>/ DB_INSTRUMENTS SP RECURSIVE SP db_path
                  </t>
-                 <t>/ DB_INSTRUMENTS SP pathname
+                 <t>/ DB_INSTRUMENTS SP db_path
                  </t>
-                 <t>/ DB_INSTRUMENT SP INFO SP pathname
+                 <t>/ DB_INSTRUMENT SP INFO SP db_path
                  </t>
                  <t>/ DB_INSTRUMENTS_JOB SP INFO SP number
                  </t>
                  <t>/ VOLUME
                  </t>
+                 <t>/ FILE SP INSTRUMENTS SP filename
+                 </t>
+                 <t>/ FILE SP INSTRUMENT SP INFO SP filename SP instrument_index
+                 </t>
          </list>
  </t>
  <t>set_instruction =
-Line 6217 
 Schoenebeck'>
+Line 6772 
 Schoenebeck'>
                  </t>
                  <t>/ MIDI_INPUT_DEVICE_PARAMETER SP number SP string '=' param_val_list
                  </t>
+                 <t>/ MIDI_INPUT_PORT_PARAMETER SP number SP number SP string '=' NONE
+                 </t>
                  <t>/ MIDI_INPUT_PORT_PARAMETER SP number SP number SP string '=' param_val_list
                  </t>
                  <t>/ CHANNEL SP set_chan_instruction
-Line 6231 
 Schoenebeck'>
+Line 6788 
 Schoenebeck'>
                  </t>
                  <t>/ FX_SEND SP LEVEL SP sampler_channel SP fx_send_id SP volume_value
                  </t>
-                 <t>/ DB_INSTRUMENT_DIRECTORY SP NAME SP pathname SP dirname
+                 <t>/ DB_INSTRUMENT_DIRECTORY SP NAME SP db_path SP stringval_escaped
+                 </t>
+                 <t>/ DB_INSTRUMENT_DIRECTORY SP DESCRIPTION SP db_path SP stringval_escaped
                  </t>
-                 <t>/ DB_INSTRUMENT_DIRECTORY SP DESCRIPTION SP pathname SP stringval
+                 <t>/ DB_INSTRUMENT SP NAME SP db_path SP stringval_escaped
                  </t>
-                 <t>/ DB_INSTRUMENT SP NAME SP pathname SP dirname
+                 <t>/ DB_INSTRUMENT SP DESCRIPTION SP db_path SP stringval_escaped
                  </t>
-                 <t>/ DB_INSTRUMENT SP DESCRIPTION SP pathname SP stringval
+                 <t>/ DB_INSTRUMENT SP FILE_PATH SP filename SP filename
                  </t>
                  <t>/ ECHO SP boolean
                  </t>
-Line 6277 
 Schoenebeck'>
+Line 6836 
 Schoenebeck'>
  </t>
  <t>find_instruction =
          <list>
-                 <t>DB_INSTRUMENTS SP NON_RECURSIVE SP pathname SP query_val_list
+                 <t>DB_INSTRUMENTS SP NON_RECURSIVE SP db_path SP query_val_list
                  </t>
-                 <t>/ DB_INSTRUMENTS SP pathname SP query_val_list
+                 <t>/ DB_INSTRUMENTS SP db_path SP query_val_list
                  </t>
-                 <t>/ DB_INSTRUMENT_DIRECTORIES SP NON_RECURSIVE SP pathname SP query_val_list
+                 <t>/ DB_INSTRUMENT_DIRECTORIES SP NON_RECURSIVE SP db_path SP query_val_list
                  </t>
-                 <t>/ DB_INSTRUMENT_DIRECTORIES SP pathname SP query_val_list
+                 <t>/ DB_INSTRUMENT_DIRECTORIES SP db_path SP query_val_list
+                 </t>
+                 <t>/ LOST SP DB_INSTRUMENT_FILES
                  </t>
          </list>
  </t>
  <t>move_instruction =
          <list>
-                 <t>DB_INSTRUMENT_DIRECTORY SP pathname SP pathname
+                 <t>DB_INSTRUMENT_DIRECTORY SP db_path SP db_path
                  </t>
-                 <t>/ DB_INSTRUMENT SP pathname SP pathname
+                 <t>/ DB_INSTRUMENT SP db_path SP db_path
                  </t>
          </list>
  </t>
  <t>copy_instruction =
          <list>
-                 <t>DB_INSTRUMENT_DIRECTORY SP pathname SP pathname
+                 <t>DB_INSTRUMENT_DIRECTORY SP db_path SP db_path
                  </t>
-                 <t>/ DB_INSTRUMENT SP pathname SP pathname
+                 <t>/ DB_INSTRUMENT SP db_path SP db_path
                  </t>
          </list>
  </t>
-Line 6355 
 Schoenebeck'>
+Line 6916 
 Schoenebeck'>
  </t>
  <t>edit_instruction =
          <list>
-                 <t>INSTRUMENT SP sampler_channel
+                 <t>CHANNEL SP INSTRUMENT SP sampler_channel
+                 </t>
+         </list>
+ </t>
+ <t>format_instruction =
+         <list>
+                 <t>INSTRUMENTS_DB
                  </t>
          </list>
  </t>
-Line 6405 
 Schoenebeck'>
+Line 6972 
 Schoenebeck'>
                  </t>
                  <t>/ FX_SENDS SP sampler_channel
                  </t>
-                 <t>/ DB_INSTRUMENT_DIRECTORIES SP RECURSIVE SP pathname
+                 <t>/ DB_INSTRUMENT_DIRECTORIES SP RECURSIVE SP db_path
+                 </t>
+                 <t>/ DB_INSTRUMENT_DIRECTORIES SP db_path
                  </t>
-                 <t>/ DB_INSTRUMENT_DIRECTORIES SP pathname
+                 <t>/ DB_INSTRUMENTS SP RECURSIVE SP db_path
                  </t>
-                 <t>/ DB_INSTRUMENTS SP RECURSIVE SP pathname
+                 <t>/ DB_INSTRUMENTS SP db_path
                  </t>
-                 <t>/ DB_INSTRUMENTS SP pathname
+                 <t>/ FILE SP INSTRUMENTS SP filename
+                 </t>
+         </list>
+ </t>
+ <t>send_instruction =
+         <list>
+                 <t>CHANNEL SP MIDI_DATA SP string SP sampler_channel SP number SP number
                  </t>
          </list>
  </t>
-Line 6533 
 Schoenebeck'>
+Line 7108 
 Schoenebeck'>
                  </t>
          </list>
  </t>
- <t>pathname =
+ <t>filename =
-         <list>
-                 <t>stringval
-                 </t>
-         </list>
- </t>
- <t>dirname =
          <list>
-                 <t>stringval
+                 <t>path
                  </t>
          </list>
  </t>
- <t>filename =
+ <t>db_path =
          <list>
-                 <t>stringval_escaped
+                 <t>path
                  </t>
          </list>
  </t>
  <t>map_name =
          <list>
-                 <t>stringval
+                 <t>stringval_escaped
                  </t>
          </list>
  </t>
  <t>entry_name =
          <list>
-                 <t>stringval
+                 <t>stringval_escaped
                  </t>
          </list>
  </t>
  <t>fx_send_name =
          <list>
-                 <t>stringval
+                 <t>stringval_escaped
                  </t>
          </list>
  </t>
-Line 6577 
 Schoenebeck'>
+Line 7146 
 Schoenebeck'>
                  </t>
          </list>
  </t>
  <t>param_val =
          <list>
                  <t>string
-Line 6599 
 Schoenebeck'>
+Line 7169 
 Schoenebeck'>
  </t>
  <t>query_val =
          <list>
-                 <t>string
+                 <t>text_escaped
                  </t>
-                 <t>/ stringval
+                 <t>/ stringval_escaped
                  </t>
          </list>
  </t>
-Line 6648 
 Schoenebeck'>
+Line 7218 
 Schoenebeck'>
                  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.</t>
+                 <t>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:
+                 <list>
+                     <t><xref target="LOAD INSTRUMENT">"LOAD INSTRUMENT"</xref></t>
+                     <t><xref target="GET CHANNEL INFO">"GET CHANNEL INFO"</xref></t>
+                     <t><xref target="MAP MIDI_INSTRUMENT">"MAP MIDI_INSTRUMENT"</xref></t>
+                     <t><xref target="GET MIDI_INSTRUMENT INFO">"GET MIDI_INSTRUMENT INFO"</xref></t>
+                     <t><xref target="ADD DB_INSTRUMENT_DIRECTORY">"ADD DB_INSTRUMENT_DIRECTORY"</xref></t>
+                     <t><xref target="ADD DB_INSTRUMENTS">"ADD DB_INSTRUMENTS"</xref></t>
+                     <t><xref target="REMOVE DB_INSTRUMENT_DIRECTORY">"REMOVE DB_INSTRUMENT_DIRECTORY"</xref></t>
+                     <t><xref target="REMOVE DB_INSTRUMENT">"REMOVE DB_INSTRUMENT"</xref></t>
+                     <t><xref target="GET DB_INSTRUMENT_DIRECTORIES">"GET DB_INSTRUMENT_DIRECTORIES"</xref></t>
+                     <t><xref target="LIST DB_INSTRUMENT_DIRECTORIES">"LIST DB_INSTRUMENT_DIRECTORIES"</xref></t>
+                     <t><xref target="GET DB_INSTRUMENT_DIRECTORY INFO">"GET DB_INSTRUMENT_DIRECTORY INFO"</xref></t>
+                     <t><xref target="GET DB_INSTRUMENTS">"GET DB_INSTRUMENTS"</xref></t>
+                     <t><xref target="LIST DB_INSTRUMENTS">"LIST DB_INSTRUMENTS"</xref></t>
+                     <t><xref target="GET DB_INSTRUMENT INFO">"GET DB_INSTRUMENT INFO"</xref></t>
+                     <t><xref target="SET DB_INSTRUMENT_DIRECTORY NAME">"SET DB_INSTRUMENT_DIRECTORY NAME"</xref></t>
+                     <t><xref target="SET DB_INSTRUMENT_DIRECTORY DESCRIPTION">"SET DB_INSTRUMENT_DIRECTORY DESCRIPTION"</xref></t>
+                     <t><xref target="SET DB_INSTRUMENT NAME">"SET DB_INSTRUMENT NAME"</xref></t>
+                     <t><xref target="SET DB_INSTRUMENT DESCRIPTION">"SET DB_INSTRUMENT DESCRIPTION"</xref></t>
+                     <t><xref target="FIND DB_INSTRUMENTS">"FIND DB_INSTRUMENTS"</xref></t>
+                     <t><xref target="FIND DB_INSTRUMENT_DIRECTORIES">"FIND DB_INSTRUMENT_DIRECTORIES"</xref></t>
+                     <t><xref target="MOVE DB_INSTRUMENT">"MOVE DB_INSTRUMENT"</xref></t>
+                     <t><xref target="MOVE DB_INSTRUMENT_DIRECTORY">"MOVE DB_INSTRUMENT_DIRECTORY"</xref></t>
+                     <t><xref target="COPY DB_INSTRUMENT">"COPY DB_INSTRUMENT"</xref></t>
+                     <t><xref target="COPY DB_INSTRUMENT_DIRECTORY">"COPY DB_INSTRUMENT_DIRECTORY"</xref></t>
+                     <t><xref target="FIND LOST DB_INSTRUMENT_FILES">"FIND LOST DB_INSTRUMENT_FILES"</xref></t>
+                     <t><xref target="SET DB_INSTRUMENT FILE_PATH">"SET DB_INSTRUMENT FILE_PATH"</xref></t>
+                     <t><xref target="GET FILE INSTRUMENTS">"GET FILE INSTRUMENTS"</xref></t>
+                     <t><xref target="LIST FILE INSTRUMENTS">"LIST FILE INSTRUMENTS"</xref></t>
+                     <t><xref target="GET FILE INSTRUMENT INFO">"GET FILE INSTRUMENT INFO"</xref></t>
+                 </list>
+                 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").
+                 </t>
+                 <t>
+                 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".
+                 </t>
+                 <t>
+                 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:
+                 <list>
+                     <t><xref target="GET SERVER INFO">"GET SERVER INFO"</xref></t>
+                     <t><xref target="GET ENGINE INFO">"GET ENGINE INFO"</xref></t>
+                     <t><xref target="GET CHANNEL INFO">"GET CHANNEL INFO"</xref></t>
+                     <t><xref target="CREATE FX_SEND">"CREATE FX_SEND"</xref></t>
+                     <t><xref target="GET FX_SEND INFO">"GET FX_SEND INFO"</xref></t>
+                     <t><xref target="SET FX_SEND NAME">"SET FX_SEND NAME"</xref></t>
+                     <t><xref target="GET MIDI_INSTRUMENT INFO">"GET MIDI_INSTRUMENT INFO"</xref></t>
+                     <t><xref target="GET MIDI_INSTRUMENT_MAP INFO">"GET MIDI_INSTRUMENT_MAP INFO"</xref></t>
+                     <t><xref target="ADD MIDI_INSTRUMENT_MAP">"ADD MIDI_INSTRUMENT_MAP"</xref></t>
+                     <t><xref target="MAP MIDI_INSTRUMENT">"MAP MIDI_INSTRUMENT"</xref></t>
+                     <t><xref target="SET MIDI_INSTRUMENT_MAP NAME">"SET MIDI_INSTRUMENT_MAP NAME"</xref></t>
+                     <t><xref target="GET DB_INSTRUMENT_DIRECTORY INFO">"GET DB_INSTRUMENT_DIRECTORY INFO"</xref></t>
+                     <t><xref target="SET DB_INSTRUMENT_DIRECTORY NAME">"SET DB_INSTRUMENT_DIRECTORY NAME"</xref></t>
+                     <t><xref target="SET DB_INSTRUMENT_DIRECTORY DESCRIPTION">"SET DB_INSTRUMENT_DIRECTORY DESCRIPTION"</xref></t>
+                     <t><xref target="FIND DB_INSTRUMENT_DIRECTORIES">"FIND DB_INSTRUMENT_DIRECTORIES"</xref></t>
+                     <t><xref target="GET DB_INSTRUMENT INFO">"GET DB_INSTRUMENT INFO"</xref></t>
+                     <t><xref target="SET DB_INSTRUMENT NAME">"SET DB_INSTRUMENT NAME"</xref></t>
+                     <t><xref target="SET DB_INSTRUMENT DESCRIPTION">"SET DB_INSTRUMENT DESCRIPTION"</xref></t>
+                     <t><xref target="FIND DB_INSTRUMENTS">"FIND DB_INSTRUMENTS"</xref></t>
+                 </list>
+                 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!
+                 </t>
              </section>
          </section>
-Line 6752 
 Schoenebeck'>
+Line 7405 
 Schoenebeck'>
                  of sampler channels.</t>
              </section>
+             <section title="MIDI data on a sampler channel arrived" anchor="SUBSCRIBE CHANNEL_MIDI">
+                 <t>Client may want to be notified when MIDI data arrive on sampler channels on
+                 back-end side, by issuing the following command:</t>
+                 <t>
+                     <list>
+                         <t>SUBSCRIBE CHANNEL_MIDI</t>
+                     </list>
+                 </t>
+                 <t>Server will start sending one of the the following notification messages:</t>
+                 <t>
+                     <list>
+                         <t>"NOTIFY:CHANNEL_MIDI:&lt;channel-id&gt; NOTE_ON  &lt;note&gt; &lt;velocity&gt;"</t>
+                         <t>"NOTIFY:CHANNEL_MIDI:&lt;channel-id&gt; NOTE_OFF &lt;note&gt; &lt;velocity&gt;"</t>
+                     </list>
+                 </t>
+                 <t>where &lt;channel-id&gt; will be replaced by the ID of the sampler channel where the MIDI
+                 data arrived. &lt;note&gt; and &lt;velocity&gt; are integer values in the range between
+.. 127, reflecting the analog meaning of the MIDI specification.
+                 </t>
+                 <t>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.</t>
+             </section>
+             <section title="MIDI data on a MIDI input device arrived" anchor="SUBSCRIBE DEVICE_MIDI">
+                     <t>Client may want to be notified when MIDI data arrive on MIDI input devices by issuing the following command:</t>
+                     <t>
+                             <list>
+                                     <t>SUBSCRIBE DEVICE_MIDI</t>
+                             </list>
+                     </t>
+                     <t>Server will start sending one of the the following notification messages:</t>
+                     <t>
+                             <list>
+                                     <t>"NOTIFY:DEVICE_MIDI:&lt;device-id&gt; &lt;port-id&gt; NOTE_ON &lt;note&gt; &lt;velocity&gt;"</t>
+                                     <t>"NOTIFY:DEVICE_MIDI:&lt;device-id&gt; &lt;port-id&gt; NOTE_OFF &lt;note&gt; &lt;velocity&gt;"</t>
+                             </list>
+                     </t>
+                     <t>where &lt;device-id&gt; &lt;port-id&gt; will be replaced
+                        by the IDs of the respective MIDI input device and the device's MIDI port where the MIDI
+                        data arrived. &lt;note&gt; and &lt;velocity&gt; are integer values in the range between
+.. 127, reflecting the analog meaning of the MIDI specification.
+                     </t>
+                     <t>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.</t>
+             </section>
              <section title="Number of active voices changed" anchor="SUBSCRIBE VOICE_COUNT">
                  <t>Client may want to be notified when the number of voices on the
                  back-end changes by issuing the following command:</t>
-Line 6889 
 Schoenebeck'>
+Line 7592 
 Schoenebeck'>
                  all currently active voices.</t>
              </section>
+             <section title="Total number of active disk streams changed" anchor="SUBSCRIBE TOTAL_STREAM_COUNT">
+                 <t>Client may want to be notified when the total number of disk streams on the
+                 back-end changes by issuing the following command:</t>
+                 <t>
+                     <list>
+                         <t>SUBSCRIBE TOTAL_STREAM_COUNT</t>
+                     </list>
+                 </t>
+                 <t>Server will start sending the following notification messages:</t>
+                 <t>
+                     <list>
+                         <t>"NOTIFY:TOTAL_STREAM_COUNT:&lt;streams&gt;"</t>
+                     </list>
+                 </t>
+                 <t>where &lt;streams&gt; will be replaced by the new number of
+                 all currently active disk streams.</t>
+             </section>
              <section title="Number of MIDI instrument maps changed" anchor="SUBSCRIBE MIDI_INSTRUMENT_MAP_COUNT">
                  <t>Client may want to be notified when the number of MIDI instrument maps on the
                  back-end changes by issuing the following command:</t>

 Legend:



Removed from v.1250
 


changed lines


 
Added in v.1782
 Legend:



Removed from v.1250
 


changed lines


 
Added in v.1782
-Removed from v.1250
+Added in v.1782

	ViewVC Help
Powered by ViewVC