/[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 1544 by iliev, Tue Dec 4 18:20:16 2007 UTC revision 1727 by iliev, Tue Apr 29 15:44:09 2008 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.4">
20      <front>      <front>
21          <title>LinuxSampler Control Protocol</title>          <title>LinuxSampler Control Protocol</title>
22          <author initials='C.S.' surname="Schoenebeck" fullname='C.          <author initials='C.S.' surname="Schoenebeck" fullname='C.
# 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="October" year="2007"/>          <date month="April" year="2008"/>
38          <workgroup>LinuxSampler Developers</workgroup>          <workgroup>LinuxSampler Developers</workgroup>
39          <keyword>LSCP</keyword>          <keyword>LSCP</keyword>
40          <abstract>          <abstract>
# Line 2162  Schoenebeck'> Line 2162  Schoenebeck'>
2162                              </t>                              </t>
2163                          </list>                          </list>
2164                      </t>                      </t>
2165                      <t>Example:</t>                      <t>Example (Unix):</t>
2166                      <t>                      <t>
2167                          <list>                          <list>
2168                              <t></t>                              <t>C: LOAD INSTRUMENT '/home/joe/gigs/cello.gig' 0 0</t>
2169                                <t>S: OK</t>
2170                            </list>
2171                        </t>
2172                        <t>Example (Windows):</t>
2173                        <t>
2174                            <list>
2175                                <t>C: LOAD INSTRUMENT 'D:/MySounds/cello.gig' 0 0</t>
2176                                <t>S: OK</t>
2177                          </list>                          </list>
2178                      </t>                      </t>
2179                  </section>                  </section>
# Line 5733  Schoenebeck'> Line 5741  Schoenebeck'>
5741                          </list>                          </list>
5742                      </t>                      </t>
5743                      <t>Where &lt;instr&gt; is the absolute path name of the instrument and                      <t>Where &lt;instr&gt; is the absolute path name of the instrument and
5744                      &lt;desc&gt; is the new description for the instrument                      &lt;desc&gt; is the new description for the instrument
5745                      (encapsulated into apostrophes, supporting escape sequences as described in chapter                      (encapsulated into apostrophes, supporting escape sequences as described in chapter
5746                      "<xref target="character_set">Character Set and Escape Sequences</xref>").</t>                      "<xref target="character_set">Character Set and Escape Sequences</xref>").</t>
5747    
# Line 5976  Schoenebeck'> Line 5984  Schoenebeck'>
5984                              <t>FORMAT INSTRUMENTS_DB</t>                              <t>FORMAT INSTRUMENTS_DB</t>
5985                          </list>                          </list>
5986                      </t>                      </t>
5987                        
5988                      <t>Possible Answers:</t>                      <t>Possible Answers:</t>
5989                      <t>                      <t>
5990                          <list>                          <list>
# Line 5995  Schoenebeck'> Line 6003  Schoenebeck'>
6003                      </t>                      </t>
6004                  </section>                  </section>
6005    
6006                    <section title="Checking for lost instrument files" anchor="FIND LOST DB_INSTRUMENT_FILES">
6007                        <t>The front-end can retrieve the list of all instrument files in the instruments database
6008                        that don't exist in the filesystem by sending the following command:</t>
6009                        <t>
6010                            <list>
6011                                <t>FIND LOST DB_INSTRUMENT_FILES</t>
6012                            </list>
6013                        </t>
6014    
6015                        <t>Possible Answers:</t>
6016                        <t>
6017                            <list>
6018                                <t>A comma separated list with the absolute path names
6019                                (encapsulated into apostrophes) of all lost instrument files.</t>
6020                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
6021                                    <list>
6022                                        <t>in case it failed, providing an appropriate error code and error message.</t>
6023                                    </list>
6024                                </t>
6025                            </list>
6026                        </t>
6027                        <t>Example:</t>
6028                        <t>
6029                            <list>
6030                                <t>C: "FIND LOST DB_INSTRUMENT_FILES"</t>
6031                                <t>S: "'/gigs/Bosendorfer 290.gig','/gigs/Steinway D.gig','/gigs/Free Piano.gig'"</t>
6032                            </list>
6033                        </t>
6034                    </section>
6035    
6036                    <section title="Replacing an instrument file" anchor="SET DB_INSTRUMENT FILE_PATH">
6037                        <t>The front-end can substitute all occurrences of an instrument file
6038                        in the instruments database with a new one by sending the following command:</t>
6039                        <t>
6040                            <list>
6041                                <t>SET DB_INSTRUMENT FILE_PATH &lt;old_path&gt; &lt;new_path&gt;</t>
6042                            </list>
6043                        </t>
6044                        <t>Where &lt;old_path&gt; is the absolute path name of the instrument file
6045                        to substitute with &lt;new_path&gt;.</t>
6046    
6047                        <t>Possible Answers:</t>
6048                        <t>
6049                            <list>
6050                                <t>"OK" -
6051                                    <list>
6052                                        <t>on success</t>
6053                                    </list>
6054                                </t>
6055                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
6056                                    <list>
6057                                        <t>in case it failed, providing an appropriate error code and error message.</t>
6058                                    </list>
6059                                </t>
6060                            </list>
6061                        </t>
6062    
6063                        <t>Example:</t>
6064                        <t>
6065                            <list>
6066                                <t>C: "SET DB_INSTRUMENT FILE_PATH '/gigs/Bosendorfer 290.gig' '/gigs/pianos/Bosendorfer 290.gig'"</t>
6067                                <t>S: "OK"</t>
6068                            </list>
6069                        </t>
6070                    </section>
6071    
6072              </section>              </section>
6073    
6074    
# Line 6073  Schoenebeck'> Line 6147  Schoenebeck'>
6147                      </t>                      </t>
6148                  </section>                  </section>
6149              </section>              </section>
         </section>  
6150    
6151                <section title="Managing Files" anchor="file_management">
6152                    <t>You can query detailed informations about files located
6153                    at the same system where the sampler instance is running on.
6154                    Using this command set allows to retrieve file informations
6155                    even remotely from another machine.</t>
6156    
6157                    <section title="Retrieving amount of instruments of a file" anchor="GET FILE INSTRUMENTS">
6158                        <t>The front-end can retrieve the amount of instruments
6159                        within a given instrument file by sending the
6160                        following command:</t>
6161                        <t>
6162                            <list>
6163                                <t>GET FILE INSTRUMENTS &lt;filename&gt;</t>
6164                            </list>
6165                        </t>
6166                        <t>Where &lt;filename&gt; is the name of the instrument
6167                        file (encapsulated into apostrophes, supporting escape
6168                        sequences as described in chapter
6169                        "<xref target="character_set">Character Set and Escape
6170                            Sequences</xref>").</t>
6171    
6172                        <t>The sampler will try to ask all sampler engines,
6173                        whether they support the given file and ask the first
6174                        engine with a positive answer for the amount of
6175                        instruments.</t>
6176    
6177                        <t>Possible Answers:</t>
6178                        <t>
6179                            <list>
6180                                <t>On success, the sampler will answer by
6181                                   returning the amount of instruments.
6182                                </t>
6183                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
6184                                    <list>
6185                                        <t>if the file could not be handled</t>
6186                                    </list>
6187                                </t>
6188                            </list>
6189                        </t>
6190    
6191                        <t>Examples:</t>
6192                        <t>
6193                            <list>
6194                                <t>C: "GET FILE INSTRUMENTS 'D:/Sounds/Foo.gig'"</t>
6195                                <t>S: "10"</t>
6196                            </list>
6197                        </t>
6198                    </section>
6199    
6200                    <section title="Retrieving all instruments of a file" anchor="LIST FILE INSTRUMENTS">
6201                        <t>The front-end can retrieve a list of all instruments
6202                        within a given instrument file by sending the
6203                        following command:</t>
6204                        <t>
6205                            <list>
6206                                <t>LIST FILE INSTRUMENTS &lt;filename&gt;</t>
6207                            </list>
6208                        </t>
6209                        <t>Where &lt;filename&gt; is the name of the instrument
6210                        file (encapsulated into apostrophes, supporting escape
6211                        sequences as described in chapter
6212                        "<xref target="character_set">Character Set and Escape
6213                            Sequences</xref>").</t>
6214    
6215                        <t>The sampler will try to ask all sampler engines,
6216                        whether they support the given file and ask the first
6217                        engine with a positive answer for a list of IDs for the
6218                        instruments in the given file.</t>
6219    
6220                        <t>Possible Answers:</t>
6221                        <t>
6222                            <list>
6223                                <t>On success, the sampler will answer by
6224                                   returning a comma separated list of
6225                                   instrument IDs.
6226                                </t>
6227                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
6228                                    <list>
6229                                        <t>if the file could not be handled</t>
6230                                    </list>
6231                                </t>
6232                            </list>
6233                        </t>
6234    
6235                        <t>Examples:</t>
6236                        <t>
6237                            <list>
6238                                <t>C: "LIST FILE INSTRUMENTS 'D:/Sounds/Foo.gig'"</t>
6239                                <t>S: "0,1,2,3,4,5,6,7,8,9"</t>
6240                            </list>
6241                        </t>
6242                    </section>
6243    
6244                    <section title="Retrieving informations about one instrument in a file" anchor="GET FILE INSTRUMENT INFO">
6245                        <t>The front-end can retrieve detailed informations
6246                        about a specific instrument within a given instrument
6247                        file by sending the following command:</t>
6248                        <t>
6249                            <list>
6250                                <t>GET FILE INSTRUMENT INFO &lt;filename&gt;
6251                                &lt;instr-id&gt;</t>
6252                            </list>
6253                        </t>
6254                        <t>Where &lt;filename&gt; is the name of the instrument
6255                        file (encapsulated into apostrophes, supporting escape
6256                        sequences as described in chapter
6257                        "<xref target="character_set">Character Set and Escape
6258                            Sequences</xref>") and &lt;instr-id&gt; is the numeric
6259                        instrument ID as returned by the
6260                        <xref target="LIST FILE INSTRUMENTS">
6261                        "LIST FILE INSTRUMENTS"</xref> command.</t>
6262    
6263                        <t>The sampler will try to ask all sampler engines,
6264                        whether they support the given file and ask the first
6265                        engine with a positive answer for informations about the
6266                        specific instrument in the given file.</t>
6267    
6268                        <t>Possible Answers:</t>
6269                        <t>
6270                            <list>
6271                                <t>LinuxSampler will answer by sending a &lt;CRLF&gt; separated list.
6272                                Each answer line begins with the settings category name
6273                                followed by a colon and then a space character &lt;SP&gt; and finally
6274                                the info character string to that setting category. At the
6275                                moment the following categories are defined:</t>
6276    
6277                                <t>
6278                                    <list>
6279                                        <t>NAME -
6280                                            <list>
6281                                                <t>name of the instrument as
6282                                                stored in the instrument file</t>
6283                                            </list>
6284                                        </t>
6285                                        <t>FORMAT_FAMILY -
6286                                            <list>
6287                                                <t>name of the sampler format
6288                                                of the given instrument</t>
6289                                            </list>
6290                                        </t>
6291                                        <t>FORMAT_VERSION -
6292                                            <list>
6293                                                <t>version of the sampler format
6294                                                the instrumen is stored as</t>
6295                                            </list>
6296                                        </t>
6297                                        <t>PRODUCT -
6298                                            <list>
6299                                                <t>official product name of the
6300                                                instrument as stored in the file
6301                                                </t>
6302                                            </list>
6303                                        </t>
6304                                        <t>ARTISTS -
6305                                            <list>
6306                                                <t>artists / sample library
6307                                                vendor of the instrument</t>
6308                                            </list>
6309                                        </t>
6310                                    </list>
6311                                </t>
6312                            </list>
6313                        </t>
6314                        <t>The mentioned fields above don't have to be in particular order.</t>
6315    
6316                        <t>Example:</t>
6317                        <t>
6318                            <list>
6319                                <t>C: "GET FILE INSTRUMENT INFO 'D:/Sounds/Foo.gig' 0"</t>
6320                                <t>S: "NAME: Lunatic Loops"</t>
6321                                <t>&nbsp;&nbsp;&nbsp;"FORMAT_FAMILY: GIG"</t>
6322                                <t>&nbsp;&nbsp;&nbsp;"FORMAT_VERSION: 3"</t>
6323                                <t>&nbsp;&nbsp;&nbsp;"PRODUCT: The Backbone Bongo Beats"</t>
6324                                <t>&nbsp;&nbsp;&nbsp;"ARTISTS: Jimmy the Fish"</t>
6325                                <t>&nbsp;&nbsp;&nbsp;"."</t>
6326                            </list>
6327                        </t>
6328                    </section>
6329                </section>
6330            </section>
6331    
6332          <section title="Command Syntax" anchor="command_syntax">          <section title="Command Syntax" anchor="command_syntax">
6333              <t>The grammar of the control protocol as descibed in <xref target="control_commands"/>              <t>The grammar of the control protocol as descibed in <xref target="control_commands"/>
# Line 6204  Schoenebeck'> Line 6457  Schoenebeck'>
6457                  </t>                  </t>
6458                  <t>/ CHANNEL_COUNT                  <t>/ CHANNEL_COUNT
6459                  </t>                  </t>
6460                    <t>/ CHANNEL_MIDI
6461                    </t>
6462                    <t>/ DEVICE_MIDI
6463                    </t>
6464                  <t>/ VOICE_COUNT                  <t>/ VOICE_COUNT
6465                  </t>                  </t>
6466                  <t>/ STREAM_COUNT                  <t>/ STREAM_COUNT
# Line 6256  Schoenebeck'> Line 6513  Schoenebeck'>
6513                  </t>                  </t>
6514                  <t>/ CHANNEL_COUNT                  <t>/ CHANNEL_COUNT
6515                  </t>                  </t>
6516                    <t>/ CHANNEL_MIDI
6517                    </t>
6518                    <t>/ DEVICE_MIDI
6519                    </t>
6520                  <t>/ VOICE_COUNT                  <t>/ VOICE_COUNT
6521                  </t>                  </t>
6522                  <t>/ STREAM_COUNT                  <t>/ STREAM_COUNT
# Line 6454  Schoenebeck'> Line 6715  Schoenebeck'>
6715                  </t>                  </t>
6716                  <t>/ DB_INSTRUMENT SP DESCRIPTION SP db_path SP stringval_escaped                  <t>/ DB_INSTRUMENT SP DESCRIPTION SP db_path SP stringval_escaped
6717                  </t>                  </t>
6718                    <t>/ DB_INSTRUMENT SP FILE_PATH SP filename SP filename
6719                    </t>
6720                  <t>/ ECHO SP boolean                  <t>/ ECHO SP boolean
6721                  </t>                  </t>
6722                  <t>/ VOLUME SP volume_value                  <t>/ VOLUME SP volume_value
# Line 6500  Schoenebeck'> Line 6763  Schoenebeck'>
6763                  </t>                  </t>
6764                  <t>/ DB_INSTRUMENT_DIRECTORIES SP db_path SP query_val_list                  <t>/ DB_INSTRUMENT_DIRECTORIES SP db_path SP query_val_list
6765                  </t>                  </t>
6766                    <t>/ LOST SP DB_INSTRUMENT_FILES
6767                    </t>
6768          </list>          </list>
6769  </t>  </t>
6770  <t>move_instruction =  <t>move_instruction =
# Line 6759  Schoenebeck'> Line 7024  Schoenebeck'>
7024  <t>filename =  <t>filename =
7025          <list>          <list>
7026                  <t>path                  <t>path
                                  #if WIN32  
                                  $$ = $1.toWindows();  
                                  #else  
   
                                  $$ = $1.toPosix();  
                                  #endif  
   
7027                  </t>                  </t>
7028          </list>          </list>
7029  </t>  </t>
# Line 6902  Schoenebeck'> Line 7160  Schoenebeck'>
7160                      <t><xref target="MOVE DB_INSTRUMENT_DIRECTORY">"MOVE DB_INSTRUMENT_DIRECTORY"</xref></t>                      <t><xref target="MOVE DB_INSTRUMENT_DIRECTORY">"MOVE DB_INSTRUMENT_DIRECTORY"</xref></t>
7161                      <t><xref target="COPY DB_INSTRUMENT">"COPY DB_INSTRUMENT"</xref></t>                      <t><xref target="COPY DB_INSTRUMENT">"COPY DB_INSTRUMENT"</xref></t>
7162                      <t><xref target="COPY DB_INSTRUMENT_DIRECTORY">"COPY DB_INSTRUMENT_DIRECTORY"</xref></t>                      <t><xref target="COPY DB_INSTRUMENT_DIRECTORY">"COPY DB_INSTRUMENT_DIRECTORY"</xref></t>
7163                        <t><xref target="FIND LOST DB_INSTRUMENT_FILES">"FIND LOST DB_INSTRUMENT_FILES"</xref></t>
7164                        <t><xref target="SET DB_INSTRUMENT FILE_PATH">"SET DB_INSTRUMENT FILE_PATH"</xref></t>
7165                        <t><xref target="GET FILE INSTRUMENTS">"GET FILE INSTRUMENTS"</xref></t>
7166                        <t><xref target="LIST FILE INSTRUMENTS">"LIST FILE INSTRUMENTS"</xref></t>
7167                        <t><xref target="GET FILE INSTRUMENT INFO">"GET FILE INSTRUMENT INFO"</xref></t>
7168                  </list>                  </list>
7169                  Note that the forward slash character ('/') has a special meaning in                  Note that the forward slash character ('/') has a special meaning in
7170                  filename / path based arguments: it acts as separator of the nodes in                  filename / path based arguments: it acts as separator of the nodes in
# Line 6912  Schoenebeck'> Line 7175  Schoenebeck'>
7175                  </t>                  </t>
7176    
7177                  <t>                  <t>
7178                    Note for Windows: file path arguments in LSCP are expected
7179                    to use forward slashes as directory node separator similar
7180                    to Unix based operating systems. In contrast to Unix however
7181                    a Windows typical drive character is expected to be
7182                    prefixed to the path. That is an original Windows file path
7183                    like "D:\Sounds\My.gig" would become in LSCP:
7184                    "D:/Sounds/My.gig".
7185                    </t>
7186    
7187                    <t>
7188                  The following LSCP commands even support escape sequences as                  The following LSCP commands even support escape sequences as
7189                  part of at least one of their text-based arguments (i.e. entity name,                  part of at least one of their text-based arguments (i.e. entity name,
7190                  description) and / or may contain escape sequences in at least one of                  description) and / or may contain escape sequences in at least one of
# Line 7045  Schoenebeck'> Line 7318  Schoenebeck'>
7318                  of sampler channels.</t>                  of sampler channels.</t>
7319              </section>              </section>
7320    
7321                <section title="MIDI data on a sampler channel arrived" anchor="SUBSCRIBE CHANNEL_MIDI">
7322                    <t>Client may want to be notified when MIDI data arrive on sampler channels on
7323                    back-end side, by issuing the following command:</t>
7324                    <t>
7325                        <list>
7326                            <t>SUBSCRIBE CHANNEL_MIDI</t>
7327                        </list>
7328                    </t>
7329                    <t>Server will start sending one of the the following notification messages:</t>
7330                    <t>
7331                        <list>
7332                            <t>"NOTIFY:CHANNEL_MIDI:&lt;channel-id&gt; NOTE_ON  &lt;note&gt; &lt;velocity&gt;"</t>
7333                            <t>"NOTIFY:CHANNEL_MIDI:&lt;channel-id&gt; NOTE_OFF &lt;note&gt; &lt;velocity&gt;"</t>
7334                        </list>
7335                    </t>
7336                    <t>where &lt;channel-id&gt; will be replaced by the ID of the sampler channel where the MIDI
7337                    data arrived. &lt;note&gt; and &lt;velocity&gt; are integer values in the range between
7338                    0 .. 127, reflecting the analog meaning of the MIDI specification.
7339                    </t>
7340                    <t>CAUTION: no guarantee whatsoever will be made that MIDI events are actually all
7341                    delivered by this mechanism! With other words: events could be lost at any time!
7342                    This restriction was made to keep the RT-safeness of the backend's MIDI and audio
7343                    thread unaffected by this feature.</t>
7344                </section>
7345    
7346                <section title="MIDI data on a MIDI input device arrived" anchor="SUBSCRIBE DEVICE_MIDI">
7347                        <t>Client may want to be notified when MIDI data arrive on MIDI input devices by issuing the following command:</t>
7348                        <t>
7349                                <list>
7350                                        <t>SUBSCRIBE DEVICE_MIDI</t>
7351                                </list>
7352                        </t>
7353                        <t>Server will start sending one of the the following notification messages:</t>
7354                        <t>
7355                                <list>
7356                                        <t>"NOTIFY:DEVICE_MIDI:&lt;device-id&gt; &lt;port-id&gt; NOTE_ON &lt;note&gt; &lt;velocity&gt;"</t>
7357                                        <t>"NOTIFY:DEVICE_MIDI:&lt;device-id&gt; &lt;port-id&gt; NOTE_OFF &lt;note&gt; &lt;velocity&gt;"</t>
7358                                </list>
7359                        </t>
7360                        <t>where &lt;device-id&gt; &lt;port-id&gt; will be replaced
7361                           by the IDs of the respective MIDI input device and the device's MIDI port where the MIDI
7362                           data arrived. &lt;note&gt; and &lt;velocity&gt; are integer values in the range between
7363                           0 .. 127, reflecting the analog meaning of the MIDI specification.
7364                        </t>
7365                        <t>CAUTION: no guarantee whatsoever will be made that MIDI events are actually all
7366                           delivered by this mechanism! With other words: events could be lost at any time!
7367                           This restriction was made to keep the RT-safeness of the backend's MIDI and audio
7368                           thread unaffected by this feature.</t>
7369                </section>
7370    
7371              <section title="Number of active voices changed" anchor="SUBSCRIBE VOICE_COUNT">              <section title="Number of active voices changed" anchor="SUBSCRIBE VOICE_COUNT">
7372                  <t>Client may want to be notified when the number of voices on the                  <t>Client may want to be notified when the number of voices on the
7373                  back-end changes by issuing the following command:</t>                  back-end changes by issuing the following command:</t>
Legend:
Removed from v.1544  
changed lines
  Added in v.1727
  ViewVC Help
Powered by ViewVC