/[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 1200 by iliev, Thu May 24 14:04:18 2007 UTC revision 1389 by schoenebeck, Sun Oct 7 14:05:04 2007 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.2">  <rfc category="std" ipr="full3978" docName="LSCP 1.2cvs">
20      <front>      <front>
21          <title>LinuxSampler Control Protocol</title>          <title>LinuxSampler Control Protocol (draft)</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="May" year="2007"/>          <date month="October" year="2007"/>
38          <workgroup>LinuxSampler Developers</workgroup>          <workgroup>LinuxSampler Developers</workgroup>
39          <keyword>LSCP</keyword>          <keyword>LSCP</keyword>
40          <abstract>          <abstract>
# Line 61  Schoenebeck'> Line 61  Schoenebeck'>
61              (front-end) and server (LinuxSampler) respectively. Lines in              (front-end) and server (LinuxSampler) respectively. Lines in
62              examples must be interpreted as every line being CRLF              examples must be interpreted as every line being CRLF
63              terminated (carriage return character followed by line feed              terminated (carriage return character followed by line feed
64              character as defined in the ASCII standard), thus the following              character as defined in the ASCII standard <xref target="RFC20"/>),
65              example:</t>              thus the following example:</t>
66    
67              <t>              <t>
68                  <list>                  <list>
# 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 2113  Schoenebeck'> Line 2121  Schoenebeck'>
2121                      number of the sampler channel the instrument should be assigned to.                      number of the sampler channel the instrument should be assigned to.
2122                      Each sampler channel can only have one instrument.</t>                      Each sampler channel can only have one instrument.</t>
2123    
2124                        <t>Notice: since LSCP 1.2 the &lt;filename&gt; argument supports
2125                        escape characters for special characters (see chapter
2126                        "<xref target="character_set">Character Set and Escape Sequences</xref>"
2127                        for details) and accordingly backslash characters in the filename
2128                        MUST now be escaped as well!</t>
2129    
2130                      <t>The difference between regular and NON_MODAL versions of the command                      <t>The difference between regular and NON_MODAL versions of the command
2131                      is that the regular command returns OK only after the instrument has been                      is that the regular command returns OK only after the instrument has been
2132                      fully loaded and the channel is ready to be used while NON_MODAL version                      fully loaded and the channel is ready to be used while NON_MODAL version
# Line 3241  Schoenebeck'> Line 3255  Schoenebeck'>
3255                      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;
3256                      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
3257                      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
3258                      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
3259                        encapsulated into apostrophes and supports escape sequences as described in chapter
3260                        "<xref target="character_set">Character Set and Escape Sequences</xref>".</t>
3261    
3262                      <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
3263                      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 3494  Schoenebeck'> Line 3510  Schoenebeck'>
3510                      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>
3511                      or <xref target="LIST FX_SENDS">"LIST FX_SENDS"</xref> command and                      or <xref target="LIST FX_SENDS">"LIST FX_SENDS"</xref> command and
3512                      &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
3513                      does not have to be unique.</t>                      does not have to be unique (name MUST be encapsulated into apostrophes
3514                        and supports escape sequences as described in chapter
3515                        "<xref target="character_set">Character Set and Escape Sequences</xref>").
3516                        </t>
3517    
3518                      <t>Possible Answers:</t>                      <t>Possible Answers:</t>
3519                      <t>                      <t>
# Line 3945  Schoenebeck'> Line 3964  Schoenebeck'>
3964                                  <list>                                  <list>
3965                                      <t>DESCRIPTION -                                      <t>DESCRIPTION -
3966                                          <list>                                          <list>
3967                                              <t>arbitrary textual description about the sampler</t>                                              <t>arbitrary textual description about the sampler
3968                                                (note that the character string may contain
3969                                                <xref target="character_set">escape sequences</xref>)</t>
3970                                          </list>                                          </list>
3971                                      </t>                                      </t>
3972                                      <t>VERSION -                                      <t>VERSION -
# Line 4061  Schoenebeck'> Line 4082  Schoenebeck'>
4082                  cause the sampler to switch to the respective instrument as                  cause the sampler to switch to the respective instrument as
4083                  reflected by the current MIDI instrument map.</t>                  reflected by the current MIDI instrument map.</t>
4084    
4085                  <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">
4086                      <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
4087                      the following command:</t>                      the following command:</t>
4088                      <t>                      <t>
# Line 4071  Schoenebeck'> Line 4092  Schoenebeck'>
4092                      </t>                      </t>
4093                      <t>Where &lt;name&gt; is an optional argument allowing to                      <t>Where &lt;name&gt; is an optional argument allowing to
4094                      assign a custom name to the new map. MIDI instrument Map                      assign a custom name to the new map. MIDI instrument Map
4095                      names do not have to be unique.</t>                      names do not have to be unique, but MUST be encapsulated
4096                        into apostrophes and support escape sequences as described
4097                        in chapter "<xref target="character_set">Character Set and Escape Sequences</xref>".
4098                        </t>
4099    
4100                      <t>Possible Answers:</t>                      <t>Possible Answers:</t>
4101                      <t>                      <t>
# Line 4278  Schoenebeck'> Line 4302  Schoenebeck'>
4302                      </t>                      </t>
4303                      <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
4304                      &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
4305                      have to be unique.</t>                      have to be unique (name MUST be encapsulated into apostrophes
4306                        and supports escape sequences as described in chapter
4307                        "<xref target="character_set">Character Set and Escape Sequences</xref>").
4308                        </t>
4309    
4310                      <t>Possible Answers:</t>                      <t>Possible Answers:</t>
4311                      <t>                      <t>
# Line 4325  Schoenebeck'> Line 4352  Schoenebeck'>
4352                      index, &lt;engine_name&gt; a sampler engine name as returned by                      index, &lt;engine_name&gt; a sampler engine name as returned by
4353                      the <xref target="LIST AVAILABLE_ENGINES">"LIST AVAILABLE_ENGINES"</xref>                      the <xref target="LIST AVAILABLE_ENGINES">"LIST AVAILABLE_ENGINES"</xref>
4354                      command (not encapsulated into apostrophes), &lt;filename&gt; the name                      command (not encapsulated into apostrophes), &lt;filename&gt; the name
4355                      of the instrument's file to be deployed (encapsulated into apostrophes),                      of the instrument's file to be deployed (encapsulated into apostrophes,
4356                        supporting escape sequences as described in chapter
4357                        "<xref target="character_set">Character Set and Escape Sequences</xref>"),
4358                      &lt;instrument_index&gt; the index (integer value) of the instrument                      &lt;instrument_index&gt; the index (integer value) of the instrument
4359                      within the given file, &lt;volume_value&gt; reflects the master                      within the given file, &lt;volume_value&gt; reflects the master
4360                      volume of the instrument as optionally dotted number (where a                      volume of the instrument as optionally dotted number (where a
# Line 4407  Schoenebeck'> Line 4436  Schoenebeck'>
4436                      load modes of entries, the frontend should retrieve the actual                      load modes of entries, the frontend should retrieve the actual
4437                      mode by i.e. sending                      mode by i.e. sending
4438                      <xref target="GET MIDI_INSTRUMENT INFO">"GET MIDI_INSTRUMENT INFO"</xref>                      <xref target="GET MIDI_INSTRUMENT INFO">"GET MIDI_INSTRUMENT INFO"</xref>
4439                      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
4440                      set a custom name (encapsulated into apostrophes) for the mapping                      (encapsulated into apostrophes, supporting escape sequences as described in chapter
4441                      entry, useful for frontends for displaying an appropriate name for                      "<xref target="character_set">Character Set and Escape Sequences</xref>") for the
4442                        mapping entry, useful for frontends for displaying an appropriate name for
4443                      mapped instruments (using                      mapped instruments (using
4444                      <xref target="GET MIDI_INSTRUMENT INFO">"GET MIDI_INSTRUMENT INFO"</xref>).                      <xref target="GET MIDI_INSTRUMENT INFO">"GET MIDI_INSTRUMENT INFO"</xref>).
4445                      </t>                      </t>
# Line 4744  Schoenebeck'> Line 4774  Schoenebeck'>
4774              <section title="Managing Instruments Database" anchor="Managing Instruments Database">              <section title="Managing Instruments Database" anchor="Managing Instruments Database">
4775                  <t>The following commands describe how to use and manage                  <t>The following commands describe how to use and manage
4776                  the instruments database.</t>                  the instruments database.</t>
4777                    <t>Notice:</t>
4778                        <t>
4779                            <list>
4780                                <t>All command arguments representing a path or
4781                                instrument/directory name support escape sequences as described in chapter
4782                                "<xref target="character_set">Character Set and Escape Sequences</xref>".
4783                                </t>
4784                                <t>All occurrences of a forward slash in instrument and directory
4785                                   names are escaped with its hex (\x2f) or octal (\057) escape sequence.
4786                                </t>
4787                            </list>
4788                        </t>
4789    
4790                  <section title="Creating a new instrument directory" anchor="ADD DB_INSTRUMENT_DIRECTORY">                  <section title="Creating a new instrument directory" anchor="ADD DB_INSTRUMENT_DIRECTORY">
4791                      <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 4921  Schoenebeck'> Line 4963  Schoenebeck'>
4963                                  <list>                                  <list>
4964                                      <t>DESCRIPTION -                                      <t>DESCRIPTION -
4965                                          <list>                                          <list>
4966                                              <t>A brief description of the directory content</t>                                              <t>A brief description of the directory content.
4967                                                Note that the character string may contain
4968                                                <xref target="character_set">escape sequences</xref>.</t>
4969                                          </list>                                          </list>
4970                                      </t>                                      </t>
4971                                      <t>CREATED -                                      <t>CREATED -
# Line 5085  Schoenebeck'> Line 5129  Schoenebeck'>
5129                          </list>                          </list>
5130                      </t>                      </t>
5131                      <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
5132                      &lt;desc&gt; is the new description for the directory.</t>                      &lt;desc&gt; is the new description for the directory
5133                        (encapsulated into apostrophes, supporting escape sequences as described in chapter
5134                        "<xref target="character_set">Character Set and Escape Sequences</xref>").</t>
5135    
5136                      <t>Possible Answers:</t>                      <t>Possible Answers:</t>
5137                      <t>                      <t>
# Line 5130  Schoenebeck'> Line 5176  Schoenebeck'>
5176                        <t>NAME='&lt;search-string&gt;'                        <t>NAME='&lt;search-string&gt;'
5177                            <list>                            <list>
5178                                <t>Restricts the search to directories, which names                                <t>Restricts the search to directories, which names
5179                                satisfy the supplied search string.</t>                                satisfy the supplied search string (encapsulated into apostrophes,
5180                                  supporting escape sequences as described in chapter
5181                                  "<xref target="character_set">Character Set and Escape Sequences</xref>").</t>
5182                            </list>                            </list>
5183                        </t>                        </t>
5184    
# Line 5161  Schoenebeck'> Line 5209  Schoenebeck'>
5209                        <t>DESCRIPTION='&lt;search-string&gt;'                        <t>DESCRIPTION='&lt;search-string&gt;'
5210                            <list>                            <list>
5211                                <t>Restricts the search to directories with description                                <t>Restricts the search to directories with description
5212                                that satisfies the supplied search string.</t>                                that satisfies the supplied search string
5213                                  (encapsulated into apostrophes, supporting escape
5214                                  sequences as described in chapter
5215                                  "<xref target="character_set">Character Set and Escape Sequences</xref>").</t>
5216                            </list>                            </list>
5217                        </t>                        </t>
5218                      </t>                      </t>
# Line 5422  Schoenebeck'> Line 5473  Schoenebeck'>
5473                                  <list>                                  <list>
5474                                      <t>INSTRUMENT_FILE -                                      <t>INSTRUMENT_FILE -
5475                                          <list>                                          <list>
5476                                              <t>File name of the instrument.</t>                                              <t>File name of the instrument.
5477                                                Note that the character string may contain
5478                                                <xref target="character_set">escape sequences</xref>.</t>
5479                                          </list>                                          </list>
5480                                      </t>                                      </t>
5481                                      <t>INSTRUMENT_NR -                                      <t>INSTRUMENT_NR -
# Line 5461  Schoenebeck'> Line 5514  Schoenebeck'>
5514                                      </t>                                      </t>
5515                                      <t>DESCRIPTION -                                      <t>DESCRIPTION -
5516                                          <list>                                          <list>
5517                                              <t>A brief description of the instrument</t>                                              <t>A brief description of the instrument.
5518                                                Note that the character string may contain
5519                                                <xref target="character_set">escape sequences</xref>.</t>
5520                                          </list>                                          </list>
5521                                      </t>                                      </t>
5522                                      <t>IS_DRUM -                                      <t>IS_DRUM -
# Line 5472  Schoenebeck'> Line 5527  Schoenebeck'>
5527                                      </t>                                      </t>
5528                                      <t>PRODUCT -                                      <t>PRODUCT -
5529                                          <list>                                          <list>
5530                                              <t>The product title of the instrument</t>                                              <t>The product title of the instrument.
5531                                                Note that the character string may contain
5532                                                <xref target="character_set">escape sequences</xref>.</t>
5533                                          </list>                                          </list>
5534                                      </t>                                      </t>
5535                                      <t>ARTISTS -                                      <t>ARTISTS -
5536                                          <list>                                          <list>
5537                                              <t>Lists the artist names</t>                                              <t>Lists the artist names.
5538                                                Note that the character string may contain
5539                                                <xref target="character_set">escape sequences</xref>.</t>
5540                                          </list>                                          </list>
5541                                      </t>                                      </t>
5542                                      <t>KEYWORDS -                                      <t>KEYWORDS -
5543                                          <list>                                          <list>
5544                                              <t>Provides a list of keywords that refer to the instrument.                                              <t>Provides a list of keywords that refer to the instrument.
5545                                              Keywords are separated with semicolon and blank.</t>                                              Keywords are separated with semicolon and blank.
5546                                                Note that the character string may contain
5547                                                <xref target="character_set">escape sequences</xref>.</t>
5548                                          </list>                                          </list>
5549                                      </t>                                      </t>
5550                                  </list>                                  </list>
# Line 5640  Schoenebeck'> Line 5701  Schoenebeck'>
5701                          </list>                          </list>
5702                      </t>                      </t>
5703                      <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
5704                      &lt;desc&gt; is the new description for the instrument.</t>                      &lt;desc&gt; is the new description for the instrument
5705                        (encapsulated into apostrophes, supporting escape sequences as described in chapter
5706                        "<xref target="character_set">Character Set and Escape Sequences</xref>").</t>
5707    
5708                      <t>Possible Answers:</t>                      <t>Possible Answers:</t>
5709                      <t>                      <t>
# Line 5685  Schoenebeck'> Line 5748  Schoenebeck'>
5748                        <t>NAME='&lt;search-string&gt;'                        <t>NAME='&lt;search-string&gt;'
5749                            <list>                            <list>
5750                                <t>Restricts the search to instruments, which names                                <t>Restricts the search to instruments, which names
5751                                satisfy the supplied search string.</t>                                satisfy the supplied search string (encapsulated into apostrophes,
5752                                  supporting escape sequences as described in chapter
5753                                  "<xref target="character_set">Character Set and Escape Sequences</xref>").</t>
5754                            </list>                            </list>
5755                        </t>                        </t>
5756    
5757                        <t>SIZE=[&lt;min&gt;]..[&lt;max&gt;]                        <t>SIZE=[&lt;min&gt;]..[&lt;max&gt;]
5758                            <list>                            <list>
5759                                <t>Restricts the search to instruments, which                                <t>Restricts the search to instruments, which
5760                                size is in the specified range. If &lt;min&gt; is omitted,                                size is in the specified range. If &lt;min&gt; is omitted,
5761                                the search results are restricted to instruments with size less then                                the search results are restricted to instruments with size less then
5762                                or equal to &lt;max&gt;. If &lt;max&gt; is omitted, the                                or equal to &lt;max&gt;. If &lt;max&gt; is omitted, the
# Line 5727  Schoenebeck'> Line 5792  Schoenebeck'>
5792                        <t>DESCRIPTION='&lt;search-string&gt;'                        <t>DESCRIPTION='&lt;search-string&gt;'
5793                            <list>                            <list>
5794                                <t>Restricts the search to instruments with description                                <t>Restricts the search to instruments with description
5795                                that satisfies the supplied search string.</t>                                that satisfies the supplied search string (encapsulated into apostrophes,
5796                                  supporting escape sequences as described in chapter
5797                                  "<xref target="character_set">Character Set and Escape Sequences</xref>").</t>
5798                            </list>                            </list>
5799                        </t>                        </t>
5800    
5801                        <t>PRODUCT='&lt;search-string&gt;'                        <t>PRODUCT='&lt;search-string&gt;'
5802                            <list>                            <list>
5803                                <t>Restricts the search to instruments with product info                                <t>Restricts the search to instruments with product info
5804                                that satisfies the supplied search string.</t>                                that satisfies the supplied search string (encapsulated into apostrophes,
5805                                  supporting escape sequences as described in chapter
5806                                  "<xref target="character_set">Character Set and Escape Sequences</xref>").</t>
5807                            </list>                            </list>
5808                        </t>                        </t>
5809    
5810                        <t>ARTISTS='&lt;search-string&gt;'                        <t>ARTISTS='&lt;search-string&gt;'
5811                            <list>                            <list>
5812                                <t>Restricts the search to instruments with artists info                                <t>Restricts the search to instruments with artists info
5813                                that satisfies the supplied search string.</t>                                that satisfies the supplied search string (encapsulated into apostrophes,
5814                                  supporting escape sequences as described in chapter
5815                                  "<xref target="character_set">Character Set and Escape Sequences</xref>").</t>
5816                            </list>                            </list>
5817                        </t>                        </t>
5818    
5819                        <t>KEYWORDS='&lt;search-string&gt;'                        <t>KEYWORDS='&lt;search-string&gt;'
5820                            <list>                            <list>
5821                                <t>Restricts the search to instruments with keyword list                                <t>Restricts the search to instruments with keyword list
5822                                that satisfies the supplied search string.</t>                                that satisfies the supplied search string (encapsulated into apostrophes,
5823                                  supporting escape sequences as described in chapter
5824                                  "<xref target="character_set">Character Set and Escape Sequences</xref>").</t>
5825                            </list>                            </list>
5826                        </t>                        </t>
5827    
5828                        <t>IS_DRUM=true | false                        <t>IS_DRUM=true | false
5829                            <list>                            <list>
5830                                <t>Either true or false. Restricts the search to                                <t>Either true or false. Restricts the search to
5831                                drum kits or chromatic instruments.</t>                                drum kits or chromatic instruments.</t>
5832                            </list>                            </list>
5833                        </t>                        </t>
# Line 5862  Schoenebeck'> Line 5935  Schoenebeck'>
5935                      </t>                      </t>
5936                  </section>                  </section>
5937    
5938                    <section title="Formatting the instruments database" anchor="FORMAT INSTRUMENTS_DB">
5939                        <t>The front-end can remove all instruments and directories and re-create
5940                        the instruments database structure (e.g., in case of a database corruption)
5941                        by sending the following command:</t>
5942                        <t>
5943                            <list>
5944                                <t>FORMAT INSTRUMENTS_DB</t>
5945                            </list>
5946                        </t>
5947                        
5948                        <t>Possible Answers:</t>
5949                        <t>
5950                            <list>
5951                                <t>"OK" -
5952                                    <list>
5953                                        <t>on success</t>
5954                                    </list>
5955                                </t>
5956                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
5957                                    <list>
5958                                        <t>If the formatting of the instruments database
5959                                        failed.</t>
5960                                    </list>
5961                                </t>
5962                            </list>
5963                        </t>
5964                    </section>
5965    
5966              </section>              </section>
5967    
5968    
5969    
5970                <section title="Editing Instruments" anchor="editing_instruments">
5971                    <t>The sampler allows to edit instruments while playing with the
5972                    sampler by spawning an external (3rd party) instrument editor
5973                    application for a given instrument. The 3rd party instrument
5974                    editor applications have to place a respective plugin DLL file
5975                    into the sampler's plugins directory. The sampler will
5976                    automatically try to load all plugin DLLs in that directory on
5977                    startup and only on startup!</t>
5978                    <t>At the moment there is only one command for this feature set,
5979                    but this will most probably change in future.</t>
5980    
5981                    <section title="Opening an appropriate instrument editor application" anchor="EDIT INSTRUMENT">
5982                        <t>The front-end can request to open an appropriate instrument
5983                        editor application by sending the following command:</t>
5984                        <t>
5985                            <list>
5986                                <t>EDIT INSTRUMENT &lt;sampler-channel&gt;</t>
5987                            </list>
5988                        </t>
5989                        <t>Where &lt;sampler-channel&gt; should be replaced by the
5990                        number of the sampler channel as given by the
5991                        <xref target="ADD CHANNEL">"ADD CHANNEL"</xref>
5992                        or <xref target="LIST CHANNELS">"LIST CHANNELS"</xref>
5993                        command.</t>
5994    
5995                        <t>The sampler will try to ask all registered instrument
5996                        editors (or to be more specific: their sampler plugins)
5997                        whether they are capable to handle the instrument on the
5998                        given sampler channel. The sampler will simply use the first
5999                        instrument editor application which replied with a positive
6000                        answer and spawn that instrument editor application within
6001                        the sampler's process and provide that application access
6002                        to the instrument's data structures, so both applications
6003                        can share and access the same instruments data at the same
6004                        time, thus allowing to immediately hear changes with the
6005                        sampler made by the instrument editor.</t>
6006    
6007                        <t>Note: consequently instrument editors are always spawned
6008                        locally on the same machine where the sampler is running
6009                        on!</t>
6010    
6011                        <t>Possible Answers:</t>
6012                        <t>
6013                            <list>
6014                                <t>"OK" -
6015                                    <list>
6016                                        <t>when an appropriate instrument editor was
6017                                        launched</t>
6018                                    </list>
6019                                </t>
6020                                <t>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
6021                                    <list>
6022                                        <t>when an appropriate instrument editor was
6023                                        launched, but there are noteworthy issues</t>
6024                                    </list>
6025                                </t>
6026                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
6027                                    <list>
6028                                        <t>when an appropriate instrument editor
6029                                        could not be launched</t>
6030                                    </list>
6031                                </t>
6032                            </list>
6033                        </t>
6034    
6035                        <t>Examples:</t>
6036                        <t>
6037                            <list>
6038                                <t>C: "EDIT INSTRUMENT 0"</t>
6039                                <t>S: "OK"</t>
6040                            </list>
6041                        </t>
6042                    </section>
6043                </section>
6044          </section>          </section>
6045    
6046    
# Line 5949  Schoenebeck'> Line 6126  Schoenebeck'>
6126                  </t>                  </t>
6127                  <t>/ COPY SP copy_instruction                  <t>/ COPY SP copy_instruction
6128                  </t>                  </t>
6129                    <t>/ EDIT SP edit_instruction
6130                    </t>
6131                    <t>/ FORMAT SP format_instruction
6132                    </t>
6133                  <t>/ RESET                  <t>/ RESET
6134                  </t>                  </t>
6135                  <t>/ QUIT                  <t>/ QUIT
# Line 5959  Schoenebeck'> Line 6140  Schoenebeck'>
6140          <list>          <list>
6141                  <t>CHANNEL                  <t>CHANNEL
6142                  </t>                  </t>
6143                  <t>/ DB_INSTRUMENT_DIRECTORY SP pathname                  <t>/ DB_INSTRUMENT_DIRECTORY SP db_path
6144                  </t>                  </t>
6145                  <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
6146                  </t>                  </t>
6147                  <t>/ DB_INSTRUMENTS SP scan_mode SP pathname SP pathname                  <t>/ DB_INSTRUMENTS SP scan_mode SP db_path SP filename
6148                  </t>                  </t>
6149                  <t>/ DB_INSTRUMENTS SP NON_MODAL SP pathname SP pathname                  <t>/ DB_INSTRUMENTS SP NON_MODAL SP db_path SP filename
6150                  </t>                  </t>
6151                  <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
6152                  </t>                  </t>
6153                  <t>/ DB_INSTRUMENTS SP pathname SP pathname                  <t>/ DB_INSTRUMENTS SP db_path SP filename
6154                  </t>                  </t>
6155                  <t>/ DB_INSTRUMENTS SP pathname SP pathname SP instrument_index                  <t>/ DB_INSTRUMENTS SP db_path SP filename SP instrument_index
6156                  </t>                  </t>
6157                  <t>/ MIDI_INSTRUMENT_MAP                  <t>/ MIDI_INSTRUMENT_MAP
6158                  </t>                  </t>
# Line 6105  Schoenebeck'> Line 6286  Schoenebeck'>
6286                  </t>                  </t>
6287                  <t>/ MIDI_INSTRUMENT_MAP SP ALL                  <t>/ MIDI_INSTRUMENT_MAP SP ALL
6288                  </t>                  </t>
6289                  <t>/ DB_INSTRUMENT_DIRECTORY SP FORCE SP pathname                  <t>/ DB_INSTRUMENT_DIRECTORY SP FORCE SP db_path
6290                  </t>                  </t>
6291                  <t>/ DB_INSTRUMENT_DIRECTORY SP pathname                  <t>/ DB_INSTRUMENT_DIRECTORY SP db_path
6292                  </t>                  </t>
6293                  <t>/ DB_INSTRUMENT SP pathname                  <t>/ DB_INSTRUMENT SP db_path
6294                  </t>                  </t>
6295          </list>          </list>
6296  </t>  </t>
# Line 6181  Schoenebeck'> Line 6362  Schoenebeck'>
6362                  </t>                  </t>
6363                  <t>/ FX_SEND SP INFO SP sampler_channel SP fx_send_id                  <t>/ FX_SEND SP INFO SP sampler_channel SP fx_send_id
6364                  </t>                  </t>
6365                  <t>/ DB_INSTRUMENT_DIRECTORIES SP RECURSIVE SP pathname                  <t>/ DB_INSTRUMENT_DIRECTORIES SP RECURSIVE SP db_path
6366                  </t>                  </t>
6367                  <t>/ DB_INSTRUMENT_DIRECTORIES SP pathname                  <t>/ DB_INSTRUMENT_DIRECTORIES SP db_path
6368                  </t>                  </t>
6369                  <t>/ DB_INSTRUMENT_DIRECTORY SP INFO SP pathname                  <t>/ DB_INSTRUMENT_DIRECTORY SP INFO SP db_path
6370                  </t>                  </t>
6371                  <t>/ DB_INSTRUMENTS SP RECURSIVE SP pathname                  <t>/ DB_INSTRUMENTS SP RECURSIVE SP db_path
6372                  </t>                  </t>
6373                  <t>/ DB_INSTRUMENTS SP pathname                  <t>/ DB_INSTRUMENTS SP db_path
6374                  </t>                  </t>
6375                  <t>/ DB_INSTRUMENT SP INFO SP pathname                  <t>/ DB_INSTRUMENT SP INFO SP db_path
6376                  </t>                  </t>
6377                  <t>/ DB_INSTRUMENTS_JOB SP INFO SP number                  <t>/ DB_INSTRUMENTS_JOB SP INFO SP number
6378                  </t>                  </t>
# Line 6207  Schoenebeck'> Line 6388  Schoenebeck'>
6388                  </t>                  </t>
6389                  <t>/ MIDI_INPUT_DEVICE_PARAMETER SP number SP string '=' param_val_list                  <t>/ MIDI_INPUT_DEVICE_PARAMETER SP number SP string '=' param_val_list
6390                  </t>                  </t>
6391                    <t>/ MIDI_INPUT_PORT_PARAMETER SP number SP number SP string '=' NONE
6392                    </t>
6393                  <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
6394                  </t>                  </t>
6395                  <t>/ CHANNEL SP set_chan_instruction                  <t>/ CHANNEL SP set_chan_instruction
# Line 6221  Schoenebeck'> Line 6404  Schoenebeck'>
6404                  </t>                  </t>
6405                  <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
6406                  </t>                  </t>
6407                  <t>/ DB_INSTRUMENT_DIRECTORY SP NAME SP pathname SP dirname                  <t>/ DB_INSTRUMENT_DIRECTORY SP NAME SP db_path SP stringval_escaped
6408                  </t>                  </t>
6409                  <t>/ DB_INSTRUMENT_DIRECTORY SP DESCRIPTION SP pathname SP stringval                  <t>/ DB_INSTRUMENT_DIRECTORY SP DESCRIPTION SP db_path SP stringval_escaped
6410                  </t>                  </t>
6411                  <t>/ DB_INSTRUMENT SP NAME SP pathname SP dirname                  <t>/ DB_INSTRUMENT SP NAME SP db_path SP stringval_escaped
6412                  </t>                  </t>
6413                  <t>/ DB_INSTRUMENT SP DESCRIPTION SP pathname SP stringval                  <t>/ DB_INSTRUMENT SP DESCRIPTION SP db_path SP stringval_escaped
6414                  </t>                  </t>
6415                  <t>/ ECHO SP boolean                  <t>/ ECHO SP boolean
6416                  </t>                  </t>
# Line 6267  Schoenebeck'> Line 6450  Schoenebeck'>
6450  </t>  </t>
6451  <t>find_instruction =  <t>find_instruction =
6452          <list>          <list>
6453                  <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
6454                  </t>                  </t>
6455                  <t>/ DB_INSTRUMENTS SP pathname SP query_val_list                  <t>/ DB_INSTRUMENTS SP db_path SP query_val_list
6456                  </t>                  </t>
6457                  <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
6458                  </t>                  </t>
6459                  <t>/ DB_INSTRUMENT_DIRECTORIES SP pathname SP query_val_list                  <t>/ DB_INSTRUMENT_DIRECTORIES SP db_path SP query_val_list
6460                  </t>                  </t>
6461          </list>          </list>
6462  </t>  </t>
6463  <t>move_instruction =  <t>move_instruction =
6464          <list>          <list>
6465                  <t>DB_INSTRUMENT_DIRECTORY SP pathname SP pathname                  <t>DB_INSTRUMENT_DIRECTORY SP db_path SP db_path
6466                  </t>                  </t>
6467                  <t>/ DB_INSTRUMENT SP pathname SP pathname                  <t>/ DB_INSTRUMENT SP db_path SP db_path
6468                  </t>                  </t>
6469          </list>          </list>
6470  </t>  </t>
6471  <t>copy_instruction =  <t>copy_instruction =
6472          <list>          <list>
6473                  <t>DB_INSTRUMENT_DIRECTORY SP pathname SP pathname                  <t>DB_INSTRUMENT_DIRECTORY SP db_path SP db_path
6474                  </t>                  </t>
6475                  <t>/ DB_INSTRUMENT SP pathname SP pathname                  <t>/ DB_INSTRUMENT SP db_path SP db_path
6476                  </t>                  </t>
6477          </list>          </list>
6478  </t>  </t>
# Line 6343  Schoenebeck'> Line 6526  Schoenebeck'>
6526                  </t>                  </t>
6527          </list>          </list>
6528  </t>  </t>
6529    <t>edit_instruction =
6530            <list>
6531                    <t>INSTRUMENT SP sampler_channel
6532                    </t>
6533            </list>
6534    </t>
6535    <t>format_instruction =
6536            <list>
6537                    <t>INSTRUMENTS_DB
6538                    </t>
6539            </list>
6540    </t>
6541  <t>modal_arg =  <t>modal_arg =
6542          <list>          <list>
6543                  <t>/* epsilon (empty argument) */                  <t>/* epsilon (empty argument) */
# Line 6389  Schoenebeck'> Line 6584  Schoenebeck'>
6584                  </t>                  </t>
6585                  <t>/ FX_SENDS SP sampler_channel                  <t>/ FX_SENDS SP sampler_channel
6586                  </t>                  </t>
6587                  <t>/ DB_INSTRUMENT_DIRECTORIES SP RECURSIVE SP pathname                  <t>/ DB_INSTRUMENT_DIRECTORIES SP RECURSIVE SP db_path
6588                  </t>                  </t>
6589                  <t>/ DB_INSTRUMENT_DIRECTORIES SP pathname                  <t>/ DB_INSTRUMENT_DIRECTORIES SP db_path
6590                  </t>                  </t>
6591                  <t>/ DB_INSTRUMENTS SP RECURSIVE SP pathname                  <t>/ DB_INSTRUMENTS SP RECURSIVE SP db_path
6592                  </t>                  </t>
6593                  <t>/ DB_INSTRUMENTS SP pathname                  <t>/ DB_INSTRUMENTS SP db_path
6594                  </t>                  </t>
6595          </list>          </list>
6596  </t>  </t>
# Line 6517  Schoenebeck'> Line 6712  Schoenebeck'>
6712                  </t>                  </t>
6713          </list>          </list>
6714  </t>  </t>
6715  <t>pathname =  <t>filename =
         <list>  
                 <t>stringval  
                 </t>  
         </list>  
 </t>  
 <t>dirname =  
6716          <list>          <list>
6717                  <t>stringval                  <t>path
6718                  </t>                  </t>
6719          </list>          </list>
6720  </t>  </t>
6721  <t>filename =  <t>db_path =
6722          <list>          <list>
6723                  <t>stringval                  <t>path
6724                  </t>                  </t>
6725          </list>          </list>
6726  </t>  </t>
6727  <t>map_name =  <t>map_name =
6728          <list>          <list>
6729                  <t>stringval                  <t>stringval_escaped
6730                  </t>                  </t>
6731          </list>          </list>
6732  </t>  </t>
6733  <t>entry_name =  <t>entry_name =
6734          <list>          <list>
6735                  <t>stringval                  <t>stringval_escaped
6736                  </t>                  </t>
6737          </list>          </list>
6738  </t>  </t>
6739  <t>fx_send_name =  <t>fx_send_name =
6740          <list>          <list>
6741                  <t>stringval                  <t>stringval_escaped
6742                  </t>                  </t>
6743          </list>          </list>
6744  </t>  </t>
# Line 6561  Schoenebeck'> Line 6750  Schoenebeck'>
6750                  </t>                  </t>
6751          </list>          </list>
6752  </t>  </t>
6753    
6754  <t>param_val =  <t>param_val =
6755          <list>          <list>
6756                  <t>string                  <t>string
# Line 6583  Schoenebeck'> Line 6773  Schoenebeck'>
6773  </t>  </t>
6774  <t>query_val =  <t>query_val =
6775          <list>          <list>
6776                  <t>string                  <t>text_escaped
6777                  </t>                  </t>
6778                  <t>/ stringval                  <t>/ stringval_escaped
6779                  </t>                  </t>
6780          </list>          </list>
6781  </t>  </t>
# Line 6601  Schoenebeck'> Line 6791  Schoenebeck'>
6791  </t>  </t>
6792    
6793              <!-- GRAMMAR_BNF_END - do NOT delete or modify this line !!! -->              <!-- GRAMMAR_BNF_END - do NOT delete or modify this line !!! -->
6794    
6795                <section title="Character Set and Escape Sequences" anchor="character_set">
6796                    <t>Older versions of this protocol up to and including v1.1 only
6797                    supported the standard ASCII character set (ASCII code 0 - 127)
6798                    <xref target="RFC20"/>, all younger versions of this protocol
6799                    however support the Extended ASCII character set (ASCII code
6800                    0 - 255). The same group of younger protocols also support
6801                    escape sequences, but only for certain, explicitly declared
6802                    parts of the protocol. The supported escape sequences are
6803                    defined as follows:</t>
6804                    <texttable>
6805                        <ttcol>ASCII Character Sequence</ttcol>
6806                        <ttcol>Translated into (Name)</ttcol>
6807                        <c>\n</c> <c>new line</c>
6808                        <c>\r</c> <c>carriage return</c>
6809                        <c>\f</c> <c>form feed</c>
6810                        <c>\t</c> <c>horizontal tab</c>
6811                        <c>\v</c> <c>vertical tab</c>
6812                        <c>\'</c> <c>apostrophe</c>
6813                        <c>\"</c> <c>quotation mark</c>
6814                        <c>\\</c> <c>backslash</c>
6815                        <c>\OOO</c> <c>three digit octal ASCII code of the character</c>
6816                        <c>\xHH</c> <c>two digit hex ASCII code of the character</c>
6817                    </texttable>
6818                    <t>Notice: due to the transition of certain parts of the
6819                    protocol which now support escape sequences, a slight backward
6820                    incompatibility to protocols version v1.1 and younger has been
6821                    introduced. The only difference is that in parts of the protocol
6822                    where escape characters are now supported, a backslash characters
6823                    MUST be escaped as well (that is as double backslash), whereas
6824                    in the old versions a single backslash was sufficient.</t>
6825    
6826                    <t>The following LSCP commands support escape sequences as part
6827                    of their filename / path based arguments:
6828                    <list>
6829                        <t><xref target="LOAD INSTRUMENT">"LOAD INSTRUMENT"</xref></t>
6830                        <t><xref target="MAP MIDI_INSTRUMENT">"MAP MIDI_INSTRUMENT"</xref></t>
6831                        <t><xref target="ADD DB_INSTRUMENT_DIRECTORY">"ADD DB_INSTRUMENT_DIRECTORY"</xref></t>
6832                        <t><xref target="ADD DB_INSTRUMENTS">"ADD DB_INSTRUMENTS"</xref></t>
6833                        <t><xref target="REMOVE DB_INSTRUMENT_DIRECTORY">"REMOVE DB_INSTRUMENT_DIRECTORY"</xref></t>
6834                        <t><xref target="REMOVE DB_INSTRUMENT">"REMOVE DB_INSTRUMENT"</xref></t>
6835                        <t><xref target="GET DB_INSTRUMENT_DIRECTORIES">"GET DB_INSTRUMENT_DIRECTORIES"</xref></t>
6836                        <t><xref target="LIST DB_INSTRUMENT_DIRECTORIES">"LIST DB_INSTRUMENT_DIRECTORIES"</xref></t>
6837                        <t><xref target="GET DB_INSTRUMENT_DIRECTORY INFO">"GET DB_INSTRUMENT_DIRECTORY INFO"</xref></t>
6838                        <t><xref target="GET DB_INSTRUMENTS">"GET DB_INSTRUMENTS"</xref></t>
6839                        <t><xref target="LIST DB_INSTRUMENTS">"LIST DB_INSTRUMENTS"</xref></t>
6840                        <t><xref target="GET DB_INSTRUMENT INFO">"GET DB_INSTRUMENT INFO"</xref></t>
6841                        <t><xref target="SET DB_INSTRUMENT_DIRECTORY NAME">"SET DB_INSTRUMENT_DIRECTORY NAME"</xref></t>
6842                        <t><xref target="SET DB_INSTRUMENT_DIRECTORY DESCRIPTION">"SET DB_INSTRUMENT_DIRECTORY DESCRIPTION"</xref></t>
6843                        <t><xref target="SET DB_INSTRUMENT NAME">"SET DB_INSTRUMENT NAME"</xref></t>
6844                        <t><xref target="SET DB_INSTRUMENT DESCRIPTION">"SET DB_INSTRUMENT DESCRIPTION"</xref></t>
6845                        <t><xref target="FIND DB_INSTRUMENTS">"FIND DB_INSTRUMENTS"</xref></t>
6846                        <t><xref target="FIND DB_INSTRUMENT_DIRECTORIES">"FIND DB_INSTRUMENT_DIRECTORIES"</xref></t>
6847                        <t><xref target="MOVE DB_INSTRUMENT">"MOVE DB_INSTRUMENT"</xref></t>
6848                        <t><xref target="MOVE DB_INSTRUMENT_DIRECTORY">"MOVE DB_INSTRUMENT_DIRECTORY"</xref></t>
6849                        <t><xref target="COPY DB_INSTRUMENT">"COPY DB_INSTRUMENT"</xref></t>
6850                        <t><xref target="COPY DB_INSTRUMENT_DIRECTORY">"COPY DB_INSTRUMENT_DIRECTORY"</xref></t>
6851                    </list>
6852                    Note that the forward slash character ('/') has a special meaning in
6853                    filename / path based arguments: it acts as separator of the nodes in
6854                    the path, thus if a directory- or filename includes a forward slash
6855                    (not intended as path node separator), you MUST escape that slash
6856                    either with the respective hex escape sequence ("\x2f") or with the
6857                    respective octal escape sequence ("\057").
6858                    </t>
6859    
6860                    <t>
6861                    The following LSCP commands even support escape sequences as
6862                    part of at least one of their text-based arguments (i.e. entity name,
6863                    description):
6864                    <list>
6865                        <t><xref target="ADD MIDI_INSTRUMENT_MAP">"ADD MIDI_INSTRUMENT_MAP"</xref></t>
6866                        <t><xref target="MAP MIDI_INSTRUMENT">"MAP MIDI_INSTRUMENT"</xref></t>
6867                        <t><xref target="SET MIDI_INSTRUMENT_MAP NAME">"SET MIDI_INSTRUMENT_MAP NAME"</xref></t>
6868                        <t><xref target="SET DB_INSTRUMENT_DIRECTORY NAME">"SET DB_INSTRUMENT_DIRECTORY NAME"</xref></t>
6869                        <t><xref target="SET DB_INSTRUMENT_DIRECTORY DESCRIPTION">"SET DB_INSTRUMENT_DIRECTORY DESCRIPTION"</xref></t>
6870                        <t><xref target="SET DB_INSTRUMENT NAME">"SET DB_INSTRUMENT NAME"</xref></t>
6871                        <t><xref target="SET DB_INSTRUMENT DESCRIPTION">"SET DB_INSTRUMENT DESCRIPTION"</xref></t>
6872                        <t><xref target="FIND DB_INSTRUMENT_DIRECTORIES">"FIND DB_INSTRUMENT_DIRECTORIES"</xref></t>
6873                    </list>
6874                    Please note that these lists are manually maintained. If you
6875                    find a command that also supports escape sequences we forgot to
6876                    mention here, please report it!
6877                    </t>
6878                </section>
6879          </section>          </section>
6880    
6881          <section title="Events" anchor="events">          <section title="Events" anchor="events">
# Line 6786  Schoenebeck'> Line 7061  Schoenebeck'>
7061              </section>              </section>
7062    
7063              <section title="Number of effect sends changed" anchor="SUBSCRIBE FX_SEND_COUNT">              <section title="Number of effect sends changed" anchor="SUBSCRIBE FX_SEND_COUNT">
7064                  <t>Client may want to be notified when the number of effect sends on                  <t>Client may want to be notified when the number of effect sends on
7065                  a particular sampler channel is changed by issuing the following command:</t>                  a particular sampler channel is changed by issuing the following command:</t>
7066                  <t>                  <t>
7067                      <list>                      <list>
# Line 7146  Schoenebeck'> Line 7421  Schoenebeck'>
7421                  </front>                  </front>
7422                  <seriesInfo name="RFC" value="2234" />                  <seriesInfo name="RFC" value="2234" />
7423              </reference>              </reference>
7424                <reference anchor="RFC20">
7425                    <front>
7426                        <title>ASCII format for Network Interchange</title>
7427                        <author>
7428                            <organization>UCLA</organization>
7429                        </author>
7430                        <date year="1969"></date>
7431                    </front>
7432                    <seriesInfo name="RFC" value="20" />
7433                </reference>
7434           </references>           </references>
7435      </back>      </back>
7436    
Legend:
Removed from v.1200  
changed lines
  Added in v.1389
  ViewVC Help
Powered by ViewVC