/[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 1362 by schoenebeck, Sun Sep 30 21:33:26 2007 UTC revision 1804 by schoenebeck, Wed Dec 10 22:08:20 2008 UTC
# Line 16  Line 16 
16       to an annoying "missing Normative/Informative References" error message -->       to an annoying "missing Normative/Informative References" error message -->
17  <?rfc strict="no" ?>  <?rfc strict="no" ?>
18    
19  <rfc category="std" ipr="full3978" docName="LSCP 1.2cvs">  <rfc category="std" ipr="full3978" docName="LSCP 1.4">
20      <front>      <front>
21          <title>LinuxSampler Control Protocol (draft)</title>          <title>LinuxSampler Control Protocol</title>
22          <author initials='C.S.' surname="Schoenebeck" fullname='C.          <author initials='C.S.' surname="Schoenebeck" fullname='C.
23  Schoenebeck'>  Schoenebeck'>
24              <organization>              <organization>
# Line 34  Schoenebeck'> Line 34  Schoenebeck'>
34                  <email>schoenebeck at software minus engineering dot org</email>                  <email>schoenebeck at software minus engineering dot org</email>
35              </address>              </address>
36          </author>          </author>
37          <date month="September" year="2007"/>          <date month="December" year="2008"/>
38          <workgroup>LinuxSampler Developers</workgroup>          <workgroup>LinuxSampler Developers</workgroup>
39          <keyword>LSCP</keyword>          <keyword>LSCP</keyword>
40          <abstract>          <abstract>
# Line 2162  Schoenebeck'> Line 2162  Schoenebeck'>
2162                              </t>                              </t>
2163                          </list>                          </list>
2164                      </t>                      </t>
2165                      <t>Example:</t>                      <t>Example (Unix):</t>
2166                      <t>                      <t>
2167                          <list>                          <list>
2168                              <t></t>                              <t>C: LOAD INSTRUMENT '/home/joe/gigs/cello.gig' 0 0</t>
2169                                <t>S: OK</t>
2170                            </list>
2171                        </t>
2172                        <t>Example (Windows):</t>
2173                        <t>
2174                            <list>
2175                                <t>C: LOAD INSTRUMENT 'D:/MySounds/cello.gig' 0 0</t>
2176                                <t>S: OK</t>
2177                          </list>                          </list>
2178                      </t>                      </t>
2179                  </section>                  </section>
# Line 2443  Schoenebeck'> Line 2451  Schoenebeck'>
2451                                  <list>                                  <list>
2452                                      <t>DESCRIPTION -                                      <t>DESCRIPTION -
2453                                          <list>                                          <list>
2454                                              <t>arbitrary description text about the engine</t>                                              <t>arbitrary description text about the engine
2455                                                (note that the character string may contain
2456                                                <xref target="character_set">escape sequences</xref>)</t>
2457                                          </list>                                          </list>
2458                                      </t>                                      </t>
2459                                       <t>VERSION -                                       <t>VERSION -
# Line 2502  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 2527  Schoenebeck'> Line 2537  Schoenebeck'>
2537                                          <list>                                          <list>
2538                                              <t>the file name of the loaded instrument, "NONE" if                                              <t>the file name of the loaded instrument, "NONE" if
2539                                              there's no instrument yet loaded for this sampler                                              there's no instrument yet loaded for this sampler
2540                                              channel</t>                                              channel (note: since LSCP 1.2 this path may contain
2541                                                <xref target="character_set">escape sequences</xref>)</t>
2542                                          </list>                                          </list>
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 -
2552                                          <list>                                          <list>
2553                                              <t>the instrument name of the loaded instrument</t>                                              <t>the instrument name of the loaded instrument
2554                                                (note: since LSCP 1.2 this character string may contain
2555                                                <xref target="character_set">escape sequences</xref>)</t>
2556                                          </list>                                          </list>
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 2551  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 3255  Schoenebeck'> Line 3275  Schoenebeck'>
3275                      sampler channel on which the effect send should be created on, &lt;midi-ctrl&gt;                      sampler channel on which the effect send should be created on, &lt;midi-ctrl&gt;
3276                      is a number between 0..127 defining the MIDI controller which can alter the                      is a number between 0..127 defining the MIDI controller which can alter the
3277                      effect send level and &lt;name&gt; is an optional argument defining a name                      effect send level and &lt;name&gt; is an optional argument defining a name
3278                      for the effect send entity. The name does not have to be unique.</t>                      for the effect send entity. The name does not have to be unique, but MUST be
3279                        encapsulated into apostrophes and supports escape sequences as described in chapter
3280                        "<xref target="character_set">Character Set and Escape Sequences</xref>".</t>
3281    
3282                      <t>By default, that is as initial routing, the effect send's audio channels                      <t>By default, that is as initial routing, the effect send's audio channels
3283                      are automatically routed to the last audio channels of the sampler channel's                      are automatically routed to the last audio channels of the sampler channel's
# Line 3445  Schoenebeck'> Line 3467  Schoenebeck'>
3467                                  <list>                                  <list>
3468                                      <t>NAME -                                      <t>NAME -
3469                                          <list>                                          <list>
3470                                              <t>name of the effect send entity</t>                                              <t>name of the effect send entity
3471                                                (note that this character string may contain
3472                                                 <xref target="character_set">escape sequences</xref>)</t>
3473                                          </list>                                          </list>
3474                                      </t>                                      </t>
3475                                      <t>MIDI_CONTROLLER -                                      <t>MIDI_CONTROLLER -
# Line 3508  Schoenebeck'> Line 3532  Schoenebeck'>
3532                      as returned by the <xref target="CREATE FX_SEND">"CREATE FX_SEND"</xref>                      as returned by the <xref target="CREATE FX_SEND">"CREATE FX_SEND"</xref>
3533                      or <xref target="LIST FX_SENDS">"LIST FX_SENDS"</xref> command and                      or <xref target="LIST FX_SENDS">"LIST FX_SENDS"</xref> command and
3534                      &lt;name&gt; is the new name of the effect send entity, which                      &lt;name&gt; is the new name of the effect send entity, which
3535                      does not have to be unique.</t>                      does not have to be unique (name MUST be encapsulated into apostrophes
3536                        and supports escape sequences as described in chapter
3537                        "<xref target="character_set">Character Set and Escape Sequences</xref>").
3538                        </t>
3539    
3540                      <t>Possible Answers:</t>                      <t>Possible Answers:</t>
3541                      <t>                      <t>
# Line 3691  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 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                            </list>
3751                        </t>
3752                        <t>CAUTION: This command is provided for implementations of virtual MIDI keyboards
3753                        and no realtime guarantee whatsoever will be made!</t>
3754                        <t>Possible Answers:</t>
3755                        <t>
3756                            <list>
3757                                <t>"OK" -
3758                                    <list>
3759                                        <t>on success</t>
3760                                    </list>
3761                                </t>
3762                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
3763                                    <list>
3764                                        <t>in case it failed, providing an appropriate error code and error message</t>
3765                                    </list>
3766                                </t>
3767                            </list>
3768                        </t>
3769                        <t>Example:</t>
3770                        <t>
3771                            <list>
3772                                <t>C: "SEND CHANNEL MIDI_DATA NOTE_ON 0 56 112"</t>
3773                                <t>S: "OK"</t>
3774                            </list>
3775                        </t>
3776                    </section>
3777    
3778                  <section title="Resetting a sampler channel" anchor="RESET CHANNEL">                  <section title="Resetting a sampler channel" anchor="RESET CHANNEL">
3779                      <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>
3780                      <t>                      <t>
# Line 3912  Schoenebeck'> Line 3996  Schoenebeck'>
3996                      </t>                      </t>
3997                  </section>                  </section>
3998    
3999                    <section title="Current number of active disk streams" anchor="GET TOTAL_STREAM_COUNT">
4000                        <t>The front-end can ask for the current number of active disk streams on
4001                        the sampler by sending the following command:</t>
4002                        <t>
4003                            <list>
4004                                <t>GET TOTAL_STREAM_COUNT</t>
4005                            </list>
4006                        </t>
4007    
4008                        <t>Possible Answers:</t>
4009                        <t>
4010                            <list>
4011                                <t>LinuxSampler will answer by returning the number of all active
4012                                disk streams on the sampler.</t>
4013                            </list>
4014                        </t>
4015                    </section>
4016    
4017                  <section title="Reset sampler" anchor="RESET">                  <section title="Reset sampler" anchor="RESET">
4018                      <t>The front-end can reset the whole sampler by sending the following command:</t>                      <t>The front-end can reset the whole sampler by sending the following command:</t>
4019                      <t>                      <t>
# Line 3959  Schoenebeck'> Line 4061  Schoenebeck'>
4061                                  <list>                                  <list>
4062                                      <t>DESCRIPTION -                                      <t>DESCRIPTION -
4063                                          <list>                                          <list>
4064                                              <t>arbitrary textual description about the sampler</t>                                              <t>arbitrary textual description about the sampler
4065                                                (note that the character string may contain
4066                                                <xref target="character_set">escape sequences</xref>)</t>
4067                                          </list>                                          </list>
4068                                      </t>                                      </t>
4069                                      <t>VERSION -                                      <t>VERSION -
# Line 4045  Schoenebeck'> Line 4149  Schoenebeck'>
4149                          </list>                          </list>
4150                      </t>                      </t>
4151                  </section>                  </section>
4152    
4153                    <section title="Getting global voice limit" anchor="GET VOICES">
4154                        <t>The client can ask for the current global sampler-wide limit
4155                           for maximum voices by sending the following command:</t>
4156                        <t>
4157                            <list>
4158                                <t>GET VOICES</t>
4159                            </list>
4160                        </t>
4161                        <t>Possible Answers:</t>
4162                        <t>
4163                            <list>
4164                                <t>LinuxSampler will answer by returning the number for
4165                                   the current limit of maximum voices.</t>
4166                            </list>
4167                        </t>
4168    
4169                        <t>The voice limit setting defines how many voices should maximum
4170                           be processed by the sampler at the same time. If the user
4171                           triggers new notes which would exceed that voice limit, the
4172                           sampler engine will react by stealing old voices for those
4173                           newly triggered notes. Note that the amount of voices triggered
4174                           by a new note can be larger than one and is dependent to the
4175                           respective instrument and probably further criterias.</t>
4176                    </section>
4177    
4178                    <section title="Setting global voice limit" anchor="SET VOICES">
4179                        <t>The client can alter the current global sampler-wide limit
4180                        for maximum voices by sending the following command:</t>
4181                        <t>
4182                            <list>
4183                                <t>SET VOICES &lt;max-voices&gt;</t>
4184                            </list>
4185                        </t>
4186                       <t>Where &lt;max-voices&gt; should be replaced by the integer
4187                       value, reflecting the new global amount limit of maximum voices.
4188                       This value has to be larger than 0.</t>
4189    
4190                        <t>Possible Answers:</t>
4191                        <t>
4192                            <list>
4193                                <t>"OK" -
4194                                    <list>
4195                                        <t>on success</t>
4196                                    </list>
4197                                </t>
4198                                <t>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
4199                                    <list>
4200                                        <t>if the voice limit was set, but there are noteworthy
4201                                        issue(s) related, providing an appropriate warning code and
4202                                        warning message</t>
4203                                    </list>
4204                                </t>
4205                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
4206                                    <list>
4207                                        <t>in case it failed, providing an appropriate error code and error message</t>
4208                                    </list>
4209                                </t>
4210                            </list>
4211                        </t>
4212    
4213                        <t>Note: the given value will be passed to all sampler engine instances.
4214                           The total amount of maximum voices on the running system might thus
4215                           be as big as the given value multiplied by the current amount of engine
4216                           instances.</t>
4217    
4218                         <t>Caution: when adjusting the voice limit, you SHOULD also
4219                            adjust the disk stream limit respectively and vice versa.</t>
4220                    </section>
4221    
4222                    <section title="Getting global disk stream limit" anchor="GET STREAMS">
4223                        <t>The client can ask for the current global sampler-wide limit
4224                           for maximum disk streams by sending the following command:</t>
4225                        <t>
4226                            <list>
4227                                <t>GET STREAMS</t>
4228                            </list>
4229                        </t>
4230                        <t>Possible Answers:</t>
4231                        <t>
4232                            <list>
4233                                <t>LinuxSampler will answer by returning the number for
4234                                   the current limit of maximum disk streams.</t>
4235                            </list>
4236                        </t>
4237    
4238                        <t>The disk stream limit setting defines how many disk streams should
4239                           maximum be processed by a sampler engine at the same time. The
4240                           higher this value, the more memory (RAM) will be occupied, since
4241                           every disk streams allocates a certain buffer size for being able
4242                           to perform its streaming operations.</t>
4243                    </section>
4244    
4245                    <section title="Setting global disk stream limit" anchor="SET STREAMS">
4246                        <t>The client can alter the current global sampler-wide limit
4247                        for maximum disk streams by sending the following command:</t>
4248                        <t>
4249                            <list>
4250                                <t>SET STREAMS &lt;max-streams&gt;</t>
4251                            </list>
4252                        </t>
4253                       <t>Where &lt;max-streams&gt; should be replaced by the integer
4254                       value, reflecting the new global amount limit of maximum disk streams.
4255                       This value has to be positive.</t>
4256    
4257                        <t>Possible Answers:</t>
4258                        <t>
4259                            <list>
4260                                <t>"OK" -
4261                                    <list>
4262                                        <t>on success</t>
4263                                    </list>
4264                                </t>
4265                                <t>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
4266                                    <list>
4267                                        <t>if the disk stream limit was set, but there are noteworthy
4268                                        issue(s) related, providing an appropriate warning code and
4269                                        warning message</t>
4270                                    </list>
4271                                </t>
4272                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
4273                                    <list>
4274                                        <t>in case it failed, providing an appropriate error code and error message</t>
4275                                    </list>
4276                                </t>
4277                            </list>
4278                        </t>
4279    
4280                        <t>Note: the given value will be passed to all sampler engine instances.
4281                           The total amount of maximum disk streams on the running system might
4282                           thus be as big as the given value multiplied by the current amount of
4283                           engine instances.</t>
4284    
4285                         <t>Caution: when adjusting the disk stream limit, you SHOULD also
4286                            adjust the voice limit respectively and vice versa.</t>
4287                    </section>
4288    
4289              </section>              </section>
4290    
4291    
# Line 4075  Schoenebeck'> Line 4316  Schoenebeck'>
4316                  cause the sampler to switch to the respective instrument as                  cause the sampler to switch to the respective instrument as
4317                  reflected by the current MIDI instrument map.</t>                  reflected by the current MIDI instrument map.</t>
4318    
4319                  <section title="Create a new MIDI instrument map" anchor="ADD MIDI_INSTRUMENT MAP">                  <section title="Create a new MIDI instrument map" anchor="ADD MIDI_INSTRUMENT_MAP">
4320                      <t>The front-end can add a new MIDI instrument map by sending                      <t>The front-end can add a new MIDI instrument map by sending
4321                      the following command:</t>                      the following command:</t>
4322                      <t>                      <t>
# Line 4085  Schoenebeck'> Line 4326  Schoenebeck'>
4326                      </t>                      </t>
4327                      <t>Where &lt;name&gt; is an optional argument allowing to                      <t>Where &lt;name&gt; is an optional argument allowing to
4328                      assign a custom name to the new map. MIDI instrument Map                      assign a custom name to the new map. MIDI instrument Map
4329                      names do not have to be unique.</t>                      names do not have to be unique, but MUST be encapsulated
4330                        into apostrophes and support escape sequences as described
4331                        in chapter "<xref target="character_set">Character Set and Escape Sequences</xref>".
4332                        </t>
4333    
4334                      <t>Possible Answers:</t>                      <t>Possible Answers:</t>
4335                      <t>                      <t>
# Line 4256  Schoenebeck'> Line 4500  Schoenebeck'>
4500                                      <t>NAME -                                      <t>NAME -
4501                                          <list>                                          <list>
4502                                              <t>custom name of the given map,                                              <t>custom name of the given map,
4503                                              which does not have to be unique</t>                                              which does not have to be unique
4504                                                (note that this character string may contain
4505                                                 <xref target="character_set">escape sequences</xref>)</t>
4506                                          </list>                                          </list>
4507                                      </t>                                      </t>
4508                                      <t>DEFAULT -                                      <t>DEFAULT -
# Line 4292  Schoenebeck'> Line 4538  Schoenebeck'>
4538                      </t>                      </t>
4539                      <t>Where &lt;map&gt; is the numerical ID of the map and                      <t>Where &lt;map&gt; is the numerical ID of the map and
4540                      &lt;name&gt; the new custom name of the map, which does not                      &lt;name&gt; the new custom name of the map, which does not
4541                      have to be unique.</t>                      have to be unique (name MUST be encapsulated into apostrophes
4542                        and supports escape sequences as described in chapter
4543                        "<xref target="character_set">Character Set and Escape Sequences</xref>").
4544                        </t>
4545    
4546                      <t>Possible Answers:</t>                      <t>Possible Answers:</t>
4547                      <t>                      <t>
# Line 4423  Schoenebeck'> Line 4672  Schoenebeck'>
4672                      load modes of entries, the frontend should retrieve the actual                      load modes of entries, the frontend should retrieve the actual
4673                      mode by i.e. sending                      mode by i.e. sending
4674                      <xref target="GET MIDI_INSTRUMENT INFO">"GET MIDI_INSTRUMENT INFO"</xref>                      <xref target="GET MIDI_INSTRUMENT INFO">"GET MIDI_INSTRUMENT INFO"</xref>
4675                      command(s). Finally the OPTIONAL &lt;name&gt; argument allows to                      command(s). Finally the OPTIONAL &lt;name&gt; argument allows to set a custom name
4676                      set a custom name (encapsulated into apostrophes) for the mapping                      (encapsulated into apostrophes, supporting escape sequences as described in chapter
4677                      entry, useful for frontends for displaying an appropriate name for                      "<xref target="character_set">Character Set and Escape Sequences</xref>") for the
4678                        mapping entry, useful for frontends for displaying an appropriate name for
4679                      mapped instruments (using                      mapped instruments (using
4680                      <xref target="GET MIDI_INSTRUMENT INFO">"GET MIDI_INSTRUMENT INFO"</xref>).                      <xref target="GET MIDI_INSTRUMENT INFO">"GET MIDI_INSTRUMENT INFO"</xref>).
4681                      </t>                      </t>
# Line 4649  Schoenebeck'> Line 4899  Schoenebeck'>
4899                                      name for this mapped instrument. It can be set and                                      name for this mapped instrument. It can be set and
4900                                      changed with the                                      changed with the
4901                                      <xref target="MAP MIDI_INSTRUMENT">"MAP MIDI_INSTRUMENT"</xref>                                      <xref target="MAP MIDI_INSTRUMENT">"MAP MIDI_INSTRUMENT"</xref>
4902                                      command and does not have to be unique.</t>                                      command and does not have to be unique.
4903                                        (note that this character string may contain
4904                                        <xref target="character_set">escape sequences</xref>)</t>
4905                                  </list>                                  </list>
4906                              </t>                              </t>
4907                              <t>"ENGINE_NAME" -                              <t>"ENGINE_NAME" -
# Line 4660  Schoenebeck'> Line 4912  Schoenebeck'>
4912                              </t>                              </t>
4913                              <t>"INSTRUMENT_FILE" -                              <t>"INSTRUMENT_FILE" -
4914                                  <list>                                  <list>
4915                                      <t>File name of the instrument.</t>                                      <t>File name of the instrument
4916                                        (note that this path may contain
4917                                        <xref target="character_set">escape sequences</xref>).</t>
4918                                  </list>                                  </list>
4919                              </t>                              </t>
4920                              <t>"INSTRUMENT_NR" -                              <t>"INSTRUMENT_NR" -
# Line 4672  Schoenebeck'> Line 4926  Schoenebeck'>
4926                                  <list>                                  <list>
4927                                      <t>Name of the loaded instrument as reflected by its file.                                      <t>Name of the loaded instrument as reflected by its file.
4928                                      In contrast to the "NAME" field, the "INSTRUMENT_NAME" field                                      In contrast to the "NAME" field, the "INSTRUMENT_NAME" field
4929                                      cannot be changed.</t>                                      cannot be changed (note that this character string may contain
4930                                        <xref target="character_set">escape sequences</xref>).</t>
4931                                  </list>                                  </list>
4932                              </t>                              </t>
4933                              <t>"LOAD_MODE" -                              <t>"LOAD_MODE" -
# Line 5239  Schoenebeck'> Line 5494  Schoenebeck'>
5494                      to the instruments database by sending the following command:</t>                      to the instruments database by sending the following command:</t>
5495                      <t>                      <t>
5496                          <list>                          <list>
5497                              <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>
5498                          </list>                          </list>
5499                      </t>                      </t>
5500                      <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 5284  Schoenebeck'> Line 5539  Schoenebeck'>
5539                          </list>                          </list>
5540                      </t>                      </t>
5541    
5542                     <t> If FILE_AS_DIR argument is supplied, all instruments in an instrument
5543                     file will be added to a separate directory in the instruments database, which
5544                     name will be the name of the instrument file with the file extension stripped off.
5545                     </t>
5546                   <t>The difference between regular and NON_MODAL versions of the command                   <t>The difference between regular and NON_MODAL versions of the command
5547                      is that the regular command returns when the scanning is finished                      is that the regular command returns when the scanning is finished
5548                      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 5687  Schoenebeck'> Line 5946  Schoenebeck'>
5946                          </list>                          </list>
5947                      </t>                      </t>
5948                      <t>Where &lt;instr&gt; is the absolute path name of the instrument and                      <t>Where &lt;instr&gt; is the absolute path name of the instrument and
5949                      &lt;desc&gt; is the new description for the instrument                      &lt;desc&gt; is the new description for the instrument
5950                      (encapsulated into apostrophes, supporting escape sequences as described in chapter                      (encapsulated into apostrophes, supporting escape sequences as described in chapter
5951                      "<xref target="character_set">Character Set and Escape Sequences</xref>").</t>                      "<xref target="character_set">Character Set and Escape Sequences</xref>").</t>
5952    
# Line 5930  Schoenebeck'> Line 6189  Schoenebeck'>
6189                              <t>FORMAT INSTRUMENTS_DB</t>                              <t>FORMAT INSTRUMENTS_DB</t>
6190                          </list>                          </list>
6191                      </t>                      </t>
6192                        
6193                      <t>Possible Answers:</t>                      <t>Possible Answers:</t>
6194                      <t>                      <t>
6195                          <list>                          <list>
# Line 5949  Schoenebeck'> Line 6208  Schoenebeck'>
6208                      </t>                      </t>
6209                  </section>                  </section>
6210    
6211                    <section title="Checking for lost instrument files" anchor="FIND LOST DB_INSTRUMENT_FILES">
6212                        <t>The front-end can retrieve the list of all instrument files in the instruments database
6213                        that don't exist in the filesystem by sending the following command:</t>
6214                        <t>
6215                            <list>
6216                                <t>FIND LOST DB_INSTRUMENT_FILES</t>
6217                            </list>
6218                        </t>
6219    
6220                        <t>Possible Answers:</t>
6221                        <t>
6222                            <list>
6223                                <t>A comma separated list with the absolute path names
6224                                (encapsulated into apostrophes) of all lost instrument files.</t>
6225                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
6226                                    <list>
6227                                        <t>in case it failed, providing an appropriate error code and error message.</t>
6228                                    </list>
6229                                </t>
6230                            </list>
6231                        </t>
6232                        <t>Example:</t>
6233                        <t>
6234                            <list>
6235                                <t>C: "FIND LOST DB_INSTRUMENT_FILES"</t>
6236                                <t>S: "'/gigs/Bosendorfer 290.gig','/gigs/Steinway D.gig','/gigs/Free Piano.gig'"</t>
6237                            </list>
6238                        </t>
6239                    </section>
6240    
6241                    <section title="Replacing an instrument file" anchor="SET DB_INSTRUMENT FILE_PATH">
6242                        <t>The front-end can substitute all occurrences of an instrument file
6243                        in the instruments database with a new one by sending the following command:</t>
6244                        <t>
6245                            <list>
6246                                <t>SET DB_INSTRUMENT FILE_PATH &lt;old_path&gt; &lt;new_path&gt;</t>
6247                            </list>
6248                        </t>
6249                        <t>Where &lt;old_path&gt; is the absolute path name of the instrument file
6250                        to substitute with &lt;new_path&gt;.</t>
6251    
6252                        <t>Possible Answers:</t>
6253                        <t>
6254                            <list>
6255                                <t>"OK" -
6256                                    <list>
6257                                        <t>on success</t>
6258                                    </list>
6259                                </t>
6260                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
6261                                    <list>
6262                                        <t>in case it failed, providing an appropriate error code and error message.</t>
6263                                    </list>
6264                                </t>
6265                            </list>
6266                        </t>
6267    
6268                        <t>Example:</t>
6269                        <t>
6270                            <list>
6271                                <t>C: "SET DB_INSTRUMENT FILE_PATH '/gigs/Bosendorfer 290.gig' '/gigs/pianos/Bosendorfer 290.gig'"</t>
6272                                <t>S: "OK"</t>
6273                            </list>
6274                        </t>
6275                    </section>
6276    
6277              </section>              </section>
6278    
6279    
# Line 5969  Schoenebeck'> Line 6294  Schoenebeck'>
6294                      editor application by sending the following command:</t>                      editor application by sending the following command:</t>
6295                      <t>                      <t>
6296                          <list>                          <list>
6297                              <t>EDIT INSTRUMENT &lt;sampler-channel&gt;</t>                              <t>EDIT CHANNEL INSTRUMENT &lt;sampler-channel&gt;</t>
6298                          </list>                          </list>
6299                      </t>                      </t>
6300                      <t>Where &lt;sampler-channel&gt; should be replaced by the                      <t>Where &lt;sampler-channel&gt; should be replaced by the
# Line 6021  Schoenebeck'> Line 6346  Schoenebeck'>
6346                      <t>Examples:</t>                      <t>Examples:</t>
6347                      <t>                      <t>
6348                          <list>                          <list>
6349                              <t>C: "EDIT INSTRUMENT 0"</t>                              <t>C: "EDIT CHANNEL INSTRUMENT 0"</t>
6350                              <t>S: "OK"</t>                              <t>S: "OK"</t>
6351                          </list>                          </list>
6352                      </t>                      </t>
6353                  </section>                  </section>
6354              </section>              </section>
         </section>  
6355    
6356                <section title="Managing Files" anchor="file_management">
6357                    <t>You can query detailed informations about files located
6358                    at the same system where the sampler instance is running on.
6359                    Using this command set allows to retrieve file informations
6360                    even remotely from another machine.</t>
6361    
6362                    <section title="Retrieving amount of instruments of a file" anchor="GET FILE INSTRUMENTS">
6363                        <t>The front-end can retrieve the amount of instruments
6364                        within a given instrument file by sending the
6365                        following command:</t>
6366                        <t>
6367                            <list>
6368                                <t>GET FILE INSTRUMENTS &lt;filename&gt;</t>
6369                            </list>
6370                        </t>
6371                        <t>Where &lt;filename&gt; is the name of the instrument
6372                        file (encapsulated into apostrophes, supporting escape
6373                        sequences as described in chapter
6374                        "<xref target="character_set">Character Set and Escape
6375                            Sequences</xref>").</t>
6376    
6377                        <t>The sampler will try to ask all sampler engines,
6378                        whether they support the given file and ask the first
6379                        engine with a positive answer for the amount of
6380                        instruments.</t>
6381    
6382                        <t>Possible Answers:</t>
6383                        <t>
6384                            <list>
6385                                <t>On success, the sampler will answer by
6386                                   returning the amount of instruments.
6387                                </t>
6388                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
6389                                    <list>
6390                                        <t>if the file could not be handled</t>
6391                                    </list>
6392                                </t>
6393                            </list>
6394                        </t>
6395    
6396                        <t>Examples:</t>
6397                        <t>
6398                            <list>
6399                                <t>C: "GET FILE INSTRUMENTS 'D:/Sounds/Foo.gig'"</t>
6400                                <t>S: "10"</t>
6401                            </list>
6402                        </t>
6403                    </section>
6404    
6405                    <section title="Retrieving all instruments of a file" anchor="LIST FILE INSTRUMENTS">
6406                        <t>The front-end can retrieve a list of all instruments
6407                        within a given instrument file by sending the
6408                        following command:</t>
6409                        <t>
6410                            <list>
6411                                <t>LIST FILE INSTRUMENTS &lt;filename&gt;</t>
6412                            </list>
6413                        </t>
6414                        <t>Where &lt;filename&gt; is the name of the instrument
6415                        file (encapsulated into apostrophes, supporting escape
6416                        sequences as described in chapter
6417                        "<xref target="character_set">Character Set and Escape
6418                            Sequences</xref>").</t>
6419    
6420                        <t>The sampler will try to ask all sampler engines,
6421                        whether they support the given file and ask the first
6422                        engine with a positive answer for a list of IDs for the
6423                        instruments in the given file.</t>
6424    
6425                        <t>Possible Answers:</t>
6426                        <t>
6427                            <list>
6428                                <t>On success, the sampler will answer by
6429                                   returning a comma separated list of
6430                                   instrument IDs.
6431                                </t>
6432                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
6433                                    <list>
6434                                        <t>if the file could not be handled</t>
6435                                    </list>
6436                                </t>
6437                            </list>
6438                        </t>
6439    
6440                        <t>Examples:</t>
6441                        <t>
6442                            <list>
6443                                <t>C: "LIST FILE INSTRUMENTS 'D:/Sounds/Foo.gig'"</t>
6444                                <t>S: "0,1,2,3,4,5,6,7,8,9"</t>
6445                            </list>
6446                        </t>
6447                    </section>
6448    
6449                    <section title="Retrieving informations about one instrument in a file" anchor="GET FILE INSTRUMENT INFO">
6450                        <t>The front-end can retrieve detailed informations
6451                        about a specific instrument within a given instrument
6452                        file by sending the following command:</t>
6453                        <t>
6454                            <list>
6455                                <t>GET FILE INSTRUMENT INFO &lt;filename&gt;
6456                                &lt;instr-id&gt;</t>
6457                            </list>
6458                        </t>
6459                        <t>Where &lt;filename&gt; is the name of the instrument
6460                        file (encapsulated into apostrophes, supporting escape
6461                        sequences as described in chapter
6462                        "<xref target="character_set">Character Set and Escape
6463                            Sequences</xref>") and &lt;instr-id&gt; is the numeric
6464                        instrument ID as returned by the
6465                        <xref target="LIST FILE INSTRUMENTS">
6466                        "LIST FILE INSTRUMENTS"</xref> command.</t>
6467    
6468                        <t>The sampler will try to ask all sampler engines,
6469                        whether they support the given file and ask the first
6470                        engine with a positive answer for informations about the
6471                        specific instrument in the given file.</t>
6472    
6473                        <t>Possible Answers:</t>
6474                        <t>
6475                            <list>
6476                                <t>LinuxSampler will answer by sending a &lt;CRLF&gt; separated list.
6477                                Each answer line begins with the settings category name
6478                                followed by a colon and then a space character &lt;SP&gt; and finally
6479                                the info character string to that setting category. At the
6480                                moment the following categories are defined:</t>
6481    
6482                                <t>
6483                                    <list>
6484                                        <t>NAME -
6485                                            <list>
6486                                                <t>name of the instrument as
6487                                                stored in the instrument file</t>
6488                                            </list>
6489                                        </t>
6490                                        <t>FORMAT_FAMILY -
6491                                            <list>
6492                                                <t>name of the sampler format
6493                                                of the given instrument</t>
6494                                            </list>
6495                                        </t>
6496                                        <t>FORMAT_VERSION -
6497                                            <list>
6498                                                <t>version of the sampler format
6499                                                the instrumen is stored as</t>
6500                                            </list>
6501                                        </t>
6502                                        <t>PRODUCT -
6503                                            <list>
6504                                                <t>official product name of the
6505                                                instrument as stored in the file
6506                                                </t>
6507                                            </list>
6508                                        </t>
6509                                        <t>ARTISTS -
6510                                            <list>
6511                                                <t>artists / sample library
6512                                                vendor of the instrument</t>
6513                                            </list>
6514                                        </t>
6515                                        <t>KEY_BINDINGS -
6516                                            <list>
6517                                                <t>comma separated list of integer values representing
6518                                                   the instrument's key mapping in the range between 0 .. 127,
6519                                                   reflecting the analog meaning of the MIDI specification.</t>
6520                                            </list>
6521                                        </t>
6522                                        <t>KEYSWITCH_BINDINGS -
6523                                            <list>
6524                                                <t>comma separated list of integer values representing
6525                                                   the instrument's keyswitch mapping in the range between 0 .. 127,
6526                                                   reflecting the analog meaning of the MIDI specification.</t>
6527                                            </list>
6528                                        </t>
6529                                    </list>
6530                                </t>
6531                            </list>
6532                        </t>
6533                        <t>The mentioned fields above don't have to be in particular order.</t>
6534    
6535                        <t>Example:</t>
6536                        <t>
6537                            <list>
6538                                <t>C: "GET FILE INSTRUMENT INFO 'D:/Sounds/Foo.gig' 0"</t>
6539                                <t>S: "NAME: Lunatic Loops"</t>
6540                                <t>&nbsp;&nbsp;&nbsp;"FORMAT_FAMILY: GIG"</t>
6541                                <t>&nbsp;&nbsp;&nbsp;"FORMAT_VERSION: 3"</t>
6542                                <t>&nbsp;&nbsp;&nbsp;"PRODUCT: The Backbone Bongo Beats"</t>
6543                                <t>&nbsp;&nbsp;&nbsp;"ARTISTS: Jimmy the Fish"</t>
6544                                <t>&nbsp;&nbsp;&nbsp;"."</t>
6545                            </list>
6546                        </t>
6547                    </section>
6548                </section>
6549            </section>
6550    
6551          <section title="Command Syntax" anchor="command_syntax">          <section title="Command Syntax" anchor="command_syntax">
6552              <t>The grammar of the control protocol as descibed in <xref target="control_commands"/>              <t>The grammar of the control protocol as descibed in <xref target="control_commands"/>
# Line 6116  Schoenebeck'> Line 6634  Schoenebeck'>
6634                  </t>                  </t>
6635                  <t>/ FORMAT SP format_instruction                  <t>/ FORMAT SP format_instruction
6636                  </t>                  </t>
6637                    <t>/ SEND SP send_instruction
6638                    </t>
6639                  <t>/ RESET                  <t>/ RESET
6640                  </t>                  </t>
6641                  <t>/ QUIT                  <t>/ QUIT
# Line 6130  Schoenebeck'> Line 6650  Schoenebeck'>
6650                  </t>                  </t>
6651                  <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
6652                  </t>                  </t>
6653                    <t>/ DB_INSTRUMENTS SP NON_MODAL SP scan_mode SP FILE_AS_DIR SP db_path SP filename
6654                    </t>
6655                  <t>/ DB_INSTRUMENTS SP scan_mode SP db_path SP filename                  <t>/ DB_INSTRUMENTS SP scan_mode SP db_path SP filename
6656                  </t>                  </t>
6657                    <t>/ DB_INSTRUMENTS SP scan_mode SP FILE_AS_DIR SP db_path SP filename
6658                    </t>
6659                  <t>/ DB_INSTRUMENTS SP NON_MODAL SP db_path SP filename                  <t>/ DB_INSTRUMENTS SP NON_MODAL SP db_path SP filename
6660                  </t>                  </t>
6661                  <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 6158  Schoenebeck'> Line 6682  Schoenebeck'>
6682                  </t>                  </t>
6683                  <t>/ CHANNEL_COUNT                  <t>/ CHANNEL_COUNT
6684                  </t>                  </t>
6685                    <t>/ CHANNEL_MIDI
6686                    </t>
6687                    <t>/ DEVICE_MIDI
6688                    </t>
6689                  <t>/ VOICE_COUNT                  <t>/ VOICE_COUNT
6690                  </t>                  </t>
6691                  <t>/ STREAM_COUNT                  <t>/ STREAM_COUNT
# Line 6190  Schoenebeck'> Line 6718  Schoenebeck'>
6718                  </t>                  </t>
6719                  <t>/ MISCELLANEOUS                  <t>/ MISCELLANEOUS
6720                  </t>                  </t>
6721                    <t>/ TOTAL_STREAM_COUNT
6722                    </t>
6723                  <t>/ TOTAL_VOICE_COUNT                  <t>/ TOTAL_VOICE_COUNT
6724                  </t>                  </t>
6725                  <t>/ GLOBAL_INFO                  <t>/ GLOBAL_INFO
# Line 6208  Schoenebeck'> Line 6738  Schoenebeck'>
6738                  </t>                  </t>
6739                  <t>/ CHANNEL_COUNT                  <t>/ CHANNEL_COUNT
6740                  </t>                  </t>
6741                    <t>/ CHANNEL_MIDI
6742                    </t>
6743                    <t>/ DEVICE_MIDI
6744                    </t>
6745                  <t>/ VOICE_COUNT                  <t>/ VOICE_COUNT
6746                  </t>                  </t>
6747                  <t>/ STREAM_COUNT                  <t>/ STREAM_COUNT
# Line 6240  Schoenebeck'> Line 6774  Schoenebeck'>
6774                  </t>                  </t>
6775                  <t>/ MISCELLANEOUS                  <t>/ MISCELLANEOUS
6776                  </t>                  </t>
6777                    <t>/ TOTAL_STREAM_COUNT
6778                    </t>
6779                  <t>/ TOTAL_VOICE_COUNT                  <t>/ TOTAL_VOICE_COUNT
6780                  </t>                  </t>
6781                  <t>/ GLOBAL_INFO                  <t>/ GLOBAL_INFO
# Line 6330  Schoenebeck'> Line 6866  Schoenebeck'>
6866                  </t>                  </t>
6867                  <t>/ SERVER SP INFO                  <t>/ SERVER SP INFO
6868                  </t>                  </t>
6869                    <t>/ TOTAL_STREAM_COUNT
6870                    </t>
6871                  <t>/ TOTAL_VOICE_COUNT                  <t>/ TOTAL_VOICE_COUNT
6872                  </t>                  </t>
6873                  <t>/ TOTAL_VOICE_COUNT_MAX                  <t>/ TOTAL_VOICE_COUNT_MAX
# Line 6364  Schoenebeck'> Line 6902  Schoenebeck'>
6902                  </t>                  </t>
6903                  <t>/ VOLUME                  <t>/ VOLUME
6904                  </t>                  </t>
6905                    <t>/ VOICES
6906                    </t>
6907                    <t>/ STREAMS
6908                    </t>
6909                    <t>/ FILE SP INSTRUMENTS SP filename
6910                    </t>
6911                    <t>/ FILE SP INSTRUMENT SP INFO SP filename SP instrument_index
6912                    </t>
6913          </list>          </list>
6914  </t>  </t>
6915  <t>set_instruction =  <t>set_instruction =
# Line 6398  Schoenebeck'> Line 6944  Schoenebeck'>
6944                  </t>                  </t>
6945                  <t>/ DB_INSTRUMENT SP DESCRIPTION SP db_path SP stringval_escaped                  <t>/ DB_INSTRUMENT SP DESCRIPTION SP db_path SP stringval_escaped
6946                  </t>                  </t>
6947                    <t>/ DB_INSTRUMENT SP FILE_PATH SP filename SP filename
6948                    </t>
6949                  <t>/ ECHO SP boolean                  <t>/ ECHO SP boolean
6950                  </t>                  </t>
6951                  <t>/ VOLUME SP volume_value                  <t>/ VOLUME SP volume_value
6952                  </t>                  </t>
6953                    <t>/ VOICES SP number
6954                    </t>
6955                    <t>/ STREAMS SP number
6956                    </t>
6957          </list>          </list>
6958  </t>  </t>
6959  <t>create_instruction =  <t>create_instruction =
# Line 6444  Schoenebeck'> Line 6996  Schoenebeck'>
6996                  </t>                  </t>
6997                  <t>/ DB_INSTRUMENT_DIRECTORIES SP db_path SP query_val_list                  <t>/ DB_INSTRUMENT_DIRECTORIES SP db_path SP query_val_list
6998                  </t>                  </t>
6999                    <t>/ LOST SP DB_INSTRUMENT_FILES
7000                    </t>
7001          </list>          </list>
7002  </t>  </t>
7003  <t>move_instruction =  <t>move_instruction =
# Line 6514  Schoenebeck'> Line 7068  Schoenebeck'>
7068  </t>  </t>
7069  <t>edit_instruction =  <t>edit_instruction =
7070          <list>          <list>
7071                  <t>INSTRUMENT SP sampler_channel                  <t>CHANNEL SP INSTRUMENT SP sampler_channel
7072                  </t>                  </t>
7073          </list>          </list>
7074  </t>  </t>
# Line 6578  Schoenebeck'> Line 7132  Schoenebeck'>
7132                  </t>                  </t>
7133                  <t>/ DB_INSTRUMENTS SP db_path                  <t>/ DB_INSTRUMENTS SP db_path
7134                  </t>                  </t>
7135                    <t>/ FILE SP INSTRUMENTS SP filename
7136                    </t>
7137            </list>
7138    </t>
7139    <t>send_instruction =
7140            <list>
7141                    <t>CHANNEL SP MIDI_DATA SP string SP sampler_channel SP number SP number
7142                    </t>
7143          </list>          </list>
7144  </t>  </t>
7145  <t>load_instr_args =  <t>load_instr_args =
# Line 6712  Schoenebeck'> Line 7274  Schoenebeck'>
7274  </t>  </t>
7275  <t>map_name =  <t>map_name =
7276          <list>          <list>
7277                  <t>stringval                  <t>stringval_escaped
7278                  </t>                  </t>
7279          </list>          </list>
7280  </t>  </t>
7281  <t>entry_name =  <t>entry_name =
7282          <list>          <list>
7283                  <t>stringval                  <t>stringval_escaped
7284                  </t>                  </t>
7285          </list>          </list>
7286  </t>  </t>
7287  <t>fx_send_name =  <t>fx_send_name =
7288          <list>          <list>
7289                  <t>stringval                  <t>stringval_escaped
7290                  </t>                  </t>
7291          </list>          </list>
7292  </t>  </t>
# Line 6736  Schoenebeck'> Line 7298  Schoenebeck'>
7298                  </t>                  </t>
7299          </list>          </list>
7300  </t>  </t>
7301    
7302  <t>param_val =  <t>param_val =
7303          <list>          <list>
7304                  <t>string                  <t>string
# Line 6758  Schoenebeck'> Line 7321  Schoenebeck'>
7321  </t>  </t>
7322  <t>query_val =  <t>query_val =
7323          <list>          <list>
7324                  <t>textval_escaped                  <t>text_escaped
7325                  </t>                  </t>
7326                  <t>/ stringval_escaped                  <t>/ stringval_escaped
7327                  </t>                  </t>
# Line 6807  Schoenebeck'> Line 7370  Schoenebeck'>
7370                  where escape characters are now supported, a backslash characters                  where escape characters are now supported, a backslash characters
7371                  MUST be escaped as well (that is as double backslash), whereas                  MUST be escaped as well (that is as double backslash), whereas
7372                  in the old versions a single backslash was sufficient.</t>                  in the old versions a single backslash was sufficient.</t>
7373    
7374                    <t>The following LSCP commands support escape sequences as part
7375                    of their filename / path based arguments and / or may contain
7376                    a filename / path with escape sequences in their response:
7377                    <list>
7378                        <t><xref target="LOAD INSTRUMENT">"LOAD INSTRUMENT"</xref></t>
7379                        <t><xref target="GET CHANNEL INFO">"GET CHANNEL INFO"</xref></t>
7380                        <t><xref target="MAP MIDI_INSTRUMENT">"MAP MIDI_INSTRUMENT"</xref></t>
7381                        <t><xref target="GET MIDI_INSTRUMENT INFO">"GET MIDI_INSTRUMENT INFO"</xref></t>
7382                        <t><xref target="ADD DB_INSTRUMENT_DIRECTORY">"ADD DB_INSTRUMENT_DIRECTORY"</xref></t>
7383                        <t><xref target="ADD DB_INSTRUMENTS">"ADD DB_INSTRUMENTS"</xref></t>
7384                        <t><xref target="REMOVE DB_INSTRUMENT_DIRECTORY">"REMOVE DB_INSTRUMENT_DIRECTORY"</xref></t>
7385                        <t><xref target="REMOVE DB_INSTRUMENT">"REMOVE DB_INSTRUMENT"</xref></t>
7386                        <t><xref target="GET DB_INSTRUMENT_DIRECTORIES">"GET DB_INSTRUMENT_DIRECTORIES"</xref></t>
7387                        <t><xref target="LIST DB_INSTRUMENT_DIRECTORIES">"LIST DB_INSTRUMENT_DIRECTORIES"</xref></t>
7388                        <t><xref target="GET DB_INSTRUMENT_DIRECTORY INFO">"GET DB_INSTRUMENT_DIRECTORY INFO"</xref></t>
7389                        <t><xref target="GET DB_INSTRUMENTS">"GET DB_INSTRUMENTS"</xref></t>
7390                        <t><xref target="LIST DB_INSTRUMENTS">"LIST DB_INSTRUMENTS"</xref></t>
7391                        <t><xref target="GET DB_INSTRUMENT INFO">"GET DB_INSTRUMENT INFO"</xref></t>
7392                        <t><xref target="SET DB_INSTRUMENT_DIRECTORY NAME">"SET DB_INSTRUMENT_DIRECTORY NAME"</xref></t>
7393                        <t><xref target="SET DB_INSTRUMENT_DIRECTORY DESCRIPTION">"SET DB_INSTRUMENT_DIRECTORY DESCRIPTION"</xref></t>
7394                        <t><xref target="SET DB_INSTRUMENT NAME">"SET DB_INSTRUMENT NAME"</xref></t>
7395                        <t><xref target="SET DB_INSTRUMENT DESCRIPTION">"SET DB_INSTRUMENT DESCRIPTION"</xref></t>
7396                        <t><xref target="FIND DB_INSTRUMENTS">"FIND DB_INSTRUMENTS"</xref></t>
7397                        <t><xref target="FIND DB_INSTRUMENT_DIRECTORIES">"FIND DB_INSTRUMENT_DIRECTORIES"</xref></t>
7398                        <t><xref target="MOVE DB_INSTRUMENT">"MOVE DB_INSTRUMENT"</xref></t>
7399                        <t><xref target="MOVE DB_INSTRUMENT_DIRECTORY">"MOVE DB_INSTRUMENT_DIRECTORY"</xref></t>
7400                        <t><xref target="COPY DB_INSTRUMENT">"COPY DB_INSTRUMENT"</xref></t>
7401                        <t><xref target="COPY DB_INSTRUMENT_DIRECTORY">"COPY DB_INSTRUMENT_DIRECTORY"</xref></t>
7402                        <t><xref target="FIND LOST DB_INSTRUMENT_FILES">"FIND LOST DB_INSTRUMENT_FILES"</xref></t>
7403                        <t><xref target="SET DB_INSTRUMENT FILE_PATH">"SET DB_INSTRUMENT FILE_PATH"</xref></t>
7404                        <t><xref target="GET FILE INSTRUMENTS">"GET FILE INSTRUMENTS"</xref></t>
7405                        <t><xref target="LIST FILE INSTRUMENTS">"LIST FILE INSTRUMENTS"</xref></t>
7406                        <t><xref target="GET FILE INSTRUMENT INFO">"GET FILE INSTRUMENT INFO"</xref></t>
7407                    </list>
7408                    Note that the forward slash character ('/') has a special meaning in
7409                    filename / path based arguments: it acts as separator of the nodes in
7410                    the path, thus if a directory- or filename includes a forward slash
7411                    (not intended as path node separator), you MUST escape that slash
7412                    either with the respective hex escape sequence ("\x2f") or with the
7413                    respective octal escape sequence ("\057").
7414                    </t>
7415    
7416                    <t>
7417                    Note for Windows: file path arguments in LSCP are expected
7418                    to use forward slashes as directory node separator similar
7419                    to Unix based operating systems. In contrast to Unix however
7420                    a Windows typical drive character is expected to be
7421                    prefixed to the path. That is an original Windows file path
7422                    like "D:\Sounds\My.gig" would become in LSCP:
7423                    "D:/Sounds/My.gig".
7424                    </t>
7425    
7426                    <t>
7427                    The following LSCP commands even support escape sequences as
7428                    part of at least one of their text-based arguments (i.e. entity name,
7429                    description) and / or may contain escape sequences in at least one of
7430                    their text-based fields in their response:
7431                    <list>
7432                        <t><xref target="GET SERVER INFO">"GET SERVER INFO"</xref></t>
7433                        <t><xref target="GET ENGINE INFO">"GET ENGINE INFO"</xref></t>
7434                        <t><xref target="GET CHANNEL INFO">"GET CHANNEL INFO"</xref></t>
7435                        <t><xref target="CREATE FX_SEND">"CREATE FX_SEND"</xref></t>
7436                        <t><xref target="GET FX_SEND INFO">"GET FX_SEND INFO"</xref></t>
7437                        <t><xref target="SET FX_SEND NAME">"SET FX_SEND NAME"</xref></t>
7438                        <t><xref target="GET MIDI_INSTRUMENT INFO">"GET MIDI_INSTRUMENT INFO"</xref></t>
7439                        <t><xref target="GET MIDI_INSTRUMENT_MAP INFO">"GET MIDI_INSTRUMENT_MAP INFO"</xref></t>
7440                        <t><xref target="ADD MIDI_INSTRUMENT_MAP">"ADD MIDI_INSTRUMENT_MAP"</xref></t>
7441                        <t><xref target="MAP MIDI_INSTRUMENT">"MAP MIDI_INSTRUMENT"</xref></t>
7442                        <t><xref target="SET MIDI_INSTRUMENT_MAP NAME">"SET MIDI_INSTRUMENT_MAP NAME"</xref></t>
7443                        <t><xref target="GET DB_INSTRUMENT_DIRECTORY INFO">"GET DB_INSTRUMENT_DIRECTORY INFO"</xref></t>
7444                        <t><xref target="SET DB_INSTRUMENT_DIRECTORY NAME">"SET DB_INSTRUMENT_DIRECTORY NAME"</xref></t>
7445                        <t><xref target="SET DB_INSTRUMENT_DIRECTORY DESCRIPTION">"SET DB_INSTRUMENT_DIRECTORY DESCRIPTION"</xref></t>
7446                        <t><xref target="FIND DB_INSTRUMENT_DIRECTORIES">"FIND DB_INSTRUMENT_DIRECTORIES"</xref></t>
7447                        <t><xref target="GET DB_INSTRUMENT INFO">"GET DB_INSTRUMENT INFO"</xref></t>
7448                        <t><xref target="SET DB_INSTRUMENT NAME">"SET DB_INSTRUMENT NAME"</xref></t>
7449                        <t><xref target="SET DB_INSTRUMENT DESCRIPTION">"SET DB_INSTRUMENT DESCRIPTION"</xref></t>
7450                        <t><xref target="FIND DB_INSTRUMENTS">"FIND DB_INSTRUMENTS"</xref></t>
7451                    </list>
7452                    Please note that these lists are manually maintained. If you
7453                    find a command that also supports escape sequences we forgot to
7454                    mention here, please report it!
7455                    </t>
7456              </section>              </section>
7457          </section>          </section>
7458    
# Line 6911  Schoenebeck'> Line 7557  Schoenebeck'>
7557                  of sampler channels.</t>                  of sampler channels.</t>
7558              </section>              </section>
7559    
7560                <section title="MIDI data on a sampler channel arrived" anchor="SUBSCRIBE CHANNEL_MIDI">
7561                    <t>Client may want to be notified when MIDI data arrive on sampler channels on
7562                    back-end side, by issuing the following command:</t>
7563                    <t>
7564                        <list>
7565                            <t>SUBSCRIBE CHANNEL_MIDI</t>
7566                        </list>
7567                    </t>
7568                    <t>Server will start sending one of the the following notification messages:</t>
7569                    <t>
7570                        <list>
7571                            <t>"NOTIFY:CHANNEL_MIDI:&lt;channel-id&gt; NOTE_ON  &lt;note&gt; &lt;velocity&gt;"</t>
7572                            <t>"NOTIFY:CHANNEL_MIDI:&lt;channel-id&gt; NOTE_OFF &lt;note&gt; &lt;velocity&gt;"</t>
7573                        </list>
7574                    </t>
7575                    <t>where &lt;channel-id&gt; will be replaced by the ID of the sampler channel where the MIDI
7576                    data arrived. &lt;note&gt; and &lt;velocity&gt; are integer values in the range between
7577                    0 .. 127, reflecting the analog meaning of the MIDI specification.
7578                    </t>
7579                    <t>CAUTION: no guarantee whatsoever will be made that MIDI events are actually all
7580                    delivered by this mechanism! With other words: events could be lost at any time!
7581                    This restriction was made to keep the RT-safeness of the backend's MIDI and audio
7582                    thread unaffected by this feature.</t>
7583                </section>
7584    
7585                <section title="MIDI data on a MIDI input device arrived" anchor="SUBSCRIBE DEVICE_MIDI">
7586                        <t>Client may want to be notified when MIDI data arrive on MIDI input devices by issuing the following command:</t>
7587                        <t>
7588                                <list>
7589                                        <t>SUBSCRIBE DEVICE_MIDI</t>
7590                                </list>
7591                        </t>
7592                        <t>Server will start sending one of the the following notification messages:</t>
7593                        <t>
7594                                <list>
7595                                        <t>"NOTIFY:DEVICE_MIDI:&lt;device-id&gt; &lt;port-id&gt; NOTE_ON &lt;note&gt; &lt;velocity&gt;"</t>
7596                                        <t>"NOTIFY:DEVICE_MIDI:&lt;device-id&gt; &lt;port-id&gt; NOTE_OFF &lt;note&gt; &lt;velocity&gt;"</t>
7597                                </list>
7598                        </t>
7599                        <t>where &lt;device-id&gt; &lt;port-id&gt; will be replaced
7600                           by the IDs of the respective MIDI input device and the device's MIDI port where the MIDI
7601                           data arrived. &lt;note&gt; and &lt;velocity&gt; are integer values in the range between
7602                           0 .. 127, reflecting the analog meaning of the MIDI specification.
7603                        </t>
7604                        <t>CAUTION: no guarantee whatsoever will be made that MIDI events are actually all
7605                           delivered by this mechanism! With other words: events could be lost at any time!
7606                           This restriction was made to keep the RT-safeness of the backend's MIDI and audio
7607                           thread unaffected by this feature.</t>
7608                </section>
7609    
7610              <section title="Number of active voices changed" anchor="SUBSCRIBE VOICE_COUNT">              <section title="Number of active voices changed" anchor="SUBSCRIBE VOICE_COUNT">
7611                  <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
7612                  back-end changes by issuing the following command:</t>                  back-end changes by issuing the following command:</t>
# Line 7048  Schoenebeck'> Line 7744  Schoenebeck'>
7744                  all currently active voices.</t>                  all currently active voices.</t>
7745              </section>              </section>
7746    
7747                <section title="Total number of active disk streams changed" anchor="SUBSCRIBE TOTAL_STREAM_COUNT">
7748                    <t>Client may want to be notified when the total number of disk streams on the
7749                    back-end changes by issuing the following command:</t>
7750                    <t>
7751                        <list>
7752                            <t>SUBSCRIBE TOTAL_STREAM_COUNT</t>
7753                        </list>
7754                    </t>
7755                    <t>Server will start sending the following notification messages:</t>
7756                    <t>
7757                        <list>
7758                            <t>"NOTIFY:TOTAL_STREAM_COUNT:&lt;streams&gt;"</t>
7759                        </list>
7760                    </t>
7761                    <t>where &lt;streams&gt; will be replaced by the new number of
7762                    all currently active disk streams.</t>
7763                </section>
7764    
7765              <section title="Number of MIDI instrument maps changed" anchor="SUBSCRIBE MIDI_INSTRUMENT_MAP_COUNT">              <section title="Number of MIDI instrument maps changed" anchor="SUBSCRIBE MIDI_INSTRUMENT_MAP_COUNT">
7766                  <t>Client may want to be notified when the number of MIDI instrument maps on the                  <t>Client may want to be notified when the number of MIDI instrument maps on the
7767                  back-end changes by issuing the following command:</t>                  back-end changes by issuing the following command:</t>
# Line 7146  Schoenebeck'> Line 7860  Schoenebeck'>
7860                          replaced by the optional dotted floating point value, reflecting the                          replaced by the optional dotted floating point value, reflecting the
7861                          new global volume parameter.</t>                          new global volume parameter.</t>
7862                      </list>                      </list>
7863                        <list>
7864                            <t>"NOTIFY:GLOBAL_INFO:VOICES &lt;max-voices&gt;" - Notifies that the
7865                            golbal limit of the sampler for maximum voices is changed, where
7866                            &lt;max-voices&gt; will be an integer value, reflecting the
7867                            new global voice limit parameter.</t>
7868                        </list>
7869                        <list>
7870                            <t>"NOTIFY:GLOBAL_INFO:STREAMS &lt;max-streams&gt;" - Notifies that the
7871                            golbal limit of the sampler for maximum disk streams is changed, where
7872                            &lt;max-streams&gt; will be an integer value, reflecting the
7873                            new global disk streams limit parameter.</t>
7874                        </list>
7875                  </t>                  </t>
7876              </section>              </section>
7877    
Legend:
Removed from v.1362  
changed lines
  Added in v.1804
  ViewVC Help
Powered by ViewVC