/[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 1250 by schoenebeck, Fri Jun 22 14:21:03 2007 UTC revision 1727 by iliev, Tue Apr 29 15:44:09 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="June" year="2007"/>          <date month="April" year="2008"/>
38          <workgroup>LinuxSampler Developers</workgroup>          <workgroup>LinuxSampler Developers</workgroup>
39          <keyword>LSCP</keyword>          <keyword>LSCP</keyword>
40          <abstract>          <abstract>
# Line 2061  Schoenebeck'> Line 2061  Schoenebeck'>
2061                      or <xref target="LIST MIDI_INPUT_DEVICES">"LIST MIDI_INPUT_DEVICES"</xref>                      or <xref target="LIST MIDI_INPUT_DEVICES">"LIST MIDI_INPUT_DEVICES"</xref>
2062                      command, &lt;port&gt; by the MIDI port number, &lt;key&gt; by the name of                      command, &lt;port&gt; by the MIDI port number, &lt;key&gt; by the name of
2063                      the parameter to change and &lt;value&gt; by the new value for this                      the parameter to change and &lt;value&gt; by the new value for this
2064                      parameter.</t>                      parameter (encapsulated into apostrophes) or NONE (not encapsulated into apostrophes)
2065                        for specifying no value for parameters allowing a list of values.</t>
2066    
2067                      <t>Possible Answers:</t>                      <t>Possible Answers:</t>
2068                      <t>                      <t>
# Line 2088  Schoenebeck'> Line 2089  Schoenebeck'>
2089                      <t>Example:</t>                      <t>Example:</t>
2090                      <t>                      <t>
2091                          <list>                          <list>
2092                              <t></t>                              <t>C: "SET MIDI_INPUT_PORT_PARAMETER 0 0 ALSA_SEQ_BINDINGS='20:0'"</t>
2093                                <t>S: "OK"</t>
2094                            </list>
2095                        </t>
2096                        <t>
2097                            <list>
2098                                <t>C: "SET MIDI_INPUT_PORT_PARAMETER 0 0 ALSA_SEQ_BINDINGS=NONE"</t>
2099                                <t>S: "OK"</t>
2100                          </list>                          </list>
2101                      </t>                      </t>
2102                  </section>                  </section>
# Line 2154  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 2435  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 2519  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 2529  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 3247  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 3437  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 3500  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 3904  Schoenebeck'> Line 3932  Schoenebeck'>
3932                      </t>                      </t>
3933                  </section>                  </section>
3934    
3935                    <section title="Current number of active disk streams" anchor="GET TOTAL_STREAM_COUNT">
3936                        <t>The front-end can ask for the current number of active disk streams on
3937                        the sampler by sending the following command:</t>
3938                        <t>
3939                            <list>
3940                                <t>GET TOTAL_STREAM_COUNT</t>
3941                            </list>
3942                        </t>
3943    
3944                        <t>Possible Answers:</t>
3945                        <t>
3946                            <list>
3947                                <t>LinuxSampler will answer by returning the number of all active
3948                                disk streams on the sampler.</t>
3949                            </list>
3950                        </t>
3951                    </section>
3952    
3953                  <section title="Reset sampler" anchor="RESET">                  <section title="Reset sampler" anchor="RESET">
3954                      <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>
3955                      <t>                      <t>
# Line 3951  Schoenebeck'> Line 3997  Schoenebeck'>
3997                                  <list>                                  <list>
3998                                      <t>DESCRIPTION -                                      <t>DESCRIPTION -
3999                                          <list>                                          <list>
4000                                              <t>arbitrary textual description about the sampler</t>                                              <t>arbitrary textual description about the sampler
4001                                                (note that the character string may contain
4002                                                <xref target="character_set">escape sequences</xref>)</t>
4003                                          </list>                                          </list>
4004                                      </t>                                      </t>
4005                                      <t>VERSION -                                      <t>VERSION -
# Line 4067  Schoenebeck'> Line 4115  Schoenebeck'>
4115                  cause the sampler to switch to the respective instrument as                  cause the sampler to switch to the respective instrument as
4116                  reflected by the current MIDI instrument map.</t>                  reflected by the current MIDI instrument map.</t>
4117    
4118                  <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">
4119                      <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
4120                      the following command:</t>                      the following command:</t>
4121                      <t>                      <t>
# Line 4077  Schoenebeck'> Line 4125  Schoenebeck'>
4125                      </t>                      </t>
4126                      <t>Where &lt;name&gt; is an optional argument allowing to                      <t>Where &lt;name&gt; is an optional argument allowing to
4127                      assign a custom name to the new map. MIDI instrument Map                      assign a custom name to the new map. MIDI instrument Map
4128                      names do not have to be unique.</t>                      names do not have to be unique, but MUST be encapsulated
4129                        into apostrophes and support escape sequences as described
4130                        in chapter "<xref target="character_set">Character Set and Escape Sequences</xref>".
4131                        </t>
4132    
4133                      <t>Possible Answers:</t>                      <t>Possible Answers:</t>
4134                      <t>                      <t>
# Line 4248  Schoenebeck'> Line 4299  Schoenebeck'>
4299                                      <t>NAME -                                      <t>NAME -
4300                                          <list>                                          <list>
4301                                              <t>custom name of the given map,                                              <t>custom name of the given map,
4302                                              which does not have to be unique</t>                                              which does not have to be unique
4303                                                (note that this character string may contain
4304                                                 <xref target="character_set">escape sequences</xref>)</t>
4305                                          </list>                                          </list>
4306                                      </t>                                      </t>
4307                                      <t>DEFAULT -                                      <t>DEFAULT -
# Line 4284  Schoenebeck'> Line 4337  Schoenebeck'>
4337                      </t>                      </t>
4338                      <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
4339                      &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
4340                      have to be unique.</t>                      have to be unique (name MUST be encapsulated into apostrophes
4341                        and supports escape sequences as described in chapter
4342                        "<xref target="character_set">Character Set and Escape Sequences</xref>").
4343                        </t>
4344    
4345                      <t>Possible Answers:</t>                      <t>Possible Answers:</t>
4346                      <t>                      <t>
# Line 4415  Schoenebeck'> Line 4471  Schoenebeck'>
4471                      load modes of entries, the frontend should retrieve the actual                      load modes of entries, the frontend should retrieve the actual
4472                      mode by i.e. sending                      mode by i.e. sending
4473                      <xref target="GET MIDI_INSTRUMENT INFO">"GET MIDI_INSTRUMENT INFO"</xref>                      <xref target="GET MIDI_INSTRUMENT INFO">"GET MIDI_INSTRUMENT INFO"</xref>
4474                      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
4475                      set a custom name (encapsulated into apostrophes) for the mapping                      (encapsulated into apostrophes, supporting escape sequences as described in chapter
4476                      entry, useful for frontends for displaying an appropriate name for                      "<xref target="character_set">Character Set and Escape Sequences</xref>") for the
4477                        mapping entry, useful for frontends for displaying an appropriate name for
4478                      mapped instruments (using                      mapped instruments (using
4479                      <xref target="GET MIDI_INSTRUMENT INFO">"GET MIDI_INSTRUMENT INFO"</xref>).                      <xref target="GET MIDI_INSTRUMENT INFO">"GET MIDI_INSTRUMENT INFO"</xref>).
4480                      </t>                      </t>
# Line 4641  Schoenebeck'> Line 4698  Schoenebeck'>
4698                                      name for this mapped instrument. It can be set and                                      name for this mapped instrument. It can be set and
4699                                      changed with the                                      changed with the
4700                                      <xref target="MAP MIDI_INSTRUMENT">"MAP MIDI_INSTRUMENT"</xref>                                      <xref target="MAP MIDI_INSTRUMENT">"MAP MIDI_INSTRUMENT"</xref>
4701                                      command and does not have to be unique.</t>                                      command and does not have to be unique.
4702                                        (note that this character string may contain
4703                                        <xref target="character_set">escape sequences</xref>)</t>
4704                                  </list>                                  </list>
4705                              </t>                              </t>
4706                              <t>"ENGINE_NAME" -                              <t>"ENGINE_NAME" -
# Line 4652  Schoenebeck'> Line 4711  Schoenebeck'>
4711                              </t>                              </t>
4712                              <t>"INSTRUMENT_FILE" -                              <t>"INSTRUMENT_FILE" -
4713                                  <list>                                  <list>
4714                                      <t>File name of the instrument.</t>                                      <t>File name of the instrument
4715                                        (note that this path may contain
4716                                        <xref target="character_set">escape sequences</xref>).</t>
4717                                  </list>                                  </list>
4718                              </t>                              </t>
4719                              <t>"INSTRUMENT_NR" -                              <t>"INSTRUMENT_NR" -
# Line 4664  Schoenebeck'> Line 4725  Schoenebeck'>
4725                                  <list>                                  <list>
4726                                      <t>Name of the loaded instrument as reflected by its file.                                      <t>Name of the loaded instrument as reflected by its file.
4727                                      In contrast to the "NAME" field, the "INSTRUMENT_NAME" field                                      In contrast to the "NAME" field, the "INSTRUMENT_NAME" field
4728                                      cannot be changed.</t>                                      cannot be changed (note that this character string may contain
4729                                        <xref target="character_set">escape sequences</xref>).</t>
4730                                  </list>                                  </list>
4731                              </t>                              </t>
4732                              <t>"LOAD_MODE" -                              <t>"LOAD_MODE" -
# Line 4752  Schoenebeck'> Line 4814  Schoenebeck'>
4814              <section title="Managing Instruments Database" anchor="Managing Instruments Database">              <section title="Managing Instruments Database" anchor="Managing Instruments Database">
4815                  <t>The following commands describe how to use and manage                  <t>The following commands describe how to use and manage
4816                  the instruments database.</t>                  the instruments database.</t>
4817                    <t>Notice:</t>
4818                        <t>
4819                            <list>
4820                                <t>All command arguments representing a path or
4821                                instrument/directory name support escape sequences as described in chapter
4822                                "<xref target="character_set">Character Set and Escape Sequences</xref>".
4823                                </t>
4824                                <t>All occurrences of a forward slash in instrument and directory
4825                                   names are escaped with its hex (\x2f) or octal (\057) escape sequence.
4826                                </t>
4827                            </list>
4828                        </t>
4829    
4830                  <section title="Creating a new instrument directory" anchor="ADD DB_INSTRUMENT_DIRECTORY">                  <section title="Creating a new instrument directory" anchor="ADD DB_INSTRUMENT_DIRECTORY">
4831                      <t>The front-end can add a new instrument directory to the                      <t>The front-end can add a new instrument directory to the
# Line 4929  Schoenebeck'> Line 5003  Schoenebeck'>
5003                                  <list>                                  <list>
5004                                      <t>DESCRIPTION -                                      <t>DESCRIPTION -
5005                                          <list>                                          <list>
5006                                              <t>A brief description of the directory content</t>                                              <t>A brief description of the directory content.
5007                                                Note that the character string may contain
5008                                                <xref target="character_set">escape sequences</xref>.</t>
5009                                          </list>                                          </list>
5010                                      </t>                                      </t>
5011                                      <t>CREATED -                                      <t>CREATED -
# Line 5093  Schoenebeck'> Line 5169  Schoenebeck'>
5169                          </list>                          </list>
5170                      </t>                      </t>
5171                      <t>Where &lt;dir&gt; is the absolute path name of the directory and                      <t>Where &lt;dir&gt; is the absolute path name of the directory and
5172                      &lt;desc&gt; is the new description for the directory.</t>                      &lt;desc&gt; is the new description for the directory
5173                        (encapsulated into apostrophes, supporting escape sequences as described in chapter
5174                        "<xref target="character_set">Character Set and Escape Sequences</xref>").</t>
5175    
5176                      <t>Possible Answers:</t>                      <t>Possible Answers:</t>
5177                      <t>                      <t>
# Line 5138  Schoenebeck'> Line 5216  Schoenebeck'>
5216                        <t>NAME='&lt;search-string&gt;'                        <t>NAME='&lt;search-string&gt;'
5217                            <list>                            <list>
5218                                <t>Restricts the search to directories, which names                                <t>Restricts the search to directories, which names
5219                                satisfy the supplied search string.</t>                                satisfy the supplied search string (encapsulated into apostrophes,
5220                                  supporting escape sequences as described in chapter
5221                                  "<xref target="character_set">Character Set and Escape Sequences</xref>").</t>
5222                            </list>                            </list>
5223                        </t>                        </t>
5224    
# Line 5169  Schoenebeck'> Line 5249  Schoenebeck'>
5249                        <t>DESCRIPTION='&lt;search-string&gt;'                        <t>DESCRIPTION='&lt;search-string&gt;'
5250                            <list>                            <list>
5251                                <t>Restricts the search to directories with description                                <t>Restricts the search to directories with description
5252                                that satisfies the supplied search string.</t>                                that satisfies the supplied search string
5253                                  (encapsulated into apostrophes, supporting escape
5254                                  sequences as described in chapter
5255                                  "<xref target="character_set">Character Set and Escape Sequences</xref>").</t>
5256                            </list>                            </list>
5257                        </t>                        </t>
5258                      </t>                      </t>
# Line 5430  Schoenebeck'> Line 5513  Schoenebeck'>
5513                                  <list>                                  <list>
5514                                      <t>INSTRUMENT_FILE -                                      <t>INSTRUMENT_FILE -
5515                                          <list>                                          <list>
5516                                              <t>File name of the instrument.</t>                                              <t>File name of the instrument.
5517                                                Note that the character string may contain
5518                                                <xref target="character_set">escape sequences</xref>.</t>
5519                                          </list>                                          </list>
5520                                      </t>                                      </t>
5521                                      <t>INSTRUMENT_NR -                                      <t>INSTRUMENT_NR -
# Line 5469  Schoenebeck'> Line 5554  Schoenebeck'>
5554                                      </t>                                      </t>
5555                                      <t>DESCRIPTION -                                      <t>DESCRIPTION -
5556                                          <list>                                          <list>
5557                                              <t>A brief description of the instrument</t>                                              <t>A brief description of the instrument.
5558                                                Note that the character string may contain
5559                                                <xref target="character_set">escape sequences</xref>.</t>
5560                                          </list>                                          </list>
5561                                      </t>                                      </t>
5562                                      <t>IS_DRUM -                                      <t>IS_DRUM -
# Line 5480  Schoenebeck'> Line 5567  Schoenebeck'>
5567                                      </t>                                      </t>
5568                                      <t>PRODUCT -                                      <t>PRODUCT -
5569                                          <list>                                          <list>
5570                                              <t>The product title of the instrument</t>                                              <t>The product title of the instrument.
5571                                                Note that the character string may contain
5572                                                <xref target="character_set">escape sequences</xref>.</t>
5573                                          </list>                                          </list>
5574                                      </t>                                      </t>
5575                                      <t>ARTISTS -                                      <t>ARTISTS -
5576                                          <list>                                          <list>
5577                                              <t>Lists the artist names</t>                                              <t>Lists the artist names.
5578                                                Note that the character string may contain
5579                                                <xref target="character_set">escape sequences</xref>.</t>
5580                                          </list>                                          </list>
5581                                      </t>                                      </t>
5582                                      <t>KEYWORDS -                                      <t>KEYWORDS -
5583                                          <list>                                          <list>
5584                                              <t>Provides a list of keywords that refer to the instrument.                                              <t>Provides a list of keywords that refer to the instrument.
5585                                              Keywords are separated with semicolon and blank.</t>                                              Keywords are separated with semicolon and blank.
5586                                                Note that the character string may contain
5587                                                <xref target="character_set">escape sequences</xref>.</t>
5588                                          </list>                                          </list>
5589                                      </t>                                      </t>
5590                                  </list>                                  </list>
# Line 5648  Schoenebeck'> Line 5741  Schoenebeck'>
5741                          </list>                          </list>
5742                      </t>                      </t>
5743                      <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
5744                      &lt;desc&gt; is the new description for the instrument.</t>                      &lt;desc&gt; is the new description for the instrument
5745                        (encapsulated into apostrophes, supporting escape sequences as described in chapter
5746                        "<xref target="character_set">Character Set and Escape Sequences</xref>").</t>
5747    
5748                      <t>Possible Answers:</t>                      <t>Possible Answers:</t>
5749                      <t>                      <t>
# Line 5693  Schoenebeck'> Line 5788  Schoenebeck'>
5788                        <t>NAME='&lt;search-string&gt;'                        <t>NAME='&lt;search-string&gt;'
5789                            <list>                            <list>
5790                                <t>Restricts the search to instruments, which names                                <t>Restricts the search to instruments, which names
5791                                satisfy the supplied search string.</t>                                satisfy the supplied search string (encapsulated into apostrophes,
5792                                  supporting escape sequences as described in chapter
5793                                  "<xref target="character_set">Character Set and Escape Sequences</xref>").</t>
5794                            </list>                            </list>
5795                        </t>                        </t>
5796    
# Line 5735  Schoenebeck'> Line 5832  Schoenebeck'>
5832                        <t>DESCRIPTION='&lt;search-string&gt;'                        <t>DESCRIPTION='&lt;search-string&gt;'
5833                            <list>                            <list>
5834                                <t>Restricts the search to instruments with description                                <t>Restricts the search to instruments with description
5835                                that satisfies the supplied search string.</t>                                that satisfies the supplied search string (encapsulated into apostrophes,
5836                                  supporting escape sequences as described in chapter
5837                                  "<xref target="character_set">Character Set and Escape Sequences</xref>").</t>
5838                            </list>                            </list>
5839                        </t>                        </t>
5840    
5841                        <t>PRODUCT='&lt;search-string&gt;'                        <t>PRODUCT='&lt;search-string&gt;'
5842                            <list>                            <list>
5843                                <t>Restricts the search to instruments with product info                                <t>Restricts the search to instruments with product info
5844                                that satisfies the supplied search string.</t>                                that satisfies the supplied search string (encapsulated into apostrophes,
5845                                  supporting escape sequences as described in chapter
5846                                  "<xref target="character_set">Character Set and Escape Sequences</xref>").</t>
5847                            </list>                            </list>
5848                        </t>                        </t>
5849    
5850                        <t>ARTISTS='&lt;search-string&gt;'                        <t>ARTISTS='&lt;search-string&gt;'
5851                            <list>                            <list>
5852                                <t>Restricts the search to instruments with artists info                                <t>Restricts the search to instruments with artists info
5853                                that satisfies the supplied search string.</t>                                that satisfies the supplied search string (encapsulated into apostrophes,
5854                                  supporting escape sequences as described in chapter
5855                                  "<xref target="character_set">Character Set and Escape Sequences</xref>").</t>
5856                            </list>                            </list>
5857                        </t>                        </t>
5858    
5859                        <t>KEYWORDS='&lt;search-string&gt;'                        <t>KEYWORDS='&lt;search-string&gt;'
5860                            <list>                            <list>
5861                                <t>Restricts the search to instruments with keyword list                                <t>Restricts the search to instruments with keyword list
5862                                that satisfies the supplied search string.</t>                                that satisfies the supplied search string (encapsulated into apostrophes,
5863                                  supporting escape sequences as described in chapter
5864                                  "<xref target="character_set">Character Set and Escape Sequences</xref>").</t>
5865                            </list>                            </list>
5866                        </t>                        </t>
5867    
# Line 5870  Schoenebeck'> Line 5975  Schoenebeck'>
5975                      </t>                      </t>
5976                  </section>                  </section>
5977    
5978                    <section title="Formatting the instruments database" anchor="FORMAT INSTRUMENTS_DB">
5979                        <t>The front-end can remove all instruments and directories and re-create
5980                        the instruments database structure (e.g., in case of a database corruption)
5981                        by sending the following command:</t>
5982                        <t>
5983                            <list>
5984                                <t>FORMAT INSTRUMENTS_DB</t>
5985                            </list>
5986                        </t>
5987    
5988                        <t>Possible Answers:</t>
5989                        <t>
5990                            <list>
5991                                <t>"OK" -
5992                                    <list>
5993                                        <t>on success</t>
5994                                    </list>
5995                                </t>
5996                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
5997                                    <list>
5998                                        <t>If the formatting of the instruments database
5999                                        failed.</t>
6000                                    </list>
6001                                </t>
6002                            </list>
6003                        </t>
6004                    </section>
6005    
6006                    <section title="Checking for lost instrument files" anchor="FIND LOST DB_INSTRUMENT_FILES">
6007                        <t>The front-end can retrieve the list of all instrument files in the instruments database
6008                        that don't exist in the filesystem by sending the following command:</t>
6009                        <t>
6010                            <list>
6011                                <t>FIND LOST DB_INSTRUMENT_FILES</t>
6012                            </list>
6013                        </t>
6014    
6015                        <t>Possible Answers:</t>
6016                        <t>
6017                            <list>
6018                                <t>A comma separated list with the absolute path names
6019                                (encapsulated into apostrophes) of all lost instrument files.</t>
6020                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
6021                                    <list>
6022                                        <t>in case it failed, providing an appropriate error code and error message.</t>
6023                                    </list>
6024                                </t>
6025                            </list>
6026                        </t>
6027                        <t>Example:</t>
6028                        <t>
6029                            <list>
6030                                <t>C: "FIND LOST DB_INSTRUMENT_FILES"</t>
6031                                <t>S: "'/gigs/Bosendorfer 290.gig','/gigs/Steinway D.gig','/gigs/Free Piano.gig'"</t>
6032                            </list>
6033                        </t>
6034                    </section>
6035    
6036                    <section title="Replacing an instrument file" anchor="SET DB_INSTRUMENT FILE_PATH">
6037                        <t>The front-end can substitute all occurrences of an instrument file
6038                        in the instruments database with a new one by sending the following command:</t>
6039                        <t>
6040                            <list>
6041                                <t>SET DB_INSTRUMENT FILE_PATH &lt;old_path&gt; &lt;new_path&gt;</t>
6042                            </list>
6043                        </t>
6044                        <t>Where &lt;old_path&gt; is the absolute path name of the instrument file
6045                        to substitute with &lt;new_path&gt;.</t>
6046    
6047                        <t>Possible Answers:</t>
6048                        <t>
6049                            <list>
6050                                <t>"OK" -
6051                                    <list>
6052                                        <t>on success</t>
6053                                    </list>
6054                                </t>
6055                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
6056                                    <list>
6057                                        <t>in case it failed, providing an appropriate error code and error message.</t>
6058                                    </list>
6059                                </t>
6060                            </list>
6061                        </t>
6062    
6063                        <t>Example:</t>
6064                        <t>
6065                            <list>
6066                                <t>C: "SET DB_INSTRUMENT FILE_PATH '/gigs/Bosendorfer 290.gig' '/gigs/pianos/Bosendorfer 290.gig'"</t>
6067                                <t>S: "OK"</t>
6068                            </list>
6069                        </t>
6070                    </section>
6071    
6072              </section>              </section>
6073    
         </section>  
6074    
6075    
6076                <section title="Editing Instruments" anchor="editing_instruments">
6077                    <t>The sampler allows to edit instruments while playing with the
6078                    sampler by spawning an external (3rd party) instrument editor
6079                    application for a given instrument. The 3rd party instrument
6080                    editor applications have to place a respective plugin DLL file
6081                    into the sampler's plugins directory. The sampler will
6082                    automatically try to load all plugin DLLs in that directory on
6083                    startup and only on startup!</t>
6084                    <t>At the moment there is only one command for this feature set,
6085                    but this will most probably change in future.</t>
6086    
6087                    <section title="Opening an appropriate instrument editor application" anchor="EDIT INSTRUMENT">
6088                        <t>The front-end can request to open an appropriate instrument
6089                        editor application by sending the following command:</t>
6090                        <t>
6091                            <list>
6092                                <t>EDIT CHANNEL INSTRUMENT &lt;sampler-channel&gt;</t>
6093                            </list>
6094                        </t>
6095                        <t>Where &lt;sampler-channel&gt; should be replaced by the
6096                        number of the sampler channel as given by the
6097                        <xref target="ADD CHANNEL">"ADD CHANNEL"</xref>
6098                        or <xref target="LIST CHANNELS">"LIST CHANNELS"</xref>
6099                        command.</t>
6100    
6101                        <t>The sampler will try to ask all registered instrument
6102                        editors (or to be more specific: their sampler plugins)
6103                        whether they are capable to handle the instrument on the
6104                        given sampler channel. The sampler will simply use the first
6105                        instrument editor application which replied with a positive
6106                        answer and spawn that instrument editor application within
6107                        the sampler's process and provide that application access
6108                        to the instrument's data structures, so both applications
6109                        can share and access the same instruments data at the same
6110                        time, thus allowing to immediately hear changes with the
6111                        sampler made by the instrument editor.</t>
6112    
6113                        <t>Note: consequently instrument editors are always spawned
6114                        locally on the same machine where the sampler is running
6115                        on!</t>
6116    
6117                        <t>Possible Answers:</t>
6118                        <t>
6119                            <list>
6120                                <t>"OK" -
6121                                    <list>
6122                                        <t>when an appropriate instrument editor was
6123                                        launched</t>
6124                                    </list>
6125                                </t>
6126                                <t>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
6127                                    <list>
6128                                        <t>when an appropriate instrument editor was
6129                                        launched, but there are noteworthy issues</t>
6130                                    </list>
6131                                </t>
6132                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
6133                                    <list>
6134                                        <t>when an appropriate instrument editor
6135                                        could not be launched</t>
6136                                    </list>
6137                                </t>
6138                            </list>
6139                        </t>
6140    
6141                        <t>Examples:</t>
6142                        <t>
6143                            <list>
6144                                <t>C: "EDIT CHANNEL INSTRUMENT 0"</t>
6145                                <t>S: "OK"</t>
6146                            </list>
6147                        </t>
6148                    </section>
6149                </section>
6150    
6151                <section title="Managing Files" anchor="file_management">
6152                    <t>You can query detailed informations about files located
6153                    at the same system where the sampler instance is running on.
6154                    Using this command set allows to retrieve file informations
6155                    even remotely from another machine.</t>
6156    
6157                    <section title="Retrieving amount of instruments of a file" anchor="GET FILE INSTRUMENTS">
6158                        <t>The front-end can retrieve the amount of instruments
6159                        within a given instrument file by sending the
6160                        following command:</t>
6161                        <t>
6162                            <list>
6163                                <t>GET FILE INSTRUMENTS &lt;filename&gt;</t>
6164                            </list>
6165                        </t>
6166                        <t>Where &lt;filename&gt; is the name of the instrument
6167                        file (encapsulated into apostrophes, supporting escape
6168                        sequences as described in chapter
6169                        "<xref target="character_set">Character Set and Escape
6170                            Sequences</xref>").</t>
6171    
6172                        <t>The sampler will try to ask all sampler engines,
6173                        whether they support the given file and ask the first
6174                        engine with a positive answer for the amount of
6175                        instruments.</t>
6176    
6177                        <t>Possible Answers:</t>
6178                        <t>
6179                            <list>
6180                                <t>On success, the sampler will answer by
6181                                   returning the amount of instruments.
6182                                </t>
6183                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
6184                                    <list>
6185                                        <t>if the file could not be handled</t>
6186                                    </list>
6187                                </t>
6188                            </list>
6189                        </t>
6190    
6191                        <t>Examples:</t>
6192                        <t>
6193                            <list>
6194                                <t>C: "GET FILE INSTRUMENTS 'D:/Sounds/Foo.gig'"</t>
6195                                <t>S: "10"</t>
6196                            </list>
6197                        </t>
6198                    </section>
6199    
6200                    <section title="Retrieving all instruments of a file" anchor="LIST FILE INSTRUMENTS">
6201                        <t>The front-end can retrieve a list of all instruments
6202                        within a given instrument file by sending the
6203                        following command:</t>
6204                        <t>
6205                            <list>
6206                                <t>LIST FILE INSTRUMENTS &lt;filename&gt;</t>
6207                            </list>
6208                        </t>
6209                        <t>Where &lt;filename&gt; is the name of the instrument
6210                        file (encapsulated into apostrophes, supporting escape
6211                        sequences as described in chapter
6212                        "<xref target="character_set">Character Set and Escape
6213                            Sequences</xref>").</t>
6214    
6215                        <t>The sampler will try to ask all sampler engines,
6216                        whether they support the given file and ask the first
6217                        engine with a positive answer for a list of IDs for the
6218                        instruments in the given file.</t>
6219    
6220                        <t>Possible Answers:</t>
6221                        <t>
6222                            <list>
6223                                <t>On success, the sampler will answer by
6224                                   returning a comma separated list of
6225                                   instrument IDs.
6226                                </t>
6227                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
6228                                    <list>
6229                                        <t>if the file could not be handled</t>
6230                                    </list>
6231                                </t>
6232                            </list>
6233                        </t>
6234    
6235                        <t>Examples:</t>
6236                        <t>
6237                            <list>
6238                                <t>C: "LIST FILE INSTRUMENTS 'D:/Sounds/Foo.gig'"</t>
6239                                <t>S: "0,1,2,3,4,5,6,7,8,9"</t>
6240                            </list>
6241                        </t>
6242                    </section>
6243    
6244                    <section title="Retrieving informations about one instrument in a file" anchor="GET FILE INSTRUMENT INFO">
6245                        <t>The front-end can retrieve detailed informations
6246                        about a specific instrument within a given instrument
6247                        file by sending the following command:</t>
6248                        <t>
6249                            <list>
6250                                <t>GET FILE INSTRUMENT INFO &lt;filename&gt;
6251                                &lt;instr-id&gt;</t>
6252                            </list>
6253                        </t>
6254                        <t>Where &lt;filename&gt; is the name of the instrument
6255                        file (encapsulated into apostrophes, supporting escape
6256                        sequences as described in chapter
6257                        "<xref target="character_set">Character Set and Escape
6258                            Sequences</xref>") and &lt;instr-id&gt; is the numeric
6259                        instrument ID as returned by the
6260                        <xref target="LIST FILE INSTRUMENTS">
6261                        "LIST FILE INSTRUMENTS"</xref> command.</t>
6262    
6263                        <t>The sampler will try to ask all sampler engines,
6264                        whether they support the given file and ask the first
6265                        engine with a positive answer for informations about the
6266                        specific instrument in the given file.</t>
6267    
6268                        <t>Possible Answers:</t>
6269                        <t>
6270                            <list>
6271                                <t>LinuxSampler will answer by sending a &lt;CRLF&gt; separated list.
6272                                Each answer line begins with the settings category name
6273                                followed by a colon and then a space character &lt;SP&gt; and finally
6274                                the info character string to that setting category. At the
6275                                moment the following categories are defined:</t>
6276    
6277                                <t>
6278                                    <list>
6279                                        <t>NAME -
6280                                            <list>
6281                                                <t>name of the instrument as
6282                                                stored in the instrument file</t>
6283                                            </list>
6284                                        </t>
6285                                        <t>FORMAT_FAMILY -
6286                                            <list>
6287                                                <t>name of the sampler format
6288                                                of the given instrument</t>
6289                                            </list>
6290                                        </t>
6291                                        <t>FORMAT_VERSION -
6292                                            <list>
6293                                                <t>version of the sampler format
6294                                                the instrumen is stored as</t>
6295                                            </list>
6296                                        </t>
6297                                        <t>PRODUCT -
6298                                            <list>
6299                                                <t>official product name of the
6300                                                instrument as stored in the file
6301                                                </t>
6302                                            </list>
6303                                        </t>
6304                                        <t>ARTISTS -
6305                                            <list>
6306                                                <t>artists / sample library
6307                                                vendor of the instrument</t>
6308                                            </list>
6309                                        </t>
6310                                    </list>
6311                                </t>
6312                            </list>
6313                        </t>
6314                        <t>The mentioned fields above don't have to be in particular order.</t>
6315    
6316                        <t>Example:</t>
6317                        <t>
6318                            <list>
6319                                <t>C: "GET FILE INSTRUMENT INFO 'D:/Sounds/Foo.gig' 0"</t>
6320                                <t>S: "NAME: Lunatic Loops"</t>
6321                                <t>&nbsp;&nbsp;&nbsp;"FORMAT_FAMILY: GIG"</t>
6322                                <t>&nbsp;&nbsp;&nbsp;"FORMAT_VERSION: 3"</t>
6323                                <t>&nbsp;&nbsp;&nbsp;"PRODUCT: The Backbone Bongo Beats"</t>
6324                                <t>&nbsp;&nbsp;&nbsp;"ARTISTS: Jimmy the Fish"</t>
6325                                <t>&nbsp;&nbsp;&nbsp;"."</t>
6326                            </list>
6327                        </t>
6328                    </section>
6329                </section>
6330            </section>
6331    
6332          <section title="Command Syntax" anchor="command_syntax">          <section title="Command Syntax" anchor="command_syntax">
6333              <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"/>
6334              is defined below using Backus-Naur Form (BNF as described in <xref target="RFC2234"/>)              is defined below using Backus-Naur Form (BNF as described in <xref target="RFC2234"/>)
# Line 5959  Schoenebeck'> Line 6413  Schoenebeck'>
6413                  </t>                  </t>
6414                  <t>/ EDIT SP edit_instruction                  <t>/ EDIT SP edit_instruction
6415                  </t>                  </t>
6416                    <t>/ FORMAT SP format_instruction
6417                    </t>
6418                  <t>/ RESET                  <t>/ RESET
6419                  </t>                  </t>
6420                  <t>/ QUIT                  <t>/ QUIT
# Line 5969  Schoenebeck'> Line 6425  Schoenebeck'>
6425          <list>          <list>
6426                  <t>CHANNEL                  <t>CHANNEL
6427                  </t>                  </t>
6428                  <t>/ DB_INSTRUMENT_DIRECTORY SP pathname                  <t>/ DB_INSTRUMENT_DIRECTORY SP db_path
6429                  </t>                  </t>
6430                  <t>/ DB_INSTRUMENTS SP NON_MODAL SP scan_mode SP pathname SP pathname                  <t>/ DB_INSTRUMENTS SP NON_MODAL SP scan_mode SP db_path SP filename
6431                  </t>                  </t>
6432                  <t>/ DB_INSTRUMENTS SP scan_mode SP pathname SP pathname                  <t>/ DB_INSTRUMENTS SP scan_mode SP db_path SP filename
6433                  </t>                  </t>
6434                  <t>/ DB_INSTRUMENTS SP NON_MODAL SP pathname SP pathname                  <t>/ DB_INSTRUMENTS SP NON_MODAL SP db_path SP filename
6435                  </t>                  </t>
6436                  <t>/ DB_INSTRUMENTS SP NON_MODAL SP pathname SP pathname SP instrument_index                  <t>/ DB_INSTRUMENTS SP NON_MODAL SP db_path SP filename SP instrument_index
6437                  </t>                  </t>
6438                  <t>/ DB_INSTRUMENTS SP pathname SP pathname                  <t>/ DB_INSTRUMENTS SP db_path SP filename
6439                  </t>                  </t>
6440                  <t>/ DB_INSTRUMENTS SP pathname SP pathname SP instrument_index                  <t>/ DB_INSTRUMENTS SP db_path SP filename SP instrument_index
6441                  </t>                  </t>
6442                  <t>/ MIDI_INSTRUMENT_MAP                  <t>/ MIDI_INSTRUMENT_MAP
6443                  </t>                  </t>
# Line 6001  Schoenebeck'> Line 6457  Schoenebeck'>
6457                  </t>                  </t>
6458                  <t>/ CHANNEL_COUNT                  <t>/ CHANNEL_COUNT
6459                  </t>                  </t>
6460                    <t>/ CHANNEL_MIDI
6461                    </t>
6462                    <t>/ DEVICE_MIDI
6463                    </t>
6464                  <t>/ VOICE_COUNT                  <t>/ VOICE_COUNT
6465                  </t>                  </t>
6466                  <t>/ STREAM_COUNT                  <t>/ STREAM_COUNT
# Line 6033  Schoenebeck'> Line 6493  Schoenebeck'>
6493                  </t>                  </t>
6494                  <t>/ MISCELLANEOUS                  <t>/ MISCELLANEOUS
6495                  </t>                  </t>
6496                    <t>/ TOTAL_STREAM_COUNT
6497                    </t>
6498                  <t>/ TOTAL_VOICE_COUNT                  <t>/ TOTAL_VOICE_COUNT
6499                  </t>                  </t>
6500                  <t>/ GLOBAL_INFO                  <t>/ GLOBAL_INFO
# Line 6051  Schoenebeck'> Line 6513  Schoenebeck'>
6513                  </t>                  </t>
6514                  <t>/ CHANNEL_COUNT                  <t>/ CHANNEL_COUNT
6515                  </t>                  </t>
6516                    <t>/ CHANNEL_MIDI
6517                    </t>
6518                    <t>/ DEVICE_MIDI
6519                    </t>
6520                  <t>/ VOICE_COUNT                  <t>/ VOICE_COUNT
6521                  </t>                  </t>
6522                  <t>/ STREAM_COUNT                  <t>/ STREAM_COUNT
# Line 6083  Schoenebeck'> Line 6549  Schoenebeck'>
6549                  </t>                  </t>
6550                  <t>/ MISCELLANEOUS                  <t>/ MISCELLANEOUS
6551                  </t>                  </t>
6552                    <t>/ TOTAL_STREAM_COUNT
6553                    </t>
6554                  <t>/ TOTAL_VOICE_COUNT                  <t>/ TOTAL_VOICE_COUNT
6555                  </t>                  </t>
6556                  <t>/ GLOBAL_INFO                  <t>/ GLOBAL_INFO
# Line 6115  Schoenebeck'> Line 6583  Schoenebeck'>
6583                  </t>                  </t>
6584                  <t>/ MIDI_INSTRUMENT_MAP SP ALL                  <t>/ MIDI_INSTRUMENT_MAP SP ALL
6585                  </t>                  </t>
6586                  <t>/ DB_INSTRUMENT_DIRECTORY SP FORCE SP pathname                  <t>/ DB_INSTRUMENT_DIRECTORY SP FORCE SP db_path
6587                  </t>                  </t>
6588                  <t>/ DB_INSTRUMENT_DIRECTORY SP pathname                  <t>/ DB_INSTRUMENT_DIRECTORY SP db_path
6589                  </t>                  </t>
6590                  <t>/ DB_INSTRUMENT SP pathname                  <t>/ DB_INSTRUMENT SP db_path
6591                  </t>                  </t>
6592          </list>          </list>
6593  </t>  </t>
# Line 6173  Schoenebeck'> Line 6641  Schoenebeck'>
6641                  </t>                  </t>
6642                  <t>/ SERVER SP INFO                  <t>/ SERVER SP INFO
6643                  </t>                  </t>
6644                    <t>/ TOTAL_STREAM_COUNT
6645                    </t>
6646                  <t>/ TOTAL_VOICE_COUNT                  <t>/ TOTAL_VOICE_COUNT
6647                  </t>                  </t>
6648                  <t>/ TOTAL_VOICE_COUNT_MAX                  <t>/ TOTAL_VOICE_COUNT_MAX
# Line 6191  Schoenebeck'> Line 6661  Schoenebeck'>
6661                  </t>                  </t>
6662                  <t>/ FX_SEND SP INFO SP sampler_channel SP fx_send_id                  <t>/ FX_SEND SP INFO SP sampler_channel SP fx_send_id
6663                  </t>                  </t>
6664                  <t>/ DB_INSTRUMENT_DIRECTORIES SP RECURSIVE SP pathname                  <t>/ DB_INSTRUMENT_DIRECTORIES SP RECURSIVE SP db_path
6665                  </t>                  </t>
6666                  <t>/ DB_INSTRUMENT_DIRECTORIES SP pathname                  <t>/ DB_INSTRUMENT_DIRECTORIES SP db_path
6667                  </t>                  </t>
6668                  <t>/ DB_INSTRUMENT_DIRECTORY SP INFO SP pathname                  <t>/ DB_INSTRUMENT_DIRECTORY SP INFO SP db_path
6669                  </t>                  </t>
6670                  <t>/ DB_INSTRUMENTS SP RECURSIVE SP pathname                  <t>/ DB_INSTRUMENTS SP RECURSIVE SP db_path
6671                  </t>                  </t>
6672                  <t>/ DB_INSTRUMENTS SP pathname                  <t>/ DB_INSTRUMENTS SP db_path
6673                  </t>                  </t>
6674                  <t>/ DB_INSTRUMENT SP INFO SP pathname                  <t>/ DB_INSTRUMENT SP INFO SP db_path
6675                  </t>                  </t>
6676                  <t>/ DB_INSTRUMENTS_JOB SP INFO SP number                  <t>/ DB_INSTRUMENTS_JOB SP INFO SP number
6677                  </t>                  </t>
6678                  <t>/ VOLUME                  <t>/ VOLUME
6679                  </t>                  </t>
6680                    <t>/ FILE SP INSTRUMENTS SP filename
6681                    </t>
6682                    <t>/ FILE SP INSTRUMENT SP INFO SP filename SP instrument_index
6683                    </t>
6684          </list>          </list>
6685  </t>  </t>
6686  <t>set_instruction =  <t>set_instruction =
# Line 6217  Schoenebeck'> Line 6691  Schoenebeck'>
6691                  </t>                  </t>
6692                  <t>/ MIDI_INPUT_DEVICE_PARAMETER SP number SP string '=' param_val_list                  <t>/ MIDI_INPUT_DEVICE_PARAMETER SP number SP string '=' param_val_list
6693                  </t>                  </t>
6694                    <t>/ MIDI_INPUT_PORT_PARAMETER SP number SP number SP string '=' NONE
6695                    </t>
6696                  <t>/ MIDI_INPUT_PORT_PARAMETER SP number SP number SP string '=' param_val_list                  <t>/ MIDI_INPUT_PORT_PARAMETER SP number SP number SP string '=' param_val_list
6697                  </t>                  </t>
6698                  <t>/ CHANNEL SP set_chan_instruction                  <t>/ CHANNEL SP set_chan_instruction
# Line 6231  Schoenebeck'> Line 6707  Schoenebeck'>
6707                  </t>                  </t>
6708                  <t>/ FX_SEND SP LEVEL SP sampler_channel SP fx_send_id SP volume_value                  <t>/ FX_SEND SP LEVEL SP sampler_channel SP fx_send_id SP volume_value
6709                  </t>                  </t>
6710                  <t>/ DB_INSTRUMENT_DIRECTORY SP NAME SP pathname SP dirname                  <t>/ DB_INSTRUMENT_DIRECTORY SP NAME SP db_path SP stringval_escaped
6711                    </t>
6712                    <t>/ DB_INSTRUMENT_DIRECTORY SP DESCRIPTION SP db_path SP stringval_escaped
6713                  </t>                  </t>
6714                  <t>/ DB_INSTRUMENT_DIRECTORY SP DESCRIPTION SP pathname SP stringval                  <t>/ DB_INSTRUMENT SP NAME SP db_path SP stringval_escaped
6715                  </t>                  </t>
6716                  <t>/ DB_INSTRUMENT SP NAME SP pathname SP dirname                  <t>/ DB_INSTRUMENT SP DESCRIPTION SP db_path SP stringval_escaped
6717                  </t>                  </t>
6718                  <t>/ DB_INSTRUMENT SP DESCRIPTION SP pathname SP stringval                  <t>/ DB_INSTRUMENT SP FILE_PATH SP filename SP filename
6719                  </t>                  </t>
6720                  <t>/ ECHO SP boolean                  <t>/ ECHO SP boolean
6721                  </t>                  </t>
# Line 6277  Schoenebeck'> Line 6755  Schoenebeck'>
6755  </t>  </t>
6756  <t>find_instruction =  <t>find_instruction =
6757          <list>          <list>
6758                  <t>DB_INSTRUMENTS SP NON_RECURSIVE SP pathname SP query_val_list                  <t>DB_INSTRUMENTS SP NON_RECURSIVE SP db_path SP query_val_list
6759                  </t>                  </t>
6760                  <t>/ DB_INSTRUMENTS SP pathname SP query_val_list                  <t>/ DB_INSTRUMENTS SP db_path SP query_val_list
6761                  </t>                  </t>
6762                  <t>/ DB_INSTRUMENT_DIRECTORIES SP NON_RECURSIVE SP pathname SP query_val_list                  <t>/ DB_INSTRUMENT_DIRECTORIES SP NON_RECURSIVE SP db_path SP query_val_list
6763                  </t>                  </t>
6764                  <t>/ DB_INSTRUMENT_DIRECTORIES SP pathname SP query_val_list                  <t>/ DB_INSTRUMENT_DIRECTORIES SP db_path SP query_val_list
6765                    </t>
6766                    <t>/ LOST SP DB_INSTRUMENT_FILES
6767                  </t>                  </t>
6768          </list>          </list>
6769  </t>  </t>
6770  <t>move_instruction =  <t>move_instruction =
6771          <list>          <list>
6772                  <t>DB_INSTRUMENT_DIRECTORY SP pathname SP pathname                  <t>DB_INSTRUMENT_DIRECTORY SP db_path SP db_path
6773                  </t>                  </t>
6774                  <t>/ DB_INSTRUMENT SP pathname SP pathname                  <t>/ DB_INSTRUMENT SP db_path SP db_path
6775                  </t>                  </t>
6776          </list>          </list>
6777  </t>  </t>
6778  <t>copy_instruction =  <t>copy_instruction =
6779          <list>          <list>
6780                  <t>DB_INSTRUMENT_DIRECTORY SP pathname SP pathname                  <t>DB_INSTRUMENT_DIRECTORY SP db_path SP db_path
6781                  </t>                  </t>
6782                  <t>/ DB_INSTRUMENT SP pathname SP pathname                  <t>/ DB_INSTRUMENT SP db_path SP db_path
6783                  </t>                  </t>
6784          </list>          </list>
6785  </t>  </t>
# Line 6355  Schoenebeck'> Line 6835  Schoenebeck'>
6835  </t>  </t>
6836  <t>edit_instruction =  <t>edit_instruction =
6837          <list>          <list>
6838                  <t>INSTRUMENT SP sampler_channel                  <t>CHANNEL SP INSTRUMENT SP sampler_channel
6839                    </t>
6840            </list>
6841    </t>
6842    <t>format_instruction =
6843            <list>
6844                    <t>INSTRUMENTS_DB
6845                  </t>                  </t>
6846          </list>          </list>
6847  </t>  </t>
# Line 6405  Schoenebeck'> Line 6891  Schoenebeck'>
6891                  </t>                  </t>
6892                  <t>/ FX_SENDS SP sampler_channel                  <t>/ FX_SENDS SP sampler_channel
6893                  </t>                  </t>
6894                  <t>/ DB_INSTRUMENT_DIRECTORIES SP RECURSIVE SP pathname                  <t>/ DB_INSTRUMENT_DIRECTORIES SP RECURSIVE SP db_path
6895                  </t>                  </t>
6896                  <t>/ DB_INSTRUMENT_DIRECTORIES SP pathname                  <t>/ DB_INSTRUMENT_DIRECTORIES SP db_path
6897                  </t>                  </t>
6898                  <t>/ DB_INSTRUMENTS SP RECURSIVE SP pathname                  <t>/ DB_INSTRUMENTS SP RECURSIVE SP db_path
6899                  </t>                  </t>
6900                  <t>/ DB_INSTRUMENTS SP pathname                  <t>/ DB_INSTRUMENTS SP db_path
6901                    </t>
6902                    <t>/ FILE SP INSTRUMENTS SP filename
6903                  </t>                  </t>
6904          </list>          </list>
6905  </t>  </t>
# Line 6533  Schoenebeck'> Line 7021  Schoenebeck'>
7021                  </t>                  </t>
7022          </list>          </list>
7023  </t>  </t>
7024  <t>pathname =  <t>filename =
         <list>  
                 <t>stringval  
                 </t>  
         </list>  
 </t>  
 <t>dirname =  
7025          <list>          <list>
7026                  <t>stringval                  <t>path
7027                  </t>                  </t>
7028          </list>          </list>
7029  </t>  </t>
7030  <t>filename =  <t>db_path =
7031          <list>          <list>
7032                  <t>stringval_escaped                  <t>path
7033                  </t>                  </t>
7034          </list>          </list>
7035  </t>  </t>
7036  <t>map_name =  <t>map_name =
7037          <list>          <list>
7038                  <t>stringval                  <t>stringval_escaped
7039                  </t>                  </t>
7040          </list>          </list>
7041  </t>  </t>
7042  <t>entry_name =  <t>entry_name =
7043          <list>          <list>
7044                  <t>stringval                  <t>stringval_escaped
7045                  </t>                  </t>
7046          </list>          </list>
7047  </t>  </t>
7048  <t>fx_send_name =  <t>fx_send_name =
7049          <list>          <list>
7050                  <t>stringval                  <t>stringval_escaped
7051                  </t>                  </t>
7052          </list>          </list>
7053  </t>  </t>
# Line 6577  Schoenebeck'> Line 7059  Schoenebeck'>
7059                  </t>                  </t>
7060          </list>          </list>
7061  </t>  </t>
7062    
7063  <t>param_val =  <t>param_val =
7064          <list>          <list>
7065                  <t>string                  <t>string
# Line 6599  Schoenebeck'> Line 7082  Schoenebeck'>
7082  </t>  </t>
7083  <t>query_val =  <t>query_val =
7084          <list>          <list>
7085                  <t>string                  <t>text_escaped
7086                  </t>                  </t>
7087                  <t>/ stringval                  <t>/ stringval_escaped
7088                  </t>                  </t>
7089          </list>          </list>
7090  </t>  </t>
# Line 6648  Schoenebeck'> Line 7131  Schoenebeck'>
7131                  where escape characters are now supported, a backslash characters                  where escape characters are now supported, a backslash characters
7132                  MUST be escaped as well (that is as double backslash), whereas                  MUST be escaped as well (that is as double backslash), whereas
7133                  in the old versions a single backslash was sufficient.</t>                  in the old versions a single backslash was sufficient.</t>
7134    
7135                    <t>The following LSCP commands support escape sequences as part
7136                    of their filename / path based arguments and / or may contain
7137                    a filename / path with escape sequences in their response:
7138                    <list>
7139                        <t><xref target="LOAD INSTRUMENT">"LOAD INSTRUMENT"</xref></t>
7140                        <t><xref target="GET CHANNEL INFO">"GET CHANNEL INFO"</xref></t>
7141                        <t><xref target="MAP MIDI_INSTRUMENT">"MAP MIDI_INSTRUMENT"</xref></t>
7142                        <t><xref target="GET MIDI_INSTRUMENT INFO">"GET MIDI_INSTRUMENT INFO"</xref></t>
7143                        <t><xref target="ADD DB_INSTRUMENT_DIRECTORY">"ADD DB_INSTRUMENT_DIRECTORY"</xref></t>
7144                        <t><xref target="ADD DB_INSTRUMENTS">"ADD DB_INSTRUMENTS"</xref></t>
7145                        <t><xref target="REMOVE DB_INSTRUMENT_DIRECTORY">"REMOVE DB_INSTRUMENT_DIRECTORY"</xref></t>
7146                        <t><xref target="REMOVE DB_INSTRUMENT">"REMOVE DB_INSTRUMENT"</xref></t>
7147                        <t><xref target="GET DB_INSTRUMENT_DIRECTORIES">"GET DB_INSTRUMENT_DIRECTORIES"</xref></t>
7148                        <t><xref target="LIST DB_INSTRUMENT_DIRECTORIES">"LIST DB_INSTRUMENT_DIRECTORIES"</xref></t>
7149                        <t><xref target="GET DB_INSTRUMENT_DIRECTORY INFO">"GET DB_INSTRUMENT_DIRECTORY INFO"</xref></t>
7150                        <t><xref target="GET DB_INSTRUMENTS">"GET DB_INSTRUMENTS"</xref></t>
7151                        <t><xref target="LIST DB_INSTRUMENTS">"LIST DB_INSTRUMENTS"</xref></t>
7152                        <t><xref target="GET DB_INSTRUMENT INFO">"GET DB_INSTRUMENT INFO"</xref></t>
7153                        <t><xref target="SET DB_INSTRUMENT_DIRECTORY NAME">"SET DB_INSTRUMENT_DIRECTORY NAME"</xref></t>
7154                        <t><xref target="SET DB_INSTRUMENT_DIRECTORY DESCRIPTION">"SET DB_INSTRUMENT_DIRECTORY DESCRIPTION"</xref></t>
7155                        <t><xref target="SET DB_INSTRUMENT NAME">"SET DB_INSTRUMENT NAME"</xref></t>
7156                        <t><xref target="SET DB_INSTRUMENT DESCRIPTION">"SET DB_INSTRUMENT DESCRIPTION"</xref></t>
7157                        <t><xref target="FIND DB_INSTRUMENTS">"FIND DB_INSTRUMENTS"</xref></t>
7158                        <t><xref target="FIND DB_INSTRUMENT_DIRECTORIES">"FIND DB_INSTRUMENT_DIRECTORIES"</xref></t>
7159                        <t><xref target="MOVE DB_INSTRUMENT">"MOVE DB_INSTRUMENT"</xref></t>
7160                        <t><xref target="MOVE DB_INSTRUMENT_DIRECTORY">"MOVE DB_INSTRUMENT_DIRECTORY"</xref></t>
7161                        <t><xref target="COPY DB_INSTRUMENT">"COPY DB_INSTRUMENT"</xref></t>
7162                        <t><xref target="COPY DB_INSTRUMENT_DIRECTORY">"COPY DB_INSTRUMENT_DIRECTORY"</xref></t>
7163                        <t><xref target="FIND LOST DB_INSTRUMENT_FILES">"FIND LOST DB_INSTRUMENT_FILES"</xref></t>
7164                        <t><xref target="SET DB_INSTRUMENT FILE_PATH">"SET DB_INSTRUMENT FILE_PATH"</xref></t>
7165                        <t><xref target="GET FILE INSTRUMENTS">"GET FILE INSTRUMENTS"</xref></t>
7166                        <t><xref target="LIST FILE INSTRUMENTS">"LIST FILE INSTRUMENTS"</xref></t>
7167                        <t><xref target="GET FILE INSTRUMENT INFO">"GET FILE INSTRUMENT INFO"</xref></t>
7168                    </list>
7169                    Note that the forward slash character ('/') has a special meaning in
7170                    filename / path based arguments: it acts as separator of the nodes in
7171                    the path, thus if a directory- or filename includes a forward slash
7172                    (not intended as path node separator), you MUST escape that slash
7173                    either with the respective hex escape sequence ("\x2f") or with the
7174                    respective octal escape sequence ("\057").
7175                    </t>
7176    
7177                    <t>
7178                    Note for Windows: file path arguments in LSCP are expected
7179                    to use forward slashes as directory node separator similar
7180                    to Unix based operating systems. In contrast to Unix however
7181                    a Windows typical drive character is expected to be
7182                    prefixed to the path. That is an original Windows file path
7183                    like "D:\Sounds\My.gig" would become in LSCP:
7184                    "D:/Sounds/My.gig".
7185                    </t>
7186    
7187                    <t>
7188                    The following LSCP commands even support escape sequences as
7189                    part of at least one of their text-based arguments (i.e. entity name,
7190                    description) and / or may contain escape sequences in at least one of
7191                    their text-based fields in their response:
7192                    <list>
7193                        <t><xref target="GET SERVER INFO">"GET SERVER INFO"</xref></t>
7194                        <t><xref target="GET ENGINE INFO">"GET ENGINE INFO"</xref></t>
7195                        <t><xref target="GET CHANNEL INFO">"GET CHANNEL INFO"</xref></t>
7196                        <t><xref target="CREATE FX_SEND">"CREATE FX_SEND"</xref></t>
7197                        <t><xref target="GET FX_SEND INFO">"GET FX_SEND INFO"</xref></t>
7198                        <t><xref target="SET FX_SEND NAME">"SET FX_SEND NAME"</xref></t>
7199                        <t><xref target="GET MIDI_INSTRUMENT INFO">"GET MIDI_INSTRUMENT INFO"</xref></t>
7200                        <t><xref target="GET MIDI_INSTRUMENT_MAP INFO">"GET MIDI_INSTRUMENT_MAP INFO"</xref></t>
7201                        <t><xref target="ADD MIDI_INSTRUMENT_MAP">"ADD MIDI_INSTRUMENT_MAP"</xref></t>
7202                        <t><xref target="MAP MIDI_INSTRUMENT">"MAP MIDI_INSTRUMENT"</xref></t>
7203                        <t><xref target="SET MIDI_INSTRUMENT_MAP NAME">"SET MIDI_INSTRUMENT_MAP NAME"</xref></t>
7204                        <t><xref target="GET DB_INSTRUMENT_DIRECTORY INFO">"GET DB_INSTRUMENT_DIRECTORY INFO"</xref></t>
7205                        <t><xref target="SET DB_INSTRUMENT_DIRECTORY NAME">"SET DB_INSTRUMENT_DIRECTORY NAME"</xref></t>
7206                        <t><xref target="SET DB_INSTRUMENT_DIRECTORY DESCRIPTION">"SET DB_INSTRUMENT_DIRECTORY DESCRIPTION"</xref></t>
7207                        <t><xref target="FIND DB_INSTRUMENT_DIRECTORIES">"FIND DB_INSTRUMENT_DIRECTORIES"</xref></t>
7208                        <t><xref target="GET DB_INSTRUMENT INFO">"GET DB_INSTRUMENT INFO"</xref></t>
7209                        <t><xref target="SET DB_INSTRUMENT NAME">"SET DB_INSTRUMENT NAME"</xref></t>
7210                        <t><xref target="SET DB_INSTRUMENT DESCRIPTION">"SET DB_INSTRUMENT DESCRIPTION"</xref></t>
7211                        <t><xref target="FIND DB_INSTRUMENTS">"FIND DB_INSTRUMENTS"</xref></t>
7212                    </list>
7213                    Please note that these lists are manually maintained. If you
7214                    find a command that also supports escape sequences we forgot to
7215                    mention here, please report it!
7216                    </t>
7217              </section>              </section>
7218          </section>          </section>
7219    
# Line 6752  Schoenebeck'> Line 7318  Schoenebeck'>
7318                  of sampler channels.</t>                  of sampler channels.</t>
7319              </section>              </section>
7320    
7321                <section title="MIDI data on a sampler channel arrived" anchor="SUBSCRIBE CHANNEL_MIDI">
7322                    <t>Client may want to be notified when MIDI data arrive on sampler channels on
7323                    back-end side, by issuing the following command:</t>
7324                    <t>
7325                        <list>
7326                            <t>SUBSCRIBE CHANNEL_MIDI</t>
7327                        </list>
7328                    </t>
7329                    <t>Server will start sending one of the the following notification messages:</t>
7330                    <t>
7331                        <list>
7332                            <t>"NOTIFY:CHANNEL_MIDI:&lt;channel-id&gt; NOTE_ON  &lt;note&gt; &lt;velocity&gt;"</t>
7333                            <t>"NOTIFY:CHANNEL_MIDI:&lt;channel-id&gt; NOTE_OFF &lt;note&gt; &lt;velocity&gt;"</t>
7334                        </list>
7335                    </t>
7336                    <t>where &lt;channel-id&gt; will be replaced by the ID of the sampler channel where the MIDI
7337                    data arrived. &lt;note&gt; and &lt;velocity&gt; are integer values in the range between
7338                    0 .. 127, reflecting the analog meaning of the MIDI specification.
7339                    </t>
7340                    <t>CAUTION: no guarantee whatsoever will be made that MIDI events are actually all
7341                    delivered by this mechanism! With other words: events could be lost at any time!
7342                    This restriction was made to keep the RT-safeness of the backend's MIDI and audio
7343                    thread unaffected by this feature.</t>
7344                </section>
7345    
7346                <section title="MIDI data on a MIDI input device arrived" anchor="SUBSCRIBE DEVICE_MIDI">
7347                        <t>Client may want to be notified when MIDI data arrive on MIDI input devices by issuing the following command:</t>
7348                        <t>
7349                                <list>
7350                                        <t>SUBSCRIBE DEVICE_MIDI</t>
7351                                </list>
7352                        </t>
7353                        <t>Server will start sending one of the the following notification messages:</t>
7354                        <t>
7355                                <list>
7356                                        <t>"NOTIFY:DEVICE_MIDI:&lt;device-id&gt; &lt;port-id&gt; NOTE_ON &lt;note&gt; &lt;velocity&gt;"</t>
7357                                        <t>"NOTIFY:DEVICE_MIDI:&lt;device-id&gt; &lt;port-id&gt; NOTE_OFF &lt;note&gt; &lt;velocity&gt;"</t>
7358                                </list>
7359                        </t>
7360                        <t>where &lt;device-id&gt; &lt;port-id&gt; will be replaced
7361                           by the IDs of the respective MIDI input device and the device's MIDI port where the MIDI
7362                           data arrived. &lt;note&gt; and &lt;velocity&gt; are integer values in the range between
7363                           0 .. 127, reflecting the analog meaning of the MIDI specification.
7364                        </t>
7365                        <t>CAUTION: no guarantee whatsoever will be made that MIDI events are actually all
7366                           delivered by this mechanism! With other words: events could be lost at any time!
7367                           This restriction was made to keep the RT-safeness of the backend's MIDI and audio
7368                           thread unaffected by this feature.</t>
7369                </section>
7370    
7371              <section title="Number of active voices changed" anchor="SUBSCRIBE VOICE_COUNT">              <section title="Number of active voices changed" anchor="SUBSCRIBE VOICE_COUNT">
7372                  <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
7373                  back-end changes by issuing the following command:</t>                  back-end changes by issuing the following command:</t>
# Line 6889  Schoenebeck'> Line 7505  Schoenebeck'>
7505                  all currently active voices.</t>                  all currently active voices.</t>
7506              </section>              </section>
7507    
7508                <section title="Total number of active disk streams changed" anchor="SUBSCRIBE TOTAL_STREAM_COUNT">
7509                    <t>Client may want to be notified when the total number of disk streams on the
7510                    back-end changes by issuing the following command:</t>
7511                    <t>
7512                        <list>
7513                            <t>SUBSCRIBE TOTAL_STREAM_COUNT</t>
7514                        </list>
7515                    </t>
7516                    <t>Server will start sending the following notification messages:</t>
7517                    <t>
7518                        <list>
7519                            <t>"NOTIFY:TOTAL_STREAM_COUNT:&lt;streams&gt;"</t>
7520                        </list>
7521                    </t>
7522                    <t>where &lt;streams&gt; will be replaced by the new number of
7523                    all currently active disk streams.</t>
7524                </section>
7525    
7526              <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">
7527                  <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
7528                  back-end changes by issuing the following command:</t>                  back-end changes by issuing the following command:</t>
Legend:
Removed from v.1250  
changed lines
  Added in v.1727
  ViewVC Help
Powered by ViewVC