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

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

Parent Directory | Revision Log | View Patch Patch

-revision 1161 by iliev,
Mon Apr 16 15:51:18 2007 UTC
+revision 1544 by iliev,
Tue Dec  4 18:20:16 2007 UTC
 Line 34 
 Schoenebeck'>
                  <email>schoenebeck at software minus engineering dot org</email>
              </address>
          </author>
-         <date month="April" year="2007"/>
+         <date month="October" year="2007"/>
          <workgroup>LinuxSampler Developers</workgroup>
          <keyword>LSCP</keyword>
          <abstract>
 Line 61 
 Schoenebeck'>
              (front-end) and server (LinuxSampler) respectively. Lines in
              examples must be interpreted as every line being CRLF
              terminated (carriage return character followed by line feed
-             character as defined in the ASCII standard), thus the following
+             character as defined in the ASCII standard <xref target="RFC20"/>),
-             example:</t>
+             thus the following example:</t>
              <t>
                  <list>
 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 2113 
 Schoenebeck'>
+Line 2121 
 Schoenebeck'>
                      number of the sampler channel the instrument should be assigned to.
                      Each sampler channel can only have one instrument.</t>
+                     <t>Notice: since LSCP 1.2 the &lt;filename&gt; argument supports
+                     escape characters for special characters (see chapter
+                     "<xref target="character_set">Character Set and Escape Sequences</xref>"
+                     for details) and accordingly backslash characters in the filename
+                     MUST now be escaped as well!</t>
                      <t>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
-Line 2429 
 Schoenebeck'>
+Line 2443 
 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 2513 
 Schoenebeck'>
+Line 2529 
 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 2523 
 Schoenebeck'>
+Line 2540 
 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 3241 
 Schoenebeck'>
+Line 3260 
 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 3431 
 Schoenebeck'>
+Line 3452 
 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 3494 
 Schoenebeck'>
+Line 3517 
 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 3898 
 Schoenebeck'>
+Line 3924 
 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 3945 
 Schoenebeck'>
+Line 3989 
 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 4061 
 Schoenebeck'>
+Line 4107 
 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 4071 
 Schoenebeck'>
+Line 4117 
 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 4242 
 Schoenebeck'>
+Line 4291 
 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 4278 
 Schoenebeck'>
+Line 4329 
 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 4325 
 Schoenebeck'>
+Line 4379 
 Schoenebeck'>
                      index, &lt;engine_name&gt; a sampler engine name as returned by
                      the <xref target="LIST AVAILABLE_ENGINES">"LIST AVAILABLE_ENGINES"</xref>
                      command (not encapsulated into apostrophes), &lt;filename&gt; 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
