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

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

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

revision 1161 by iliev, Mon Apr 16 15:51:18 2007 UTC revision 1296 by iliev, Wed Aug 15 17:43:34 2007 UTC
# Line 16  Line 16 
16       to an annoying "missing Normative/Informative References" error message -->       to an annoying "missing Normative/Informative References" error message -->
17  <?rfc strict="no" ?>  <?rfc strict="no" ?>
18    
19  <rfc category="std" ipr="full3978" docName="LSCP 1.2">  <rfc category="std" ipr="full3978" docName="LSCP 1.2cvs">
20      <front>      <front>
21          <title>LinuxSampler Control Protocol</title>          <title>LinuxSampler Control Protocol (draft)</title>
22          <author initials='C.S.' surname="Schoenebeck" fullname='C.          <author initials='C.S.' surname="Schoenebeck" fullname='C.
23  Schoenebeck'>  Schoenebeck'>
24              <organization>              <organization>
# Line 34  Schoenebeck'> Line 34  Schoenebeck'>
34                  <email>schoenebeck at software minus engineering dot org</email>                  <email>schoenebeck at software minus engineering dot org</email>
35              </address>              </address>
36          </author>          </author>
37          <date month="April" year="2007"/>          <date month="June" year="2007"/>
38          <workgroup>LinuxSampler Developers</workgroup>          <workgroup>LinuxSampler Developers</workgroup>
39          <keyword>LSCP</keyword>          <keyword>LSCP</keyword>
40          <abstract>          <abstract>
# Line 61  Schoenebeck'> Line 61  Schoenebeck'>
61              (front-end) and server (LinuxSampler) respectively. Lines in              (front-end) and server (LinuxSampler) respectively. Lines in
62              examples must be interpreted as every line being CRLF              examples must be interpreted as every line being CRLF
63              terminated (carriage return character followed by line feed              terminated (carriage return character followed by line feed
64              character as defined in the ASCII standard), thus the following              character as defined in the ASCII standard <xref target="RFC20"/>),
65              example:</t>              thus the following example:</t>
66    
67              <t>              <t>
68                  <list>                  <list>
# Line 2061  Schoenebeck'> Line 2061  Schoenebeck'>
2061                      or <xref target="LIST MIDI_INPUT_DEVICES">"LIST MIDI_INPUT_DEVICES"</xref>                      or <xref target="LIST MIDI_INPUT_DEVICES">"LIST MIDI_INPUT_DEVICES"</xref>
2062                      command, &lt;port&gt; by the MIDI port number, &lt;key&gt; by the name of                      command, &lt;port&gt; by the MIDI port number, &lt;key&gt; by the name of
2063                      the parameter to change and &lt;value&gt; by the new value for this                      the parameter to change and &lt;value&gt; by the new value for this
2064                      parameter.</t>                      parameter (encapsulated into apostrophes) or NONE (not encapsulated into apostrophes)
2065                        for specifying no value for parameters allowing a list of values.</t>
2066    
2067                      <t>Possible Answers:</t>                      <t>Possible Answers:</t>
2068                      <t>                      <t>
# Line 2088  Schoenebeck'> Line 2089  Schoenebeck'>
2089                      <t>Example:</t>                      <t>Example:</t>
2090                      <t>                      <t>
2091                          <list>                          <list>
2092                              <t></t>                              <t>C: "SET MIDI_INPUT_PORT_PARAMETER 0 0 ALSA_SEQ_BINDINGS='20:0'"</t>
2093                                <t>S: "OK"</t>
2094                            </list>
2095                        </t>
2096                        <t>
2097                            <list>
2098                                <t>C: "SET MIDI_INPUT_PORT_PARAMETER 0 0 ALSA_SEQ_BINDINGS=NONE"</t>
2099                                <t>S: "OK"</t>
2100                          </list>                          </list>
2101                      </t>                      </t>
2102                  </section>                  </section>
# Line 2113  Schoenebeck'> Line 2121  Schoenebeck'>
2121                      number of the sampler channel the instrument should be assigned to.                      number of the sampler channel the instrument should be assigned to.
2122                      Each sampler channel can only have one instrument.</t>                      Each sampler channel can only have one instrument.</t>
2123    
2124                        <t>Notice: since LSCP 1.2 the &lt;filename&gt; argument supports
2125                        escape characters for special characters (see chapter
2126                        "<xref target="character_set">Character Set and Escape Sequences</xref>"
2127                        for details) and accordingly backslash characters in the filename
2128                        MUST now be escaped as well!</t>
2129    
2130                      <t>The difference between regular and NON_MODAL versions of the command                      <t>The difference between regular and NON_MODAL versions of the command
2131                      is that the regular command returns OK only after the instrument has been                      is that the regular command returns OK only after the instrument has been
2132                      fully loaded and the channel is ready to be used while NON_MODAL version                      fully loaded and the channel is ready to be used while NON_MODAL version
# Line 4325  Schoenebeck'> Line 4339  Schoenebeck'>
4339                      index, &lt;engine_name&gt; a sampler engine name as returned by                      index, &lt;engine_name&gt; a sampler engine name as returned by
4340                      the <xref target="LIST AVAILABLE_ENGINES">"LIST AVAILABLE_ENGINES"</xref>                      the <xref target="LIST AVAILABLE_ENGINES">"LIST AVAILABLE_ENGINES"</xref>
4341                      command (not encapsulated into apostrophes), &lt;filename&gt; the name                      command (not encapsulated into apostrophes), &lt;filename&gt; the name
4342                      of the instrument's file to be deployed (encapsulated into apostrophes),                      of the instrument's file to be deployed (encapsulated into apostrophes,
4343                        supporting escape sequences as described in chapter
4344                        "<xref target="character_set">Character Set and Escape Sequences</xref>"),
4345                      &lt;instrument_index&gt; the index (integer value) of the instrument                      &lt;instrument_index&gt; the index (integer value) of the instrument
4346                      within the given file, &lt;volume_value&gt; reflects the master                      within the given file, &lt;volume_value&gt; reflects the master
4347                      volume of the instrument as optionally dotted number (where a                      volume of the instrument as optionally dotted number (where a
# Line 4827  Schoenebeck'> Line 4843  Schoenebeck'>
4843                      directories in a specific directory by sending the following command:</t>                      directories in a specific directory by sending the following command:</t>
4844                      <t>                      <t>
4845                          <list>                          <list>
4846                              <t>GET DB_INSTRUMENT_DIRECTORIES &lt;dir&gt;</t>                              <t>GET DB_INSTRUMENT_DIRECTORIES [RECURSIVE] &lt;dir&gt;</t>
4847                          </list>                          </list>
4848                      </t>                      </t>
4849                      <t>Where &lt;dir&gt; should be replaced by the absolute path                      <t>Where &lt;dir&gt; should be replaced by the absolute path
4850                      name of the directory.</t>                      name of the directory. If RECURSIVE is specified, the number of
4851                        all directories, including those located in subdirectories of the
4852                        specified directory, will be returned.</t>
4853    
4854                      <t>Possible Answers:</t>                      <t>Possible Answers:</t>
4855                      <t>                      <t>
# Line 4860  Schoenebeck'> Line 4878  Schoenebeck'>
4878                      in specific directory by sending the following command:</t>                      in specific directory by sending the following command:</t>
4879                      <t>                      <t>
4880                          <list>                          <list>
4881                              <t>LIST DB_INSTRUMENT_DIRECTORIES &lt;dir&gt;</t>                              <t>LIST DB_INSTRUMENT_DIRECTORIES [RECURSIVE] &lt;dir&gt;</t>
4882                          </list>                          </list>
4883                      </t>                      </t>
4884                      <t>Where &lt;dir&gt; should be replaced by the absolute path                      <t>Where &lt;dir&gt; should be replaced by the absolute path
4885                      name of the directory.</t>                      name of the directory. If RECURSIVE is specified, the absolute path names
4886                        of all directories, including those located in subdirectories of the
4887                        specified directory, will be returned.</t>
4888    
4889                      <t>Possible Answers:</t>                      <t>Possible Answers:</t>
4890                      <t>                      <t>
# Line 4885  Schoenebeck'> Line 4905  Schoenebeck'>
4905                              <t>S: "'Piano Collection','Percussion Collection'"</t>                              <t>S: "'Piano Collection','Percussion Collection'"</t>
4906                          </list>                          </list>
4907                      </t>                      </t>
4908                        <t>
4909                            <list>
4910                                <t>C: "LIST DB_INSTRUMENT_DIRECTORIES RECURSIVE '/'"</t>
4911                                <t>S: "'/Piano Collection','/Piano Collection/Acoustic','/Piano Collection/Acoustic/New','/Percussion Collection'"</t>
4912                            </list>
4913                        </t>
4914                  </section>                  </section>
4915    
4916                  <section title="Getting instrument directory information" anchor="GET DB_INSTRUMENT_DIRECTORY INFO">                  <section title="Getting instrument directory information" anchor="GET DB_INSTRUMENT_DIRECTORY INFO">
# Line 5024  Schoenebeck'> Line 5050  Schoenebeck'>
5050                      </t>                      </t>
5051                  </section>                  </section>
5052    
5053                    <section title="Copying instrument directories" anchor="COPY DB_INSTRUMENT_DIRECTORY">
5054                        <t>The front-end can copy a specific
5055                        instrument directory by sending the following command:</t>
5056                        <t>
5057                            <list>
5058                                <t>COPY DB_INSTRUMENT_DIRECTORY &lt;dir&gt; &lt;dst&gt;</t>
5059                            </list>
5060                        </t>
5061                        <t>Where &lt;dir&gt; is the absolute path name of the directory
5062                        to copy and &lt;dst&gt; is the location where the directory will
5063                        be copied to.</t>
5064    
5065                        <t>Possible Answers:</t>
5066                        <t>
5067                            <list>
5068                                <t>"OK" -
5069                                    <list>
5070                                        <t>on success</t>
5071                                    </list>
5072                                </t>
5073                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
5074                                    <list>
5075                                        <t>in case a given directory does not exists,
5076                                        or if a directory with name equal to the name
5077                                        of the specified directory already exists in
5078                                        the destination directory. Error is also thrown
5079                                        when trying to copy a directory to a subdirectory
5080                                        of itself.</t>
5081                                    </list>
5082                                </t>
5083                            </list>
5084                        </t>
5085    
5086                        <t>Example:</t>
5087                        <t>
5088                            <list>
5089                                <t>C: "COPY DB_INSTRUMENT_DIRECTORY '/Piano Collection/Acoustic' '/Acoustic/Pianos'"</t>
5090                                <t>S: "OK"</t>
5091                            </list>
5092                        </t>
5093                    </section>
5094    
5095                  <section title="Changing the description of directory" anchor="SET DB_INSTRUMENT_DIRECTORY DESCRIPTION">                  <section title="Changing the description of directory" anchor="SET DB_INSTRUMENT_DIRECTORY DESCRIPTION">
5096                      <t>The front-end can alter the description of a specific                      <t>The front-end can alter the description of a specific
5097                      instrument directory by sending the following command:</t>                      instrument directory by sending the following command:</t>
# Line 5060  Schoenebeck'> Line 5128  Schoenebeck'>
5128                      </t>                      </t>
5129                  </section>                  </section>
5130    
5131                    <section title="Finding directories" anchor="FIND DB_INSTRUMENT_DIRECTORIES">
5132                        <t>The front-end can search for directories
5133                        in specific directory by sending the following command:</t>
5134                        <t>
5135                            <list>
5136                                <t>FIND DB_INSTRUMENT_DIRECTORIES [NON_RECURSIVE] &lt;dir&gt; &lt;criteria-list&gt;</t>
5137                            </list>
5138                        </t>
5139                        <t>Where &lt;dir&gt; should be replaced by the absolute path
5140                        name of the directory to search in. If NON_RECURSIVE is specified, the
5141                        directories located in subdirectories of the specified directory will not
5142                        be searched. &lt;criteria-list&gt; is a list of search criterias
5143                        in form of "key1=val1 key2=val2 ...". The following criterias are
5144                        allowed:</t>
5145                        <t>
5146                          <t>NAME='&lt;search-string&gt;'
5147                              <list>
5148                                  <t>Restricts the search to directories, which names
5149                                  satisfy the supplied search string.</t>
5150                              </list>
5151                          </t>
5152    
5153                          <t>CREATED='[&lt;date-after&gt;]..[&lt;date-before&gt;]'
5154                              <list>
5155                                  <t>Restricts the search to directories, which creation
5156                                  date satisfies the specified period, where &lt;date-after&gt;
5157                                  and &lt;date-before&gt; are in "YYYY-MM-DD HH:MM:SS" format.
5158                                  If &lt;date-after&gt; is omitted the search is restricted to
5159                                  directories created before &lt;date-before&gt;. If
5160                                  &lt;date-before&gt; is omitted, the search is restricted
5161                                  to directories created after &lt;date-after&gt;.</t>
5162                              </list>
5163                          </t>
5164    
5165                          <t>MODIFIED='[&lt;date-after&gt;]..[&lt;date-before&gt;]'
5166                              <list>
5167                                  <t>Restricts the search to directories, which
5168                                  date of last modification satisfies the specified period, where
5169                                  &lt;date-after&gt; and &lt;date-before&gt; are in "YYYY-MM-DD HH:MM:SS"
5170                                  format. If &lt;date-after&gt; is omitted the search is restricted to
5171                                  directories, which are last modified before &lt;date-before&gt;. If
5172                                  &lt;date-before&gt; is omitted, the search is restricted to directories,
5173                                  which are last modified after &lt;date-after&gt;.</t>
5174                              </list>
5175                          </t>
5176    
5177                          <t>DESCRIPTION='&lt;search-string&gt;'
5178                              <list>
5179                                  <t>Restricts the search to directories with description
5180                                  that satisfies the supplied search string.</t>
5181                              </list>
5182                          </t>
5183                        </t>
5184    
5185                        <t>Where &lt;search-string&gt; is either a regular expression, or a
5186                        word list separated with spaces for OR search and with '+' for AND search.</t>
5187    
5188                        <t>Possible Answers:</t>
5189                        <t>
5190                            <list>
5191                                <t>A comma separated list with the absolute path names (encapsulated into
5192                                apostrophes) of all directories in the specified directory that satisfy
5193                                the supplied search criterias.</t>
5194                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
5195                                    <list>
5196                                        <t>if the given directory does not exist.</t>
5197                                    </list>
5198                                </t>
5199                            </list>
5200                        </t>
5201                        <t>Example:</t>
5202                        <t>
5203                            <list>
5204                                <t>C: "FIND DB_INSTRUMENT_DIRECTORIES '/' NAME='Piano'"</t>
5205                                <t>S: "'/Piano Collection'"</t>
5206                            </list>
5207                        </t>
5208                        <t>
5209                            <list>
5210                                <t>C: "FIND DB_INSTRUMENT_DIRECTORIES '/' CREATED='..2007-04-01 09:30:13'"</t>
5211                                <t>S: "'/Piano Collection','/Percussions'"</t>
5212                            </list>
5213                        </t>
5214                    </section>
5215    
5216                  <section title="Adding instruments to the instruments database" anchor="ADD DB_INSTRUMENTS">                  <section title="Adding instruments to the instruments database" anchor="ADD DB_INSTRUMENTS">
5217                      <t>The front-end can add one or more instruments                      <t>The front-end can add one or more instruments
5218                      to the instruments database by sending the following command:</t>                      to the instruments database by sending the following command:</t>
5219                      <t>                      <t>
5220                          <list>                          <list>
5221                              <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>
5222                          </list>                          </list>
5223                      </t>                      </t>
5224                      <t>Where &lt;db_dir&gt; is the absolute path name of a directory                      <t>Where &lt;db_dir&gt; is the absolute path name of a directory
# Line 5083  Schoenebeck'> Line 5236  Schoenebeck'>
5236                      scanning will be done and has exactly the following possibilities:</t>                      scanning will be done and has exactly the following possibilities:</t>
5237                      <t>                      <t>
5238                          <list>                          <list>
5239                                <t>"RECURSIVE" -
5240                                    <list>
5241                                        <t>All instruments will be processed, including those
5242                                        in the subdirectories, and the respective subdirectory
5243                                        tree structure will be recreated in the instruments
5244                                        database</t>
5245                                    </list>
5246                                </t>
5247                              <t>"NON_RECURSIVE" -                              <t>"NON_RECURSIVE" -
5248                                  <list>                                  <list>
5249                                      <t>Only the instruments in the specified directory                                      <t>Only the instruments in the specified directory
# Line 5099  Schoenebeck'> Line 5260  Schoenebeck'>
5260                                      the specified database directory.</t>                                      the specified database directory.</t>
5261                                  </list>                                  </list>
5262                              </t>                              </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>  
5263                          </list>                          </list>
5264                      </t>                      </t>
5265    
5266                     <t>The difference between regular and NON_MODAL versions of the command
5267                        is that the regular command returns when the scanning is finished
5268                        while NON_MODAL version returns immediately and a background process is launched.
5269                        The <xref target="GET DB_INSTRUMENTS_JOB INFO">GET DB_INSTRUMENTS_JOB INFO</xref>
5270                        command can be used to monitor the scanning progress.</t>
5271    
5272                      <t>Possible Answers:</t>                      <t>Possible Answers:</t>
5273                      <t>                      <t>
5274                          <list>                          <list>
5275                              <t>"OK" -                              <t>"OK" -
5276                                  <list>                                  <list>
5277                                      <t>on success</t>                                      <t>on success when NON_MODAL is not supplied</t>
5278                                    </list>
5279                                </t>
5280                                <t>"OK[&lt;job-id&gt;]" -
5281                                    <list>
5282                                        <t>on success when NON_MODAL is supplied, where &lt;job-id&gt;
5283                                        is a numerical ID used to obtain status information about the job progress.
5284                                        See <xref target="GET DB_INSTRUMENTS_JOB INFO">GET DB_INSTRUMENTS_JOB INFO</xref>
5285                                        </t>
5286                                  </list>                                  </list>
5287                              </t>                              </t>
5288                              <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -                              <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
# Line 5177  Schoenebeck'> Line 5344  Schoenebeck'>
5344                      instruments in a specific directory by sending the following command:</t>                      instruments in a specific directory by sending the following command:</t>
5345                      <t>                      <t>
5346                          <list>                          <list>
5347                              <t>GET DB_INSTRUMENTS &lt;dir&gt;</t>                              <t>GET DB_INSTRUMENTS [RECURSIVE] &lt;dir&gt;</t>
5348                          </list>                          </list>
5349                      </t>                      </t>
5350                      <t>Where &lt;dir&gt; should be replaced by the absolute path name                      <t>Where &lt;dir&gt; should be replaced by the absolute path name
5351                      of the directory.</t>                      of the directory. If RECURSIVE is specified, the number of all
5352                        instruments, including those located in subdirectories of the
5353                        specified directory, will be returned.</t>
5354    
5355                      <t>Possible Answers:</t>                      <t>Possible Answers:</t>
5356                      <t>                      <t>
# Line 5210  Schoenebeck'> Line 5379  Schoenebeck'>
5379                      in specific directory by sending the following command:</t>                      in specific directory by sending the following command:</t>
5380                      <t>                      <t>
5381                          <list>                          <list>
5382                              <t>LIST DB_INSTRUMENTS &lt;dir&gt;</t>                              <t>LIST DB_INSTRUMENTS [RECURSIVE] &lt;dir&gt;</t>
5383                          </list>                          </list>
5384                      </t>                      </t>
5385                      <t>Where &lt;dir&gt; should be replaced by the absolute path                      <t>Where &lt;dir&gt; should be replaced by the absolute path
5386                      name of the directory.</t>                      name of the directory. If RECURSIVE is specified, the absolute path
5387                        names of all instruments, including those located in subdirectories
5388                        of the specified directory, will be returned.</t>
5389    
5390                      <t>Possible Answers:</t>                      <t>Possible Answers:</t>
5391                      <t>                      <t>
# Line 5235  Schoenebeck'> Line 5406  Schoenebeck'>
5406                              <t>S: "'Bosendorfer 290','Steinway D'"</t>                              <t>S: "'Bosendorfer 290','Steinway D'"</t>
5407                          </list>                          </list>
5408                      </t>                      </t>
5409                        <t>
5410                            <list>
5411                                <t>C: "LIST DB_INSTRUMENTS RECURSIVE '/Piano Collection'"</t>
5412                                <t>S: "'/Piano Collection/Bosendorfer 290','/Piano Collection/Steinway D','/Piano Collection/Lite/Free Piano'"</t>
5413                            </list>
5414                        </t>
5415                  </section>                  </section>
5416    
5417                  <section title="Getting instrument information" anchor="GET DB_INSTRUMENT INFO">                  <section title="Getting instrument information" anchor="GET DB_INSTRUMENT INFO">
# Line 5430  Schoenebeck'> Line 5607  Schoenebeck'>
5607                      </t>                      </t>
5608                  </section>                  </section>
5609    
5610                    <section title="Copying instruments" anchor="COPY DB_INSTRUMENT">
5611                        <t>The front-end can copy a specific instrument to another directory by
5612                        sending the following command:</t>
5613                        <t>
5614                            <list>
5615                                <t>COPY DB_INSTRUMENT &lt;instr&gt; &lt;dst&gt;</t>
5616                            </list>
5617                        </t>
5618                        <t>Where &lt;instr&gt; is the absolute path name of the instrument
5619                        to copy and &lt;dst&gt; is the directory where the instrument will
5620                        be copied to.</t>
5621    
5622                        <t>Possible Answers:</t>
5623                        <t>
5624                            <list>
5625                                <t>"OK" -
5626                                    <list>
5627                                        <t>on success</t>
5628                                    </list>
5629                                </t>
5630                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
5631                                    <list>
5632                                        <t>in case the given instrument does not exists,
5633                                        or if an instrument with name equal to the name of the
5634                                        specified instrument already exists in the destination
5635                                        directory.</t>
5636                                    </list>
5637                                </t>
5638                            </list>
5639                        </t>
5640    
5641                        <t>Example:</t>
5642                        <t>
5643                            <list>
5644                                <t>C: "COPY DB_INSTRUMENT '/Piano Collection/Bosendorfer 290' '/Acoustic/Pianos/'"</t>
5645                                <t>S: "OK"</t>
5646                            </list>
5647                        </t>
5648                    </section>
5649    
5650                  <section title="Changing the description of instrument" anchor="SET DB_INSTRUMENT DESCRIPTION">                  <section title="Changing the description of instrument" anchor="SET DB_INSTRUMENT DESCRIPTION">
5651                      <t>The front-end can alter the description of a specific                      <t>The front-end can alter the description of a specific
5652                      instrument by sending the following command:</t>                      instrument by sending the following command:</t>
# Line 5466  Schoenebeck'> Line 5683  Schoenebeck'>
5683                      </t>                      </t>
5684                  </section>                  </section>
5685    
5686                    <section title="Finding instruments" anchor="FIND DB_INSTRUMENTS">
5687                        <t>The front-end can search for instruments
5688                        in specific directory by sending the following command:</t>
5689                        <t>
5690                            <list>
5691                                <t>FIND DB_INSTRUMENTS [NON_RECURSIVE] &lt;dir&gt; &lt;criteria-list&gt;</t>
5692                            </list>
5693                        </t>
5694                        <t>Where &lt;dir&gt; should be replaced by the absolute path
5695                        name of the directory to search in. If NON_RECURSIVE is specified, the
5696                        directories located in subdirectories of the specified directory will not
5697                        be searched. &lt;criteria-list&gt; is a list of search criterias
5698                        in form of "key1=val1 key2=val2 ...". The following criterias are
5699                        allowed:</t>
5700                        <t>
5701                          <t>NAME='&lt;search-string&gt;'
5702                              <list>
5703                                  <t>Restricts the search to instruments, which names
5704                                  satisfy the supplied search string.</t>
5705                              </list>
5706                          </t>
5707    
5708                          <t>SIZE=[&lt;min&gt;]..[&lt;max&gt;]
5709                              <list>
5710                                  <t>Restricts the search to instruments, which
5711                                  size is in the specified range. If &lt;min&gt; is omitted,
5712                                  the search results are restricted to instruments with size less then
5713                                  or equal to &lt;max&gt;. If &lt;max&gt; is omitted, the
5714                                  search is restricted to instruments with size greater then
5715                                  or equal to &lt;min&gt;.</t>
5716                              </list>
5717                          </t>
5718    
5719                          <t>CREATED='[&lt;date-after&gt;]..[&lt;date-before&gt;]'
5720                              <list>
5721                                  <t>Restricts the search to instruments, which creation
5722                                  date satisfies the specified period, where &lt;date-after&gt;
5723                                  and &lt;date-before&gt; are in "YYYY-MM-DD HH:MM:SS" format.
5724                                  If &lt;date-after&gt; is omitted the search is restricted to
5725                                  instruments created before &lt;date-before&gt;. If
5726                                  &lt;date-before&gt; is omitted, the search is restricted
5727                                  to instruments created after &lt;date-after&gt;.</t>
5728                              </list>
5729                          </t>
5730    
5731                          <t>MODIFIED='[&lt;date-after&gt;]..[&lt;date-before&gt;]'
5732                              <list>
5733                                  <t>Restricts the search to instruments, which
5734                                  date of last modification satisfies the specified period, where
5735                                  &lt;date-after&gt; and &lt;date-before&gt; are in "YYYY-MM-DD HH:MM:SS"
5736                                  format. If &lt;date-after&gt; is omitted the search is restricted to
5737                                  instruments, which are last modified before &lt;date-before&gt;. If
5738                                  &lt;date-before&gt; is omitted, the search is restricted to instruments,
5739                                  which are last modified after &lt;date-after&gt;.</t>
5740                              </list>
5741                          </t>
5742    
5743                          <t>DESCRIPTION='&lt;search-string&gt;'
5744                              <list>
5745                                  <t>Restricts the search to instruments with description
5746                                  that satisfies the supplied search string.</t>
5747                              </list>
5748                          </t>
5749    
5750                          <t>PRODUCT='&lt;search-string&gt;'
5751                              <list>
5752                                  <t>Restricts the search to instruments with product info
5753                                  that satisfies the supplied search string.</t>
5754                              </list>
5755                          </t>
5756    
5757                          <t>ARTISTS='&lt;search-string&gt;'
5758                              <list>
5759                                  <t>Restricts the search to instruments with artists info
5760                                  that satisfies the supplied search string.</t>
5761                              </list>
5762                          </t>
5763    
5764                          <t>KEYWORDS='&lt;search-string&gt;'
5765                              <list>
5766                                  <t>Restricts the search to instruments with keyword list
5767                                  that satisfies the supplied search string.</t>
5768                              </list>
5769                          </t>
5770    
5771                          <t>IS_DRUM=true | false
5772                              <list>
5773                                  <t>Either true or false. Restricts the search to
5774                                  drum kits or chromatic instruments.</t>
5775                              </list>
5776                          </t>
5777    
5778                          <t>FORMAT_FAMILIES='&lt;format-list&gt;'
5779                              <list>
5780                                  <t>Restricts the search to instruments of the supplied format families,
5781                                  where &lt;format-list&gt; is a comma separated list of format families.</t>
5782                              </list>
5783                          </t>
5784                        </t>
5785    
5786                        <t>Where &lt;search-string&gt; is either a regular expression, or a
5787                        word list separated with spaces for OR search and with '+' for AND search.</t>
5788    
5789                        <t>Possible Answers:</t>
5790                        <t>
5791                            <list>
5792                                <t>A comma separated list with the absolute path names (encapsulated into
5793                                apostrophes) of all instruments in the specified directory that satisfy
5794                                the supplied search criterias.</t>
5795                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
5796                                    <list>
5797                                        <t>if the given directory does not exist.</t>
5798                                    </list>
5799                                </t>
5800                            </list>
5801                        </t>
5802                        <t>Example:</t>
5803                        <t>
5804                            <list>
5805                                <t>C: "FIND DB_INSTRUMENTS '/Piano Collection' NAME='bosendorfer+290'"</t>
5806                                <t>S: "'/Piano Collection/Bosendorfer 290'"</t>
5807                            </list>
5808                        </t>
5809                        <t>
5810                            <list>
5811                                <t>C: "FIND DB_INSTRUMENTS '/Piano Collection' CREATED='2007-04-01 09:30:13..'"</t>
5812                                <t>S: "'/Piano Collection/Bosendorfer 290','/Piano Collection/Steinway D'"</t>
5813                            </list>
5814                        </t>
5815                    </section>
5816    
5817                    <section title="Getting job status information" anchor="GET DB_INSTRUMENTS_JOB INFO">
5818                        <t>The front-end can ask for the current status of a
5819                        particular database instruments job by sending the following command:</t>
5820                        <t>
5821                            <list>
5822                                <t>GET DB_INSTRUMENTS_JOB INFO &lt;job-id&gt;</t>
5823                            </list>
5824                        </t>
5825                        <t>Where &lt;job-id&gt; should be replaced by the numerical ID
5826                        of the job the front-end is interested in.</t>
5827    
5828                        <t>Possible Answers:</t>
5829                        <t>
5830                            <list>
5831                                <t>LinuxSampler will answer by sending a &lt;CRLF&gt; separated list.
5832                                Each answer line begins with the settings category name
5833                                followed by a colon and then a space character &lt;SP&gt; and finally
5834                                the info character string to that setting category. At the
5835                                moment the following categories are defined:</t>
5836    
5837                                <t>
5838                                    <list>
5839                                        <t>FILES_TOTAL -
5840                                            <list>
5841                                                <t>The total number of files scheduled for scanning</t>
5842                                            </list>
5843                                        </t>
5844                                        <t>FILES_SCANNED -
5845                                            <list>
5846                                                <t>The current number of scanned files</t>
5847                                            </list>
5848                                        </t>
5849                                        <t>SCANNING -
5850                                            <list>
5851                                                <t>The absolute path name of the file which is currently
5852                                                being scanned</t>
5853                                            </list>
5854                                        </t>
5855                                        <t>STATUS -
5856                                            <list>
5857                                                <t>An integer value between 0 and 100 indicating the
5858                                                scanning progress percentage of the file which is
5859                                                currently being scanned</t>
5860                                            </list>
5861                                        </t>
5862                                    </list>
5863                                </t>
5864                            </list>
5865                        </t>
5866                        <t>The mentioned fields above don't have to be in particular order.</t>
5867    
5868                        <t>Example:</t>
5869                        <t>
5870                            <list>
5871                                <t>C: "GET DB_INSTRUMENTS_JOB INFO 2"</t>
5872                                <t>S: "FILES_TOTAL: 12"</t>
5873                                <t>&nbsp;&nbsp;&nbsp;"FILES_SCANNED: 7"</t>
5874                                <t>&nbsp;&nbsp;&nbsp;"SCANNING: /home/me/gigs/Bosendorfer 290.gig"</t>
5875                                <t>&nbsp;&nbsp;&nbsp;"STATUS: 42"</t>
5876                                <t>&nbsp;&nbsp;&nbsp;"."</t>
5877                            </list>
5878                        </t>
5879                    </section>
5880    
5881              </section>              </section>
5882    
5883          </section>          </section>
# Line 5547  Schoenebeck'> Line 5959  Schoenebeck'>
5959                  </t>                  </t>
5960                  <t>/ CLEAR SP clear_instruction                  <t>/ CLEAR SP clear_instruction
5961                  </t>                  </t>
5962                    <t>/ FIND SP find_instruction
5963                    </t>
5964                  <t>/ MOVE SP move_instruction                  <t>/ MOVE SP move_instruction
5965                  </t>                  </t>
5966                    <t>/ COPY SP copy_instruction
5967                    </t>
5968                    <t>/ EDIT SP edit_instruction
5969                    </t>
5970                  <t>/ RESET                  <t>/ RESET
5971                  </t>                  </t>
5972                  <t>/ QUIT                  <t>/ QUIT
# Line 5561  Schoenebeck'> Line 5979  Schoenebeck'>
5979                  </t>                  </t>
5980                  <t>/ DB_INSTRUMENT_DIRECTORY SP pathname                  <t>/ DB_INSTRUMENT_DIRECTORY SP pathname
5981                  </t>                  </t>
5982                  <t>/ DB_INSTRUMENTS SP FLAT SP pathname SP pathname                  <t>/ DB_INSTRUMENTS SP NON_MODAL SP scan_mode SP pathname SP pathname
5983                    </t>
5984                    <t>/ DB_INSTRUMENTS SP scan_mode SP pathname SP pathname
5985                    </t>
5986                    <t>/ DB_INSTRUMENTS SP NON_MODAL SP pathname SP pathname
5987                  </t>                  </t>
5988                  <t>/ DB_INSTRUMENTS SP NON_RECURSIVE SP pathname SP pathname                  <t>/ DB_INSTRUMENTS SP NON_MODAL SP pathname SP pathname SP instrument_index
5989                  </t>                  </t>
5990                  <t>/ DB_INSTRUMENTS SP pathname SP pathname                  <t>/ DB_INSTRUMENTS SP pathname SP pathname
5991                  </t>                  </t>
# Line 5615  Schoenebeck'> Line 6037  Schoenebeck'>
6037                  </t>                  </t>
6038                  <t>/ DB_INSTRUMENT_INFO                  <t>/ DB_INSTRUMENT_INFO
6039                  </t>                  </t>
6040                    <t>/ DB_INSTRUMENTS_JOB_INFO
6041                    </t>
6042                  <t>/ MISCELLANEOUS                  <t>/ MISCELLANEOUS
6043                  </t>                  </t>
6044                  <t>/ TOTAL_VOICE_COUNT                  <t>/ TOTAL_VOICE_COUNT
# Line 5663  Schoenebeck'> Line 6087  Schoenebeck'>
6087                  </t>                  </t>
6088                  <t>/ DB_INSTRUMENT_INFO                  <t>/ DB_INSTRUMENT_INFO
6089                  </t>                  </t>
6090                    <t>/ DB_INSTRUMENTS_JOB_INFO
6091                    </t>
6092                  <t>/ MISCELLANEOUS                  <t>/ MISCELLANEOUS
6093                  </t>                  </t>
6094                  <t>/ TOTAL_VOICE_COUNT                  <t>/ TOTAL_VOICE_COUNT
# Line 5773  Schoenebeck'> Line 6199  Schoenebeck'>
6199                  </t>                  </t>
6200                  <t>/ FX_SEND SP INFO SP sampler_channel SP fx_send_id                  <t>/ FX_SEND SP INFO SP sampler_channel SP fx_send_id
6201                  </t>                  </t>
6202                    <t>/ DB_INSTRUMENT_DIRECTORIES SP RECURSIVE SP pathname
6203                    </t>
6204                  <t>/ DB_INSTRUMENT_DIRECTORIES SP pathname                  <t>/ DB_INSTRUMENT_DIRECTORIES SP pathname
6205                  </t>                  </t>
6206                  <t>/ DB_INSTRUMENT_DIRECTORY SP INFO SP pathname                  <t>/ DB_INSTRUMENT_DIRECTORY SP INFO SP pathname
6207                  </t>                  </t>
6208                    <t>/ DB_INSTRUMENTS SP RECURSIVE SP pathname
6209                    </t>
6210                  <t>/ DB_INSTRUMENTS SP pathname                  <t>/ DB_INSTRUMENTS SP pathname
6211                  </t>                  </t>
6212                  <t>/ DB_INSTRUMENT SP INFO SP pathname                  <t>/ DB_INSTRUMENT SP INFO SP pathname
6213                  </t>                  </t>
6214                    <t>/ DB_INSTRUMENTS_JOB SP INFO SP number
6215                    </t>
6216                  <t>/ VOLUME                  <t>/ VOLUME
6217                  </t>                  </t>
6218          </list>          </list>
# Line 5793  Schoenebeck'> Line 6225  Schoenebeck'>
6225                  </t>                  </t>
6226                  <t>/ MIDI_INPUT_DEVICE_PARAMETER SP number SP string '=' param_val_list                  <t>/ MIDI_INPUT_DEVICE_PARAMETER SP number SP string '=' param_val_list
6227                  </t>                  </t>
6228                    <t>/ MIDI_INPUT_PORT_PARAMETER SP number SP number SP string '=' NONE
6229                    </t>
6230                  <t>/ MIDI_INPUT_PORT_PARAMETER SP number SP number SP string '=' param_val_list                  <t>/ MIDI_INPUT_PORT_PARAMETER SP number SP number SP string '=' param_val_list
6231                  </t>                  </t>
6232                  <t>/ CHANNEL SP set_chan_instruction                  <t>/ CHANNEL SP set_chan_instruction
# Line 5851  Schoenebeck'> Line 6285  Schoenebeck'>
6285                  </t>                  </t>
6286          </list>          </list>
6287  </t>  </t>
6288    <t>find_instruction =
6289            <list>
6290                    <t>DB_INSTRUMENTS SP NON_RECURSIVE SP pathname SP query_val_list
6291                    </t>
6292                    <t>/ DB_INSTRUMENTS SP pathname SP query_val_list
6293                    </t>
6294                    <t>/ DB_INSTRUMENT_DIRECTORIES SP NON_RECURSIVE SP pathname SP query_val_list
6295                    </t>
6296                    <t>/ DB_INSTRUMENT_DIRECTORIES SP pathname SP query_val_list
6297                    </t>
6298            </list>
6299    </t>
6300  <t>move_instruction =  <t>move_instruction =
6301          <list>          <list>
6302                  <t>DB_INSTRUMENT_DIRECTORY SP pathname SP pathname                  <t>DB_INSTRUMENT_DIRECTORY SP pathname SP pathname
# Line 5859  Schoenebeck'> Line 6305  Schoenebeck'>
6305                  </t>                  </t>
6306          </list>          </list>
6307  </t>  </t>
6308    <t>copy_instruction =
6309            <list>
6310                    <t>DB_INSTRUMENT_DIRECTORY SP pathname SP pathname
6311                    </t>
6312                    <t>/ DB_INSTRUMENT SP pathname SP pathname
6313                    </t>
6314            </list>
6315    </t>
6316  <t>destroy_instruction =  <t>destroy_instruction =
6317          <list>          <list>
6318                  <t>AUDIO_OUTPUT_DEVICE SP number                  <t>AUDIO_OUTPUT_DEVICE SP number
# Line 5909  Schoenebeck'> Line 6363  Schoenebeck'>
6363                  </t>                  </t>
6364          </list>          </list>
6365  </t>  </t>
6366    <t>edit_instruction =
6367            <list>
6368                    <t>INSTRUMENT SP sampler_channel
6369                    </t>
6370            </list>
6371    </t>
6372  <t>modal_arg =  <t>modal_arg =
6373          <list>          <list>
6374                  <t>/* epsilon (empty argument) */                  <t>/* epsilon (empty argument) */
# Line 5955  Schoenebeck'> Line 6415  Schoenebeck'>
6415                  </t>                  </t>
6416                  <t>/ FX_SENDS SP sampler_channel                  <t>/ FX_SENDS SP sampler_channel
6417                  </t>                  </t>
6418                    <t>/ DB_INSTRUMENT_DIRECTORIES SP RECURSIVE SP pathname
6419                    </t>
6420                  <t>/ DB_INSTRUMENT_DIRECTORIES SP pathname                  <t>/ DB_INSTRUMENT_DIRECTORIES SP pathname
6421                  </t>                  </t>
6422                    <t>/ DB_INSTRUMENTS SP RECURSIVE SP pathname
6423                    </t>
6424                  <t>/ DB_INSTRUMENTS SP pathname                  <t>/ DB_INSTRUMENTS SP pathname
6425                  </t>                  </t>
6426          </list>          </list>
# Line 6093  Schoenebeck'> Line 6557  Schoenebeck'>
6557  </t>  </t>
6558  <t>filename =  <t>filename =
6559          <list>          <list>
6560                  <t>stringval                  <t>stringval_escaped
6561                  </t>                  </t>
6562          </list>          </list>
6563  </t>  </t>
# Line 6135  Schoenebeck'> Line 6599  Schoenebeck'>
6599                  </t>                  </t>
6600          </list>          </list>
6601  </t>  </t>
6602    <t>query_val_list =
6603            <list>
6604                    <t>string '=' query_val
6605                    </t>
6606                    <t>/ query_val_list SP string '=' query_val
6607                    </t>
6608            </list>
6609    </t>
6610    <t>query_val =
6611            <list>
6612                    <t>string
6613                    </t>
6614                    <t>/ stringval
6615                    </t>
6616            </list>
6617    </t>
6618    <t>scan_mode =
6619            <list>
6620                    <t>RECURSIVE
6621                    </t>
6622                    <t>/ NON_RECURSIVE
6623                    </t>
6624                    <t>/ FLAT
6625                    </t>
6626            </list>
6627    </t>
6628    
6629              <!-- GRAMMAR_BNF_END - do NOT delete or modify this line !!! -->              <!-- GRAMMAR_BNF_END - do NOT delete or modify this line !!! -->
6630    
6631                <section title="Character Set and Escape Sequences" anchor="character_set">
6632                    <t>Older versions of this protocol up to and including v1.1 only
6633                    supported the standard ASCII character set (ASCII code 0 - 127)
6634                    <xref target="RFC20"/>, all younger versions of this protocol
6635                    however support the Extended ASCII character set (ASCII code
6636                    0 - 255). The same group of younger protocols also support
6637                    escape sequences, but only for certain, explicitly declared
6638                    parts of the protocol. The supported escape sequences are
6639                    defined as follows:</t>
6640                    <texttable>
6641                        <ttcol>ASCII Character Sequence</ttcol>
6642                        <ttcol>Translated into (Name)</ttcol>
6643                        <c>\n</c> <c>new line</c>
6644                        <c>\r</c> <c>carriage return</c>
6645                        <c>\f</c> <c>form feed</c>
6646                        <c>\t</c> <c>horizontal tab</c>
6647                        <c>\v</c> <c>vertical tab</c>
6648                        <c>\'</c> <c>apostrophe</c>
6649                        <c>\"</c> <c>quotation mark</c>
6650                        <c>\\</c> <c>backslash</c>
6651                        <c>\OOO</c> <c>three digit octal ASCII code of the character</c>
6652                        <c>\xHH</c> <c>two digit hex ASCII code of the character</c>
6653                    </texttable>
6654                    <t>Notice: due to the transition of certain parts of the
6655                    protocol which now support escape sequences, a slight backward
6656                    incompatibility to protocols version v1.1 and younger has been
6657                    introduced. The only difference is that in parts of the protocol
6658                    where escape characters are now supported, a backslash characters
6659                    MUST be escaped as well (that is as double backslash), whereas
6660                    in the old versions a single backslash was sufficient.</t>
6661                </section>
6662          </section>          </section>
6663    
6664          <section title="Events" anchor="events">          <section title="Events" anchor="events">
# Line 6322  Schoenebeck'> Line 6844  Schoenebeck'>
6844              </section>              </section>
6845    
6846              <section title="Number of effect sends changed" anchor="SUBSCRIBE FX_SEND_COUNT">              <section title="Number of effect sends changed" anchor="SUBSCRIBE FX_SEND_COUNT">
6847                  <t>Client may want to be notified when the number of effect sends on                  <t>Client may want to be notified when the number of effect sends on
6848                  a particular sampler channel is changed by issuing the following command:</t>                  a particular sampler channel is changed by issuing the following command:</t>
6849                  <t>                  <t>
6850                      <list>                      <list>
# Line 6582  Schoenebeck'> Line 7104  Schoenebeck'>
7104                  the new name of the instrument, encapsulated into apostrophes.</t>                  the new name of the instrument, encapsulated into apostrophes.</t>
7105              </section>              </section>
7106    
7107                <section title="Database job status information changed" anchor="SUBSCRIBE DB_INSTRUMENTS_JOB_INFO">
7108                    <t>Client may want to be notified when the status of particular database
7109                    instruments job is changed by issuing the following command:</t>
7110                    <t>
7111                        <list>
7112                            <t>SUBSCRIBE DB_INSTRUMENTS_JOB_INFO</t>
7113                        </list>
7114                    </t>
7115                    <t>Server will start sending the following notification messages:</t>
7116                    <t>
7117                        <list>
7118                            <t>"NOTIFY:DB_INSTRUMENTS_JOB_INFO:&lt;job-id&gt;"</t>
7119                        </list>
7120                    </t>
7121                    <t>where &lt;job-id&gt; will be replaced by the numerical ID of the job,
7122                    which status is changed. The front-end will have to send the respective
7123                    command to actually get the status info. Because these messages
7124                    will be triggered by LSCP commands issued by other clients rather than real
7125                    time events happening on the server, it is believed that an empty notification
7126                    message is sufficient here.</t>
7127                </section>
7128    
7129              <section title="Miscellaneous and debugging events" anchor="SUBSCRIBE MISCELLANEOUS">              <section title="Miscellaneous and debugging events" anchor="SUBSCRIBE MISCELLANEOUS">
7130                  <t>Client may want to be notified of miscellaneous and debugging events occurring at                  <t>Client may want to be notified of miscellaneous and debugging events occurring at
7131                  the server by issuing the following command:</t>                  the server by issuing the following command:</t>
# Line 6660  Schoenebeck'> Line 7204  Schoenebeck'>
7204                  </front>                  </front>
7205                  <seriesInfo name="RFC" value="2234" />                  <seriesInfo name="RFC" value="2234" />
7206              </reference>              </reference>
7207                <reference anchor="RFC20">
7208                    <front>
7209                        <title>ASCII format for Network Interchange</title>
7210                        <author>
7211                            <organization>UCLA</organization>
7212                        </author>
7213                        <date year="1969"></date>
7214                    </front>
7215                    <seriesInfo name="RFC" value="20" />
7216                </reference>
7217           </references>           </references>
7218      </back>      </back>
7219    
Legend:
Removed from v.1161  
changed lines
  Added in v.1296
  ViewVC Help
Powered by ViewVC