/[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 981 by iliev, Sun Dec 17 22:35:01 2006 UTC revision 3502 by schoenebeck, Mon Mar 11 15:42:54 2019 UTC
# Line 1  Line 1 
1  <?xml version="1.0" encoding="UTF-8"?>  <?xml version="1.0" encoding="UTF-8"?>
2    
3    <!-- NOTE: Use xml2rfc -n switch to avoid irrelevant DTD errors for now. -->
4    
5  <!DOCTYPE rfc SYSTEM "rfc2629.dtd" [  <!DOCTYPE rfc SYSTEM "rfc2629.dtd" [
6      <!ENTITY rfc2119 PUBLIC ''      <!ENTITY rfc2119 PUBLIC ''
7        'http://xml.resource.org/public/rfc/bibxml/reference.RFC.2119.xml'>        'http://xml.resource.org/public/rfc/bibxml/reference.RFC.2119.xml'>
# Line 16  Line 18 
18       to an annoying "missing Normative/Informative References" error message -->       to an annoying "missing Normative/Informative References" error message -->
19  <?rfc strict="no" ?>  <?rfc strict="no" ?>
20    
21  <rfc category="std" ipr="full3978" docName="LSCP 1.2">  <rfc category="info" ipr="noDerivativesTrust200902" docName="LSCP 1.7">
22      <front>      <front>
23          <title>LinuxSampler Control Protocol</title>          <title>LinuxSampler Control Protocol</title>
24          <author initials='C.S.' surname="Schoenebeck" fullname='C.          <author initials='C.S.' surname="Schoenebeck" fullname='C.
25  Schoenebeck'>  Schoenebeck' role="editor">
26              <organization>              <organization>
27                  Interessengemeinschaft Software Engineering e. V.                  LinuxSampler.org
28              </organization>              </organization>
29              <address>              <address>
30                  <postal>                  <postal>
31                      <street>Max-Planck-Str. 39</street>                      <street>Crudebyte Engineering</street>
32                        <street>Hofgartenstr. 3</street>
33  <!--                    <code>74081</code> -->  <!--                    <code>74081</code> -->
34                      <city>74081 Heilbronn</city>                      <city>74189 Weinsberg</city>
35                      <country>Germany</country>                      <country>Germany</country>
36                  </postal>                  </postal>
37                  <email>schoenebeck at software minus engineering dot org</email>                  <phone>+49 7134 911614</phone>
38                    <email>cuse@users.sf.net</email>
39              </address>              </address>
40          </author>          </author>
41          <date month="December" year="2006"/>          <date month="March" year="2019"/>
42          <workgroup>LinuxSampler Developers</workgroup>          <workgroup>LinuxSampler Developers</workgroup>
43          <keyword>LSCP</keyword>          <keyword>LSCP</keyword>
44          <abstract>          <abstract>
# Line 61  Schoenebeck'> Line 65  Schoenebeck'>
65              (front-end) and server (LinuxSampler) respectively. Lines in              (front-end) and server (LinuxSampler) respectively. Lines in
66              examples must be interpreted as every line being CRLF              examples must be interpreted as every line being CRLF
67              terminated (carriage return character followed by line feed              terminated (carriage return character followed by line feed
68              character as defined in the ASCII standard), thus the following              character as defined in the ASCII standard <xref target="RFC20"/>),
69              example:</t>              thus the following example:</t>
70    
71              <t>              <t>
72                  <list>                  <list>
# Line 514  Schoenebeck'> Line 518  Schoenebeck'>
518                  what parameters drivers are offering, how to retrieve their                  what parameters drivers are offering, how to retrieve their
519                  possible values, etc.</t>                  possible values, etc.</t>
520    
521                  <section title="Getting amount of available audio output drivers" anchor="GET AVAILABLE_AUDIO_OUTPUT_DRIVERS">                  <section title="Getting amount of available audio output drivers" anchor="GET AVAILABLE_AUDIO_OUTPUT_DRIVERS" lscp_cmd="true">
522                      <t>Use the following command to get the number of                      <t>Use the following command to get the number of
523                      audio output drivers currently available for the                      audio output drivers currently available for the
524                      LinuxSampler instance:</t>                      LinuxSampler instance:</t>
# Line 539  Schoenebeck'> Line 543  Schoenebeck'>
543                      </t>                      </t>
544                  </section>                  </section>
545    
546                  <section title="Getting all available audio output drivers" anchor="LIST AVAILABLE_AUDIO_OUTPUT_DRIVERS">                  <section title="Getting all available audio output drivers" anchor="LIST AVAILABLE_AUDIO_OUTPUT_DRIVERS" lscp_cmd="true">
547                      <t>Use the following command to list all audio output                      <t>Use the following command to list all audio output
548                      drivers currently available for the LinuxSampler                      drivers currently available for the LinuxSampler
549                      instance:</t>                      instance:</t>
# Line 566  Schoenebeck'> Line 570  Schoenebeck'>
570                  </section>                  </section>
571    
572                  <section title="Getting information about a specific audio                  <section title="Getting information about a specific audio
573                  output driver" anchor="GET AUDIO_OUTPUT_DRIVER INFO">                  output driver" anchor="GET AUDIO_OUTPUT_DRIVER INFO" lscp_cmd="true">
574                      <t>Use the following command to get detailed information                      <t>Use the following command to get detailed information
575                      about a specific audio output driver:</t>                      about a specific audio output driver:</t>
576                      <t>                      <t>
# Line 639  Schoenebeck'> Line 643  Schoenebeck'>
643                  </section>                  </section>
644    
645                  <section title="Getting information about specific audio                  <section title="Getting information about specific audio
646                  output driver parameter" anchor="GET AUDIO_OUTPUT_DRIVER_PARAMETER INFO">                  output driver parameter" anchor="GET AUDIO_OUTPUT_DRIVER_PARAMETER INFO" lscp_cmd="true">
647                      <t>Use the following command to get detailed information                      <t>Use the following command to get detailed information
648                      about a  specific audio output driver parameter:</t>                      about a  specific audio output driver parameter:</t>
649                      <t>                      <t>
# Line 827  Schoenebeck'> Line 831  Schoenebeck'>
831                      </t>                      </t>
832                  </section>                  </section>
833    
834                  <section title="Creating an audio output device" anchor="CREATE AUDIO_OUTPUT_DEVICE">                  <section title="Creating an audio output device" anchor="CREATE AUDIO_OUTPUT_DEVICE" lscp_cmd="true">
835                      <t>Use the following command to create a new audio output device for  the desired audio output system:</t>                      <t>Use the following command to create a new audio output device for  the desired audio output system:</t>
836    
837                      <t>                      <t>
# Line 887  Schoenebeck'> Line 891  Schoenebeck'>
891                      </t>                      </t>
892                  </section>                  </section>
893    
894                  <section title="Destroying an audio output device" anchor="DESTROY AUDIO_OUTPUT_DEVICE">                  <section title="Destroying an audio output device" anchor="DESTROY AUDIO_OUTPUT_DEVICE" lscp_cmd="true">
895                      <t>Use the following command to destroy a created output device:</t>                      <t>Use the following command to destroy a created output device:</t>
896                      <t>                      <t>
897                          <list>                          <list>
# Line 956  Schoenebeck'> Line 960  Schoenebeck'>
960                      </t>                      </t>
961                  </section>                  </section>
962    
963                  <section title="Getting all created audio output device list" anchor="LIST AUDIO_OUTPUT_DEVICES">                  <section title="Getting all created audio output device list" anchor="LIST AUDIO_OUTPUT_DEVICES" lscp_cmd="true">
964                      <t>Use the following command to list all created audio output devices:</t>                      <t>Use the following command to list all created audio output devices:</t>
965                      <t>                      <t>
966                          <list>                          <list>
# Line 979  Schoenebeck'> Line 983  Schoenebeck'>
983                      </t>                      </t>
984                  </section>                  </section>
985    
986                  <section title="Getting current settings of an audio output device" anchor="GET AUDIO_OUTPUT_DEVICE INFO">                  <section title="Getting current settings of an audio output device" anchor="GET AUDIO_OUTPUT_DEVICE INFO" lscp_cmd="true">
987                      <t>Use the following command to get current settings of a specific, created audio output device:</t>                      <t>Use the following command to get current settings of a specific, created audio output device:</t>
988                      <t>                      <t>
989                          <list>                          <list>
# Line 1052  Schoenebeck'> Line 1056  Schoenebeck'>
1056                  </section>                  </section>
1057    
1058    
1059                  <section title="Changing settings of audio output devices" anchor="SET AUDIO_OUTPUT_DEVICE_PARAMETER">                  <section title="Changing settings of audio output devices" anchor="SET AUDIO_OUTPUT_DEVICE_PARAMETER" lscp_cmd="true">
1060                      <t>Use the following command to alter a specific setting of a created audio output device:</t>                      <t>Use the following command to alter a specific setting of a created audio output device:</t>
1061                      <t>                      <t>
1062                          <list>                          <list>
# Line 1097  Schoenebeck'> Line 1101  Schoenebeck'>
1101                      </t>                      </t>
1102                  </section>                  </section>
1103    
1104                  <section title="Getting information about an audio channel" anchor="GET AUDIO_OUTPUT_CHANNEL INFO">                  <section title="Getting information about an audio channel" anchor="GET AUDIO_OUTPUT_CHANNEL INFO" lscp_cmd="true">
1105                      <t>Use the following command to get information about an audio channel:</t>                      <t>Use the following command to get information about an audio channel:</t>
1106                      <t>                      <t>
1107                          <list>                          <list>
# Line 1197  Schoenebeck'> Line 1201  Schoenebeck'>
1201                      </t>                      </t>
1202                  </section>                  </section>
1203    
1204                  <section title="Getting information about specific audio channel parameter" anchor="GET AUDIO_OUTPUT_CHANNEL_PARAMETER INFO">                  <section title="Getting information about specific audio channel parameter" anchor="GET AUDIO_OUTPUT_CHANNEL_PARAMETER INFO" lscp_cmd="true">
1205                      <t>Use the following command to get detailed information about specific audio channel parameter:</t>                      <t>Use the following command to get detailed information about specific audio channel parameter:</t>
1206    
1207                      <t>                      <t>
# Line 1303  Schoenebeck'> Line 1307  Schoenebeck'>
1307                      </t>                      </t>
1308                  </section>                  </section>
1309    
1310                  <section title="Changing settings of audio output channels" anchor="SET AUDIO_OUTPUT_CHANNEL_PARAMETER">                  <section title="Changing settings of audio output channels" anchor="SET AUDIO_OUTPUT_CHANNEL_PARAMETER" lscp_cmd="true">
1311                      <t>Use the following command to alter a specific setting of an audio output channel:</t>                      <t>Use the following command to alter a specific setting of an audio output channel:</t>
1312                      <t>                      <t>
1313                          <list>                          <list>
# Line 1381  Schoenebeck'> Line 1385  Schoenebeck'>
1385                  showing how to retrieve what parameters drivers are offering, how to retrieve their                  showing how to retrieve what parameters drivers are offering, how to retrieve their
1386                  possible values, etc.</t>                  possible values, etc.</t>
1387    
1388                  <section title="Getting amount of available MIDI input drivers" anchor="GET AVAILABLE_MIDI_INPUT_DRIVERS">                  <section title="Getting amount of available MIDI input drivers" anchor="GET AVAILABLE_MIDI_INPUT_DRIVERS" lscp_cmd="true">
1389                      <t>Use the following command to get the number of                      <t>Use the following command to get the number of
1390                      MIDI input drivers currently available for the                      MIDI input drivers currently available for the
1391                      LinuxSampler instance:</t>                      LinuxSampler instance:</t>
# Line 1406  Schoenebeck'> Line 1410  Schoenebeck'>
1410                      </t>                      </t>
1411                  </section>                  </section>
1412    
1413                  <section title="Getting all available MIDI input drivers" anchor="LIST AVAILABLE_MIDI_INPUT_DRIVERS">                  <section title="Getting all available MIDI input drivers" anchor="LIST AVAILABLE_MIDI_INPUT_DRIVERS" lscp_cmd="true">
1414                      <t>Use the following command to list all MIDI input drivers currently available                      <t>Use the following command to list all MIDI input drivers currently available
1415                      for the LinuxSampler instance:</t>                      for the LinuxSampler instance:</t>
1416                      <t>                      <t>
# Line 1430  Schoenebeck'> Line 1434  Schoenebeck'>
1434                      </t>                      </t>
1435                  </section>                  </section>
1436    
1437                  <section title="Getting information about a specific MIDI input driver" anchor="GET MIDI_INPUT_DRIVER INFO">                  <section title="Getting information about a specific MIDI input driver" anchor="GET MIDI_INPUT_DRIVER INFO" lscp_cmd="true">
1438                      <t>Use the following command to get detailed information about a specific MIDI input driver:</t>                      <t>Use the following command to get detailed information about a specific MIDI input driver:</t>
1439                      <t>                      <t>
1440                          <list>                          <list>
# Line 1486  Schoenebeck'> Line 1490  Schoenebeck'>
1490                      </t>                      </t>
1491                  </section>                  </section>
1492    
1493                  <section title="Getting information about specific MIDI input driver parameter" anchor="GET MIDI_INPUT_DRIVER_PARAMETER INFO">                  <section title="Getting information about specific MIDI input driver parameter" anchor="GET MIDI_INPUT_DRIVER_PARAMETER INFO" lscp_cmd="true">
1494                      <t>Use the following command to get detailed information about a specific parameter of a specific MIDI input driver:</t>                      <t>Use the following command to get detailed information about a specific parameter of a specific MIDI input driver:</t>
1495                      <t>                      <t>
1496                          <list>                          <list>
# Line 1641  Schoenebeck'> Line 1645  Schoenebeck'>
1645                      </t>                      </t>
1646                  </section>                  </section>
1647    
1648                  <section title="Creating a MIDI input device" anchor="CREATE MIDI_INPUT_DEVICE">                  <section title="Creating a MIDI input device" anchor="CREATE MIDI_INPUT_DEVICE" lscp_cmd="true">
1649                      <t>Use the following command to create a new MIDI input device for  the desired MIDI input system:</t>                      <t>Use the following command to create a new MIDI input device for  the desired MIDI input system:</t>
1650                      <t>                      <t>
1651                          <list>                          <list>
# Line 1691  Schoenebeck'> Line 1695  Schoenebeck'>
1695                      </t>                      </t>
1696                  </section>                  </section>
1697    
1698                  <section title="Destroying a MIDI input device" anchor="DESTROY MIDI_INPUT_DEVICE">                  <section title="Destroying a MIDI input device" anchor="DESTROY MIDI_INPUT_DEVICE" lscp_cmd="true">
1699                      <t>Use the following command to destroy a created MIDI input device:</t>                      <t>Use the following command to destroy a created MIDI input device:</t>
1700                      <t>                      <t>
1701                          <list>                          <list>
# Line 1733  Schoenebeck'> Line 1737  Schoenebeck'>
1737                      </t>                      </t>
1738                  </section>                  </section>
1739    
1740                  <section title="Getting all created MIDI input device count" anchor="GET MIDI_INPUT_DEVICES">                  <section title="Getting all created MIDI input device count" anchor="GET MIDI_INPUT_DEVICES" lscp_cmd="true">
1741                      <t>Use the following command to count all created MIDI input devices:</t>                      <t>Use the following command to count all created MIDI input devices:</t>
1742                      <t>                      <t>
1743                          <list>                          <list>
# Line 1757  Schoenebeck'> Line 1761  Schoenebeck'>
1761                  </section>                  </section>
1762    
1763    
1764                  <section title="Getting all created MIDI input device list" anchor="LIST MIDI_INPUT_DEVICES">                  <section title="Getting all created MIDI input device list" anchor="LIST MIDI_INPUT_DEVICES" lscp_cmd="true">
1765                      <t>Use the following command to list all created MIDI input devices:</t>                      <t>Use the following command to list all created MIDI input devices:</t>
1766                      <t>                      <t>
1767                          <list>                          <list>
# Line 1786  Schoenebeck'> Line 1790  Schoenebeck'>
1790                      </t>                      </t>
1791                  </section>                  </section>
1792    
1793                  <section title="Getting current settings of a MIDI input device" anchor="GET MIDI_INPUT_DEVICE INFO">                  <section title="Getting current settings of a MIDI input device" anchor="GET MIDI_INPUT_DEVICE INFO" lscp_cmd="true">
1794                      <t>Use the following command to get current settings of a specific, created MIDI input device:</t>                      <t>Use the following command to get current settings of a specific, created MIDI input device:</t>
1795                      <t>                      <t>
1796                          <list>                          <list>
# Line 1852  Schoenebeck'> Line 1856  Schoenebeck'>
1856                      </t>                      </t>
1857                  </section>                  </section>
1858    
1859                  <section title="Changing settings of MIDI input devices" anchor="SET MIDI_INPUT_DEVICE_PARAMETER">                  <section title="Changing settings of MIDI input devices" anchor="SET MIDI_INPUT_DEVICE_PARAMETER" lscp_cmd="true">
1860                      <t>Use the following command to alter a specific setting of a created MIDI input device:</t>                      <t>Use the following command to alter a specific setting of a created MIDI input device:</t>
1861                      <t>                      <t>
1862                          <list>                          <list>
# Line 1898  Schoenebeck'> Line 1902  Schoenebeck'>
1902                      </t>                      </t>
1903                  </section>                  </section>
1904    
1905                  <section title="Getting information about a MIDI port" anchor="GET MIDI_INPUT_PORT INFO">                  <section title="Getting information about a MIDI port" anchor="GET MIDI_INPUT_PORT INFO" lscp_cmd="true">
1906                      <t>Use the following command to get information about a MIDI port:</t>                      <t>Use the following command to get information about a MIDI port:</t>
1907                      <t>                      <t>
1908                          <list>                          <list>
# Line 1942  Schoenebeck'> Line 1946  Schoenebeck'>
1946                      </t>                      </t>
1947                  </section>                  </section>
1948    
1949                  <section title="Getting information about specific MIDI port parameter" anchor="GET MIDI_INPUT_PORT_PARAMETER INFO">                  <section title="Getting information about specific MIDI port parameter" anchor="GET MIDI_INPUT_PORT_PARAMETER INFO" lscp_cmd="true">
1950                      <t>Use the following command to get detailed information about specific MIDI port parameter:</t>                      <t>Use the following command to get detailed information about specific MIDI port parameter:</t>
1951                      <t>                      <t>
1952                          <list>                          <list>
# Line 2047  Schoenebeck'> Line 2051  Schoenebeck'>
2051                      </t>                      </t>
2052                  </section>                  </section>
2053    
2054                  <section title="Changing settings of MIDI input ports" anchor="SET MIDI_INPUT_PORT_PARAMETER">                  <section title="Changing settings of MIDI input ports" anchor="SET MIDI_INPUT_PORT_PARAMETER" lscp_cmd="true">
2055                      <t>Use the following command to alter a specific setting of a MIDI input port:</t>                      <t>Use the following command to alter a specific setting of a MIDI input port:</t>
2056                      <t>                      <t>
2057                          <list>                          <list>
# Line 2061  Schoenebeck'> Line 2065  Schoenebeck'>
2065                      or <xref target="LIST MIDI_INPUT_DEVICES">"LIST MIDI_INPUT_DEVICES"</xref>                      or <xref target="LIST MIDI_INPUT_DEVICES">"LIST MIDI_INPUT_DEVICES"</xref>
2066                      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
2067                      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
2068                      parameter.</t>                      parameter (encapsulated into apostrophes) or NONE (not encapsulated into apostrophes)
2069                        for specifying no value for parameters allowing a list of values.</t>
2070    
2071                      <t>Possible Answers:</t>                      <t>Possible Answers:</t>
2072                      <t>                      <t>
# Line 2088  Schoenebeck'> Line 2093  Schoenebeck'>
2093                      <t>Example:</t>                      <t>Example:</t>
2094                      <t>                      <t>
2095                          <list>                          <list>
2096                              <t></t>                              <t>C: "SET MIDI_INPUT_PORT_PARAMETER 0 0 ALSA_SEQ_BINDINGS='20:0'"</t>
2097                                <t>S: "OK"</t>
2098                            </list>
2099                        </t>
2100                        <t>
2101                            <list>
2102                                <t>C: "SET MIDI_INPUT_PORT_PARAMETER 0 0 ALSA_SEQ_BINDINGS=NONE"</t>
2103                                <t>S: "OK"</t>
2104                          </list>                          </list>
2105                      </t>                      </t>
2106                  </section>                  </section>
# Line 2099  Schoenebeck'> Line 2111  Schoenebeck'>
2111                  sampler channel with a sampler engine, load instruments and connect sampler channels to                  sampler channel with a sampler engine, load instruments and connect sampler channels to
2112                  MIDI and audio devices.</t>                  MIDI and audio devices.</t>
2113    
2114                  <section title="Loading an instrument" anchor="LOAD INSTRUMENT">                  <section title="Loading an instrument" anchor="LOAD INSTRUMENT" lscp_cmd="true">
2115                      <t>An instrument file can be loaded and assigned to a sampler channel by one of the following commands:</t>                      <t>An instrument file can be loaded and assigned to a sampler channel by one of the following commands:</t>
2116                      <t>                      <t>
2117                          <list>                          <list>
# Line 2113  Schoenebeck'> Line 2125  Schoenebeck'>
2125                      number of the sampler channel the instrument should be assigned to.                      number of the sampler channel the instrument should be assigned to.
2126                      Each sampler channel can only have one instrument.</t>                      Each sampler channel can only have one instrument.</t>
2127    
2128                        <t>Notice: since LSCP 1.2 the &lt;filename&gt; argument supports
2129                        escape characters for special characters (see chapter
2130                        "<xref target="character_set">Character Set and Escape Sequences</xref>"
2131                        for details) and accordingly backslash characters in the filename
2132                        MUST now be escaped as well!</t>
2133    
2134                      <t>The difference between regular and NON_MODAL versions of the command                      <t>The difference between regular and NON_MODAL versions of the command
2135                      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
2136                      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 2148  Schoenebeck'> Line 2166  Schoenebeck'>
2166                              </t>                              </t>
2167                          </list>                          </list>
2168                      </t>                      </t>
2169                      <t>Example:</t>                      <t>Example (Unix):</t>
2170                      <t>                      <t>
2171                          <list>                          <list>
2172                              <t></t>                              <t>C: LOAD INSTRUMENT '/home/joe/gigs/cello.gig' 0 0</t>
2173                                <t>S: OK</t>
2174                            </list>
2175                        </t>
2176                        <t>Example (Windows):</t>
2177                        <t>
2178                            <list>
2179                                <t>C: LOAD INSTRUMENT 'D:/MySounds/cello.gig' 0 0</t>
2180                                <t>S: OK</t>
2181                          </list>                          </list>
2182                      </t>                      </t>
2183                  </section>                  </section>
# Line 2211  Schoenebeck'> Line 2237  Schoenebeck'>
2237                      </t>                      </t>
2238                  </section>                  </section>
2239    
2240                  <section title="Getting all created sampler channel count" anchor="GET CHANNELS">                  <section title="Getting all created sampler channel count" anchor="GET CHANNELS" lscp_cmd="true">
2241                      <t>The number of sampler channels can change on runtime. To get the                      <t>The number of sampler channels can change on runtime. To get the
2242                      current amount of sampler channels, the front-end can send the                      current amount of sampler channels, the front-end can send the
2243                      following command:</t>                      following command:</t>
# Line 2235  Schoenebeck'> Line 2261  Schoenebeck'>
2261                      </t>                      </t>
2262                  </section>                  </section>
2263    
2264                  <section title="Getting all created sampler channel list" anchor="LIST CHANNELS">                  <section title="Getting all created sampler channel list" anchor="LIST CHANNELS" lscp_cmd="true">
2265                      <t>The number of sampler channels can change on runtime. To get the                      <t>The number of sampler channels can change on runtime. To get the
2266                      current list of sampler channels, the front-end can send the                      current list of sampler channels, the front-end can send the
2267                      following command:</t>                      following command:</t>
# Line 2260  Schoenebeck'> Line 2286  Schoenebeck'>
2286                      </t>                      </t>
2287                  </section>                  </section>
2288    
2289                  <section title="Adding a new sampler channel" anchor="ADD CHANNEL">                  <section title="Adding a new sampler channel" anchor="ADD CHANNEL" lscp_cmd="true">
2290                      <t>A new sampler channel can be added to the end of the sampler                      <t>A new sampler channel can be added to the end of the sampler
2291                      channel list by sending the following command:</t>                      channel list by sending the following command:</t>
2292                      <t>                      <t>
# Line 2312  Schoenebeck'> Line 2338  Schoenebeck'>
2338                      </t>                      </t>
2339                  </section>                  </section>
2340    
2341                  <section title="Removing a sampler channel" anchor="REMOVE CHANNEL">                  <section title="Removing a sampler channel" anchor="REMOVE CHANNEL" lscp_cmd="true">
2342                      <t>A sampler channel can be removed by sending the following command:</t>                      <t>A sampler channel can be removed by sending the following command:</t>
2343                      <t>                      <t>
2344                          <list>                          <list>
# Line 2358  Schoenebeck'> Line 2384  Schoenebeck'>
2384                      </t>                      </t>
2385                  </section>                  </section>
2386    
2387                  <section title="Getting amount of available engines" anchor="GET AVAILABLE_ENGINES">                  <section title="Getting amount of available engines" anchor="GET AVAILABLE_ENGINES" lscp_cmd="true">
2388                      <t>The front-end can ask for the number of available engines by sending the following command:</t>                      <t>The front-end can ask for the number of available engines by sending the following command:</t>
2389                      <t>                      <t>
2390                          <list>                          <list>
# Line 2380  Schoenebeck'> Line 2406  Schoenebeck'>
2406                      </t>                      </t>
2407                  </section>                  </section>
2408    
2409                  <section title="Getting all available engines" anchor="LIST AVAILABLE_ENGINES">                  <section title="Getting all available engines" anchor="LIST AVAILABLE_ENGINES" lscp_cmd="true">
2410                      <t>The front-end can ask for a list of all available engines by sending the following command:</t>                      <t>The front-end can ask for a list of all available engines by sending the following command:</t>
2411                      <t>                      <t>
2412                          <list>                          <list>
# Line 2400  Schoenebeck'> Line 2426  Schoenebeck'>
2426                      <t>                      <t>
2427                          <list>                          <list>
2428                              <t>C: "LIST AVAILABLE_ENGINES"</t>                              <t>C: "LIST AVAILABLE_ENGINES"</t>
2429                              <t>S: "'GigEngine','AkaiEngine','DLSEngine','JoesCustomEngine'"</t>                              <t>S: "'gig','sfz','sf2'"</t>
2430                          </list>                          </list>
2431                      </t>                      </t>
2432                  </section>                  </section>
2433    
2434                  <section title="Getting information about an engine" anchor="GET ENGINE INFO">                  <section title="Getting information about an engine" anchor="GET ENGINE INFO" lscp_cmd="true">
2435                      <t>The front-end can ask for information about a specific engine by                      <t>The front-end can ask for information about a specific engine by
2436                      sending the following command:</t>                      sending the following command:</t>
2437                      <t>                      <t>
# Line 2429  Schoenebeck'> Line 2455  Schoenebeck'>
2455                                  <list>                                  <list>
2456                                      <t>DESCRIPTION -                                      <t>DESCRIPTION -
2457                                          <list>                                          <list>
2458                                              <t>arbitrary description text about the engine</t>                                              <t>arbitrary description text about the engine
2459                                                (note that the character string may contain
2460                                                <xref target="character_set">escape sequences</xref>)</t>
2461                                          </list>                                          </list>
2462                                      </t>                                      </t>
2463                                       <t>VERSION -                                       <t>VERSION -
# Line 2444  Schoenebeck'> Line 2472  Schoenebeck'>
2472    
2473                      <t>The mentioned fields above don't have to be in particular order.</t>                      <t>The mentioned fields above don't have to be in particular order.</t>
2474    
2475                      <t>Example:</t>                      <t>Examples:</t>
2476                      <t>                      <t>
2477                          <list>                          <list>
2478                              <t>C: "GET ENGINE INFO JoesCustomEngine"</t>                              <t>C: "GET ENGINE INFO gig"</t>
2479                              <t>S: "DESCRIPTION: this is Joe's custom sampler engine"</t>                              <t>S: "DESCRIPTION: GigaSampler Format Engine"</t>
2480                              <t>&nbsp;&nbsp;&nbsp;"VERSION: testing-1.0"</t>                              <t>&nbsp;&nbsp;&nbsp;"VERSION: 1.110"</t>
2481                                <t>&nbsp;&nbsp;&nbsp;"."</t>
2482                                <t>C: "GET ENGINE INFO sf2"</t>
2483                                <t>S: "DESCRIPTION: SoundFont Format Engine"</t>
2484                                <t>&nbsp;&nbsp;&nbsp;"VERSION: 1.4"</t>
2485                                <t>&nbsp;&nbsp;&nbsp;"."</t>
2486                                <t>C: "GET ENGINE INFO sfz"</t>
2487                                <t>S: "DESCRIPTION: SFZ Format Engine"</t>
2488                                <t>&nbsp;&nbsp;&nbsp;"VERSION: 1.11"</t>
2489                              <t>&nbsp;&nbsp;&nbsp;"."</t>                              <t>&nbsp;&nbsp;&nbsp;"."</t>
2490                          </list>                          </list>
2491                      </t>                      </t>
2492                  </section>                  </section>
2493    
2494                  <section title="Getting sampler channel information" anchor="GET CHANNEL INFO">                  <section title="Getting sampler channel information" anchor="GET CHANNEL INFO" lscp_cmd="true">
2495                      <t>The front-end can ask for the current settings of a sampler channel                      <t>The front-end can ask for the current settings of a sampler channel
2496                      by sending the following command:</t>                      by sending the following command:</t>
2497                      <t>                      <t>
# Line 2488  Schoenebeck'> Line 2524  Schoenebeck'>
2524                                          <list>                                          <list>
2525                                              <t>numerical ID of the audio output device which is                                              <t>numerical ID of the audio output device which is
2526                                              currently connected to this sampler channel to output                                              currently connected to this sampler channel to output
2527                                              the audio signal, "NONE" if there's no device                                              the audio signal, "-1" if there's no device
2528                                              connected to this sampler channel</t>                                              connected to this sampler channel</t>
2529                                          </list>                                          </list>
2530                                      </t>                                      </t>
# Line 2513  Schoenebeck'> Line 2549  Schoenebeck'>
2549                                          <list>                                          <list>
2550                                              <t>the file name of the loaded instrument, "NONE" if                                              <t>the file name of the loaded instrument, "NONE" if
2551                                              there's no instrument yet loaded for this sampler                                              there's no instrument yet loaded for this sampler
2552                                              channel</t>                                              channel (note: since LSCP 1.2 this path may contain
2553                                                <xref target="character_set">escape sequences</xref>)</t>
2554                                          </list>                                          </list>
2555                                      </t>                                      </t>
2556                                      <t>INSTRUMENT_NR -                                      <t>INSTRUMENT_NR -
2557                                          <list>                                          <list>
2558                                              <t>the instrument index number of the loaded instrument</t>                                              <t>the instrument index number of the loaded instrument,
2559                                                "-1" if there's no instrument loaded for this sampler
2560                                                channel</t>
2561                                          </list>                                          </list>
2562                                      </t>                                      </t>
2563                                      <t>INSTRUMENT_NAME -                                      <t>INSTRUMENT_NAME -
2564                                          <list>                                          <list>
2565                                              <t>the instrument name of the loaded instrument</t>                                              <t>the instrument name of the loaded instrument
2566                                                (note: since LSCP 1.2 this character string may contain
2567                                                <xref target="character_set">escape sequences</xref>)</t>
2568                                          </list>                                          </list>
2569                                      </t>                                      </t>
2570                                      <t>INSTRUMENT_STATUS -                                      <t>INSTRUMENT_STATUS -
2571                                          <list>                                          <list>
2572                                              <t>integer values 0 to 100 indicating loading progress percentage for the instrument. Negative                                              <t>Integer values 0 to 100 indicating loading progress
2573                                              value indicates a loading exception. Value of 100 indicates that the instrument is fully                                              percentage for the instrument. Negative
2574                                                value indicates a loading exception (also returns "-1" in case no
2575                                                instrument was yet to be loaded on the sampler channel).
2576                                                Value of 100 indicates that the instrument is fully
2577                                              loaded.</t>                                              loaded.</t>
2578                                          </list>                                          </list>
2579                                      </t>                                      </t>
2580                                      <t>MIDI_INPUT_DEVICE -                                      <t>MIDI_INPUT_DEVICE -
2581                                          <list>                                          <list>
2582                                                <t>DEPRECATED: THIS FIELD WILL DISAPPEAR!</t>
2583                                              <t>numerical ID of the MIDI input device which is                                              <t>numerical ID of the MIDI input device which is
2584                                              currently connected to this sampler channel to deliver                                              currently connected to this sampler channel to deliver
2585                                              MIDI input commands, "NONE" if there's no device                                              MIDI input commands, "-1" if there's no device
2586                                              connected to this sampler channel</t>                                              connected to this sampler channel</t>
2587                                                <t>Should not be used anymore as of LSCP v1.6 and younger.
2588                                                This field is currently only preserved for backward compatibility.
2589                                                </t>
2590                                                <t>This field a relict from times where only one MIDI input per
2591                                                sampler channel was allowed. Use <xref target="LIST CHANNEL MIDI_INPUTS">"GET CHANNEL MIDI_INPUTS"</xref>
2592                                                instead.</t>
2593                                          </list>                                          </list>
2594                                      </t>                                      </t>
2595                                      <t>MIDI_INPUT_PORT -                                      <t>MIDI_INPUT_PORT -
2596                                          <list>                                          <list>
2597                                              <t>port number of the MIDI input device</t>                                              <t>DEPRECATED: THIS FIELD WILL DISAPPEAR!</t>
2598                                                <t>port number of the MIDI input device (in case a
2599                                                MIDI device was already assigned to the sampler
2600                                                channel)</t>
2601                                                <t>Should not be used anymore as of LSCP v1.6 and younger.
2602                                                This field is currently only preserved for backward compatibility.
2603                                                </t>
2604                                                <t>This field a relict from times where only one MIDI input per
2605                                                sampler channel was allowed. Use <xref target="LIST CHANNEL MIDI_INPUTS">"GET CHANNEL MIDI_INPUTS"</xref>
2606                                                instead.</t>
2607                                          </list>                                          </list>
2608                                      </t>                                      </t>
2609                                      <t>MIDI_INPUT_CHANNEL -                                      <t>MIDI_INPUT_CHANNEL -
# Line 2555  Schoenebeck'> Line 2615  Schoenebeck'>
2615                                      <t>VOLUME -                                      <t>VOLUME -
2616                                          <list>                                          <list>
2617                                              <t>optionally dotted number for the channel volume factor                                              <t>optionally dotted number for the channel volume factor
2618                                              (where a value < 1.0 means attenuation and a value >                                              (where a value &lt; 1.0 means attenuation and a value >
2619                                              1.0 means amplification)</t>                                              1.0 means amplification)</t>
2620                                          </list>                                          </list>
2621                                      </t>                                      </t>
# Line 2592  Schoenebeck'> Line 2652  Schoenebeck'>
2652                      <t>                      <t>
2653                          <list>                          <list>
2654                              <t>C: "GET CHANNEL INFO 34"</t>                              <t>C: "GET CHANNEL INFO 34"</t>
2655                              <t>S: "ENGINE_NAME: GigEngine"</t>                              <t>S: "ENGINE_NAME: gig"</t>
2656                              <t>&nbsp;&nbsp;&nbsp;"VOLUME: 1.0"</t>                              <t>&nbsp;&nbsp;&nbsp;"VOLUME: 1.0"</t>
2657                              <t>&nbsp;&nbsp;&nbsp;"AUDIO_OUTPUT_DEVICE: 0"</t>                              <t>&nbsp;&nbsp;&nbsp;"AUDIO_OUTPUT_DEVICE: 0"</t>
2658                              <t>&nbsp;&nbsp;&nbsp;"AUDIO_OUTPUT_CHANNELS: 2"</t>                              <t>&nbsp;&nbsp;&nbsp;"AUDIO_OUTPUT_CHANNELS: 2"</t>
# Line 2613  Schoenebeck'> Line 2673  Schoenebeck'>
2673                      </t>                      </t>
2674                  </section>                  </section>
2675    
2676                  <section title="Current number of active voices" anchor="GET CHANNEL VOICE_COUNT">                  <section title="Current number of active voices" anchor="GET CHANNEL VOICE_COUNT" lscp_cmd="true">
2677                      <t>The front-end can ask for the current number of active voices on a                      <t>The front-end can ask for the current number of active voices on a
2678                      sampler channel by sending the following command:</t>                      sampler channel by sending the following command:</t>
2679                      <t>                      <t>
# Line 2640  Schoenebeck'> Line 2700  Schoenebeck'>
2700                      </t>                      </t>
2701                  </section>                  </section>
2702    
2703                  <section title="Current number of active disk streams" anchor="GET CHANNEL STREAM_COUNT">                  <section title="Current number of active disk streams" anchor="GET CHANNEL STREAM_COUNT" lscp_cmd="true">
2704                      <t>The front-end can ask for the current number of active disk streams                      <t>The front-end can ask for the current number of active disk streams
2705                      on a sampler channel by sending the following command:</t>                      on a sampler channel by sending the following command:</t>
2706                      <t>                      <t>
# Line 2669  Schoenebeck'> Line 2729  Schoenebeck'>
2729                      </t>                      </t>
2730                  </section>                  </section>
2731    
2732                  <section title="Current fill state of disk stream buffers" anchor="GET CHANNEL BUFFER_FILL">                  <section title="Current fill state of disk stream buffers" anchor="GET CHANNEL BUFFER_FILL" lscp_cmd="true">
2733                      <t>The front-end can ask for the current fill state of all disk streams                      <t>The front-end can ask for the current fill state of all disk streams
2734                      on a sampler channel by sending the following command:</t>                      on a sampler channel by sending the following command:</t>
2735                      <t>                      <t>
# Line 2722  Schoenebeck'> Line 2782  Schoenebeck'>
2782                      </t>                      </t>
2783                  </section>                  </section>
2784    
2785                  <section title="Setting audio output device" anchor="SET CHANNEL AUDIO_OUTPUT_DEVICE">                  <section title="Setting audio output device" anchor="SET CHANNEL AUDIO_OUTPUT_DEVICE" lscp_cmd="true">
2786                      <t>The front-end can set the audio output device on a specific sampler                      <t>The front-end can set the audio output device on a specific sampler
2787                      channel by sending the following command:</t>                      channel by sending the following command:</t>
2788                      <t>                      <t>
# Line 2768  Schoenebeck'> Line 2828  Schoenebeck'>
2828                      </t>                      </t>
2829                  </section>                  </section>
2830    
2831                  <section title="Setting audio output type" anchor="SET CHANNEL AUDIO_OUTPUT_TYPE">                  <section title="Setting audio output type" anchor="SET CHANNEL AUDIO_OUTPUT_TYPE" lscp_cmd="true">
2832                      <t>DEPRECATED: THIS COMMAND WILL DISAPPEAR SOON!</t>                      <t>DEPRECATED: THIS COMMAND WILL DISAPPEAR!</t>
2833    
2834                      <t>The front-end can alter the audio output type on a specific sampler                      <t>The front-end can alter the audio output type on a specific sampler
2835                      channel by sending the following command:</t>                      channel by sending the following command:</t>
# Line 2809  Schoenebeck'> Line 2869  Schoenebeck'>
2869                              <t></t>                              <t></t>
2870                          </list>                          </list>
2871                      </t>                      </t>
2872                        <t>Deprecated:</t>
2873                        <t>
2874                            <list>
2875                                <t>Should not be used anymore. This command is currently only preserved for backward compatibility.</t>
2876                                <t>This command is a relict from times where there was no sophisticated driver management yet. Use <xref target="CREATE AUDIO_OUTPUT_DEVICE">"CREATE AUDIO_OUTPUT_DEVICE"</xref> and <xref target="SET CHANNEL AUDIO_OUTPUT_DEVICE">"SET CHANNEL AUDIO_OUTPUT_DEVICE"</xref> instead.</t>
2877                            </list>
2878                        </t>
2879                  </section>                  </section>
2880    
2881                  <section title="Setting audio output channel" anchor="SET CHANNEL AUDIO_OUTPUT_CHANNEL">                  <section title="Setting audio output channel" anchor="SET CHANNEL AUDIO_OUTPUT_CHANNEL" lscp_cmd="true">
2882                      <t>The front-end can alter the audio output channel on a specific                      <t>The front-end can alter the audio output channel on a specific
2883                      sampler channel by sending the following command:</t>                      sampler channel by sending the following command:</t>
2884                      <t>                      <t>
# Line 2856  Schoenebeck'> Line 2923  Schoenebeck'>
2923                      </t>                      </t>
2924                  </section>                  </section>
2925    
2926                  <section title="Setting MIDI input device" anchor="SET CHANNEL MIDI_INPUT_DEVICE">                  <section title="Add MIDI input to sampler channel" anchor="ADD CHANNEL MIDI_INPUT" lscp_cmd="true">
2927                        <t>The front-end can add a MIDI input on a specific sampler
2928                        channel by sending the following command:</t>
2929                        <t>
2930                            <list>
2931                                <t>ADD CHANNEL MIDI_INPUT &lt;sampler-channel&gt; &lt;midi-device-id&gt; [&lt;midi-input-port&gt;]</t>
2932                            </list>
2933                        </t>
2934                        <t>Where &lt;sampler-channel&gt; is the sampler channel number
2935                        as returned by the <xref target="ADD CHANNEL">"ADD CHANNEL"</xref>
2936                        or <xref target="LIST CHANNELS">"LIST CHANNELS"</xref> command
2937                        and &lt;midi-device-id&gt; is the numerical ID of the MIDI input
2938                        device as returned by the
2939                        <xref target="CREATE MIDI_INPUT_DEVICE">"CREATE MIDI_INPUT_DEVICE"</xref>
2940                        or <xref target="LIST MIDI_INPUT_DEVICES">"LIST MIDI_INPUT_DEVICES"</xref> command,
2941                        and &lt;midi-input-port&gt; is an optional MIDI input port number of that
2942                        MIDI input device. If &lt;midi-input-port&gt; is omitted,
2943                        then the MIDI input device's first port (port number 0) is
2944                        used.
2945                        </t>
2946    
2947                        <t>Possible Answers:</t>
2948                        <t>
2949                            <list>
2950                                <t>"OK" -
2951                                    <list>
2952                                        <t>on success</t>
2953                                    </list>
2954                                </t>
2955                                <t>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
2956                                    <list>
2957                                        <t>if MIDI input port was connected, but there are noteworthy
2958                                        issue(s) related, providing an appropriate warning code and
2959                                        warning message</t>
2960                                    </list>
2961                                </t>
2962                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
2963                                    <list>
2964                                        <t>in case it failed, providing an appropriate error code and error message</t>
2965                                    </list>
2966                                </t>
2967                            </list>
2968                        </t>
2969                        <t>Examples:</t>
2970                        <t>
2971                            <list>
2972                                <t>C: "ADD CHANNEL MIDI_INPUT 0 0"</t>
2973                                <t>S: "OK"</t>
2974                                <t>C: "ADD CHANNEL MIDI_INPUT 1 0"</t>
2975                                <t>S: "OK"</t>
2976                                <t>C: "ADD CHANNEL MIDI_INPUT 1 1 1"</t>
2977                                <t>S: "OK"</t>
2978                                <t>C: "ADD CHANNEL MIDI_INPUT 1 2 0"</t>
2979                                <t>S: "OK"</t>
2980                            </list>
2981                        </t>
2982                        <t>Since:</t>
2983                        <t>
2984                            <list>
2985                                <t>Introduced with LSCP v1.6</t>
2986                            </list>
2987                        </t>
2988                    </section>
2989    
2990                    <section title="Remove MIDI input(s) from sampler channel" anchor="REMOVE CHANNEL MIDI_INPUT" lscp_cmd="true">
2991                        <t>The front-end can remove one ore more MIDI input(s) on a
2992                        specific sampler channel by sending the following command:</t>
2993                        <t>
2994                            <list>
2995                                <t>REMOVE CHANNEL MIDI_INPUT &lt;sampler-channel&gt; [&lt;midi-device-id&gt; [&lt;midi-input-port&gt;]]</t>
2996                            </list>
2997                        </t>
2998                        <t>Where &lt;sampler-channel&gt; is the sampler channel number
2999                        as returned by the <xref target="ADD CHANNEL">"ADD CHANNEL"</xref>
3000                        or <xref target="LIST CHANNELS">"LIST CHANNELS"</xref> command
3001                        and &lt;midi-device-id&gt; and &lt;midi-input-port&gt; are
3002                        optional numerical IDs defining the MIDI input device and
3003                        one of its MIDI ports as returned by the
3004                        <xref target="LIST CHANNEL MIDI_INPUTS">"LIST CHANNEL MIDI_INPUTS"</xref> command.
3005                        </t>
3006    
3007                        <t>
3008                        If &lt;midi-input-port&gt; is omitted, then all MIDI input
3009                        ports of &lt;midi-device-id&gt; are disconnected from this
3010                        sampler channel.
3011                        </t>
3012    
3013                        <t>
3014                        If both, &lt;midi-device-id&gt; and &lt;midi-input-port&gt;
3015                        are omitted, then all MIDI input ports currently connected
3016                        to this sampler channel are disconnected from this sampler
3017                        channel.
3018                        </t>
3019    
3020                        <t>Possible Answers:</t>
3021                        <t>
3022                            <list>
3023                                <t>"OK" -
3024                                    <list>
3025                                        <t>on success</t>
3026                                    </list>
3027                                </t>
3028                                <t>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
3029                                    <list>
3030                                        <t>if MIDI input porst were disconnected, but there are noteworthy
3031                                        issue(s) related, providing an appropriate warning code and
3032                                        warning message</t>
3033                                    </list>
3034                                </t>
3035                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
3036                                    <list>
3037                                        <t>in case it failed, providing an appropriate error code and error message</t>
3038                                    </list>
3039                                </t>
3040                            </list>
3041                        </t>
3042                        <t>Examples:</t>
3043                        <t>
3044                            <list>
3045                                <t>C: "REMOVE CHANNEL MIDI_INPUT 0"</t>
3046                                <t>S: "OK"</t>
3047                                <t>C: "REMOVE CHANNEL MIDI_INPUT 1"</t>
3048                                <t>S: "OK"</t>
3049                                <t>C: "REMOVE CHANNEL MIDI_INPUT 1 2 0"</t>
3050                                <t>S: "OK"</t>
3051                            </list>
3052                        </t>
3053                        <t>Since:</t>
3054                        <t>
3055                            <list>
3056                                <t>Introduced with LSCP v1.6</t>
3057                            </list>
3058                        </t>
3059                    </section>
3060    
3061                    <section title="Getting all MIDI inputs of a sampler channel" anchor="LIST CHANNEL MIDI_INPUTS" lscp_cmd="true">
3062                        <t>The front-end can query a list of all currently connected
3063                        MIDI inputs of a certain sampler channel by sending the following
3064                        command:</t>
3065                        <t>
3066                            <list>
3067                                <t>LIST CHANNEL MIDI_INPUTS &lt;sampler-channel&gt;</t>
3068                            </list>
3069                        </t>
3070                        <t>Where &lt;sampler-channel&gt; is the sampler channel number
3071                        as returned by the <xref target="ADD CHANNEL">"ADD CHANNEL"</xref>
3072                        or <xref target="LIST CHANNELS">"LIST CHANNELS"</xref> command.
3073                        </t>
3074    
3075                        <t>Possible Answers:</t>
3076                        <t>
3077                            <list>
3078                                <t>The sampler will answer by sending a comma separated
3079                                list of MIDI input device ID - MIDI input port number pairs, where
3080                                each pair is encapsulated into curly braces. The
3081                                list is returned in one single line. The MIDI input
3082                                device ID corresponds to the number returned by
3083                                <xref target="LIST MIDI_INPUT_DEVICES">"LIST MIDI_INPUT_DEVICES"</xref>
3084                                and the port number is the index of the respective MIDI
3085                                port of that MIDI input device.</t>
3086                            </list>
3087                        </t>
3088    
3089                        <t>Example:</t>
3090                        <t>
3091                            <list>
3092                                <t>C: "LIST CHANNEL MIDI_INPUTS 0"</t>
3093                                <t>S: "{0,0},{1,3},{2,0}"</t>
3094                            </list>
3095                        </t>
3096    
3097                        <t>Since:</t>
3098                        <t>
3099                            <list>
3100                                <t>Introduced with LSCP v1.6</t>
3101                            </list>
3102                        </t>
3103                    </section>
3104    
3105                    <section title="Setting MIDI input device" anchor="SET CHANNEL MIDI_INPUT_DEVICE" lscp_cmd="true">
3106                        <t>DEPRECATED: THIS COMMAND WILL DISAPPEAR!</t>
3107    
3108                      <t>The front-end can set the MIDI input device on a specific sampler                      <t>The front-end can set the MIDI input device on a specific sampler
3109                      channel by sending the following command:</t>                      channel by sending the following command:</t>
3110                      <t>                      <t>
# Line 2871  Schoenebeck'> Line 3119  Schoenebeck'>
3119                      <xref target="CREATE MIDI_INPUT_DEVICE">"CREATE MIDI_INPUT_DEVICE"</xref>                      <xref target="CREATE MIDI_INPUT_DEVICE">"CREATE MIDI_INPUT_DEVICE"</xref>
3120                      or <xref target="LIST MIDI_INPUT_DEVICES">"LIST MIDI_INPUT_DEVICES"</xref> command.</t>                      or <xref target="LIST MIDI_INPUT_DEVICES">"LIST MIDI_INPUT_DEVICES"</xref> command.</t>
3121    
3122                        <t>
3123                        If more than 1 MIDI inputs are currently connected to this
3124                        sampler channel: Sending this command will disconnect ALL
3125                        currently connected MIDI input ports connected to this
3126                        sampler channel before establishing the new MIDI input
3127                        connection. So this command does NOT add the connection,
3128                        it replaces all existing ones instead. This behavior is due
3129                        to preserving full behavior backward compatibility.
3130                        </t>
3131    
3132                      <t>Possible Answers:</t>                      <t>Possible Answers:</t>
3133                      <t>                      <t>
3134                          <list>                          <list>
# Line 2899  Schoenebeck'> Line 3157  Schoenebeck'>
3157                              <t></t>                              <t></t>
3158                          </list>                          </list>
3159                      </t>                      </t>
3160                        <t>Deprecated:</t>
3161                        <t>
3162                            <list>
3163                                <t>Should not be used anymore as of LSCP v1.6 and younger. This command is currently only preserved for backward compatibility.</t>
3164                                <t>This command is a relict from times where only one MIDI input per sampler channel was allowed. Use <xref target="ADD CHANNEL MIDI_INPUT">"ADD CHANNEL MIDI_INPUT"</xref> and <xref target="REMOVE CHANNEL MIDI_INPUT">"REMOVE CHANNEL MIDI_INPUT"</xref> instead.</t>
3165                            </list>
3166                        </t>
3167                  </section>                  </section>
3168    
3169                  <section title="Setting MIDI input type" anchor="SET CHANNEL MIDI_INPUT_TYPE">                  <section title="Setting MIDI input type" anchor="SET CHANNEL MIDI_INPUT_TYPE" lscp_cmd="true">
3170                      <t>DEPRECATED: THIS COMMAND WILL DISAPPEAR SOON!</t>                      <t>DEPRECATED: THIS COMMAND WILL DISAPPEAR!</t>
3171    
3172                      <t>The front-end can alter the MIDI input type on a specific sampler                      <t>The front-end can alter the MIDI input type on a specific sampler
3173                      channel by sending the following command:</t>                      channel by sending the following command:</t>
# Line 2914  Schoenebeck'> Line 3179  Schoenebeck'>
3179                      <t>Where &lt;midi-input-type&gt; is currently only "ALSA" and                      <t>Where &lt;midi-input-type&gt; is currently only "ALSA" and
3180                      &lt;sampler-channel&gt; is the respective sampler channel number.</t>                      &lt;sampler-channel&gt; is the respective sampler channel number.</t>
3181    
3182                        <t>
3183                        If more than 1 MIDI inputs are currently connected to this
3184                        sampler channel: Sending this command will disconnect ALL
3185                        currently connected MIDI input ports connected to this
3186                        sampler channel before establishing the new MIDI input
3187                        connection. So this command does NOT add the connection,
3188                        it replaces all existing ones instead. This behavior is due
3189                        to preserving full behavior backward compatibility.
3190                        </t>
3191    
3192                      <t>Possible Answers:</t>                      <t>Possible Answers:</t>
3193                      <t>                      <t>
3194                          <list>                          <list>
# Line 2942  Schoenebeck'> Line 3217  Schoenebeck'>
3217                              <t></t>                              <t></t>
3218                          </list>                          </list>
3219                      </t>                      </t>
3220                        <t>Deprecated:</t>
3221                        <t>
3222                            <list>
3223                                <t>Should not be used anymore. This command is currently only preserved for backward compatibility.</t>
3224                                <t>This command is a relict from times where only 1 MIDI input per sampler channels was allowed and where no sophisticated driver management existed yet. Use <xref target="ADD CHANNEL MIDI_INPUT">"ADD CHANNEL MIDI_INPUT"</xref> and <xref target="REMOVE CHANNEL MIDI_INPUT">"REMOVE CHANNEL MIDI_INPUT"</xref> instead.</t>
3225                            </list>
3226                        </t>
3227                  </section>                  </section>
3228    
3229                  <section title="Setting MIDI input port" anchor="SET CHANNEL MIDI_INPUT_PORT">                  <section title="Setting MIDI input port" anchor="SET CHANNEL MIDI_INPUT_PORT" lscp_cmd="true">
3230                        <t>DEPRECATED: THIS COMMAND WILL DISAPPEAR!</t>
3231                        
3232                      <t>The front-end can alter the MIDI input port on a specific sampler                      <t>The front-end can alter the MIDI input port on a specific sampler
3233                      channel by sending the following command:</t>                      channel by sending the following command:</t>
3234                      <t>                      <t>
# Line 2955  Schoenebeck'> Line 3239  Schoenebeck'>
3239                      <t>Where &lt;midi-input-port&gt; is a MIDI input port number of the                      <t>Where &lt;midi-input-port&gt; is a MIDI input port number of the
3240                      MIDI input device connected to the sampler channel given by                      MIDI input device connected to the sampler channel given by
3241                      &lt;sampler-channel&gt;.</t>                      &lt;sampler-channel&gt;.</t>
3242                        
3243                        <t>
3244                        If more than 1 MIDI inputs are currently connected to this
3245                        sampler channel: Sending this command will switch the
3246                        connection of the first (and only the first) MIDI input port
3247                        currently being connected to this sampler channel, to
3248                        another port of the same MIDI input device. Or in other
3249                        words: the first MIDI input port currently connected to
3250                        this sampler channel will be disconnected, and the requested
3251                        other port of its MIDI input device will be connected to
3252                        this sampler channel instead. This behavior is due
3253                        to preserving full behavior backward compatibility.
3254                        </t>
3255    
3256                      <t>Possible Answers:</t>                      <t>Possible Answers:</t>
3257                      <t>                      <t>
# Line 2984  Schoenebeck'> Line 3281  Schoenebeck'>
3281                              <t></t>                              <t></t>
3282                          </list>                          </list>
3283                      </t>                      </t>
3284                        <t>Deprecated:</t>
3285                        <t>
3286                            <list>
3287                                <t>Should not be used anymore. This command is currently only preserved for backward compatibility.</t>
3288                                <t>This command is a relict from times where only one MIDI input per sampler channel was allowed. Use <xref target="ADD CHANNEL MIDI_INPUT">"ADD CHANNEL MIDI_INPUT"</xref> and <xref target="REMOVE CHANNEL MIDI_INPUT">"REMOVE CHANNEL MIDI_INPUT"</xref> instead.</t>
3289                            </list>
3290                        </t>
3291                  </section>                  </section>
3292    
3293                  <section title="Setting MIDI input channel" anchor="SET CHANNEL MIDI_INPUT_CHANNEL">                  <section title="Setting MIDI input channel" anchor="SET CHANNEL MIDI_INPUT_CHANNEL" lscp_cmd="true">
3294                      <t>The front-end can alter the MIDI channel a sampler channel should                      <t>The front-end can alter the MIDI channel a sampler channel should
3295                      listen to by sending the following command:</t>                      listen to by sending the following command:</t>
3296                      <t>                      <t>
# Line 2994  Schoenebeck'> Line 3298  Schoenebeck'>
3298                              <t>SET CHANNEL MIDI_INPUT_CHANNEL &lt;sampler-channel&gt; &lt;midi-input-chan&gt;</t>                              <t>SET CHANNEL MIDI_INPUT_CHANNEL &lt;sampler-channel&gt; &lt;midi-input-chan&gt;</t>
3299                          </list>                          </list>
3300                      </t>                      </t>
3301                      <t>Where &lt;midi-input-chan&gt; is the number of the new MIDI input channel where                      <t>Where &lt;midi-input-chan&gt; is the number
3302                      &lt;sampler-channel&gt; should listen to or "ALL" to listen on all 16 MIDI                      of the new MIDI input channel (zero indexed!) where
3303                        &lt;sampler-channel&gt; should listen to, or "ALL" to listen on all 16 MIDI
3304                      channels.</t>                      channels.</t>
3305    
3306                      <t>Possible Answers:</t>                      <t>Possible Answers:</t>
# Line 3023  Schoenebeck'> Line 3328  Schoenebeck'>
3328                      <t>Examples:</t>                      <t>Examples:</t>
3329                      <t>                      <t>
3330                          <list>                          <list>
3331                              <t></t>                              <t>C: "SET CHANNEL MIDI_INPUT_CHANNEL 0 0"</t>
3332                                <t>S: "OK"</t>
3333                                <t>C: "SET CHANNEL MIDI_INPUT_CHANNEL 1 ALL"</t>
3334                                <t>S: "OK"</t>
3335                          </list>                          </list>
3336                      </t>                      </t>
3337                  </section>                  </section>
3338    
3339                  <section title="Setting channel volume" anchor="SET CHANNEL VOLUME">                  <section title="Setting channel volume" anchor="SET CHANNEL VOLUME" lscp_cmd="true">
3340                      <t>The front-end can alter the volume of a sampler channel by sending                      <t>The front-end can alter the volume of a sampler channel by sending
3341                      the following command:</t>                      the following command:</t>
3342                      <t>                      <t>
# Line 3071  Schoenebeck'> Line 3379  Schoenebeck'>
3379                      </t>                      </t>
3380                  </section>                  </section>
3381    
3382                  <section title="Muting a sampler channel" anchor="SET CHANNEL MUTE">                  <section title="Muting a sampler channel" anchor="SET CHANNEL MUTE" lscp_cmd="true">
3383                      <t>The front-end can mute/unmute a specific sampler                      <t>The front-end can mute/unmute a specific sampler
3384                      channel by sending the following command:</t>                      channel by sending the following command:</t>
3385                      <t>                      <t>
# Line 3115  Schoenebeck'> Line 3423  Schoenebeck'>
3423                      </t>                      </t>
3424                  </section>                  </section>
3425    
3426                  <section title="Soloing a sampler channel" anchor="SET CHANNEL SOLO">                  <section title="Soloing a sampler channel" anchor="SET CHANNEL SOLO" lscp_cmd="true">
3427                      <t>The front-end can solo/unsolo a specific sampler channel                      <t>The front-end can solo/unsolo a specific sampler channel
3428                      by sending the following command:</t>                      by sending the following command:</t>
3429                      <t>                      <t>
# Line 3159  Schoenebeck'> Line 3467  Schoenebeck'>
3467                      </t>                      </t>
3468                  </section>                  </section>
3469    
3470                  <section title="Assigning a MIDI instrument map to a sampler channel" anchor="SET CHANNEL MIDI_INSTRUMENT_MAP">                  <section title="Assigning a MIDI instrument map to a sampler channel" anchor="SET CHANNEL MIDI_INSTRUMENT_MAP" lscp_cmd="true">
3471                      <t>The front-end can assign a MIDI instrument map to a specific sampler channel                      <t>The front-end can assign a MIDI instrument map to a specific sampler channel
3472                      by sending the following command:</t>                      by sending the following command:</t>
3473                      <t>                      <t>
# Line 3227  Schoenebeck'> Line 3535  Schoenebeck'>
3535                      </t>                      </t>
3536                  </section>                  </section>
3537    
3538                  <section title="Resetting a sampler channel" anchor="RESET CHANNEL">                  <section title="Adding an effect send to a sampler channel" anchor="CREATE FX_SEND" lscp_cmd="true">
3539                        <t>The front-end can create an additional effect send on a specific sampler channel
3540                        by sending the following command:</t>
3541                        <t>
3542                            <list>
3543                                <t>CREATE FX_SEND &lt;sampler-channel&gt; &lt;midi-ctrl&gt; [&lt;name&gt;]</t>
3544                            </list>
3545                        </t>
3546                        <t>Where &lt;sampler-channel&gt; is the respective sampler channel
3547                        number as returned by the <xref target="ADD CHANNEL">"ADD CHANNEL"</xref>
3548                        or <xref target="LIST CHANNELS">"LIST CHANNELS"</xref> command, that is the
3549                        sampler channel on which the effect send should be created on, &lt;midi-ctrl&gt;
3550                        is a number between 0..127 defining the MIDI controller which can alter the
3551                        effect send level and &lt;name&gt; is an optional argument defining a name
3552                        for the effect send entity. The name does not have to be unique, but MUST be
3553                        encapsulated into apostrophes and supports escape sequences as described in chapter
3554                        "<xref target="character_set">Character Set and Escape Sequences</xref>".</t>
3555    
3556                        <t>Note: there are two possible approaches to apply audio effects with FX sends:
3557                           you can either use a) internal effects or b) external effects.
3558                           By default, that is as initial routing, effect sends are automatically routed
3559                           directly to the sampler channel's audio output device and the effect send's
3560                           audio channels are by default automatically routed to the last audio channels
3561                           of that audio output device (for the purpose of applying effects externally that is,
3562                           e.g. by using another application), that way you can i.e. first increase the
3563                           amount of audio channels on the audio output device for having dedicated effect
3564                           send output channels and when "CREATE FX_SEND" is called, those channels will
3565                           automatically be picked. You can alter the destination channels however with
3566                           <xref target="SET FX_SEND AUDIO_OUTPUT_CHANNEL">"SET FX_SEND AUDIO_OUTPUT_CHANNEL"</xref>.
3567                           If your intention is rather to use internal effects instead of external effects,
3568                           then you first need to <xref target="effects">load those internal effects</xref>
3569                           and then assign the FX sends to the desired internal effect by sending
3570                           <xref target="SET FX_SEND EFFECT">"SET FX_SEND EFFECT"</xref>.
3571                        </t>
3572    
3573                        <t>Note: Create effect sends on a sampler channel only when needed, because having effect
3574                        sends on a sampler channel will decrease runtime performance, because for implementing channel
3575                        effect sends, separate (sampler channel local) audio buffers are needed to render and mix
3576                        the voices and route the audio signal afterwards to the master outputs and effect send
3577                        outputs (along with their respective effect send levels). A sampler channel without effect
3578                        sends however can mix its voices directly into the audio output devices's audio buffers
3579                        and is thus faster.
3580                        </t>
3581    
3582                        <t>Possible Answers:</t>
3583                        <t>
3584                            <list>
3585                                <t>"OK[&lt;fx-send-id&gt;]" -
3586                                    <list>
3587                                        <t>in case a new effect send could be added to the
3588                                        sampler channel, where &lt;fx-send-id&gt; reflects the
3589                                        unique ID of the newly created effect send entity</t>
3590                                    </list>
3591                                </t>
3592                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
3593                                    <list>
3594                                        <t>when a new effect send could not be added, i.e.
3595                                        due to invalid parameters</t>
3596                                    </list>
3597                                </t>
3598                            </list>
3599                        </t>
3600    
3601                        <t>Examples:</t>
3602                        <t>
3603                            <list>
3604                                <t>C: "CREATE FX_SEND 0 91 'Reverb Send'"</t>
3605                                <t>S: "OK[0]"</t>
3606                            </list>
3607                        </t>
3608                        <t>
3609                            <list>
3610                                <t>C: "CREATE FX_SEND 0 93"</t>
3611                                <t>S: "OK[1]"</t>
3612                            </list>
3613                        </t>
3614                    </section>
3615    
3616                    <section title="Removing an effect send from a sampler channel" anchor="DESTROY FX_SEND" lscp_cmd="true">
3617                        <t>The front-end can remove an existing effect send on a specific sampler channel
3618                        by sending the following command:</t>
3619                        <t>
3620                            <list>
3621                                <t>DESTROY FX_SEND &lt;sampler-channel&gt; &lt;fx-send-id&gt;</t>
3622                            </list>
3623                        </t>
3624                        <t>Where &lt;sampler-channel&gt; is the respective sampler channel
3625                        number as returned by the <xref target="ADD CHANNEL">"ADD CHANNEL"</xref>
3626                        or <xref target="LIST CHANNELS">"LIST CHANNELS"</xref> command, that is the
3627                        sampler channel from which the effect send should be removed from and
3628                        &lt;fx-send-id&gt; is the respective effect send number as returned by the
3629                        <xref target="CREATE FX_SEND">"CREATE FX_SEND"</xref>
3630                        or <xref target="LIST FX_SENDS">"LIST FX_SENDS"</xref> command.</t>
3631    
3632                        <t>Possible Answers:</t>
3633                        <t>
3634                            <list>
3635                                <t>"OK" -
3636                                    <list>
3637                                        <t>on success</t>
3638                                    </list>
3639                                </t>
3640                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
3641                                    <list>
3642                                        <t>in case it failed, providing an appropriate error code and
3643                                        error message</t>
3644                                    </list>
3645                                </t>
3646                            </list>
3647                        </t>
3648    
3649                        <t>Example:</t>
3650                        <t>
3651                            <list>
3652                                <t>C: "DESTROY FX_SEND 0 0"</t>
3653                                <t>S: "OK"</t>
3654                            </list>
3655                        </t>
3656                    </section>
3657    
3658                    <section title="Getting amount of effect sends on a sampler channel" anchor="GET FX_SENDS" lscp_cmd="true">
3659                        <t>The front-end can ask for the amount of effect sends on a specific sampler channel
3660                        by sending the following command:</t>
3661                        <t>
3662                            <list>
3663                                <t>GET FX_SENDS &lt;sampler-channel&gt;</t>
3664                            </list>
3665                        </t>
3666                        <t>Where &lt;sampler-channel&gt; is the respective sampler channel
3667                        number as returned by the <xref target="ADD CHANNEL">"ADD CHANNEL"</xref>
3668                        or <xref target="LIST CHANNELS">"LIST CHANNELS"</xref> command.</t>
3669    
3670                        <t>Possible Answers:</t>
3671                        <t>
3672                            <list>
3673                                <t>The sampler will answer by returning the number of effect
3674                                sends on the given sampler channel.</t>
3675                            </list>
3676                        </t>
3677    
3678                        <t>Example:</t>
3679                        <t>
3680                            <list>
3681                                <t>C: "GET FX_SENDS 0"</t>
3682                                <t>S: "2"</t>
3683                            </list>
3684                        </t>
3685                    </section>
3686    
3687                    <section title="Listing all effect sends on a sampler channel" anchor="LIST FX_SENDS" lscp_cmd="true">
3688                        <t>The front-end can ask for a list of effect sends on a specific sampler channel
3689                        by sending the following command:</t>
3690                        <t>
3691                            <list>
3692                                <t>LIST FX_SENDS &lt;sampler-channel&gt;</t>
3693                            </list>
3694                        </t>
3695                        <t>Where &lt;sampler-channel&gt; is the respective sampler channel
3696                        number as returned by the <xref target="ADD CHANNEL">"ADD CHANNEL"</xref>
3697                        or <xref target="LIST CHANNELS">"LIST CHANNELS"</xref> command.</t>
3698    
3699                        <t>Possible Answers:</t>
3700                        <t>
3701                            <list>
3702                                <t>The sampler will answer by returning a comma separated list
3703                                with all effect sends' numerical IDs on the given sampler
3704                                channel.</t>
3705                            </list>
3706                        </t>
3707    
3708                        <t>Examples:</t>
3709                        <t>
3710                            <list>
3711                                <t>C: "LIST FX_SENDS 0"</t>
3712                                <t>S: "0,1"</t>
3713                            </list>
3714                        </t>
3715                        <t>
3716                            <list>
3717                                <t>C: "LIST FX_SENDS 1"</t>
3718                                <t>S: ""</t>
3719                            </list>
3720                        </t>
3721                    </section>
3722    
3723                    <section title="Getting effect send information" anchor="GET FX_SEND INFO" lscp_cmd="true">
3724                        <t>The front-end can ask for the current settings of an effect send entity
3725                        by sending the following command:</t>
3726                        <t>
3727                            <list>
3728                                <t>GET FX_SEND INFO &lt;sampler-channel&gt; &lt;fx-send-id&gt;</t>
3729                            </list>
3730                        </t>
3731                        <t>Where &lt;sampler-channel&gt; is the sampler channel number
3732                        as returned by the <xref target="ADD CHANNEL">"ADD CHANNEL"</xref>
3733                        or <xref target="LIST CHANNELS">"LIST CHANNELS"</xref> command and
3734                        &lt;fx-send-id&gt; reflects the numerical ID of the effect send entity
3735                        as returned by the <xref target="CREATE FX_SEND">"CREATE FX_SEND"</xref>
3736                        or <xref target="LIST FX_SENDS">"LIST FX_SENDS"</xref> command.
3737                       </t>
3738    
3739                        <t>Possible Answers:</t>
3740                        <t>
3741                            <list>
3742                                <t>The sampler will answer by sending a &lt;CRLF&gt; separated list.
3743                                Each answer line begins with the settings category name
3744                                followed by a colon and then a space character &lt;SP&gt; and finally
3745                                the info character string to that setting category. At the
3746                                moment the following categories are defined:</t>
3747    
3748                                <t>
3749                                    <list>
3750                                        <t>NAME -
3751                                            <list>
3752                                                <t>name of the effect send entity
3753                                                (note that this character string may contain
3754                                                 <xref target="character_set">escape sequences</xref>)</t>
3755                                            </list>
3756                                        </t>
3757                                        <t>MIDI_CONTROLLER -
3758                                            <list>
3759                                                <t>a value between 0 and 127 reflecting the MIDI controller
3760                                                which is able to modify the effect send's send level</t>
3761                                            </list>
3762                                        </t>
3763                                        <t>LEVEL -
3764                                            <list>
3765                                                <t>optionally dotted number reflecting the effect send's
3766                                                current send level (where a value &lt; 1.0 means attenuation
3767                                                and a value > 1.0 means amplification)</t>
3768                                            </list>
3769                                        </t>
3770                                        <t>AUDIO_OUTPUT_ROUTING -
3771                                            <list>
3772                                                <t>comma separated list which reflects to which audio
3773                                                channel of the selected audio output device each
3774                                                effect send output channel is routed to, e.g. "0,3" would
3775                                                mean the effect send's output channel 0 is routed to channel
3776                                                0 of the audio output device and the effect send's output
3777                                                channel 1 is routed to the channel 3 of the audio
3778                                                output device (see
3779                                                <xref target="SET FX_SEND AUDIO_OUTPUT_CHANNEL">"SET FX_SEND AUDIO_OUTPUT_CHANNEL"</xref>
3780                                                for details), if an internal send
3781                                                effect is assigned to the effect
3782                                                send, then this setting defines the
3783                                                audio channel routing to that
3784                                                effect instance respectively</t>
3785                                            </list>
3786                                        </t>
3787                                        <t>EFFECT -
3788                                            <list>
3789                                                <t>destination send effect chain ID
3790                                                and destination effect chain
3791                                                position, separated by comma in the
3792                                                form "&lt;effect-chain&gt;,&lt;chain-pos&gt;"
3793                                                or "NONE" if there is no send effect
3794                                                assigned to the effect send</t>
3795                                            </list>
3796                                        </t>
3797                                    </list>
3798                                </t>
3799                            </list>
3800                        </t>
3801                        <t>The mentioned fields above don't have to be in particular order.</t>
3802    
3803                        <t>Example:</t>
3804                        <t>
3805                            <list>
3806                                <t>C: "GET FX_SEND INFO 0 0"</t>
3807                                <t>S: "NAME: Reverb Send"</t>
3808                                <t>&nbsp;&nbsp;&nbsp;"MIDI_CONTROLLER: 91"</t>
3809                                <t>&nbsp;&nbsp;&nbsp;"LEVEL: 0.3"</t>
3810                                <t>&nbsp;&nbsp;&nbsp;"AUDIO_OUTPUT_ROUTING: 2,3"</t>
3811                                <t>&nbsp;&nbsp;&nbsp;"EFFECT: NONE"</t>
3812                                <t>&nbsp;&nbsp;&nbsp;"."</t>
3813                            </list>
3814                        </t>
3815                        <t>
3816                            <list>
3817                                <t>C: "GET FX_SEND INFO 0 1"</t>
3818                                <t>S: "NAME: Delay Send (Internal)"</t>
3819                                <t>&nbsp;&nbsp;&nbsp;"MIDI_CONTROLLER: 93"</t>
3820                                <t>&nbsp;&nbsp;&nbsp;"LEVEL: 0.51"</t>
3821                                <t>&nbsp;&nbsp;&nbsp;"AUDIO_OUTPUT_ROUTING: 1,2"</t>
3822                                <t>&nbsp;&nbsp;&nbsp;"EFFECT: 2,0"</t>
3823                                <t>&nbsp;&nbsp;&nbsp;"."</t>
3824                            </list>
3825                        </t>
3826                    </section>
3827    
3828                    <section title="Changing effect send's name" anchor="SET FX_SEND NAME" lscp_cmd="true">
3829                        <t>The front-end can alter the current name of an effect
3830                        send entity by sending the following command:</t>
3831                        <t>
3832                            <list>
3833                                <t>SET FX_SEND NAME &lt;sampler-chan&gt; &lt;fx-send-id&gt; &lt;name&gt;</t>
3834                            </list>
3835                        </t>
3836                        <t>Where &lt;sampler-chan&gt; is the sampler channel number
3837                        as returned by the <xref target="ADD CHANNEL">"ADD CHANNEL"</xref>
3838                        or <xref target="LIST CHANNELS">"LIST CHANNELS"</xref> command,
3839                        &lt;fx-send-id&gt; reflects the numerical ID of the effect send entity
3840                        as returned by the <xref target="CREATE FX_SEND">"CREATE FX_SEND"</xref>
3841                        or <xref target="LIST FX_SENDS">"LIST FX_SENDS"</xref> command and
3842                        &lt;name&gt; is the new name of the effect send entity, which
3843                        does not have to be unique (name MUST be encapsulated into apostrophes
3844                        and supports escape sequences as described in chapter
3845                        "<xref target="character_set">Character Set and Escape Sequences</xref>").
3846                        </t>
3847    
3848                        <t>Possible Answers:</t>
3849                        <t>
3850                            <list>
3851                                <t>"OK" -
3852                                    <list>
3853                                        <t>on success</t>
3854                                    </list>
3855                                </t>
3856                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
3857                                    <list>
3858                                        <t>in case it failed, providing an appropriate error code and error message</t>
3859                                    </list>
3860                                </t>
3861                            </list>
3862                        </t>
3863                        <t>Example:</t>
3864                        <t>
3865                            <list>
3866                                <t>C: "SET FX_SEND NAME 0 0 'Fx Send 1'"</t>
3867                                <t>S: "OK"</t>
3868                            </list>
3869                        </t>
3870                    </section>
3871    
3872                    <section title="Altering effect send's audio routing" anchor="SET FX_SEND AUDIO_OUTPUT_CHANNEL" lscp_cmd="true">
3873                        <t>The front-end can alter the destination of an effect send's audio channel on a specific
3874                        sampler channel by sending the following command:</t>
3875                        <t>
3876                            <list>
3877                                <t>SET FX_SEND AUDIO_OUTPUT_CHANNEL &lt;sampler-chan&gt; &lt;fx-send-id&gt; &lt;audio-src&gt; &lt;audio-dst&gt;</t>
3878                            </list>
3879                        </t>
3880                        <t>Where &lt;sampler-chan&gt; is the sampler channel number
3881                        as returned by the <xref target="ADD CHANNEL">"ADD CHANNEL"</xref>
3882                        or <xref target="LIST CHANNELS">"LIST CHANNELS"</xref> command,
3883                        &lt;fx-send-id&gt; reflects the numerical ID of the effect send entity
3884                        as returned by the <xref target="CREATE FX_SEND">"CREATE FX_SEND"</xref>
3885                        or <xref target="LIST FX_SENDS">"LIST FX_SENDS"</xref> command,
3886                        &lt;audio-src&gt; is the numerical ID of the effect send's audio channel
3887                        which should be rerouted and &lt;audio-dst&gt; is the numerical ID of
3888                        either a) the audio output channel of the sampler channel's audio output
3889                        device (i.e. if external effect shall be applied) or b) of the audio
3890                        input channel of an internal effect assigned to the FX send where
3891                        &lt;audio-src&gt; should be routed to.</t>
3892    
3893                        <t>Note that effect sends can only route audio to the same audio output
3894                        device as assigned to the effect send's sampler channel. Also note that an
3895                        effect send entity does always have exactly as much audio channels as its
3896                        sampler channel. So if the sampler channel is stereo, the effect send does
3897                        have two audio channels as well. Also keep in mind that the amount of audio
3898                        channels on a sampler channel might be dependant not only to the deployed
3899                        sampler engine on the sampler channel, but also dependant to the instrument
3900                        currently loaded. However you can (effectively) turn an i.e. stereo effect
3901                        send into a mono one by simply altering its audio routing appropriately.</t>
3902    
3903                        <t>Possible Answers:</t>
3904                        <t>
3905                            <list>
3906                                <t>"OK" -
3907                                    <list>
3908                                        <t>on success</t>
3909                                    </list>
3910                                </t>
3911                                <t>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
3912                                    <list>
3913                                        <t>if audio output channel was set, but there are noteworthy
3914                                        issue(s) related, providing an appropriate warning code and
3915                                        warning message</t>
3916                                    </list>
3917                                </t>
3918                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
3919                                    <list>
3920                                        <t>in case it failed, providing an appropriate error code and error message</t>
3921                                    </list>
3922                                </t>
3923                            </list>
3924                        </t>
3925                        <t>Example:</t>
3926                        <t>
3927                            <list>
3928                                <t>C: "SET FX_SEND AUDIO_OUTPUT_CHANNEL 0 0 0 2"</t>
3929                                <t>S: "OK"</t>
3930                            </list>
3931                        </t>
3932                    </section>
3933    
3934                    <section title="Assigning destination effect to an effect send" anchor="SET FX_SEND EFFECT" lscp_cmd="true">
3935                        <t>The front-end can (re-)assign an internal destination effect to an
3936                        effect send by sending the following command:</t>
3937                        <t>
3938                            <list>
3939                                <t>SET FX_SEND EFFECT &lt;sampler-chan&gt; &lt;fx-send-id&gt; &lt;effect-chain&gt; &lt;chain-pos&gt;</t>
3940                            </list>
3941                        </t>
3942                        <t>Where &lt;sampler-chan&gt; is the sampler channel number
3943                        as returned by the <xref target="ADD CHANNEL">"ADD CHANNEL"</xref>
3944                        or <xref target="LIST CHANNELS">"LIST CHANNELS"</xref> command,
3945                        &lt;fx-send-id&gt; reflects the numerical ID of the effect send entity
3946                        as returned by the <xref target="CREATE FX_SEND">"CREATE FX_SEND"</xref>
3947                        or <xref target="LIST FX_SENDS">"LIST FX_SENDS"</xref> command,
3948                        &lt;effect-chain&gt; by the numerical ID of the destination
3949                        effect chain as returned by the
3950                        <xref target="ADD SEND_EFFECT_CHAIN">"ADD SEND_EFFECT_CHAIN"</xref>
3951                        or
3952                        <xref target="LIST SEND_EFFECT_CHAINS">"LIST SEND_EFFECT_CHAINS"</xref>
3953                        command and &lt;chain-pos&gt; reflects the exact effect
3954                        chain position in the effect chain which hosts the actual
3955                        destination effect.</t>
3956    
3957                        <t>Note: This command MUST NOT be used if you want to apply
3958                           audio effects externally! By default FX sends are routed directly
3959                           to the audio output device for that purpose.
3960                           You can also revert this command later on by sending
3961                           <xref target="REMOVE FX_SEND EFFECT">"REMOVE FX_SEND EFFECT"</xref>,
3962                           which will cause the FX send to be routed directly to the sampler channel's
3963                           audio output device instead (i.e. for using external effects instead of
3964                           internal effects).
3965                        </t>
3966    
3967                        <t>Possible Answers:</t>
3968                        <t>
3969                            <list>
3970                                <t>"OK" -
3971                                    <list>
3972                                        <t>on success</t>
3973                                    </list>
3974                                </t>
3975                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
3976                                    <list>
3977                                        <t>in case it failed, providing an appropriate error code and error message</t>
3978                                    </list>
3979                                </t>
3980                            </list>
3981                        </t>
3982                        <t>Example:</t>
3983                        <t>
3984                            <list>
3985                                <t>C: "SET FX_SEND EFFECT 0 0 2 5"</t>
3986                                <t>S: "OK"</t>
3987                            </list>
3988                        </t>
3989                    </section>
3990    
3991                    <section title="Removing destination effect from an effect send" anchor="REMOVE FX_SEND EFFECT" lscp_cmd="true">
3992                        <t>The front-end can (re-)assign a destination effect to an
3993                        effect send by sending the following command:</t>
3994                        <t>
3995                            <list>
3996                                <t>REMOVE FX_SEND EFFECT &lt;sampler-chan&gt; &lt;fx-send-id&gt;</t>
3997                            </list>
3998                        </t>
3999                        <t>Where &lt;sampler-chan&gt; is the sampler channel number
4000                        as returned by the <xref target="ADD CHANNEL">"ADD CHANNEL"</xref>
4001                        or <xref target="LIST CHANNELS">"LIST CHANNELS"</xref> command,
4002                        &lt;fx-send-id&gt; reflects the numerical ID of the effect send entity
4003                        as returned by the <xref target="CREATE FX_SEND">"CREATE FX_SEND"</xref>
4004                        or <xref target="LIST FX_SENDS">"LIST FX_SENDS"</xref> command.</t>
4005    
4006                        <t>After the destination effect has been removed from the
4007                        effect send, the audio signal of the effect send will be
4008                        routed directly to the audio output device, according to the
4009                        audio channel routing setting of the effect send.
4010                        </t>
4011    
4012                        <t>Possible Answers:</t>
4013                        <t>
4014                            <list>
4015                                <t>"OK" -
4016                                    <list>
4017                                        <t>on success</t>
4018                                    </list>
4019                                </t>
4020                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
4021                                    <list>
4022                                        <t>in case it failed, providing an appropriate error code and error message</t>
4023                                    </list>
4024                                </t>
4025                            </list>
4026                        </t>
4027                        <t>Example:</t>
4028                        <t>
4029                            <list>
4030                                <t>C: "REMOVE FX_SEND EFFECT 0 0"</t>
4031                                <t>S: "OK"</t>
4032                            </list>
4033                        </t>
4034                    </section>
4035    
4036                    <section title="Altering effect send's MIDI controller" anchor="SET FX_SEND MIDI_CONTROLLER" lscp_cmd="true">
4037                        <t>The front-end can alter the MIDI controller of an effect
4038                        send entity by sending the following command:</t>
4039                        <t>
4040                            <list>
4041                                <t>SET FX_SEND MIDI_CONTROLLER &lt;sampler-chan&gt; &lt;fx-send-id&gt; &lt;midi-ctrl&gt;</t>
4042                            </list>
4043                        </t>
4044                        <t>Where &lt;sampler-chan&gt; is the sampler channel number
4045                        as returned by the <xref target="ADD CHANNEL">"ADD CHANNEL"</xref>
4046                        or <xref target="LIST CHANNELS">"LIST CHANNELS"</xref> command,
4047                        &lt;fx-send-id&gt; reflects the numerical ID of the effect send entity
4048                        as returned by the <xref target="CREATE FX_SEND">"CREATE FX_SEND"</xref>
4049                        or <xref target="LIST FX_SENDS">"LIST FX_SENDS"</xref> command and
4050                        &lt;midi-ctrl&gt; reflects the MIDI controller which shall be
4051                        able to modify the effect send's send level.</t>
4052    
4053                        <t>Possible Answers:</t>
4054                        <t>
4055                            <list>
4056                                <t>"OK" -
4057                                    <list>
4058                                        <t>on success</t>
4059                                    </list>
4060                                </t>
4061                                <t>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
4062                                    <list>
4063                                        <t>if MIDI controller was set, but there are noteworthy
4064                                        issue(s) related, providing an appropriate warning code and
4065                                        warning message</t>
4066                                    </list>
4067                                </t>
4068                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
4069                                    <list>
4070                                        <t>in case it failed, providing an appropriate error code and error message</t>
4071                                    </list>
4072                                </t>
4073                            </list>
4074                        </t>
4075                        <t>Example:</t>
4076                        <t>
4077                            <list>
4078                                <t>C: "SET FX_SEND MIDI_CONTROLLER 0 0 91"</t>
4079                                <t>S: "OK"</t>
4080                            </list>
4081                        </t>
4082                    </section>
4083    
4084                    <section title="Altering effect send's send level" anchor="SET FX_SEND LEVEL" lscp_cmd="true">
4085                        <t>The front-end can alter the current send level of an effect
4086                        send entity by sending the following command:</t>
4087                        <t>
4088                            <list>
4089                                <t>SET FX_SEND LEVEL &lt;sampler-chan&gt; &lt;fx-send-id&gt; &lt;volume&gt;</t>
4090                            </list>
4091                        </t>
4092                        <t>Where &lt;sampler-chan&gt; is the sampler channel number
4093                        as returned by the <xref target="ADD CHANNEL">"ADD CHANNEL"</xref>
4094                        or <xref target="LIST CHANNELS">"LIST CHANNELS"</xref> command,
4095                        &lt;fx-send-id&gt; reflects the numerical ID of the effect send entity
4096                        as returned by the <xref target="CREATE FX_SEND">"CREATE FX_SEND"</xref>
4097                        or <xref target="LIST FX_SENDS">"LIST FX_SENDS"</xref> command and
4098                        &lt;volume&gt; is an optionally dotted positive number (a value
4099                        smaller than 1.0 means attenuation, whereas a value greater than
4100                        1.0 means amplification) reflecting the new send level.</t>
4101    
4102                        <t>Possible Answers:</t>
4103                        <t>
4104                            <list>
4105                                <t>"OK" -
4106                                    <list>
4107                                        <t>on success</t>
4108                                    </list>
4109                                </t>
4110                                <t>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
4111                                    <list>
4112                                        <t>if new send level was set, but there are noteworthy
4113                                        issue(s) related, providing an appropriate warning code and
4114                                        warning message</t>
4115                                    </list>
4116                                </t>
4117                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
4118                                    <list>
4119                                        <t>in case it failed, providing an appropriate error code and error message</t>
4120                                    </list>
4121                                </t>
4122                            </list>
4123                        </t>
4124                        <t>Example:</t>
4125                        <t>
4126                            <list>
4127                                <t>C: "SET FX_SEND LEVEL 0 0 0.15"</t>
4128                                <t>S: "OK"</t>
4129                            </list>
4130                        </t>
4131                    </section>
4132    
4133                    <section title="Sending MIDI messages to sampler channel" anchor="SEND CHANNEL MIDI_DATA" lscp_cmd="true">
4134                        <t>The front-end can send MIDI events to a specific sampler channel
4135                        by sending the following command:</t>
4136                        <t>
4137                            <list>
4138                                <t>SEND CHANNEL MIDI_DATA &lt;midi-msg&gt; &lt;sampler-chan&gt; &lt;arg1&gt; &lt;arg2&gt;</t>
4139                            </list>
4140                        </t>
4141                        <t>Where &lt;sampler-chan&gt; is the sampler channel number
4142                        as returned by the <xref target="ADD CHANNEL">"ADD CHANNEL"</xref>
4143                        or <xref target="LIST CHANNELS">"LIST CHANNELS"</xref> command,
4144                        &lt;arg1&gt; and &lt;arg2&gt; arguments depend on the &lt;midi-msg&gt; argument, which
4145                        specifies the MIDI message type. Currently, the following MIDI messages are supported:</t>
4146                        <t>
4147                            <list>
4148                                <t>"NOTE_ON" -
4149                                    <list>
4150                                        <t>For turning on MIDI notes, where &lt;arg1&gt;
4151                                        specifies the key number and &lt;arg2&gt; the velocity
4152                                        as described in the MIDI specification.</t>
4153                                    </list>
4154                                </t>
4155                                <t>"NOTE_OFF" -
4156                                    <list>
4157                                        <t>For turning a currently playing MIDI note off, where &lt;arg1&gt;
4158                                        specifies the key number and &lt;arg2&gt; the velocity
4159                                        as described in the MIDI specification.</t>
4160                                    </list>
4161                                </t>
4162                                <t>"CC" -
4163                                    <list>
4164                                        <t>For changing a MIDI controller, where &lt;arg1&gt;
4165                                        specifies the controller number and &lt;arg2&gt; the
4166                                        new value of the controller as described in the Control
4167                                        Change section of the MIDI specification.</t>
4168                                    </list>
4169                                </t>
4170                            </list>
4171                        </t>
4172                        <t>CAUTION: This command is provided for implementations of virtual MIDI keyboards
4173                        and no realtime guarantee whatsoever will be made!</t>
4174                        <t>Possible Answers:</t>
4175                        <t>
4176                            <list>
4177                                <t>"OK" -
4178                                    <list>
4179                                        <t>on success</t>
4180                                    </list>
4181                                </t>
4182                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
4183                                    <list>
4184                                        <t>in case it failed, providing an appropriate error code and error message</t>
4185                                    </list>
4186                                </t>
4187                            </list>
4188                        </t>
4189                        <t>Example:</t>
4190                        <t>
4191                            <list>
4192                                <t>C: "SEND CHANNEL MIDI_DATA NOTE_ON 0 56 112"</t>
4193                                <t>S: "OK"</t>
4194                            </list>
4195                        </t>
4196                    </section>
4197    
4198                    <section title="Resetting a sampler channel" anchor="RESET CHANNEL" lscp_cmd="true">
4199                      <t>The front-end can reset a particular sampler channel by sending the following command:</t>                      <t>The front-end can reset a particular sampler channel by sending the following command:</t>
4200                      <t>                      <t>
4201                          <list>                          <list>
# Line 3275  Schoenebeck'> Line 4243  Schoenebeck'>
4243              <section title="Controlling connection">              <section title="Controlling connection">
4244                  <t>The following commands are used to control the connection to LinuxSampler.</t>                  <t>The following commands are used to control the connection to LinuxSampler.</t>
4245    
4246                  <section title="Register front-end for receiving event messages" anchor="SUBSCRIBE">                  <section title="Register front-end for receiving event messages" anchor="SUBSCRIBE" lscp_cmd="true">
4247                      <t>The front-end can register itself to the LinuxSampler application to                      <t>The front-end can register itself to the LinuxSampler application to
4248                      be informed about noteworthy events by sending this command:</t>                      be informed about noteworthy events by sending this command:</t>
4249                      <t>                      <t>
# Line 3317  Schoenebeck'> Line 4285  Schoenebeck'>
4285                      </t>                      </t>
4286                  </section>                  </section>
4287    
4288                  <section title="Unregister front-end for not receiving event messages" anchor="UNSUBSCRIBE">                  <section title="Unregister front-end for not receiving event messages" anchor="UNSUBSCRIBE" lscp_cmd="true">
4289                      <t>The front-end can unregister itself if it doesn't want to receive event                      <t>The front-end can unregister itself if it doesn't want to receive event
4290                      messages anymore by sending the following command:</t>                      messages anymore by sending the following command:</t>
4291                      <t>                      <t>
# Line 3359  Schoenebeck'> Line 4327  Schoenebeck'>
4327                      </t>                      </t>
4328                  </section>                  </section>
4329    
4330                  <section title="Enable or disable echo of commands" anchor="SET ECHO">                  <section title="Enable or disable echo of commands" anchor="SET ECHO" lscp_cmd="true">
4331                      <t>To enable or disable back sending of commands to the client the following command can be used:</t>                      <t>To enable or disable back sending of commands to the client the following command can be used:</t>
4332                      <t>                      <t>
4333                          <list>                          <list>
# Line 3397  Schoenebeck'> Line 4365  Schoenebeck'>
4365                      </t>                      </t>
4366                  </section>                  </section>
4367    
4368                  <section title="Close client connection" anchor="QUIT">                  <section title="Close client connection" anchor="QUIT" lscp_cmd="true">
4369                      <t>The client can close its network connection to LinuxSampler by sending the following command:</t>                      <t>The client can close its network connection to LinuxSampler by sending the following command:</t>
4370                      <t>                      <t>
4371                          <list>                          <list>
# Line 3412  Schoenebeck'> Line 4380  Schoenebeck'>
4380              <section title="Global commands">              <section title="Global commands">
4381                  <t>The following commands have global impact on the sampler.</t>                  <t>The following commands have global impact on the sampler.</t>
4382    
4383                  <section title="Current number of active voices" anchor="GET TOTAL_VOICE_COUNT">                  <section title="Current number of active voices" anchor="GET TOTAL_VOICE_COUNT" lscp_cmd="true">
4384                      <t>The front-end can ask for the current number of active voices on                      <t>The front-end can ask for the current number of active voices on
4385                      the sampler by sending the following command:</t>                      the sampler by sending the following command:</t>
4386                      <t>                      <t>
# Line 3430  Schoenebeck'> Line 4398  Schoenebeck'>
4398                      </t>                      </t>
4399                  </section>                  </section>
4400    
4401                  <section title="Maximum amount of active voices" anchor="GET TOTAL_VOICE_COUNT_MAX">                  <section title="Maximum amount of active voices" anchor="GET TOTAL_VOICE_COUNT_MAX" lscp_cmd="true">
4402                      <t>The front-end can ask for the maximum number of active voices                      <t>The front-end can ask for the maximum number of active voices
4403                      by sending the following command:</t>                      by sending the following command:</t>
4404                      <t>                      <t>
# Line 3448  Schoenebeck'> Line 4416  Schoenebeck'>
4416                      </t>                      </t>
4417                  </section>                  </section>
4418    
4419                    <section title="Current number of active disk streams" anchor="GET TOTAL_STREAM_COUNT" lscp_cmd="true">
4420                        <t>The front-end can ask for the current number of active disk streams on
4421                        the sampler by sending the following command:</t>
4422                        <t>
4423                            <list>
4424                                <t>GET TOTAL_STREAM_COUNT</t>
4425                            </list>
4426                        </t>
4427    
4428                        <t>Possible Answers:</t>
4429                        <t>
4430                            <list>
4431                                <t>LinuxSampler will answer by returning the number of all active
4432                                disk streams on the sampler.</t>
4433                            </list>
4434                        </t>
4435                    </section>
4436    
4437                  <section title="Reset sampler" anchor="RESET">                  <section title="Reset sampler" anchor="RESET">
4438                      <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>
4439                      <t>                      <t>
# Line 3474  Schoenebeck'> Line 4460  Schoenebeck'>
4460                      </t>                      </t>
4461                  </section>                  </section>
4462    
4463                  <section title="General sampler informations" anchor="GET SERVER INFO">                  <section title="General sampler information" anchor="GET SERVER INFO" lscp_cmd="true">
4464                      <t>The client can ask for general informations about the LinuxSampler                      <t>The client can ask for general information about the LinuxSampler
4465                         instance by sending the following command:</t>                         instance by sending the following command:</t>
4466                      <t>                      <t>
4467                          <list>                          <list>
# Line 3495  Schoenebeck'> Line 4481  Schoenebeck'>
4481                                  <list>                                  <list>
4482                                      <t>DESCRIPTION -                                      <t>DESCRIPTION -
4483                                          <list>                                          <list>
4484                                              <t>arbitrary textual description about the sampler</t>                                              <t>arbitrary textual description about the sampler
4485                                                (note that the character string may contain
4486                                                <xref target="character_set">escape sequences</xref>)</t>
4487                                          </list>                                          </list>
4488                                      </t>                                      </t>
4489                                      <t>VERSION -                                      <t>VERSION -
# Line 3509  Schoenebeck'> Line 4497  Schoenebeck'>
4497                                              complies with (see <xref target="LSCP versioning" /> for details)</t>                                              complies with (see <xref target="LSCP versioning" /> for details)</t>
4498                                          </list>                                          </list>
4499                                      </t>                                      </t>
4500                                        <t>INSTRUMENTS_DB_SUPPORT -
4501                                            <list>
4502                                                <t>either yes or no, specifies whether the
4503                                                sampler is build with instruments database support.</t>
4504                                            </list>
4505                                        </t>
4506                                  </list>                                  </list>
4507                              </t>                              </t>
4508                          </list>                          </list>
4509                      </t>                      </t>
4510                      <t>The mentioned fields above don't have to be in particular order.                      <t>The mentioned fields above don't have to be in particular order.
4511                      Other fields might be added in future.</t>                      Other fields might be added in future.</t>
4512                        
4513                        <t>Example:</t>
4514                        <t>
4515                            <list>
4516                                <t>C: "GET SERVER INFO"</t>
4517                                <t>S: "DESCRIPTION: LinuxSampler - modular, streaming capable sampler"</t>
4518                                <t>&nbsp;&nbsp;&nbsp;"VERSION: 1.0.0.svn23"</t>
4519                                <t>&nbsp;&nbsp;&nbsp;"PROTOCOL_VERSION: 1.5"</t>
4520                                <t>&nbsp;&nbsp;&nbsp;"INSTRUMENTS_DB_SUPPORT: no"</t>
4521                                <t>&nbsp;&nbsp;&nbsp;"."</t>
4522                            </list>
4523                        </t>
4524                  </section>                  </section>
4525    
4526                    <section title="Getting global volume attenuation" anchor="GET VOLUME" lscp_cmd="true">
4527                        <t>The client can ask for the current global sampler-wide volume
4528                        attenuation by sending the following command:</t>
4529                        <t>
4530                            <list>
4531                                <t>GET VOLUME</t>
4532                            </list>
4533                        </t>
4534                        <t>Possible Answers:</t>
4535                        <t>
4536                            <list>
4537                                <t>The sampler will always answer by returning the optional
4538                                dotted floating point coefficient, reflecting the current
4539                                global volume attenuation.
4540                                </t>
4541                            </list>
4542                        </t>
4543                        <t>Note: it is up to the respective sampler engine whether to obey
4544                        that global volume parameter or not, but in general all engines SHOULD
4545                        use this parameter.</t>
4546                    </section>
4547    
4548                    <section title="Setting global volume attenuation" anchor="SET VOLUME" lscp_cmd="true">
4549                        <t>The client can alter the current global sampler-wide volume
4550                        attenuation by sending the following command:</t>
4551                        <t>
4552                            <list>
4553                                <t>SET VOLUME &lt;volume&gt;</t>
4554                            </list>
4555                        </t>
4556                       <t>Where &lt;volume&gt; should be replaced by the optional dotted
4557                       floating point value, reflecting the new global volume parameter.
4558                       This value might usually be in the range between 0.0 and 1.0, that
4559                       is for attenuating the overall volume.</t>
4560    
4561                        <t>Possible Answers:</t>
4562                        <t>
4563                            <list>
4564                                <t>"OK" -
4565                                    <list>
4566                                        <t>on success</t>
4567                                    </list>
4568                                </t>
4569                                <t>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
4570                                    <list>
4571                                        <t>if the global volume was set, but there are noteworthy
4572                                        issue(s) related, providing an appropriate warning code and
4573                                        warning message</t>
4574                                    </list>
4575                                </t>
4576                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
4577                                    <list>
4578                                        <t>in case it failed, providing an appropriate error code and error message</t>
4579                                    </list>
4580                                </t>
4581                            </list>
4582                        </t>
4583                    </section>
4584    
4585                    <section title="Getting global voice limit" anchor="GET VOICES" lscp_cmd="true">
4586                        <t>The client can ask for the current global sampler-wide limit
4587                           for maximum voices by sending the following command:</t>
4588                        <t>
4589                            <list>
4590                                <t>GET VOICES</t>
4591                            </list>
4592                        </t>
4593                        <t>Possible Answers:</t>
4594                        <t>
4595                            <list>
4596                                <t>LinuxSampler will answer by returning the number for
4597                                   the current limit of maximum voices.</t>
4598                            </list>
4599                        </t>
4600    
4601                        <t>The voice limit setting defines how many voices should maximum
4602                           be processed by the sampler at the same time. If the user
4603                           triggers new notes which would exceed that voice limit, the
4604                           sampler engine will react by stealing old voices for those
4605                           newly triggered notes. Note that the amount of voices triggered
4606                           by a new note can be larger than one and is dependent to the
4607                           respective instrument and probably further criterias.</t>
4608                    </section>
4609    
4610                    <section title="Setting global voice limit" anchor="SET VOICES" lscp_cmd="true">
4611                        <t>The client can alter the current global sampler-wide limit
4612                        for maximum voices by sending the following command:</t>
4613                        <t>
4614                            <list>
4615                                <t>SET VOICES &lt;max-voices&gt;</t>
4616                            </list>
4617                        </t>
4618                       <t>Where &lt;max-voices&gt; should be replaced by the integer
4619                       value, reflecting the new global amount limit of maximum voices.
4620                       This value has to be larger than 0.</t>
4621    
4622                        <t>Possible Answers:</t>
4623                        <t>
4624                            <list>
4625                                <t>"OK" -
4626                                    <list>
4627                                        <t>on success</t>
4628                                    </list>
4629                                </t>
4630                                <t>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
4631                                    <list>
4632                                        <t>if the voice limit was set, but there are noteworthy
4633                                        issue(s) related, providing an appropriate warning code and
4634                                        warning message</t>
4635                                    </list>
4636                                </t>
4637                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
4638                                    <list>
4639                                        <t>in case it failed, providing an appropriate error code and error message</t>
4640                                    </list>
4641                                </t>
4642                            </list>
4643                        </t>
4644    
4645                        <t>Note: the given value will be passed to all sampler engine instances.
4646                           The total amount of maximum voices on the running system might thus
4647                           be as big as the given value multiplied by the current amount of engine
4648                           instances.</t>
4649    
4650                         <t>Caution: when adjusting the voice limit, you SHOULD also
4651                            adjust the disk stream limit respectively and vice versa.</t>
4652                    </section>
4653    
4654                    <section title="Getting global disk stream limit" anchor="GET STREAMS" lscp_cmd="true">
4655                        <t>The client can ask for the current global sampler-wide limit
4656                           for maximum disk streams by sending the following command:</t>
4657                        <t>
4658                            <list>
4659                                <t>GET STREAMS</t>
4660                            </list>
4661                        </t>
4662                        <t>Possible Answers:</t>
4663                        <t>
4664                            <list>
4665                                <t>LinuxSampler will answer by returning the number for
4666                                   the current limit of maximum disk streams.</t>
4667                            </list>
4668                        </t>
4669    
4670                        <t>The disk stream limit setting defines how many disk streams should
4671                           maximum be processed by a sampler engine at the same time. The
4672                           higher this value, the more memory (RAM) will be occupied, since
4673                           every disk streams allocates a certain buffer size for being able
4674                           to perform its streaming operations.</t>
4675                    </section>
4676    
4677                    <section title="Setting global disk stream limit" anchor="SET STREAMS" lscp_cmd="true">
4678                        <t>The client can alter the current global sampler-wide limit
4679                        for maximum disk streams by sending the following command:</t>
4680                        <t>
4681                            <list>
4682                                <t>SET STREAMS &lt;max-streams&gt;</t>
4683                            </list>
4684                        </t>
4685                       <t>Where &lt;max-streams&gt; should be replaced by the integer
4686                       value, reflecting the new global amount limit of maximum disk streams.
4687                       This value has to be positive.</t>
4688    
4689                        <t>Possible Answers:</t>
4690                        <t>
4691                            <list>
4692                                <t>"OK" -
4693                                    <list>
4694                                        <t>on success</t>
4695                                    </list>
4696                                </t>
4697                                <t>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
4698                                    <list>
4699                                        <t>if the disk stream limit was set, but there are noteworthy
4700                                        issue(s) related, providing an appropriate warning code and
4701                                        warning message</t>
4702                                    </list>
4703                                </t>
4704                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
4705                                    <list>
4706                                        <t>in case it failed, providing an appropriate error code and error message</t>
4707                                    </list>
4708                                </t>
4709                            </list>
4710                        </t>
4711    
4712                        <t>Note: the given value will be passed to all sampler engine instances.
4713                           The total amount of maximum disk streams on the running system might
4714                           thus be as big as the given value multiplied by the current amount of
4715                           engine instances.</t>
4716    
4717                         <t>Caution: when adjusting the disk stream limit, you SHOULD also
4718                            adjust the voice limit respectively and vice versa.</t>
4719                    </section>
4720    
4721              </section>              </section>
4722    
4723    
# Line 3546  Schoenebeck'> Line 4748  Schoenebeck'>
4748                  cause the sampler to switch to the respective instrument as                  cause the sampler to switch to the respective instrument as
4749                  reflected by the current MIDI instrument map.</t>                  reflected by the current MIDI instrument map.</t>
4750    
4751                  <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" lscp_cmd="true">
4752                      <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
4753                      the following command:</t>                      the following command:</t>
4754                      <t>                      <t>
# Line 3556  Schoenebeck'> Line 4758  Schoenebeck'>
4758                      </t>                      </t>
4759                      <t>Where &lt;name&gt; is an optional argument allowing to                      <t>Where &lt;name&gt; is an optional argument allowing to
4760                      assign a custom name to the new map. MIDI instrument Map                      assign a custom name to the new map. MIDI instrument Map
4761                      names do not have to be unique.</t>                      names do not have to be unique, but MUST be encapsulated
4762                        into apostrophes and support escape sequences as described
4763                        in chapter "<xref target="character_set">Character Set and Escape Sequences</xref>".
4764                        </t>
4765    
4766                      <t>Possible Answers:</t>                      <t>Possible Answers:</t>
4767                      <t>                      <t>
# Line 3599  Schoenebeck'> Line 4804  Schoenebeck'>
4804                      </t>                      </t>
4805                  </section>                  </section>
4806    
4807                  <section title="Delete one particular or all MIDI instrument maps" anchor="REMOVE MIDI_INSTRUMENT_MAP">                  <section title="Delete one particular or all MIDI instrument maps" anchor="REMOVE MIDI_INSTRUMENT_MAP" lscp_cmd="true">
4808                      <t>The front-end can delete a particular MIDI instrument map                      <t>The front-end can delete a particular MIDI instrument map
4809                      by sending the following command:</t>                      by sending the following command:</t>
4810                      <t>                      <t>
# Line 3649  Schoenebeck'> Line 4854  Schoenebeck'>
4854                      </t>                      </t>
4855                  </section>                  </section>
4856    
4857                  <section title="Get amount of existing MIDI instrument maps" anchor="GET MIDI_INSTRUMENT_MAPS">                  <section title="Get amount of existing MIDI instrument maps" anchor="GET MIDI_INSTRUMENT_MAPS" lscp_cmd="true">
4858                      <t>The front-end can retrieve the current amount of MIDI                      <t>The front-end can retrieve the current amount of MIDI
4859                      instrument maps by sending the following command:</t>                      instrument maps by sending the following command:</t>
4860                      <t>                      <t>
# Line 3675  Schoenebeck'> Line 4880  Schoenebeck'>
4880                      </t>                      </t>
4881                  </section>                  </section>
4882    
4883                  <section title="Getting all created MIDI instrument maps" anchor="LIST MIDI_INSTRUMENT_MAPS">                  <section title="Getting all created MIDI instrument maps" anchor="LIST MIDI_INSTRUMENT_MAPS" lscp_cmd="true">
4884                      <t>The number of MIDI instrument maps can change on runtime. To get the                      <t>The number of MIDI instrument maps can change on runtime. To get the
4885                      current list of MIDI instrument maps, the front-end can send the                      current list of MIDI instrument maps, the front-end can send the
4886                      following command:</t>                      following command:</t>
# Line 3700  Schoenebeck'> Line 4905  Schoenebeck'>
4905                      </t>                      </t>
4906                  </section>                  </section>
4907    
4908                  <section title="Getting MIDI instrument map information" anchor="GET MIDI_INSTRUMENT_MAP INFO">                  <section title="Getting MIDI instrument map information" anchor="GET MIDI_INSTRUMENT_MAP INFO" lscp_cmd="true">
4909                      <t>The front-end can ask for the current settings of a MIDI                      <t>The front-end can ask for the current settings of a MIDI
4910                      instrument map by sending the following command:</t>                      instrument map by sending the following command:</t>
4911                      <t>                      <t>
# Line 3727  Schoenebeck'> Line 4932  Schoenebeck'>
4932                                      <t>NAME -                                      <t>NAME -
4933                                          <list>                                          <list>
4934                                              <t>custom name of the given map,                                              <t>custom name of the given map,
4935                                              which does not have to be unique</t>                                              which does not have to be unique
4936                                                (note that this character string may contain
4937                                                 <xref target="character_set">escape sequences</xref>)</t>
4938                                            </list>
4939                                        </t>
4940                                        <t>DEFAULT -
4941                                            <list>
4942                                                <t>either true or false,
4943                                                defines whether this map is the default map</t>
4944                                          </list>                                          </list>
4945                                      </t>                                      </t>
4946                                  </list>                                  </list>
# Line 3741  Schoenebeck'> Line 4954  Schoenebeck'>
4954                          <list>                          <list>
4955                              <t>C: "GET MIDI_INSTRUMENT_MAP INFO 0"</t>                              <t>C: "GET MIDI_INSTRUMENT_MAP INFO 0"</t>
4956                              <t>S: "NAME: Standard Map"</t>                              <t>S: "NAME: Standard Map"</t>
4957                                <t>&nbsp;&nbsp;&nbsp;"DEFAULT: true"</t>
4958                              <t>&nbsp;&nbsp;&nbsp;"."</t>                              <t>&nbsp;&nbsp;&nbsp;"."</t>
4959                          </list>                          </list>
4960                      </t>                      </t>
4961                  </section>                  </section>
4962    
4963                  <section title="Renaming a MIDI instrument map" anchor="SET MIDI_INSTRUMENT_MAP NAME">                  <section title="Renaming a MIDI instrument map" anchor="SET MIDI_INSTRUMENT_MAP NAME" lscp_cmd="true">
4964                      <t>The front-end can alter the custom name of a MIDI                      <t>The front-end can alter the custom name of a MIDI
4965                      instrument map by sending the following command:</t>                      instrument map by sending the following command:</t>
4966                      <t>                      <t>
# Line 3756  Schoenebeck'> Line 4970  Schoenebeck'>
4970                      </t>                      </t>
4971                      <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
4972                      &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
4973                      have to be unique.</t>                      have to be unique (name MUST be encapsulated into apostrophes
4974                        and supports escape sequences as described in chapter
4975                        "<xref target="character_set">Character Set and Escape Sequences</xref>").
4976                        </t>
4977    
4978                      <t>Possible Answers:</t>                      <t>Possible Answers:</t>
4979                      <t>                      <t>
# Line 3783  Schoenebeck'> Line 5000  Schoenebeck'>
5000                      </t>                      </t>
5001                  </section>                  </section>
5002    
5003                  <section title="Create or replace a MIDI instrument map entry" anchor="MAP MIDI_INSTRUMENT">                  <section title="Create or replace a MIDI instrument map entry" anchor="MAP MIDI_INSTRUMENT" lscp_cmd="true">
5004                      <t>The front-end can create a new or replace an existing entry                      <t>The front-end can create a new or replace an existing entry
5005                      in a sampler's MIDI instrument map by sending the following                      in a sampler's MIDI instrument map by sending the following
5006                      command:</t>                      command:</t>
5007                      <t>                      <t>
5008                          <list>                          <list>
5009                              <t>MAP MIDI_INSTRUMENT &lt;map&gt;                              <t>MAP MIDI_INSTRUMENT [NON_MODAL] &lt;map&gt;
5010                              &lt;midi_bank&gt; &lt;midi_prog&gt; &lt;engine_name&gt;                              &lt;midi_bank&gt; &lt;midi_prog&gt; &lt;engine_name&gt;
5011                              &lt;filename&gt; &lt;instrument_index&gt; &lt;volume_value&gt;                              &lt;filename&gt; &lt;instrument_index&gt; &lt;volume_value&gt;
5012                              [&lt;instr_load_mode&gt;] [&lt;name&gt;]</t>                              [&lt;instr_load_mode&gt;] [&lt;name&gt;]</t>
# Line 3803  Schoenebeck'> Line 5020  Schoenebeck'>
5020                      index, &lt;engine_name&gt; a sampler engine name as returned by                      index, &lt;engine_name&gt; a sampler engine name as returned by
5021                      the <xref target="LIST AVAILABLE_ENGINES">"LIST AVAILABLE_ENGINES"</xref>                      the <xref target="LIST AVAILABLE_ENGINES">"LIST AVAILABLE_ENGINES"</xref>
5022                      command (not encapsulated into apostrophes), &lt;filename&gt; the name                      command (not encapsulated into apostrophes), &lt;filename&gt; the name
5023                      of the instrument's file to be deployed (encapsulated into apostrophes),                      of the instrument's file to be deployed (encapsulated into apostrophes,
5024                        supporting escape sequences as described in chapter
5025                        "<xref target="character_set">Character Set and Escape Sequences</xref>"),
5026                      &lt;instrument_index&gt; the index (integer value) of the instrument                      &lt;instrument_index&gt; the index (integer value) of the instrument
5027                      within the given file, &lt;volume_value&gt; reflects the master                      within the given file, &lt;volume_value&gt; reflects the master
5028                      volume of the instrument as optionally dotted number (where a                      volume of the instrument as optionally dotted number (where a
5029                      value < 1.0 means attenuation and a value > 1.0 means                      value &lt; 1.0 means attenuation and a value > 1.0 means
5030                      amplification). This parameter easily allows to adjust the                      amplification). This parameter easily allows to adjust the
5031                      volume of all intruments within a custom instrument map                      volume of all intruments within a custom instrument map
5032                      without having to adjust their instrument files. The                      without having to adjust their instrument files. The
# Line 3842  Schoenebeck'> Line 5061  Schoenebeck'>
5061                              <t>"PERSISTENT" -                              <t>"PERSISTENT" -
5062                                  <list>                                  <list>
5063                                      <t>The instrument will immediately be loaded                                      <t>The instrument will immediately be loaded
5064                                      into memory in the background when this mapping                                      into memory when this mapping
5065                                      command is sent and the instrument is kept all                                      command is sent and the instrument is kept all
5066                                      the time. Instruments with this mode are                                      the time. Instruments with this mode are
5067                                      only freed when the sampler is reset or all                                      only freed when the sampler is reset or all
# Line 3885  Schoenebeck'> Line 5104  Schoenebeck'>
5104                      load modes of entries, the frontend should retrieve the actual                      load modes of entries, the frontend should retrieve the actual
5105                      mode by i.e. sending                      mode by i.e. sending
5106                      <xref target="GET MIDI_INSTRUMENT INFO">"GET MIDI_INSTRUMENT INFO"</xref>                      <xref target="GET MIDI_INSTRUMENT INFO">"GET MIDI_INSTRUMENT INFO"</xref>
5107                      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
5108                      set a custom name (encapsulated into apostrophes) for the mapping                      (encapsulated into apostrophes, supporting escape sequences as described in chapter
5109                      entry, useful for frontends for displaying an appropriate name for                      "<xref target="character_set">Character Set and Escape Sequences</xref>") for the
5110                        mapping entry, useful for frontends for displaying an appropriate name for
5111                      mapped instruments (using                      mapped instruments (using
5112                      <xref target="GET MIDI_INSTRUMENT INFO">"GET MIDI_INSTRUMENT INFO"</xref>).                      <xref target="GET MIDI_INSTRUMENT INFO">"GET MIDI_INSTRUMENT INFO"</xref>).
5113                      </t>                      </t>
5114                      <t>                      <t>
5115                      The "MAP MIDI_INSTRUMENT" command                      By default, "MAP MIDI_INSTRUMENT" commands block until the mapping is
5116                      will immediately return, thus it will not block when an                      completely established in the sampler. The OPTIONAL "NON_MODAL" argument
5117                      instrument is to be loaded due to a "PERSISTENT" type                      however causes the respective "MAP MIDI_INSTRUMENT" command to return
5118                      entry as instruments are loaded in the background. As a                      immediately, that is to let the sampler establish the mapping in the
5119                      consequence this command may not necessarily return an error                      background. So this argument might be especially useful for mappings with
5120                      i.e. when the given instrument file does not exist or may                      a "PERSISTENT" type, because these have to load the respective instruments
5121                      turn out to be corrupt.                      immediately and might thus block for a very long time. It is recommended
5122                        however to use the OPTIONAL "NON_MODAL" argument only if really necessary,
5123                        because it has the following drawbacks: as "NON_MODAL" instructions return
5124                        immediately, they may not necessarily return an error i.e. when the given
5125                        instrument file turns out to be corrupt, beside that subsequent commands
5126                        in a LSCP instruction sequence might fail, because mandatory mappings are
5127                        not yet completed.
5128                      </t>                      </t>
5129    
5130                      <t>Possible Answers:</t>                      <t>Possible Answers:</t>
# Line 3941  Schoenebeck'> Line 5167  Schoenebeck'>
5167                      </t>                      </t>
5168                      <t>                      <t>
5169                          <list>                          <list>
5170                              <t>C: "MAP MIDI_INSTRUMENT 1 8 120 gig '/home/joe/foodrums.gig' 0 1.0 PERSISTENT 'Foo Drumkit'"</t>                              <t>C: "MAP MIDI_INSTRUMENT NON_MODAL 1 8 120 gig '/home/joe/foodrums.gig' 0 1.0 PERSISTENT 'Foo Drumkit'"</t>
5171                              <t>S: "OK"</t>                              <t>S: "OK"</t>
5172                          </list>                          </list>
5173                      </t>                      </t>
5174                  </section>                  </section>
5175    
5176                  <section title="Getting ammount of MIDI instrument map entries" anchor="GET MIDI_INSTRUMENTS">                  <section title="Getting amount of MIDI instrument map entries" anchor="GET MIDI_INSTRUMENTS" lscp_cmd="true">
5177                      <t>The front-end can query the amount of currently existing                      <t>The front-end can query the amount of currently existing
5178                      entries in a MIDI instrument map by sending the following                      entries in a MIDI instrument map by sending the following
5179                      command:</t>                      command:</t>
# Line 3987  Schoenebeck'> Line 5213  Schoenebeck'>
5213                      </t>                      </t>
5214                  </section>                  </section>
5215    
5216                  <section title="Getting indeces of all entries of a MIDI instrument map" anchor="LIST MIDI_INSTRUMENTS">                  <section title="Getting indeces of all entries of a MIDI instrument map" anchor="LIST MIDI_INSTRUMENTS" lscp_cmd="true">
5217                      <t>The front-end can query a list of all currently existing                      <t>The front-end can query a list of all currently existing
5218                      entries in a certain MIDI instrument map by sending the following                      entries in a certain MIDI instrument map by sending the following
5219                      command:</t>                      command:</t>
# Line 4016  Schoenebeck'> Line 5242  Schoenebeck'>
5242                              just reflects the key of the respective map entry,                              just reflects the key of the respective map entry,
5243                              thus subsequent                              thus subsequent
5244                              <xref target="GET MIDI_INSTRUMENT INFO">"GET MIDI_INSTRUMENT INFO"</xref>                              <xref target="GET MIDI_INSTRUMENT INFO">"GET MIDI_INSTRUMENT INFO"</xref>
5245                              command(s) are necessary to retrieve detailed informations                              command(s) are necessary to retrieve detailed information
5246                              about each entry.</t>                              about each entry.</t>
5247                          </list>                          </list>
5248                      </t>                      </t>
# Line 4030  Schoenebeck'> Line 5256  Schoenebeck'>
5256                      </t>                      </t>
5257                  </section>                  </section>
5258    
5259                  <section title="Remove an entry from the MIDI instrument map" anchor="UNMAP MIDI_INSTRUMENT">                  <section title="Remove an entry from the MIDI instrument map" anchor="UNMAP MIDI_INSTRUMENT" lscp_cmd="true">
5260                      <t>The front-end can delete an entry from a MIDI instrument                      <t>The front-end can delete an entry from a MIDI instrument
5261                      map by sending the following command:</t>                      map by sending the following command:</t>
5262                      <t>                      <t>
# Line 4072  Schoenebeck'> Line 5298  Schoenebeck'>
5298                      </t>                      </t>
5299                  </section>                  </section>
5300    
5301                  <section title="Get current settings of MIDI instrument map entry" anchor="GET MIDI_INSTRUMENT INFO">                  <section title="Get current settings of MIDI instrument map entry" anchor="GET MIDI_INSTRUMENT INFO" lscp_cmd="true">
5302                      <t>The front-end can retrieve the current settings of a certain                      <t>The front-end can retrieve the current settings of a certain
5303                      instrument map entry by sending the following command:</t>                      instrument map entry by sending the following command:</t>
5304                      <t>                      <t>
# Line 4105  Schoenebeck'> Line 5331  Schoenebeck'>
5331                                      name for this mapped instrument. It can be set and                                      name for this mapped instrument. It can be set and
5332                                      changed with the                                      changed with the
5333                                      <xref target="MAP MIDI_INSTRUMENT">"MAP MIDI_INSTRUMENT"</xref>                                      <xref target="MAP MIDI_INSTRUMENT">"MAP MIDI_INSTRUMENT"</xref>
5334                                      command and does not have to be unique.</t>                                      command and does not have to be unique.
5335                                        (note that this character string may contain
5336                                        <xref target="character_set">escape sequences</xref>)</t>
5337                                  </list>                                  </list>
5338                              </t>                              </t>
5339                              <t>"ENGINE_NAME" -                              <t>"ENGINE_NAME" -
# Line 4116  Schoenebeck'> Line 5344  Schoenebeck'>
5344                              </t>                              </t>
5345                              <t>"INSTRUMENT_FILE" -                              <t>"INSTRUMENT_FILE" -
5346                                  <list>                                  <list>
5347                                      <t>File name of the instrument.</t>                                      <t>File name of the instrument
5348                                        (note that this path may contain
5349                                        <xref target="character_set">escape sequences</xref>).</t>
5350                                  </list>                                  </list>
5351                              </t>                              </t>
5352                              <t>"INSTRUMENT_NR" -                              <t>"INSTRUMENT_NR" -
# Line 4128  Schoenebeck'> Line 5358  Schoenebeck'>
5358                                  <list>                                  <list>
5359                                      <t>Name of the loaded instrument as reflected by its file.                                      <t>Name of the loaded instrument as reflected by its file.
5360                                      In contrast to the "NAME" field, the "INSTRUMENT_NAME" field                                      In contrast to the "NAME" field, the "INSTRUMENT_NAME" field
5361                                      cannot be changed.</t>                                      cannot be changed (note that this character string may contain
5362                                        <xref target="character_set">escape sequences</xref>).</t>
5363                                  </list>                                  </list>
5364                              </t>                              </t>
5365                              <t>"LOAD_MODE" -                              <t>"LOAD_MODE" -
# Line 4140  Schoenebeck'> Line 5371  Schoenebeck'>
5371                              <t>"VOLUME" -                              <t>"VOLUME" -
5372                                  <list>                                  <list>
5373                                      <t>master volume of the instrument as optionally                                      <t>master volume of the instrument as optionally
5374                                      dotted number (where a value < 1.0 means attenuation                                      dotted number (where a value &lt; 1.0 means attenuation
5375                                      and a value > 1.0 means amplification)</t>                                      and a value > 1.0 means amplification)</t>
5376                                  </list>                                  </list>
5377                              </t>                              </t>
# Line 4164  Schoenebeck'> Line 5395  Schoenebeck'>
5395                      </t>                      </t>
5396                  </section>                  </section>
5397    
5398                  <section title="Clear MIDI instrument map" anchor="CLEAR MIDI_INSTRUMENTS">                  <section title="Clear MIDI instrument map" anchor="CLEAR MIDI_INSTRUMENTS" lscp_cmd="true">
5399                      <t>The front-end can clear a whole MIDI instrument map, that                      <t>The front-end can clear a whole MIDI instrument map, that
5400                      is delete all its entries by sending the following command:</t>                      is delete all its entries by sending the following command:</t>
5401                      <t>                      <t>
# Line 4212  Schoenebeck'> Line 5443  Schoenebeck'>
5443                  </section>                  </section>
5444              </section>              </section>
5445    
         </section>  