+                     "<xref target="character_set">Character Set and Escape Sequences</xref>"),
                      &lt;instrument_index&gt; the index (integer value) of the instrument
                      within the given file, &lt;volume_value&gt; reflects the master
                      volume of the instrument as optionally dotted number (where a
-Line 4407 
 Schoenebeck'>
+Line 4463 
 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 4633 
 Schoenebeck'>
+Line 4690 
 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 4644 
 Schoenebeck'>
+Line 4703 
 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 4656 
 Schoenebeck'>
+Line 4717 
 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 4744 
 Schoenebeck'>
+Line 4806 
 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 4827 
 Schoenebeck'>
+Line 4901 
 Schoenebeck'>
                      directories in a specific directory by sending the following command:</t>
                      <t>
                          <list>
-                             <t>GET DB_INSTRUMENT_DIRECTORIES &lt;dir&gt;</t>
+                             <t>GET DB_INSTRUMENT_DIRECTORIES [RECURSIVE] &lt;dir&gt;</t>
                          </list>
                      </t>
                      <t>Where &lt;dir&gt; should be replaced by the absolute path
-                     name of the directory.</t>
+                     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.</t>
                      <t>Possible Answers:</t>
                      <t>
-Line 4860 
 Schoenebeck'>
+Line 4936 
 Schoenebeck'>
                      in specific directory by sending the following command:</t>
                      <t>
                          <list>
-                             <t>LIST DB_INSTRUMENT_DIRECTORIES &lt;dir&gt;</t>
+                             <t>LIST DB_INSTRUMENT_DIRECTORIES [RECURSIVE] &lt;dir&gt;</t>
                          </list>
                      </t>
                      <t>Where &lt;dir&gt; should be replaced by the absolute path
-                     name of the directory.</t>
+                     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.</t>
                      <t>Possible Answers:</t>
                      <t>
-Line 4885 
 Schoenebeck'>
+Line 4963 
 Schoenebeck'>
                              <t>S: "'Piano Collection','Percussion Collection'"</t>
                          </list>
                      </t>
+                     <t>
+                         <list>
+                             <t>C: "LIST DB_INSTRUMENT_DIRECTORIES RECURSIVE '/'"</t>
+                             <t>S: "'/Piano Collection','/Piano Collection/Acoustic','/Piano Collection/Acoustic/New','/Percussion Collection'"</t>
+                         </list>
+                     </t>
                  </section>
                  <section title="Getting instrument directory information" anchor="GET DB_INSTRUMENT_DIRECTORY INFO">
-Line 4911 
 Schoenebeck'>
+Line 4995 
 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 5024 
 Schoenebeck'>
+Line 5110 
 Schoenebeck'>
                      </t>
                  </section>
+                 <section title="Copying instrument directories" anchor="COPY DB_INSTRUMENT_DIRECTORY">
+                     <t>The front-end can copy a specific
+                     instrument directory by sending the following command:</t>
+                     <t>
+                         <list>
+                             <t>COPY DB_INSTRUMENT_DIRECTORY &lt;dir&gt; &lt;dst&gt;</t>
+                         </list>
+                     </t>
+                     <t>Where &lt;dir&gt; is the absolute path name of the directory
+                     to copy and &lt;dst&gt; is the location where the directory will
+                     be copied to.</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 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.</t>
+                                 </list>
+                             </t>
+                         </list>
+                     </t>
+                     <t>Example:</t>
+                     <t>
+                         <list>
+                             <t>C: "COPY DB_INSTRUMENT_DIRECTORY '/Piano Collection/Acoustic' '/Acoustic/Pianos'"</t>
+                             <t>S: "OK"</t>
+                         </list>
+                     </t>
+                 </section>
                  <section title="Changing the description of directory" anchor="SET DB_INSTRUMENT_DIRECTORY DESCRIPTION">
                      <t>The front-end can alter the description of a specific
                      instrument directory by sending the following command:</t>
-Line 5033 
 Schoenebeck'>
+Line 5161 
 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 5060 
 Schoenebeck'>
+Line 5190 
 Schoenebeck'>
                      </t>
                  </section>
+                 <section title="Finding directories" anchor="FIND DB_INSTRUMENT_DIRECTORIES">
+                     <t>The front-end can search for directories
+                     in specific directory by sending the following command:</t>
+                     <t>
+                         <list>
+                             <t>FIND DB_INSTRUMENT_DIRECTORIES [NON_RECURSIVE] &lt;dir&gt; &lt;criteria-list&gt;</t>
+                         </list>
+                     </t>
+                     <t>Where &lt;dir&gt; 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. &lt;criteria-list&gt; is a list of search criterias
+                     in form of "key1=val1 key2=val2 ...". The following criterias are
+                     allowed:</t>
+                     <t>
+                       <t>NAME='&lt;search-string&gt;'
+                           <list>
+                               <t>Restricts the search to directories, which names
+                               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>
+                       <t>CREATED='[&lt;date-after&gt;]..[&lt;date-before&gt;]'
+                           <list>
+                               <t>Restricts the search to directories, which creation
+                               date satisfies the specified period, where &lt;date-after&gt;
+                               and &lt;date-before&gt; are in "YYYY-MM-DD HH:MM:SS" format.
+                               If &lt;date-after&gt; is omitted the search is restricted to
+                               directories created before &lt;date-before&gt;. If
+                               &lt;date-before&gt; is omitted, the search is restricted
+                               to directories created after &lt;date-after&gt;.</t>
+                           </list>
+                       </t>
+                       <t>MODIFIED='[&lt;date-after&gt;]..[&lt;date-before&gt;]'
+                           <list>
+                               <t>Restricts the search to directories, which
+                               date of last modification satisfies the specified period, where
+                               &lt;date-after&gt; and &lt;date-before&gt; are in "YYYY-MM-DD HH:MM:SS"
+                               format. If &lt;date-after&gt; is omitted the search is restricted to
+                               directories, which are last modified before &lt;date-before&gt;. If
+                               &lt;date-before&gt; is omitted, the search is restricted to directories,
+                               which are last modified after &lt;date-after&gt;.</t>
+                           </list>
+                       </t>
+                       <t>DESCRIPTION='&lt;search-string&gt;'
+                           <list>
+                               <t>Restricts the search to directories with description
+                               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>
+                     <t>Where &lt;search-string&gt; is either a regular expression, or a
+                     word list separated with spaces for OR search and with '+' for AND search.</t>
+                     <t>Possible Answers:</t>
+                     <t>
+                         <list>
+                             <t>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.</t>
+                             <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
+                                 <list>
+                                     <t>if the given directory does not exist.</t>
+                                 </list>
+                             </t>
+                         </list>
+                     </t>
+                     <t>Example:</t>
+                     <t>
+                         <list>
+                             <t>C: "FIND DB_INSTRUMENT_DIRECTORIES '/' NAME='Piano'"</t>
+                             <t>S: "'/Piano Collection'"</t>
+                         </list>
+                     </t>
+                     <t>
+                         <list>
+                             <t>C: "FIND DB_INSTRUMENT_DIRECTORIES '/' CREATED='..2007-04-01 09:30:13'"</t>
+                             <t>S: "'/Piano Collection','/Percussions'"</t>
+                         </list>
+                     </t>
+                 </section>
                  <section title="Adding instruments to the instruments database" anchor="ADD DB_INSTRUMENTS">
                      <t>The front-end can add one or more instruments
                      to the instruments database by sending the following command:</t>
                      <t>
                          <list>
-                             <t>ADD DB_INSTRUMENTS [&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;] &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 5083 
 Schoenebeck'>
+Line 5303 
 Schoenebeck'>
                      scanning will be done and has exactly the following possibilities:</t>
                      <t>
                          <list>
+                             <t>"RECURSIVE" -
+                                 <list>
+                                     <t>All instruments will be processed, including those
+                                     in the subdirectories, and the respective subdirectory
+                                     tree structure will be recreated in the instruments
+                                     database</t>
+                                 </list>
+                             </t>
                              <t>"NON_RECURSIVE" -
                                  <list>
                                      <t>Only the instruments in the specified directory
-Line 5099 
 Schoenebeck'>
+Line 5327 
 Schoenebeck'>
                                      the specified database directory.</t>
                                  </list>
                              </t>
-                             <t>not supplied -
-                                 <list>
-                                     <t>The subdirectory tree structure will be recreated
-                                     in the instruments database and all instruments will be
-                                     processed and added to the respective subdirectory
-                                     in the instruments database.</t>
-                                 </list>
-                             </t>
                          </list>
                      </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.
+                     The <xref target="GET DB_INSTRUMENTS_JOB INFO">GET DB_INSTRUMENTS_JOB INFO</xref>
+                     command can be used to monitor the scanning progress.</t>
                      <t>Possible Answers:</t>
                      <t>
                          <list>
                              <t>"OK" -
                                  <list>
-                                     <t>on success</t>
+                                     <t>on success when NON_MODAL is not supplied</t>
+                                 </list>
+                             </t>
+                             <t>"OK[&lt;job-id&gt;]" -
+                                 <list>
+                                     <t>on success when NON_MODAL is supplied, where &lt;job-id&gt;
+                                     is a numerical ID used to obtain status information about the job progress.
+                                     See <xref target="GET DB_INSTRUMENTS_JOB INFO">GET DB_INSTRUMENTS_JOB INFO</xref>
+                                     </t>
                                  </list>
                              </t>
                              <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
-Line 5177 
 Schoenebeck'>
+Line 5411 
 Schoenebeck'>
                      instruments in a specific directory by sending the following command:</t>
                      <t>
                          <list>
-                             <t>GET DB_INSTRUMENTS &lt;dir&gt;</t>
+                             <t>GET DB_INSTRUMENTS [RECURSIVE] &lt;dir&gt;</t>
                          </list>
                      </t>
                      <t>Where &lt;dir&gt; should be replaced by the absolute path name
-                     of the directory.</t>
+                     of the directory. If RECURSIVE is specified, the number of all
+                     instruments, including those located in subdirectories of the
+                     specified directory, will be returned.</t>
                      <t>Possible Answers:</t>
                      <t>
-Line 5210 
 Schoenebeck'>
+Line 5446 
 Schoenebeck'>
                      in specific directory by sending the following command:</t>
                      <t>
                          <list>
-                             <t>LIST DB_INSTRUMENTS &lt;dir&gt;</t>
+                             <t>LIST DB_INSTRUMENTS [RECURSIVE] &lt;dir&gt;</t>
                          </list>
                      </t>
                      <t>Where &lt;dir&gt; should be replaced by the absolute path
-                     name of the directory.</t>
+                     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.</t>
                      <t>Possible Answers:</t>
                      <t>
-Line 5235 
 Schoenebeck'>
+Line 5473 
 Schoenebeck'>
                              <t>S: "'Bosendorfer 290','Steinway D'"</t>
                          </list>
                      </t>
+                     <t>
+                         <list>
+                             <t>C: "LIST DB_INSTRUMENTS RECURSIVE '/Piano Collection'"</t>
+                             <t>S: "'/Piano Collection/Bosendorfer 290','/Piano Collection/Steinway D','/Piano Collection/Lite/Free Piano'"</t>
+                         </list>
+                     </t>
                  </section>
                  <section title="Getting instrument information" anchor="GET DB_INSTRUMENT INFO">
-Line 5261 
 Schoenebeck'>
+Line 5505 
 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 5300 
 Schoenebeck'>
+Line 5546 
 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 5311 
 Schoenebeck'>
+Line 5559 
 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 5430 
 Schoenebeck'>
+Line 5684 
 Schoenebeck'>
                      </t>
                  </section>
+                 <section title="Copying instruments" anchor="COPY DB_INSTRUMENT">
+                     <t>The front-end can copy a specific instrument to another directory by
+                     sending the following command:</t>
+                     <t>
+                         <list>
+                             <t>COPY DB_INSTRUMENT &lt;instr&gt; &lt;dst&gt;</t>
+                         </list>
+                     </t>
+                     <t>Where &lt;instr&gt; is the absolute path name of the instrument
+                     to copy and &lt;dst&gt; is the directory where the instrument will
+                     be copied to.</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 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.</t>
+                                 </list>
+                             </t>
+                         </list>
+                     </t>
+                     <t>Example:</t>
+                     <t>
+                         <list>
+                             <t>C: "COPY DB_INSTRUMENT '/Piano Collection/Bosendorfer 290' '/Acoustic/Pianos/'"</t>
+                             <t>S: "OK"</t>
+                         </list>
+                     </t>
+                 </section>
                  <section title="Changing the description of instrument" anchor="SET DB_INSTRUMENT DESCRIPTION">
                      <t>The front-end can alter the description of a specific
                      instrument by sending the following command:</t>
-Line 5439 
 Schoenebeck'>
+Line 5733 
 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 5466 
 Schoenebeck'>
+Line 5762 
 Schoenebeck'>
                      </t>
                  </section>
+                 <section title="Finding instruments" anchor="FIND DB_INSTRUMENTS">
+                     <t>The front-end can search for instruments
+                     in specific directory by sending the following command:</t>
+                     <t>
+                         <list>
+                             <t>FIND DB_INSTRUMENTS [NON_RECURSIVE] &lt;dir&gt; &lt;criteria-list&gt;</t>
+                         </list>
+                     </t>
+                     <t>Where &lt;dir&gt; 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. &lt;criteria-list&gt; is a list of search criterias
+                     in form of "key1=val1 key2=val2 ...". The following criterias are
+                     allowed:</t>
+                     <t>
+                       <t>NAME='&lt;search-string&gt;'
+                           <list>
+                               <t>Restricts the search to instruments, which names
+                               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>
+                       <t>SIZE=[&lt;min&gt;]..[&lt;max&gt;]
+                           <list>
+                               <t>Restricts the search to instruments, which
+                               size is in the specified range. If &lt;min&gt; is omitted,
+                               the search results are restricted to instruments with size less then
+                               or equal to &lt;max&gt;. If &lt;max&gt; is omitted, the
+                               search is restricted to instruments with size greater then
+                               or equal to &lt;min&gt;.</t>
+                           </list>
+                       </t>
+                       <t>CREATED='[&lt;date-after&gt;]..[&lt;date-before&gt;]'
+                           <list>
+                               <t>Restricts the search to instruments, which creation
+                               date satisfies the specified period, where &lt;date-after&gt;
+                               and &lt;date-before&gt; are in "YYYY-MM-DD HH:MM:SS" format.
+                               If &lt;date-after&gt; is omitted the search is restricted to
+                               instruments created before &lt;date-before&gt;. If
+                               &lt;date-before&gt; is omitted, the search is restricted
+                               to instruments created after &lt;date-after&gt;.</t>
+                           </list>
+                       </t>
+                       <t>MODIFIED='[&lt;date-after&gt;]..[&lt;date-before&gt;]'
+                           <list>
+                               <t>Restricts the search to instruments, which
+                               date of last modification satisfies the specified period, where
+                               &lt;date-after&gt; and &lt;date-before&gt; are in "YYYY-MM-DD HH:MM:SS"
+                               format. If &lt;date-after&gt; is omitted the search is restricted to
+                               instruments, which are last modified before &lt;date-before&gt;. If
+                               &lt;date-before&gt; is omitted, the search is restricted to instruments,
+                               which are last modified after &lt;date-after&gt;.</t>
+                           </list>
+                       </t>
+                       <t>DESCRIPTION='&lt;search-string&gt;'
+                           <list>
+                               <t>Restricts the search to instruments with description
+                               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 (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 (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 (encapsulated into apostrophes,
+                               supporting escape sequences as described in chapter
+                               "<xref target="character_set">Character Set and Escape Sequences</xref>").</t>
+                           </list>
+                       </t>
+                       <t>IS_DRUM=true | false
+                           <list>
+                               <t>Either true or false. Restricts the search to
+                               drum kits or chromatic instruments.</t>
+                           </list>
+                       </t>
+                       <t>FORMAT_FAMILIES='&lt;format-list&gt;'
+                           <list>
+                               <t>Restricts the search to instruments of the supplied format families,
+                               where &lt;format-list&gt; is a comma separated list of format families.</t>
+                           </list>
+                       </t>
+                     </t>
+                     <t>Where &lt;search-string&gt; is either a regular expression, or a
+                     word list separated with spaces for OR search and with '+' for AND search.</t>
+                     <t>Possible Answers:</t>
+                     <t>
+                         <list>
+                             <t>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.</t>
+                             <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
+                                 <list>
+                                     <t>if the given directory does not exist.</t>
+                                 </list>
+                             </t>
+                         </list>
+                     </t>
+                     <t>Example:</t>
+                     <t>
+                         <list>
+                             <t>C: "FIND DB_INSTRUMENTS '/Piano Collection' NAME='bosendorfer+290'"</t>
+                             <t>S: "'/Piano Collection/Bosendorfer 290'"</t>
+                         </list>
+                     </t>
+                     <t>
+                         <list>
+                             <t>C: "FIND DB_INSTRUMENTS '/Piano Collection' CREATED='2007-04-01 09:30:13..'"</t>
+                             <t>S: "'/Piano Collection/Bosendorfer 290','/Piano Collection/Steinway D'"</t>
+                         </list>
+                     </t>
+                 </section>
+                 <section title="Getting job status information" anchor="GET DB_INSTRUMENTS_JOB INFO">
+                     <t>The front-end can ask for the current status of a
+                     particular database instruments job by sending the following command:</t>
+                     <t>
+                         <list>
+                             <t>GET DB_INSTRUMENTS_JOB INFO &lt;job-id&gt;</t>
+                         </list>
+                     </t>
+                     <t>Where &lt;job-id&gt; should be replaced by the numerical ID
+                     of the job the front-end is interested in.</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>FILES_TOTAL -
+                                         <list>
+                                             <t>The total number of files scheduled for scanning</t>
+                                         </list>
+                                     </t>
+                                     <t>FILES_SCANNED -
+                                         <list>
+                                             <t>The current number of scanned files</t>
+                                         </list>
+                                     </t>
+                                     <t>SCANNING -
+                                         <list>
+                                             <t>The absolute path name of the file which is currently
+                                             being scanned</t>
+                                         </list>
+                                     </t>
+                                     <t>STATUS -
+                                         <list>
+                                             <t>An integer value between 0 and 100 indicating the
+                                             scanning progress percentage of the file which is
+                                             currently being scanned</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 DB_INSTRUMENTS_JOB INFO 2"</t>
+                             <t>S: "FILES_TOTAL: 12"</t>
+                             <t>&nbsp;&nbsp;&nbsp;"FILES_SCANNED: 7"</t>
+                             <t>&nbsp;&nbsp;&nbsp;"SCANNING: /home/me/gigs/Bosendorfer 290.gig"</t>
+                             <t>&nbsp;&nbsp;&nbsp;"STATUS: 42"</t>
+                             <t>&nbsp;&nbsp;&nbsp;"."</t>
+                         </list>
+                     </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>
+             <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>
-Line 5547 
 Schoenebeck'>
+Line 6152 
 Schoenebeck'>
                  </t>
                  <t>/ CLEAR SP clear_instruction
                  </t>
+                 <t>/ FIND SP find_instruction
+                 </t>
                  <t>/ MOVE SP move_instruction
                  </t>
+                 <t>/ COPY SP copy_instruction
+                 </t>
+                 <t>/ EDIT SP edit_instruction
+                 </t>
+                 <t>/ FORMAT SP format_instruction
+                 </t>
                  <t>/ RESET
                  </t>
                  <t>/ QUIT
-Line 5559 
 Schoenebeck'>
+Line 6172 
 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 FLAT SP pathname SP pathname
+                 <t>/ DB_INSTRUMENTS SP scan_mode SP db_path SP filename
                  </t>
-                 <t>/ DB_INSTRUMENTS SP NON_RECURSIVE SP pathname SP pathname
+                 <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 5615 
 Schoenebeck'>
+Line 6232 
 Schoenebeck'>
                  </t>
                  <t>/ DB_INSTRUMENT_INFO
                  </t>
+                 <t>/ DB_INSTRUMENTS_JOB_INFO
+                 </t>
                  <t>/ MISCELLANEOUS
                  </t>
+                 <t>/ TOTAL_STREAM_COUNT
+                 </t>
                  <t>/ TOTAL_VOICE_COUNT
                  </t>
                  <t>/ GLOBAL_INFO
-Line 5663 
 Schoenebeck'>
+Line 6284 
 Schoenebeck'>
                  </t>
                  <t>/ DB_INSTRUMENT_INFO
                  </t>
+                 <t>/ DB_INSTRUMENTS_JOB_INFO
+                 </t>
                  <t>/ MISCELLANEOUS
                  </t>
+                 <t>/ TOTAL_STREAM_COUNT
+                 </t>
                  <t>/ TOTAL_VOICE_COUNT
                  </t>
                  <t>/ GLOBAL_INFO
-Line 5697 
 Schoenebeck'>
+Line 6322 
 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 5755 
 Schoenebeck'>
+Line 6380 
 Schoenebeck'>
                  </t>
                  <t>/ SERVER SP INFO
                  </t>
+                 <t>/ TOTAL_STREAM_COUNT
+                 </t>
                  <t>/ TOTAL_VOICE_COUNT
                  </t>
                  <t>/ TOTAL_VOICE_COUNT_MAX
-Line 5773 
 Schoenebeck'>
+Line 6400 
 Schoenebeck'>
                  </t>
                  <t>/ FX_SEND SP INFO SP sampler_channel SP fx_send_id
                  </t>
-                 <t>/ DB_INSTRUMENT_DIRECTORIES SP pathname
+                 <t>/ DB_INSTRUMENT_DIRECTORIES SP RECURSIVE SP db_path
                  </t>
-                 <t>/ DB_INSTRUMENT_DIRECTORY SP INFO SP pathname
+                 <t>/ DB_INSTRUMENT_DIRECTORIES SP db_path
                  </t>
-                 <t>/ DB_INSTRUMENTS SP pathname
+                 <t>/ DB_INSTRUMENT_DIRECTORY SP INFO SP db_path
                  </t>
-                 <t>/ DB_INSTRUMENT SP INFO SP pathname
+                 <t>/ DB_INSTRUMENTS SP RECURSIVE SP db_path
+                 </t>
+                 <t>/ DB_INSTRUMENTS SP db_path
+                 </t>
+                 <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 5793 
 Schoenebeck'>
+Line 6430 
 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 5807 
 Schoenebeck'>
+Line 6446 
 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 pathname SP stringval
+                 <t>/ DB_INSTRUMENT_DIRECTORY SP DESCRIPTION SP db_path SP stringval_escaped
                  </t>
-                 <t>/ DB_INSTRUMENT SP NAME SP pathname SP dirname
+                 <t>/ DB_INSTRUMENT SP NAME SP db_path SP stringval_escaped
                  </t>
-                 <t>/ DB_INSTRUMENT SP DESCRIPTION SP pathname SP stringval
+                 <t>/ DB_INSTRUMENT SP DESCRIPTION SP db_path SP stringval_escaped
                  </t>
                  <t>/ ECHO SP boolean
                  </t>
-Line 5851 
 Schoenebeck'>
+Line 6490 
 Schoenebeck'>
                  </t>
          </list>
  </t>
+ <t>find_instruction =
+         <list>
+                 <t>DB_INSTRUMENTS SP NON_RECURSIVE SP db_path SP query_val_list
+                 </t>
+                 <t>/ DB_INSTRUMENTS SP db_path SP query_val_list
+                 </t>
+                 <t>/ DB_INSTRUMENT_DIRECTORIES SP NON_RECURSIVE SP db_path SP query_val_list
+                 </t>
+                 <t>/ DB_INSTRUMENT_DIRECTORIES SP db_path SP query_val_list
+                 </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 db_path SP db_path
+                 </t>
+         </list>
+ </t>
+ <t>copy_instruction =
+         <list>
+                 <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 5909 
 Schoenebeck'>
+Line 6568 
 Schoenebeck'>
                  </t>
          </list>
  </t>
+ <t>edit_instruction =
+         <list>
+                 <t>CHANNEL SP INSTRUMENT SP sampler_channel
+                 </t>
+         </list>
+ </t>
+ <t>format_instruction =
+         <list>
+                 <t>INSTRUMENTS_DB
+                 </t>
+         </list>
+ </t>
  <t>modal_arg =
          <list>
                  <t>/* epsilon (empty argument) */
-Line 5955 
 Schoenebeck'>
+Line 6626 
 Schoenebeck'>
                  </t>
                  <t>/ FX_SENDS SP sampler_channel
                  </t>
-                 <t>/ DB_INSTRUMENT_DIRECTORIES SP pathname
+                 <t>/ DB_INSTRUMENT_DIRECTORIES SP RECURSIVE SP db_path
+                 </t>
+                 <t>/ DB_INSTRUMENT_DIRECTORIES SP db_path
                  </t>
-                 <t>/ DB_INSTRUMENTS SP pathname
+                 <t>/ DB_INSTRUMENTS SP RECURSIVE SP db_path
+                 </t>
+                 <t>/ DB_INSTRUMENTS SP db_path
+                 </t>
+                 <t>/ FILE SP INSTRUMENTS SP filename
                  </t>
          </list>
  </t>
-Line 6079 
 Schoenebeck'>
+Line 6756 
 Schoenebeck'>
                  </t>
          </list>
  </t>
- <t>pathname =
+ <t>filename =
-         <list>
-                 <t>stringval
-                 </t>
-         </list>
- </t>
- <t>dirname =
          <list>
-                 <t>stringval
+                 <t>path
+                                  #if WIN32
+                                  $$ = $1.toWindows();
+                                  #else
+                                  $$ = $1.toPosix();
+                                  #endif
                  </t>
          </list>
  </t>
- <t>filename =
+ <t>db_path =
          <list>
-                 <t>stringval
+                 <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 6123 
 Schoenebeck'>
+Line 6801 
 Schoenebeck'>
                  </t>
          </list>
  </t>
  <t>param_val =
          <list>
                  <t>string
-Line 6135 
 Schoenebeck'>
+Line 6814 
 Schoenebeck'>
                  </t>
          </list>
  </t>
+ <t>query_val_list =
+         <list>
+                 <t>string '=' query_val
+                 </t>
+                 <t>/ query_val_list SP string '=' query_val
+                 </t>
+         </list>
+ </t>
+ <t>query_val =
+         <list>
+                 <t>text_escaped
+                 </t>
+                 <t>/ stringval_escaped
+                 </t>
+         </list>
+ </t>
+ <t>scan_mode =
+         <list>
+                 <t>RECURSIVE
+                 </t>
+                 <t>/ NON_RECURSIVE
+                 </t>
+                 <t>/ FLAT
+                 </t>
+         </list>
+ </t>
              <!-- GRAMMAR_BNF_END - do NOT delete or modify this line !!! -->
+             <section title="Character Set and Escape Sequences" anchor="character_set">
+                 <t>Older versions of this protocol up to and including v1.1 only
+                 supported the standard ASCII character set (ASCII code 0 - 127)
+                 <xref target="RFC20"/>, all younger versions of this protocol
+                 however support the Extended ASCII character set (ASCII code
+- 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:</t>
+                 <texttable>
+                     <ttcol>ASCII Character Sequence</ttcol>
+                     <ttcol>Translated into (Name)</ttcol>
+                     <c>\n</c> <c>new line</c>
+                     <c>\r</c> <c>carriage return</c>
+                     <c>\f</c> <c>form feed</c>
+                     <c>\t</c> <c>horizontal tab</c>
+                     <c>\v</c> <c>vertical tab</c>
+                     <c>\'</c> <c>apostrophe</c>
+                     <c>\"</c> <c>quotation mark</c>
+                     <c>\\</c> <c>backslash</c>
+                     <c>\OOO</c> <c>three digit octal ASCII code of the character</c>
+                     <c>\xHH</c> <c>two digit hex ASCII code of the character</c>
+                 </texttable>
+                 <t>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.</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>
+                 </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>
+                 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>
          <section title="Events" anchor="events">
-Line 6322 
 Schoenebeck'>
+Line 7127 
 Schoenebeck'>
              </section>
              <section title="Number of effect sends changed" anchor="SUBSCRIBE FX_SEND_COUNT">
                  <t>Client may want to be notified when the number of effect sends on
                  a particular sampler channel is changed by issuing the following command:</t>
                  <t>
                      <list>
-Line 6377 
 Schoenebeck'>
+Line 7182 
 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>
-Line 6582 
 Schoenebeck'>
+Line 7405 
 Schoenebeck'>
                  the new name of the instrument, encapsulated into apostrophes.</t>
              </section>
+             <section title="Database job status information changed" anchor="SUBSCRIBE DB_INSTRUMENTS_JOB_INFO">
+                 <t>Client may want to be notified when the status of particular database
+                 instruments job is changed by issuing the following command:</t>
+                 <t>
+                     <list>
+                         <t>SUBSCRIBE DB_INSTRUMENTS_JOB_INFO</t>
+                     </list>
+                 </t>
+                 <t>Server will start sending the following notification messages:</t>
+                 <t>
+                     <list>
+                         <t>"NOTIFY:DB_INSTRUMENTS_JOB_INFO:&lt;job-id&gt;"</t>
+                     </list>
+                 </t>
+                 <t>where &lt;job-id&gt; 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.</t>
+             </section>
              <section title="Miscellaneous and debugging events" anchor="SUBSCRIBE MISCELLANEOUS">
                  <t>Client may want to be notified of miscellaneous and debugging events occurring at
                  the server by issuing the following command:</t>
-Line 6660 
 Schoenebeck'>
+Line 7505 
 Schoenebeck'>
                  </front>
                  <seriesInfo name="RFC" value="2234" />
              </reference>
+             <reference anchor="RFC20">
+                 <front>
+                     <title>ASCII format for Network Interchange</title>
+                     <author>
+                         <organization>UCLA</organization>
+                     </author>
+                     <date year="1969"></date>
+                 </front>
+                 <seriesInfo name="RFC" value="20" />
+             </reference>
           </references>
      </back>

 Legend:



Removed from v.1161
 


changed lines


 
Added in v.1544
 Legend:



Removed from v.1161
 


changed lines


 
Added in v.1544
-Removed from v.1161
+Added in v.1544

	ViewVC Help
Powered by ViewVC