/[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 1727 by iliev, Tue Apr 29 15:44:09 2008 UTC revision 2025 by schoenebeck, Sun Nov 1 18:47:59 2009 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.4">  <rfc category="std" ipr="full3978" docName="LSCP 1.5">
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="April" year="2008"/>          <date month="November" year="2009"/>
38          <workgroup>LinuxSampler Developers</workgroup>          <workgroup>LinuxSampler Developers</workgroup>
39          <keyword>LSCP</keyword>          <keyword>LSCP</keyword>
40          <abstract>          <abstract>
# Line 2512  Schoenebeck'> Line 2512  Schoenebeck'>
2512                                          <list>                                          <list>
2513                                              <t>numerical ID of the audio output device which is                                              <t>numerical ID of the audio output device which is
2514                                              currently connected to this sampler channel to output                                              currently connected to this sampler channel to output
2515                                              the audio signal, "NONE" if there's no device                                              the audio signal, "-1" if there's no device
2516                                              connected to this sampler channel</t>                                              connected to this sampler channel</t>
2517                                          </list>                                          </list>
2518                                      </t>                                      </t>
# Line 2543  Schoenebeck'> Line 2543  Schoenebeck'>
2543                                      </t>                                      </t>
2544                                      <t>INSTRUMENT_NR -                                      <t>INSTRUMENT_NR -
2545                                          <list>                                          <list>
2546                                              <t>the instrument index number of the loaded instrument</t>                                              <t>the instrument index number of the loaded instrument,
2547                                                "-1" if there's no instrument loaded for this sampler
2548                                                channel</t>
2549                                          </list>                                          </list>
2550                                      </t>                                      </t>
2551                                      <t>INSTRUMENT_NAME -                                      <t>INSTRUMENT_NAME -
# Line 2555  Schoenebeck'> Line 2557  Schoenebeck'>
2557                                      </t>                                      </t>
2558                                      <t>INSTRUMENT_STATUS -                                      <t>INSTRUMENT_STATUS -
2559                                          <list>                                          <list>
2560                                              <t>integer values 0 to 100 indicating loading progress percentage for the instrument. Negative                                              <t>Integer values 0 to 100 indicating loading progress
2561                                              value indicates a loading exception. Value of 100 indicates that the instrument is fully                                              percentage for the instrument. Negative
2562                                                value indicates a loading exception (also returns "-1" in case no
2563                                                instrument was yet to be loaded on the sampler channel).
2564                                                Value of 100 indicates that the instrument is fully
2565                                              loaded.</t>                                              loaded.</t>
2566                                          </list>                                          </list>
2567                                      </t>                                      </t>
# Line 2564  Schoenebeck'> Line 2569  Schoenebeck'>
2569                                          <list>                                          <list>
2570                                              <t>numerical ID of the MIDI input device which is                                              <t>numerical ID of the MIDI input device which is
2571                                              currently connected to this sampler channel to deliver                                              currently connected to this sampler channel to deliver
2572                                              MIDI input commands, "NONE" if there's no device                                              MIDI input commands, "-1" if there's no device
2573                                              connected to this sampler channel</t>                                              connected to this sampler channel</t>
2574                                          </list>                                          </list>
2575                                      </t>                                      </t>
2576                                      <t>MIDI_INPUT_PORT -                                      <t>MIDI_INPUT_PORT -
2577                                          <list>                                          <list>
2578                                              <t>port number of the MIDI input device</t>                                              <t>port number of the MIDI input device (in case a
2579                                                MIDI device was already assigned to the sampler
2580                                                channel)</t>
2581                                          </list>                                          </list>
2582                                      </t>                                      </t>
2583                                      <t>MIDI_INPUT_CHANNEL -                                      <t>MIDI_INPUT_CHANNEL -
# Line 3711  Schoenebeck'> Line 3718  Schoenebeck'>
3718                      </t>                      </t>
3719                  </section>                  </section>
3720    
3721                    <section title="Sending MIDI messages to sampler channel" anchor="SEND CHANNEL MIDI_DATA">
3722                        <t>The front-end can send MIDI events to a specific sampler channel
3723                        by sending the following command:</t>
3724                        <t>
3725                            <list>
3726                                <t>SEND CHANNEL MIDI_DATA &lt;midi-msg&gt; &lt;sampler-chan&gt; &lt;arg1&gt; &lt;arg2&gt;</t>
3727                            </list>
3728                        </t>
3729                        <t>Where &lt;sampler-chan&gt; is the sampler channel number
3730                        as returned by the <xref target="ADD CHANNEL">"ADD CHANNEL"</xref>
3731                        or <xref target="LIST CHANNELS">"LIST CHANNELS"</xref> command,
3732                        &lt;arg1&gt; and &lt;arg2&gt; arguments depend on the &lt;midi-msg&gt; argument, which
3733                        specifies the MIDI message type. Currently, the following MIDI messages are supported:</t>
3734                        <t>
3735                            <list>
3736                                <t>"NOTE_ON" -
3737                                    <list>
3738                                        <t>For turning on MIDI notes, 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                                <t>"NOTE_OFF" -
3744                                    <list>
3745                                        <t>For turning a currently playing MIDI note off, where &lt;arg1&gt;
3746                                        specifies the key number and &lt;arg2&gt; the velocity
3747                                        as described in the MIDI specification.</t>
3748                                    </list>
3749                                </t>
3750                                <t>"CC" -
3751                                    <list>
3752                                        <t>For changing a MIDI controller, where &lt;arg1&gt;
3753                                        specifies the controller number and &lt;arg2&gt; the
3754                                        new value of the controller as described in the Control
3755                                        Change section of the MIDI specification.</t>
3756                                    </list>
3757                                </t>
3758                            </list>
3759                        </t>
3760                        <t>CAUTION: This command is provided for implementations of virtual MIDI keyboards
3761                        and no realtime guarantee whatsoever will be made!</t>
3762                        <t>Possible Answers:</t>
3763                        <t>
3764                            <list>
3765                                <t>"OK" -
3766                                    <list>
3767                                        <t>on success</t>
3768                                    </list>
3769                                </t>
3770                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
3771                                    <list>
3772                                        <t>in case it failed, providing an appropriate error code and error message</t>
3773                                    </list>
3774                                </t>
3775                            </list>
3776                        </t>
3777                        <t>Example:</t>
3778                        <t>
3779                            <list>
3780                                <t>C: "SEND CHANNEL MIDI_DATA NOTE_ON 0 56 112"</t>
3781                                <t>S: "OK"</t>
3782                            </list>
3783                        </t>
3784                    </section>
3785    
3786                  <section title="Resetting a sampler channel" anchor="RESET CHANNEL">                  <section title="Resetting a sampler channel" anchor="RESET CHANNEL">
3787                      <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>
3788                      <t>                      <t>
# Line 4085  Schoenebeck'> Line 4157  Schoenebeck'>
4157                          </list>                          </list>
4158                      </t>                      </t>
4159                  </section>                  </section>
4160    
4161                    <section title="Getting global voice limit" anchor="GET VOICES">
4162                        <t>The client can ask for the current global sampler-wide limit
4163                           for maximum voices by sending the following command:</t>
4164                        <t>
4165                            <list>
4166                                <t>GET VOICES</t>
4167                            </list>
4168                        </t>
4169                        <t>Possible Answers:</t>
4170                        <t>
4171                            <list>
4172                                <t>LinuxSampler will answer by returning the number for
4173                                   the current limit of maximum voices.</t>
4174                            </list>
4175                        </t>
4176    
4177                        <t>The voice limit setting defines how many voices should maximum
4178                           be processed by the sampler at the same time. If the user
4179                           triggers new notes which would exceed that voice limit, the
4180                           sampler engine will react by stealing old voices for those
4181                           newly triggered notes. Note that the amount of voices triggered
4182                           by a new note can be larger than one and is dependent to the
4183                           respective instrument and probably further criterias.</t>
4184                    </section>
4185    
4186                    <section title="Setting global voice limit" anchor="SET VOICES">
4187                        <t>The client can alter the current global sampler-wide limit
4188                        for maximum voices by sending the following command:</t>
4189                        <t>
4190                            <list>
4191                                <t>SET VOICES &lt;max-voices&gt;</t>
4192                            </list>
4193                        </t>
4194                       <t>Where &lt;max-voices&gt; should be replaced by the integer
4195                       value, reflecting the new global amount limit of maximum voices.
4196                       This value has to be larger than 0.</t>
4197    
4198                        <t>Possible Answers:</t>
4199                        <t>
4200                            <list>
4201                                <t>"OK" -
4202                                    <list>
4203                                        <t>on success</t>
4204                                    </list>
4205                                </t>
4206                                <t>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
4207                                    <list>
4208                                        <t>if the voice limit was set, but there are noteworthy
4209                                        issue(s) related, providing an appropriate warning code and
4210                                        warning message</t>
4211                                    </list>
4212                                </t>
4213                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
4214                                    <list>
4215                                        <t>in case it failed, providing an appropriate error code and error message</t>
4216                                    </list>
4217                                </t>
4218                            </list>
4219                        </t>
4220    
4221                        <t>Note: the given value will be passed to all sampler engine instances.
4222                           The total amount of maximum voices on the running system might thus
4223                           be as big as the given value multiplied by the current amount of engine
4224                           instances.</t>
4225    
4226                         <t>Caution: when adjusting the voice limit, you SHOULD also
4227                            adjust the disk stream limit respectively and vice versa.</t>
4228                    </section>
4229    
4230                    <section title="Getting global disk stream limit" anchor="GET STREAMS">
4231                        <t>The client can ask for the current global sampler-wide limit
4232                           for maximum disk streams by sending the following command:</t>
4233                        <t>
4234                            <list>
4235                                <t>GET STREAMS</t>
4236                            </list>
4237                        </t>
4238                        <t>Possible Answers:</t>
4239                        <t>
4240                            <list>
4241                                <t>LinuxSampler will answer by returning the number for
4242                                   the current limit of maximum disk streams.</t>
4243                            </list>
4244                        </t>
4245    
4246                        <t>The disk stream limit setting defines how many disk streams should
4247                           maximum be processed by a sampler engine at the same time. The
4248                           higher this value, the more memory (RAM) will be occupied, since
4249                           every disk streams allocates a certain buffer size for being able
4250                           to perform its streaming operations.</t>
4251                    </section>
4252    
4253                    <section title="Setting global disk stream limit" anchor="SET STREAMS">
4254                        <t>The client can alter the current global sampler-wide limit
4255                        for maximum disk streams by sending the following command:</t>
4256                        <t>
4257                            <list>
4258                                <t>SET STREAMS &lt;max-streams&gt;</t>
4259                            </list>
4260                        </t>
4261                       <t>Where &lt;max-streams&gt; should be replaced by the integer
4262                       value, reflecting the new global amount limit of maximum disk streams.
4263                       This value has to be positive.</t>
4264    
4265                        <t>Possible Answers:</t>
4266                        <t>
4267                            <list>
4268                                <t>"OK" -
4269                                    <list>
4270                                        <t>on success</t>
4271                                    </list>
4272                                </t>
4273                                <t>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
4274                                    <list>
4275                                        <t>if the disk stream limit was set, but there are noteworthy
4276                                        issue(s) related, providing an appropriate warning code and
4277                                        warning message</t>
4278                                    </list>
4279                                </t>
4280                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
4281                                    <list>
4282                                        <t>in case it failed, providing an appropriate error code and error message</t>
4283                                    </list>
4284                                </t>
4285                            </list>
4286                        </t>
4287    
4288                        <t>Note: the given value will be passed to all sampler engine instances.
4289                           The total amount of maximum disk streams on the running system might
4290                           thus be as big as the given value multiplied by the current amount of
4291                           engine instances.</t>
4292    
4293                         <t>Caution: when adjusting the disk stream limit, you SHOULD also
4294                            adjust the voice limit respectively and vice versa.</t>
4295                    </section>
4296    
4297              </section>              </section>
4298    
4299    
# Line 5293  Schoenebeck'> Line 5502  Schoenebeck'>
5502                      to the instruments database by sending the following command:</t>                      to the instruments database by sending the following command:</t>
5503                      <t>                      <t>
5504                          <list>                          <list>
5505                              <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>
5506                          </list>                          </list>
5507                      </t>                      </t>
5508                      <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 5547  Schoenebeck'>
5547                          </list>                          </list>
5548                      </t>                      </t>
5549    
5550                     <t> If FILE_AS_DIR argument is supplied, all instruments in an instrument
5551                     file will be added to a separate directory in the instruments database, which
5552                     name will be the name of the instrument file with the file extension stripped off.
5553                     </t>
5554                   <t>The difference between regular and NON_MODAL versions of the command                   <t>The difference between regular and NON_MODAL versions of the command
5555                      is that the regular command returns when the scanning is finished                      is that the regular command returns when the scanning is finished
5556                      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 6307  Schoenebeck'> Line 6520  Schoenebeck'>
6520                                              vendor of the instrument</t>                                              vendor of the instrument</t>
6521                                          </list>                                          </list>
6522                                      </t>                                      </t>
6523                                        <t>KEY_BINDINGS -
6524                                            <list>
6525                                                <t>comma separated list of integer values representing
6526                                                   the instrument's key mapping in the range between 0 .. 127,
6527                                                   reflecting the analog meaning of the MIDI specification.</t>
6528                                            </list>
6529                                        </t>
6530                                        <t>KEYSWITCH_BINDINGS -
6531                                            <list>
6532                                                <t>comma separated list of integer values representing
6533                                                   the instrument's keyswitch mapping in the range between 0 .. 127,
6534                                                   reflecting the analog meaning of the MIDI specification.</t>
6535                                            </list>
6536                                        </t>
6537                                  </list>                                  </list>
6538                              </t>                              </t>
6539                          </list>                          </list>
# Line 6415  Schoenebeck'> Line 6642  Schoenebeck'>
6642                  </t>                  </t>
6643                  <t>/ FORMAT SP format_instruction                  <t>/ FORMAT SP format_instruction
6644                  </t>                  </t>
6645                    <t>/ SEND SP send_instruction
6646                    </t>
6647                  <t>/ RESET                  <t>/ RESET
6648                  </t>                  </t>
6649                  <t>/ QUIT                  <t>/ QUIT
# Line 6429  Schoenebeck'> Line 6658  Schoenebeck'>
6658                  </t>                  </t>
6659                  <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
6660                  </t>                  </t>
6661                    <t>/ DB_INSTRUMENTS SP NON_MODAL SP scan_mode SP FILE_AS_DIR SP db_path SP filename
6662                    </t>
6663                  <t>/ DB_INSTRUMENTS SP scan_mode SP db_path SP filename                  <t>/ DB_INSTRUMENTS SP scan_mode SP db_path SP filename
6664                  </t>                  </t>
6665                    <t>/ DB_INSTRUMENTS SP scan_mode SP FILE_AS_DIR SP db_path SP filename
6666                    </t>
6667                  <t>/ DB_INSTRUMENTS SP NON_MODAL SP db_path SP filename                  <t>/ DB_INSTRUMENTS SP NON_MODAL SP db_path SP filename
6668                  </t>                  </t>
6669                  <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 6677  Schoenebeck'> Line 6910  Schoenebeck'>
6910                  </t>                  </t>
6911                  <t>/ VOLUME                  <t>/ VOLUME
6912                  </t>                  </t>
6913                    <t>/ VOICES
6914                    </t>
6915                    <t>/ STREAMS
6916                    </t>
6917                  <t>/ FILE SP INSTRUMENTS SP filename                  <t>/ FILE SP INSTRUMENTS SP filename
6918                  </t>                  </t>
6919                  <t>/ FILE SP INSTRUMENT SP INFO SP filename SP instrument_index                  <t>/ FILE SP INSTRUMENT SP INFO SP filename SP instrument_index
# Line 6721  Schoenebeck'> Line 6958  Schoenebeck'>
6958                  </t>                  </t>
6959                  <t>/ VOLUME SP volume_value                  <t>/ VOLUME SP volume_value
6960                  </t>                  </t>
6961                    <t>/ VOICES SP number
6962                    </t>
6963                    <t>/ STREAMS SP number
6964                    </t>
6965          </list>          </list>
6966  </t>  </t>
6967  <t>create_instruction =  <t>create_instruction =
# Line 6903  Schoenebeck'> Line 7144  Schoenebeck'>
7144                  </t>                  </t>
7145          </list>          </list>
7146  </t>  </t>
7147    <t>send_instruction =
7148            <list>
7149                    <t>CHANNEL SP MIDI_DATA SP string SP sampler_channel SP number SP number
7150                    </t>
7151            </list>
7152    </t>
7153  <t>load_instr_args =  <t>load_instr_args =
7154          <list>          <list>
7155                  <t>filename SP instrument_index SP sampler_channel                  <t>filename SP instrument_index SP sampler_channel
# Line 7621  Schoenebeck'> Line 7868  Schoenebeck'>
7868                          replaced by the optional dotted floating point value, reflecting the                          replaced by the optional dotted floating point value, reflecting the
7869                          new global volume parameter.</t>                          new global volume parameter.</t>
7870                      </list>                      </list>
7871                        <list>
7872                            <t>"NOTIFY:GLOBAL_INFO:VOICES &lt;max-voices&gt;" - Notifies that the
7873                            golbal limit of the sampler for maximum voices is changed, where
7874                            &lt;max-voices&gt; will be an integer value, reflecting the
7875                            new global voice limit parameter.</t>
7876                        </list>
7877                        <list>
7878                            <t>"NOTIFY:GLOBAL_INFO:STREAMS &lt;max-streams&gt;" - Notifies that the
7879                            golbal limit of the sampler for maximum disk streams is changed, where
7880                            &lt;max-streams&gt; will be an integer value, reflecting the
7881                            new global disk streams limit parameter.</t>
7882                        </list>
7883                  </t>                  </t>
7884              </section>              </section>
7885    
Legend:
Removed from v.1727  
changed lines
  Added in v.2025
  ViewVC Help
Powered by ViewVC