/[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 1187 by iliev, Wed May 16 14:22:26 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 5202  Schoenebeck'> Line 5218  Schoenebeck'>
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 5220  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 5236  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 5677  Schoenebeck'> Line 5707  Schoenebeck'>
5707    
5708                        <t>SIZE=[&lt;min&gt;]..[&lt;max&gt;]                        <t>SIZE=[&lt;min&gt;]..[&lt;max&gt;]
5709                            <list>                            <list>
5710                                <t>Restricts the search to instruments, which                                <t>Restricts the search to instruments, which
5711                                size is in the specified range. If &lt;min&gt; is omitted,                                size is in the specified range. If &lt;min&gt; is omitted,
5712                                the search results are restricted to instruments with size less then                                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                                or equal to &lt;max&gt;. If &lt;max&gt; is omitted, the
# Line 5740  Schoenebeck'> Line 5770  Schoenebeck'>
5770    
5771                        <t>IS_DRUM=true | false                        <t>IS_DRUM=true | false
5772                            <list>                            <list>
5773                                <t>Either true or false. Restricts the search to                                <t>Either true or false. Restricts the search to
5774                                drum kits or chromatic instruments.</t>                                drum kits or chromatic instruments.</t>
5775                            </list>                            </list>
5776                        </t>                        </t>
# Line 5784  Schoenebeck'> Line 5814  Schoenebeck'>
5814                      </t>                      </t>
5815                  </section>                  </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 5871  Schoenebeck'> Line 5965  Schoenebeck'>
5965                  </t>                  </t>
5966                  <t>/ COPY SP copy_instruction                  <t>/ COPY SP copy_instruction
5967                  </t>                  </t>
5968                    <t>/ EDIT SP edit_instruction
5969                    </t>
5970                  <t>/ RESET                  <t>/ RESET
5971                  </t>                  </t>
5972                  <t>/ QUIT                  <t>/ QUIT
# Line 5883  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>                  </t>
5986                  <t>/ DB_INSTRUMENTS SP NON_RECURSIVE SP pathname SP pathname                  <t>/ DB_INSTRUMENTS SP NON_MODAL SP pathname SP pathname
5987                    </t>
5988                    <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 5937  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 5985  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 6107  Schoenebeck'> Line 6211  Schoenebeck'>
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 6119  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 6255  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 6443  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 6501  Schoenebeck'> Line 6615  Schoenebeck'>
6615                  </t>                  </t>
6616          </list>          </list>
6617  </t>  </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 6688  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 6948  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 7026  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.1187  
changed lines
  Added in v.1296
  ViewVC Help
Powered by ViewVC