/[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 1401 by iliev, Thu Oct 11 20:45:49 2007 UTC revision 1686 by schoenebeck, Thu Feb 14 14:58:50 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.2cvs">  <rfc category="std" ipr="full3978" docName="LSCP 1.4">
20      <front>      <front>
21          <title>LinuxSampler Control Protocol (draft)</title>          <title>LinuxSampler Control Protocol</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="October" year="2007"/>          <date month="February" 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 3924  Schoenebeck'> Line 3932  Schoenebeck'>
3932                      </t>                      </t>
3933                  </section>                  </section>
3934    
3935                    <section title="Current number of active disk streams" anchor="GET TOTAL_STREAM_COUNT">
3936                        <t>The front-end can ask for the current number of active disk streams on
3937                        the sampler by sending the following command:</t>
3938                        <t>
3939                            <list>
3940                                <t>GET TOTAL_STREAM_COUNT</t>
3941                            </list>
3942                        </t>
3943    
3944                        <t>Possible Answers:</t>
3945                        <t>
3946                            <list>
3947                                <t>LinuxSampler will answer by returning the number of all active
3948                                disk streams on the sampler.</t>
3949                            </list>
3950                        </t>
3951                    </section>
3952    
3953                  <section title="Reset sampler" anchor="RESET">                  <section title="Reset sampler" anchor="RESET">
3954                      <t>The front-end can reset the whole sampler by sending the following command:</t>                      <t>The front-end can reset the whole sampler by sending the following command:</t>
3955                      <t>                      <t>
# Line 5715  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 5958  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 5997  Schoenebeck'> Line 6023  Schoenebeck'>
6023                      editor application by sending the following command:</t>                      editor application by sending the following command:</t>
6024                      <t>                      <t>
6025                          <list>                          <list>
6026                              <t>EDIT INSTRUMENT &lt;sampler-channel&gt;</t>                              <t>EDIT CHANNEL INSTRUMENT &lt;sampler-channel&gt;</t>
6027                          </list>                          </list>
6028                      </t>                      </t>
6029                      <t>Where &lt;sampler-channel&gt; should be replaced by the                      <t>Where &lt;sampler-channel&gt; should be replaced by the
# Line 6049  Schoenebeck'> Line 6075  Schoenebeck'>
6075                      <t>Examples:</t>                      <t>Examples:</t>
6076                      <t>                      <t>
6077                          <list>                          <list>
6078                              <t>C: "EDIT INSTRUMENT 0"</t>                              <t>C: "EDIT CHANNEL INSTRUMENT 0"</t>
6079                              <t>S: "OK"</t>                              <t>S: "OK"</t>
6080                          </list>                          </list>
6081                      </t>                      </t>
6082                  </section>                  </section>
6083              </section>              </section>
         </section>  
6084    
6085                <section title="Managing Files" anchor="file_management">
6086                    <t>You can query detailed informations about files located
6087                    at the same system where the sampler instance is running on.
6088                    Using this command set allows to retrieve file informations
6089                    even remotely from another machine.</t>
6090    
6091                    <section title="Retrieving amount of instruments of a file" anchor="GET FILE INSTRUMENTS">
6092                        <t>The front-end can retrieve the amount of instruments
6093                        within a given instrument file by sending the
6094                        following command:</t>
6095                        <t>
6096                            <list>
6097                                <t>GET FILE INSTRUMENTS &lt;filename&gt;</t>
6098                            </list>
6099                        </t>
6100                        <t>Where &lt;filename&gt; is the name of the instrument
6101                        file (encapsulated into apostrophes, supporting escape
6102                        sequences as described in chapter
6103                        "<xref target="character_set">Character Set and Escape
6104                            Sequences</xref>").</t>
6105    
6106                        <t>The sampler will try to ask all sampler engines,
6107                        whether they support the given file and ask the first
6108                        engine with a positive answer for the amount of
6109                        instruments.</t>
6110    
6111                        <t>Possible Answers:</t>
6112                        <t>
6113                            <list>
6114                                <t>On success, the sampler will answer by
6115                                   returning the amount of instruments.
6116                                </t>
6117                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
6118                                    <list>
6119                                        <t>if the file could not be handled</t>
6120                                    </list>
6121                                </t>
6122                            </list>
6123                        </t>
6124    
6125                        <t>Examples:</t>
6126                        <t>
6127                            <list>
6128                                <t>C: "GET FILE INSTRUMENTS 'D:/Sounds/Foo.gig'"</t>
6129                                <t>S: "10"</t>
6130                            </list>
6131                        </t>
6132                    </section>
6133    
6134                    <section title="Retrieving all instruments of a file" anchor="LIST FILE INSTRUMENTS">
6135                        <t>The front-end can retrieve a list of all instruments
6136                        within a given instrument file by sending the
6137                        following command:</t>
6138                        <t>
6139                            <list>
6140                                <t>LIST FILE INSTRUMENTS &lt;filename&gt;</t>
6141                            </list>
6142                        </t>
6143                        <t>Where &lt;filename&gt; is the name of the instrument
6144                        file (encapsulated into apostrophes, supporting escape
6145                        sequences as described in chapter
6146                        "<xref target="character_set">Character Set and Escape
6147                            Sequences</xref>").</t>
6148    
6149                        <t>The sampler will try to ask all sampler engines,
6150                        whether they support the given file and ask the first
6151                        engine with a positive answer for a list of IDs for the
6152                        instruments in the given file.</t>
6153    
6154                        <t>Possible Answers:</t>
6155                        <t>
6156                            <list>
6157                                <t>On success, the sampler will answer by
6158                                   returning a comma separated list of
6159                                   instrument IDs.
6160                                </t>
6161                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
6162                                    <list>
6163                                        <t>if the file could not be handled</t>
6164                                    </list>
6165                                </t>
6166                            </list>
6167                        </t>
6168    
6169                        <t>Examples:</t>
6170                        <t>
6171                            <list>
6172                                <t>C: "LIST FILE INSTRUMENTS 'D:/Sounds/Foo.gig'"</t>
6173                                <t>S: "0,1,2,3,4,5,6,7,8,9"</t>
6174                            </list>
6175                        </t>
6176                    </section>
6177    
6178                    <section title="Retrieving informations about one instrument in a file" anchor="GET FILE INSTRUMENT INFO">
6179                        <t>The front-end can retrieve detailed informations
6180                        about a specific instrument within a given instrument
6181                        file by sending the following command:</t>
6182                        <t>
6183                            <list>
6184                                <t>GET FILE INSTRUMENT INFO &lt;filename&gt;
6185                                &lt;instr-id&gt;</t>
6186                            </list>
6187                        </t>
6188                        <t>Where &lt;filename&gt; is the name of the instrument
6189                        file (encapsulated into apostrophes, supporting escape
6190                        sequences as described in chapter
6191                        "<xref target="character_set">Character Set and Escape
6192                            Sequences</xref>") and &lt;instr-id&gt; is the numeric
6193                        instrument ID as returned by the
6194                        <xref target="LIST FILE INSTRUMENTS">
6195                        "LIST FILE INSTRUMENTS"</xref> command.</t>
6196    
6197                        <t>The sampler will try to ask all sampler engines,
6198                        whether they support the given file and ask the first
6199                        engine with a positive answer for informations about the
6200                        specific instrument in the given file.</t>
6201    
6202                        <t>Possible Answers:</t>
6203                        <t>
6204                            <list>
6205                                <t>LinuxSampler will answer by sending a &lt;CRLF&gt; separated list.
6206                                Each answer line begins with the settings category name
6207                                followed by a colon and then a space character &lt;SP&gt; and finally
6208                                the info character string to that setting category. At the
6209                                moment the following categories are defined:</t>
6210    
6211                                <t>
6212                                    <list>
6213                                        <t>NAME -
6214                                            <list>
6215                                                <t>name of the instrument as
6216                                                stored in the instrument file</t>
6217                                            </list>
6218                                        </t>
6219                                        <t>FORMAT_FAMILY -
6220                                            <list>
6221                                                <t>name of the sampler format
6222                                                of the given instrument</t>
6223                                            </list>
6224                                        </t>
6225                                        <t>FORMAT_VERSION -
6226                                            <list>
6227                                                <t>version of the sampler format
6228                                                the instrumen is stored as</t>
6229                                            </list>
6230                                        </t>
6231                                        <t>PRODUCT -
6232                                            <list>
6233                                                <t>official product name of the
6234                                                instrument as stored in the file
6235                                                </t>
6236                                            </list>
6237                                        </t>
6238                                        <t>ARTISTS -
6239                                            <list>
6240                                                <t>artists / sample library
6241                                                vendor of the instrument</t>
6242                                            </list>
6243                                        </t>
6244                                    </list>
6245                                </t>
6246                            </list>
6247                        </t>
6248                        <t>The mentioned fields above don't have to be in particular order.</t>
6249    
6250                        <t>Example:</t>
6251                        <t>
6252                            <list>
6253                                <t>C: "GET FILE INSTRUMENT INFO 'D:/Sounds/Foo.gig' 0"</t>
6254                                <t>S: "NAME: Lunatic Loops"</t>
6255                                <t>&nbsp;&nbsp;&nbsp;"FORMAT_FAMILY: GIG"</t>
6256                                <t>&nbsp;&nbsp;&nbsp;"FORMAT_VERSION: 3"</t>
6257                                <t>&nbsp;&nbsp;&nbsp;"PRODUCT: The Backbone Bongo Beats"</t>
6258                                <t>&nbsp;&nbsp;&nbsp;"ARTISTS: Jimmy the Fish"</t>
6259                                <t>&nbsp;&nbsp;&nbsp;"."</t>
6260                            </list>
6261                        </t>
6262                    </section>
6263                </section>
6264            </section>
6265    
6266          <section title="Command Syntax" anchor="command_syntax">          <section title="Command Syntax" anchor="command_syntax">
6267              <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 6186  Schoenebeck'> Line 6391  Schoenebeck'>
6391                  </t>                  </t>
6392                  <t>/ CHANNEL_COUNT                  <t>/ CHANNEL_COUNT
6393                  </t>                  </t>
6394                    <t>/ CHANNEL_MIDI
6395                    </t>
6396                  <t>/ VOICE_COUNT                  <t>/ VOICE_COUNT
6397                  </t>                  </t>
6398                  <t>/ STREAM_COUNT                  <t>/ STREAM_COUNT
# Line 6218  Schoenebeck'> Line 6425  Schoenebeck'>
6425                  </t>                  </t>
6426                  <t>/ MISCELLANEOUS                  <t>/ MISCELLANEOUS
6427                  </t>                  </t>
6428                    <t>/ TOTAL_STREAM_COUNT
6429                    </t>
6430                  <t>/ TOTAL_VOICE_COUNT                  <t>/ TOTAL_VOICE_COUNT
6431                  </t>                  </t>
6432                  <t>/ GLOBAL_INFO                  <t>/ GLOBAL_INFO
# Line 6236  Schoenebeck'> Line 6445  Schoenebeck'>
6445                  </t>                  </t>
6446                  <t>/ CHANNEL_COUNT                  <t>/ CHANNEL_COUNT
6447                  </t>                  </t>
6448                    <t>/ CHANNEL_MIDI
6449                    </t>
6450                  <t>/ VOICE_COUNT                  <t>/ VOICE_COUNT
6451                  </t>                  </t>
6452                  <t>/ STREAM_COUNT                  <t>/ STREAM_COUNT
# Line 6268  Schoenebeck'> Line 6479  Schoenebeck'>
6479                  </t>                  </t>
6480                  <t>/ MISCELLANEOUS                  <t>/ MISCELLANEOUS
6481                  </t>                  </t>
6482                    <t>/ TOTAL_STREAM_COUNT
6483                    </t>
6484                  <t>/ TOTAL_VOICE_COUNT                  <t>/ TOTAL_VOICE_COUNT
6485                  </t>                  </t>
6486                  <t>/ GLOBAL_INFO                  <t>/ GLOBAL_INFO
# Line 6358  Schoenebeck'> Line 6571  Schoenebeck'>
6571                  </t>                  </t>
6572                  <t>/ SERVER SP INFO                  <t>/ SERVER SP INFO
6573                  </t>                  </t>
6574                    <t>/ TOTAL_STREAM_COUNT
6575                    </t>
6576                  <t>/ TOTAL_VOICE_COUNT                  <t>/ TOTAL_VOICE_COUNT
6577                  </t>                  </t>
6578                  <t>/ TOTAL_VOICE_COUNT_MAX                  <t>/ TOTAL_VOICE_COUNT_MAX
# Line 6392  Schoenebeck'> Line 6607  Schoenebeck'>
6607                  </t>                  </t>
6608                  <t>/ VOLUME                  <t>/ VOLUME
6609                  </t>                  </t>
6610                    <t>/ FILE SP INSTRUMENTS SP filename
6611                    </t>
6612                    <t>/ FILE SP INSTRUMENT SP INFO SP filename SP instrument_index
6613                    </t>
6614          </list>          </list>
6615  </t>  </t>
6616  <t>set_instruction =  <t>set_instruction =
# Line 6542  Schoenebeck'> Line 6761  Schoenebeck'>
6761  </t>  </t>
6762  <t>edit_instruction =  <t>edit_instruction =
6763          <list>          <list>
6764                  <t>INSTRUMENT SP sampler_channel                  <t>CHANNEL SP INSTRUMENT SP sampler_channel
6765                  </t>                  </t>
6766          </list>          </list>
6767  </t>  </t>
# Line 6606  Schoenebeck'> Line 6825  Schoenebeck'>
6825                  </t>                  </t>
6826                  <t>/ DB_INSTRUMENTS SP db_path                  <t>/ DB_INSTRUMENTS SP db_path
6827                  </t>                  </t>
6828                    <t>/ FILE SP INSTRUMENTS SP filename
6829                    </t>
6830          </list>          </list>
6831  </t>  </t>
6832  <t>load_instr_args =  <t>load_instr_args =
# Line 6865  Schoenebeck'> Line 7086  Schoenebeck'>
7086                      <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>
7087                      <t><xref target="COPY DB_INSTRUMENT">"COPY DB_INSTRUMENT"</xref></t>                      <t><xref target="COPY DB_INSTRUMENT">"COPY DB_INSTRUMENT"</xref></t>
7088                      <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>
7089                        <t><xref target="GET FILE INSTRUMENTS">"GET FILE INSTRUMENTS"</xref></t>
7090                        <t><xref target="LIST FILE INSTRUMENTS">"LIST FILE INSTRUMENTS"</xref></t>
7091                        <t><xref target="GET FILE INSTRUMENT INFO">"GET FILE INSTRUMENT INFO"</xref></t>
7092                  </list>                  </list>
7093                  Note that the forward slash character ('/') has a special meaning in                  Note that the forward slash character ('/') has a special meaning in
7094                  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 6875  Schoenebeck'> Line 7099  Schoenebeck'>
7099                  </t>                  </t>
7100    
7101                  <t>                  <t>
7102                    Note for Windows: file path arguments in LSCP are expected
7103                    to use forward slashes as directory node separator similar
7104                    to Unix based operating systems. In contrast to Unix however
7105                    a Windows typical drive character is expected to be
7106                    prefixed to the path. That is an original Windows file path
7107                    like "D:\Sounds\My.gig" would become in LSCP:
7108                    "D:/Sounds/My.gig".
7109                    </t>
7110    
7111                    <t>
7112                  The following LSCP commands even support escape sequences as                  The following LSCP commands even support escape sequences as
7113                  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,
7114                  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 7008  Schoenebeck'> Line 7242  Schoenebeck'>
7242                  of sampler channels.</t>                  of sampler channels.</t>
7243              </section>              </section>
7244    
7245                <section title="MIDI data on a sampler channel arrived" anchor="SUBSCRIBE CHANNEL_MIDI">
7246                    <t>Client may want to be notified when MIDI data arrive on sampler channels on
7247                    back-end side, by issuing the following command:</t>
7248                    <t>
7249                        <list>
7250                            <t>SUBSCRIBE CHANNEL_MIDI</t>
7251                        </list>
7252                    </t>
7253                    <t>Server will start sending one of the the following notification messages:</t>
7254                    <t>
7255                        <list>
7256                            <t>"NOTIFY:CHANNEL_MIDI:&lt;channel-id&gt; NOTE_ON  &lt;note&gt; &lt;velocity&gt;"</t>
7257                            <t>"NOTIFY:CHANNEL_MIDI:&lt;channel-id&gt; NOTE_OFF &lt;note&gt; &lt;velocity&gt;"</t>
7258                        </list>
7259                    </t>
7260                    <t>where &lt;channel-id&gt; will be replaced by the ID of the sampler channel where the MIDI
7261                    data arrived. &lt;note&gt; and &lt;velocity&gt; are integer values in the range between
7262                    0 .. 127, reflecting the analog meaning of the MIDI specification.
7263                    </t>
7264                    <t>CAUTION: no guarantee whatsoever will be made that MIDI events are actually all
7265                    delivered by this mechanism! With other words: events could be lost at any time!
7266                    This restriction was made to keep the RT-safeness of the backend's MIDI and audio
7267                    thread unaffected by this feature.</t>
7268                </section>
7269    
7270              <section title="Number of active voices changed" anchor="SUBSCRIBE VOICE_COUNT">              <section title="Number of active voices changed" anchor="SUBSCRIBE VOICE_COUNT">
7271                  <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
7272                  back-end changes by issuing the following command:</t>                  back-end changes by issuing the following command:</t>
# Line 7145  Schoenebeck'> Line 7404  Schoenebeck'>
7404                  all currently active voices.</t>                  all currently active voices.</t>
7405              </section>              </section>
7406    
7407                <section title="Total number of active disk streams changed" anchor="SUBSCRIBE TOTAL_STREAM_COUNT">
7408                    <t>Client may want to be notified when the total number of disk streams on the
7409                    back-end changes by issuing the following command:</t>
7410                    <t>
7411                        <list>
7412                            <t>SUBSCRIBE TOTAL_STREAM_COUNT</t>
7413                        </list>
7414                    </t>
7415                    <t>Server will start sending the following notification messages:</t>
7416                    <t>
7417                        <list>
7418                            <t>"NOTIFY:TOTAL_STREAM_COUNT:&lt;streams&gt;"</t>
7419                        </list>
7420                    </t>
7421                    <t>where &lt;streams&gt; will be replaced by the new number of
7422                    all currently active disk streams.</t>
7423                </section>
7424    
7425              <section title="Number of MIDI instrument maps changed" anchor="SUBSCRIBE MIDI_INSTRUMENT_MAP_COUNT">              <section title="Number of MIDI instrument maps changed" anchor="SUBSCRIBE MIDI_INSTRUMENT_MAP_COUNT">
7426                  <t>Client may want to be notified when the number of MIDI instrument maps on the                  <t>Client may want to be notified when the number of MIDI instrument maps on the
7427                  back-end changes by issuing the following command:</t>                  back-end changes by issuing the following command:</t>
Legend:
Removed from v.1401  
changed lines
  Added in v.1686
  ViewVC Help
Powered by ViewVC