/[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 1554 by schoenebeck, Thu Dec 6 01:38:31 2007 UTC revision 1771 by iliev, Wed Sep 10 15:02:24 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.3">  <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="December" 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 3711  Schoenebeck'> Line 3711  Schoenebeck'>
3711                      </t>                      </t>
3712                  </section>                  </section>
3713    
3714                    <section title="Sending MIDI messages to sampler channel" anchor="SEND CHANNEL MIDI_DATA">
3715                        <t>The front-end can send MIDI events to specific sampler channel
3716                        by sending the following command:</t>
3717                        <t>
3718                            <list>
3719                                <t>SEND CHANNEL MIDI_DATA &lt;midi-msg&gt; &lt;sampler-chan&gt; &lt;arg1&gt; &lt;arg2&gt;</t>
3720                            </list>
3721                        </t>
3722                        <t>Where &lt;sampler-chan&gt; is the sampler channel number
3723                        as returned by the <xref target="ADD CHANNEL">"ADD CHANNEL"</xref>
3724                        or <xref target="LIST CHANNELS">"LIST CHANNELS"</xref> command,
3725                        &lt;arg1&gt; and &lt;arg2&gt; arguments depend on the &lt;midi-msg&gt; argument, which
3726                        specifies the MIDI message type. Currently, the following MIDI messages are supported:</t>
3727                        <t>
3728                            <list>
3729                                <t>"NOTE_ON" -
3730                                    <list>
3731                                        <t>For turning on MIDI notes, where &lt;arg1&gt;
3732                                        specifies the key number and &lt;arg2&gt; the velocity
3733                                        as described in the MIDI specification.</t>
3734                                    </list>
3735                                </t>
3736                                <t>"NOTE_OFF" -
3737                                    <list>
3738                                        <t>For turning a currently playing MIDI note off, where &lt;arg1&gt;
3739                                        specifies the key number and &lt;arg2&gt; the velocity
3740                                        as described in the MIDI specification.</t>
3741                                    </list>
3742                                </t>
3743                            </list>
3744                        </t>
3745                        <t>CAUTION: This command is provided for implementations of virtual MIDI keyboards
3746                        and no realtime guarantee whatsoever will be made!</t>
3747                        <t>Possible Answers:</t>
3748                        <t>
3749                            <list>
3750                                <t>"OK" -
3751                                    <list>
3752                                        <t>on success</t>
3753                                    </list>
3754                                </t>
3755                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
3756                                    <list>
3757                                        <t>in case it failed, providing an appropriate error code and error message</t>
3758                                    </list>
3759                                </t>
3760                            </list>
3761                        </t>
3762                        <t>Example:</t>
3763                        <t>
3764                            <list>
3765                                <t>C: "SEND CHANNEL MIDI_DATA NOTE_ON 0 56 112"</t>
3766                                <t>S: "OK"</t>
3767                            </list>
3768                        </t>
3769                    </section>
3770    
3771                  <section title="Resetting a sampler channel" anchor="RESET CHANNEL">                  <section title="Resetting a sampler channel" anchor="RESET CHANNEL">
3772                      <t>The front-end can reset a particular sampler channel by sending the following command:</t>                      <t>The front-end can reset a particular sampler channel by sending the following command:</t>
3773                      <t>                      <t>
# Line 6003  Schoenebeck'> Line 6060  Schoenebeck'>
6060                      </t>                      </t>
6061                  </section>                  </section>
6062    
6063                    <section title="Checking for lost instrument files" anchor="FIND LOST DB_INSTRUMENT_FILES">
6064                        <t>The front-end can retrieve the list of all instrument files in the instruments database
6065                        that don't exist in the filesystem by sending the following command:</t>
6066                        <t>
6067                            <list>
6068                                <t>FIND LOST DB_INSTRUMENT_FILES</t>
6069                            </list>
6070                        </t>
6071    
6072                        <t>Possible Answers:</t>
6073                        <t>
6074                            <list>
6075                                <t>A comma separated list with the absolute path names
6076                                (encapsulated into apostrophes) of all lost instrument files.</t>
6077                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
6078                                    <list>
6079                                        <t>in case it failed, providing an appropriate error code and error message.</t>
6080                                    </list>
6081                                </t>
6082                            </list>
6083                        </t>
6084                        <t>Example:</t>
6085                        <t>
6086                            <list>
6087                                <t>C: "FIND LOST DB_INSTRUMENT_FILES"</t>
6088                                <t>S: "'/gigs/Bosendorfer 290.gig','/gigs/Steinway D.gig','/gigs/Free Piano.gig'"</t>
6089                            </list>
6090                        </t>
6091                    </section>
6092    
6093                    <section title="Replacing an instrument file" anchor="SET DB_INSTRUMENT FILE_PATH">
6094                        <t>The front-end can substitute all occurrences of an instrument file
6095                        in the instruments database with a new one by sending the following command:</t>
6096                        <t>
6097                            <list>
6098                                <t>SET DB_INSTRUMENT FILE_PATH &lt;old_path&gt; &lt;new_path&gt;</t>
6099                            </list>
6100                        </t>
6101                        <t>Where &lt;old_path&gt; is the absolute path name of the instrument file
6102                        to substitute with &lt;new_path&gt;.</t>
6103    
6104                        <t>Possible Answers:</t>
6105                        <t>
6106                            <list>
6107                                <t>"OK" -
6108                                    <list>
6109                                        <t>on success</t>
6110                                    </list>
6111                                </t>
6112                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
6113                                    <list>
6114                                        <t>in case it failed, providing an appropriate error code and error message.</t>
6115                                    </list>
6116                                </t>
6117                            </list>
6118                        </t>
6119    
6120                        <t>Example:</t>
6121                        <t>
6122                            <list>
6123                                <t>C: "SET DB_INSTRUMENT FILE_PATH '/gigs/Bosendorfer 290.gig' '/gigs/pianos/Bosendorfer 290.gig'"</t>
6124                                <t>S: "OK"</t>
6125                            </list>
6126                        </t>
6127                    </section>
6128    
6129              </section>              </section>
6130    
6131    
# Line 6241  Schoenebeck'> Line 6364  Schoenebeck'>
6364                                              vendor of the instrument</t>                                              vendor of the instrument</t>
6365                                          </list>                                          </list>
6366                                      </t>                                      </t>
6367                                        <t>KEY_BINDINGS -
6368                                            <list>
6369                                                <t>comma separated list of integer values representing
6370                                                   the instrument's key mapping in the range between 0 .. 127,
6371                                                   reflecting the analog meaning of the MIDI specification.</t>
6372                                            </list>
6373                                        </t>
6374                                        <t>KEYSWITCH_BINDINGS -
6375                                            <list>
6376                                                <t>comma separated list of integer values representing
6377                                                   the instrument's keyswitch mapping in the range between 0 .. 127,
6378                                                   reflecting the analog meaning of the MIDI specification.</t>
6379                                            </list>
6380                                        </t>
6381                                  </list>                                  </list>
6382                              </t>                              </t>
6383                          </list>                          </list>
# Line 6347  Schoenebeck'> Line 6484  Schoenebeck'>
6484                  </t>                  </t>
6485                  <t>/ EDIT SP edit_instruction                  <t>/ EDIT SP edit_instruction
6486                  </t>                  </t>
6487                  <t>/ FORMAT SP format_instruction                  <t>/ FORMAT SP format_instruction
6488                    </t>
6489                    <t>SEND SP send_instruction
6490                  </t>                  </t>
6491                  <t>/ RESET                  <t>/ RESET
6492                  </t>                  </t>
# Line 6391  Schoenebeck'> Line 6530  Schoenebeck'>
6530                  </t>                  </t>
6531                  <t>/ CHANNEL_COUNT                  <t>/ CHANNEL_COUNT
6532                  </t>                  </t>
6533                    <t>/ CHANNEL_MIDI
6534                    </t>
6535                    <t>/ DEVICE_MIDI
6536                    </t>
6537                  <t>/ VOICE_COUNT                  <t>/ VOICE_COUNT
6538                  </t>                  </t>
6539                  <t>/ STREAM_COUNT                  <t>/ STREAM_COUNT
# Line 6443  Schoenebeck'> Line 6586  Schoenebeck'>
6586                  </t>                  </t>
6587                  <t>/ CHANNEL_COUNT                  <t>/ CHANNEL_COUNT
6588                  </t>                  </t>
6589                    <t>/ CHANNEL_MIDI
6590                    </t>
6591                    <t>/ DEVICE_MIDI
6592                    </t>
6593                  <t>/ VOICE_COUNT                  <t>/ VOICE_COUNT
6594                  </t>                  </t>
6595                  <t>/ STREAM_COUNT                  <t>/ STREAM_COUNT
# Line 6641  Schoenebeck'> Line 6788  Schoenebeck'>
6788                  </t>                  </t>
6789                  <t>/ DB_INSTRUMENT SP DESCRIPTION SP db_path SP stringval_escaped                  <t>/ DB_INSTRUMENT SP DESCRIPTION SP db_path SP stringval_escaped
6790                  </t>                  </t>
6791                    <t>/ DB_INSTRUMENT SP FILE_PATH SP filename SP filename
6792                    </t>
6793                  <t>/ ECHO SP boolean                  <t>/ ECHO SP boolean
6794                  </t>                  </t>
6795                  <t>/ VOLUME SP volume_value                  <t>/ VOLUME SP volume_value
# Line 6687  Schoenebeck'> Line 6836  Schoenebeck'>
6836                  </t>                  </t>
6837                  <t>/ DB_INSTRUMENT_DIRECTORIES SP db_path SP query_val_list                  <t>/ DB_INSTRUMENT_DIRECTORIES SP db_path SP query_val_list
6838                  </t>                  </t>
6839                    <t>/ LOST SP DB_INSTRUMENT_FILES
6840                    </t>
6841          </list>          </list>
6842  </t>  </t>
6843  <t>move_instruction =  <t>move_instruction =
# Line 6825  Schoenebeck'> Line 6976  Schoenebeck'>
6976                  </t>                  </t>
6977          </list>          </list>
6978  </t>  </t>
6979    <t>send_instruction =
6980            <list>
6981                    <t>CHANNEL SP MIDI_DATA SP string SP sampler_channel SP number SP number
6982                    </t>
6983            </list>
6984    </t>
6985  <t>load_instr_args =  <t>load_instr_args =
6986          <list>          <list>
6987                  <t>filename SP instrument_index SP sampler_channel                  <t>filename SP instrument_index SP sampler_channel
# Line 7082  Schoenebeck'> Line 7239  Schoenebeck'>
7239                      <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>
7240                      <t><xref target="COPY DB_INSTRUMENT">"COPY DB_INSTRUMENT"</xref></t>                      <t><xref target="COPY DB_INSTRUMENT">"COPY DB_INSTRUMENT"</xref></t>
7241                      <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>
7242                        <t><xref target="FIND LOST DB_INSTRUMENT_FILES">"FIND LOST DB_INSTRUMENT_FILES"</xref></t>
7243                        <t><xref target="SET DB_INSTRUMENT FILE_PATH">"SET DB_INSTRUMENT FILE_PATH"</xref></t>
7244                      <t><xref target="GET FILE INSTRUMENTS">"GET FILE INSTRUMENTS"</xref></t>                      <t><xref target="GET FILE INSTRUMENTS">"GET FILE INSTRUMENTS"</xref></t>
7245                      <t><xref target="LIST FILE INSTRUMENTS">"LIST FILE INSTRUMENTS"</xref></t>                      <t><xref target="LIST FILE INSTRUMENTS">"LIST FILE INSTRUMENTS"</xref></t>
7246                      <t><xref target="GET FILE INSTRUMENT INFO">"GET FILE INSTRUMENT INFO"</xref></t>                      <t><xref target="GET FILE INSTRUMENT INFO">"GET FILE INSTRUMENT INFO"</xref></t>
# Line 7238  Schoenebeck'> Line 7397  Schoenebeck'>
7397                  of sampler channels.</t>                  of sampler channels.</t>
7398              </section>              </section>
7399    
7400                <section title="MIDI data on a sampler channel arrived" anchor="SUBSCRIBE CHANNEL_MIDI">
7401                    <t>Client may want to be notified when MIDI data arrive on sampler channels on
7402                    back-end side, by issuing the following command:</t>
7403                    <t>
7404                        <list>
7405                            <t>SUBSCRIBE CHANNEL_MIDI</t>
7406                        </list>
7407                    </t>
7408                    <t>Server will start sending one of the the following notification messages:</t>
7409                    <t>
7410                        <list>
7411                            <t>"NOTIFY:CHANNEL_MIDI:&lt;channel-id&gt; NOTE_ON  &lt;note&gt; &lt;velocity&gt;"</t>
7412                            <t>"NOTIFY:CHANNEL_MIDI:&lt;channel-id&gt; NOTE_OFF &lt;note&gt; &lt;velocity&gt;"</t>
7413                        </list>
7414                    </t>
7415                    <t>where &lt;channel-id&gt; will be replaced by the ID of the sampler channel where the MIDI
7416                    data arrived. &lt;note&gt; and &lt;velocity&gt; are integer values in the range between
7417                    0 .. 127, reflecting the analog meaning of the MIDI specification.
7418                    </t>
7419                    <t>CAUTION: no guarantee whatsoever will be made that MIDI events are actually all
7420                    delivered by this mechanism! With other words: events could be lost at any time!
7421                    This restriction was made to keep the RT-safeness of the backend's MIDI and audio
7422                    thread unaffected by this feature.</t>
7423                </section>
7424    
7425                <section title="MIDI data on a MIDI input device arrived" anchor="SUBSCRIBE DEVICE_MIDI">
7426                        <t>Client may want to be notified when MIDI data arrive on MIDI input devices by issuing the following command:</t>
7427                        <t>
7428                                <list>
7429                                        <t>SUBSCRIBE DEVICE_MIDI</t>
7430                                </list>
7431                        </t>
7432                        <t>Server will start sending one of the the following notification messages:</t>
7433                        <t>
7434                                <list>
7435                                        <t>"NOTIFY:DEVICE_MIDI:&lt;device-id&gt; &lt;port-id&gt; NOTE_ON &lt;note&gt; &lt;velocity&gt;"</t>
7436                                        <t>"NOTIFY:DEVICE_MIDI:&lt;device-id&gt; &lt;port-id&gt; NOTE_OFF &lt;note&gt; &lt;velocity&gt;"</t>
7437                                </list>
7438                        </t>
7439                        <t>where &lt;device-id&gt; &lt;port-id&gt; will be replaced
7440                           by the IDs of the respective MIDI input device and the device's MIDI port where the MIDI
7441                           data arrived. &lt;note&gt; and &lt;velocity&gt; are integer values in the range between
7442                           0 .. 127, reflecting the analog meaning of the MIDI specification.
7443                        </t>
7444                        <t>CAUTION: no guarantee whatsoever will be made that MIDI events are actually all
7445                           delivered by this mechanism! With other words: events could be lost at any time!
7446                           This restriction was made to keep the RT-safeness of the backend's MIDI and audio
7447                           thread unaffected by this feature.</t>
7448                </section>
7449    
7450              <section title="Number of active voices changed" anchor="SUBSCRIBE VOICE_COUNT">              <section title="Number of active voices changed" anchor="SUBSCRIBE VOICE_COUNT">
7451                  <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
7452                  back-end changes by issuing the following command:</t>                  back-end changes by issuing the following command:</t>
Legend:
Removed from v.1554  
changed lines
  Added in v.1771
  ViewVC Help
Powered by ViewVC