/[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 1782 by iliev, Tue Sep 30 02:16:41 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="September" 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 5293  Schoenebeck'> Line 5350  Schoenebeck'>
5350                      to the instruments database by sending the following command:</t>                      to the instruments database by sending the following command:</t>
5351                      <t>                      <t>
5352                          <list>                          <list>
5353                              <t>ADD DB_INSTRUMENTS [NON_MODAL] [&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;[ FILE_AS_DIR]] &lt;db_dir&gt; &lt;file_path&gt; [&lt;instr_index&gt;]</t>
5354                          </list>                          </list>
5355                      </t>                      </t>
5356                      <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 5338  Schoenebeck'> Line 5395  Schoenebeck'>
5395                          </list>                          </list>
5396                      </t>                      </t>
5397    
5398                     <t> If FILE_AS_DIR argument is supplied, all instruments in an instrument
5399                     file will be added to a separate directory in the instruments database, which
5400                     name will be the name of the instrument file with the file extension stripped off.
5401                     </t>
5402                   <t>The difference between regular and NON_MODAL versions of the command                   <t>The difference between regular and NON_MODAL versions of the command
5403                      is that the regular command returns when the scanning is finished                      is that the regular command returns when the scanning is finished
5404                      while NON_MODAL version returns immediately and a background process is launched.                      while NON_MODAL version returns immediately and a background process is launched.
# Line 6003  Schoenebeck'> Line 6064  Schoenebeck'>
6064                      </t>                      </t>
6065                  </section>                  </section>
6066    
6067                    <section title="Checking for lost instrument files" anchor="FIND LOST DB_INSTRUMENT_FILES">
6068                        <t>The front-end can retrieve the list of all instrument files in the instruments database
6069                        that don't exist in the filesystem by sending the following command:</t>
6070                        <t>
6071                            <list>
6072                                <t>FIND LOST DB_INSTRUMENT_FILES</t>
6073                            </list>
6074                        </t>
6075    
6076                        <t>Possible Answers:</t>
6077                        <t>
6078                            <list>
6079                                <t>A comma separated list with the absolute path names
6080                                (encapsulated into apostrophes) of all lost instrument files.</t>
6081                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
6082                                    <list>
6083                                        <t>in case it failed, providing an appropriate error code and error message.</t>
6084                                    </list>
6085                                </t>
6086                            </list>
6087                        </t>
6088                        <t>Example:</t>
6089                        <t>
6090                            <list>
6091                                <t>C: "FIND LOST DB_INSTRUMENT_FILES"</t>
6092                                <t>S: "'/gigs/Bosendorfer 290.gig','/gigs/Steinway D.gig','/gigs/Free Piano.gig'"</t>
6093                            </list>
6094                        </t>
6095                    </section>
6096    
6097                    <section title="Replacing an instrument file" anchor="SET DB_INSTRUMENT FILE_PATH">
6098                        <t>The front-end can substitute all occurrences of an instrument file
6099                        in the instruments database with a new one by sending the following command:</t>
6100                        <t>
6101                            <list>
6102                                <t>SET DB_INSTRUMENT FILE_PATH &lt;old_path&gt; &lt;new_path&gt;</t>
6103                            </list>
6104                        </t>
6105                        <t>Where &lt;old_path&gt; is the absolute path name of the instrument file
6106                        to substitute with &lt;new_path&gt;.</t>
6107    
6108                        <t>Possible Answers:</t>
6109                        <t>
6110                            <list>
6111                                <t>"OK" -
6112                                    <list>
6113                                        <t>on success</t>
6114                                    </list>
6115                                </t>
6116                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
6117                                    <list>
6118                                        <t>in case it failed, providing an appropriate error code and error message.</t>
6119                                    </list>
6120                                </t>
6121                            </list>
6122                        </t>
6123    
6124                        <t>Example:</t>
6125                        <t>
6126                            <list>
6127                                <t>C: "SET DB_INSTRUMENT FILE_PATH '/gigs/Bosendorfer 290.gig' '/gigs/pianos/Bosendorfer 290.gig'"</t>
6128                                <t>S: "OK"</t>
6129                            </list>
6130                        </t>
6131                    </section>
6132    
6133              </section>              </section>
6134    
6135    
# Line 6241  Schoenebeck'> Line 6368  Schoenebeck'>
6368                                              vendor of the instrument</t>                                              vendor of the instrument</t>
6369                                          </list>                                          </list>
6370                                      </t>                                      </t>
6371                                        <t>KEY_BINDINGS -
6372                                            <list>
6373                                                <t>comma separated list of integer values representing
6374                                                   the instrument's key mapping in the range between 0 .. 127,
6375                                                   reflecting the analog meaning of the MIDI specification.</t>
6376                                            </list>
6377                                        </t>
6378                                        <t>KEYSWITCH_BINDINGS -
6379                                            <list>
6380                                                <t>comma separated list of integer values representing
6381                                                   the instrument's keyswitch mapping in the range between 0 .. 127,
6382                                                   reflecting the analog meaning of the MIDI specification.</t>
6383                                            </list>
6384                                        </t>
6385                                  </list>                                  </list>
6386                              </t>                              </t>
6387                          </list>                          </list>
# Line 6349  Schoenebeck'> Line 6490  Schoenebeck'>
6490                  </t>                  </t>
6491                  <t>/ FORMAT SP format_instruction                  <t>/ FORMAT SP format_instruction
6492                  </t>                  </t>
6493                    <t>/ SEND SP send_instruction
6494                    </t>
6495                  <t>/ RESET                  <t>/ RESET
6496                  </t>                  </t>
6497                  <t>/ QUIT                  <t>/ QUIT
# Line 6363  Schoenebeck'> Line 6506  Schoenebeck'>
6506                  </t>                  </t>
6507                  <t>/ DB_INSTRUMENTS SP NON_MODAL SP scan_mode SP db_path SP filename                  <t>/ DB_INSTRUMENTS SP NON_MODAL SP scan_mode SP db_path SP filename
6508                  </t>                  </t>
6509                    <t>/ DB_INSTRUMENTS SP NON_MODAL SP scan_mode SP FILE_AS_DIR SP db_path SP filename
6510                    </t>
6511                  <t>/ DB_INSTRUMENTS SP scan_mode SP db_path SP filename                  <t>/ DB_INSTRUMENTS SP scan_mode SP db_path SP filename
6512                  </t>                  </t>
6513                    <t>/ DB_INSTRUMENTS SP scan_mode SP FILE_AS_DIR SP db_path SP filename
6514                    </t>
6515                  <t>/ DB_INSTRUMENTS SP NON_MODAL SP db_path SP filename                  <t>/ DB_INSTRUMENTS SP NON_MODAL SP db_path SP filename
6516                  </t>                  </t>
6517                  <t>/ DB_INSTRUMENTS SP NON_MODAL SP db_path SP filename SP instrument_index                  <t>/ DB_INSTRUMENTS SP NON_MODAL SP db_path SP filename SP instrument_index
# Line 6391  Schoenebeck'> Line 6538  Schoenebeck'>
6538                  </t>                  </t>
6539                  <t>/ CHANNEL_COUNT                  <t>/ CHANNEL_COUNT
6540                  </t>                  </t>
6541                    <t>/ CHANNEL_MIDI
6542                    </t>
6543                    <t>/ DEVICE_MIDI
6544                    </t>
6545                  <t>/ VOICE_COUNT                  <t>/ VOICE_COUNT
6546                  </t>                  </t>
6547                  <t>/ STREAM_COUNT                  <t>/ STREAM_COUNT
# Line 6443  Schoenebeck'> Line 6594  Schoenebeck'>
6594                  </t>                  </t>
6595                  <t>/ CHANNEL_COUNT                  <t>/ CHANNEL_COUNT
6596                  </t>                  </t>
6597                    <t>/ CHANNEL_MIDI
6598                    </t>
6599                    <t>/ DEVICE_MIDI
6600                    </t>
6601                  <t>/ VOICE_COUNT                  <t>/ VOICE_COUNT
6602                  </t>                  </t>
6603                  <t>/ STREAM_COUNT                  <t>/ STREAM_COUNT
# Line 6641  Schoenebeck'> Line 6796  Schoenebeck'>
6796                  </t>                  </t>
6797                  <t>/ DB_INSTRUMENT SP DESCRIPTION SP db_path SP stringval_escaped                  <t>/ DB_INSTRUMENT SP DESCRIPTION SP db_path SP stringval_escaped
6798                  </t>                  </t>
6799                    <t>/ DB_INSTRUMENT SP FILE_PATH SP filename SP filename
6800                    </t>
6801                  <t>/ ECHO SP boolean                  <t>/ ECHO SP boolean
6802                  </t>                  </t>
6803                  <t>/ VOLUME SP volume_value                  <t>/ VOLUME SP volume_value
# Line 6687  Schoenebeck'> Line 6844  Schoenebeck'>
6844                  </t>                  </t>
6845                  <t>/ DB_INSTRUMENT_DIRECTORIES SP db_path SP query_val_list                  <t>/ DB_INSTRUMENT_DIRECTORIES SP db_path SP query_val_list
6846                  </t>                  </t>
6847                    <t>/ LOST SP DB_INSTRUMENT_FILES
6848                    </t>
6849          </list>          </list>
6850  </t>  </t>
6851  <t>move_instruction =  <t>move_instruction =
# Line 6825  Schoenebeck'> Line 6984  Schoenebeck'>
6984                  </t>                  </t>
6985          </list>          </list>
6986  </t>  </t>
6987    <t>send_instruction =
6988            <list>
6989                    <t>CHANNEL SP MIDI_DATA SP string SP sampler_channel SP number SP number
6990                    </t>
6991            </list>
6992    </t>
6993  <t>load_instr_args =  <t>load_instr_args =
6994          <list>          <list>
6995                  <t>filename SP instrument_index SP sampler_channel                  <t>filename SP instrument_index SP sampler_channel
# Line 7082  Schoenebeck'> Line 7247  Schoenebeck'>
7247                      <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>
7248                      <t><xref target="COPY DB_INSTRUMENT">"COPY DB_INSTRUMENT"</xref></t>                      <t><xref target="COPY DB_INSTRUMENT">"COPY DB_INSTRUMENT"</xref></t>
7249                      <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>
7250                        <t><xref target="FIND LOST DB_INSTRUMENT_FILES">"FIND LOST DB_INSTRUMENT_FILES"</xref></t>
7251                        <t><xref target="SET DB_INSTRUMENT FILE_PATH">"SET DB_INSTRUMENT FILE_PATH"</xref></t>
7252                      <t><xref target="GET FILE INSTRUMENTS">"GET FILE INSTRUMENTS"</xref></t>                      <t><xref target="GET FILE INSTRUMENTS">"GET FILE INSTRUMENTS"</xref></t>
7253                      <t><xref target="LIST FILE INSTRUMENTS">"LIST FILE INSTRUMENTS"</xref></t>                      <t><xref target="LIST FILE INSTRUMENTS">"LIST FILE INSTRUMENTS"</xref></t>
7254                      <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 7405  Schoenebeck'>
7405                  of sampler channels.</t>                  of sampler channels.</t>
7406              </section>              </section>
7407    
7408                <section title="MIDI data on a sampler channel arrived" anchor="SUBSCRIBE CHANNEL_MIDI">
7409                    <t>Client may want to be notified when MIDI data arrive on sampler channels on
7410                    back-end side, by issuing the following command:</t>
7411                    <t>
7412                        <list>
7413                            <t>SUBSCRIBE CHANNEL_MIDI</t>
7414                        </list>
7415                    </t>
7416                    <t>Server will start sending one of the the following notification messages:</t>
7417                    <t>
7418                        <list>
7419                            <t>"NOTIFY:CHANNEL_MIDI:&lt;channel-id&gt; NOTE_ON  &lt;note&gt; &lt;velocity&gt;"</t>
7420                            <t>"NOTIFY:CHANNEL_MIDI:&lt;channel-id&gt; NOTE_OFF &lt;note&gt; &lt;velocity&gt;"</t>
7421                        </list>
7422                    </t>
7423                    <t>where &lt;channel-id&gt; will be replaced by the ID of the sampler channel where the MIDI
7424                    data arrived. &lt;note&gt; and &lt;velocity&gt; are integer values in the range between
7425                    0 .. 127, reflecting the analog meaning of the MIDI specification.
7426                    </t>
7427                    <t>CAUTION: no guarantee whatsoever will be made that MIDI events are actually all
7428                    delivered by this mechanism! With other words: events could be lost at any time!
7429                    This restriction was made to keep the RT-safeness of the backend's MIDI and audio
7430                    thread unaffected by this feature.</t>
7431                </section>
7432    
7433                <section title="MIDI data on a MIDI input device arrived" anchor="SUBSCRIBE DEVICE_MIDI">
7434                        <t>Client may want to be notified when MIDI data arrive on MIDI input devices by issuing the following command:</t>
7435                        <t>
7436                                <list>
7437                                        <t>SUBSCRIBE DEVICE_MIDI</t>
7438                                </list>
7439                        </t>
7440                        <t>Server will start sending one of the the following notification messages:</t>
7441                        <t>
7442                                <list>
7443                                        <t>"NOTIFY:DEVICE_MIDI:&lt;device-id&gt; &lt;port-id&gt; NOTE_ON &lt;note&gt; &lt;velocity&gt;"</t>
7444                                        <t>"NOTIFY:DEVICE_MIDI:&lt;device-id&gt; &lt;port-id&gt; NOTE_OFF &lt;note&gt; &lt;velocity&gt;"</t>
7445                                </list>
7446                        </t>
7447                        <t>where &lt;device-id&gt; &lt;port-id&gt; will be replaced
7448                           by the IDs of the respective MIDI input device and the device's MIDI port where the MIDI
7449                           data arrived. &lt;note&gt; and &lt;velocity&gt; are integer values in the range between
7450                           0 .. 127, reflecting the analog meaning of the MIDI specification.
7451                        </t>
7452                        <t>CAUTION: no guarantee whatsoever will be made that MIDI events are actually all
7453                           delivered by this mechanism! With other words: events could be lost at any time!
7454                           This restriction was made to keep the RT-safeness of the backend's MIDI and audio
7455                           thread unaffected by this feature.</t>
7456                </section>
7457    
7458              <section title="Number of active voices changed" anchor="SUBSCRIBE VOICE_COUNT">              <section title="Number of active voices changed" anchor="SUBSCRIBE VOICE_COUNT">
7459                  <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
7460                  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.1782
  ViewVC Help
Powered by ViewVC