5446    
5447                <section title="Managing Instruments Database" anchor="Managing Instruments Database">
5448                    <t>The following commands describe how to use and manage
5449                    the instruments database.</t>
5450                    <t>Notice:</t>
5451                        <t>
5452                            <list>
5453                                <t>All command arguments representing a path or
5454                                instrument/directory name support escape sequences as described in chapter
5455                                "<xref target="character_set">Character Set and Escape Sequences</xref>".
5456                                </t>
5457                                <t>All occurrences of a forward slash in instrument and directory
5458                                   names are escaped with its hex (\x2f) or octal (\057) escape sequence.
5459                                </t>
5460                            </list>
5461                        </t>
5462    
5463                    <section title="Creating a new instrument directory" anchor="ADD DB_INSTRUMENT_DIRECTORY" lscp_cmd="true">
5464                        <t>The front-end can add a new instrument directory to the
5465                        instruments database by sending the following command:</t>
5466                        <t>
5467                            <list>
5468                                <t>ADD DB_INSTRUMENT_DIRECTORY &lt;dir&gt;</t>
5469                            </list>
5470                        </t>
5471                        <t>Where &lt;dir&gt; is the absolute path name of the directory
5472                        to be created (encapsulated into apostrophes).</t>
5473    
5474                        <t>Possible Answers:</t>
5475                        <t>
5476                            <list>
5477                                <t>"OK" -
5478                                    <list>
5479                                        <t>on success</t>
5480                                    </list>
5481                                </t>
5482                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
5483                                    <list>
5484                                        <t>when the directory could not be created, which
5485                                        can happen if the directory already exists or the
5486                                        name contains not allowed symbols</t>
5487                                    </list>
5488                                </t>
5489                            </list>
5490                        </t>
5491    
5492                        <t>Examples:</t>
5493                        <t>
5494                            <list>
5495                                <t>C: "ADD DB_INSTRUMENT_DIRECTORY '/Piano Collection'"</t>
5496                                <t>S: "OK"</t>
5497                            </list>
5498                        </t>
5499                    </section>
5500    
5501                    <section title="Deleting an instrument directory" anchor="REMOVE DB_INSTRUMENT_DIRECTORY" lscp_cmd="true">
5502                        <t>The front-end can delete a particular instrument directory
5503                        from the instruments database by sending the following command:</t>
5504                        <t>
5505                            <list>
5506                                <t>REMOVE DB_INSTRUMENT_DIRECTORY [FORCE] &lt;dir&gt;</t>
5507                            </list>
5508                        </t>
5509                        <t>Where &lt;dir&gt; is the absolute path name of the directory
5510                        to delete. The optional FORCE argument can be used to
5511                        force the deletion of a non-empty directory and all its content.</t>
5512    
5513                        <t>Possible Answers:</t>
5514                        <t>
5515                            <list>
5516                                <t>"OK" -
5517                                    <list>
5518                                        <t>if the directory is deleted successfully</t>
5519                                    </list>
5520                                </t>
5521                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
5522                                    <list>
5523                                        <t>if the given directory does not exist, or
5524                                        if trying to delete a non-empty directory,
5525                                        without using the FORCE argument.</t>
5526                                    </list>
5527                                </t>
5528                            </list>
5529                        </t>
5530    
5531                        <t>Examples:</t>
5532                        <t>
5533                            <list>
5534                                <t>C: "REMOVE DB_INSTRUMENT_DIRECTORY FORCE '/Piano Collection'"</t>
5535                                <t>S: "OK"</t>
5536                            </list>
5537                        </t>
5538                    </section>
5539    
5540                    <section title="Getting amount of instrument directories" anchor="GET DB_INSTRUMENT_DIRECTORIES" lscp_cmd="true">
5541                        <t>The front-end can retrieve the current amount of
5542                        directories in a specific directory by sending the following command:</t>
5543                        <t>
5544                            <list>
5545                                <t>GET DB_INSTRUMENT_DIRECTORIES [RECURSIVE] &lt;dir&gt;</t>
5546                            </list>
5547                        </t>
5548                        <t>Where &lt;dir&gt; should be replaced by the absolute path
5549                        name of the directory. If RECURSIVE is specified, the number of
5550                        all directories, including those located in subdirectories of the
5551                        specified directory, will be returned.</t>
5552    
5553                        <t>Possible Answers:</t>
5554                        <t>
5555                            <list>
5556                                <t>The current number of instrument directories
5557                                in the specified directory.</t>
5558                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
5559                                    <list>
5560                                        <t>if the given directory does not exist.</t>
5561                                    </list>
5562                                </t>
5563                            </list>
5564                        </t>
5565    
5566                        <t>Example:</t>
5567                        <t>
5568                            <list>
5569                                <t>C: "GET DB_INSTRUMENT_DIRECTORIES '/'"</t>
5570                                <t>S: "2"</t>
5571                            </list>
5572                        </t>
5573                    </section>
5574    
5575                    <section title="Listing all directories in specific directory" anchor="LIST DB_INSTRUMENT_DIRECTORIES" lscp_cmd="true">
5576                        <t>The front-end can retrieve the current list of directories
5577                        in specific directory by sending the following command:</t>
5578                        <t>
5579                            <list>
5580                                <t>LIST DB_INSTRUMENT_DIRECTORIES [RECURSIVE] &lt;dir&gt;</t>
5581                            </list>
5582                        </t>
5583                        <t>Where &lt;dir&gt; should be replaced by the absolute path
5584                        name of the directory. If RECURSIVE is specified, the absolute path names
5585                        of all directories, including those located in subdirectories of the
5586                        specified directory, will be returned.</t>
5587    
5588                        <t>Possible Answers:</t>
5589                        <t>
5590                            <list>
5591                                <t>A comma separated list of all instrument directories
5592                                (encapsulated into apostrophes) in the specified directory.</t>
5593                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
5594                                    <list>
5595                                        <t>if the given directory does not exist.</t>
5596                                    </list>
5597                                </t>
5598                            </list>
5599                        </t>
5600                        <t>Example:</t>
5601                        <t>
5602                            <list>
5603                                <t>C: "LIST DB_INSTRUMENT_DIRECTORIES '/'"</t>
5604                                <t>S: "'Piano Collection','Percussion Collection'"</t>
5605                            </list>
5606                        </t>
5607                        <t>
5608                            <list>
5609                                <t>C: "LIST DB_INSTRUMENT_DIRECTORIES RECURSIVE '/'"</t>
5610                                <t>S: "'/Piano Collection','/Piano Collection/Acoustic','/Piano Collection/Acoustic/New','/Percussion Collection'"</t>
5611                            </list>
5612                        </t>
5613                    </section>
5614    
5615                    <section title="Getting instrument directory information" anchor="GET DB_INSTRUMENT_DIRECTORY INFO" lscp_cmd="true">
5616                        <t>The front-end can ask for the current settings of an
5617                        instrument directory by sending the following command:</t>
5618                        <t>
5619                            <list>
5620                                <t>GET DB_INSTRUMENT_DIRECTORY INFO &lt;dir&gt;</t>
5621                            </list>
5622                        </t>
5623                        <t>Where &lt;dir&gt; should be replaced by the absolute path
5624                        name of the directory the front-end is interested in.</t>
5625    
5626                        <t>Possible Answers:</t>
5627                        <t>
5628                            <list>
5629                                <t>LinuxSampler will answer by sending a &lt;CRLF&gt; separated list.
5630                                Each answer line begins with the settings category name
5631                                followed by a colon and then a space character &lt;SP&gt; and finally
5632                                the info character string to that setting category. At the
5633                                moment the following categories are defined:</t>
5634    
5635                                <t>
5636                                    <list>
5637                                        <t>DESCRIPTION -
5638                                            <list>
5639                                                <t>A brief description of the directory content.
5640                                                Note that the character string may contain
5641                                                <xref target="character_set">escape sequences</xref>.</t>
5642                                            </list>
5643                                        </t>
5644                                        <t>CREATED -
5645                                            <list>
5646                                                <t>The creation date and time of the directory,
5647                                                represented in "YYYY-MM-DD HH:MM:SS" format</t>
5648                                            </list>
5649                                        </t>
5650                                        <t>MODIFIED -
5651                                            <list>
5652                                                <t>The date and time of the last modification of the
5653                                                directory, represented in "YYYY-MM-DD HH:MM:SS" format</t>
5654                                            </list>
5655                                        </t>
5656                                    </list>
5657                                </t>
5658                            </list>
5659                        </t>
5660                        <t>The mentioned fields above don't have to be in particular order.</t>
5661    
5662                        <t>Example:</t>
5663                        <t>
5664                            <list>
5665                                <t>C: "GET DB_INSTRUMENT_DIRECTORY INFO '/Piano Collection'"</t>
5666                                <t>S: "DESCRIPTION: Piano collection of instruments in GigaSampler format."</t>
5667                                <t>&nbsp;&nbsp;&nbsp;"CREATED: 2007-02-05 10:23:12"</t>
5668                                <t>&nbsp;&nbsp;&nbsp;"MODIFIED: 2007-04-07 12:50:21"</t>
5669                                <t>&nbsp;&nbsp;&nbsp;"."</t>
5670                            </list>
5671                        </t>
5672                    </section>
5673    
5674                    <section title="Renaming an instrument directory" anchor="SET DB_INSTRUMENT_DIRECTORY NAME" lscp_cmd="true">
5675                        <t>The front-end can alter the name of a specific
5676                        instrument directory by sending the following command:</t>
5677                        <t>
5678                            <list>
5679                                <t>SET DB_INSTRUMENT_DIRECTORY NAME &lt;dir&gt; &lt;name&gt;</t>
5680                            </list>
5681                        </t>
5682                        <t>Where &lt;dir&gt; is the absolute path name of the directory and
5683                        &lt;name&gt; is the new name for that directory.</t>
5684    
5685                        <t>Possible Answers:</t>
5686                        <t>
5687                            <list>
5688                                <t>"OK" -
5689                                    <list>
5690                                        <t>on success</t>
5691                                    </list>
5692                                </t>
5693                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
5694                                    <list>
5695                                        <t>in case the given directory does not exists,
5696                                        or if a directory with name equal to the new
5697                                        name already exists.</t>
5698                                    </list>
5699                                </t>
5700                            </list>
5701                        </t>
5702    
5703                        <t>Example:</t>
5704                        <t>
5705                            <list>
5706                                <t>C: "SET DB_INSTRUMENT_DIRECTORY NAME '/Piano Collection/Acustic' 'Acoustic'"</t>
5707                                <t>S: "OK"</t>
5708                            </list>
5709                        </t>
5710                    </section>
5711    
5712                    <section title="Moving an instrument directory" anchor="MOVE DB_INSTRUMENT_DIRECTORY" lscp_cmd="true">
5713                        <t>The front-end can move a specific
5714                        instrument directory by sending the following command:</t>
5715                        <t>
5716                            <list>
5717                                <t>MOVE DB_INSTRUMENT_DIRECTORY &lt;dir&gt; &lt;dst&gt;</t>
5718                            </list>
5719                        </t>
5720                        <t>Where &lt;dir&gt; is the absolute path name of the directory
5721                        to move and &lt;dst&gt; is the location where the directory will
5722                        be moved to.</t>
5723    
5724                        <t>Possible Answers:</t>
5725                        <t>
5726                            <list>
5727                                <t>"OK" -
5728                                    <list>
5729                                        <t>on success</t>
5730                                    </list>
5731                                </t>
5732                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
5733                                    <list>
5734                                        <t>in case a given directory does not exists,
5735                                        or if a directory with name equal to the name
5736                                        of the specified directory already exists in
5737                                        the destination directory. Error is also thrown
5738                                        when trying to move a directory to a subdirectory
5739                                        of itself.</t>
5740                                    </list>
5741                                </t>
5742                            </list>
5743                        </t>
5744    
5745                        <t>Example:</t>
5746                        <t>
5747                            <list>
5748                                <t>C: "MOVE DB_INSTRUMENT_DIRECTORY '/Acoustic' '/Piano Collection/Acoustic'"</t>
5749                                <t>S: "OK"</t>
5750                            </list>
5751                        </t>
5752                    </section>
5753    
5754                    <section title="Copying instrument directories" anchor="COPY DB_INSTRUMENT_DIRECTORY" lscp_cmd="true">
5755                        <t>The front-end can copy a specific
5756                        instrument directory by sending the following command:</t>
5757                        <t>
5758                            <list>
5759                                <t>COPY DB_INSTRUMENT_DIRECTORY &lt;dir&gt; &lt;dst&gt;</t>
5760                            </list>
5761                        </t>
5762                        <t>Where &lt;dir&gt; is the absolute path name of the directory
5763                        to copy and &lt;dst&gt; is the location where the directory will
5764                        be copied to.</t>
5765    
5766                        <t>Possible Answers:</t>
5767                        <t>
5768                            <list>
5769                                <t>"OK" -
5770                                    <list>
5771                                        <t>on success</t>
5772                                    </list>
5773                                </t>
5774                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
5775                                    <list>
5776                                        <t>in case a given directory does not exists,
5777                                        or if a directory with name equal to the name
5778                                        of the specified directory already exists in
5779                                        the destination directory. Error is also thrown
5780                                        when trying to copy a directory to a subdirectory
5781                                        of itself.</t>
5782                                    </list>
5783                                </t>
5784                            </list>
5785                        </t>
5786    
5787                        <t>Example:</t>
5788                        <t>
5789                            <list>
5790                                <t>C: "COPY DB_INSTRUMENT_DIRECTORY '/Piano Collection/Acoustic' '/Acoustic/Pianos'"</t>
5791                                <t>S: "OK"</t>
5792                            </list>
5793                        </t>
5794                    </section>
5795    
5796                    <section title="Changing the description of directory" anchor="SET DB_INSTRUMENT_DIRECTORY DESCRIPTION" lscp_cmd="true">
5797                        <t>The front-end can alter the description of a specific
5798                        instrument directory by sending the following command:</t>
5799                        <t>
5800                            <list>
5801                                <t>SET DB_INSTRUMENT_DIRECTORY DESCRIPTION &lt;dir&gt; &lt;desc&gt;</t>
5802                            </list>
5803                        </t>
5804                        <t>Where &lt;dir&gt; is the absolute path name of the directory and
5805                        &lt;desc&gt; is the new description for the directory
5806                        (encapsulated into apostrophes, supporting escape sequences as described in chapter
5807                        "<xref target="character_set">Character Set and Escape Sequences</xref>").</t>
5808    
5809                        <t>Possible Answers:</t>
5810                        <t>
5811                            <list>
5812                                <t>"OK" -
5813                                    <list>
5814                                        <t>on success</t>
5815                                    </list>
5816                                </t>
5817                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
5818                                    <list>
5819                                        <t>in case the given directory does not exists.</t>
5820                                    </list>
5821                                </t>
5822                            </list>
5823                        </t>
5824    
5825                        <t>Example:</t>
5826                        <t>
5827                            <list>
5828                                <t>C: "SET DB_INSTRUMENT_DIRECTORY DESCRIPTION '/Piano Collection' 'A collection of piano instruments in various format.'"</t>
5829                                <t>S: "OK"</t>
5830                            </list>
5831                        </t>
5832                    </section>
5833    
5834                    <section title="Finding directories" anchor="FIND DB_INSTRUMENT_DIRECTORIES" lscp_cmd="true">
5835                        <t>The front-end can search for directories
5836                        in specific directory by sending the following command:</t>
5837                        <t>
5838                            <list>
5839                                <t>FIND DB_INSTRUMENT_DIRECTORIES [NON_RECURSIVE] &lt;dir&gt; &lt;criteria-list&gt;</t>
5840                            </list>
5841                        </t>
5842                        <t>Where &lt;dir&gt; should be replaced by the absolute path
5843                        name of the directory to search in. If NON_RECURSIVE is specified, the
5844                        directories located in subdirectories of the specified directory will not
5845                        be searched. &lt;criteria-list&gt; is a list of search criterias
5846                        in form of "key1=val1 key2=val2 ...". The following criterias are
5847                        allowed:</t>
5848                        <t>
5849                          <t>NAME='&lt;search-string&gt;'
5850                              <list>
5851                                  <t>Restricts the search to directories, which names
5852                                  satisfy the supplied search string (encapsulated into apostrophes,
5853                                  supporting escape sequences as described in chapter
5854                                  "<xref target="character_set">Character Set and Escape Sequences</xref>").</t>
5855                              </list>
5856                          </t>
5857    
5858                          <t>CREATED='[&lt;date-after&gt;]..[&lt;date-before&gt;]'
5859                              <list>
5860                                  <t>Restricts the search to directories, which creation
5861                                  date satisfies the specified period, where &lt;date-after&gt;
5862                                  and &lt;date-before&gt; are in "YYYY-MM-DD HH:MM:SS" format.
5863                                  If &lt;date-after&gt; is omitted the search is restricted to
5864                                  directories created before &lt;date-before&gt;. If
5865                                  &lt;date-before&gt; is omitted, the search is restricted
5866                                  to directories created after &lt;date-after&gt;.</t>
5867                              </list>
5868                          </t>
5869    
5870                          <t>MODIFIED='[&lt;date-after&gt;]..[&lt;date-before&gt;]'
5871                              <list>
5872                                  <t>Restricts the search to directories, which
5873                                  date of last modification satisfies the specified period, where
5874                                  &lt;date-after&gt; and &lt;date-before&gt; are in "YYYY-MM-DD HH:MM:SS"
5875                                  format. If &lt;date-after&gt; is omitted the search is restricted to
5876                                  directories, which are last modified before &lt;date-before&gt;. If
5877                                  &lt;date-before&gt; is omitted, the search is restricted to directories,
5878                                  which are last modified after &lt;date-after&gt;.</t>
5879                              </list>
5880                          </t>
5881    
5882                          <t>DESCRIPTION='&lt;search-string&gt;'
5883                              <list>
5884                                  <t>Restricts the search to directories with description
5885                                  that satisfies the supplied search string
5886                                  (encapsulated into apostrophes, supporting escape
5887                                  sequences as described in chapter
5888                                  "<xref target="character_set">Character Set and Escape Sequences</xref>").</t>
5889                              </list>
5890                          </t>
5891                        </t>
5892    
5893                        <t>Where &lt;search-string&gt; is either a regular expression, or a
5894                        word list separated with spaces for OR search and with '+' for AND search.</t>
5895    
5896                        <t>Possible Answers:</t>
5897                        <t>
5898                            <list>
5899                                <t>A comma separated list with the absolute path names (encapsulated into
5900                                apostrophes) of all directories in the specified directory that satisfy
5901                                the supplied search criterias.</t>
5902                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
5903                                    <list>
5904                                        <t>if the given directory does not exist.</t>
5905                                    </list>
5906                                </t>
5907                            </list>
5908                        </t>
5909                        <t>Example:</t>
5910                        <t>
5911                            <list>
5912                                <t>C: "FIND DB_INSTRUMENT_DIRECTORIES '/' NAME='Piano'"</t>
5913                                <t>S: "'/Piano Collection'"</t>
5914                            </list>
5915                        </t>
5916                        <t>
5917                            <list>
5918                                <t>C: "FIND DB_INSTRUMENT_DIRECTORIES '/' CREATED='..2007-04-01 09:30:13'"</t>
5919                                <t>S: "'/Piano Collection','/Percussions'"</t>
5920                            </list>
5921                        </t>
5922                    </section>
5923    
5924                    <section title="Adding instruments to the instruments database" anchor="ADD DB_INSTRUMENTS" lscp_cmd="true">
5925                        <t>The front-end can add one or more instruments
5926                        to the instruments database by sending the following command:</t>
5927                        <t>
5928                            <list>
5929                                <t>ADD DB_INSTRUMENTS [NON_MODAL] [&lt;mode&gt;[ FILE_AS_DIR]] &lt;db_dir&gt; &lt;file_path&gt; [&lt;instr_index&gt;]</t>
5930                            </list>
5931                        </t>
5932                        <t>Where &lt;db_dir&gt; is the absolute path name of a directory
5933                        (encapsulated into apostrophes) in the instruments database in which
5934                        only the new instruments (that are not already in the database) will
5935                        be added, &lt;file_path&gt; is the absolute path name of a file or
5936                        directory in the file system (encapsulated into apostrophes). In case
5937                        an instrument file is supplied, only the instruments in the specified
5938                        file will be added to the instruments database. If the optional
5939                        &lt;instr_index&gt; (the index of the instrument within the given file)
5940                        is supplied too, then only the specified instrument will be added.
5941                        In case a directory is supplied, the instruments in that directory
5942                        will be added. The OPTIONAL &lt;mode&gt; argument is only applied
5943                        when a directory is provided as &lt;file_path&gt; and specifies how the
5944                        scanning will be done and has exactly the following possibilities:</t>
5945                        <t>
5946                            <list>
5947                                <t>"RECURSIVE" -
5948                                    <list>
5949                                        <t>All instruments will be processed, including those
5950                                        in the subdirectories, and the respective subdirectory
5951                                        tree structure will be recreated in the instruments
5952                                        database</t>
5953                                    </list>
5954                                </t>
5955                                <t>"NON_RECURSIVE" -
5956                                    <list>
5957                                        <t>Only the instruments in the specified directory
5958                                        will be added, the instruments in the subdirectories
5959                                        will not be processed.</t>
5960                                    </list>
5961                                </t>
5962                                <t>"FLAT" -
5963                                    <list>
5964                                        <t>All instruments will be processed, including those
5965                                        in the subdirectories, but the respective subdirectory
5966                                        structure will not be recreated in the instruments
5967                                        database. All instruments will be added directly in
5968                                        the specified database directory.</t>
5969                                    </list>
5970                                </t>
5971                            </list>
5972                        </t>
5973    
5974                     <t> If FILE_AS_DIR argument is supplied, all instruments in an instrument
5975                     file will be added to a separate directory in the instruments database, which
5976                     name will be the name of the instrument file with the file extension stripped off.
5977                     </t>
5978                     <t>The difference between regular and NON_MODAL versions of the command
5979                        is that the regular command returns when the scanning is finished
5980                        while NON_MODAL version returns immediately and a background process is launched.
5981                        The <xref target="GET DB_INSTRUMENTS_JOB INFO">GET DB_INSTRUMENTS_JOB INFO</xref>
5982                        command can be used to monitor the scanning progress.</t>
5983    
5984                        <t>Possible Answers:</t>
5985                        <t>
5986                            <list>
5987                                <t>"OK" -
5988                                    <list>
5989                                        <t>on success when NON_MODAL is not supplied</t>
5990                                    </list>
5991                                </t>
5992                                <t>"OK[&lt;job-id&gt;]" -
5993                                    <list>
5994                                        <t>on success when NON_MODAL is supplied, where &lt;job-id&gt;
5995                                        is a numerical ID used to obtain status information about the job progress.
5996                                        See <xref target="GET DB_INSTRUMENTS_JOB INFO">GET DB_INSTRUMENTS_JOB INFO</xref>
5997                                        </t>
5998                                    </list>
5999                                </t>
6000                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
6001                                    <list>
6002                                        <t>if an invalid path is specified.</t>
6003                                    </list>
6004                                </t>
6005                            </list>
6006                        </t>
6007    
6008                        <t>Examples:</t>
6009                        <t>
6010                            <list>
6011                                <t>C: "ADD DB_INSTRUMENTS '/Piano Collection' '/home/me/gigs/PMI Bosendorfer 290.gig' 0"</t>
6012                                <t>S: "OK"</t>
6013                            </list>
6014                        </t>
6015                    </section>
6016    
6017                    <section title="Removing an instrument" anchor="REMOVE DB_INSTRUMENT" lscp_cmd="true">
6018                        <t>The front-end can remove a particular instrument
6019                        from the instruments database by sending the following command:</t>
6020                        <t>
6021                            <list>
6022                                <t>REMOVE DB_INSTRUMENT &lt;instr_path&gt;</t>
6023                            </list>
6024                        </t>
6025                        <t>Where &lt;instr_path&gt; is the absolute path name
6026                        (in the instruments database) of the instrument to remove.</t>
6027    
6028                        <t>Possible Answers:</t>
6029                        <t>
6030                            <list>
6031                                <t>"OK" -
6032                                    <list>
6033                                        <t>if the instrument is removed successfully</t>
6034                                    </list>
6035                                </t>
6036                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
6037                                    <list>
6038                                        <t>if the given path does not exist or
6039                                        is a directory.</t>
6040                                    </list>
6041                                </t>
6042                            </list>
6043                        </t>
6044    
6045                        <t>Examples:</t>
6046                        <t>
6047                            <list>
6048                                <t>C: "REMOVE DB_INSTRUMENT '/Piano Collection/Bosendorfer 290'"</t>
6049                                <t>S: "OK"</t>
6050                            </list>
6051                        </t>
6052                    </section>
6053    
6054                    <section title="Getting amount of instruments" anchor="GET DB_INSTRUMENTS" lscp_cmd="true">
6055                        <t>The front-end can retrieve the current amount of
6056                        instruments in a specific directory by sending the following command:</t>
6057                        <t>
6058                            <list>
6059                                <t>GET DB_INSTRUMENTS [RECURSIVE] &lt;dir&gt;</t>
6060                            </list>
6061                        </t>
6062                        <t>Where &lt;dir&gt; should be replaced by the absolute path name
6063                        of the directory. If RECURSIVE is specified, the number of all
6064                        instruments, including those located in subdirectories of the
6065                        specified directory, will be returned.</t>
6066    
6067                        <t>Possible Answers:</t>
6068                        <t>
6069                            <list>
6070                                <t>The current number of instruments
6071                                in the specified directory.</t>
6072                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
6073                                    <list>
6074                                        <t>if the given directory does not exist.</t>
6075                                    </list>
6076                                </t>
6077                            </list>
6078                        </t>
6079    
6080                        <t>Example:</t>
6081                        <t>
6082                            <list>
6083                                <t>C: "GET DB_INSTRUMENTS '/Piano Collection'"</t>
6084                                <t>S: "2"</t>
6085                            </list>
6086                        </t>
6087                    </section>
6088    
6089                    <section title="Listing all instruments in specific directory" anchor="LIST DB_INSTRUMENTS" lscp_cmd="true">
6090                        <t>The front-end can retrieve the current list of instruments
6091                        in specific directory by sending the following command:</t>
6092                        <t>
6093                            <list>
6094                                <t>LIST DB_INSTRUMENTS [RECURSIVE] &lt;dir&gt;</t>
6095                            </list>
6096                        </t>
6097                        <t>Where &lt;dir&gt; should be replaced by the absolute path
6098                        name of the directory. If RECURSIVE is specified, the absolute path
6099                        names of all instruments, including those located in subdirectories
6100                        of the specified directory, will be returned.</t>
6101    
6102                        <t>Possible Answers:</t>
6103                        <t>
6104                            <list>
6105                                <t>A comma separated list of all instruments
6106                                (encapsulated into apostrophes) in the specified directory.</t>
6107                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
6108                                    <list>
6109                                        <t>if the given directory does not exist.</t>
6110                                    </list>
6111                                </t>
6112                            </list>
6113                        </t>
6114                        <t>Example:</t>
6115                        <t>
6116                            <list>
6117                                <t>C: "LIST DB_INSTRUMENTS '/Piano Collection'"</t>
6118                                <t>S: "'Bosendorfer 290','Steinway D'"</t>
6119                            </list>
6120                        </t>
6121                        <t>
6122                            <list>
6123                                <t>C: "LIST DB_INSTRUMENTS RECURSIVE '/Piano Collection'"</t>
6124                                <t>S: "'/Piano Collection/Bosendorfer 290','/Piano Collection/Steinway D','/Piano Collection/Lite/Free Piano'"</t>
6125                            </list>
6126                        </t>
6127                    </section>
6128    
6129                    <section title="Getting instrument information" anchor="GET DB_INSTRUMENT INFO" lscp_cmd="true">
6130                        <t>The front-end can ask for the current settings of an
6131                        instrument by sending the following command:</t>
6132                        <t>
6133                            <list>
6134                                <t>GET DB_INSTRUMENT INFO &lt;instr_path&gt;</t>
6135                            </list>
6136                        </t>
6137                        <t>Where &lt;instr_path&gt; should be replaced by the absolute path
6138                        name of the instrument the front-end is interested in.</t>
6139    
6140                        <t>Possible Answers:</t>
6141                        <t>
6142                            <list>
6143                                <t>LinuxSampler will answer by sending a &lt;CRLF&gt; separated list.
6144                                Each answer line begins with the settings category name
6145                                followed by a colon and then a space character &lt;SP&gt; and finally
6146                                the info character string to that setting category. At the
6147                                moment the following categories are defined:</t>
6148    
6149                                <t>
6150                                    <list>
6151                                        <t>INSTRUMENT_FILE -
6152                                            <list>
6153                                                <t>File name of the instrument.
6154                                                Note that the character string may contain
6155                                                <xref target="character_set">escape sequences</xref>.</t>
6156                                            </list>
6157                                        </t>
6158                                        <t>INSTRUMENT_NR -
6159                                            <list>
6160                                                <t>Index of the instrument within the file.</t>
6161                                            </list>
6162                                        </t>
6163                                        <t>FORMAT_FAMILY -
6164                                            <list>
6165                                                <t>The format family of the instrument.</t>
6166                                            </list>
6167                                        </t>
6168                                        <t>FORMAT_VERSION -
6169                                            <list>
6170                                                <t>The format version of the instrument.</t>
6171                                            </list>
6172                                        </t>
6173                                        <t>SIZE -
6174                                            <list>
6175                                                <t>The size of the instrument in bytes.</t>
6176                                            </list>
6177                                        </t>
6178                                        <t>CREATED -
6179                                            <list>
6180                                                <t>The date and time when the instrument is added
6181                                                in the instruments database, represented in
6182                                               "YYYY-MM-DD HH:MM:SS" format</t>
6183                                            </list>
6184                                        </t>
6185                                        <t>MODIFIED -
6186                                            <list>
6187                                                <t>The date and time of the last modification of the
6188                                                instrument's database settings, represented in
6189                                                "YYYY-MM-DD HH:MM:SS" format</t>
6190                                            </list>
6191                                        </t>
6192                                        <t>DESCRIPTION -
6193                                            <list>
6194                                                <t>A brief description of the instrument.
6195                                                Note that the character string may contain
6196                                                <xref target="character_set">escape sequences</xref>.</t>
6197                                            </list>
6198                                        </t>
6199                                        <t>IS_DRUM -
6200                                            <list>
6201                                                <t>either true or false, determines whether the
6202                                                instrument is a drumkit or a chromatic instrument</t>
6203                                            </list>
6204                                        </t>
6205                                        <t>PRODUCT -
6206                                            <list>
6207                                                <t>The product title of the instrument.
6208                                                Note that the character string may contain
6209                                                <xref target="character_set">escape sequences</xref>.</t>
6210                                            </list>
6211                                        </t>
6212                                        <t>ARTISTS -
6213                                            <list>
6214                                                <t>Lists the artist names.
6215                                                Note that the character string may contain
6216                                                <xref target="character_set">escape sequences</xref>.</t>
6217                                            </list>
6218                                        </t>
6219                                        <t>KEYWORDS -
6220                                            <list>
6221                                                <t>Provides a list of keywords that refer to the instrument.
6222                                                Keywords are separated with semicolon and blank.
6223                                                Note that the character string may contain
6224                                                <xref target="character_set">escape sequences</xref>.</t>
6225                                            </list>
6226                                        </t>
6227                                    </list>
6228                                </t>
6229                            </list>
6230                        </t>
6231                        <t>The mentioned fields above don't have to be in particular order.</t>
6232    
6233                        <t>Example:</t>
6234                        <t>
6235                            <list>
6236                                <t>C: "GET DB_INSTRUMENT INFO '/Piano Collection/Bosendorfer 290'"</t>
6237                                <t>S: "INSTRUMENT_FILE: /home/me/gigs/Bosendorfer 290.gig"</t>
6238                                <t>&nbsp;&nbsp;&nbsp;"INSTRUMENT_NR: 0"</t>
6239                                <t>&nbsp;&nbsp;&nbsp;"FORMAT_FAMILY: GIG"</t>
6240                                <t>&nbsp;&nbsp;&nbsp;"FORMAT_VERSION: 2"</t>
6241                                <t>&nbsp;&nbsp;&nbsp;"SIZE: 2050871870"</t>
6242                                <t>&nbsp;&nbsp;&nbsp;"CREATED: 2007-02-05 10:23:12"</t>
6243                                <t>&nbsp;&nbsp;&nbsp;"MODIFIED: 2007-04-07 12:50:21"</t>
6244                                <t>&nbsp;&nbsp;&nbsp;"DESCRIPTION: "</t>
6245                                <t>&nbsp;&nbsp;&nbsp;"IS_DRUM: false"</t>
6246                                <t>&nbsp;&nbsp;&nbsp;"PRODUCT: GRANDIOSO Bosendorfer 290"</t>
6247                                <t>&nbsp;&nbsp;&nbsp;"ARTISTS: Post Musical Instruments"</t>
6248                                <t>&nbsp;&nbsp;&nbsp;"KEYWORDS: Bosendorfer"</t>
6249                                <t>&nbsp;&nbsp;&nbsp;"."</t>
6250                            </list>
6251                        </t>
6252                    </section>
6253    
6254                    <section title="Renaming an instrument" anchor="SET DB_INSTRUMENT NAME" lscp_cmd="true">
6255                        <t>The front-end can alter the name of a specific
6256                        instrument by sending the following command:</t>
6257                        <t>
6258                            <list>
6259                                <t>SET DB_INSTRUMENT NAME &lt;instr&gt; &lt;name&gt;</t>
6260                            </list>
6261                        </t>
6262                        <t>Where &lt;instr&gt; is the absolute path name of the instrument and
6263                        &lt;name&gt; is the new name for that instrument.</t>
6264    
6265                        <t>Possible Answers:</t>
6266                        <t>
6267                            <list>
6268                                <t>"OK" -
6269                                    <list>
6270                                        <t>on success</t>
6271                                    </list>
6272                                </t>
6273                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
6274                                    <list>
6275                                        <t>in case the given instrument does not exists,
6276                                        or if an instrument with name equal to the new
6277                                        name already exists.</t>
6278                                    </list>
6279                                </t>
6280                            </list>
6281                        </t>
6282    
6283                        <t>Example:</t>
6284                        <t>
6285                            <list>
6286                                <t>C: "SET DB_INSTRUMENT NAME '/Piano Collection/Bosendorfer' 'Bosendorfer 290'"</t>
6287                                <t>S: "OK"</t>
6288                            </list>
6289                        </t>
6290                    </section>
6291    
6292                    <section title="Moving an instrument" anchor="MOVE DB_INSTRUMENT" lscp_cmd="true">
6293                        <t>The front-end can move a specific instrument to another directory by
6294                        sending the following command:</t>
6295                        <t>
6296                            <list>
6297                                <t>MOVE DB_INSTRUMENT &lt;instr&gt; &lt;dst&gt;</t>
6298                            </list>
6299                        </t>
6300                        <t>Where &lt;instr&gt; is the absolute path name of the instrument
6301                        to move and &lt;dst&gt; is the directory where the instrument will
6302                        be moved to.</t>
6303    
6304                        <t>Possible Answers:</t>
6305                        <t>
6306                            <list>
6307                                <t>"OK" -
6308                                    <list>
6309                                        <t>on success</t>
6310                                    </list>
6311                                </t>
6312                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
6313                                    <list>
6314                                        <t>in case the given instrument does not exists,
6315                                        or if an instrument with name equal to the name of the
6316                                        specified instrument already exists in the destination
6317                                        directory.</t>
6318                                    </list>
6319                                </t>
6320                            </list>
6321                        </t>
6322    
6323                        <t>Example:</t>
6324                        <t>
6325                            <list>
6326                                <t>C: "MOVE DB_INSTRUMENT '/Piano Collection/Bosendorfer 290' '/Piano Collection/Acoustic'"</t>
6327                                <t>S: "OK"</t>
6328                            </list>
6329                        </t>
6330                    </section>
6331    
6332                    <section title="Copying instruments" anchor="COPY DB_INSTRUMENT" lscp_cmd="true">
6333                        <t>The front-end can copy a specific instrument to another directory by
6334                        sending the following command:</t>
6335                        <t>
6336                            <list>
6337                                <t>COPY DB_INSTRUMENT &lt;instr&gt; &lt;dst&gt;</t>
6338                            </list>
6339                        </t>
6340                        <t>Where &lt;instr&gt; is the absolute path name of the instrument
6341                        to copy and &lt;dst&gt; is the directory where the instrument will
6342                        be copied to.</t>
6343    
6344                        <t>Possible Answers:</t>
6345                        <t>
6346                            <list>
6347                                <t>"OK" -
6348                                    <list>
6349                                        <t>on success</t>
6350                                    </list>
6351                                </t>
6352                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
6353                                    <list>
6354                                        <t>in case the given instrument does not exists,
6355                                        or if an instrument with name equal to the name of the
6356                                        specified instrument already exists in the destination
6357                                        directory.</t>
6358                                    </list>
6359                                </t>
6360                            </list>
6361                        </t>
6362    
6363                        <t>Example:</t>
6364                        <t>
6365                            <list>
6366                                <t>C: "COPY DB_INSTRUMENT '/Piano Collection/Bosendorfer 290' '/Acoustic/Pianos/'"</t>
6367                                <t>S: "OK"</t>
6368                            </list>
6369                        </t>
6370                    </section>
6371    
6372                    <section title="Changing the description of instrument" anchor="SET DB_INSTRUMENT DESCRIPTION" lscp_cmd="true">
6373                        <t>The front-end can alter the description of a specific
6374                        instrument by sending the following command:</t>
6375                        <t>
6376                            <list>
6377                                <t>SET DB_INSTRUMENT DESCRIPTION &lt;instr&gt; &lt;desc&gt;</t>
6378                            </list>
6379                        </t>
6380                        <t>Where &lt;instr&gt; is the absolute path name of the instrument and
6381                        &lt;desc&gt; is the new description for the instrument
6382                        (encapsulated into apostrophes, supporting escape sequences as described in chapter
6383                        "<xref target="character_set">Character Set and Escape Sequences</xref>").</t>
6384    
6385                        <t>Possible Answers:</t>
6386                        <t>
6387                            <list>
6388                                <t>"OK" -
6389                                    <list>
6390                                        <t>on success</t>
6391                                    </list>
6392                                </t>
6393                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
6394                                    <list>
6395                                        <t>in case the given instrument does not exists.</t>
6396                                    </list>
6397                                </t>
6398                            </list>
6399                        </t>
6400    
6401                        <t>Example:</t>
6402                        <t>
6403                            <list>
6404                                <t>C: "SET DB_INSTRUMENT DESCRIPTION '/Piano Collection/Acoustic/Bosendorfer 290' 'No comment :)'"</t>
6405                                <t>S: "OK"</t>
6406                            </list>
6407                        </t>
6408                    </section>
6409    
6410                    <section title="Finding instruments" anchor="FIND DB_INSTRUMENTS" lscp_cmd="true">
6411                        <t>The front-end can search for instruments
6412                        in specific directory by sending the following command:</t>
6413                        <t>
6414                            <list>
6415                                <t>FIND DB_INSTRUMENTS [NON_RECURSIVE] &lt;dir&gt; &lt;criteria-list&gt;</t>
6416                            </list>
6417                        </t>
6418                        <t>Where &lt;dir&gt; should be replaced by the absolute path
6419                        name of the directory to search in. If NON_RECURSIVE is specified, the
6420                        directories located in subdirectories of the specified directory will not
6421                        be searched. &lt;criteria-list&gt; is a list of search criterias
6422                        in form of "key1=val1 key2=val2 ...". The following criterias are
6423                        allowed:</t>
6424                        <t>
6425                          <t>NAME='&lt;search-string&gt;'
6426                              <list>
6427                                  <t>Restricts the search to instruments, which names
6428                                  satisfy the supplied search string (encapsulated into apostrophes,
6429                                  supporting escape sequences as described in chapter
6430                                  "<xref target="character_set">Character Set and Escape Sequences</xref>").</t>
6431                              </list>
6432                          </t>
6433    
6434                          <t>SIZE=[&lt;min&gt;]..[&lt;max&gt;]
6435                              <list>
6436                                  <t>Restricts the search to instruments, which
6437                                  size is in the specified range. If &lt;min&gt; is omitted,
6438                                  the search results are restricted to instruments with size less then
6439                                  or equal to &lt;max&gt;. If &lt;max&gt; is omitted, the
6440                                  search is restricted to instruments with size greater then
6441                                  or equal to &lt;min&gt;.</t>
6442                              </list>
6443                          </t>
6444    
6445                          <t>CREATED='[&lt;date-after&gt;]..[&lt;date-before&gt;]'
6446                              <list>
6447                                  <t>Restricts the search to instruments, which creation
6448                                  date satisfies the specified period, where &lt;date-after&gt;
6449                                  and &lt;date-before&gt; are in "YYYY-MM-DD HH:MM:SS" format.
6450                                  If &lt;date-after&gt; is omitted the search is restricted to
6451                                  instruments created before &lt;date-before&gt;. If
6452                                  &lt;date-before&gt; is omitted, the search is restricted
6453                                  to instruments created after &lt;date-after&gt;.</t>
6454                              </list>
6455                          </t>
6456    
6457                          <t>MODIFIED='[&lt;date-after&gt;]..[&lt;date-before&gt;]'
6458                              <list>
6459                                  <t>Restricts the search to instruments, which
6460                                  date of last modification satisfies the specified period, where
6461                                  &lt;date-after&gt; and &lt;date-before&gt; are in "YYYY-MM-DD HH:MM:SS"
6462                                  format. If &lt;date-after&gt; is omitted the search is restricted to
6463                                  instruments, which are last modified before &lt;date-before&gt;. If
6464                                  &lt;date-before&gt; is omitted, the search is restricted to instruments,
6465                                  which are last modified after &lt;date-after&gt;.</t>
6466                              </list>
6467                          </t>
6468    
6469                          <t>DESCRIPTION='&lt;search-string&gt;'
6470                              <list>
6471                                  <t>Restricts the search to instruments with description
6472                                  that satisfies the supplied search string (encapsulated into apostrophes,
6473                                  supporting escape sequences as described in chapter
6474                                  "<xref target="character_set">Character Set and Escape Sequences</xref>").</t>
6475                              </list>
6476                          </t>
6477    
6478                          <t>PRODUCT='&lt;search-string&gt;'
6479                              <list>
6480                                  <t>Restricts the search to instruments with product info
6481                                  that satisfies the supplied search string (encapsulated into apostrophes,
6482                                  supporting escape sequences as described in chapter
6483                                  "<xref target="character_set">Character Set and Escape Sequences</xref>").</t>
6484                              </list>
6485                          </t>
6486    
6487                          <t>ARTISTS='&lt;search-string&gt;'
6488                              <list>
6489                                  <t>Restricts the search to instruments with artists info
6490                                  that satisfies the supplied search string (encapsulated into apostrophes,
6491                                  supporting escape sequences as described in chapter
6492                                  "<xref target="character_set">Character Set and Escape Sequences</xref>").</t>
6493                              </list>
6494                          </t>
6495    
6496                          <t>KEYWORDS='&lt;search-string&gt;'
6497                              <list>
6498                                  <t>Restricts the search to instruments with keyword list
6499                                  that satisfies the supplied search string (encapsulated into apostrophes,
6500                                  supporting escape sequences as described in chapter
6501                                  "<xref target="character_set">Character Set and Escape Sequences</xref>").</t>
6502                              </list>
6503                          </t>
6504    
6505                          <t>IS_DRUM=true | false
6506                              <list>
6507                                  <t>Either true or false. Restricts the search to
6508                                  drum kits or chromatic instruments.</t>
6509                              </list>
6510                          </t>
6511    
6512                          <t>FORMAT_FAMILIES='&lt;format-list&gt;'
6513                              <list>
6514                                  <t>Restricts the search to instruments of the supplied format families,
6515                                  where &lt;format-list&gt; is a comma separated list of format families.</t>
6516                              </list>
6517                          </t>
6518                        </t>
6519    
6520                        <t>Where &lt;search-string&gt; is either a regular expression, or a
6521                        word list separated with spaces for OR search and with '+' for AND search.</t>
6522    
6523                        <t>Possible Answers:</t>
6524                        <t>
6525                            <list>
6526                                <t>A comma separated list with the absolute path names (encapsulated into
6527                                apostrophes) of all instruments in the specified directory that satisfy
6528                                the supplied search criterias.</t>
6529                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
6530                                    <list>
6531                                        <t>if the given directory does not exist.</t>
6532                                    </list>
6533                                </t>
6534                            </list>
6535                        </t>
6536                        <t>Example:</t>
6537                        <t>
6538                            <list>
6539                                <t>C: "FIND DB_INSTRUMENTS '/Piano Collection' NAME='bosendorfer+290'"</t>
6540                                <t>S: "'/Piano Collection/Bosendorfer 290'"</t>
6541                            </list>
6542                        </t>
6543                        <t>
6544                            <list>
6545                                <t>C: "FIND DB_INSTRUMENTS '/Piano Collection' CREATED='2007-04-01 09:30:13..'"</t>
6546                                <t>S: "'/Piano Collection/Bosendorfer 290','/Piano Collection/Steinway D'"</t>
6547                            </list>
6548                        </t>
6549                    </section>
6550    
6551                    <section title="Getting job status information" anchor="GET DB_INSTRUMENTS_JOB INFO" lscp_cmd="true">
6552                        <t>The front-end can ask for the current status of a
6553                        particular database instruments job by sending the following command:</t>
6554                        <t>
6555                            <list>
6556                                <t>GET DB_INSTRUMENTS_JOB INFO &lt;job-id&gt;</t>
6557                            </list>
6558                        </t>
6559                        <t>Where &lt;job-id&gt; should be replaced by the numerical ID
6560                        of the job the front-end is interested in.</t>
6561    
6562                        <t>Possible Answers:</t>
6563                        <t>
6564                            <list>
6565                                <t>LinuxSampler will answer by sending a &lt;CRLF&gt; separated list.
6566                                Each answer line begins with the settings category name
6567                                followed by a colon and then a space character &lt;SP&gt; and finally
6568                                the info character string to that setting category. At the
6569                                moment the following categories are defined:</t>
6570    
6571                                <t>
6572                                    <list>
6573                                        <t>FILES_TOTAL -
6574                                            <list>
6575                                                <t>The total number of files scheduled for scanning</t>
6576                                            </list>
6577                                        </t>
6578                                        <t>FILES_SCANNED -
6579                                            <list>
6580                                                <t>The current number of scanned files</t>
6581                                            </list>
6582                                        </t>
6583                                        <t>SCANNING -
6584                                            <list>
6585                                                <t>The absolute path name of the file which is currently
6586                                                being scanned</t>
6587                                            </list>
6588                                        </t>
6589                                        <t>STATUS -
6590                                            <list>
6591                                                <t>An integer value between 0 and 100 indicating the
6592                                                scanning progress percentage of the file which is
6593                                                currently being scanned</t>
6594                                            </list>
6595                                        </t>
6596                                    </list>
6597                                </t>
6598                            </list>
6599                        </t>
6600                        <t>The mentioned fields above don't have to be in particular order.</t>
6601    
6602                        <t>Example:</t>
6603                        <t>
6604                            <list>
6605                                <t>C: "GET DB_INSTRUMENTS_JOB INFO 2"</t>
6606                                <t>S: "FILES_TOTAL: 12"</t>
6607                                <t>&nbsp;&nbsp;&nbsp;"FILES_SCANNED: 7"</t>
6608                                <t>&nbsp;&nbsp;&nbsp;"SCANNING: /home/me/gigs/Bosendorfer 290.gig"</t>
6609                                <t>&nbsp;&nbsp;&nbsp;"STATUS: 42"</t>
6610                                <t>&nbsp;&nbsp;&nbsp;"."</t>
6611                            </list>
6612                        </t>
6613                    </section>
6614    
6615                    <section title="Formatting the instruments database" anchor="FORMAT INSTRUMENTS_DB" lscp_cmd="true">
6616                        <t>The front-end can remove all instruments and directories and re-create
6617                        the instruments database structure (e.g., in case of a database corruption)
6618                        by sending the following command:</t>
6619                        <t>
6620                            <list>
6621                                <t>FORMAT INSTRUMENTS_DB</t>
6622                            </list>
6623                        </t>
6624    
6625                        <t>Possible Answers:</t>
6626                        <t>
6627                            <list>
6628                                <t>"OK" -
6629                                    <list>
6630                                        <t>on success</t>
6631                                    </list>
6632                                </t>
6633                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
6634                                    <list>
6635                                        <t>If the formatting of the instruments database
6636                                        failed.</t>
6637                                    </list>
6638                                </t>
6639                            </list>
6640                        </t>
6641                    </section>
6642    
6643                    <section title="Checking for lost instrument files" anchor="FIND LOST DB_INSTRUMENT_FILES" lscp_cmd="true">
6644                        <t>The front-end can retrieve the list of all instrument files in the instruments database
6645                        that don't exist in the filesystem by sending the following command:</t>
6646                        <t>
6647                            <list>
6648                                <t>FIND LOST DB_INSTRUMENT_FILES</t>
6649                            </list>
6650                        </t>
6651    
6652                        <t>Possible Answers:</t>
6653                        <t>
6654                            <list>
6655                                <t>A comma separated list with the absolute path names
6656                                (encapsulated into apostrophes) of all lost instrument files.</t>
6657                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
6658                                    <list>
6659                                        <t>in case it failed, providing an appropriate error code and error message.</t>
6660                                    </list>
6661                                </t>
6662                            </list>
6663                        </t>
6664                        <t>Example:</t>
6665                        <t>
6666                            <list>
6667                                <t>C: "FIND LOST DB_INSTRUMENT_FILES"</t>
6668                                <t>S: "'/gigs/Bosendorfer 290.gig','/gigs/Steinway D.gig','/gigs/Free Piano.gig'"</t>
6669                            </list>
6670                        </t>
6671                    </section>
6672    
6673                    <section title="Replacing an instrument file" anchor="SET DB_INSTRUMENT FILE_PATH" lscp_cmd="true">
6674                        <t>The front-end can substitute all occurrences of an instrument file
6675                        in the instruments database with a new one by sending the following command:</t>
6676                        <t>
6677                            <list>
6678                                <t>SET DB_INSTRUMENT FILE_PATH &lt;old_path&gt; &lt;new_path&gt;</t>
6679                            </list>
6680                        </t>
6681                        <t>Where &lt;old_path&gt; is the absolute path name of the instrument file
6682                        to substitute with &lt;new_path&gt;.</t>
6683    
6684                        <t>Possible Answers:</t>
6685                        <t>
6686                            <list>
6687                                <t>"OK" -
6688                                    <list>
6689                                        <t>on success</t>
6690                                    </list>
6691                                </t>
6692                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
6693                                    <list>
6694                                        <t>in case it failed, providing an appropriate error code and error message.</t>
6695                                    </list>
6696                                </t>
6697                            </list>
6698                        </t>
6699    
6700                        <t>Example:</t>
6701                        <t>
6702                            <list>
6703                                <t>C: "SET DB_INSTRUMENT FILE_PATH '/gigs/Bosendorfer 290.gig' '/gigs/pianos/Bosendorfer 290.gig'"</t>
6704                                <t>S: "OK"</t>
6705                            </list>
6706                        </t>
6707                    </section>
6708    
6709                </section>
6710    
6711    
6712    
6713                <section title="Editing Instruments" anchor="editing_instruments">
6714                    <t>The sampler allows to edit instruments while playing with the
6715                    sampler by spawning an external (3rd party) instrument editor
6716                    application for a given instrument. The 3rd party instrument
6717                    editor applications have to place a respective plugin DLL file
6718                    into the sampler's plugins directory. The sampler will
6719                    automatically try to load all plugin DLLs in that directory on
6720                    startup and only on startup!</t>
6721                    <t>At the moment there is only one command for this feature set,
6722                    but this will most probably change in future.</t>
6723    
6724                    <section title="Opening an appropriate instrument editor application" anchor="EDIT INSTRUMENT" lscp_cmd="true">
6725                        <t>The front-end can request to open an appropriate instrument
6726                        editor application by sending the following command:</t>
6727                        <t>
6728                            <list>
6729                                <t>EDIT CHANNEL INSTRUMENT &lt;sampler-channel&gt;</t>
6730                            </list>
6731                        </t>
6732                        <t>Where &lt;sampler-channel&gt; should be replaced by the
6733                        number of the sampler channel as given by the
6734                        <xref target="ADD CHANNEL">"ADD CHANNEL"</xref>
6735                        or <xref target="LIST CHANNELS">"LIST CHANNELS"</xref>
6736                        command.</t>
6737    
6738                        <t>The sampler will try to ask all registered instrument
6739                        editors (or to be more specific: their sampler plugins)
6740                        whether they are capable to handle the instrument on the
6741                        given sampler channel. The sampler will simply use the first
6742                        instrument editor application which replied with a positive
6743                        answer and spawn that instrument editor application within
6744                        the sampler's process and provide that application access
6745                        to the instrument's data structures, so both applications
6746                        can share and access the same instruments data at the same
6747                        time, thus allowing to immediately hear changes with the
6748                        sampler made by the instrument editor.</t>
6749    
6750                        <t>Note: consequently instrument editors are always spawned
6751                        locally on the same machine where the sampler is running
6752                        on!</t>
6753    
6754                        <t>Possible Answers:</t>
6755                        <t>
6756                            <list>
6757                                <t>"OK" -
6758                                    <list>
6759                                        <t>when an appropriate instrument editor was
6760                                        launched</t>
6761                                    </list>
6762                                </t>
6763                                <t>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
6764                                    <list>
6765                                        <t>when an appropriate instrument editor was
6766                                        launched, but there are noteworthy issues</t>
6767                                    </list>
6768                                </t>
6769                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
6770                                    <list>
6771                                        <t>when an appropriate instrument editor
6772                                        could not be launched</t>
6773                                    </list>
6774                                </t>
6775                            </list>
6776                        </t>
6777    
6778                        <t>Examples:</t>
6779                        <t>
6780                            <list>
6781                                <t>C: "EDIT CHANNEL INSTRUMENT 0"</t>
6782                                <t>S: "OK"</t>
6783                            </list>
6784                        </t>
6785                    </section>
6786                </section>
6787    
6788                <section title="Managing Files" anchor="file_management">
6789                    <t>You can query detailed information about files located
6790                    at the same system where the sampler instance is running on.
6791                    Using this command set allows to retrieve file information
6792                    even remotely from another machine.</t>
6793    
6794                    <section title="Retrieving amount of instruments of a file" anchor="GET FILE INSTRUMENTS" lscp_cmd="true">
6795                        <t>The front-end can retrieve the amount of instruments
6796                        within a given instrument file by sending the
6797                        following command:</t>
6798                        <t>
6799                            <list>
6800                                <t>GET FILE INSTRUMENTS &lt;filename&gt;</t>
6801                            </list>
6802                        </t>
6803                        <t>Where &lt;filename&gt; is the name of the instrument
6804                        file (encapsulated into apostrophes, supporting escape
6805                        sequences as described in chapter
6806                        "<xref target="character_set">Character Set and Escape
6807                            Sequences</xref>").</t>
6808    
6809                        <t>The sampler will try to ask all sampler engines,
6810                        whether they support the given file and ask the first
6811                        engine with a positive answer for the amount of
6812                        instruments.</t>
6813    
6814                        <t>Possible Answers:</t>
6815                        <t>
6816                            <list>
6817                                <t>On success, the sampler will answer by
6818                                   returning the amount of instruments.
6819                                </t>
6820                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
6821                                    <list>
6822                                        <t>if the file could not be handled</t>
6823                                    </list>
6824                                </t>
6825                            </list>
6826                        </t>
6827    
6828                        <t>Examples:</t>
6829                        <t>
6830                            <list>
6831                                <t>C: "GET FILE INSTRUMENTS 'D:/Sounds/Foo.gig'"</t>
6832                                <t>S: "10"</t>
6833                            </list>
6834                        </t>
6835                    </section>
6836    
6837                    <section title="Retrieving all instruments of a file" anchor="LIST FILE INSTRUMENTS" lscp_cmd="true">
6838                        <t>The front-end can retrieve a list of all instruments
6839                        within a given instrument file by sending the
6840                        following command:</t>
6841                        <t>
6842                            <list>
6843                                <t>LIST FILE INSTRUMENTS &lt;filename&gt;</t>
6844                            </list>
6845                        </t>
6846                        <t>Where &lt;filename&gt; is the name of the instrument
6847                        file (encapsulated into apostrophes, supporting escape
6848                        sequences as described in chapter
6849                        "<xref target="character_set">Character Set and Escape
6850                            Sequences</xref>").</t>
6851    
6852                        <t>The sampler will try to ask all sampler engines,
6853                        whether they support the given file and ask the first
6854                        engine with a positive answer for a list of IDs for the
6855                        instruments in the given file.</t>
6856    
6857                        <t>Possible Answers:</t>
6858                        <t>
6859                            <list>
6860                                <t>On success, the sampler will answer by
6861                                   returning a comma separated list of
6862                                   instrument IDs.
6863                                </t>
6864                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
6865                                    <list>
6866                                        <t>if the file could not be handled</t>
6867                                    </list>
6868                                </t>
6869                            </list>
6870                        </t>
6871    
6872                        <t>Examples:</t>
6873                        <t>
6874                            <list>
6875                                <t>C: "LIST FILE INSTRUMENTS 'D:/Sounds/Foo.gig'"</t>
6876                                <t>S: "0,1,2,3,4,5,6,7,8,9"</t>
6877                            </list>
6878                        </t>
6879                    </section>
6880    
6881                    <section title="Retrieving information about one instrument in a file" anchor="GET FILE INSTRUMENT INFO" lscp_cmd="true">
6882                        <t>The front-end can retrieve detailed information
6883                        about a specific instrument within a given instrument
6884                        file by sending the following command:</t>
6885                        <t>
6886                            <list>
6887                                <t>GET FILE INSTRUMENT INFO &lt;filename&gt;
6888                                &lt;instr-id&gt;</t>
6889                            </list>
6890                        </t>
6891                        <t>Where &lt;filename&gt; is the name of the instrument
6892                        file (encapsulated into apostrophes, supporting escape
6893                        sequences as described in chapter
6894                        "<xref target="character_set">Character Set and Escape
6895                            Sequences</xref>") and &lt;instr-id&gt; is the numeric
6896                        instrument ID as returned by the
6897                        <xref target="LIST FILE INSTRUMENTS">
6898                        "LIST FILE INSTRUMENTS"</xref> command.</t>
6899    
6900                        <t>The sampler will try to ask all sampler engines,
6901                        whether they support the given file and ask the first
6902                        engine with a positive answer for information about the
6903                        specific instrument in the given file.</t>
6904    
6905                        <t>Possible Answers:</t>
6906                        <t>
6907                            <list>
6908                                <t>LinuxSampler will answer by sending a &lt;CRLF&gt; separated list.
6909                                Each answer line begins with the settings category name
6910                                followed by a colon and then a space character &lt;SP&gt; and finally
6911                                the info character string to that setting category. At the
6912                                moment the following categories are defined:</t>
6913    
6914                                <t>
6915                                    <list>
6916                                        <t>NAME -
6917                                            <list>
6918                                                <t>name of the instrument as
6919                                                stored in the instrument file</t>
6920                                            </list>
6921                                        </t>
6922                                        <t>FORMAT_FAMILY -
6923                                            <list>
6924                                                <t>name of the sampler format
6925                                                of the given instrument</t>
6926                                            </list>
6927                                        </t>
6928                                        <t>FORMAT_VERSION -
6929                                            <list>
6930                                                <t>version of the sampler format
6931                                                the instrumen is stored as</t>
6932                                            </list>
6933                                        </t>
6934                                        <t>PRODUCT -
6935                                            <list>
6936                                                <t>official product name of the
6937                                                instrument as stored in the file
6938                                                </t>
6939                                            </list>
6940                                        </t>
6941                                        <t>ARTISTS -
6942                                            <list>
6943                                                <t>artists / sample library
6944                                                vendor of the instrument</t>
6945                                            </list>
6946                                        </t>
6947                                        <t>KEY_BINDINGS -
6948                                            <list>
6949                                                <t>comma separated list of integer values representing
6950                                                   the instrument's key mapping in the range between 0 .. 127,
6951                                                   reflecting the analog meaning of the MIDI specification.</t>
6952                                            </list>
6953                                        </t>
6954                                        <t>KEYSWITCH_BINDINGS -
6955                                            <list>
6956                                                <t>comma separated list of integer values representing
6957                                                   the instrument's keyswitch mapping in the range between 0 .. 127,
6958                                                   reflecting the analog meaning of the MIDI specification.</t>
6959                                            </list>
6960                                        </t>
6961                                    </list>
6962                                </t>
6963                            </list>
6964                        </t>
6965                        <t>The mentioned fields above don't have to be in particular order.</t>
6966    
6967                        <t>Example:</t>
6968                        <t>
6969                            <list>
6970                                <t>C: "GET FILE INSTRUMENT INFO 'D:/Sounds/Foo.gig' 0"</t>
6971                                <t>S: "NAME: Lunatic Loops"</t>
6972                                <t>&nbsp;&nbsp;&nbsp;"FORMAT_FAMILY: GIG"</t>
6973                                <t>&nbsp;&nbsp;&nbsp;"FORMAT_VERSION: 3"</t>
6974                                <t>&nbsp;&nbsp;&nbsp;"PRODUCT: The Backbone Bongo Beats"</t>
6975                                <t>&nbsp;&nbsp;&nbsp;"ARTISTS: Jimmy the Fish"</t>
6976                                <t>&nbsp;&nbsp;&nbsp;"."</t>
6977                            </list>
6978                        </t>
6979                    </section>
6980                </section>
6981                <section title="Managing Effects" anchor="effects">
6982                    <t>There are two possible approaches to apply audio effects
6983                    (e.g. reverb, delay, compression).
6984                    You can either a) load and apply internal effects or you can b) route
6985                    effect sends directly to dedicated output channels of your
6986                    audio device and apply effects externally (e.g. by routing
6987                    those dedicated output channels to another application).</t>
6988                    <t>This chapter describes how to load and manage internal effects.
6989                    If your intention is rather to apply effects externally, then
6990                    you can omit this chapter. For applying effects externally, you
6991                    just need to <xref target="CREATE FX_SEND">create FX sends</xref>
6992                    on the respective sampler channel(s)
6993                    and <xref target="SET FX_SEND AUDIO_OUTPUT_CHANNEL">adjust their destination audio channels</xref>
6994                    appropriately, because by default FX sends are automatically routed
6995                    directly to the audio output device.</t>
6996                    <t>The sampler usually provides a set of internal audio effects.
6997                    The exact set of effects depends on the availability
6998                    of third party effect plugins installed on the system where the
6999                    sampler runs on (e.g. LADSPA plugins).</t>
7000                    <t>At the moment only "send effects" are supported. Support for
7001                    "insert effects" and "master effects" is planned to be added at
7002                    a later point.</t>
7003                    <t>The following commands allow to retrieve the set of internal
7004                    effects available to the sampler, detailed information about
7005                    those effects and to create and destroy instances of such
7006                    effects. After an instance of an effect is created, the effect
7007                    instance can be inserted into the audio signal path of the
7008                    sampler, e.g. as send effect.</t>
7009                    <t>The sampler allows to create an arbitrary amount of so called
7010                    send effect chains. Each effect chain can host an arbitrary
7011                    amount of effect instances. The output of the first effect
7012                    instance in an effect chain is fed to the input of the second
7013                    effect instance of the chain and so on. So effects in one chain
7014                    are processed sequentially. Send effect chains however are
7015                    processed in parallel to other send effect chains. Audio signals
7016                    of sampler channels are fed to send effects by creating FX sends
7017                    to the respective sampler channel and assigning a destination
7018                    send effect to that FX by using the
7019                    <xref target="SET FX_SEND EFFECT">"SET FX_SEND EFFECT"</xref>
7020                    command. The latter allows to route the FX send to the beginning
7021                    of a send effect chain, as well as directly to any other
7022                    position of the send effect chain.</t>
7023    
7024                    <section title="Retrieve amount of available effects" anchor="GET AVAILABLE_EFFECTS" lscp_cmd="true">
7025                        <t>The front-end can retrieve the amount of internal
7026                        effects, available to the sampler by sending
7027                        the following command:</t>
7028                        <t>
7029                            <list>
7030                                <t>GET AVAILABLE_EFFECTS</t>
7031                            </list>
7032                        </t>
7033    
7034                        <t>Possible Answers:</t>
7035                        <t>
7036                            <list>
7037                                <t>The sampler will answer by returning the current
7038                                number of effects available to the sampler.</t>
7039                            </list>
7040                        </t>
7041    
7042                        <t>Examples:</t>
7043                        <t>
7044                            <list>
7045                                <t>C: "GET AVAILABLE_EFFECTS"</t>
7046                                <t>S: "129"</t>
7047                            </list>
7048                        </t>
7049                    </section>
7050    
7051                    <section title="Get list of available effects" anchor="LIST AVAILABLE_EFFECTS" lscp_cmd="true">
7052                        <t>The set of available internal effects can change at
7053                        runtime. The front-end can retrieve the list of internal
7054                        effects, available to the sampler by sending the following
7055                        command:</t>
7056                        <t>
7057                            <list>
7058                                <t>LIST AVAILABLE_EFFECTS</t>
7059                            </list>
7060                        </t>
7061    
7062                        <t>Possible Answers:</t>
7063                        <t>
7064                            <list>
7065                                <t>The sampler will answer by returning a comma
7066                                separated list with numerical IDs of effects. Note:
7067                                the numercial ID of an effect is generated by the
7068                                sampler for the current moment. The numerical ID of
7069                                the same effect can change at runtime, e.g. when the
7070                                user requests a rescan of available effect plugins.
7071                                </t>
7072                            </list>
7073                        </t>
7074                        <t>Example:</t>
7075                        <t>
7076                            <list>
7077                                <t>C: "LIST AVAILABLE_EFFECTS"</t>
7078                                <t>S: "5,6,7,120,121,122,123,124"</t>
7079                            </list>
7080                        </t>
7081                    </section>
7082    
7083                    <section title="Retrieving general information about an effect" anchor="GET EFFECT INFO" lscp_cmd="true">
7084                        <t>The front-end can ask for general information about an
7085                        effect by sending the following command:</t>
7086                        <t>
7087                            <list>
7088                                <t>GET EFFECT INFO &lt;effect-index&gt;</t>
7089                            </list>
7090                        </t>
7091                        <t>Where &lt;effect-index&gt; is the numerical ID of an
7092                        effect as returned by the
7093                        <xref target="LIST AVAILABLE_EFFECTS">"LIST AVAILABLE_EFFECTS"</xref>
7094                        command.</t>
7095                        <t>Possible Answers:</t>
7096                        <t>
7097                            <list>
7098                                <t>LinuxSampler will answer by sending a &lt;CRLF&gt; separated list.
7099                                Each answer line begins with the effect information
7100                                category name, followed by a colon and then a space
7101                                character &lt;SP&gt; and finally the info character
7102                                string to that effect information category. At the
7103                                moment the following categories are defined:</t>
7104                                <t>
7105                                    <list>
7106                                        <t>SYSTEM -
7107                                            <list>
7108                                                <t>name of the effect plugin system
7109                                                the effect is based on
7110                                                (e.g. "LADSPA")</t>
7111                                            </list>
7112                                        </t>
7113                                        <t>MODULE -
7114                                            <list>
7115                                                <t>module of the effect plugin
7116                                                system that contains this effect,
7117                                                the module is usually the
7118                                                dynamic-linked library (DLL)
7119                                                filename of the effect plugin,
7120                                                including full path (note that this
7121                                                filename may contain
7122                                                <xref target="character_set">escape sequences</xref>)</t>
7123                                            </list>
7124                                        </t>
7125                                        <t>NAME -
7126                                            <list>
7127                                                <t>character string defining the
7128                                                unique name of the effect within its
7129                                                module (note that the character
7130                                                string may contain
7131                                                <xref target="character_set">escape sequences</xref>)</t>
7132                                            </list>
7133                                        </t>
7134                                        <t>DESCRIPTION -
7135                                            <list>
7136                                                <t>human readable name of the
7137                                                effect, intended to be displayed in
7138                                                user interfaces (note that the
7139                                                character string may contain
7140                                                <xref target="character_set">escape sequences</xref>)</t>
7141                                            </list>
7142                                        </t>
7143                                    </list>
7144                                </t>
7145                            </list>
7146                        </t>
7147                        <t>The mentioned fields above don't have to be in particular order.</t>
7148    
7149                        <t>Example:</t>
7150                        <t>
7151                            <list>
7152                                <t>C: "GET EFFECT INFO 121"</t>
7153                                <t>S: "SYSTEM: LADSPA"</t>
7154                                <t>&nbsp;&nbsp;&nbsp;"MODULE: /usr/lib/ladspa/lowpass_iir_1891.so"</t>
7155                                <t>&nbsp;&nbsp;&nbsp;"NAME: lowpass_iir"</t>
7156                                <t>&nbsp;&nbsp;&nbsp;"DESCRIPTION: Glame Lowpass Filter"</t>
7157                                <t>&nbsp;&nbsp;&nbsp;"."</t>
7158                            </list>
7159                        </t>
7160                    </section>
7161    
7162                    <section title="Creating an instance of an effect by its portable ID" anchor="CREATE EFFECT_INSTANCE" lscp_cmd="true">
7163                        <t>The front-end can spawn an instance of the desired
7164                        effect by sending the following command:</t>
7165                        <t>
7166                            <list>
7167                                <t>CREATE EFFECT_INSTANCE &lt;effect-system&gt; &lt;module&gt; &lt;effect-name&gt;</t>
7168                            </list>
7169                        </t>
7170                        <t>Where &lt;effect-system&gt; is the "SYSTEM" field,
7171                        &lt;module&gt; the "MODULE" field and &lt;effect-name&gt;
7172                        the "NAME" field as returned by the
7173                        <xref target="GET EFFECT INFO">"GET EFFECT INFO"</xref>
7174                        command. The filename of argument &lt;module&gt; and the
7175                        character string of argument &lt;effect-name&gt; may contain
7176                        <xref target="character_set">escape sequences</xref>.</t>
7177    
7178                        <t>The sampler will try to load the requested effect and to
7179                        create an instance of it. To allow loading the same effect
7180                        on a different machine, probably even running a completely
7181                        different operating system (e.g. Linux vs. Windows), the
7182                        sampler tries to match &lt;module&gt; "softly". That means
7183                        it first tries to find an effect that exactly matches the
7184                        given &lt;module&gt; argument. If there is no exact match,
7185                        the sampler will try to lower the restrictions on matching
7186                        the &lt;module&gt; argument more and more, e.g. by ignoring
7187                        upper / lower case differences and by ignoring the path of
7188                        the DLL filename and file extension. If there is still no
7189                        match at the end, the sampler will try to ignore the
7190                        &lt;module&gt; argument completely and as a last resort
7191                        search for an effect that only matches the given
7192                        &lt;effect-system&gt; and &lt;effect-name&gt; arguments.</t>
7193    
7194                        <t>Possible Answers:</t>
7195                        <t>
7196                            <list>
7197                                <t>"OK[&lt;effect-instance&gt;]" -
7198                                    <list>
7199                                        <t>in case the effect instance was
7200                                        successfully created, where
7201                                        &lt;effect-instance&gt; is the numerical ID
7202                                        of the new effect instance</t>
7203                                    </list>
7204                                </t>
7205                                <t>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
7206                                    <list>
7207                                        <t>in case the effect instance was spawned
7208                                        successfully, but there are noteworthy
7209                                        issue(s) related, providing an appropriate
7210                                        warning code and warning message</t>
7211                                    </list>
7212                                </t>
7213                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
7214                                    <list>
7215                                        <t>if the effect could not be instantiated</t>
7216                                    </list>
7217                                </t>
7218                            </list>
7219                        </t>
7220    
7221                        <t>Examples:</t>
7222                        <t>
7223                            <list>
7224                                <t>C: "CREATE EFFECT_INSTANCE LADSPA '/usr/lib/ladspa/mod_delay_1419.so' 'modDelay'"</t>
7225                                <t>S: "OK[0]"</t>
7226                            </list>
7227                        </t>
7228                    </section>
7229    
7230                    <section title="Creating an instance of an effect by its numerical ID" anchor="CREATE EFFECT_INSTANCE (non-portable)">
7231                        <t>The front-end can spawn an instance of the desired
7232                        effect by sending the following command:</t>
7233                        <t>
7234                            <list>
7235                                <t>CREATE EFFECT_INSTANCE &lt;effect-index&gt;</t>
7236                            </list>
7237                        </t>
7238                        <t>Where &lt;effect-index&gt; is the numerical ID of the
7239                        effect as returned by the
7240                        <xref target="LIST AVAILABLE_EFFECTS">"LIST AVAILABLE_EFFECTS"</xref>
7241                        command.</t>
7242    
7243                        <t>The sampler will try to load the requested effect and to
7244                        create an instance of it.</t>
7245    
7246                        <t>Note: Since the numerical ID of a certain effect can
7247                        change at any time, you should not use this command in
7248                        LSCP files to restore a certain effect at a later time! To
7249                        store a sampler session including all its effects, use the
7250                        <xref target="CREATE EFFECT_INSTANCE">portable text-based
7251                        version of "CREATE EFFECT_INSTANCE"</xref> instead! This
7252                        allows to restore a sampler session with all its effects
7253                        also on other machines, possibly even running a completely
7254                        different operating system (e.g. Linux vs. Windows), with
7255                        different plugin directories or plugin DLL names.</t>
7256    
7257                        <t>Possible Answers:</t>
7258                        <t>
7259                            <list>
7260                                <t>"OK[&lt;effect-instance&gt;]" -
7261                                    <list>
7262                                        <t>in case the effect instance was
7263                                        successfully created, where
7264                                        &lt;effect-instance&gt; is the numerical ID
7265                                        of the new effect instance</t>
7266                                    </list>
7267                                </t>
7268                                <t>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
7269                                    <list>
7270                                        <t>in case the effect instance was spawned
7271                                        successfully, but there are noteworthy
7272                                        issue(s) related, providing an appropriate
7273                                        warning code and warning message</t>
7274                                    </list>
7275                                </t>
7276                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
7277                                    <list>
7278                                        <t>if the effect could not be instantiated</t>
7279                                    </list>
7280                                </t>
7281                            </list>
7282                        </t>
7283    
7284                        <t>Examples:</t>
7285                        <t>
7286                            <list>
7287                                <t>C: "CREATE EFFECT_INSTANCE 72"</t>
7288                                <t>S: "OK[5]"</t>
7289                            </list>
7290                        </t>
7291                    </section>
7292    
7293                    <section title="Destroy an effect instance" anchor="DESTROY EFFECT_INSTANCE" lscp_cmd="true">
7294                        <t>The front-end can destroy an unusued effect instance and
7295                        thus freeing it from memory by sending the following command:</t>
7296                        <t>
7297                            <list>
7298                                <t>DESTROY EFFECT_INSTANCE &lt;effect-instance&gt;</t>
7299                            </list>
7300                        </t>
7301                        <t>Where &lt;effect-instance&gt; is the numerical ID of the
7302                        effect instance as returned by the
7303                        <xref target="CREATE EFFECT_INSTANCE">"CREATE EFFECT_INSTANCE"</xref> or
7304                        <xref target="LIST EFFECT_INSTANCES">"LIST EFFECT_INSTANCES"</xref>
7305                        command.</t>
7306    
7307                        <t>The effect instance can only be destroyed if it's not
7308                        used in any part of the sampler's audio signal path anymore.
7309                        If the effect instance is still in use somewhere, trying to
7310                        destroy the effect instance will result in an error
7311                        message.</t>
7312    
7313                        <t>Possible Answers:</t>
7314                        <t>
7315                            <list>
7316                                <t>"OK" -
7317                                    <list>
7318                                        <t>in case the effect instance was successfully destroyed</t>
7319                                    </list>
7320                                </t>
7321                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
7322                                    <list>
7323                                        <t>in case it failed, providing an appropriate error code and
7324                                        error message</t>
7325                                    </list>
7326                                </t>
7327                            </list>
7328                        </t>
7329    
7330                        <t>Examples:</t>
7331                        <t>
7332                            <list>
7333                                <t>C: "DESTROY EFFECT_INSTANCE 5"</t>
7334                                <t>S: "OK"</t>
7335                            </list>
7336                        </t>
7337                    </section>
7338    
7339                    <section title="Retrieve amount of effect instances" anchor="GET EFFECT_INSTANCES" lscp_cmd="true">
7340                        <t>The front-end can retrieve the current amount of effect
7341                        instances by sending the following command:</t>
7342                        <t>
7343                            <list>
7344                                <t>GET EFFECT_INSTANCES</t>
7345                            </list>
7346                        </t>
7347    
7348                        <t>Possible Answers:</t>
7349                        <t>
7350                            <list>
7351                                <t>The sampler will answer by returning the current
7352                                number of effect instances created and not yet
7353                                destroyed in the current sampler session.</t>
7354                            </list>
7355                        </t>
7356    
7357                        <t>Examples:</t>
7358                        <t>
7359                            <list>
7360                                <t>C: "GET EFFECT_INSTANCES"</t>
7361                                <t>S: "14"</t>
7362                            </list>
7363                        </t>
7364                    </section>
7365    
7366                    <section title="Get list of effect instances" anchor="LIST EFFECT_INSTANCES" lscp_cmd="true">
7367                        <t>The front-end can retrieve the current list of effect
7368                        instances by sending the following command:</t>
7369                        <t>
7370                            <list>
7371                                <t>LIST EFFECT_INSTANCES</t>
7372                            </list>
7373                        </t>
7374    
7375                        <t>Possible Answers:</t>
7376                        <t>
7377                            <list>
7378                                <t>The sampler will answer by returning a comma
7379                                separated list with numerical IDs of effects
7380                                instances.
7381                                </t>
7382                            </list>
7383                        </t>
7384                        <t>Example:</t>
7385                        <t>
7386                            <list>
7387                                <t>C: "LIST EFFECT_INSTANCES"</t>
7388                                <t>S: "9,11,14,15,16,17,25"</t>
7389                            </list>
7390                        </t>
7391                    </section>
7392    
7393                    <section title="Retrieving current information about an effect instance" anchor="GET EFFECT_INSTANCE INFO" lscp_cmd="true">
7394                        <t>The front-end can ask for the current information about
7395                        a particular effect instance by sending the following command:</t>
7396                        <t>
7397                            <list>
7398                                <t>GET EFFECT_INSTANCE INFO &lt;effect-instance&gt;</t>
7399                            </list>
7400                        </t>
7401                        <t>Where &lt;effect-instance&gt; is the numerical ID of an
7402                        effect instance as returned by the
7403                        <xref target="CREATE EFFECT_INSTANCE">"CREATE EFFECT_INSTANCE"</xref>
7404                        or
7405                        <xref target="LIST EFFECT_INSTANCES">"LIST EFFECT_INSTANCES"</xref>
7406                        command.</t>
7407    
7408                        <t>Possible Answers:</t>
7409                        <t>
7410                            <list>
7411                                <t>LinuxSampler will answer by sending a &lt;CRLF&gt; separated list.
7412                                Each answer line begins with the information
7413                                category name, followed by a colon and then a space
7414                                character &lt;SP&gt; and finally the info character
7415                                string to that information category. At the
7416                                moment the following categories are defined:</t>
7417                                <t>
7418                                    <list>
7419                                        <t>SYSTEM -
7420                                            <list>
7421                                                <t>name of the effect plugin system
7422                                                the effect is based on
7423                                                (e.g. "LADSPA")</t>
7424                                            </list>
7425                                        </t>
7426                                        <t>MODULE -
7427                                            <list>
7428                                                <t>module of the effect plugin
7429                                                system that contains this effect,
7430                                                the module is usually the
7431                                                dynamic-linked library (DLL)
7432                                                filename of the effect plugin,
7433                                                including full path (note that this
7434                                                filename may contain
7435                                                <xref target="character_set">escape sequences</xref>)</t>
7436                                            </list>
7437                                        </t>
7438                                        <t>NAME -
7439                                            <list>
7440                                                <t>character string defining the
7441                                                unique name of the effect within its
7442                                                module (note that the character
7443                                                string may contain
7444                                                <xref target="character_set">escape sequences</xref>)</t>
7445                                            </list>
7446                                        </t>
7447                                        <t>DESCRIPTION -
7448                                            <list>
7449                                                <t>human readable name of the
7450                                                effect, intended to be displayed in
7451                                                user interfaces (note that the
7452                                                character string may contain
7453                                                <xref target="character_set">escape sequences</xref>)</t>
7454                                            </list>
7455                                        </t>
7456                                        <t>INPUT_CONTROLS -
7457                                            <list>
7458                                                <t>amount of input controls the
7459                                                effect instance provides, to allow
7460                                                controlling the effect parameters in
7461                                                realtime</t>
7462                                            </list>
7463                                        </t>
7464                                    </list>
7465                                </t>
7466                            </list>
7467                        </t>
7468                        <t>The mentioned fields above don't have to be in particular order.</t>
7469    
7470                        <t>Example:</t>
7471                        <t>
7472                            <list>
7473                                <t>C: "GET EFFECT_INSTANCE INFO 3"</t>
7474                                <t>S: "SYSTEM: LADSPA"</t>
7475                                <t>&nbsp;&nbsp;&nbsp;"MODULE: /usr/lib/ladspa/mod_delay_1419.so"</t>
7476                                <t>&nbsp;&nbsp;&nbsp;"NAME: modDelay"</t>
7477                                <t>&nbsp;&nbsp;&nbsp;"DESCRIPTION: Modulatable delay"</t>
7478                                <t>&nbsp;&nbsp;&nbsp;"INPUT_CONTROLS: 1"</t>
7479                                <t>&nbsp;&nbsp;&nbsp;"."</t>
7480                            </list>
7481                        </t>
7482                    </section>
7483    
7484                    <section title="Retrieving information about an effect parameter" anchor="GET EFFECT_INSTANCE_INPUT_CONTROL INFO" lscp_cmd="true">
7485                        <t>Effects typically provide a certain set of effect
7486                        parameters which can be altered by the user in realtime
7487                        (e.g. depth of a reverb effect, duration of a delay effect,
7488                        dry / wet signal ratio). Those controllable effect parameters
7489                        are called "input controls". The front-end can ask for the
7490                        current information of an effect instance's input control
7491                        by sending the following command:</t>
7492                        <t>
7493                            <list>
7494                                <t>GET EFFECT_INSTANCE_INPUT_CONTROL INFO &lt;effect-instance&gt; &lt;input-control&gt;</t>
7495                            </list>
7496                        </t>
7497                        <t>Where &lt;effect-instance&gt; is the numerical ID of an
7498                        effect instance as returned by the
7499                        <xref target="CREATE EFFECT_INSTANCE">"CREATE EFFECT_INSTANCE"</xref>
7500                        or
7501                        <xref target="LIST EFFECT_INSTANCES">"LIST EFFECT_INSTANCES"</xref>
7502                        command and &lt;input-control&gt; is the index of the input
7503                        control within the numerical bounds as returned by the
7504                        "INPUT_CONTROLS" field of the
7505                        <xref target="GET EFFECT_INSTANCE INFO">"GET EFFECT_INSTANCE INFO"</xref>
7506                        command.</t>
7507    
7508                        <t>Possible Answers:</t>
7509                        <t>
7510                            <list>
7511                                <t>LinuxSampler will answer by sending a &lt;CRLF&gt; separated list.
7512                                Each answer line begins with the information
7513                                category name, followed by a colon and then a space
7514                                character &lt;SP&gt; and finally the info character
7515                                string to that information category. There are
7516                                information categories which are always returned,
7517                                independent of the respective effect parameter and
7518                                there are optional information categories
7519                                which are only shown for certain effect parameters.
7520                                At the moment the following categories are defined:</t>
7521                                <t>
7522                                    <list>
7523                                        <t>DESCRIPTION -
7524                                            <list>
7525                                                <t>(always returned)
7526                                                human readable name of the
7527                                                effect parameter, intended to be
7528                                                displayed in user interfaces (note
7529                                                that the character string may
7530                                                contain <xref target="character_set">escape sequences</xref>)</t>
7531                                            </list>
7532                                        </t>
7533                                        <t>VALUE -
7534                                            <list>
7535                                                <t>
7536                                                (always returned)
7537                                                current (optional dotted)
7538                                                floating point value of this effect
7539                                                parameter</t>
7540                                            </list>
7541                                        </t>
7542                                        <t>RANGE_MIN -
7543                                            <list>
7544                                                <t>
7545                                                (optionally returned)
7546                                                minimum allowed value for this
7547                                                effect parameter</t>
7548                                            </list>
7549                                        </t>
7550                                        <t>RANGE_MAX -
7551                                            <list>
7552                                                <t>
7553                                                (optionally returned)
7554                                                maximum allowed value for this
7555                                                effect parameter</t>
7556                                            </list>
7557                                        </t>
7558                                        <t>POSSIBILITIES -
7559                                            <list>
7560                                                <t>
7561                                                (optionally returned)
7562                                                comma separated list of
7563                                                (optional dotted) floating point
7564                                                numbers, reflecting the exact set of
7565                                                possible values for this effect
7566                                                parameter</t>
7567                                            </list>
7568                                        </t>
7569                                        <t>DEFAULT -
7570                                            <list>
7571                                                <t>
7572                                                (optionally returned)
7573                                                default value of this effect
7574                                                parameter</t>
7575                                            </list>
7576                                        </t>
7577                                    </list>
7578                                </t>
7579                            </list>
7580                        </t>
7581                        <t>The mentioned fields above don't have to be in particular order.</t>
7582    
7583                        <t>Example:</t>
7584                        <t>
7585                            <list>
7586                                <t>C: "GET EFFECT_INSTANCE_INPUT_CONTROL INFO 1 0"</t>
7587                                <t>S: "DESCRIPTION: Base delay (s)"</t>
7588                                <t>&nbsp;&nbsp;&nbsp;"VALUE: 0.500"</t>
7589                                <t>&nbsp;&nbsp;&nbsp;"RANGE_MIN: 0.000"</t>
7590                                <t>&nbsp;&nbsp;&nbsp;"."</t>
7591                            </list>
7592                        </t>
7593                    </section>
7594    
7595                    <section title="Altering an effect parameter" anchor="SET EFFECT_INSTANCE_INPUT_CONTROL VALUE" lscp_cmd="true">
7596                        <t>The front-end can alter the current value of an effect
7597                        parameter by sending the following command:</t>
7598                        <t>
7599                            <list>
7600                                <t>SET EFFECT_INSTANCE_INPUT_CONTROL VALUE &lt;effect-instance&gt; &lt;input-control&gt; &lt;value&gt;</t>
7601                            </list>
7602                        </t>
7603                        <t>Where &lt;effect-instance&gt; is the numerical ID of the
7604                        effect instance as returned by the
7605                        <xref target="CREATE EFFECT_INSTANCE">"CREATE EFFECT_INSTANCE"</xref> or
7606                        <xref target="LIST EFFECT_INSTANCES">"LIST EFFECT_INSTANCES"</xref>
7607                        command, &lt;input-control&gt; is the index of the input
7608                        control within the numerical bounds as returned by the
7609                        "INPUT_CONTROLS" field of the
7610                        <xref target="GET EFFECT_INSTANCE INFO">"GET EFFECT_INSTANCE INFO"</xref>
7611                        command and &lt;value&gt; is the new (optional dotted)
7612                        floating point value for this effect parameter.</t>
7613    
7614                        <t>Possible Answers:</t>
7615                        <t>
7616                            <list>
7617                                <t>"OK" -
7618                                    <list>
7619                                        <t>in case the effect was altered successfully</t>
7620                                    </list>
7621                                </t>
7622                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
7623                                    <list>
7624                                        <t>in case it failed, providing an appropriate error code and
7625                                        error message</t>
7626                                    </list>
7627                                </t>
7628                            </list>
7629                        </t>
7630    
7631                        <t>Examples:</t>
7632                        <t>
7633                            <list>
7634                                <t>C: "SET EFFECT_INSTANCE_INPUT_CONTROL VALUE 0 1 0.5"</t>
7635                                <t>S: "OK"</t>
7636                            </list>
7637                        </t>
7638                    </section>
7639    
7640                    <section title="Retrieve amount of send effect chains" anchor="GET SEND_EFFECT_CHAINS" lscp_cmd="true">
7641                        <t>The front-end can retrieve the current amount of send
7642                        effect chains of an audio output device by sending the
7643                        following command:</t>
7644                        <t>
7645                            <list>
7646                                <t>GET SEND_EFFECT_CHAINS &lt;audio-device&gt;</t>
7647                            </list>
7648                        </t>
7649                        <t>Where &lt;audio-device&gt; should be replaced by the
7650                        numerical ID of the audio output device as given by the
7651                        <xref target="CREATE AUDIO_OUTPUT_DEVICE">"CREATE AUDIO_OUTPUT_DEVICE"</xref>
7652                        or <xref target="LIST AUDIO_OUTPUT_DEVICES">"LIST AUDIO_OUTPUT_DEVICES"</xref>
7653                        command.</t>
7654    
7655                        <t>Possible Answers:</t>
7656                        <t>
7657                            <list>
7658                                <t>The sampler will answer by returning the current
7659                                number of send effect chains of the supplied audio
7660                                output device.</t>
7661                            </list>
7662                        </t>
7663    
7664                        <t>Examples:</t>
7665                        <t>
7666                            <list>
7667                                <t>C: "GET SEND_EFFECT_CHAINS 0"</t>
7668                                <t>S: "4"</t>
7669                            </list>
7670                        </t>
7671                    </section>
7672    
7673                    <section title="Retrieve list of send effect chains" anchor="LIST SEND_EFFECT_CHAINS" lscp_cmd="true">
7674                        <t>The front-end can retrieve the current list of send
7675                        effect chains of an audio output device by sending the
7676                        following command:</t>
7677                        <t>
7678                            <list>
7679                                <t>LIST SEND_EFFECT_CHAINS &lt;audio-device&gt;</t>
7680                            </list>
7681                        </t>
7682                        <t>Where &lt;audio-device&gt; should be replaced by the
7683                        numerical ID of the audio output device as given by the
7684                        <xref target="CREATE AUDIO_OUTPUT_DEVICE">"CREATE AUDIO_OUTPUT_DEVICE"</xref>
7685                        or <xref target="LIST AUDIO_OUTPUT_DEVICES">"LIST AUDIO_OUTPUT_DEVICES"</xref>
7686                        command.</t>
7687    
7688                        <t>Possible Answers:</t>
7689                        <t>
7690                            <list>
7691                                <t>The sampler will answer by returning a comma
7692                                separated list with numerical IDs of send effect
7693                                chains of the supplied audio output device.
7694                                </t>
7695                            </list>
7696                        </t>
7697    
7698                        <t>Examples:</t>
7699                        <t>
7700                            <list>
7701                                <t>C: "LIST SEND_EFFECT_CHAINS 0"</t>
7702                                <t>S: "3,4,7"</t>
7703                            </list>
7704                        </t>
7705                    </section>
7706    
7707                    <section title="Add send effect chain" anchor="ADD SEND_EFFECT_CHAIN" lscp_cmd="true">
7708                        <t>The front-end can add a send effect chain by sending the
7709                        following command:</t>
7710                        <t>
7711                            <list>
7712                                <t>ADD SEND_EFFECT_CHAIN &lt;audio-device&gt;</t>
7713                            </list>
7714                        </t>
7715                        <t>Where &lt;audio-device&gt; should be replaced by the
7716                        numerical ID of the audio output device as given by the
7717                        <xref target="CREATE AUDIO_OUTPUT_DEVICE">"CREATE AUDIO_OUTPUT_DEVICE"</xref>
7718                        or <xref target="LIST AUDIO_OUTPUT_DEVICES">"LIST AUDIO_OUTPUT_DEVICES"</xref>
7719                        command.</t>
7720    
7721                        <t>Possible Answers:</t>
7722                        <t>
7723                            <list>
7724                                <t>"OK[&lt;effect-chain&gt;]" -
7725                                    <list>
7726                                        <t>in case the send effect chain was
7727                                        added successfully, where
7728                                        &lt;effect-chain&gt; is the numerical ID
7729                                        of the new send effect chain</t>
7730                                    </list>
7731                                </t>
7732                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
7733                                    <list>
7734                                        <t>if the send effect chain could not be added</t>
7735                                    </list>
7736                                </t>
7737                            </list>
7738                        </t>
7739    
7740                        <t>Examples:</t>
7741                        <t>
7742                            <list>
7743                                <t>C: "ADD SEND_EFFECT_CHAIN 0"</t>
7744                                <t>S: "OK[2]"</t>
7745                            </list>
7746                        </t>
7747                    </section>
7748    
7749                    <section title="Remove send effect chain" anchor="REMOVE SEND_EFFECT_CHAIN" lscp_cmd="true">
7750                        <t>The front-end can remove a send effect chain by sending
7751                        the following command:</t>
7752                        <t>
7753                            <list>
7754                                <t>REMOVE SEND_EFFECT_CHAIN &lt;audio-device&gt; &lt;effect-chain&gt;</t>
7755                            </list>
7756                        </t>
7757                        <t>Where &lt;audio-device&gt; should be replaced by the
7758                        numerical ID of the audio output device as given by the
7759                        <xref target="CREATE AUDIO_OUTPUT_DEVICE">"CREATE AUDIO_OUTPUT_DEVICE"</xref>
7760                        or <xref target="LIST AUDIO_OUTPUT_DEVICES">"LIST AUDIO_OUTPUT_DEVICES"</xref>
7761                        command and &lt;effect-chain&gt; by the numerical ID as
7762                        returned by the
7763                        <xref target="ADD SEND_EFFECT_CHAIN">"ADD SEND_EFFECT_CHAIN"</xref>
7764                        or
7765                        <xref target="LIST SEND_EFFECT_CHAINS">"LIST SEND_EFFECT_CHAINS"</xref>
7766                        command.</t>
7767    
7768                        <t>Possible Answers:</t>
7769                        <t>
7770                            <list>
7771                                <t>"OK" -
7772                                    <list>
7773                                        <t>in case the send effect chain was
7774                                        removed successfully</t>
7775                                    </list>
7776                                </t>
7777                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
7778                                    <list>
7779                                        <t>if the send effect chain could not be removed</t>
7780                                    </list>
7781                                </t>
7782                            </list>
7783                        </t>
7784    
7785                        <t>Examples:</t>
7786                        <t>
7787                            <list>
7788                                <t>C: "REMOVE SEND_EFFECT_CHAIN 0 2"</t>
7789                                <t>S: "OK"</t>
7790                            </list>
7791                        </t>
7792                    </section>
7793    
7794                    <section title="Retrieving information about a send effect chain" anchor="GET SEND_EFFECT_CHAIN INFO" lscp_cmd="true">
7795                        <t>The front-end can ask for information of a send effect
7796                        chain by sending the following command:</t>
7797                        <t>
7798                            <list>
7799                                <t>GET SEND_EFFECT_CHAIN INFO &lt;audio-device&gt; &lt;effect-chain&gt;</t>
7800                            </list>
7801                        </t>
7802                        <t>Where &lt;audio-device&gt; should be replaced by the
7803                        numerical ID of the audio output device as given by the
7804                        <xref target="CREATE AUDIO_OUTPUT_DEVICE">"CREATE AUDIO_OUTPUT_DEVICE"</xref>
7805                        or <xref target="LIST AUDIO_OUTPUT_DEVICES">"LIST AUDIO_OUTPUT_DEVICES"</xref>
7806                        command and &lt;effect-chain&gt; by the numerical ID as
7807                        returned by the
7808                        <xref target="ADD SEND_EFFECT_CHAIN">"ADD SEND_EFFECT_CHAIN"</xref>
7809                        or
7810                        <xref target="LIST SEND_EFFECT_CHAINS">"LIST SEND_EFFECT_CHAINS"</xref>
7811                        command.</t>
7812    
7813                        <t>Possible Answers:</t>
7814                        <t>
7815                            <list>
7816                                <t>LinuxSampler will answer by sending a &lt;CRLF&gt; separated list.
7817                                Each answer line begins with the information
7818                                category name, followed by a colon and then a space
7819                                character &lt;SP&gt; and finally the info character
7820                                string to that information category.
7821                                At the moment the following categories are defined:</t>
7822                                <t>
7823                                    <list>
7824                                        <t>EFFECT_COUNT -
7825                                            <list>
7826                                                <t>amount of effects in this send
7827                                                effect chain</t>
7828                                            </list>
7829                                        </t>
7830                                        <t>EFFECT_SEQUENCE -
7831                                            <list>
7832                                                <t>comma separated list of the
7833                                                numerical IDs of the effect
7834                                                instances in this send effect chain,
7835                                                in the order as they are procssed in
7836                                                the effect chain</t>
7837                                            </list>
7838                                        </t>
7839                                    </list>
7840                                </t>
7841                            </list>
7842                        </t>
7843                        <t>The mentioned fields above don't have to be in particular order.</t>
7844    
7845                        <t>Example:</t>
7846                        <t>
7847                            <list>
7848                                <t>C: "GET SEND_EFFECT_CHAIN INFO 0 2"</t>
7849                                <t>S: "EFFECT_COUNT: 3"</t>
7850                                <t>&nbsp;&nbsp;&nbsp;"EFFECT_SEQUENCE: 31,4,7"</t>
7851                                <t>&nbsp;&nbsp;&nbsp;"."</t>
7852                            </list>
7853                        </t>
7854                    </section>
7855    
7856                    <section title="Append effect instance to a send effect chain" anchor="APPEND SEND_EFFECT_CHAIN EFFECT" lscp_cmd="true">
7857                        <t>The front-end can add an unused effect instance to the
7858                        end of a send effect chain by sending the following command:</t>
7859                        <t>
7860                            <list>
7861                                <t>APPEND SEND_EFFECT_CHAIN EFFECT &lt;audio-device&gt; &lt;effect-chain&gt; &lt;effect-instance&gt;</t>
7862                            </list>
7863                        </t>
7864                        <t>Where &lt;audio-device&gt; should be replaced by the
7865                        numerical ID of the audio output device as given by the
7866                        <xref target="CREATE AUDIO_OUTPUT_DEVICE">"CREATE AUDIO_OUTPUT_DEVICE"</xref>
7867                        or <xref target="LIST AUDIO_OUTPUT_DEVICES">"LIST AUDIO_OUTPUT_DEVICES"</xref>
7868                        command and &lt;effect-chain&gt; by the numerical ID as
7869                        returned by the
7870                        <xref target="ADD SEND_EFFECT_CHAIN">"ADD SEND_EFFECT_CHAIN"</xref>
7871                        or
7872                        <xref target="LIST SEND_EFFECT_CHAINS">"LIST SEND_EFFECT_CHAINS"</xref>
7873                        command and &lt;effect-instance&gt; as returned by the
7874                        <xref target="CREATE EFFECT_INSTANCE">"CREATE EFFECT_INSTANCE"</xref> or
7875                        <xref target="LIST EFFECT_INSTANCES">"LIST EFFECT_INSTANCES"</xref>
7876                        command.</t>
7877                        <t>Only unused effect instances can be added to the effect
7878                        chain. Trying to add an effect instance which is already in
7879                        use somewhere in the audio signal path of the sampler will
7880                        result in an error.</t>
7881    
7882                        <t>Possible Answers:</t>
7883                        <t>
7884                            <list>
7885                                <t>"OK" -
7886                                    <list>
7887                                        <t>in case the effect instance was
7888                                        added successfully to the chain</t>
7889                                    </list>
7890                                </t>
7891                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
7892                                    <list>
7893                                        <t>if the effect instance could not be added</t>
7894                                    </list>
7895                                </t>
7896                            </list>
7897                        </t>
7898    
7899                        <t>Examples:</t>
7900                        <t>
7901                            <list>
7902                                <t>C: "APPEND SEND_EFFECT_CHAIN EFFECT 0 2 38"</t>
7903                                <t>S: "OK"</t>
7904                            </list>
7905                        </t>
7906                    </section>
7907    
7908                    <section title="Insert effect instance to a send effect chain" anchor="INSERT SEND_EFFECT_CHAIN EFFECT" lscp_cmd="true">
7909                        <t>The front-end can add an unused effect instance to a
7910                        certain position of a send effect chain by sending the
7911                        following command:</t>
7912                        <t>
7913                            <list>
7914                                <t>INSERT SEND_EFFECT_CHAIN EFFECT &lt;audio-device&gt; &lt;effect-chain&gt; &lt;chain-pos&gt; &lt;effect-instance&gt;</t>
7915                            </list>
7916                        </t>
7917                        <t>Where &lt;audio-device&gt; should be replaced by the
7918                        numerical ID of the audio output device as given by the
7919                        <xref target="CREATE AUDIO_OUTPUT_DEVICE">"CREATE AUDIO_OUTPUT_DEVICE"</xref>
7920                        or <xref target="LIST AUDIO_OUTPUT_DEVICES">"LIST AUDIO_OUTPUT_DEVICES"</xref>
7921                        command, &lt;effect-chain&gt; by the numerical ID as
7922                        returned by the
7923                        <xref target="ADD SEND_EFFECT_CHAIN">"ADD SEND_EFFECT_CHAIN"</xref>
7924                        or
7925                        <xref target="LIST SEND_EFFECT_CHAINS">"LIST SEND_EFFECT_CHAINS"</xref>
7926                        command, &lt;effect-instance&gt; as returned by the
7927                        <xref target="CREATE EFFECT_INSTANCE">"CREATE EFFECT_INSTANCE"</xref> or
7928                        <xref target="LIST EFFECT_INSTANCES">"LIST EFFECT_INSTANCES"</xref>
7929                        command and &lt;chain-pos&gt; the exact position of the
7930                        effect chain where the supplied effect shall be inserted
7931                        to.</t>
7932                        <t>Only unused effect instances can be added to the effect
7933                        chain. Trying to add an effect instance which is already in
7934                        use somewhere in the audio signal path of the sampler will
7935                        result in an error.</t>
7936    
7937                        <t>Possible Answers:</t>
7938                        <t>
7939                            <list>
7940                                <t>"OK" -
7941                                    <list>
7942                                        <t>in case the effect instance was
7943                                        added successfully to the chain</t>
7944                                    </list>
7945                                </t>
7946                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
7947                                    <list>
7948                                        <t>if the effect instance could not be added</t>
7949                                    </list>
7950                                </t>
7951                            </list>
7952                        </t>
7953    
7954                        <t>Examples:</t>
7955                        <t>
7956                            <list>
7957                                <t>C: "INSERT SEND_EFFECT_CHAIN EFFECT 0 2 4 38"</t>
7958                                <t>S: "OK"</t>
7959                            </list>
7960                        </t>
7961                    </section>
7962    
7963                    <section title="Remove effect instance from send effect chain" anchor="REMOVE SEND_EFFECT_CHAIN EFFECT" lscp_cmd="true">
7964                        <t>The front-end can remove an effect instance from a
7965                        certain position of a send effect chain by sending the
7966                        following command:</t>
7967                        <t>
7968                            <list>
7969                                <t>REMOVE SEND_EFFECT_CHAIN EFFECT &lt;audio-device&gt; &lt;effect-chain&gt; &lt;chain-pos&gt;</t>
7970                            </list>
7971                        </t>
7972                        <t>Where &lt;audio-device&gt; should be replaced by the
7973                        numerical ID of the audio output device as given by the
7974                        <xref target="CREATE AUDIO_OUTPUT_DEVICE">"CREATE AUDIO_OUTPUT_DEVICE"</xref>
7975                        or <xref target="LIST AUDIO_OUTPUT_DEVICES">"LIST AUDIO_OUTPUT_DEVICES"</xref>
7976                        command, &lt;effect-chain&gt; by the numerical ID as
7977                        returned by the
7978                        <xref target="ADD SEND_EFFECT_CHAIN">"ADD SEND_EFFECT_CHAIN"</xref>
7979                        or
7980                        <xref target="LIST SEND_EFFECT_CHAINS">"LIST SEND_EFFECT_CHAINS"</xref>
7981                        command and &lt;chain-pos&gt; the exact position of the
7982                        effect instance to be removed from the effect chain.</t>
7983    
7984                        <t>Possible Answers:</t>
7985                        <t>
7986                            <list>
7987                                <t>"OK" -
7988                                    <list>
7989                                        <t>in case the effect instance was
7990                                        removed successfully</t>
7991                                    </list>
7992                                </t>
7993                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
7994                                    <list>
7995                                        <t>if the effect instance could not be removed</t>
7996                                    </list>
7997                                </t>
7998                            </list>
7999                        </t>
8000    
8001                        <t>Examples:</t>
8002                        <t>
8003                            <list>
8004                                <t>C: "REMOVE SEND_EFFECT_CHAIN EFFECT 0 2 4"</t>
8005                                <t>S: "OK"</t>
8006                            </list>
8007                        </t>
8008                    </section>
8009    
8010                </section>
8011            </section>
8012    
8013          <section title="Command Syntax" anchor="command_syntax">          <section title="Command Syntax" anchor="command_syntax">
8014              <t>The grammar of the control protocol as descibed in <xref target="control_commands"/>              <t>The grammar of the control protocol as descibed in <xref target="control_commands"/>
# Line 4229  Schoenebeck'> Line 8024  Schoenebeck'>
8024    
8025  <t>input =  <t>input =
8026          <list>          <list>
8027                  <t>line LF                  <t>line
8028                  </t>                  </t>
8029                  <t>/ line CR LF                  <t>/ error
8030                  </t>                  </t>
8031          </list>          </list>
8032  </t>  </t>
8033  <t>line =  <t>line =
8034          <list>          <list>
8035                  <t>/* epsilon (empty line ignored) */                  <t>statement LF
8036                    </t>
8037                    <t>/ statement CR LF
8038                    </t>
8039            </list>
8040    </t>
8041    <t>statement =
8042            <list>
8043                    <t>/* epsilon (empty statement/line ignored) */
8044                  </t>                  </t>
8045                  <t>/ comment                  <t>/ comment
8046                  </t>                  </t>
8047                  <t>/ command                  <t>/ command
8048                  </t>                  </t>
                 <t>/ error  
                 </t>  
8049          </list>          </list>
8050  </t>  </t>
8051  <t>comment =  <t>comment =
# Line 4287  Schoenebeck'> Line 8088  Schoenebeck'>
8088                  </t>                  </t>
8089                  <t>/ UNSUBSCRIBE SP unsubscribe_event                  <t>/ UNSUBSCRIBE SP unsubscribe_event
8090                  </t>                  </t>
                 <t>/ SELECT SP text  
                 </t>  
8091                  <t>/ RESET SP reset_instruction                  <t>/ RESET SP reset_instruction
8092                  </t>                  </t>
8093                  <t>/ CLEAR SP clear_instruction                  <t>/ CLEAR SP clear_instruction
8094                  </t>                  </t>
8095                    <t>/ FIND SP find_instruction
8096                    </t>
8097                    <t>/ MOVE SP move_instruction
8098                    </t>
8099                    <t>/ COPY SP copy_instruction
8100                    </t>
8101                    <t>/ EDIT SP edit_instruction
8102                    </t>
8103                    <t>/ FORMAT SP format_instruction
8104                    </t>
8105                    <t>/ SEND SP send_instruction
8106                    </t>
8107                    <t>/ APPEND SP append_instruction
8108                    </t>
8109                    <t>/ INSERT SP insert_instruction
8110                    </t>
8111                  <t>/ RESET                  <t>/ RESET
8112                  </t>                  </t>
8113                  <t>/ QUIT                  <t>/ QUIT
# Line 4303  Schoenebeck'> Line 8118  Schoenebeck'>
8118          <list>          <list>
8119                  <t>CHANNEL                  <t>CHANNEL
8120                  </t>                  </t>
8121                    <t>/ CHANNEL SP MIDI_INPUT SP sampler_channel SP device_index
8122                    </t>
8123                    <t>/ CHANNEL SP MIDI_INPUT SP sampler_channel SP device_index SP midi_input_port_index
8124                    </t>
8125                    <t>/ DB_INSTRUMENT_DIRECTORY SP db_path
8126                    </t>
8127                    <t>/ DB_INSTRUMENTS SP NON_MODAL SP scan_mode SP db_path SP filename
8128                    </t>
8129                    <t>/ DB_INSTRUMENTS SP NON_MODAL SP scan_mode SP FILE_AS_DIR SP db_path SP filename
8130                    </t>
8131                    <t>/ DB_INSTRUMENTS SP scan_mode SP db_path SP filename
8132                    </t>
8133                    <t>/ DB_INSTRUMENTS SP scan_mode SP FILE_AS_DIR SP db_path SP filename
8134                    </t>
8135                    <t>/ DB_INSTRUMENTS SP NON_MODAL SP db_path SP filename
8136                    </t>
8137                    <t>/ DB_INSTRUMENTS SP NON_MODAL SP db_path SP filename SP instrument_index
8138                    </t>
8139                    <t>/ DB_INSTRUMENTS SP db_path SP filename
8140                    </t>
8141                    <t>/ DB_INSTRUMENTS SP db_path SP filename SP instrument_index
8142                    </t>
8143                  <t>/ MIDI_INSTRUMENT_MAP                  <t>/ MIDI_INSTRUMENT_MAP
8144                  </t>                  </t>
8145                  <t>/ MIDI_INSTRUMENT_MAP SP map_name                  <t>/ MIDI_INSTRUMENT_MAP SP map_name
8146                  </t>                  </t>
8147                    <t>/ SEND_EFFECT_CHAIN SP device_index
8148                    </t>
8149          </list>          </list>
8150  </t>  </t>
8151  <t>subscribe_event =  <t>subscribe_event =
8152          <list>          <list>
8153                  <t>CHANNEL_COUNT                  <t>AUDIO_OUTPUT_DEVICE_COUNT
8154                    </t>
8155                    <t>/ AUDIO_OUTPUT_DEVICE_INFO
8156                    </t>
8157                    <t>/ MIDI_INPUT_DEVICE_COUNT
8158                    </t>
8159                    <t>/ MIDI_INPUT_DEVICE_INFO
8160                    </t>
8161                    <t>/ CHANNEL_COUNT
8162                    </t>
8163                    <t>/ CHANNEL_MIDI
8164                    </t>
8165                    <t>/ DEVICE_MIDI
8166                  </t>                  </t>
8167                  <t>/ VOICE_COUNT                  <t>/ VOICE_COUNT
8168                  </t>                  </t>
# Line 4321  Schoenebeck'> Line 8172  Schoenebeck'>
8172                  </t>                  </t>
8173                  <t>/ CHANNEL_INFO                  <t>/ CHANNEL_INFO
8174                  </t>                  </t>
8175                    <t>/ FX_SEND_COUNT
8176                    </t>
8177                    <t>/ FX_SEND_INFO
8178                    </t>
8179                    <t>/ MIDI_INSTRUMENT_MAP_COUNT
8180                    </t>
8181                    <t>/ MIDI_INSTRUMENT_MAP_INFO
8182                    </t>
8183                    <t>/ MIDI_INSTRUMENT_COUNT
8184                    </t>
8185                    <t>/ MIDI_INSTRUMENT_INFO
8186                    </t>
8187                    <t>/ DB_INSTRUMENT_DIRECTORY_COUNT
8188                    </t>
8189                    <t>/ DB_INSTRUMENT_DIRECTORY_INFO
8190                    </t>
8191                    <t>/ DB_INSTRUMENT_COUNT
8192                    </t>
8193                    <t>/ DB_INSTRUMENT_INFO
8194                    </t>
8195                    <t>/ DB_INSTRUMENTS_JOB_INFO
8196                    </t>
8197                  <t>/ MISCELLANEOUS                  <t>/ MISCELLANEOUS
8198                  </t>                  </t>
8199                    <t>/ TOTAL_STREAM_COUNT
8200                    </t>
8201                  <t>/ TOTAL_VOICE_COUNT                  <t>/ TOTAL_VOICE_COUNT
8202                  </t>                  </t>
8203                    <t>/ GLOBAL_INFO
8204                    </t>
8205                    <t>/ EFFECT_INSTANCE_COUNT
8206                    </t>
8207                    <t>/ EFFECT_INSTANCE_INFO
8208                    </t>
8209                    <t>/ SEND_EFFECT_CHAIN_COUNT
8210                    </t>
8211                    <t>/ SEND_EFFECT_CHAIN_INFO
8212                    </t>
8213          </list>          </list>
8214  </t>  </t>
8215  <t>unsubscribe_event =  <t>unsubscribe_event =
8216          <list>          <list>
8217                  <t>CHANNEL_COUNT                  <t>AUDIO_OUTPUT_DEVICE_COUNT
8218                    </t>
8219                    <t>/ AUDIO_OUTPUT_DEVICE_INFO
8220                    </t>
8221                    <t>/ MIDI_INPUT_DEVICE_COUNT
8222                    </t>
8223                    <t>/ MIDI_INPUT_DEVICE_INFO
8224                    </t>
8225                    <t>/ CHANNEL_COUNT
8226                    </t>
8227                    <t>/ CHANNEL_MIDI
8228                    </t>
8229                    <t>/ DEVICE_MIDI
8230                  </t>                  </t>
8231                  <t>/ VOICE_COUNT                  <t>/ VOICE_COUNT
8232                  </t>                  </t>
# Line 4339  Schoenebeck'> Line 8236  Schoenebeck'>
8236                  </t>                  </t>
8237                  <t>/ CHANNEL_INFO                  <t>/ CHANNEL_INFO
8238                  </t>                  </t>
8239                    <t>/ FX_SEND_COUNT
8240                    </t>
8241                    <t>/ FX_SEND_INFO
8242                    </t>
8243                    <t>/ MIDI_INSTRUMENT_MAP_COUNT
8244                    </t>
8245                    <t>/ MIDI_INSTRUMENT_MAP_INFO
8246                    </t>
8247                    <t>/ MIDI_INSTRUMENT_COUNT
8248                    </t>
8249                    <t>/ MIDI_INSTRUMENT_INFO
8250                    </t>
8251                    <t>/ DB_INSTRUMENT_DIRECTORY_COUNT
8252                    </t>
8253                    <t>/ DB_INSTRUMENT_DIRECTORY_INFO
8254                    </t>
8255                    <t>/ DB_INSTRUMENT_COUNT
8256                    </t>
8257                    <t>/ DB_INSTRUMENT_INFO
8258                    </t>
8259                    <t>/ DB_INSTRUMENTS_JOB_INFO
8260                    </t>
8261                  <t>/ MISCELLANEOUS                  <t>/ MISCELLANEOUS
8262                  </t>                  </t>
8263                    <t>/ TOTAL_STREAM_COUNT
8264                    </t>
8265                  <t>/ TOTAL_VOICE_COUNT                  <t>/ TOTAL_VOICE_COUNT
8266                  </t>                  </t>
8267                    <t>/ GLOBAL_INFO
8268                    </t>
8269                    <t>/ EFFECT_INSTANCE_COUNT
8270                    </t>
8271                    <t>/ EFFECT_INSTANCE_INFO
8272                    </t>
8273                    <t>/ SEND_EFFECT_CHAIN_COUNT
8274                    </t>
8275                    <t>/ SEND_EFFECT_CHAIN_INFO
8276                    </t>
8277          </list>          </list>
8278  </t>  </t>
8279  <t>map_instruction =  <t>map_instruction =
8280          <list>          <list>
8281                  <t>MIDI_INSTRUMENT SP midi_map SP midi_bank SP midi_prog SP engine_name SP filename SP instrument_index SP volume_value                  <t>MIDI_INSTRUMENT SP modal_arg midi_map SP midi_bank SP midi_prog SP engine_name SP filename SP instrument_index SP volume_value
8282                  </t>                  </t>
8283                  <t>/ MIDI_INSTRUMENT SP midi_map SP midi_bank SP midi_prog SP engine_name SP filename SP instrument_index SP volume_value SP instr_load_mode                  <t>/ MIDI_INSTRUMENT SP modal_arg midi_map SP midi_bank SP midi_prog SP engine_name SP filename SP instrument_index SP volume_value SP instr_load_mode
8284                  </t>                  </t>
8285                  <t>/ MIDI_INSTRUMENT SP midi_map SP midi_bank SP midi_prog SP engine_name SP filename SP instrument_index SP volume_value SP entry_name                  <t>/ MIDI_INSTRUMENT SP modal_arg midi_map SP midi_bank SP midi_prog SP engine_name SP filename SP instrument_index SP volume_value SP entry_name
8286                  </t>                  </t>
8287                  <t>/ MIDI_INSTRUMENT SP midi_map SP midi_bank SP midi_prog SP engine_name SP filename SP instrument_index SP volume_value SP instr_load_mode SP entry_name                  <t>/ MIDI_INSTRUMENT SP modal_arg midi_map SP midi_bank SP midi_prog SP engine_name SP filename SP instrument_index SP volume_value SP instr_load_mode SP entry_name
8288                  </t>                  </t>
8289          </list>          </list>
8290  </t>  </t>
# Line 4367  Schoenebeck'> Line 8298  Schoenebeck'>
8298          <list>          <list>
8299                  <t>CHANNEL SP sampler_channel                  <t>CHANNEL SP sampler_channel
8300                  </t>                  </t>
8301                    <t>/ CHANNEL SP MIDI_INPUT SP sampler_channel
8302                    </t>
8303                    <t>/ CHANNEL SP MIDI_INPUT SP sampler_channel SP device_index
8304                    </t>
8305                    <t>/ CHANNEL SP MIDI_INPUT SP sampler_channel SP device_index SP midi_input_port_index
8306                    </t>
8307                  <t>/ MIDI_INSTRUMENT_MAP SP midi_map                  <t>/ MIDI_INSTRUMENT_MAP SP midi_map
8308                  </t>                  </t>
8309                  <t>/ MIDI_INSTRUMENT_MAP SP ALL                  <t>/ MIDI_INSTRUMENT_MAP SP ALL
8310                  </t>                  </t>
8311                    <t>/ SEND_EFFECT_CHAIN SP device_index SP effect_chain
8312                    </t>
8313                    <t>/ SEND_EFFECT_CHAIN SP EFFECT SP device_index SP effect_chain SP chain_pos
8314                    </t>
8315                    <t>/ FX_SEND SP EFFECT SP sampler_channel SP fx_send_id
8316                    </t>
8317                    <t>/ DB_INSTRUMENT_DIRECTORY SP FORCE SP db_path
8318                    </t>
8319                    <t>/ DB_INSTRUMENT_DIRECTORY SP db_path
8320                    </t>
8321                    <t>/ DB_INSTRUMENT SP db_path
8322                    </t>
8323          </list>          </list>
8324  </t>  </t>
8325  <t>get_instruction =  <t>get_instruction =
8326          <list>          <list>
8327                  <t>AVAILABLE_ENGINES                  <t>AVAILABLE_ENGINES
8328                  </t>                  </t>
8329                    <t>/ AVAILABLE_EFFECTS
8330                    </t>
8331                    <t>/ EFFECT_INSTANCES
8332                    </t>
8333                    <t>/ EFFECT SP INFO SP effect_index
8334                    </t>
8335                    <t>/ EFFECT_INSTANCE SP INFO SP effect_instance
8336                    </t>
8337                    <t>/ EFFECT_INSTANCE_INPUT_CONTROL SP INFO SP effect_instance SP input_control
8338                    </t>
8339                    <t>/ SEND_EFFECT_CHAINS SP device_index
8340                    </t>
8341                    <t>/ SEND_EFFECT_CHAIN SP INFO SP device_index SP effect_chain
8342                    </t>
8343                  <t>/ AVAILABLE_MIDI_INPUT_DRIVERS                  <t>/ AVAILABLE_MIDI_INPUT_DRIVERS
8344                  </t>                  </t>
8345                  <t>/ MIDI_INPUT_DRIVER SP INFO SP string                  <t>/ MIDI_INPUT_DRIVER SP INFO SP string
# Line 4423  Schoenebeck'> Line 8386  Schoenebeck'>
8386                  </t>                  </t>
8387                  <t>/ SERVER SP INFO                  <t>/ SERVER SP INFO
8388                  </t>                  </t>
8389                    <t>/ TOTAL_STREAM_COUNT
8390                    </t>
8391                  <t>/ TOTAL_VOICE_COUNT                  <t>/ TOTAL_VOICE_COUNT
8392                  </t>                  </t>
8393                  <t>/ TOTAL_VOICE_COUNT_MAX                  <t>/ TOTAL_VOICE_COUNT_MAX
# Line 4437  Schoenebeck'> Line 8402  Schoenebeck'>
8402                  </t>                  </t>
8403                  <t>/ MIDI_INSTRUMENT_MAP SP INFO SP midi_map                  <t>/ MIDI_INSTRUMENT_MAP SP INFO SP midi_map
8404                  </t>                  </t>
8405                    <t>/ FX_SENDS SP sampler_channel
8406                    </t>
8407                    <t>/ FX_SEND SP INFO SP sampler_channel SP fx_send_id
8408                    </t>
8409                    <t>/ DB_INSTRUMENT_DIRECTORIES SP RECURSIVE SP db_path
8410                    </t>
8411                    <t>/ DB_INSTRUMENT_DIRECTORIES SP db_path
8412                    </t>
8413                    <t>/ DB_INSTRUMENT_DIRECTORY SP INFO SP db_path
8414                    </t>
8415                    <t>/ DB_INSTRUMENTS SP RECURSIVE SP db_path
8416                    </t>
8417                    <t>/ DB_INSTRUMENTS SP db_path
8418                    </t>
8419                    <t>/ DB_INSTRUMENT SP INFO SP db_path
8420                    </t>
8421                    <t>/ DB_INSTRUMENTS_JOB SP INFO SP number
8422                    </t>
8423                    <t>/ VOLUME
8424                    </t>
8425                    <t>/ VOICES
8426                    </t>
8427                    <t>/ STREAMS
8428                    </t>
8429                    <t>/ FILE SP INSTRUMENTS SP filename
8430                    </t>
8431                    <t>/ FILE SP INSTRUMENT SP INFO SP filename SP instrument_index
8432                    </t>
8433          </list>          </list>
8434  </t>  </t>
8435  <t>set_instruction =  <t>set_instruction =
# Line 4447  Schoenebeck'> Line 8440  Schoenebeck'>
8440                  </t>                  </t>
8441                  <t>/ MIDI_INPUT_DEVICE_PARAMETER SP number SP string '=' param_val_list                  <t>/ MIDI_INPUT_DEVICE_PARAMETER SP number SP string '=' param_val_list
8442                  </t>                  </t>
8443                    <t>/ MIDI_INPUT_PORT_PARAMETER SP number SP number SP string '=' NONE
8444                    </t>
8445                  <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
8446                  </t>                  </t>
8447                    <t>/ EFFECT_INSTANCE_INPUT_CONTROL SP VALUE SP effect_instance SP input_control SP control_value
8448                    </t>
8449                  <t>/ CHANNEL SP set_chan_instruction                  <t>/ CHANNEL SP set_chan_instruction
8450                  </t>                  </t>
8451                  <t>/ MIDI_INSTRUMENT_MAP SP NAME SP midi_map SP map_name                  <t>/ MIDI_INSTRUMENT_MAP SP NAME SP midi_map SP map_name
8452                  </t>                  </t>
8453                    <t>/ FX_SEND SP NAME SP sampler_channel SP fx_send_id SP fx_send_name
8454                    </t>
8455                    <t>/ FX_SEND SP AUDIO_OUTPUT_CHANNEL SP sampler_channel SP fx_send_id SP audio_channel_index SP audio_channel_index
8456                    </t>
8457                    <t>/ FX_SEND SP MIDI_CONTROLLER SP sampler_channel SP fx_send_id SP midi_ctrl
8458                    </t>
8459                    <t>/ FX_SEND SP LEVEL SP sampler_channel SP fx_send_id SP volume_value
8460                    </t>
8461                    <t>/ FX_SEND SP EFFECT SP sampler_channel SP fx_send_id SP effect_chain SP chain_pos
8462                    </t>
8463                    <t>/ DB_INSTRUMENT_DIRECTORY SP NAME SP db_path SP stringval_escaped
8464                    </t>
8465                    <t>/ DB_INSTRUMENT_DIRECTORY SP DESCRIPTION SP db_path SP stringval_escaped
8466                    </t>
8467                    <t>/ DB_INSTRUMENT SP NAME SP db_path SP stringval_escaped
8468                    </t>
8469                    <t>/ DB_INSTRUMENT SP DESCRIPTION SP db_path SP stringval_escaped
8470                    </t>
8471                    <t>/ DB_INSTRUMENT SP FILE_PATH SP filename SP filename
8472                    </t>
8473                  <t>/ ECHO SP boolean                  <t>/ ECHO SP boolean
8474                  </t>                  </t>
8475                    <t>/ SHELL SP INTERACT SP boolean
8476                    </t>
8477                    <t>/ SHELL SP AUTO_CORRECT SP boolean
8478                    </t>
8479                    <t>/ SHELL SP DOC SP boolean
8480                    </t>
8481                    <t>/ VOLUME SP volume_value
8482                    </t>
8483                    <t>/ VOICES SP number
8484                    </t>
8485                    <t>/ STREAMS SP number
8486                    </t>
8487          </list>          </list>
8488  </t>  </t>
8489  <t>create_instruction =  <t>create_instruction =
# Line 4467  Schoenebeck'> Line 8496  Schoenebeck'>
8496                  </t>                  </t>
8497                  <t>/ MIDI_INPUT_DEVICE SP string                  <t>/ MIDI_INPUT_DEVICE SP string
8498                  </t>                  </t>
8499                    <t>/ FX_SEND SP sampler_channel SP midi_ctrl
8500                    </t>
8501                    <t>/ FX_SEND SP sampler_channel SP midi_ctrl SP fx_send_name
8502                    </t>
8503                    <t>/ EFFECT_INSTANCE SP effect_index
8504                    </t>
8505                    <t>/ EFFECT_INSTANCE SP effect_system SP module SP effect_name
8506                    </t>
8507          </list>          </list>
8508  </t>  </t>
8509  <t>reset_instruction =  <t>reset_instruction =
# Line 4483  Schoenebeck'> Line 8520  Schoenebeck'>
8520                  </t>                  </t>
8521          </list>          </list>
8522  </t>  </t>
8523    <t>find_instruction =
8524            <list>
8525                    <t>DB_INSTRUMENTS SP NON_RECURSIVE SP db_path SP query_val_list
8526                    </t>
8527                    <t>/ DB_INSTRUMENTS SP db_path SP query_val_list
8528                    </t>
8529                    <t>/ DB_INSTRUMENT_DIRECTORIES SP NON_RECURSIVE SP db_path SP query_val_list
8530                    </t>
8531                    <t>/ DB_INSTRUMENT_DIRECTORIES SP db_path SP query_val_list
8532                    </t>
8533                    <t>/ LOST SP DB_INSTRUMENT_FILES
8534                    </t>
8535            </list>
8536    </t>
8537    <t>move_instruction =
8538            <list>
8539                    <t>DB_INSTRUMENT_DIRECTORY SP db_path SP db_path
8540                    </t>
8541                    <t>/ DB_INSTRUMENT SP db_path SP db_path
8542                    </t>
8543            </list>
8544    </t>
8545    <t>copy_instruction =
8546            <list>
8547                    <t>DB_INSTRUMENT_DIRECTORY SP db_path SP db_path
8548                    </t>
8549                    <t>/ DB_INSTRUMENT SP db_path SP db_path
8550                    </t>
8551            </list>
8552    </t>
8553  <t>destroy_instruction =  <t>destroy_instruction =
8554          <list>          <list>
8555                  <t>AUDIO_OUTPUT_DEVICE SP number                  <t>AUDIO_OUTPUT_DEVICE SP number
8556                  </t>                  </t>
8557                  <t>/ MIDI_INPUT_DEVICE SP number                  <t>/ MIDI_INPUT_DEVICE SP number
8558                  </t>                  </t>
8559                    <t>/ FX_SEND SP sampler_channel SP fx_send_id
8560                    </t>
8561                    <t>/ EFFECT_INSTANCE SP number
8562                    </t>
8563          </list>          </list>
8564  </t>  </t>
8565  <t>load_instruction =  <t>load_instruction =
# Line 4499  Schoenebeck'> Line 8570  Schoenebeck'>
8570                  </t>                  </t>
8571          </list>          </list>
8572  </t>  </t>
8573    <t>append_instruction =
8574            <list>
8575                    <t>SEND_EFFECT_CHAIN SP EFFECT SP device_index SP effect_chain SP effect_instance
8576                    </t>
8577            </list>
8578    </t>
8579    <t>insert_instruction =
8580            <list>
8581                    <t>SEND_EFFECT_CHAIN SP EFFECT SP device_index SP effect_chain SP chain_pos SP effect_instance
8582                    </t>
8583            </list>
8584    </t>
8585  <t>set_chan_instruction =  <t>set_chan_instruction =
8586          <list>          <list>
8587                  <t>AUDIO_OUTPUT_DEVICE SP sampler_channel SP device_index                  <t>AUDIO_OUTPUT_DEVICE SP sampler_channel SP device_index
# Line 4531  Schoenebeck'> Line 8614  Schoenebeck'>
8614                  </t>                  </t>
8615          </list>          </list>
8616  </t>  </t>
8617    <t>edit_instruction =
8618            <list>
8619                    <t>CHANNEL SP INSTRUMENT SP sampler_channel
8620                    </t>
8621            </list>
8622    </t>
8623    <t>format_instruction =
8624            <list>
8625                    <t>INSTRUMENTS_DB
8626                    </t>
8627            </list>
8628    </t>
8629    <t>modal_arg =
8630            <list>
8631                    <t>/* epsilon (empty argument) */
8632                    </t>
8633                    <t>/ NON_MODAL SP
8634                    </t>
8635            </list>
8636    </t>
8637  <t>key_val_list =  <t>key_val_list =
8638          <list>          <list>
8639                  <t>string '=' param_val_list                  <t>string '=' param_val_list
# Line 4555  Schoenebeck'> Line 8658  Schoenebeck'>
8658                  </t>                  </t>
8659                  <t>/ CHANNELS                  <t>/ CHANNELS
8660                  </t>                  </t>
8661                    <t>/ CHANNEL SP MIDI_INPUTS SP sampler_channel
8662                    </t>
8663                  <t>/ AVAILABLE_ENGINES                  <t>/ AVAILABLE_ENGINES
8664                  </t>                  </t>
8665                    <t>/ AVAILABLE_EFFECTS
8666                    </t>
8667                    <t>/ EFFECT_INSTANCES
8668                    </t>
8669                    <t>/ SEND_EFFECT_CHAINS SP number
8670                    </t>
8671                  <t>/ AVAILABLE_MIDI_INPUT_DRIVERS                  <t>/ AVAILABLE_MIDI_INPUT_DRIVERS
8672                  </t>                  </t>
8673                  <t>/ AVAILABLE_AUDIO_OUTPUT_DRIVERS                  <t>/ AVAILABLE_AUDIO_OUTPUT_DRIVERS
# Line 4567  Schoenebeck'> Line 8678  Schoenebeck'>
8678                  </t>                  </t>
8679                  <t>/ MIDI_INSTRUMENT_MAPS                  <t>/ MIDI_INSTRUMENT_MAPS
8680                  </t>                  </t>
8681                    <t>/ FX_SENDS SP sampler_channel
8682                    </t>
8683                    <t>/ DB_INSTRUMENT_DIRECTORIES SP RECURSIVE SP db_path
8684                    </t>
8685                    <t>/ DB_INSTRUMENT_DIRECTORIES SP db_path
8686                    </t>
8687                    <t>/ DB_INSTRUMENTS SP RECURSIVE SP db_path
8688                    </t>
8689                    <t>/ DB_INSTRUMENTS SP db_path
8690                    </t>
8691                    <t>/ FILE SP INSTRUMENTS SP filename
8692                    </t>
8693            </list>
8694    </t>
8695    <t>send_instruction =
8696            <list>
8697                    <t>CHANNEL SP MIDI_DATA SP string SP sampler_channel SP number SP number
8698                    </t>
8699          </list>          </list>
8700  </t>  </t>
8701  <t>load_instr_args =  <t>load_instr_args =
# Line 4593  Schoenebeck'> Line 8722  Schoenebeck'>
8722                  </t>                  </t>
8723          </list>          </list>
8724  </t>  </t>
8725    <t>effect_instance =
8726            <list>
8727                    <t>number
8728                    </t>
8729            </list>
8730    </t>
8731  <t>device_index =  <t>device_index =
8732          <list>          <list>
8733                  <t>number                  <t>number
# Line 4649  Schoenebeck'> Line 8784  Schoenebeck'>
8784                  </t>                  </t>
8785          </list>          </list>
8786  </t>  </t>
8787    <t>midi_ctrl =
8788            <list>
8789                    <t>number
8790                    </t>
8791            </list>
8792    </t>
8793  <t>volume_value =  <t>volume_value =
8794          <list>          <list>
8795                  <t>dotnum                  <t>dotnum
# Line 4657  Schoenebeck'> Line 8798  Schoenebeck'>
8798                  </t>                  </t>
8799          </list>          </list>
8800  </t>  </t>
8801    <t>control_value =
8802            <list>
8803                    <t>real
8804                    </t>
8805            </list>
8806    </t>
8807  <t>sampler_channel =  <t>sampler_channel =
8808          <list>          <list>
8809                  <t>number                  <t>number
# Line 4669  Schoenebeck'> Line 8816  Schoenebeck'>
8816                  </t>                  </t>
8817          </list>          </list>
8818  </t>  </t>
8819    <t>fx_send_id =
8820            <list>
8821                    <t>number
8822                    </t>
8823            </list>
8824    </t>
8825  <t>engine_name =  <t>engine_name =
8826          <list>          <list>
8827                  <t>string                  <t>string
# Line 4677  Schoenebeck'> Line 8830  Schoenebeck'>
8830  </t>  </t>
8831  <t>filename =  <t>filename =
8832          <list>          <list>
8833                  <t>stringval                  <t>path
8834                    </t>
8835            </list>
8836    </t>
8837    <t>db_path =
8838            <list>
8839                    <t>path
8840                  </t>                  </t>
8841          </list>          </list>
8842  </t>  </t>
8843  <t>map_name =  <t>map_name =
8844          <list>          <list>
8845                  <t>stringval                  <t>stringval_escaped
8846                  </t>                  </t>
8847          </list>          </list>
8848  </t>  </t>
8849  <t>entry_name =  <t>entry_name =
8850          <list>          <list>
8851                  <t>stringval                  <t>stringval_escaped
8852                    </t>
8853            </list>
8854    </t>
8855    <t>fx_send_name =
8856            <list>
8857                    <t>stringval_escaped
8858                    </t>
8859            </list>
8860    </t>
8861    <t>effect_name =
8862            <list>
8863                    <t>stringval_escaped
8864                    </t>
8865            </list>
8866    </t>
8867    <t>effect_index =
8868            <list>
8869                    <t>number
8870                    </t>
8871            </list>
8872    </t>
8873    <t>effect_chain =
8874            <list>
8875                    <t>number
8876                    </t>
8877            </list>
8878    </t>
8879    <t>chain_pos =
8880            <list>
8881                    <t>number
8882                    </t>
8883            </list>
8884    </t>
8885    <t>input_control =
8886            <list>
8887                    <t>number
8888                  </t>                  </t>
8889          </list>          </list>
8890  </t>  </t>
# Line 4701  Schoenebeck'> Line 8896  Schoenebeck'>
8896                  </t>                  </t>
8897          </list>          </list>
8898  </t>  </t>
8899    
8900  <t>param_val =  <t>param_val =
8901          <list>          <list>
8902                  <t>string                  <t>string
# Line 4713  Schoenebeck'> Line 8909  Schoenebeck'>
8909                  </t>                  </t>
8910          </list>          </list>
8911  </t>  </t>
8912    <t>query_val_list =
8913            <list>
8914                    <t>string '=' query_val
8915                    </t>
8916                    <t>/ query_val_list SP string '=' query_val
8917                    </t>
8918            </list>
8919    </t>
8920    <t>query_val =
8921            <list>
8922                    <t>text_escaped
8923                    </t>
8924                    <t>/ stringval_escaped
8925                    </t>
8926            </list>
8927    </t>
8928    <t>scan_mode =
8929            <list>
8930                    <t>RECURSIVE
8931                    </t>
8932                    <t>/ NON_RECURSIVE
8933                    </t>
8934                    <t>/ FLAT
8935                    </t>
8936            </list>
8937    </t>
8938    <t>effect_system =
8939            <list>
8940                    <t>string
8941                    </t>
8942            </list>
8943    </t>
8944    <t>module =
8945            <list>
8946                    <t>filename
8947                    </t>
8948            </list>
8949    </t>
8950    
8951              <!-- GRAMMAR_BNF_END - do NOT delete or modify this line !!! -->              <!-- GRAMMAR_BNF_END - do NOT delete or modify this line !!! -->
8952    
8953                <section title="Character Set and Escape Sequences" anchor="character_set">
8954                    <t>Older versions of this protocol up to and including v1.1 only
8955                    supported the standard ASCII character set (ASCII code 0 - 127)
8956                    <xref target="RFC20"/>, all younger versions of this protocol
8957                    however support the Extended ASCII character set (ASCII code
8958                    0 - 255). The same group of younger protocols also support
8959                    escape sequences, but only for certain, explicitly declared
8960                    parts of the protocol. The supported escape sequences are
8961                    defined as follows:</t>
8962                    <texttable>
8963                        <ttcol>ASCII Character Sequence</ttcol>
8964                        <ttcol>Translated into (Name)</ttcol>
8965                        <c>\n</c> <c>new line</c>
8966                        <c>\r</c> <c>carriage return</c>
8967                        <c>\f</c> <c>form feed</c>
8968                        <c>\t</c> <c>horizontal tab</c>
8969                        <c>\v</c> <c>vertical tab</c>
8970                        <c>\'</c> <c>apostrophe</c>
8971                        <c>\"</c> <c>quotation mark</c>
8972                        <c>\\</c> <c>backslash</c>
8973                        <c>\OOO</c> <c>three digit octal ASCII code of the character</c>
8974                        <c>\xHH</c> <c>two digit hex ASCII code of the character</c>
8975                    </texttable>
8976                    <t>Notice: due to the transition of certain parts of the
8977                    protocol which now support escape sequences, a slight backward
8978                    incompatibility to protocols version v1.1 and younger has been
8979                    introduced. The only difference is that in parts of the protocol
8980                    where escape characters are now supported, a backslash characters
8981                    MUST be escaped as well (that is as double backslash), whereas
8982                    in the old versions a single backslash was sufficient.</t>
8983    
8984                    <t>The following LSCP commands support escape sequences as part
8985                    of their filename / path based arguments and / or may contain
8986                    a filename / path with escape sequences in their response:
8987                    <list>
8988                        <t><xref target="LOAD INSTRUMENT">"LOAD INSTRUMENT"</xref></t>
8989                        <t><xref target="GET CHANNEL INFO">"GET CHANNEL INFO"</xref></t>
8990                        <t><xref target="MAP MIDI_INSTRUMENT">"MAP MIDI_INSTRUMENT"</xref></t>
8991                        <t><xref target="GET MIDI_INSTRUMENT INFO">"GET MIDI_INSTRUMENT INFO"</xref></t>
8992                        <t><xref target="ADD DB_INSTRUMENT_DIRECTORY">"ADD DB_INSTRUMENT_DIRECTORY"</xref></t>
8993                        <t><xref target="ADD DB_INSTRUMENTS">"ADD DB_INSTRUMENTS"</xref></t>
8994                        <t><xref target="REMOVE DB_INSTRUMENT_DIRECTORY">"REMOVE DB_INSTRUMENT_DIRECTORY"</xref></t>
8995                        <t><xref target="REMOVE DB_INSTRUMENT">"REMOVE DB_INSTRUMENT"</xref></t>
8996                        <t><xref target="GET DB_INSTRUMENT_DIRECTORIES">"GET DB_INSTRUMENT_DIRECTORIES"</xref></t>
8997                        <t><xref target="LIST DB_INSTRUMENT_DIRECTORIES">"LIST DB_INSTRUMENT_DIRECTORIES"</xref></t>
8998                        <t><xref target="GET DB_INSTRUMENT_DIRECTORY INFO">"GET DB_INSTRUMENT_DIRECTORY INFO"</xref></t>
8999                        <t><xref target="GET DB_INSTRUMENTS">"GET DB_INSTRUMENTS"</xref></t>
9000                        <t><xref target="LIST DB_INSTRUMENTS">"LIST DB_INSTRUMENTS"</xref></t>
9001                        <t><xref target="GET DB_INSTRUMENT INFO">"GET DB_INSTRUMENT INFO"</xref></t>
9002                        <t><xref target="SET DB_INSTRUMENT_DIRECTORY NAME">"SET DB_INSTRUMENT_DIRECTORY NAME"</xref></t>
9003                        <t><xref target="SET DB_INSTRUMENT_DIRECTORY DESCRIPTION">"SET DB_INSTRUMENT_DIRECTORY DESCRIPTION"</xref></t>
9004                        <t><xref target="SET DB_INSTRUMENT NAME">"SET DB_INSTRUMENT NAME"</xref></t>
9005                        <t><xref target="SET DB_INSTRUMENT DESCRIPTION">"SET DB_INSTRUMENT DESCRIPTION"</xref></t>
9006                        <t><xref target="FIND DB_INSTRUMENTS">"FIND DB_INSTRUMENTS"</xref></t>
9007                        <t><xref target="FIND DB_INSTRUMENT_DIRECTORIES">"FIND DB_INSTRUMENT_DIRECTORIES"</xref></t>
9008                        <t><xref target="MOVE DB_INSTRUMENT">"MOVE DB_INSTRUMENT"</xref></t>
9009                        <t><xref target="MOVE DB_INSTRUMENT_DIRECTORY">"MOVE DB_INSTRUMENT_DIRECTORY"</xref></t>
9010                        <t><xref target="COPY DB_INSTRUMENT">"COPY DB_INSTRUMENT"</xref></t>
9011                        <t><xref target="COPY DB_INSTRUMENT_DIRECTORY">"COPY DB_INSTRUMENT_DIRECTORY"</xref></t>
9012                        <t><xref target="FIND LOST DB_INSTRUMENT_FILES">"FIND LOST DB_INSTRUMENT_FILES"</xref></t>
9013                        <t><xref target="SET DB_INSTRUMENT FILE_PATH">"SET DB_INSTRUMENT FILE_PATH"</xref></t>
9014                        <t><xref target="GET FILE INSTRUMENTS">"GET FILE INSTRUMENTS"</xref></t>
9015                        <t><xref target="LIST FILE INSTRUMENTS">"LIST FILE INSTRUMENTS"</xref></t>
9016                        <t><xref target="GET FILE INSTRUMENT INFO">"GET FILE INSTRUMENT INFO"</xref></t>
9017                        <t><xref target="GET EFFECT INFO">"GET EFFECT INFO"</xref></t>
9018                        <t><xref target="GET EFFECT_INSTANCE INFO">"GET EFFECT_INSTANCE INFO"</xref></t>
9019                        <t><xref target="CREATE EFFECT_INSTANCE">"CREATE EFFECT_INSTANCE"</xref></t>
9020                    </list>
9021                    Note that the forward slash character ('/') has a special meaning in
9022                    filename / path based arguments: it acts as separator of the nodes in
9023                    the path, thus if a directory- or filename includes a forward slash
9024                    (not intended as path node separator), you MUST escape that slash
9025                    either with the respective hex escape sequence ("\x2f") or with the
9026                    respective octal escape sequence ("\057").
9027                    </t>
9028    
9029                    <t>
9030                    Note for Windows: file path arguments in LSCP are expected
9031                    to use forward slashes as directory node separator similar
9032                    to Unix based operating systems. In contrast to Unix however
9033                    a Windows typical drive character is expected to be
9034                    prefixed to the path. That is an original Windows file path
9035                    like "D:\Sounds\My.gig" would become in LSCP:
9036                    "D:/Sounds/My.gig".
9037                    </t>
9038    
9039                    <t>
9040                    The following LSCP commands even support escape sequences as
9041                    part of at least one of their text-based arguments (i.e. entity name,
9042                    description) and / or may contain escape sequences in at least one of
9043                    their text-based fields in their response:
9044                    <list>
9045                        <t><xref target="GET SERVER INFO">"GET SERVER INFO"</xref></t>
9046                        <t><xref target="GET ENGINE INFO">"GET ENGINE INFO"</xref></t>
9047                        <t><xref target="GET CHANNEL INFO">"GET CHANNEL INFO"</xref></t>
9048                        <t><xref target="CREATE FX_SEND">"CREATE FX_SEND"</xref></t>
9049                        <t><xref target="GET FX_SEND INFO">"GET FX_SEND INFO"</xref></t>
9050                        <t><xref target="SET FX_SEND NAME">"SET FX_SEND NAME"</xref></t>
9051                        <t><xref target="GET MIDI_INSTRUMENT INFO">"GET MIDI_INSTRUMENT INFO"</xref></t>
9052                        <t><xref target="GET MIDI_INSTRUMENT_MAP INFO">"GET MIDI_INSTRUMENT_MAP INFO"</xref></t>
9053                        <t><xref target="ADD MIDI_INSTRUMENT_MAP">"ADD MIDI_INSTRUMENT_MAP"</xref></t>
9054                        <t><xref target="MAP MIDI_INSTRUMENT">"MAP MIDI_INSTRUMENT"</xref></t>
9055                        <t><xref target="SET MIDI_INSTRUMENT_MAP NAME">"SET MIDI_INSTRUMENT_MAP NAME"</xref></t>
9056                        <t><xref target="GET DB_INSTRUMENT_DIRECTORY INFO">"GET DB_INSTRUMENT_DIRECTORY INFO"</xref></t>
9057                        <t><xref target="SET DB_INSTRUMENT_DIRECTORY NAME">"SET DB_INSTRUMENT_DIRECTORY NAME"</xref></t>
9058                        <t><xref target="SET DB_INSTRUMENT_DIRECTORY DESCRIPTION">"SET DB_INSTRUMENT_DIRECTORY DESCRIPTION"</xref></t>
9059                        <t><xref target="FIND DB_INSTRUMENT_DIRECTORIES">"FIND DB_INSTRUMENT_DIRECTORIES"</xref></t>
9060                        <t><xref target="GET DB_INSTRUMENT INFO">"GET DB_INSTRUMENT INFO"</xref></t>
9061                        <t><xref target="SET DB_INSTRUMENT NAME">"SET DB_INSTRUMENT NAME"</xref></t>
9062                        <t><xref target="SET DB_INSTRUMENT DESCRIPTION">"SET DB_INSTRUMENT DESCRIPTION"</xref></t>
9063                        <t><xref target="FIND DB_INSTRUMENTS">"FIND DB_INSTRUMENTS"</xref></t>
9064                        <t><xref target="GET EFFECT INFO">"GET EFFECT INFO"</xref></t>
9065                        <t><xref target="GET EFFECT_INSTANCE INFO">"GET EFFECT_INSTANCE INFO"</xref></t>
9066                        <t><xref target="CREATE EFFECT_INSTANCE">"CREATE EFFECT_INSTANCE"</xref></t>
9067                    </list>
9068                    Please note that these lists are manually maintained. If you
9069                    find a command that also supports escape sequences we forgot to
9070                    mention here, please report it!
9071                    </t>
9072                </section>
9073          </section>          </section>
9074    
9075          <section title="Events" anchor="events">          <section title="Events" anchor="events">
9076              <t>This chapter will describe all currently defined events supported by LinuxSampler.</t>              <t>This chapter will describe all currently defined events supported by LinuxSampler.</t>
9077    
9078              <section title="Number of audio output devices changed" anchor="SUBSCRIBE AUDIO_OUTPUT_DEVICE_COUNT">              <section title="Number of audio output devices changed" anchor="SUBSCRIBE AUDIO_OUTPUT_DEVICE_COUNT" lscp_cmd="true">
9079                  <t>Client may want to be notified when the total number of audio output devices on the                  <t>Client may want to be notified when the total number of audio output devices on the
9080                  back-end changes by issuing the following command:</t>                  back-end changes by issuing the following command:</t>
9081                  <t>                  <t>
# Line 4738  Schoenebeck'> Line 9093  Schoenebeck'>
9093                  of audio output devices.</t>                  of audio output devices.</t>
9094              </section>              </section>
9095    
9096              <section title="Audio output device's settings changed" anchor="SUBSCRIBE AUDIO_OUTPUT_DEVICE_INFO">              <section title="Audio output device's settings changed" anchor="SUBSCRIBE AUDIO_OUTPUT_DEVICE_INFO" lscp_cmd="true">
9097                  <t>Client may want to be notified when changes were made to audio output devices on the                  <t>Client may want to be notified when changes were made to audio output devices on the
9098                  back-end by issuing the following command:</t>                  back-end by issuing the following command:</t>
9099                  <t>                  <t>
# Line 4760  Schoenebeck'> Line 9115  Schoenebeck'>
9115                  message is sufficient here.</t>                  message is sufficient here.</t>
9116              </section>              </section>
9117    
9118              <section title="Number of MIDI input devices changed" anchor="SUBSCRIBE MIDI_INPUT_DEVICE_COUNT">              <section title="Number of MIDI input devices changed" anchor="SUBSCRIBE MIDI_INPUT_DEVICE_COUNT" lscp_cmd="true">
9119                  <t>Client may want to be notified when the total number of MIDI input devices on the                  <t>Client may want to be notified when the total number of MIDI input devices on the
9120                  back-end changes by issuing the following command:</t>                  back-end changes by issuing the following command:</t>
9121                  <t>                  <t>
# Line 4778  Schoenebeck'> Line 9133  Schoenebeck'>
9133                  of MIDI input devices.</t>                  of MIDI input devices.</t>
9134              </section>              </section>
9135    
9136              <section title="MIDI input device's settings changed" anchor="SUBSCRIBE MIDI_INPUT_DEVICE_INFO">              <section title="MIDI input device's settings changed" anchor="SUBSCRIBE MIDI_INPUT_DEVICE_INFO" lscp_cmd="true">
9137                  <t>Client may want to be notified when changes were made to MIDI input devices on the                  <t>Client may want to be notified when changes were made to MIDI input devices on the
9138                  back-end by issuing the following command:</t>                  back-end by issuing the following command:</t>
9139                  <t>                  <t>
# Line 4800  Schoenebeck'> Line 9155  Schoenebeck'>
9155                  message is sufficient here.</t>                  message is sufficient here.</t>
9156              </section>              </section>
9157    
9158              <section title="Number of sampler channels changed" anchor="SUBSCRIBE CHANNEL_COUNT">              <section title="Number of sampler channels changed" anchor="SUBSCRIBE CHANNEL_COUNT" lscp_cmd="true">
9159                  <t>Client may want to be notified when the total number of channels on the                  <t>Client may want to be notified when the total number of channels on the
9160                  back-end changes by issuing the following command:</t>                  back-end changes by issuing the following command:</t>
9161                  <t>                  <t>
# Line 4818  Schoenebeck'> Line 9173  Schoenebeck'>
9173                  of sampler channels.</t>                  of sampler channels.</t>
9174              </section>              </section>
9175    
9176              <section title="Number of active voices changed" anchor="SUBSCRIBE VOICE_COUNT">              <section title="MIDI data on a sampler channel arrived" anchor="SUBSCRIBE CHANNEL_MIDI" lscp_cmd="true">
9177                    <t>Client may want to be notified when MIDI data arrive on sampler channels on
9178                    back-end side, by issuing the following command:</t>
9179                    <t>
9180                        <list>
9181                            <t>SUBSCRIBE CHANNEL_MIDI</t>
9182                        </list>
9183                    </t>
9184                    <t>Server will start sending one of the the following notification messages:</t>
9185                    <t>
9186                        <list>
9187                            <t>"NOTIFY:CHANNEL_MIDI:&lt;channel-id&gt; NOTE_ON  &lt;note&gt; &lt;velocity&gt;"</t>
9188                            <t>"NOTIFY:CHANNEL_MIDI:&lt;channel-id&gt; NOTE_OFF &lt;note&gt; &lt;velocity&gt;"</t>
9189                        </list>
9190                    </t>
9191                    <t>where &lt;channel-id&gt; will be replaced by the ID of the sampler channel where the MIDI
9192                    data arrived. &lt;note&gt; and &lt;velocity&gt; are integer values in the range between
9193                    0 .. 127, reflecting the analog meaning of the MIDI specification.
9194                    </t>
9195                    <t>CAUTION: no guarantee whatsoever will be made that MIDI events are actually all
9196                    delivered by this mechanism! With other words: events could be lost at any time!
9197                    This restriction was made to keep the RT-safeness of the backend's MIDI and audio
9198                    thread unaffected by this feature.</t>
9199                </section>
9200    
9201                <section title="MIDI data on a MIDI input device arrived" anchor="SUBSCRIBE DEVICE_MIDI" lscp_cmd="true">
9202                        <t>Client may want to be notified when MIDI data arrive on MIDI input devices by issuing the following command:</t>
9203                        <t>
9204                                <list>
9205                                        <t>SUBSCRIBE DEVICE_MIDI</t>
9206                                </list>
9207                        </t>
9208                        <t>Server will start sending one of the the following notification messages:</t>
9209                        <t>
9210                                <list>
9211                                        <t>"NOTIFY:DEVICE_MIDI:&lt;device-id&gt; &lt;port-id&gt; NOTE_ON &lt;note&gt; &lt;velocity&gt;"</t>
9212                                        <t>"NOTIFY:DEVICE_MIDI:&lt;device-id&gt; &lt;port-id&gt; NOTE_OFF &lt;note&gt; &lt;velocity&gt;"</t>
9213                                </list>
9214                        </t>
9215                        <t>where &lt;device-id&gt; &lt;port-id&gt; will be replaced
9216                           by the IDs of the respective MIDI input device and the device's MIDI port where the MIDI
9217                           data arrived. &lt;note&gt; and &lt;velocity&gt; are integer values in the range between
9218                           0 .. 127, reflecting the analog meaning of the MIDI specification.
9219                        </t>
9220                        <t>CAUTION: no guarantee whatsoever will be made that MIDI events are actually all
9221                           delivered by this mechanism! With other words: events could be lost at any time!
9222                           This restriction was made to keep the RT-safeness of the backend's MIDI and audio
9223                           thread unaffected by this feature.</t>
9224                </section>
9225    
9226                <section title="Number of active voices changed" anchor="SUBSCRIBE VOICE_COUNT" lscp_cmd="true">
9227                  <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
9228                  back-end changes by issuing the following command:</t>                  back-end changes by issuing the following command:</t>
9229                  <t>                  <t>
# Line 4829  Schoenebeck'> Line 9234  Schoenebeck'>
9234                  <t>Server will start sending the following notification messages:</t>                  <t>Server will start sending the following notification messages:</t>
9235                  <t>                  <t>
9236                      <list>                      <list>
9237                          <t>"NOTIFY:VOICE_COUNT:&lt;sampler-channel&gt; &lt;voices&gt;</t>                          <t>"NOTIFY:VOICE_COUNT:&lt;sampler-channel&gt; &lt;voices&gt;"</t>
9238                      </list>                      </list>
9239                  </t>                  </t>
9240                  <t>where &lt;sampler-channel&gt; will be replaced by the sampler channel the                  <t>where &lt;sampler-channel&gt; will be replaced by the sampler channel the
# Line 4837  Schoenebeck'> Line 9242  Schoenebeck'>
9242                  active voices on that channel.</t>                  active voices on that channel.</t>
9243              </section>              </section>
9244    
9245              <section title="Number of active disk streams changed" anchor="SUBSCRIBE STREAM_COUNT">              <section title="Number of active disk streams changed" anchor="SUBSCRIBE STREAM_COUNT" lscp_cmd="true">
9246                  <t>Client may want to be notified when the number of streams on the back-end                  <t>Client may want to be notified when the number of streams on the back-end
9247                  changes by issuing the following command: SUBSCRIBE STREAM_COUNT</t>                  changes by issuing the following command: SUBSCRIBE STREAM_COUNT</t>
9248                  <t>                  <t>
# Line 4856  Schoenebeck'> Line 9261  Schoenebeck'>
9261                  active disk streams on that channel.</t>                  active disk streams on that channel.</t>
9262              </section>              </section>
9263    
9264              <section title="Disk stream buffer fill state changed" anchor="SUBSCRIBE BUFFER_FILL">              <section title="Disk stream buffer fill state changed" anchor="SUBSCRIBE BUFFER_FILL" lscp_cmd="true">
9265                  <t>Client may want to be notified when the buffer fill state of a disk stream                  <t>Client may want to be notified when the buffer fill state of a disk stream
9266                  on the back-end changes by issuing the following command:</t>                  on the back-end changes by issuing the following command:</t>
9267                  <t>                  <t>
# Line 4877  Schoenebeck'> Line 9282  Schoenebeck'>
9282                  "GET CHANNEL BUFFER_FILL PERCENTAGE"</xref> command was issued on this channel.</t>                  "GET CHANNEL BUFFER_FILL PERCENTAGE"</xref> command was issued on this channel.</t>
9283              </section>              </section>
9284    
9285              <section title="Channel information changed" anchor="SUBSCRIBE CHANNEL_INFO">              <section title="Channel information changed" anchor="SUBSCRIBE CHANNEL_INFO" lscp_cmd="true">
9286                  <t>Client may want to be notified when changes were made to sampler channels on the                  <t>Client may want to be notified when changes were made to sampler channels on the
9287                  back-end by issuing the following command:</t>                  back-end by issuing the following command:</t>
9288                  <t>                  <t>
# Line 4899  Schoenebeck'> Line 9304  Schoenebeck'>
9304                  message is sufficient here.</t>                  message is sufficient here.</t>
9305              </section>              </section>
9306    
9307              <section title="Total number of active voices changed" anchor="SUBSCRIBE TOTAL_VOICE_COUNT">              <section title="Number of effect sends changed" anchor="SUBSCRIBE FX_SEND_COUNT" lscp_cmd="true">
9308                    <t>Client may want to be notified when the number of effect sends on
9309                    a particular sampler channel is changed by issuing the following command:</t>
9310                    <t>
9311                        <list>
9312                            <t>SUBSCRIBE FX_SEND_COUNT</t>
9313                        </list>
9314                    </t>
9315                    <t>Server will start sending the following notification messages:</t>
9316                    <t>
9317                        <list>
9318                            <t>"NOTIFY:FX_SEND_COUNT:&lt;channel-id&gt; &lt;fx-sends&gt;"</t>
9319                        </list>
9320                    </t>
9321                    <t>where &lt;channel-id&gt; will be replaced by the numerical ID of the sampler
9322                    channel, on which the effect sends number is changed and &lt;fx-sends&gt; will
9323                    be replaced by the new number of effect sends on that channel.</t>
9324                </section>
9325    
9326                <section title="Effect send information changed" anchor="SUBSCRIBE FX_SEND_INFO" lscp_cmd="true">
9327                    <t>Client may want to be notified when changes were made to effect sends on a
9328                    a particular sampler channel by issuing the following command:</t>
9329                    <t>
9330                        <list>
9331                            <t>SUBSCRIBE FX_SEND_INFO</t>
9332                        </list>
9333                    </t>
9334                    <t>Server will start sending the following notification messages:</t>
9335                    <t>
9336                        <list>
9337                            <t>"NOTIFY:FX_SEND_INFO:&lt;channel-id&gt; &lt;fx-send-id&gt;"</t>
9338                        </list>
9339                    </t>
9340                    <t>where &lt;channel-id&gt; will be replaced by the numerical ID of the sampler
9341                    channel, on which an effect send entity is changed and &lt;fx-send-id&gt; will
9342                    be replaced by the numerical ID of the changed effect send.</t>
9343                </section>
9344    
9345                <section title="Total number of active voices changed" anchor="SUBSCRIBE TOTAL_VOICE_COUNT" lscp_cmd="true">
9346                  <t>Client may want to be notified when the total number of voices on the                  <t>Client may want to be notified when the total number of voices on the
9347                  back-end changes by issuing the following command:</t>                  back-end changes by issuing the following command:</t>
9348                  <t>                  <t>
# Line 4910  Schoenebeck'> Line 9353  Schoenebeck'>
9353                  <t>Server will start sending the following notification messages:</t>                  <t>Server will start sending the following notification messages:</t>
9354                  <t>                  <t>
9355                      <list>                      <list>
9356                          <t>"NOTIFY:TOTAL_VOICE_COUNT:&lt;voices&gt;</t>                          <t>"NOTIFY:TOTAL_VOICE_COUNT:&lt;voices&gt;"</t>
9357                      </list>                      </list>
9358                  </t>                  </t>
9359                  <t>where &lt;voices&gt; will be replaced by the new number of                  <t>where &lt;voices&gt; will be replaced by the new number of
9360                  all currently active voices.</t>                  all currently active voices.</t>
9361              </section>              </section>
9362    
9363              <section title="Number of MIDI instrument maps changed" anchor="SUBSCRIBE MIDI_INSTRUMENT_MAP_COUNT">              <section title="Total number of active disk streams changed" anchor="SUBSCRIBE TOTAL_STREAM_COUNT" lscp_cmd="true">
9364                    <t>Client may want to be notified when the total number of disk streams on the
9365                    back-end changes by issuing the following command:</t>
9366                    <t>
9367                        <list>
9368                            <t>SUBSCRIBE TOTAL_STREAM_COUNT</t>
9369                        </list>
9370                    </t>
9371                    <t>Server will start sending the following notification messages:</t>
9372                    <t>
9373                        <list>
9374                            <t>"NOTIFY:TOTAL_STREAM_COUNT:&lt;streams&gt;"</t>
9375                        </list>
9376                    </t>
9377                    <t>where &lt;streams&gt; will be replaced by the new number of
9378                    all currently active disk streams.</t>
9379                </section>
9380    
9381                <section title="Number of MIDI instrument maps changed" anchor="SUBSCRIBE MIDI_INSTRUMENT_MAP_COUNT" lscp_cmd="true">
9382                  <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
9383                  back-end changes by issuing the following command:</t>                  back-end changes by issuing the following command:</t>
9384                  <t>                  <t>
# Line 4935  Schoenebeck'> Line 9396  Schoenebeck'>
9396                  of MIDI instrument maps.</t>                  of MIDI instrument maps.</t>
9397              </section>              </section>
9398    
9399              <section title="MIDI instrument map information changed" anchor="SUBSCRIBE MIDI_INSTRUMENT_MAP_INFO">              <section title="MIDI instrument map information changed" anchor="SUBSCRIBE MIDI_INSTRUMENT_MAP_INFO" lscp_cmd="true">
9400                  <t>Client may want to be notified when changes were made to MIDI instrument maps on the                  <t>Client may want to be notified when changes were made to MIDI instrument maps on the
9401                  back-end by issuing the following command:</t>                  back-end by issuing the following command:</t>
9402                  <t>                  <t>
# Line 4957  Schoenebeck'> Line 9418  Schoenebeck'>
9418                  message is sufficient here.</t>                  message is sufficient here.</t>
9419              </section>              </section>
9420    
9421              <section title="Number of MIDI instruments changed" anchor="SUBSCRIBE MIDI_INSTRUMENT_COUNT">              <section title="Number of MIDI instruments changed" anchor="SUBSCRIBE MIDI_INSTRUMENT_COUNT" lscp_cmd="true">
9422                  <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
9423                  back-end changes by issuing the following command:</t>                  back-end changes by issuing the following command:</t>
9424                  <t>                  <t>
# Line 4971  Schoenebeck'> Line 9432  Schoenebeck'>
9432                          <t>"NOTIFY:MIDI_INSTRUMENT_COUNT:&lt;map-id&gt; &lt;instruments&gt;"</t>                          <t>"NOTIFY:MIDI_INSTRUMENT_COUNT:&lt;map-id&gt; &lt;instruments&gt;"</t>
9433                      </list>                      </list>
9434                  </t>                  </t>
9435                  <t>where &lt;map-id&gt; is the numerical ID of the MIDI instrument map, in which                  <t>where &lt;map-id&gt; is the numerical ID of the MIDI instrument map, in which
9436                  the nuber of instruments has changed and &lt;instruments&gt; will be replaced by                  the nuber of instruments has changed and &lt;instruments&gt; will be replaced by
9437                  the new number of MIDI instruments in the specified map.</t>                  the new number of MIDI instruments in the specified map.</t>
9438              </section>              </section>
9439    
9440              <section title="MIDI instrument information changed" anchor="SUBSCRIBE MIDI_INSTRUMENT_INFO">              <section title="MIDI instrument information changed" anchor="SUBSCRIBE MIDI_INSTRUMENT_INFO" lscp_cmd="true">
9441                  <t>Client may want to be notified when changes were made to MIDI instruments on the                  <t>Client may want to be notified when changes were made to MIDI instruments on the
9442                  back-end by issuing the following command:</t>                  back-end by issuing the following command:</t>
9443                  <t>                  <t>
# Line 4991  Schoenebeck'> Line 9452  Schoenebeck'>
9452                      </list>                      </list>
9453                  </t>                  </t>
9454                  <t>where &lt;map-id&gt; will be replaced by the numerical ID of the MIDI instrument map,                  <t>where &lt;map-id&gt; will be replaced by the numerical ID of the MIDI instrument map,
9455                  in which a MIDI instrument is changed. &lt;bank&gt; and &lt;program&gt; specifies                  in which a MIDI instrument is changed. &lt;bank&gt; and &lt;program&gt; specifies
9456                  the location of the changed MIDI instrument in the map. The front-end will have to send                  the location of the changed MIDI instrument in the map. The front-end will have to send
9457                  the respective command to actually get the MIDI instrument info. Because these messages                  the respective command to actually get the MIDI instrument info. Because these messages
9458                  will be triggered by LSCP commands issued by other clients rather than real                  will be triggered by LSCP commands issued by other clients rather than real
# Line 4999  Schoenebeck'> Line 9460  Schoenebeck'>
9460                  message is sufficient here.</t>                  message is sufficient here.</t>
9461              </section>              </section>
9462    
9463              <<section title="Miscellaneous and debugging events" anchor="SUBSCRIBE MISCELLANEOUS">              <section title="Global settings changed" anchor="SUBSCRIBE GLOBAL_INFO" lscp_cmd="true">
9464                    <t>Client may want to be notified when changes to the global settings
9465                    of the sampler were made by issuing the following command:</t>
9466                    <t>
9467                        <list>
9468                            <t>SUBSCRIBE GLOBAL_INFO</t>
9469                        </list>
9470                    </t>
9471                    <t>Server will start sending the following types of notification messages:</t>
9472                    <t>
9473                        <list>
9474                            <t>"NOTIFY:GLOBAL_INFO:VOLUME &lt;volume&gt;" - Notifies that the
9475                            golbal volume of the sampler is changed, where &lt;volume&gt; will be
9476                            replaced by the optional dotted floating point value, reflecting the
9477                            new global volume parameter.</t>
9478                        </list>
9479                        <list>
9480                            <t>"NOTIFY:GLOBAL_INFO:VOICES &lt;max-voices&gt;" - Notifies that the
9481                            golbal limit of the sampler for maximum voices is changed, where
9482                            &lt;max-voices&gt; will be an integer value, reflecting the
9483                            new global voice limit parameter.</t>
9484                        </list>
9485                        <list>
9486                            <t>"NOTIFY:GLOBAL_INFO:STREAMS &lt;max-streams&gt;" - Notifies that the
9487                            golbal limit of the sampler for maximum disk streams is changed, where
9488                            &lt;max-streams&gt; will be an integer value, reflecting the
9489                            new global disk streams limit parameter.</t>
9490                        </list>
9491                    </t>
9492                </section>
9493    
9494                <section title="Number of database instrument directories changed" anchor="SUBSCRIBE DB_INSTRUMENT_DIRECTORY_COUNT" lscp_cmd="true">
9495                    <t>Client may want to be notified when the number of instrument
9496                    directories in a particular directory in the instruments database
9497                    is changed by issuing the following command:</t>
9498                    <t>
9499                        <list>
9500                            <t>SUBSCRIBE DB_INSTRUMENT_DIRECTORY_COUNT</t>
9501                        </list>
9502                    </t>
9503                    <t>Server will start sending the following notification messages:</t>
9504                    <t>
9505                        <list>
9506                            <t>"NOTIFY:DB_INSTRUMENT_DIRECTORY_COUNT:&lt;dir-path&gt;"</t>
9507                        </list>
9508                    </t>
9509                    <t>where &lt;dir-path&gt; will be replaced by the absolute path
9510                    name of the directory in the instruments database,
9511                    in which the number of directories is changed.</t>
9512                    <t>Note that when a non-empty directory is removed, this event
9513                    is not sent for the subdirectories in that directory.</t>
9514                </section>
9515    
9516                <section title="Database instrument directory information changed" anchor="SUBSCRIBE DB_INSTRUMENT_DIRECTORY_INFO" lscp_cmd="true">
9517                    <t>Client may want to be notified when changes were made to directories
9518                    in the instruments database by issuing the following command:</t>
9519                    <t>
9520                        <list>
9521                            <t>SUBSCRIBE DB_INSTRUMENT_DIRECTORY_INFO</t>
9522                        </list>
9523                    </t>
9524                    <t>Server will start sending the following notification messages:</t>
9525                    <t>
9526                        <list>
9527                            <t>"NOTIFY:DB_INSTRUMENT_DIRECTORY_INFO:&lt;dir-path&gt;"</t>
9528                        </list>
9529                    </t>
9530                    <t>where &lt;dir-path&gt; will be replaced by the absolute path name
9531                    of the directory, for which information changes occurred. The front-end will have to send
9532                    the respective command to actually get the updated directory info. Because these messages
9533                    will be triggered by LSCP commands issued by other clients rather than real
9534                    time events happening on the server, it is believed that an empty notification
9535                    message is sufficient here.</t>
9536                    <t>
9537                        <list>
9538                            <t>"NOTIFY:DB_INSTRUMENT_DIRECTORY_INFO:NAME &lt;old-dir-path&gt; &lt;new-name&gt;"</t>
9539                        </list>
9540                    </t>
9541                    <t>where &lt;old-dir-path&gt; is the old absolute path name of the directory
9542                    (encapsulated into apostrophes), which name is changes and &lt;new-name&gt; is
9543                    the new name of the directory, encapsulated into apostrophes.</t>
9544                </section>
9545    
9546                <section title="Number of database instruments changed" anchor="SUBSCRIBE DB_INSTRUMENT_COUNT" lscp_cmd="true">
9547                    <t>Client may want to be notified when the number of instruments
9548                    in a particular directory in the instruments database
9549                    is changed by issuing the following command:</t>
9550                    <t>
9551                        <list>
9552                            <t>SUBSCRIBE DB_INSTRUMENT_COUNT</t>
9553                        </list>
9554                    </t>
9555                    <t>Server will start sending the following notification messages:</t>
9556                    <t>
9557                        <list>
9558                            <t>"NOTIFY:DB_INSTRUMENT_COUNT:&lt;dir-path&gt;"</t>
9559                        </list>
9560                    </t>
9561                    <t>where &lt;dir-path&gt; will be replaced by the absolute path
9562                    name of the directory in the instruments database,
9563                    in which the number of instruments is changed.</t>
9564                    <t>Note that when a non-empty directory is removed, this event
9565                    is not sent for the instruments in that directory.</t>
9566                </section>
9567    
9568                <section title="Database instrument information changed" anchor="SUBSCRIBE DB_INSTRUMENT_INFO" lscp_cmd="true">
9569                    <t>Client may want to be notified when changes were made to instruments
9570                    in the instruments database by issuing the following command:</t>
9571                    <t>
9572                        <list>
9573                            <t>SUBSCRIBE DB_INSTRUMENT_INFO</t>
9574                        </list>
9575                    </t>
9576                    <t>Server will start sending the following notification messages:</t>
9577                    <t>
9578                        <list>
9579                            <t>"NOTIFY:DB_INSTRUMENT_INFO:&lt;instr-path&gt;"</t>
9580                        </list>
9581                    </t>
9582                    <t>where &lt;instr-path&gt; will be replaced by the absolute path name
9583                    of the instrument, which settings are changed. The front-end will have to send
9584                    the respective command to actually get the updated directory info. Because these messages
9585                    will be triggered by LSCP commands issued by other clients rather than real
9586                    time events happening on the server, it is believed that an empty notification
9587                    message is sufficient here.</t>
9588                    <t>
9589                        <list>
9590                            <t>"NOTIFY:DB_INSTRUMENT_INFO:NAME &lt;old-instr-path&gt; &lt;new-name&gt;"</t>
9591                        </list>
9592                    </t>
9593                    <t>where &lt;old-instr-path&gt; is the old absolute path name of the instrument
9594                    (encapsulated into apostrophes), which name is changes and &lt;new-name&gt; is
9595                    the new name of the instrument, encapsulated into apostrophes.</t>
9596                </section>
9597    
9598                <section title="Database job status information changed" anchor="SUBSCRIBE DB_INSTRUMENTS_JOB_INFO" lscp_cmd="true">
9599                    <t>Client may want to be notified when the status of particular database
9600                    instruments job is changed by issuing the following command:</t>
9601                    <t>
9602                        <list>
9603                            <t>SUBSCRIBE DB_INSTRUMENTS_JOB_INFO</t>
9604                        </list>
9605                    </t>
9606                    <t>Server will start sending the following notification messages:</t>
9607                    <t>
9608                        <list>
9609                            <t>"NOTIFY:DB_INSTRUMENTS_JOB_INFO:&lt;job-id&gt;"</t>
9610                        </list>
9611                    </t>
9612                    <t>where &lt;job-id&gt; will be replaced by the numerical ID of the job,
9613                    which status is changed. The front-end will have to send the respective
9614                    command to actually get the status info. Because these messages
9615                    will be triggered by LSCP commands issued by other clients rather than real
9616                    time events happening on the server, it is believed that an empty notification
9617                    message is sufficient here.</t>
9618                </section>
9619    
9620                <section title="Number of effect instances changed" anchor="SUBSCRIBE EFFECT_INSTANCE_COUNT" lscp_cmd="true">
9621                    <t>Client may want to be notified when the number of effect instances
9622                    is changed by issuing the following command:</t>
9623                    <t>
9624                        <list>
9625                            <t>SUBSCRIBE EFFECT_INSTANCE_COUNT</t>
9626                        </list>
9627                    </t>
9628                    <t>Server will start sending the following notification messages:</t>
9629                    <t>
9630                        <list>
9631                            <t>"EFFECT_INSTANCE_COUNT:&lt;instances&gt;"</t>
9632                        </list>
9633                    </t>
9634                    <t>where &lt;instances&gt; will be replaced by the new number
9635                    of effect instances.</t>
9636                </section>
9637    
9638                <section title="Effect instance information changed" anchor="SUBSCRIBE EFFECT_INSTANCE_INFO" lscp_cmd="true">
9639                    <t>Client may want to be notified when changes were made to effect instances
9640                    on the back-end by issuing the following command:</t>
9641                    <t>
9642                        <list>
9643                            <t>SUBSCRIBE EFFECT_INSTANCE_INFO</t>
9644                        </list>
9645                    </t>
9646                    <t>Server will start sending the following notification messages:</t>
9647                    <t>
9648                       <list>
9649                            <t>"EFFECT_INSTANCE_INFO:&lt;instance-id&gt;"</t>
9650                        </list>
9651                    </t>
9652                    <t>where &lt;instance-id&gt; will be replaced by the numerical ID
9653                    of the effect instance.</t>
9654                </section>
9655    
9656                <section title="Number of send effect chains changed" anchor="SUBSCRIBE SEND_EFFECT_CHAIN_COUNT" lscp_cmd="true">
9657                    <t>Client may want to be notified when the number of send effect chains
9658                    is changed by issuing the following command:</t>
9659                    <t>
9660                        <list>
9661                            <t>SUBSCRIBE SEND_EFFECT_CHAIN_COUNT</t>
9662                        </list>
9663                    </t>
9664                    <t>Server will start sending the following notification messages:</t>
9665                    <t>
9666                        <list>
9667                            <t>"NOTIFY:SEND_EFFECT_CHAIN_COUNT:&lt;device-id&gt; &lt;chains&gt;"</t>
9668                        </list>
9669                    </t>
9670                    <t>where &lt;device-id&gt; will be replaced by the numerical ID of the audio
9671                    output device, in which the number of send effect chains is changed and
9672                    &lt;chains&gt; will be replaced by the new number of send effect chains.</t>
9673                </section>
9674    
9675                <section title="Send effect chain information changed" anchor="SUBSCRIBE SEND_EFFECT_CHAIN_INFO" lscp_cmd="true">
9676                    <t>Client may want to be notified when changes were made to send effect chains
9677                    on the back-end by issuing the following command:</t>
9678                    <t>
9679                        <list>
9680                            <t>SUBSCRIBE SEND_EFFECT_CHAIN_INFO</t>
9681                        </list>
9682                    </t>
9683                    <t>Server will start sending the following notification messages:</t>
9684                    <t>
9685                       <list>
9686                            <t>"SEND_EFFECT_CHAIN_INFO:&lt;device-id&gt; &lt;chain-id&gt; &lt;instances&gt;" -
9687                            Notifies that the number of effect instances in a particular send effect chain
9688                            is changed, where &lt;device-id&gt; will be replaced by the numerical ID of the audio
9689                            output device the send effect chain belongs to, &lt;chain-id&gt; will be replaced
9690                            by the numerical ID of the send effect chain in which the number of effect instances
9691                            has changed and &lt;instances&gt; will be replaced by the new number
9692                            of effect instances in the specified send effect chain.</t>
9693                        </list>
9694                    </t>
9695                </section>
9696    
9697                <section title="Miscellaneous and debugging events" anchor="SUBSCRIBE MISCELLANEOUS" lscp_cmd="true">
9698                  <t>Client may want to be notified of miscellaneous and debugging events occurring at                  <t>Client may want to be notified of miscellaneous and debugging events occurring at
9699                  the server by issuing the following command:</t>                  the server by issuing the following command:</t>
9700                  <t>                  <t>
# Line 5077  Schoenebeck'> Line 9772  Schoenebeck'>
9772                  </front>                  </front>
9773                  <seriesInfo name="RFC" value="2234" />                  <seriesInfo name="RFC" value="2234" />
9774              </reference>              </reference>
9775                <reference anchor="RFC20">
9776                    <front>
9777                        <title>ASCII format for Network Interchange</title>
9778                        <author>
9779                            <organization>UCLA</organization>
9780                        </author>
9781                        <date year="1969"></date>
9782                    </front>
9783                    <seriesInfo name="RFC" value="20" />
9784                </reference>
9785           </references>           </references>
9786      </back>      </back>
9787    
Legend:
Removed from v.981  
changed lines
  Added in v.3502
  ViewVC Help
Powered by ViewVC