/[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 1800 by schoenebeck, Sun Dec 7 01:26:46 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 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 -
# Line 2537  Schoenebeck'> Line 2548  Schoenebeck'>
2548                                      </t>                                      </t>
2549                                      <t>INSTRUMENT_NAME -                                      <t>INSTRUMENT_NAME -
2550                                          <list>                                          <list>
2551                                              <t>the instrument name of the loaded instrument</t>                                              <t>the instrument name of the loaded instrument
2552                                                (note: since LSCP 1.2 this character string may contain
2553                                                <xref target="character_set">escape sequences</xref>)</t>
2554                                          </list>                                          </list>
2555                                      </t>                                      </t>
2556                                      <t>INSTRUMENT_STATUS -                                      <t>INSTRUMENT_STATUS -
# Line 3255  Schoenebeck'> Line 3268  Schoenebeck'>
3268                      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;
3269                      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
3270                      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
3271                      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
3272                        encapsulated into apostrophes and supports escape sequences as described in chapter
3273                        "<xref target="character_set">Character Set and Escape Sequences</xref>".</t>
3274    
3275                      <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
3276                      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 3460  Schoenebeck'>
3460                                  <list>                                  <list>
3461                                      <t>NAME -                                      <t>NAME -
3462                                          <list>                                          <list>
3463                                              <t>name of the effect send entity</t>                                              <t>name of the effect send entity
3464                                                (note that this character string may contain
3465                                                 <xref target="character_set">escape sequences</xref>)</t>
3466                                          </list>                                          </list>
3467                                      </t>                                      </t>
3468                                      <t>MIDI_CONTROLLER -                                      <t>MIDI_CONTROLLER -
# Line 3508  Schoenebeck'> Line 3525  Schoenebeck'>
3525                      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>
3526                      or <xref target="LIST FX_SENDS">"LIST FX_SENDS"</xref> command and                      or <xref target="LIST FX_SENDS">"LIST FX_SENDS"</xref> command and
3527                      &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
3528                      does not have to be unique.</t>                      does not have to be unique (name MUST be encapsulated into apostrophes
3529                        and supports escape sequences as described in chapter
3530                        "<xref target="character_set">Character Set and Escape Sequences</xref>").
3531                        </t>
3532    
3533                      <t>Possible Answers:</t>                      <t>Possible Answers:</t>
3534                      <t>                      <t>
# Line 3691  Schoenebeck'> Line 3711  Schoenebeck'>
3711                      </t>                      </t>
3712                  </section>                  </section>
3713    
3714                    <section title="Sending MIDI messages to sampler channel" anchor="SEND CHANNEL MIDI_DATA">
3715                        <t>The front-end can send MIDI events to specific sampler channel
3716                        by sending the following command:</t>
3717                        <t>
3718                            <list>
3719                                <t>SEND CHANNEL MIDI_DATA &lt;midi-msg&gt; &lt;sampler-chan&gt; &lt;arg1&gt; &lt;arg2&gt;</t>
3720                            </list>
3721                        </t>
3722                        <t>Where &lt;sampler-chan&gt; is the sampler channel number
3723                        as returned by the <xref target="ADD CHANNEL">"ADD CHANNEL"</xref>
3724                        or <xref target="LIST CHANNELS">"LIST CHANNELS"</xref> command,
3725                        &lt;arg1&gt; and &lt;arg2&gt; arguments depend on the &lt;midi-msg&gt; argument, which
3726                        specifies the MIDI message type. Currently, the following MIDI messages are supported:</t>
3727                        <t>
3728                            <list>
3729                                <t>"NOTE_ON" -
3730                                    <list>
3731                                        <t>For turning on MIDI notes, where &lt;arg1&gt;
3732                                        specifies the key number and &lt;arg2&gt; the velocity
3733                                        as described in the MIDI specification.</t>
3734                                    </list>
3735                                </t>
3736                                <t>"NOTE_OFF" -
3737                                    <list>
3738                                        <t>For turning a currently playing MIDI note off, where &lt;arg1&gt;
3739                                        specifies the key number and &lt;arg2&gt; the velocity
3740                                        as described in the MIDI specification.</t>
3741                                    </list>
3742                                </t>
3743                            </list>
3744                        </t>
3745                        <t>CAUTION: This command is provided for implementations of virtual MIDI keyboards
3746                        and no realtime guarantee whatsoever will be made!</t>
3747                        <t>Possible Answers:</t>
3748                        <t>
3749                            <list>
3750                                <t>"OK" -
3751                                    <list>
3752                                        <t>on success</t>
3753                                    </list>
3754                                </t>
3755                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
3756                                    <list>
3757                                        <t>in case it failed, providing an appropriate error code and error message</t>
3758                                    </list>
3759                                </t>
3760                            </list>
3761                        </t>
3762                        <t>Example:</t>
3763                        <t>
3764                            <list>
3765                                <t>C: "SEND CHANNEL MIDI_DATA NOTE_ON 0 56 112"</t>
3766                                <t>S: "OK"</t>
3767                            </list>
3768                        </t>
3769                    </section>
3770    
3771                  <section title="Resetting a sampler channel" anchor="RESET CHANNEL">                  <section title="Resetting a sampler channel" anchor="RESET CHANNEL">
3772                      <t>The front-end can reset a particular sampler channel by sending the following command:</t>                      <t>The front-end can reset a particular sampler channel by sending the following command:</t>
3773                      <t>                      <t>
# Line 3912  Schoenebeck'> Line 3989  Schoenebeck'>
3989                      </t>                      </t>
3990                  </section>                  </section>
3991    
3992                    <section title="Current number of active disk streams" anchor="GET TOTAL_STREAM_COUNT">
3993                        <t>The front-end can ask for the current number of active disk streams on
3994                        the sampler by sending the following command:</t>
3995                        <t>
3996                            <list>
3997                                <t>GET TOTAL_STREAM_COUNT</t>
3998                            </list>
3999                        </t>
4000    
4001                        <t>Possible Answers:</t>
4002                        <t>
4003                            <list>
4004                                <t>LinuxSampler will answer by returning the number of all active
4005                                disk streams on the sampler.</t>
4006                            </list>
4007                        </t>
4008                    </section>
4009    
4010                  <section title="Reset sampler" anchor="RESET">                  <section title="Reset sampler" anchor="RESET">
4011                      <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>
4012                      <t>                      <t>
# Line 3959  Schoenebeck'> Line 4054  Schoenebeck'>
4054                                  <list>                                  <list>
4055                                      <t>DESCRIPTION -                                      <t>DESCRIPTION -
4056                                          <list>                                          <list>
4057                                              <t>arbitrary textual description about the sampler</t>                                              <t>arbitrary textual description about the sampler
4058                                                (note that the character string may contain
4059                                                <xref target="character_set">escape sequences</xref>)</t>
4060                                          </list>                                          </list>
4061                                      </t>                                      </t>
4062                                      <t>VERSION -                                      <t>VERSION -
# Line 4045  Schoenebeck'> Line 4142  Schoenebeck'>
4142                          </list>                          </list>
4143                      </t>                      </t>
4144                  </section>                  </section>
4145    
4146                    <section title="Getting global voice limit" anchor="GET VOICES">
4147                        <t>The client can ask for the current global sampler-wide limit
4148                           for maximum voices by sending the following command:</t>
4149                        <t>
4150                            <list>
4151                                <t>GET VOICES</t>
4152                            </list>
4153                        </t>
4154                        <t>Possible Answers:</t>
4155                        <t>
4156                            <list>
4157                                <t>LinuxSampler will answer by returning the number for
4158                                   the current limit of maximum voices.</t>
4159                            </list>
4160                        </t>
4161    
4162                        <t>The voice limit setting defines how many voices should maximum
4163                           be processed by the sampler at the same time. If the user
4164                           triggers new notes which would exceed that voice limit, the
4165                           sampler engine will react by stealing old voices for those
4166                           newly triggered notes. Note that the amount of voices triggered
4167                           by a new note can be larger than one and is dependent to the
4168                           respective instrument and probably further criterias.</t>
4169                    </section>
4170    
4171                    <section title="Setting global voice limit" anchor="SET VOICES">
4172                        <t>The client can alter the current global sampler-wide limit
4173                        for maximum voices by sending the following command:</t>
4174                        <t>
4175                            <list>
4176                                <t>SET VOICES &lt;max-voices&gt;</t>
4177                            </list>
4178                        </t>
4179                       <t>Where &lt;max-voices&gt; should be replaced by the integer
4180                       value, reflecting the new global amount limit of maximum voices.
4181                       This value has to be larger than 0.</t>
4182    
4183                        <t>Possible Answers:</t>
4184                        <t>
4185                            <list>
4186                                <t>"OK" -
4187                                    <list>
4188                                        <t>on success</t>
4189                                    </list>
4190                                </t>
4191                                <t>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
4192                                    <list>
4193                                        <t>if the voice limit was set, but there are noteworthy
4194                                        issue(s) related, providing an appropriate warning code and
4195                                        warning message</t>
4196                                    </list>
4197                                </t>
4198                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
4199                                    <list>
4200                                        <t>in case it failed, providing an appropriate error code and error message</t>
4201                                    </list>
4202                                </t>
4203                            </list>
4204                        </t>
4205    
4206                        <t>Note: the given value will be passed to all sampler engine instances.
4207                           The total amount of maximum voices on the running system might thus
4208                           be as big as the given value multiplied by the current amount of engine
4209                           instances.</t>
4210    
4211                         <t>Caution: when adjusting the voice limit, you SHOULD also
4212                            adjust the disk stream limit respectively and vice versa.</t>
4213                    </section>
4214    
4215                    <section title="Getting global disk stream limit" anchor="GET STREAMS">
4216                        <t>The client can ask for the current global sampler-wide limit
4217                           for maximum disk streams by sending the following command:</t>
4218                        <t>
4219                            <list>
4220                                <t>GET STREAMS</t>
4221                            </list>
4222                        </t>
4223                        <t>Possible Answers:</t>
4224                        <t>
4225                            <list>
4226                                <t>LinuxSampler will answer by returning the number for
4227                                   the current limit of maximum disk streams.</t>
4228                            </list>
4229                        </t>
4230    
4231                        <t>The disk stream limit setting defines how many disk streams should
4232                           maximum be processed by a sampler engine at the same time. The
4233                           higher this value, the more memory (RAM) will be occupied, since
4234                           every disk streams allocates a certain buffer size for being able
4235                           to perform its streaming operations.</t>
4236                    </section>
4237    
4238                    <section title="Setting global disk stream limit" anchor="SET STREAMS">
4239                        <t>The client can alter the current global sampler-wide limit
4240                        for maximum disk streams by sending the following command:</t>
4241                        <t>
4242                            <list>
4243                                <t>SET STREAMS &lt;max-streams&gt;</t>
4244                            </list>
4245                        </t>
4246                       <t>Where &lt;max-streams&gt; should be replaced by the integer
4247                       value, reflecting the new global amount limit of maximum disk streams.
4248                       This value has to be positive.</t>
4249    
4250                        <t>Possible Answers:</t>
4251                        <t>
4252                            <list>
4253                                <t>"OK" -
4254                                    <list>
4255                                        <t>on success</t>
4256                                    </list>
4257                                </t>
4258                                <t>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
4259                                    <list>
4260                                        <t>if the disk stream limit was set, but there are noteworthy
4261                                        issue(s) related, providing an appropriate warning code and
4262                                        warning message</t>
4263                                    </list>
4264                                </t>
4265                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
4266                                    <list>
4267                                        <t>in case it failed, providing an appropriate error code and error message</t>
4268                                    </list>
4269                                </t>
4270                            </list>
4271                        </t>
4272    
4273                        <t>Note: the given value will be passed to all sampler engine instances.
4274                           The total amount of maximum disk streams on the running system might
4275                           thus be as big as the given value multiplied by the current amount of
4276                           engine instances.</t>
4277    
4278                         <t>Caution: when adjusting the disk stream limit, you SHOULD also
4279                            adjust the voice limit respectively and vice versa.</t>
4280                    </section>
4281    
4282              </section>              </section>
4283    
4284    
# Line 4075  Schoenebeck'> Line 4309  Schoenebeck'>
4309                  cause the sampler to switch to the respective instrument as                  cause the sampler to switch to the respective instrument as
4310                  reflected by the current MIDI instrument map.</t>                  reflected by the current MIDI instrument map.</t>
4311    
4312                  <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">
4313                      <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
4314                      the following command:</t>                      the following command:</t>
4315                      <t>                      <t>
# Line 4085  Schoenebeck'> Line 4319  Schoenebeck'>
4319                      </t>                      </t>
4320                      <t>Where &lt;name&gt; is an optional argument allowing to                      <t>Where &lt;name&gt; is an optional argument allowing to
4321                      assign a custom name to the new map. MIDI instrument Map                      assign a custom name to the new map. MIDI instrument Map
4322                      names do not have to be unique.</t>                      names do not have to be unique, but MUST be encapsulated
4323                        into apostrophes and support escape sequences as described
4324                        in chapter "<xref target="character_set">Character Set and Escape Sequences</xref>".
4325                        </t>
4326    
4327                      <t>Possible Answers:</t>                      <t>Possible Answers:</t>
4328                      <t>                      <t>
# Line 4256  Schoenebeck'> Line 4493  Schoenebeck'>
4493                                      <t>NAME -                                      <t>NAME -
4494                                          <list>                                          <list>
4495                                              <t>custom name of the given map,                                              <t>custom name of the given map,
4496                                              which does not have to be unique</t>                                              which does not have to be unique
4497                                                (note that this character string may contain
4498                                                 <xref target="character_set">escape sequences</xref>)</t>
4499                                          </list>                                          </list>
4500                                      </t>                                      </t>
4501                                      <t>DEFAULT -                                      <t>DEFAULT -
# Line 4292  Schoenebeck'> Line 4531  Schoenebeck'>
4531                      </t>                      </t>
4532                      <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
4533                      &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
4534                      have to be unique.</t>                      have to be unique (name MUST be encapsulated into apostrophes
4535                        and supports escape sequences as described in chapter
4536                        "<xref target="character_set">Character Set and Escape Sequences</xref>").
4537                        </t>
4538    
4539                      <t>Possible Answers:</t>                      <t>Possible Answers:</t>
4540                      <t>                      <t>
# Line 4423  Schoenebeck'> Line 4665  Schoenebeck'>
4665                      load modes of entries, the frontend should retrieve the actual                      load modes of entries, the frontend should retrieve the actual
4666                      mode by i.e. sending                      mode by i.e. sending
4667                      <xref target="GET MIDI_INSTRUMENT INFO">"GET MIDI_INSTRUMENT INFO"</xref>                      <xref target="GET MIDI_INSTRUMENT INFO">"GET MIDI_INSTRUMENT INFO"</xref>
4668                      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
4669                      set a custom name (encapsulated into apostrophes) for the mapping                      (encapsulated into apostrophes, supporting escape sequences as described in chapter
4670                      entry, useful for frontends for displaying an appropriate name for                      "<xref target="character_set">Character Set and Escape Sequences</xref>") for the
4671                        mapping entry, useful for frontends for displaying an appropriate name for
4672                      mapped instruments (using                      mapped instruments (using
4673                      <xref target="GET MIDI_INSTRUMENT INFO">"GET MIDI_INSTRUMENT INFO"</xref>).                      <xref target="GET MIDI_INSTRUMENT INFO">"GET MIDI_INSTRUMENT INFO"</xref>).
4674                      </t>                      </t>
# Line 4649  Schoenebeck'> Line 4892  Schoenebeck'>
4892                                      name for this mapped instrument. It can be set and                                      name for this mapped instrument. It can be set and
4893                                      changed with the                                      changed with the
4894                                      <xref target="MAP MIDI_INSTRUMENT">"MAP MIDI_INSTRUMENT"</xref>                                      <xref target="MAP MIDI_INSTRUMENT">"MAP MIDI_INSTRUMENT"</xref>
4895                                      command and does not have to be unique.</t>                                      command and does not have to be unique.
4896                                        (note that this character string may contain
4897                                        <xref target="character_set">escape sequences</xref>)</t>
4898                                  </list>                                  </list>
4899                              </t>                              </t>
4900                              <t>"ENGINE_NAME" -                              <t>"ENGINE_NAME" -
# Line 4660  Schoenebeck'> Line 4905  Schoenebeck'>
4905                              </t>                              </t>
4906                              <t>"INSTRUMENT_FILE" -                              <t>"INSTRUMENT_FILE" -
4907                                  <list>                                  <list>
4908                                      <t>File name of the instrument.</t>                                      <t>File name of the instrument
4909                                        (note that this path may contain
4910                                        <xref target="character_set">escape sequences</xref>).</t>
4911                                  </list>                                  </list>
4912                              </t>                              </t>
4913                              <t>"INSTRUMENT_NR" -                              <t>"INSTRUMENT_NR" -
# Line 4672  Schoenebeck'> Line 4919  Schoenebeck'>
4919                                  <list>                                  <list>
4920                                      <t>Name of the loaded instrument as reflected by its file.                                      <t>Name of the loaded instrument as reflected by its file.
4921                                      In contrast to the "NAME" field, the "INSTRUMENT_NAME" field                                      In contrast to the "NAME" field, the "INSTRUMENT_NAME" field
4922                                      cannot be changed.</t>                                      cannot be changed (note that this character string may contain
4923                                        <xref target="character_set">escape sequences</xref>).</t>
4924                                  </list>                                  </list>
4925                              </t>                              </t>
4926                              <t>"LOAD_MODE" -                              <t>"LOAD_MODE" -
# Line 5239  Schoenebeck'> Line 5487  Schoenebeck'>
5487                      to the instruments database by sending the following command:</t>                      to the instruments database by sending the following command:</t>
5488                      <t>                      <t>
5489                          <list>                          <list>
5490                              <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>
5491                          </list>                          </list>
5492                      </t>                      </t>
5493                      <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 5532  Schoenebeck'>
5532                          </list>                          </list>
5533                      </t>                      </t>
5534    
5535                     <t> If FILE_AS_DIR argument is supplied, all instruments in an instrument
5536                     file will be added to a separate directory in the instruments database, which
5537                     name will be the name of the instrument file with the file extension stripped off.
5538                     </t>
5539                   <t>The difference between regular and NON_MODAL versions of the command                   <t>The difference between regular and NON_MODAL versions of the command
5540                      is that the regular command returns when the scanning is finished                      is that the regular command returns when the scanning is finished
5541                      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 5939  Schoenebeck'>
5939                          </list>                          </list>
5940                      </t>                      </t>
5941                      <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
5942                      &lt;desc&gt; is the new description for the instrument                      &lt;desc&gt; is the new description for the instrument
5943                      (encapsulated into apostrophes, supporting escape sequences as described in chapter                      (encapsulated into apostrophes, supporting escape sequences as described in chapter
5944                      "<xref target="character_set">Character Set and Escape Sequences</xref>").</t>                      "<xref target="character_set">Character Set and Escape Sequences</xref>").</t>
5945    
# Line 5930  Schoenebeck'> Line 6182  Schoenebeck'>
6182                              <t>FORMAT INSTRUMENTS_DB</t>                              <t>FORMAT INSTRUMENTS_DB</t>
6183                          </list>                          </list>
6184                      </t>                      </t>
6185                        
6186                      <t>Possible Answers:</t>                      <t>Possible Answers:</t>
6187                      <t>                      <t>
6188                          <list>                          <list>
# Line 5949  Schoenebeck'> Line 6201  Schoenebeck'>
6201                      </t>                      </t>
6202                  </section>                  </section>
6203    
6204                    <section title="Checking for lost instrument files" anchor="FIND LOST DB_INSTRUMENT_FILES">
6205                        <t>The front-end can retrieve the list of all instrument files in the instruments database
6206                        that don't exist in the filesystem by sending the following command:</t>
6207                        <t>
6208                            <list>
6209                                <t>FIND LOST DB_INSTRUMENT_FILES</t>
6210                            </list>
6211                        </t>
6212    
6213                        <t>Possible Answers:</t>
6214                        <t>
6215                            <list>
6216                                <t>A comma separated list with the absolute path names
6217                                (encapsulated into apostrophes) of all lost instrument files.</t>
6218                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
6219                                    <list>
6220                                        <t>in case it failed, providing an appropriate error code and error message.</t>
6221                                    </list>
6222                                </t>
6223                            </list>
6224                        </t>
6225                        <t>Example:</t>
6226                        <t>
6227                            <list>
6228                                <t>C: "FIND LOST DB_INSTRUMENT_FILES"</t>
6229                                <t>S: "'/gigs/Bosendorfer 290.gig','/gigs/Steinway D.gig','/gigs/Free Piano.gig'"</t>
6230                            </list>
6231                        </t>
6232                    </section>
6233    
6234                    <section title="Replacing an instrument file" anchor="SET DB_INSTRUMENT FILE_PATH">
6235                        <t>The front-end can substitute all occurrences of an instrument file
6236                        in the instruments database with a new one by sending the following command:</t>
6237                        <t>
6238                            <list>
6239                                <t>SET DB_INSTRUMENT FILE_PATH &lt;old_path&gt; &lt;new_path&gt;</t>
6240                            </list>
6241                        </t>
6242                        <t>Where &lt;old_path&gt; is the absolute path name of the instrument file
6243                        to substitute with &lt;new_path&gt;.</t>
6244    
6245                        <t>Possible Answers:</t>
6246                        <t>
6247                            <list>
6248                                <t>"OK" -
6249                                    <list>
6250                                        <t>on success</t>
6251                                    </list>
6252                                </t>
6253                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
6254                                    <list>
6255                                        <t>in case it failed, providing an appropriate error code and error message.</t>
6256                                    </list>
6257                                </t>
6258                            </list>
6259                        </t>
6260    
6261                        <t>Example:</t>
6262                        <t>
6263                            <list>
6264                                <t>C: "SET DB_INSTRUMENT FILE_PATH '/gigs/Bosendorfer 290.gig' '/gigs/pianos/Bosendorfer 290.gig'"</t>
6265                                <t>S: "OK"</t>
6266                            </list>
6267                        </t>
6268                    </section>
6269    
6270              </section>              </section>
6271    
6272    
# Line 5969  Schoenebeck'> Line 6287  Schoenebeck'>
6287                      editor application by sending the following command:</t>                      editor application by sending the following command:</t>
6288                      <t>                      <t>
6289                          <list>                          <list>
6290                              <t>EDIT INSTRUMENT &lt;sampler-channel&gt;</t>                              <t>EDIT CHANNEL INSTRUMENT &lt;sampler-channel&gt;</t>
6291                          </list>                          </list>
6292                      </t>                      </t>
6293                      <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 6339  Schoenebeck'>
6339                      <t>Examples:</t>                      <t>Examples:</t>
6340                      <t>                      <t>
6341                          <list>                          <list>
6342                              <t>C: "EDIT INSTRUMENT 0"</t>                              <t>C: "EDIT CHANNEL INSTRUMENT 0"</t>
6343                              <t>S: "OK"</t>                              <t>S: "OK"</t>
6344                          </list>                          </list>
6345                      </t>                      </t>
6346                  </section>                  </section>
6347              </section>              </section>
         </section>  
6348    
6349                <section title="Managing Files" anchor="file_management">
6350                    <t>You can query detailed informations about files located
6351                    at the same system where the sampler instance is running on.
6352                    Using this command set allows to retrieve file informations
6353                    even remotely from another machine.</t>
6354    
6355                    <section title="Retrieving amount of instruments of a file" anchor="GET FILE INSTRUMENTS">
6356                        <t>The front-end can retrieve the amount of instruments
6357                        within a given instrument file by sending the
6358                        following command:</t>
6359                        <t>
6360                            <list>
6361                                <t>GET FILE INSTRUMENTS &lt;filename&gt;</t>
6362                            </list>
6363                        </t>
6364                        <t>Where &lt;filename&gt; is the name of the instrument
6365                        file (encapsulated into apostrophes, supporting escape
6366                        sequences as described in chapter
6367                        "<xref target="character_set">Character Set and Escape
6368                            Sequences</xref>").</t>
6369    
6370                        <t>The sampler will try to ask all sampler engines,
6371                        whether they support the given file and ask the first
6372                        engine with a positive answer for the amount of
6373                        instruments.</t>
6374    
6375                        <t>Possible Answers:</t>
6376                        <t>
6377                            <list>
6378                                <t>On success, the sampler will answer by
6379                                   returning the amount of instruments.
6380                                </t>
6381                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
6382                                    <list>
6383                                        <t>if the file could not be handled</t>
6384                                    </list>
6385                                </t>
6386                            </list>
6387                        </t>
6388    
6389                        <t>Examples:</t>
6390                        <t>
6391                            <list>
6392                                <t>C: "GET FILE INSTRUMENTS 'D:/Sounds/Foo.gig'"</t>
6393                                <t>S: "10"</t>
6394                            </list>
6395                        </t>
6396                    </section>
6397    
6398                    <section title="Retrieving all instruments of a file" anchor="LIST FILE INSTRUMENTS">
6399                        <t>The front-end can retrieve a list of all instruments
6400                        within a given instrument file by sending the
6401                        following command:</t>
6402                        <t>
6403                            <list>
6404                                <t>LIST FILE INSTRUMENTS &lt;filename&gt;</t>
6405                            </list>
6406                        </t>
6407                        <t>Where &lt;filename&gt; is the name of the instrument
6408                        file (encapsulated into apostrophes, supporting escape
6409                        sequences as described in chapter
6410                        "<xref target="character_set">Character Set and Escape
6411                            Sequences</xref>").</t>
6412    
6413                        <t>The sampler will try to ask all sampler engines,
6414                        whether they support the given file and ask the first
6415                        engine with a positive answer for a list of IDs for the
6416                        instruments in the given file.</t>
6417    
6418                        <t>Possible Answers:</t>
6419                        <t>
6420                            <list>
6421                                <t>On success, the sampler will answer by
6422                                   returning a comma separated list of
6423                                   instrument IDs.
6424                                </t>
6425                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
6426                                    <list>
6427                                        <t>if the file could not be handled</t>
6428                                    </list>
6429                                </t>
6430                            </list>
6431                        </t>
6432    
6433                        <t>Examples:</t>
6434                        <t>
6435                            <list>
6436                                <t>C: "LIST FILE INSTRUMENTS 'D:/Sounds/Foo.gig'"</t>
6437                                <t>S: "0,1,2,3,4,5,6,7,8,9"</t>
6438                            </list>
6439                        </t>
6440                    </section>
6441    
6442                    <section title="Retrieving informations about one instrument in a file" anchor="GET FILE INSTRUMENT INFO">
6443                        <t>The front-end can retrieve detailed informations
6444                        about a specific instrument within a given instrument
6445                        file by sending the following command:</t>
6446                        <t>
6447                            <list>
6448                                <t>GET FILE INSTRUMENT INFO &lt;filename&gt;
6449                                &lt;instr-id&gt;</t>
6450                            </list>
6451                        </t>
6452                        <t>Where &lt;filename&gt; is the name of the instrument
6453                        file (encapsulated into apostrophes, supporting escape
6454                        sequences as described in chapter
6455                        "<xref target="character_set">Character Set and Escape
6456                            Sequences</xref>") and &lt;instr-id&gt; is the numeric
6457                        instrument ID as returned by the
6458                        <xref target="LIST FILE INSTRUMENTS">
6459                        "LIST FILE INSTRUMENTS"</xref> command.</t>
6460    
6461                        <t>The sampler will try to ask all sampler engines,
6462                        whether they support the given file and ask the first
6463                        engine with a positive answer for informations about the
6464                        specific instrument in the given file.</t>
6465    
6466                        <t>Possible Answers:</t>
6467                        <t>
6468                            <list>
6469                                <t>LinuxSampler will answer by sending a &lt;CRLF&gt; separated list.
6470                                Each answer line begins with the settings category name
6471                                followed by a colon and then a space character &lt;SP&gt; and finally
6472                                the info character string to that setting category. At the
6473                                moment the following categories are defined:</t>
6474    
6475                                <t>
6476                                    <list>
6477                                        <t>NAME -
6478                                            <list>
6479                                                <t>name of the instrument as
6480                                                stored in the instrument file</t>
6481                                            </list>
6482                                        </t>
6483                                        <t>FORMAT_FAMILY -
6484                                            <list>
6485                                                <t>name of the sampler format
6486                                                of the given instrument</t>
6487                                            </list>
6488                                        </t>
6489                                        <t>FORMAT_VERSION -
6490                                            <list>
6491                                                <t>version of the sampler format
6492                                                the instrumen is stored as</t>
6493                                            </list>
6494                                        </t>
6495                                        <t>PRODUCT -
6496                                            <list>
6497                                                <t>official product name of the
6498                                                instrument as stored in the file
6499                                                </t>
6500                                            </list>
6501                                        </t>
6502                                        <t>ARTISTS -
6503                                            <list>
6504                                                <t>artists / sample library
6505                                                vendor of the instrument</t>
6506                                            </list>
6507                                        </t>
6508                                        <t>KEY_BINDINGS -
6509                                            <list>
6510                                                <t>comma separated list of integer values representing
6511                                                   the instrument's key mapping in the range between 0 .. 127,
6512                                                   reflecting the analog meaning of the MIDI specification.</t>
6513                                            </list>
6514                                        </t>
6515                                        <t>KEYSWITCH_BINDINGS -
6516                                            <list>
6517                                                <t>comma separated list of integer values representing
6518                                                   the instrument's keyswitch mapping in the range between 0 .. 127,
6519                                                   reflecting the analog meaning of the MIDI specification.</t>
6520                                            </list>
6521                                        </t>
6522                                    </list>
6523                                </t>
6524                            </list>
6525                        </t>
6526                        <t>The mentioned fields above don't have to be in particular order.</t>
6527    
6528                        <t>Example:</t>
6529                        <t>
6530                            <list>
6531                                <t>C: "GET FILE INSTRUMENT INFO 'D:/Sounds/Foo.gig' 0"</t>
6532                                <t>S: "NAME: Lunatic Loops"</t>
6533                                <t>&nbsp;&nbsp;&nbsp;"FORMAT_FAMILY: GIG"</t>
6534                                <t>&nbsp;&nbsp;&nbsp;"FORMAT_VERSION: 3"</t>
6535                                <t>&nbsp;&nbsp;&nbsp;"PRODUCT: The Backbone Bongo Beats"</t>
6536                                <t>&nbsp;&nbsp;&nbsp;"ARTISTS: Jimmy the Fish"</t>
6537                                <t>&nbsp;&nbsp;&nbsp;"."</t>
6538                            </list>
6539                        </t>
6540                    </section>
6541                </section>
6542            </section>
6543    
6544          <section title="Command Syntax" anchor="command_syntax">          <section title="Command Syntax" anchor="command_syntax">
6545              <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 6627  Schoenebeck'>
6627                  </t>                  </t>
6628                  <t>/ FORMAT SP format_instruction                  <t>/ FORMAT SP format_instruction
6629                  </t>                  </t>
6630                    <t>/ SEND SP send_instruction
6631                    </t>
6632                  <t>/ RESET                  <t>/ RESET
6633                  </t>                  </t>
6634                  <t>/ QUIT                  <t>/ QUIT
# Line 6130  Schoenebeck'> Line 6643  Schoenebeck'>
6643                  </t>                  </t>
6644                  <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
6645                  </t>                  </t>
6646                    <t>/ DB_INSTRUMENTS SP NON_MODAL SP scan_mode SP FILE_AS_DIR SP db_path SP filename
6647                    </t>
6648                  <t>/ DB_INSTRUMENTS SP scan_mode SP db_path SP filename                  <t>/ DB_INSTRUMENTS SP scan_mode SP db_path SP filename
6649                  </t>                  </t>
6650                    <t>/ DB_INSTRUMENTS SP scan_mode SP FILE_AS_DIR SP db_path SP filename
6651                    </t>
6652                  <t>/ DB_INSTRUMENTS SP NON_MODAL SP db_path SP filename                  <t>/ DB_INSTRUMENTS SP NON_MODAL SP db_path SP filename
6653                  </t>                  </t>
6654                  <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 6675  Schoenebeck'>
6675                  </t>                  </t>
6676                  <t>/ CHANNEL_COUNT                  <t>/ CHANNEL_COUNT
6677                  </t>                  </t>
6678                    <t>/ CHANNEL_MIDI
6679                    </t>
6680                    <t>/ DEVICE_MIDI
6681                    </t>
6682                  <t>/ VOICE_COUNT                  <t>/ VOICE_COUNT
6683                  </t>                  </t>
6684                  <t>/ STREAM_COUNT                  <t>/ STREAM_COUNT
# Line 6190  Schoenebeck'> Line 6711  Schoenebeck'>
6711                  </t>                  </t>
6712                  <t>/ MISCELLANEOUS                  <t>/ MISCELLANEOUS
6713                  </t>                  </t>
6714                    <t>/ TOTAL_STREAM_COUNT
6715                    </t>
6716                  <t>/ TOTAL_VOICE_COUNT                  <t>/ TOTAL_VOICE_COUNT
6717                  </t>                  </t>
6718                  <t>/ GLOBAL_INFO                  <t>/ GLOBAL_INFO
# Line 6208  Schoenebeck'> Line 6731  Schoenebeck'>
6731                  </t>                  </t>
6732                  <t>/ CHANNEL_COUNT                  <t>/ CHANNEL_COUNT
6733                  </t>                  </t>
6734                    <t>/ CHANNEL_MIDI
6735                    </t>
6736                    <t>/ DEVICE_MIDI
6737                    </t>
6738                  <t>/ VOICE_COUNT                  <t>/ VOICE_COUNT
6739                  </t>                  </t>
6740                  <t>/ STREAM_COUNT                  <t>/ STREAM_COUNT
# Line 6240  Schoenebeck'> Line 6767  Schoenebeck'>
6767                  </t>                  </t>
6768                  <t>/ MISCELLANEOUS                  <t>/ MISCELLANEOUS
6769                  </t>                  </t>
6770                    <t>/ TOTAL_STREAM_COUNT
6771                    </t>
6772                  <t>/ TOTAL_VOICE_COUNT                  <t>/ TOTAL_VOICE_COUNT
6773                  </t>                  </t>
6774                  <t>/ GLOBAL_INFO                  <t>/ GLOBAL_INFO
# Line 6330  Schoenebeck'> Line 6859  Schoenebeck'>
6859                  </t>                  </t>
6860                  <t>/ SERVER SP INFO                  <t>/ SERVER SP INFO
6861                  </t>                  </t>
6862                    <t>/ TOTAL_STREAM_COUNT
6863                    </t>
6864                  <t>/ TOTAL_VOICE_COUNT                  <t>/ TOTAL_VOICE_COUNT
6865                  </t>                  </t>
6866                  <t>/ TOTAL_VOICE_COUNT_MAX                  <t>/ TOTAL_VOICE_COUNT_MAX
# Line 6364  Schoenebeck'> Line 6895  Schoenebeck'>
6895                  </t>                  </t>
6896                  <t>/ VOLUME                  <t>/ VOLUME
6897                  </t>                  </t>
6898                    <t>/ VOICES
6899                    </t>
6900                    <t>/ STREAMS
6901                    </t>
6902                    <t>/ FILE SP INSTRUMENTS SP filename
6903                    </t>
6904                    <t>/ FILE SP INSTRUMENT SP INFO SP filename SP instrument_index
6905                    </t>
6906          </list>          </list>
6907  </t>  </t>
6908  <t>set_instruction =  <t>set_instruction =
# Line 6398  Schoenebeck'> Line 6937  Schoenebeck'>
6937                  </t>                  </t>
6938                  <t>/ DB_INSTRUMENT SP DESCRIPTION SP db_path SP stringval_escaped                  <t>/ DB_INSTRUMENT SP DESCRIPTION SP db_path SP stringval_escaped
6939                  </t>                  </t>
6940                    <t>/ DB_INSTRUMENT SP FILE_PATH SP filename SP filename
6941                    </t>
6942                  <t>/ ECHO SP boolean                  <t>/ ECHO SP boolean
6943                  </t>                  </t>
6944                  <t>/ VOLUME SP volume_value                  <t>/ VOLUME SP volume_value
6945                  </t>                  </t>
6946                    <t>/ VOICES SP number
6947                    </t>
6948                    <t>/ STREAMS SP number
6949                    </t>
6950          </list>          </list>
6951  </t>  </t>
6952  <t>create_instruction =  <t>create_instruction =
# Line 6444  Schoenebeck'> Line 6989  Schoenebeck'>
6989                  </t>                  </t>
6990                  <t>/ DB_INSTRUMENT_DIRECTORIES SP db_path SP query_val_list                  <t>/ DB_INSTRUMENT_DIRECTORIES SP db_path SP query_val_list
6991                  </t>                  </t>
6992                    <t>/ LOST SP DB_INSTRUMENT_FILES
6993                    </t>
6994          </list>          </list>
6995  </t>  </t>
6996  <t>move_instruction =  <t>move_instruction =
# Line 6514  Schoenebeck'> Line 7061  Schoenebeck'>
7061  </t>  </t>
7062  <t>edit_instruction =  <t>edit_instruction =
7063          <list>          <list>
7064                  <t>INSTRUMENT SP sampler_channel                  <t>CHANNEL SP INSTRUMENT SP sampler_channel
7065                  </t>                  </t>
7066          </list>          </list>
7067  </t>  </t>
# Line 6578  Schoenebeck'> Line 7125  Schoenebeck'>
7125                  </t>                  </t>
7126                  <t>/ DB_INSTRUMENTS SP db_path                  <t>/ DB_INSTRUMENTS SP db_path
7127                  </t>                  </t>
7128                    <t>/ FILE SP INSTRUMENTS SP filename
7129                    </t>
7130            </list>
7131    </t>
7132    <t>send_instruction =
7133            <list>
7134                    <t>CHANNEL SP MIDI_DATA SP string SP sampler_channel SP number SP number
7135                    </t>
7136          </list>          </list>
7137  </t>  </t>
7138  <t>load_instr_args =  <t>load_instr_args =
# Line 6712  Schoenebeck'> Line 7267  Schoenebeck'>
7267  </t>  </t>
7268  <t>map_name =  <t>map_name =
7269          <list>          <list>
7270                  <t>stringval                  <t>stringval_escaped
7271                  </t>                  </t>
7272          </list>          </list>
7273  </t>  </t>
7274  <t>entry_name =  <t>entry_name =
7275          <list>          <list>
7276                  <t>stringval                  <t>stringval_escaped
7277                  </t>                  </t>
7278          </list>          </list>
7279  </t>  </t>
7280  <t>fx_send_name =  <t>fx_send_name =
7281          <list>          <list>
7282                  <t>stringval                  <t>stringval_escaped
7283                  </t>                  </t>
7284          </list>          </list>
7285  </t>  </t>
# Line 6736  Schoenebeck'> Line 7291  Schoenebeck'>
7291                  </t>                  </t>
7292          </list>          </list>
7293  </t>  </t>
7294    
7295  <t>param_val =  <t>param_val =
7296          <list>          <list>
7297                  <t>string                  <t>string
# Line 6758  Schoenebeck'> Line 7314  Schoenebeck'>
7314  </t>  </t>
7315  <t>query_val =  <t>query_val =
7316          <list>          <list>
7317                  <t>textval_escaped                  <t>text_escaped
7318                  </t>                  </t>
7319                  <t>/ stringval_escaped                  <t>/ stringval_escaped
7320                  </t>                  </t>
# Line 6807  Schoenebeck'> Line 7363  Schoenebeck'>
7363                  where escape characters are now supported, a backslash characters                  where escape characters are now supported, a backslash characters
7364                  MUST be escaped as well (that is as double backslash), whereas                  MUST be escaped as well (that is as double backslash), whereas
7365                  in the old versions a single backslash was sufficient.</t>                  in the old versions a single backslash was sufficient.</t>
7366    
7367                    <t>The following LSCP commands support escape sequences as part
7368                    of their filename / path based arguments and / or may contain
7369                    a filename / path with escape sequences in their response:
7370                    <list>
7371                        <t><xref target="LOAD INSTRUMENT">"LOAD INSTRUMENT"</xref></t>
7372                        <t><xref target="GET CHANNEL INFO">"GET CHANNEL INFO"</xref></t>
7373                        <t><xref target="MAP MIDI_INSTRUMENT">"MAP MIDI_INSTRUMENT"</xref></t>
7374                        <t><xref target="GET MIDI_INSTRUMENT INFO">"GET MIDI_INSTRUMENT INFO"</xref></t>
7375                        <t><xref target="ADD DB_INSTRUMENT_DIRECTORY">"ADD DB_INSTRUMENT_DIRECTORY"</xref></t>
7376                        <t><xref target="ADD DB_INSTRUMENTS">"ADD DB_INSTRUMENTS"</xref></t>
7377                        <t><xref target="REMOVE DB_INSTRUMENT_DIRECTORY">"REMOVE DB_INSTRUMENT_DIRECTORY"</xref></t>
7378                        <t><xref target="REMOVE DB_INSTRUMENT">"REMOVE DB_INSTRUMENT"</xref></t>
7379                        <t><xref target="GET DB_INSTRUMENT_DIRECTORIES">"GET DB_INSTRUMENT_DIRECTORIES"</xref></t>
7380                        <t><xref target="LIST DB_INSTRUMENT_DIRECTORIES">"LIST DB_INSTRUMENT_DIRECTORIES"</xref></t>
7381                        <t><xref target="GET DB_INSTRUMENT_DIRECTORY INFO">"GET DB_INSTRUMENT_DIRECTORY INFO"</xref></t>
7382                        <t><xref target="GET DB_INSTRUMENTS">"GET DB_INSTRUMENTS"</xref></t>
7383                        <t><xref target="LIST DB_INSTRUMENTS">"LIST DB_INSTRUMENTS"</xref></t>
7384                        <t><xref target="GET DB_INSTRUMENT INFO">"GET DB_INSTRUMENT INFO"</xref></t>
7385                        <t><xref target="SET DB_INSTRUMENT_DIRECTORY NAME">"SET DB_INSTRUMENT_DIRECTORY NAME"</xref></t>
7386                        <t><xref target="SET DB_INSTRUMENT_DIRECTORY DESCRIPTION">"SET DB_INSTRUMENT_DIRECTORY DESCRIPTION"</xref></t>
7387                        <t><xref target="SET DB_INSTRUMENT NAME">"SET DB_INSTRUMENT NAME"</xref></t>
7388                        <t><xref target="SET DB_INSTRUMENT DESCRIPTION">"SET DB_INSTRUMENT DESCRIPTION"</xref></t>
7389                        <t><xref target="FIND DB_INSTRUMENTS">"FIND DB_INSTRUMENTS"</xref></t>
7390                        <t><xref target="FIND DB_INSTRUMENT_DIRECTORIES">"FIND DB_INSTRUMENT_DIRECTORIES"</xref></t>
7391                        <t><xref target="MOVE DB_INSTRUMENT">"MOVE DB_INSTRUMENT"</xref></t>
7392                        <t><xref target="MOVE DB_INSTRUMENT_DIRECTORY">"MOVE DB_INSTRUMENT_DIRECTORY"</xref></t>
7393                        <t><xref target="COPY DB_INSTRUMENT">"COPY DB_INSTRUMENT"</xref></t>
7394                        <t><xref target="COPY DB_INSTRUMENT_DIRECTORY">"COPY DB_INSTRUMENT_DIRECTORY"</xref></t>
7395                        <t><xref target="FIND LOST DB_INSTRUMENT_FILES">"FIND LOST DB_INSTRUMENT_FILES"</xref></t>
7396                        <t><xref target="SET DB_INSTRUMENT FILE_PATH">"SET DB_INSTRUMENT FILE_PATH"</xref></t>
7397                        <t><xref target="GET FILE INSTRUMENTS">"GET FILE INSTRUMENTS"</xref></t>
7398                        <t><xref target="LIST FILE INSTRUMENTS">"LIST FILE INSTRUMENTS"</xref></t>
7399                        <t><xref target="GET FILE INSTRUMENT INFO">"GET FILE INSTRUMENT INFO"</xref></t>
7400                    </list>
7401                    Note that the forward slash character ('/') has a special meaning in
7402                    filename / path based arguments: it acts as separator of the nodes in
7403                    the path, thus if a directory- or filename includes a forward slash
7404                    (not intended as path node separator), you MUST escape that slash
7405                    either with the respective hex escape sequence ("\x2f") or with the
7406                    respective octal escape sequence ("\057").
7407                    </t>
7408    
7409                    <t>
7410                    Note for Windows: file path arguments in LSCP are expected
7411                    to use forward slashes as directory node separator similar
7412                    to Unix based operating systems. In contrast to Unix however
7413                    a Windows typical drive character is expected to be
7414                    prefixed to the path. That is an original Windows file path
7415                    like "D:\Sounds\My.gig" would become in LSCP:
7416                    "D:/Sounds/My.gig".
7417                    </t>
7418    
7419                    <t>
7420                    The following LSCP commands even support escape sequences as
7421                    part of at least one of their text-based arguments (i.e. entity name,
7422                    description) and / or may contain escape sequences in at least one of
7423                    their text-based fields in their response:
7424                    <list>
7425                        <t><xref target="GET SERVER INFO">"GET SERVER INFO"</xref></t>
7426                        <t><xref target="GET ENGINE INFO">"GET ENGINE INFO"</xref></t>
7427                        <t><xref target="GET CHANNEL INFO">"GET CHANNEL INFO"</xref></t>
7428                        <t><xref target="CREATE FX_SEND">"CREATE FX_SEND"</xref></t>
7429                        <t><xref target="GET FX_SEND INFO">"GET FX_SEND INFO"</xref></t>
7430                        <t><xref target="SET FX_SEND NAME">"SET FX_SEND NAME"</xref></t>
7431                        <t><xref target="GET MIDI_INSTRUMENT INFO">"GET MIDI_INSTRUMENT INFO"</xref></t>
7432                        <t><xref target="GET MIDI_INSTRUMENT_MAP INFO">"GET MIDI_INSTRUMENT_MAP INFO"</xref></t>
7433                        <t><xref target="ADD MIDI_INSTRUMENT_MAP">"ADD MIDI_INSTRUMENT_MAP"</xref></t>
7434                        <t><xref target="MAP MIDI_INSTRUMENT">"MAP MIDI_INSTRUMENT"</xref></t>
7435                        <t><xref target="SET MIDI_INSTRUMENT_MAP NAME">"SET MIDI_INSTRUMENT_MAP NAME"</xref></t>
7436                        <t><xref target="GET DB_INSTRUMENT_DIRECTORY INFO">"GET DB_INSTRUMENT_DIRECTORY INFO"</xref></t>
7437                        <t><xref target="SET DB_INSTRUMENT_DIRECTORY NAME">"SET DB_INSTRUMENT_DIRECTORY NAME"</xref></t>
7438                        <t><xref target="SET DB_INSTRUMENT_DIRECTORY DESCRIPTION">"SET DB_INSTRUMENT_DIRECTORY DESCRIPTION"</xref></t>
7439                        <t><xref target="FIND DB_INSTRUMENT_DIRECTORIES">"FIND DB_INSTRUMENT_DIRECTORIES"</xref></t>
7440                        <t><xref target="GET DB_INSTRUMENT INFO">"GET DB_INSTRUMENT INFO"</xref></t>
7441                        <t><xref target="SET DB_INSTRUMENT NAME">"SET DB_INSTRUMENT NAME"</xref></t>
7442                        <t><xref target="SET DB_INSTRUMENT DESCRIPTION">"SET DB_INSTRUMENT DESCRIPTION"</xref></t>
7443                        <t><xref target="FIND DB_INSTRUMENTS">"FIND DB_INSTRUMENTS"</xref></t>
7444                    </list>
7445                    Please note that these lists are manually maintained. If you
7446                    find a command that also supports escape sequences we forgot to
7447                    mention here, please report it!
7448                    </t>
7449              </section>              </section>
7450          </section>          </section>
7451    
# Line 6911  Schoenebeck'> Line 7550  Schoenebeck'>
7550                  of sampler channels.</t>                  of sampler channels.</t>
7551              </section>              </section>
7552    
7553                <section title="MIDI data on a sampler channel arrived" anchor="SUBSCRIBE CHANNEL_MIDI">
7554                    <t>Client may want to be notified when MIDI data arrive on sampler channels on
7555                    back-end side, by issuing the following command:</t>
7556                    <t>
7557                        <list>
7558                            <t>SUBSCRIBE CHANNEL_MIDI</t>
7559                        </list>
7560                    </t>
7561                    <t>Server will start sending one of the the following notification messages:</t>
7562                    <t>
7563                        <list>
7564                            <t>"NOTIFY:CHANNEL_MIDI:&lt;channel-id&gt; NOTE_ON  &lt;note&gt; &lt;velocity&gt;"</t>
7565                            <t>"NOTIFY:CHANNEL_MIDI:&lt;channel-id&gt; NOTE_OFF &lt;note&gt; &lt;velocity&gt;"</t>
7566                        </list>
7567                    </t>
7568                    <t>where &lt;channel-id&gt; will be replaced by the ID of the sampler channel where the MIDI
7569                    data arrived. &lt;note&gt; and &lt;velocity&gt; are integer values in the range between
7570                    0 .. 127, reflecting the analog meaning of the MIDI specification.
7571                    </t>
7572                    <t>CAUTION: no guarantee whatsoever will be made that MIDI events are actually all
7573                    delivered by this mechanism! With other words: events could be lost at any time!
7574                    This restriction was made to keep the RT-safeness of the backend's MIDI and audio
7575                    thread unaffected by this feature.</t>
7576                </section>
7577    
7578                <section title="MIDI data on a MIDI input device arrived" anchor="SUBSCRIBE DEVICE_MIDI">
7579                        <t>Client may want to be notified when MIDI data arrive on MIDI input devices by issuing the following command:</t>
7580                        <t>
7581                                <list>
7582                                        <t>SUBSCRIBE DEVICE_MIDI</t>
7583                                </list>
7584                        </t>
7585                        <t>Server will start sending one of the the following notification messages:</t>
7586                        <t>
7587                                <list>
7588                                        <t>"NOTIFY:DEVICE_MIDI:&lt;device-id&gt; &lt;port-id&gt; NOTE_ON &lt;note&gt; &lt;velocity&gt;"</t>
7589                                        <t>"NOTIFY:DEVICE_MIDI:&lt;device-id&gt; &lt;port-id&gt; NOTE_OFF &lt;note&gt; &lt;velocity&gt;"</t>
7590                                </list>
7591                        </t>
7592                        <t>where &lt;device-id&gt; &lt;port-id&gt; will be replaced
7593                           by the IDs of the respective MIDI input device and the device's MIDI port where the MIDI
7594                           data arrived. &lt;note&gt; and &lt;velocity&gt; are integer values in the range between
7595                           0 .. 127, reflecting the analog meaning of the MIDI specification.
7596                        </t>
7597                        <t>CAUTION: no guarantee whatsoever will be made that MIDI events are actually all
7598                           delivered by this mechanism! With other words: events could be lost at any time!
7599                           This restriction was made to keep the RT-safeness of the backend's MIDI and audio
7600                           thread unaffected by this feature.</t>
7601                </section>
7602    
7603              <section title="Number of active voices changed" anchor="SUBSCRIBE VOICE_COUNT">              <section title="Number of active voices changed" anchor="SUBSCRIBE VOICE_COUNT">
7604                  <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
7605                  back-end changes by issuing the following command:</t>                  back-end changes by issuing the following command:</t>
# Line 7048  Schoenebeck'> Line 7737  Schoenebeck'>
7737                  all currently active voices.</t>                  all currently active voices.</t>
7738              </section>              </section>
7739    
7740                <section title="Total number of active disk streams changed" anchor="SUBSCRIBE TOTAL_STREAM_COUNT">
7741                    <t>Client may want to be notified when the total number of disk streams on the
7742                    back-end changes by issuing the following command:</t>
7743                    <t>
7744                        <list>
7745                            <t>SUBSCRIBE TOTAL_STREAM_COUNT</t>
7746                        </list>
7747                    </t>
7748                    <t>Server will start sending the following notification messages:</t>
7749                    <t>
7750                        <list>
7751                            <t>"NOTIFY:TOTAL_STREAM_COUNT:&lt;streams&gt;"</t>
7752                        </list>
7753                    </t>
7754                    <t>where &lt;streams&gt; will be replaced by the new number of
7755                    all currently active disk streams.</t>
7756                </section>
7757    
7758              <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">
7759                  <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
7760                  back-end changes by issuing the following command:</t>                  back-end changes by issuing the following command:</t>
# Line 7146  Schoenebeck'> Line 7853  Schoenebeck'>
7853                          replaced by the optional dotted floating point value, reflecting the                          replaced by the optional dotted floating point value, reflecting the
7854                          new global volume parameter.</t>                          new global volume parameter.</t>
7855                      </list>                      </list>
7856                        <list>
7857                            <t>"NOTIFY:GLOBAL_INFO:VOICES &lt;max-voices&gt;" - Notifies that the
7858                            golbal limit of the sampler for maximum voices is changed, where
7859                            &lt;max-voices&gt; will be an integer value, reflecting the
7860                            new global voice limit parameter.</t>
7861                        </list>
7862                        <list>
7863                            <t>"NOTIFY:GLOBAL_INFO:STREAMS &lt;max-streams&gt;" - Notifies that the
7864                            golbal limit of the sampler for maximum disk streams is changed, where
7865                            &lt;max-streams&gt; will be an integer value, reflecting the
7866                            new global disk streams limit parameter.</t>
7867                        </list>
7868                  </t>                  </t>
7869              </section>              </section>
7870    
Legend:
Removed from v.1362  
changed lines
  Added in v.1800
  ViewVC Help
Powered by ViewVC