/[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 1136 by iliev, Thu Mar 29 10:01:50 2007 UTC revision 2140 by schoenebeck, Tue Oct 5 10:35:13 2010 UTC
# Line 16  Line 16 
16       to an annoying "missing Normative/Informative References" error message -->       to an annoying "missing Normative/Informative References" error message -->
17  <?rfc strict="no" ?>  <?rfc strict="no" ?>
18    
19  <rfc category="std" ipr="full3978" docName="LSCP 1.2">  <rfc category="std" ipr="full3978" docName="LSCP 1.5">
20      <front>      <front>
21          <title>LinuxSampler Control Protocol</title>          <title>LinuxSampler Control Protocol</title>
22          <author initials='C.S.' surname="Schoenebeck" fullname='C.          <author initials='C.S.' surname="Schoenebeck" fullname='C.
# Line 34  Schoenebeck'> Line 34  Schoenebeck'>
34                  <email>schoenebeck at software minus engineering dot org</email>                  <email>schoenebeck at software minus engineering dot org</email>
35              </address>              </address>
36          </author>          </author>
37          <date month="March" year="2007"/>          <date month="October" year="2010"/>
38          <workgroup>LinuxSampler Developers</workgroup>          <workgroup>LinuxSampler Developers</workgroup>
39          <keyword>LSCP</keyword>          <keyword>LSCP</keyword>
40          <abstract>          <abstract>
# Line 61  Schoenebeck'> Line 61  Schoenebeck'>
61              (front-end) and server (LinuxSampler) respectively. Lines in              (front-end) and server (LinuxSampler) respectively. Lines in
62              examples must be interpreted as every line being CRLF              examples must be interpreted as every line being CRLF
63              terminated (carriage return character followed by line feed              terminated (carriage return character followed by line feed
64              character as defined in the ASCII standard), thus the following              character as defined in the ASCII standard <xref target="RFC20"/>),
65              example:</t>              thus the following example:</t>
66    
67              <t>              <t>
68                  <list>                  <list>
# Line 2061  Schoenebeck'> Line 2061  Schoenebeck'>
2061                      or <xref target="LIST MIDI_INPUT_DEVICES">"LIST MIDI_INPUT_DEVICES"</xref>                      or <xref target="LIST MIDI_INPUT_DEVICES">"LIST MIDI_INPUT_DEVICES"</xref>
2062                      command, &lt;port&gt; by the MIDI port number, &lt;key&gt; by the name of                      command, &lt;port&gt; by the MIDI port number, &lt;key&gt; by the name of
2063                      the parameter to change and &lt;value&gt; by the new value for this                      the parameter to change and &lt;value&gt; by the new value for this
2064                      parameter.</t>                      parameter (encapsulated into apostrophes) or NONE (not encapsulated into apostrophes)
2065                        for specifying no value for parameters allowing a list of values.</t>
2066    
2067                      <t>Possible Answers:</t>                      <t>Possible Answers:</t>
2068                      <t>                      <t>
# Line 2088  Schoenebeck'> Line 2089  Schoenebeck'>
2089                      <t>Example:</t>                      <t>Example:</t>
2090                      <t>                      <t>
2091                          <list>                          <list>
2092                              <t></t>                              <t>C: "SET MIDI_INPUT_PORT_PARAMETER 0 0 ALSA_SEQ_BINDINGS='20:0'"</t>
2093                                <t>S: "OK"</t>
2094                            </list>
2095                        </t>
2096                        <t>
2097                            <list>
2098                                <t>C: "SET MIDI_INPUT_PORT_PARAMETER 0 0 ALSA_SEQ_BINDINGS=NONE"</t>
2099                                <t>S: "OK"</t>
2100                          </list>                          </list>
2101                      </t>                      </t>
2102                  </section>                  </section>
# Line 2113  Schoenebeck'> Line 2121  Schoenebeck'>
2121                      number of the sampler channel the instrument should be assigned to.                      number of the sampler channel the instrument should be assigned to.
2122                      Each sampler channel can only have one instrument.</t>                      Each sampler channel can only have one instrument.</t>
2123    
2124                        <t>Notice: since LSCP 1.2 the &lt;filename&gt; argument supports
2125                        escape characters for special characters (see chapter
2126                        "<xref target="character_set">Character Set and Escape Sequences</xref>"
2127                        for details) and accordingly backslash characters in the filename
2128                        MUST now be escaped as well!</t>
2129    
2130                      <t>The difference between regular and NON_MODAL versions of the command                      <t>The difference between regular and NON_MODAL versions of the command
2131                      is that the regular command returns OK only after the instrument has been                      is that the regular command returns OK only after the instrument has been
2132                      fully loaded and the channel is ready to be used while NON_MODAL version                      fully loaded and the channel is ready to be used while NON_MODAL version
# Line 2148  Schoenebeck'> Line 2162  Schoenebeck'>
2162                              </t>                              </t>
2163                          </list>                          </list>
2164                      </t>                      </t>
2165                      <t>Example:</t>                      <t>Example (Unix):</t>
2166                      <t>                      <t>
2167                          <list>                          <list>
2168                              <t></t>                              <t>C: LOAD INSTRUMENT '/home/joe/gigs/cello.gig' 0 0</t>
2169                                <t>S: OK</t>
2170                            </list>
2171                        </t>
2172                        <t>Example (Windows):</t>
2173                        <t>
2174                            <list>
2175                                <t>C: LOAD INSTRUMENT 'D:/MySounds/cello.gig' 0 0</t>
2176                                <t>S: OK</t>
2177                          </list>                          </list>
2178                      </t>                      </t>
2179                  </section>                  </section>
# Line 2429  Schoenebeck'> Line 2451  Schoenebeck'>
2451                                  <list>                                  <list>
2452                                      <t>DESCRIPTION -                                      <t>DESCRIPTION -
2453                                          <list>                                          <list>
2454                                              <t>arbitrary description text about the engine</t>                                              <t>arbitrary description text about the engine
2455                                                (note that the character string may contain
2456                                                <xref target="character_set">escape sequences</xref>)</t>
2457                                          </list>                                          </list>
2458                                      </t>                                      </t>
2459                                       <t>VERSION -                                       <t>VERSION -
# Line 2488  Schoenebeck'> Line 2512  Schoenebeck'>
2512                                          <list>                                          <list>
2513                                              <t>numerical ID of the audio output device which is                                              <t>numerical ID of the audio output device which is
2514                                              currently connected to this sampler channel to output                                              currently connected to this sampler channel to output
2515                                              the audio signal, "NONE" if there's no device                                              the audio signal, "-1" if there's no device
2516                                              connected to this sampler channel</t>                                              connected to this sampler channel</t>
2517                                          </list>                                          </list>
2518                                      </t>                                      </t>
# Line 2513  Schoenebeck'> Line 2537  Schoenebeck'>
2537                                          <list>                                          <list>
2538                                              <t>the file name of the loaded instrument, "NONE" if                                              <t>the file name of the loaded instrument, "NONE" if
2539                                              there's no instrument yet loaded for this sampler                                              there's no instrument yet loaded for this sampler
2540                                              channel</t>                                              channel (note: since LSCP 1.2 this path may contain
2541                                                <xref target="character_set">escape sequences</xref>)</t>
2542                                          </list>                                          </list>
2543                                      </t>                                      </t>
2544                                      <t>INSTRUMENT_NR -                                      <t>INSTRUMENT_NR -
2545                                          <list>                                          <list>
2546                                              <t>the instrument index number of the loaded instrument</t>                                              <t>the instrument index number of the loaded instrument,
2547                                                "-1" if there's no instrument loaded for this sampler
2548                                                channel</t>
2549                                          </list>                                          </list>
2550                                      </t>                                      </t>
2551                                      <t>INSTRUMENT_NAME -                                      <t>INSTRUMENT_NAME -
2552                                          <list>                                          <list>
2553                                              <t>the instrument name of the loaded instrument</t>                                              <t>the instrument name of the loaded instrument
2554                                                (note: since LSCP 1.2 this character string may contain
2555                                                <xref target="character_set">escape sequences</xref>)</t>
2556                                          </list>                                          </list>
2557                                      </t>                                      </t>
2558                                      <t>INSTRUMENT_STATUS -                                      <t>INSTRUMENT_STATUS -
2559                                          <list>                                          <list>
2560                                              <t>integer values 0 to 100 indicating loading progress percentage for the instrument. Negative                                              <t>Integer values 0 to 100 indicating loading progress
2561                                              value indicates a loading exception. Value of 100 indicates that the instrument is fully                                              percentage for the instrument. Negative
2562                                                value indicates a loading exception (also returns "-1" in case no
2563                                                instrument was yet to be loaded on the sampler channel).
2564                                                Value of 100 indicates that the instrument is fully
2565                                              loaded.</t>                                              loaded.</t>
2566                                          </list>                                          </list>
2567                                      </t>                                      </t>
# Line 2537  Schoenebeck'> Line 2569  Schoenebeck'>
2569                                          <list>                                          <list>
2570                                              <t>numerical ID of the MIDI input device which is                                              <t>numerical ID of the MIDI input device which is
2571                                              currently connected to this sampler channel to deliver                                              currently connected to this sampler channel to deliver
2572                                              MIDI input commands, "NONE" if there's no device                                              MIDI input commands, "-1" if there's no device
2573                                              connected to this sampler channel</t>                                              connected to this sampler channel</t>
2574                                          </list>                                          </list>
2575                                      </t>                                      </t>
2576                                      <t>MIDI_INPUT_PORT -                                      <t>MIDI_INPUT_PORT -
2577                                          <list>                                          <list>
2578                                              <t>port number of the MIDI input device</t>                                              <t>port number of the MIDI input device (in case a
2579                                                MIDI device was already assigned to the sampler
2580                                                channel)</t>
2581                                          </list>                                          </list>
2582                                      </t>                                      </t>
2583                                      <t>MIDI_INPUT_CHANNEL -                                      <t>MIDI_INPUT_CHANNEL -
# Line 3241  Schoenebeck'> Line 3275  Schoenebeck'>
3275                      sampler channel on which the effect send should be created on, &lt;midi-ctrl&gt;                      sampler channel on which the effect send should be created on, &lt;midi-ctrl&gt;
3276                      is a number between 0..127 defining the MIDI controller which can alter the                      is a number between 0..127 defining the MIDI controller which can alter the
3277                      effect send level and &lt;name&gt; is an optional argument defining a name                      effect send level and &lt;name&gt; is an optional argument defining a name
3278                      for the effect send entity. The name does not have to be unique.</t>                      for the effect send entity. The name does not have to be unique, but MUST be
3279                        encapsulated into apostrophes and supports escape sequences as described in chapter
3280                        "<xref target="character_set">Character Set and Escape Sequences</xref>".</t>
3281    
3282                      <t>By default, that is as initial routing, the effect send's audio channels                      <t>By default, that is as initial routing, the effect send's audio channels
3283                      are automatically routed to the last audio channels of the sampler channel's                      are automatically routed to the last audio channels of the sampler channel's
# Line 3431  Schoenebeck'> Line 3467  Schoenebeck'>
3467                                  <list>                                  <list>
3468                                      <t>NAME -                                      <t>NAME -
3469                                          <list>                                          <list>
3470                                              <t>name of the effect send entity</t>                                              <t>name of the effect send entity
3471                                                (note that this character string may contain
3472                                                 <xref target="character_set">escape sequences</xref>)</t>
3473                                          </list>                                          </list>
3474                                      </t>                                      </t>
3475                                      <t>MIDI_CONTROLLER -                                      <t>MIDI_CONTROLLER -
# Line 3457  Schoenebeck'> Line 3495  Schoenebeck'>
3495                                              channel 1 is routed to the channel 3 of the audio                                              channel 1 is routed to the channel 3 of the audio
3496                                              output device (see                                              output device (see
3497                                              <xref target="SET FX_SEND AUDIO_OUTPUT_CHANNEL">"SET FX_SEND AUDIO_OUTPUT_CHANNEL"</xref>                                              <xref target="SET FX_SEND AUDIO_OUTPUT_CHANNEL">"SET FX_SEND AUDIO_OUTPUT_CHANNEL"</xref>
3498                                              for details)</t>                                              for details), if an internal send
3499                                                effect is assigned to the effect
3500                                                send, then this setting defines the
3501                                                audio channel routing to that
3502                                                effect instance respectively</t>
3503                                            </list>
3504                                        </t>
3505                                        <t>EFFECT -
3506                                            <list>
3507                                                <t>destination send effect chain ID
3508                                                and destination effect chain
3509                                                position, separated by comma in the
3510                                                form "&lt;effect-chain&gt;,&lt;chain-pos&gt;"
3511                                                or "NONE" if there is no send effect
3512                                                assigned to the effect send</t>
3513                                          </list>                                          </list>
3514                                      </t>                                      </t>
3515                                  </list>                                  </list>
# Line 3474  Schoenebeck'> Line 3526  Schoenebeck'>
3526                              <t>&nbsp;&nbsp;&nbsp;"MIDI_CONTROLLER: 91"</t>                              <t>&nbsp;&nbsp;&nbsp;"MIDI_CONTROLLER: 91"</t>
3527                              <t>&nbsp;&nbsp;&nbsp;"LEVEL: 0.3"</t>                              <t>&nbsp;&nbsp;&nbsp;"LEVEL: 0.3"</t>
3528                              <t>&nbsp;&nbsp;&nbsp;"AUDIO_OUTPUT_ROUTING: 2,3"</t>                              <t>&nbsp;&nbsp;&nbsp;"AUDIO_OUTPUT_ROUTING: 2,3"</t>
3529                                <t>&nbsp;&nbsp;&nbsp;"EFFECT: NONE"</t>
3530                                <t>&nbsp;&nbsp;&nbsp;"."</t>
3531                            </list>
3532                        </t>
3533                        <t>
3534                            <list>
3535                                <t>C: "GET FX_SEND INFO 0 1"</t>
3536                                <t>S: "NAME: Delay Send (Internal)"</t>
3537                                <t>&nbsp;&nbsp;&nbsp;"MIDI_CONTROLLER: 93"</t>
3538                                <t>&nbsp;&nbsp;&nbsp;"LEVEL: 0.51"</t>
3539                                <t>&nbsp;&nbsp;&nbsp;"AUDIO_OUTPUT_ROUTING: 1,2"</t>
3540                                <t>&nbsp;&nbsp;&nbsp;"EFFECT: 2,0"</t>
3541                              <t>&nbsp;&nbsp;&nbsp;"."</t>                              <t>&nbsp;&nbsp;&nbsp;"."</t>
3542                          </list>                          </list>
3543                      </t>                      </t>
# Line 3494  Schoenebeck'> Line 3558  Schoenebeck'>
3558                      as returned by the <xref target="CREATE FX_SEND">"CREATE FX_SEND"</xref>                      as returned by the <xref target="CREATE FX_SEND">"CREATE FX_SEND"</xref>
3559                      or <xref target="LIST FX_SENDS">"LIST FX_SENDS"</xref> command and                      or <xref target="LIST FX_SENDS">"LIST FX_SENDS"</xref> command and
3560                      &lt;name&gt; is the new name of the effect send entity, which                      &lt;name&gt; is the new name of the effect send entity, which
3561                      does not have to be unique.</t>                      does not have to be unique (name MUST be encapsulated into apostrophes
3562                        and supports escape sequences as described in chapter
3563                        "<xref target="character_set">Character Set and Escape Sequences</xref>").
3564                        </t>
3565    
3566                      <t>Possible Answers:</t>                      <t>Possible Answers:</t>
3567                      <t>                      <t>
# Line 3537  Schoenebeck'> Line 3604  Schoenebeck'>
3604                      &lt;audio-src&gt; is the numerical ID of the effect send's audio channel                      &lt;audio-src&gt; is the numerical ID of the effect send's audio channel
3605                      which should be rerouted and &lt;audio-dst&gt; is the numerical ID of                      which should be rerouted and &lt;audio-dst&gt; is the numerical ID of
3606                      the audio channel of the selected audio output device where &lt;audio-src&gt;                      the audio channel of the selected audio output device where &lt;audio-src&gt;
3607                      should be routed to.</t>                      should be routed to. If an internal send effect is assigned
3608                        to the effect send, then this setting defines the audio
3609                        channel routing to that effect instance respectively.</t>
3610    
3611                      <t>Note that effect sends can only route audio to the same audio output                      <t>Note that effect sends can only route audio to the same audio output
3612                      device as assigned to the effect send's sampler channel. Also note that an                      device as assigned to the effect send's sampler channel. Also note that an
# Line 3580  Schoenebeck'> Line 3649  Schoenebeck'>
3649                      </t>                      </t>
3650                  </section>                  </section>
3651    
3652                    <section title="Assigning destination effect to an effect send" anchor="SET FX_SEND EFFECT">
3653                        <t>The front-end can (re-)assign a destination effect to an
3654                        effect send by sending the following command:</t>
3655                        <t>
3656                            <list>
3657                                <t>SET FX_SEND EFFECT &lt;sampler-chan&gt; &lt;fx-send-id&gt; &lt;effect-chain&gt; &lt;chain-pos&gt;</t>
3658                            </list>
3659                        </t>
3660                        <t>Where &lt;sampler-chan&gt; is the sampler channel number
3661                        as returned by the <xref target="ADD CHANNEL">"ADD CHANNEL"</xref>
3662                        or <xref target="LIST CHANNELS">"LIST CHANNELS"</xref> command,
3663                        &lt;fx-send-id&gt; reflects the numerical ID of the effect send entity
3664                        as returned by the <xref target="CREATE FX_SEND">"CREATE FX_SEND"</xref>
3665                        or <xref target="LIST FX_SENDS">"LIST FX_SENDS"</xref> command,
3666                        &lt;effect-chain&gt; by the numerical ID of the destination
3667                        effect chain as returned by the
3668                        <xref target="ADD SEND_EFFECT_CHAIN">"ADD SEND_EFFECT_CHAIN"</xref>
3669                        or
3670                        <xref target="LIST SEND_EFFECT_CHAINS">"LIST SEND_EFFECT_CHAINS"</xref>
3671                        command and &lt;chain-pos&gt; reflects the exact effect
3672                        chain position in the effect chain which hosts the actual
3673                        destination effect.</t>
3674    
3675                        <t>Possible Answers:</t>
3676                        <t>
3677                            <list>
3678                                <t>"OK" -
3679                                    <list>
3680                                        <t>on success</t>
3681                                    </list>
3682                                </t>
3683                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
3684                                    <list>
3685                                        <t>in case it failed, providing an appropriate error code and error message</t>
3686                                    </list>
3687                                </t>
3688                            </list>
3689                        </t>
3690                        <t>Example:</t>
3691                        <t>
3692                            <list>
3693                                <t>C: "SET FX_SEND EFFECT 0 0 2 5"</t>
3694                                <t>S: "OK"</t>
3695                            </list>
3696                        </t>
3697                    </section>
3698    
3699                    <section title="Removing destination effect from an effect send" anchor="REMOVE FX_SEND EFFECT">
3700                        <t>The front-end can (re-)assign a destination effect to an
3701                        effect send by sending the following command:</t>
3702                        <t>
3703                            <list>
3704                                <t>REMOVE FX_SEND EFFECT &lt;sampler-chan&gt; &lt;fx-send-id&gt;</t>
3705                            </list>
3706                        </t>
3707                        <t>Where &lt;sampler-chan&gt; is the sampler channel number
3708                        as returned by the <xref target="ADD CHANNEL">"ADD CHANNEL"</xref>
3709                        or <xref target="LIST CHANNELS">"LIST CHANNELS"</xref> command,
3710                        &lt;fx-send-id&gt; reflects the numerical ID of the effect send entity
3711                        as returned by the <xref target="CREATE FX_SEND">"CREATE FX_SEND"</xref>
3712                        or <xref target="LIST FX_SENDS">"LIST FX_SENDS"</xref> command.</t>
3713    
3714                        <t>After the destination effect has been removed from the
3715                        effect send, the audio signal of the effect send will be
3716                        routed directly to the audio output device, according to the
3717                        audio channel routing setting of the effect send.
3718                        </t>
3719    
3720                        <t>Possible Answers:</t>
3721                        <t>
3722                            <list>
3723                                <t>"OK" -
3724                                    <list>
3725                                        <t>on success</t>
3726                                    </list>
3727                                </t>
3728                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
3729                                    <list>
3730                                        <t>in case it failed, providing an appropriate error code and error message</t>
3731                                    </list>
3732                                </t>
3733                            </list>
3734                        </t>
3735                        <t>Example:</t>
3736                        <t>
3737                            <list>
3738                                <t>C: "REMOVE FX_SEND EFFECT 0 0"</t>
3739                                <t>S: "OK"</t>
3740                            </list>
3741                        </t>
3742                    </section>
3743    
3744                  <section title="Altering effect send's MIDI controller" anchor="SET FX_SEND MIDI_CONTROLLER">                  <section title="Altering effect send's MIDI controller" anchor="SET FX_SEND MIDI_CONTROLLER">
3745                      <t>The front-end can alter the MIDI controller of an effect                      <t>The front-end can alter the MIDI controller of an effect
3746                      send entity by sending the following command:</t>                      send entity by sending the following command:</t>
# Line 3677  Schoenebeck'> Line 3838  Schoenebeck'>
3838                      </t>                      </t>
3839                  </section>                  </section>
3840    
3841                    <section title="Sending MIDI messages to sampler channel" anchor="SEND CHANNEL MIDI_DATA">
3842                        <t>The front-end can send MIDI events to a specific sampler channel
3843                        by sending the following command:</t>
3844                        <t>
3845                            <list>
3846                                <t>SEND CHANNEL MIDI_DATA &lt;midi-msg&gt; &lt;sampler-chan&gt; &lt;arg1&gt; &lt;arg2&gt;</t>
3847                            </list>
3848                        </t>
3849                        <t>Where &lt;sampler-chan&gt; is the sampler channel number
3850                        as returned by the <xref target="ADD CHANNEL">"ADD CHANNEL"</xref>
3851                        or <xref target="LIST CHANNELS">"LIST CHANNELS"</xref> command,
3852                        &lt;arg1&gt; and &lt;arg2&gt; arguments depend on the &lt;midi-msg&gt; argument, which
3853                        specifies the MIDI message type. Currently, the following MIDI messages are supported:</t>
3854                        <t>
3855                            <list>
3856                                <t>"NOTE_ON" -
3857                                    <list>
3858                                        <t>For turning on MIDI notes, where &lt;arg1&gt;
3859                                        specifies the key number and &lt;arg2&gt; the velocity
3860                                        as described in the MIDI specification.</t>
3861                                    </list>
3862                                </t>
3863                                <t>"NOTE_OFF" -
3864                                    <list>
3865                                        <t>For turning a currently playing MIDI note off, where &lt;arg1&gt;
3866                                        specifies the key number and &lt;arg2&gt; the velocity
3867                                        as described in the MIDI specification.</t>
3868                                    </list>
3869                                </t>
3870                                <t>"CC" -
3871                                    <list>
3872                                        <t>For changing a MIDI controller, where &lt;arg1&gt;
3873                                        specifies the controller number and &lt;arg2&gt; the
3874                                        new value of the controller as described in the Control
3875                                        Change section of the MIDI specification.</t>
3876                                    </list>
3877                                </t>
3878                            </list>
3879                        </t>
3880                        <t>CAUTION: This command is provided for implementations of virtual MIDI keyboards
3881                        and no realtime guarantee whatsoever will be made!</t>
3882                        <t>Possible Answers:</t>
3883                        <t>
3884                            <list>
3885                                <t>"OK" -
3886                                    <list>
3887                                        <t>on success</t>
3888                                    </list>
3889                                </t>
3890                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
3891                                    <list>
3892                                        <t>in case it failed, providing an appropriate error code and error message</t>
3893                                    </list>
3894                                </t>
3895                            </list>
3896                        </t>
3897                        <t>Example:</t>
3898                        <t>
3899                            <list>
3900                                <t>C: "SEND CHANNEL MIDI_DATA NOTE_ON 0 56 112"</t>
3901                                <t>S: "OK"</t>
3902                            </list>
3903                        </t>
3904                    </section>
3905    
3906                  <section title="Resetting a sampler channel" anchor="RESET CHANNEL">                  <section title="Resetting a sampler channel" anchor="RESET CHANNEL">
3907                      <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>
3908                      <t>                      <t>
# Line 3898  Schoenebeck'> Line 4124  Schoenebeck'>
4124                      </t>                      </t>
4125                  </section>                  </section>
4126    
4127                    <section title="Current number of active disk streams" anchor="GET TOTAL_STREAM_COUNT">
4128                        <t>The front-end can ask for the current number of active disk streams on
4129                        the sampler by sending the following command:</t>
4130                        <t>
4131                            <list>
4132                                <t>GET TOTAL_STREAM_COUNT</t>
4133                            </list>
4134                        </t>
4135    
4136                        <t>Possible Answers:</t>
4137                        <t>
4138                            <list>
4139                                <t>LinuxSampler will answer by returning the number of all active
4140                                disk streams on the sampler.</t>
4141                            </list>
4142                        </t>
4143                    </section>
4144    
4145                  <section title="Reset sampler" anchor="RESET">                  <section title="Reset sampler" anchor="RESET">
4146                      <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>
4147                      <t>                      <t>
# Line 3945  Schoenebeck'> Line 4189  Schoenebeck'>
4189                                  <list>                                  <list>
4190                                      <t>DESCRIPTION -                                      <t>DESCRIPTION -
4191                                          <list>                                          <list>
4192                                              <t>arbitrary textual description about the sampler</t>                                              <t>arbitrary textual description about the sampler
4193                                                (note that the character string may contain
4194                                                <xref target="character_set">escape sequences</xref>)</t>
4195                                          </list>                                          </list>
4196                                      </t>                                      </t>
4197                                      <t>VERSION -                                      <t>VERSION -
# Line 3959  Schoenebeck'> Line 4205  Schoenebeck'>
4205                                              complies with (see <xref target="LSCP versioning" /> for details)</t>                                              complies with (see <xref target="LSCP versioning" /> for details)</t>
4206                                          </list>                                          </list>
4207                                      </t>                                      </t>
4208                                        <t>INSTRUMENTS_DB_SUPPORT -
4209                                            <list>
4210                                                <t>either yes or no, specifies whether the
4211                                                sampler is build with instruments database support.</t>
4212                                            </list>
4213                                        </t>
4214                                  </list>                                  </list>
4215                              </t>                              </t>
4216                          </list>                          </list>
# Line 4025  Schoenebeck'> Line 4277  Schoenebeck'>
4277                          </list>                          </list>
4278                      </t>                      </t>
4279                  </section>                  </section>
4280    
4281                    <section title="Getting global voice limit" anchor="GET VOICES">
4282                        <t>The client can ask for the current global sampler-wide limit
4283                           for maximum voices by sending the following command:</t>
4284                        <t>
4285                            <list>
4286                                <t>GET VOICES</t>
4287                            </list>
4288                        </t>
4289                        <t>Possible Answers:</t>
4290                        <t>
4291                            <list>
4292                                <t>LinuxSampler will answer by returning the number for
4293                                   the current limit of maximum voices.</t>
4294                            </list>
4295                        </t>
4296    
4297                        <t>The voice limit setting defines how many voices should maximum
4298                           be processed by the sampler at the same time. If the user
4299                           triggers new notes which would exceed that voice limit, the
4300                           sampler engine will react by stealing old voices for those
4301                           newly triggered notes. Note that the amount of voices triggered
4302                           by a new note can be larger than one and is dependent to the
4303                           respective instrument and probably further criterias.</t>
4304                    </section>
4305    
4306                    <section title="Setting global voice limit" anchor="SET VOICES">
4307                        <t>The client can alter the current global sampler-wide limit
4308                        for maximum voices by sending the following command:</t>
4309                        <t>
4310                            <list>
4311                                <t>SET VOICES &lt;max-voices&gt;</t>
4312                            </list>
4313                        </t>
4314                       <t>Where &lt;max-voices&gt; should be replaced by the integer
4315                       value, reflecting the new global amount limit of maximum voices.
4316                       This value has to be larger than 0.</t>
4317    
4318                        <t>Possible Answers:</t>
4319                        <t>
4320                            <list>
4321                                <t>"OK" -
4322                                    <list>
4323                                        <t>on success</t>
4324                                    </list>
4325                                </t>
4326                                <t>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
4327                                    <list>
4328                                        <t>if the voice limit was set, but there are noteworthy
4329                                        issue(s) related, providing an appropriate warning code and
4330                                        warning message</t>
4331                                    </list>
4332                                </t>
4333                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
4334                                    <list>
4335                                        <t>in case it failed, providing an appropriate error code and error message</t>
4336                                    </list>
4337                                </t>
4338                            </list>
4339                        </t>
4340    
4341                        <t>Note: the given value will be passed to all sampler engine instances.
4342                           The total amount of maximum voices on the running system might thus
4343                           be as big as the given value multiplied by the current amount of engine
4344                           instances.</t>
4345    
4346                         <t>Caution: when adjusting the voice limit, you SHOULD also
4347                            adjust the disk stream limit respectively and vice versa.</t>
4348                    </section>
4349    
4350                    <section title="Getting global disk stream limit" anchor="GET STREAMS">
4351                        <t>The client can ask for the current global sampler-wide limit
4352                           for maximum disk streams by sending the following command:</t>
4353                        <t>
4354                            <list>
4355                                <t>GET STREAMS</t>
4356                            </list>
4357                        </t>
4358                        <t>Possible Answers:</t>
4359                        <t>
4360                            <list>
4361                                <t>LinuxSampler will answer by returning the number for
4362                                   the current limit of maximum disk streams.</t>
4363                            </list>
4364                        </t>
4365    
4366                        <t>The disk stream limit setting defines how many disk streams should
4367                           maximum be processed by a sampler engine at the same time. The
4368                           higher this value, the more memory (RAM) will be occupied, since
4369                           every disk streams allocates a certain buffer size for being able
4370                           to perform its streaming operations.</t>
4371                    </section>
4372    
4373                    <section title="Setting global disk stream limit" anchor="SET STREAMS">
4374                        <t>The client can alter the current global sampler-wide limit
4375                        for maximum disk streams by sending the following command:</t>
4376                        <t>
4377                            <list>
4378                                <t>SET STREAMS &lt;max-streams&gt;</t>
4379                            </list>
4380                        </t>
4381                       <t>Where &lt;max-streams&gt; should be replaced by the integer
4382                       value, reflecting the new global amount limit of maximum disk streams.
4383                       This value has to be positive.</t>
4384    
4385                        <t>Possible Answers:</t>
4386                        <t>
4387                            <list>
4388                                <t>"OK" -
4389                                    <list>
4390                                        <t>on success</t>
4391                                    </list>
4392                                </t>
4393                                <t>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
4394                                    <list>
4395                                        <t>if the disk stream limit was set, but there are noteworthy
4396                                        issue(s) related, providing an appropriate warning code and
4397                                        warning message</t>
4398                                    </list>
4399                                </t>
4400                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
4401                                    <list>
4402                                        <t>in case it failed, providing an appropriate error code and error message</t>
4403                                    </list>
4404                                </t>
4405                            </list>
4406                        </t>
4407    
4408                        <t>Note: the given value will be passed to all sampler engine instances.
4409                           The total amount of maximum disk streams on the running system might
4410                           thus be as big as the given value multiplied by the current amount of
4411                           engine instances.</t>
4412    
4413                         <t>Caution: when adjusting the disk stream limit, you SHOULD also
4414                            adjust the voice limit respectively and vice versa.</t>
4415                    </section>
4416    
4417              </section>              </section>
4418    
4419    
# Line 4055  Schoenebeck'> Line 4444  Schoenebeck'>
4444                  cause the sampler to switch to the respective instrument as                  cause the sampler to switch to the respective instrument as
4445                  reflected by the current MIDI instrument map.</t>                  reflected by the current MIDI instrument map.</t>
4446    
4447                  <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">
4448                      <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
4449                      the following command:</t>                      the following command:</t>
4450                      <t>                      <t>
# Line 4065  Schoenebeck'> Line 4454  Schoenebeck'>
4454                      </t>                      </t>
4455                      <t>Where &lt;name&gt; is an optional argument allowing to                      <t>Where &lt;name&gt; is an optional argument allowing to
4456                      assign a custom name to the new map. MIDI instrument Map                      assign a custom name to the new map. MIDI instrument Map
4457                      names do not have to be unique.</t>                      names do not have to be unique, but MUST be encapsulated
4458                        into apostrophes and support escape sequences as described
4459                        in chapter "<xref target="character_set">Character Set and Escape Sequences</xref>".
4460                        </t>
4461    
4462                      <t>Possible Answers:</t>                      <t>Possible Answers:</t>
4463                      <t>                      <t>
# Line 4236  Schoenebeck'> Line 4628  Schoenebeck'>
4628                                      <t>NAME -                                      <t>NAME -
4629                                          <list>                                          <list>
4630                                              <t>custom name of the given map,                                              <t>custom name of the given map,
4631                                              which does not have to be unique</t>                                              which does not have to be unique
4632                                                (note that this character string may contain
4633                                                 <xref target="character_set">escape sequences</xref>)</t>
4634                                          </list>                                          </list>
4635                                      </t>                                      </t>
4636                                      <t>DEFAULT -                                      <t>DEFAULT -
# Line 4272  Schoenebeck'> Line 4666  Schoenebeck'>
4666                      </t>                      </t>
4667                      <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
4668                      &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
4669                      have to be unique.</t>                      have to be unique (name MUST be encapsulated into apostrophes
4670                        and supports escape sequences as described in chapter
4671                        "<xref target="character_set">Character Set and Escape Sequences</xref>").
4672                        </t>
4673    
4674                      <t>Possible Answers:</t>                      <t>Possible Answers:</t>
4675                      <t>                      <t>
# Line 4319  Schoenebeck'> Line 4716  Schoenebeck'>
4716                      index, &lt;engine_name&gt; a sampler engine name as returned by                      index, &lt;engine_name&gt; a sampler engine name as returned by
4717                      the <xref target="LIST AVAILABLE_ENGINES">"LIST AVAILABLE_ENGINES"</xref>                      the <xref target="LIST AVAILABLE_ENGINES">"LIST AVAILABLE_ENGINES"</xref>
4718                      command (not encapsulated into apostrophes), &lt;filename&gt; the name                      command (not encapsulated into apostrophes), &lt;filename&gt; the name
4719                      of the instrument's file to be deployed (encapsulated into apostrophes),                      of the instrument's file to be deployed (encapsulated into apostrophes,
4720                        supporting escape sequences as described in chapter
4721                        "<xref target="character_set">Character Set and Escape Sequences</xref>"),
4722                      &lt;instrument_index&gt; the index (integer value) of the instrument                      &lt;instrument_index&gt; the index (integer value) of the instrument
4723                      within the given file, &lt;volume_value&gt; reflects the master                      within the given file, &lt;volume_value&gt; reflects the master
4724                      volume of the instrument as optionally dotted number (where a                      volume of the instrument as optionally dotted number (where a
# Line 4401  Schoenebeck'> Line 4800  Schoenebeck'>
4800                      load modes of entries, the frontend should retrieve the actual                      load modes of entries, the frontend should retrieve the actual
4801                      mode by i.e. sending                      mode by i.e. sending
4802                      <xref target="GET MIDI_INSTRUMENT INFO">"GET MIDI_INSTRUMENT INFO"</xref>                      <xref target="GET MIDI_INSTRUMENT INFO">"GET MIDI_INSTRUMENT INFO"</xref>
4803                      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
4804                      set a custom name (encapsulated into apostrophes) for the mapping                      (encapsulated into apostrophes, supporting escape sequences as described in chapter
4805                      entry, useful for frontends for displaying an appropriate name for                      "<xref target="character_set">Character Set and Escape Sequences</xref>") for the
4806                        mapping entry, useful for frontends for displaying an appropriate name for
4807                      mapped instruments (using                      mapped instruments (using
4808                      <xref target="GET MIDI_INSTRUMENT INFO">"GET MIDI_INSTRUMENT INFO"</xref>).                      <xref target="GET MIDI_INSTRUMENT INFO">"GET MIDI_INSTRUMENT INFO"</xref>).
4809                      </t>                      </t>
# Line 4627  Schoenebeck'> Line 5027  Schoenebeck'>
5027                                      name for this mapped instrument. It can be set and                                      name for this mapped instrument. It can be set and
5028                                      changed with the                                      changed with the
5029                                      <xref target="MAP MIDI_INSTRUMENT">"MAP MIDI_INSTRUMENT"</xref>                                      <xref target="MAP MIDI_INSTRUMENT">"MAP MIDI_INSTRUMENT"</xref>
5030                                      command and does not have to be unique.</t>                                      command and does not have to be unique.
5031                                        (note that this character string may contain
5032                                        <xref target="character_set">escape sequences</xref>)</t>
5033                                  </list>                                  </list>
5034                              </t>                              </t>
5035                              <t>"ENGINE_NAME" -                              <t>"ENGINE_NAME" -
# Line 4638  Schoenebeck'> Line 5040  Schoenebeck'>
5040                              </t>                              </t>
5041                              <t>"INSTRUMENT_FILE" -                              <t>"INSTRUMENT_FILE" -
5042                                  <list>                                  <list>
5043                                      <t>File name of the instrument.</t>                                      <t>File name of the instrument
5044                                        (note that this path may contain
5045                                        <xref target="character_set">escape sequences</xref>).</t>
5046                                  </list>                                  </list>
5047                              </t>                              </t>
5048                              <t>"INSTRUMENT_NR" -                              <t>"INSTRUMENT_NR" -
# Line 4650  Schoenebeck'> Line 5054  Schoenebeck'>
5054                                  <list>                                  <list>
5055                                      <t>Name of the loaded instrument as reflected by its file.                                      <t>Name of the loaded instrument as reflected by its file.
5056                                      In contrast to the "NAME" field, the "INSTRUMENT_NAME" field                                      In contrast to the "NAME" field, the "INSTRUMENT_NAME" field
5057                                      cannot be changed.</t>                                      cannot be changed (note that this character string may contain
5058                                        <xref target="character_set">escape sequences</xref>).</t>
5059                                  </list>                                  </list>
5060                              </t>                              </t>
5061                              <t>"LOAD_MODE" -                              <t>"LOAD_MODE" -
# Line 4734  Schoenebeck'> Line 5139  Schoenebeck'>
5139                  </section>                  </section>
5140              </section>              </section>
5141    
         </section>  
5142    
5143                <section title="Managing Instruments Database" anchor="Managing Instruments Database">
5144                    <t>The following commands describe how to use and manage
5145                    the instruments database.</t>
5146                    <t>Notice:</t>
5147                        <t>
5148                            <list>
5149                                <t>All command arguments representing a path or
5150                                instrument/directory name support escape sequences as described in chapter
5151                                "<xref target="character_set">Character Set and Escape Sequences</xref>".
5152                                </t>
5153                                <t>All occurrences of a forward slash in instrument and directory
5154                                   names are escaped with its hex (\x2f) or octal (\057) escape sequence.
5155                                </t>
5156                            </list>
5157                        </t>
5158    
5159                    <section title="Creating a new instrument directory" anchor="ADD DB_INSTRUMENT_DIRECTORY">
5160                        <t>The front-end can add a new instrument directory to the
5161                        instruments database by sending the following command:</t>
5162                        <t>
5163                            <list>
5164                                <t>ADD DB_INSTRUMENT_DIRECTORY &lt;dir&gt;</t>
5165                            </list>
5166                        </t>
5167                        <t>Where &lt;dir&gt; is the absolute path name of the directory
5168                        to be created (encapsulated into apostrophes).</t>
5169    
5170                        <t>Possible Answers:</t>
5171                        <t>
5172                            <list>
5173                                <t>"OK" -
5174                                    <list>
5175                                        <t>on success</t>
5176                                    </list>
5177                                </t>
5178                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
5179                                    <list>
5180                                        <t>when the directory could not be created, which
5181                                        can happen if the directory already exists or the
5182                                        name contains not allowed symbols</t>
5183                                    </list>
5184                                </t>
5185                            </list>
5186                        </t>
5187    
5188                        <t>Examples:</t>
5189                        <t>
5190                            <list>
5191                                <t>C: "ADD DB_INSTRUMENT_DIRECTORY '/Piano Collection'"</t>
5192                                <t>S: "OK"</t>
5193                            </list>
5194                        </t>
5195                    </section>
5196    
5197                    <section title="Deleting an instrument directory" anchor="REMOVE DB_INSTRUMENT_DIRECTORY">
5198                        <t>The front-end can delete a particular instrument directory
5199                        from the instruments database by sending the following command:</t>
5200                        <t>
5201                            <list>
5202                                <t>REMOVE DB_INSTRUMENT_DIRECTORY [FORCE] &lt;dir&gt;</t>
5203                            </list>
5204                        </t>
5205                        <t>Where &lt;dir&gt; is the absolute path name of the directory
5206                        to delete. The optional FORCE argument can be used to
5207                        force the deletion of a non-empty directory and all its content.</t>
5208    
5209                        <t>Possible Answers:</t>
5210                        <t>
5211                            <list>
5212                                <t>"OK" -
5213                                    <list>
5214                                        <t>if the directory is deleted successfully</t>
5215                                    </list>
5216                                </t>
5217                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
5218                                    <list>
5219                                        <t>if the given directory does not exist, or
5220                                        if trying to delete a non-empty directory,
5221                                        without using the FORCE argument.</t>
5222                                    </list>
5223                                </t>
5224                            </list>
5225                        </t>
5226    
5227                        <t>Examples:</t>
5228                        <t>
5229                            <list>
5230                                <t>C: "REMOVE DB_INSTRUMENT_DIRECTORY FORCE '/Piano Collection'"</t>
5231                                <t>S: "OK"</t>
5232                            </list>
5233                        </t>
5234                    </section>
5235    
5236                    <section title="Getting amount of instrument directories" anchor="GET DB_INSTRUMENT_DIRECTORIES">
5237                        <t>The front-end can retrieve the current amount of
5238                        directories in a specific directory by sending the following command:</t>
5239                        <t>
5240                            <list>
5241                                <t>GET DB_INSTRUMENT_DIRECTORIES [RECURSIVE] &lt;dir&gt;</t>
5242                            </list>
5243                        </t>
5244                        <t>Where &lt;dir&gt; should be replaced by the absolute path
5245                        name of the directory. If RECURSIVE is specified, the number of
5246                        all directories, including those located in subdirectories of the
5247                        specified directory, will be returned.</t>
5248    
5249                        <t>Possible Answers:</t>
5250                        <t>
5251                            <list>
5252                                <t>The current number of instrument directories
5253                                in the specified directory.</t>
5254                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
5255                                    <list>
5256                                        <t>if the given directory does not exist.</t>
5257                                    </list>
5258                                </t>
5259                            </list>
5260                        </t>
5261    
5262                        <t>Example:</t>
5263                        <t>
5264                            <list>
5265                                <t>C: "GET DB_INSTRUMENT_DIRECTORIES '/'"</t>
5266                                <t>S: "2"</t>
5267                            </list>
5268                        </t>
5269                    </section>
5270    
5271                    <section title="Listing all directories in specific directory" anchor="LIST DB_INSTRUMENT_DIRECTORIES">
5272                        <t>The front-end can retrieve the current list of directories
5273                        in specific directory by sending the following command:</t>
5274                        <t>
5275                            <list>
5276                                <t>LIST DB_INSTRUMENT_DIRECTORIES [RECURSIVE] &lt;dir&gt;</t>
5277                            </list>
5278                        </t>
5279                        <t>Where &lt;dir&gt; should be replaced by the absolute path
5280                        name of the directory. If RECURSIVE is specified, the absolute path names
5281                        of all directories, including those located in subdirectories of the
5282                        specified directory, will be returned.</t>
5283    
5284                        <t>Possible Answers:</t>
5285                        <t>
5286                            <list>
5287                                <t>A comma separated list of all instrument directories
5288                                (encapsulated into apostrophes) in the specified directory.</t>
5289                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
5290                                    <list>
5291                                        <t>if the given directory does not exist.</t>
5292                                    </list>
5293                                </t>
5294                            </list>
5295                        </t>
5296                        <t>Example:</t>
5297                        <t>
5298                            <list>
5299                                <t>C: "LIST DB_INSTRUMENT_DIRECTORIES '/'"</t>
5300                                <t>S: "'Piano Collection','Percussion Collection'"</t>
5301                            </list>
5302                        </t>
5303                        <t>
5304                            <list>
5305                                <t>C: "LIST DB_INSTRUMENT_DIRECTORIES RECURSIVE '/'"</t>
5306                                <t>S: "'/Piano Collection','/Piano Collection/Acoustic','/Piano Collection/Acoustic/New','/Percussion Collection'"</t>
5307                            </list>
5308                        </t>
5309                    </section>
5310    
5311                    <section title="Getting instrument directory information" anchor="GET DB_INSTRUMENT_DIRECTORY INFO">
5312                        <t>The front-end can ask for the current settings of an
5313                        instrument directory by sending the following command:</t>
5314                        <t>
5315                            <list>
5316                                <t>GET DB_INSTRUMENT_DIRECTORY INFO &lt;dir&gt;</t>
5317                            </list>
5318                        </t>
5319                        <t>Where &lt;dir&gt; should be replaced by the absolute path
5320                        name of the directory the front-end is interested in.</t>
5321    
5322                        <t>Possible Answers:</t>
5323                        <t>
5324                            <list>
5325                                <t>LinuxSampler will answer by sending a &lt;CRLF&gt; separated list.
5326                                Each answer line begins with the settings category name
5327                                followed by a colon and then a space character &lt;SP&gt; and finally
5328                                the info character string to that setting category. At the
5329                                moment the following categories are defined:</t>
5330    
5331                                <t>
5332                                    <list>
5333                                        <t>DESCRIPTION -
5334                                            <list>
5335                                                <t>A brief description of the directory content.
5336                                                Note that the character string may contain
5337                                                <xref target="character_set">escape sequences</xref>.</t>
5338                                            </list>
5339                                        </t>
5340                                        <t>CREATED -
5341                                            <list>
5342                                                <t>The creation date and time of the directory,
5343                                                represented in "YYYY-MM-DD HH:MM:SS" format</t>
5344                                            </list>
5345                                        </t>
5346                                        <t>MODIFIED -
5347                                            <list>
5348                                                <t>The date and time of the last modification of the
5349                                                directory, represented in "YYYY-MM-DD HH:MM:SS" format</t>
5350                                            </list>
5351                                        </t>
5352                                    </list>
5353                                </t>
5354                            </list>
5355                        </t>
5356                        <t>The mentioned fields above don't have to be in particular order.</t>
5357    
5358                        <t>Example:</t>
5359                        <t>
5360                            <list>
5361                                <t>C: "GET DB_INSTRUMENT_DIRECTORY INFO '/Piano Collection'"</t>
5362                                <t>S: "DESCRIPTION: Piano collection of instruments in GigaSampler format."</t>
5363                                <t>&nbsp;&nbsp;&nbsp;"CREATED: 2007-02-05 10:23:12"</t>
5364                                <t>&nbsp;&nbsp;&nbsp;"MODIFIED: 2007-04-07 12:50:21"</t>
5365                                <t>&nbsp;&nbsp;&nbsp;"."</t>
5366                            </list>
5367                        </t>
5368                    </section>
5369    
5370                    <section title="Renaming an instrument directory" anchor="SET DB_INSTRUMENT_DIRECTORY NAME">
5371                        <t>The front-end can alter the name of a specific
5372                        instrument directory by sending the following command:</t>
5373                        <t>
5374                            <list>
5375                                <t>SET DB_INSTRUMENT_DIRECTORY NAME &lt;dir&gt; &lt;name&gt;</t>
5376                            </list>
5377                        </t>
5378                        <t>Where &lt;dir&gt; is the absolute path name of the directory and
5379                        &lt;name&gt; is the new name for that directory.</t>
5380    
5381                        <t>Possible Answers:</t>
5382                        <t>
5383                            <list>
5384                                <t>"OK" -
5385                                    <list>
5386                                        <t>on success</t>
5387                                    </list>
5388                                </t>
5389                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
5390                                    <list>
5391                                        <t>in case the given directory does not exists,
5392                                        or if a directory with name equal to the new
5393                                        name already exists.</t>
5394                                    </list>
5395                                </t>
5396                            </list>
5397                        </t>
5398    
5399                        <t>Example:</t>
5400                        <t>
5401                            <list>
5402                                <t>C: "SET DB_INSTRUMENT_DIRECTORY NAME '/Piano Collection/Acustic' 'Acoustic'"</t>
5403                                <t>S: "OK"</t>
5404                            </list>
5405                        </t>
5406                    </section>
5407    
5408                    <section title="Moving an instrument directory" anchor="MOVE DB_INSTRUMENT_DIRECTORY">
5409                        <t>The front-end can move a specific
5410                        instrument directory by sending the following command:</t>
5411                        <t>
5412                            <list>
5413                                <t>MOVE DB_INSTRUMENT_DIRECTORY &lt;dir&gt; &lt;dst&gt;</t>
5414                            </list>
5415                        </t>
5416                        <t>Where &lt;dir&gt; is the absolute path name of the directory
5417                        to move and &lt;dst&gt; is the location where the directory will
5418                        be moved to.</t>
5419    
5420                        <t>Possible Answers:</t>
5421                        <t>
5422                            <list>
5423                                <t>"OK" -
5424                                    <list>
5425                                        <t>on success</t>
5426                                    </list>
5427                                </t>
5428                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
5429                                    <list>
5430                                        <t>in case a given directory does not exists,
5431                                        or if a directory with name equal to the name
5432                                        of the specified directory already exists in
5433                                        the destination directory. Error is also thrown
5434                                        when trying to move a directory to a subdirectory
5435                                        of itself.</t>
5436                                    </list>
5437                                </t>
5438                            </list>
5439                        </t>
5440    
5441                        <t>Example:</t>
5442                        <t>
5443                            <list>
5444                                <t>C: "MOVE DB_INSTRUMENT_DIRECTORY '/Acoustic' '/Piano Collection/Acoustic'"</t>
5445                                <t>S: "OK"</t>
5446                            </list>
5447                        </t>
5448                    </section>
5449    
5450                    <section title="Copying instrument directories" anchor="COPY DB_INSTRUMENT_DIRECTORY">
5451                        <t>The front-end can copy a specific
5452                        instrument directory by sending the following command:</t>
5453                        <t>
5454                            <list>
5455                                <t>COPY DB_INSTRUMENT_DIRECTORY &lt;dir&gt; &lt;dst&gt;</t>
5456                            </list>
5457                        </t>
5458                        <t>Where &lt;dir&gt; is the absolute path name of the directory
5459                        to copy and &lt;dst&gt; is the location where the directory will
5460                        be copied to.</t>
5461    
5462                        <t>Possible Answers:</t>
5463                        <t>
5464                            <list>
5465                                <t>"OK" -
5466                                    <list>
5467                                        <t>on success</t>
5468                                    </list>
5469                                </t>
5470                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
5471                                    <list>
5472                                        <t>in case a given directory does not exists,
5473                                        or if a directory with name equal to the name
5474                                        of the specified directory already exists in
5475                                        the destination directory. Error is also thrown
5476                                        when trying to copy a directory to a subdirectory
5477                                        of itself.</t>
5478                                    </list>
5479                                </t>
5480                            </list>
5481                        </t>
5482    
5483                        <t>Example:</t>
5484                        <t>
5485                            <list>
5486                                <t>C: "COPY DB_INSTRUMENT_DIRECTORY '/Piano Collection/Acoustic' '/Acoustic/Pianos'"</t>
5487                                <t>S: "OK"</t>
5488                            </list>
5489                        </t>
5490                    </section>
5491    
5492                    <section title="Changing the description of directory" anchor="SET DB_INSTRUMENT_DIRECTORY DESCRIPTION">
5493                        <t>The front-end can alter the description of a specific
5494                        instrument directory by sending the following command:</t>
5495                        <t>
5496                            <list>
5497                                <t>SET DB_INSTRUMENT_DIRECTORY DESCRIPTION &lt;dir&gt; &lt;desc&gt;</t>
5498                            </list>
5499                        </t>
5500                        <t>Where &lt;dir&gt; is the absolute path name of the directory and
5501                        &lt;desc&gt; is the new description for the directory
5502                        (encapsulated into apostrophes, supporting escape sequences as described in chapter
5503                        "<xref target="character_set">Character Set and Escape Sequences</xref>").</t>
5504    
5505                        <t>Possible Answers:</t>
5506                        <t>
5507                            <list>
5508                                <t>"OK" -
5509                                    <list>
5510                                        <t>on success</t>
5511                                    </list>
5512                                </t>
5513                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
5514                                    <list>
5515                                        <t>in case the given directory does not exists.</t>
5516                                    </list>
5517                                </t>
5518                            </list>
5519                        </t>
5520    
5521                        <t>Example:</t>
5522                        <t>
5523                            <list>
5524                                <t>C: "SET DB_INSTRUMENT_DIRECTORY DESCRIPTION '/Piano Collection' 'A collection of piano instruments in various format.'"</t>
5525                                <t>S: "OK"</t>
5526                            </list>
5527                        </t>
5528                    </section>
5529    
5530                    <section title="Finding directories" anchor="FIND DB_INSTRUMENT_DIRECTORIES">
5531                        <t>The front-end can search for directories
5532                        in specific directory by sending the following command:</t>
5533                        <t>
5534                            <list>
5535                                <t>FIND DB_INSTRUMENT_DIRECTORIES [NON_RECURSIVE] &lt;dir&gt; &lt;criteria-list&gt;</t>
5536                            </list>
5537                        </t>
5538                        <t>Where &lt;dir&gt; should be replaced by the absolute path
5539                        name of the directory to search in. If NON_RECURSIVE is specified, the
5540                        directories located in subdirectories of the specified directory will not
5541                        be searched. &lt;criteria-list&gt; is a list of search criterias
5542                        in form of "key1=val1 key2=val2 ...". The following criterias are
5543                        allowed:</t>
5544                        <t>
5545                          <t>NAME='&lt;search-string&gt;'
5546                              <list>
5547                                  <t>Restricts the search to directories, which names
5548                                  satisfy the supplied search string (encapsulated into apostrophes,
5549                                  supporting escape sequences as described in chapter
5550                                  "<xref target="character_set">Character Set and Escape Sequences</xref>").</t>
5551                              </list>
5552                          </t>
5553    
5554                          <t>CREATED='[&lt;date-after&gt;]..[&lt;date-before&gt;]'
5555                              <list>
5556                                  <t>Restricts the search to directories, which creation
5557                                  date satisfies the specified period, where &lt;date-after&gt;
5558                                  and &lt;date-before&gt; are in "YYYY-MM-DD HH:MM:SS" format.
5559                                  If &lt;date-after&gt; is omitted the search is restricted to
5560                                  directories created before &lt;date-before&gt;. If
5561                                  &lt;date-before&gt; is omitted, the search is restricted
5562                                  to directories created after &lt;date-after&gt;.</t>
5563                              </list>
5564                          </t>
5565    
5566                          <t>MODIFIED='[&lt;date-after&gt;]..[&lt;date-before&gt;]'
5567                              <list>
5568                                  <t>Restricts the search to directories, which
5569                                  date of last modification satisfies the specified period, where
5570                                  &lt;date-after&gt; and &lt;date-before&gt; are in "YYYY-MM-DD HH:MM:SS"
5571                                  format. If &lt;date-after&gt; is omitted the search is restricted to
5572                                  directories, which are last modified before &lt;date-before&gt;. If
5573                                  &lt;date-before&gt; is omitted, the search is restricted to directories,
5574                                  which are last modified after &lt;date-after&gt;.</t>
5575                              </list>
5576                          </t>
5577    
5578                          <t>DESCRIPTION='&lt;search-string&gt;'
5579                              <list>
5580                                  <t>Restricts the search to directories with description
5581                                  that satisfies the supplied search string
5582                                  (encapsulated into apostrophes, supporting escape
5583                                  sequences as described in chapter
5584                                  "<xref target="character_set">Character Set and Escape Sequences</xref>").</t>
5585                              </list>
5586                          </t>
5587                        </t>
5588    
5589                        <t>Where &lt;search-string&gt; is either a regular expression, or a
5590                        word list separated with spaces for OR search and with '+' for AND search.</t>
5591    
5592                        <t>Possible Answers:</t>
5593                        <t>
5594                            <list>
5595                                <t>A comma separated list with the absolute path names (encapsulated into
5596                                apostrophes) of all directories in the specified directory that satisfy
5597                                the supplied search criterias.</t>
5598                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
5599                                    <list>
5600                                        <t>if the given directory does not exist.</t>
5601                                    </list>
5602                                </t>
5603                            </list>
5604                        </t>
5605                        <t>Example:</t>
5606                        <t>
5607                            <list>
5608                                <t>C: "FIND DB_INSTRUMENT_DIRECTORIES '/' NAME='Piano'"</t>
5609                                <t>S: "'/Piano Collection'"</t>
5610                            </list>
5611                        </t>
5612                        <t>
5613                            <list>
5614                                <t>C: "FIND DB_INSTRUMENT_DIRECTORIES '/' CREATED='..2007-04-01 09:30:13'"</t>
5615                                <t>S: "'/Piano Collection','/Percussions'"</t>
5616                            </list>
5617                        </t>
5618                    </section>
5619    
5620                    <section title="Adding instruments to the instruments database" anchor="ADD DB_INSTRUMENTS">
5621                        <t>The front-end can add one or more instruments
5622                        to the instruments database by sending the following command:</t>
5623                        <t>
5624                            <list>
5625                                <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>
5626                            </list>
5627                        </t>
5628                        <t>Where &lt;db_dir&gt; is the absolute path name of a directory
5629                        (encapsulated into apostrophes) in the instruments database in which
5630                        only the new instruments (that are not already in the database) will
5631                        be added, &lt;file_path&gt; is the absolute path name of a file or
5632                        directory in the file system (encapsulated into apostrophes). In case
5633                        an instrument file is supplied, only the instruments in the specified
5634                        file will be added to the instruments database. If the optional
5635                        &lt;instr_index&gt; (the index of the instrument within the given file)
5636                        is supplied too, then only the specified instrument will be added.
5637                        In case a directory is supplied, the instruments in that directory
5638                        will be added. The OPTIONAL &lt;mode&gt; argument is only applied
5639                        when a directory is provided as &lt;file_path&gt; and specifies how the
5640                        scanning will be done and has exactly the following possibilities:</t>
5641                        <t>
5642                            <list>
5643                                <t>"RECURSIVE" -
5644                                    <list>
5645                                        <t>All instruments will be processed, including those
5646                                        in the subdirectories, and the respective subdirectory
5647                                        tree structure will be recreated in the instruments
5648                                        database</t>
5649                                    </list>
5650                                </t>
5651                                <t>"NON_RECURSIVE" -
5652                                    <list>
5653                                        <t>Only the instruments in the specified directory
5654                                        will be added, the instruments in the subdirectories
5655                                        will not be processed.</t>
5656                                    </list>
5657                                </t>
5658                                <t>"FLAT" -
5659                                    <list>
5660                                        <t>All instruments will be processed, including those
5661                                        in the subdirectories, but the respective subdirectory
5662                                        structure will not be recreated in the instruments
5663                                        database. All instruments will be added directly in
5664                                        the specified database directory.</t>
5665                                    </list>
5666                                </t>
5667                            </list>
5668                        </t>
5669    
5670                     <t> If FILE_AS_DIR argument is supplied, all instruments in an instrument
5671                     file will be added to a separate directory in the instruments database, which
5672                     name will be the name of the instrument file with the file extension stripped off.
5673                     </t>
5674                     <t>The difference between regular and NON_MODAL versions of the command
5675                        is that the regular command returns when the scanning is finished
5676                        while NON_MODAL version returns immediately and a background process is launched.
5677                        The <xref target="GET DB_INSTRUMENTS_JOB INFO">GET DB_INSTRUMENTS_JOB INFO</xref>
5678                        command can be used to monitor the scanning progress.</t>
5679    
5680                        <t>Possible Answers:</t>
5681                        <t>
5682                            <list>
5683                                <t>"OK" -
5684                                    <list>
5685                                        <t>on success when NON_MODAL is not supplied</t>
5686                                    </list>
5687                                </t>
5688                                <t>"OK[&lt;job-id&gt;]" -
5689                                    <list>
5690                                        <t>on success when NON_MODAL is supplied, where &lt;job-id&gt;
5691                                        is a numerical ID used to obtain status information about the job progress.
5692                                        See <xref target="GET DB_INSTRUMENTS_JOB INFO">GET DB_INSTRUMENTS_JOB INFO</xref>
5693                                        </t>
5694                                    </list>
5695                                </t>
5696                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
5697                                    <list>
5698                                        <t>if an invalid path is specified.</t>
5699                                    </list>
5700                                </t>
5701                            </list>
5702                        </t>
5703    
5704                        <t>Examples:</t>
5705                        <t>
5706                            <list>
5707                                <t>C: "ADD DB_INSTRUMENTS '/Piano Collection' '/home/me/gigs/PMI Bosendorfer 290.gig' 0"</t>
5708                                <t>S: "OK"</t>
5709                            </list>
5710                        </t>
5711                    </section>
5712    
5713                    <section title="Removing an instrument" anchor="REMOVE DB_INSTRUMENT">
5714                        <t>The front-end can remove a particular instrument
5715                        from the instruments database by sending the following command:</t>
5716                        <t>
5717                            <list>
5718                                <t>REMOVE DB_INSTRUMENT &lt;instr_path&gt;</t>
5719                            </list>
5720                        </t>
5721                        <t>Where &lt;instr_path&gt; is the absolute path name
5722                        (in the instruments database) of the instrument to remove.</t>
5723    
5724                        <t>Possible Answers:</t>
5725                        <t>
5726                            <list>
5727                                <t>"OK" -
5728                                    <list>
5729                                        <t>if the instrument is removed successfully</t>
5730                                    </list>
5731                                </t>
5732                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
5733                                    <list>
5734                                        <t>if the given path does not exist or
5735                                        is a directory.</t>
5736                                    </list>
5737                                </t>
5738                            </list>
5739                        </t>
5740    
5741                        <t>Examples:</t>
5742                        <t>
5743                            <list>
5744                                <t>C: "REMOVE DB_INSTRUMENT '/Piano Collection/Bosendorfer 290'"</t>
5745                                <t>S: "OK"</t>
5746                            </list>
5747                        </t>
5748                    </section>
5749    
5750                    <section title="Getting amount of instruments" anchor="GET DB_INSTRUMENTS">
5751                        <t>The front-end can retrieve the current amount of
5752                        instruments in a specific directory by sending the following command:</t>
5753                        <t>
5754                            <list>
5755                                <t>GET DB_INSTRUMENTS [RECURSIVE] &lt;dir&gt;</t>
5756                            </list>
5757                        </t>
5758                        <t>Where &lt;dir&gt; should be replaced by the absolute path name
5759                        of the directory. If RECURSIVE is specified, the number of all
5760                        instruments, including those located in subdirectories of the
5761                        specified directory, will be returned.</t>
5762    
5763                        <t>Possible Answers:</t>
5764                        <t>
5765                            <list>
5766                                <t>The current number of instruments
5767                                in the specified directory.</t>
5768                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
5769                                    <list>
5770                                        <t>if the given directory does not exist.</t>
5771                                    </list>
5772                                </t>
5773                            </list>
5774                        </t>
5775    
5776                        <t>Example:</t>
5777                        <t>
5778                            <list>
5779                                <t>C: "GET DB_INSTRUMENTS '/Piano Collection'"</t>
5780                                <t>S: "2"</t>
5781                            </list>
5782                        </t>
5783                    </section>
5784    
5785                    <section title="Listing all instruments in specific directory" anchor="LIST DB_INSTRUMENTS">
5786                        <t>The front-end can retrieve the current list of instruments
5787                        in specific directory by sending the following command:</t>
5788                        <t>
5789                            <list>
5790                                <t>LIST DB_INSTRUMENTS [RECURSIVE] &lt;dir&gt;</t>
5791                            </list>
5792                        </t>
5793                        <t>Where &lt;dir&gt; should be replaced by the absolute path
5794                        name of the directory. If RECURSIVE is specified, the absolute path
5795                        names of all instruments, including those located in subdirectories
5796                        of the specified directory, will be returned.</t>
5797    
5798                        <t>Possible Answers:</t>
5799                        <t>
5800                            <list>
5801                                <t>A comma separated list of all instruments
5802                                (encapsulated into apostrophes) in the specified directory.</t>
5803                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
5804                                    <list>
5805                                        <t>if the given directory does not exist.</t>
5806                                    </list>
5807                                </t>
5808                            </list>
5809                        </t>
5810                        <t>Example:</t>
5811                        <t>
5812                            <list>
5813                                <t>C: "LIST DB_INSTRUMENTS '/Piano Collection'"</t>
5814                                <t>S: "'Bosendorfer 290','Steinway D'"</t>
5815                            </list>
5816                        </t>
5817                        <t>
5818                            <list>
5819                                <t>C: "LIST DB_INSTRUMENTS RECURSIVE '/Piano Collection'"</t>
5820                                <t>S: "'/Piano Collection/Bosendorfer 290','/Piano Collection/Steinway D','/Piano Collection/Lite/Free Piano'"</t>
5821                            </list>
5822                        </t>
5823                    </section>
5824    
5825                    <section title="Getting instrument information" anchor="GET DB_INSTRUMENT INFO">
5826                        <t>The front-end can ask for the current settings of an
5827                        instrument by sending the following command:</t>
5828                        <t>
5829                            <list>
5830                                <t>GET DB_INSTRUMENT INFO &lt;instr_path&gt;</t>
5831                            </list>
5832                        </t>
5833                        <t>Where &lt;instr_path&gt; should be replaced by the absolute path
5834                        name of the instrument the front-end is interested in.</t>
5835    
5836                        <t>Possible Answers:</t>
5837                        <t>
5838                            <list>
5839                                <t>LinuxSampler will answer by sending a &lt;CRLF&gt; separated list.
5840                                Each answer line begins with the settings category name
5841                                followed by a colon and then a space character &lt;SP&gt; and finally
5842                                the info character string to that setting category. At the
5843                                moment the following categories are defined:</t>
5844    
5845                                <t>
5846                                    <list>
5847                                        <t>INSTRUMENT_FILE -
5848                                            <list>
5849                                                <t>File name of the instrument.
5850                                                Note that the character string may contain
5851                                                <xref target="character_set">escape sequences</xref>.</t>
5852                                            </list>
5853                                        </t>
5854                                        <t>INSTRUMENT_NR -
5855                                            <list>
5856                                                <t>Index of the instrument within the file.</t>
5857                                            </list>
5858                                        </t>
5859                                        <t>FORMAT_FAMILY -
5860                                            <list>
5861                                                <t>The format family of the instrument.</t>
5862                                            </list>
5863                                        </t>
5864                                        <t>FORMAT_VERSION -
5865                                            <list>
5866                                                <t>The format version of the instrument.</t>
5867                                            </list>
5868                                        </t>
5869                                        <t>SIZE -
5870                                            <list>
5871                                                <t>The size of the instrument in bytes.</t>
5872                                            </list>
5873                                        </t>
5874                                        <t>CREATED -
5875                                            <list>
5876                                                <t>The date and time when the instrument is added
5877                                                in the instruments database, represented in
5878                                               "YYYY-MM-DD HH:MM:SS" format</t>
5879                                            </list>
5880                                        </t>
5881                                        <t>MODIFIED -
5882                                            <list>
5883                                                <t>The date and time of the last modification of the
5884                                                instrument's database settings, represented in
5885                                                "YYYY-MM-DD HH:MM:SS" format</t>
5886                                            </list>
5887                                        </t>
5888                                        <t>DESCRIPTION -
5889                                            <list>
5890                                                <t>A brief description of the instrument.
5891                                                Note that the character string may contain
5892                                                <xref target="character_set">escape sequences</xref>.</t>
5893                                            </list>
5894                                        </t>
5895                                        <t>IS_DRUM -
5896                                            <list>
5897                                                <t>either true or false, determines whether the
5898                                                instrument is a drumkit or a chromatic instrument</t>
5899                                            </list>
5900                                        </t>
5901                                        <t>PRODUCT -
5902                                            <list>
5903                                                <t>The product title of the instrument.
5904                                                Note that the character string may contain
5905                                                <xref target="character_set">escape sequences</xref>.</t>
5906                                            </list>
5907                                        </t>
5908                                        <t>ARTISTS -
5909                                            <list>
5910                                                <t>Lists the artist names.
5911                                                Note that the character string may contain
5912                                                <xref target="character_set">escape sequences</xref>.</t>
5913                                            </list>
5914                                        </t>
5915                                        <t>KEYWORDS -
5916                                            <list>
5917                                                <t>Provides a list of keywords that refer to the instrument.
5918                                                Keywords are separated with semicolon and blank.
5919                                                Note that the character string may contain
5920                                                <xref target="character_set">escape sequences</xref>.</t>
5921                                            </list>
5922                                        </t>
5923                                    </list>
5924                                </t>
5925                            </list>
5926                        </t>
5927                        <t>The mentioned fields above don't have to be in particular order.</t>
5928    
5929                        <t>Example:</t>
5930                        <t>
5931                            <list>
5932                                <t>C: "GET DB_INSTRUMENT INFO '/Piano Collection/Bosendorfer 290'"</t>
5933                                <t>S: "INSTRUMENT_FILE: /home/me/gigs/Bosendorfer 290.gig"</t>
5934                                <t>&nbsp;&nbsp;&nbsp;"INSTRUMENT_NR: 0"</t>
5935                                <t>&nbsp;&nbsp;&nbsp;"FORMAT_FAMILY: GIG"</t>
5936                                <t>&nbsp;&nbsp;&nbsp;"FORMAT_VERSION: 2"</t>
5937                                <t>&nbsp;&nbsp;&nbsp;"SIZE: 2050871870"</t>
5938                                <t>&nbsp;&nbsp;&nbsp;"CREATED: 2007-02-05 10:23:12"</t>
5939                                <t>&nbsp;&nbsp;&nbsp;"MODIFIED: 2007-04-07 12:50:21"</t>
5940                                <t>&nbsp;&nbsp;&nbsp;"DESCRIPTION: "</t>
5941                                <t>&nbsp;&nbsp;&nbsp;"IS_DRUM: false"</t>
5942                                <t>&nbsp;&nbsp;&nbsp;"PRODUCT: GRANDIOSO Bosendorfer 290"</t>
5943                                <t>&nbsp;&nbsp;&nbsp;"ARTISTS: Post Musical Instruments"</t>
5944                                <t>&nbsp;&nbsp;&nbsp;"KEYWORDS: Bosendorfer"</t>
5945                                <t>&nbsp;&nbsp;&nbsp;"."</t>
5946                            </list>
5947                        </t>
5948                    </section>
5949    
5950                    <section title="Renaming an instrument" anchor="SET DB_INSTRUMENT NAME">
5951                        <t>The front-end can alter the name of a specific
5952                        instrument by sending the following command:</t>
5953                        <t>
5954                            <list>
5955                                <t>SET DB_INSTRUMENT NAME &lt;instr&gt; &lt;name&gt;</t>
5956                            </list>
5957                        </t>
5958                        <t>Where &lt;instr&gt; is the absolute path name of the instrument and
5959                        &lt;name&gt; is the new name for that instrument.</t>
5960    
5961                        <t>Possible Answers:</t>
5962                        <t>
5963                            <list>
5964                                <t>"OK" -
5965                                    <list>
5966                                        <t>on success</t>
5967                                    </list>
5968                                </t>
5969                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
5970                                    <list>
5971                                        <t>in case the given instrument does not exists,
5972                                        or if an instrument with name equal to the new
5973                                        name already exists.</t>
5974                                    </list>
5975                                </t>
5976                            </list>
5977                        </t>
5978    
5979                        <t>Example:</t>
5980                        <t>
5981                            <list>
5982                                <t>C: "SET DB_INSTRUMENT NAME '/Piano Collection/Bosendorfer' 'Bosendorfer 290'"</t>
5983                                <t>S: "OK"</t>
5984                            </list>
5985                        </t>
5986                    </section>
5987    
5988                    <section title="Moving an instrument" anchor="MOVE DB_INSTRUMENT">
5989                        <t>The front-end can move a specific instrument to another directory by
5990                        sending the following command:</t>
5991                        <t>
5992                            <list>
5993                                <t>MOVE DB_INSTRUMENT &lt;instr&gt; &lt;dst&gt;</t>
5994                            </list>
5995                        </t>
5996                        <t>Where &lt;instr&gt; is the absolute path name of the instrument
5997                        to move and &lt;dst&gt; is the directory where the instrument will
5998                        be moved to.</t>
5999    
6000                        <t>Possible Answers:</t>
6001                        <t>
6002                            <list>
6003                                <t>"OK" -
6004                                    <list>
6005                                        <t>on success</t>
6006                                    </list>
6007                                </t>
6008                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
6009                                    <list>
6010                                        <t>in case the given instrument does not exists,
6011                                        or if an instrument with name equal to the name of the
6012                                        specified instrument already exists in the destination
6013                                        directory.</t>
6014                                    </list>
6015                                </t>
6016                            </list>
6017                        </t>
6018    
6019                        <t>Example:</t>
6020                        <t>
6021                            <list>
6022                                <t>C: "MOVE DB_INSTRUMENT '/Piano Collection/Bosendorfer 290' '/Piano Collection/Acoustic'"</t>
6023                                <t>S: "OK"</t>
6024                            </list>
6025                        </t>
6026                    </section>
6027    
6028                    <section title="Copying instruments" anchor="COPY DB_INSTRUMENT">
6029                        <t>The front-end can copy a specific instrument to another directory by
6030                        sending the following command:</t>
6031                        <t>
6032                            <list>
6033                                <t>COPY DB_INSTRUMENT &lt;instr&gt; &lt;dst&gt;</t>
6034                            </list>
6035                        </t>
6036                        <t>Where &lt;instr&gt; is the absolute path name of the instrument
6037                        to copy and &lt;dst&gt; is the directory where the instrument will
6038                        be copied to.</t>
6039    
6040                        <t>Possible Answers:</t>
6041                        <t>
6042                            <list>
6043                                <t>"OK" -
6044                                    <list>
6045                                        <t>on success</t>
6046                                    </list>
6047                                </t>
6048                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
6049                                    <list>
6050                                        <t>in case the given instrument does not exists,
6051                                        or if an instrument with name equal to the name of the
6052                                        specified instrument already exists in the destination
6053                                        directory.</t>
6054                                    </list>
6055                                </t>
6056                            </list>
6057                        </t>
6058    
6059                        <t>Example:</t>
6060                        <t>
6061                            <list>
6062                                <t>C: "COPY DB_INSTRUMENT '/Piano Collection/Bosendorfer 290' '/Acoustic/Pianos/'"</t>
6063                                <t>S: "OK"</t>
6064                            </list>
6065                        </t>
6066                    </section>
6067    
6068                    <section title="Changing the description of instrument" anchor="SET DB_INSTRUMENT DESCRIPTION">
6069                        <t>The front-end can alter the description of a specific
6070                        instrument by sending the following command:</t>
6071                        <t>
6072                            <list>
6073                                <t>SET DB_INSTRUMENT DESCRIPTION &lt;instr&gt; &lt;desc&gt;</t>
6074                            </list>
6075                        </t>
6076                        <t>Where &lt;instr&gt; is the absolute path name of the instrument and
6077                        &lt;desc&gt; is the new description for the instrument
6078                        (encapsulated into apostrophes, supporting escape sequences as described in chapter
6079                        "<xref target="character_set">Character Set and Escape Sequences</xref>").</t>
6080    
6081                        <t>Possible Answers:</t>
6082                        <t>
6083                            <list>
6084                                <t>"OK" -
6085                                    <list>
6086                                        <t>on success</t>
6087                                    </list>
6088                                </t>
6089                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
6090                                    <list>
6091                                        <t>in case the given instrument does not exists.</t>
6092                                    </list>
6093                                </t>
6094                            </list>
6095                        </t>
6096    
6097                        <t>Example:</t>
6098                        <t>
6099                            <list>
6100                                <t>C: "SET DB_INSTRUMENT DESCRIPTION '/Piano Collection/Acoustic/Bosendorfer 290' 'No comment :)'"</t>
6101                                <t>S: "OK"</t>
6102                            </list>
6103                        </t>
6104                    </section>
6105    
6106                    <section title="Finding instruments" anchor="FIND DB_INSTRUMENTS">
6107                        <t>The front-end can search for instruments
6108                        in specific directory by sending the following command:</t>
6109                        <t>
6110                            <list>
6111                                <t>FIND DB_INSTRUMENTS [NON_RECURSIVE] &lt;dir&gt; &lt;criteria-list&gt;</t>
6112                            </list>
6113                        </t>
6114                        <t>Where &lt;dir&gt; should be replaced by the absolute path
6115                        name of the directory to search in. If NON_RECURSIVE is specified, the
6116                        directories located in subdirectories of the specified directory will not
6117                        be searched. &lt;criteria-list&gt; is a list of search criterias
6118                        in form of "key1=val1 key2=val2 ...". The following criterias are
6119                        allowed:</t>
6120                        <t>
6121                          <t>NAME='&lt;search-string&gt;'
6122                              <list>
6123                                  <t>Restricts the search to instruments, which names
6124                                  satisfy the supplied search string (encapsulated into apostrophes,
6125                                  supporting escape sequences as described in chapter
6126                                  "<xref target="character_set">Character Set and Escape Sequences</xref>").</t>
6127                              </list>
6128                          </t>
6129    
6130                          <t>SIZE=[&lt;min&gt;]..[&lt;max&gt;]
6131                              <list>
6132                                  <t>Restricts the search to instruments, which
6133                                  size is in the specified range. If &lt;min&gt; is omitted,
6134                                  the search results are restricted to instruments with size less then
6135                                  or equal to &lt;max&gt;. If &lt;max&gt; is omitted, the
6136                                  search is restricted to instruments with size greater then
6137                                  or equal to &lt;min&gt;.</t>
6138                              </list>
6139                          </t>
6140    
6141                          <t>CREATED='[&lt;date-after&gt;]..[&lt;date-before&gt;]'
6142                              <list>
6143                                  <t>Restricts the search to instruments, which creation
6144                                  date satisfies the specified period, where &lt;date-after&gt;
6145                                  and &lt;date-before&gt; are in "YYYY-MM-DD HH:MM:SS" format.
6146                                  If &lt;date-after&gt; is omitted the search is restricted to
6147                                  instruments created before &lt;date-before&gt;. If
6148                                  &lt;date-before&gt; is omitted, the search is restricted
6149                                  to instruments created after &lt;date-after&gt;.</t>
6150                              </list>
6151                          </t>
6152    
6153                          <t>MODIFIED='[&lt;date-after&gt;]..[&lt;date-before&gt;]'
6154                              <list>
6155                                  <t>Restricts the search to instruments, which
6156                                  date of last modification satisfies the specified period, where
6157                                  &lt;date-after&gt; and &lt;date-before&gt; are in "YYYY-MM-DD HH:MM:SS"
6158                                  format. If &lt;date-after&gt; is omitted the search is restricted to
6159                                  instruments, which are last modified before &lt;date-before&gt;. If
6160                                  &lt;date-before&gt; is omitted, the search is restricted to instruments,
6161                                  which are last modified after &lt;date-after&gt;.</t>
6162                              </list>
6163                          </t>
6164    
6165                          <t>DESCRIPTION='&lt;search-string&gt;'
6166                              <list>
6167                                  <t>Restricts the search to instruments with description
6168                                  that satisfies the supplied search string (encapsulated into apostrophes,
6169                                  supporting escape sequences as described in chapter
6170                                  "<xref target="character_set">Character Set and Escape Sequences</xref>").</t>
6171                              </list>
6172                          </t>
6173    
6174                          <t>PRODUCT='&lt;search-string&gt;'
6175                              <list>
6176                                  <t>Restricts the search to instruments with product info
6177                                  that satisfies the supplied search string (encapsulated into apostrophes,
6178                                  supporting escape sequences as described in chapter
6179                                  "<xref target="character_set">Character Set and Escape Sequences</xref>").</t>
6180                              </list>
6181                          </t>
6182    
6183                          <t>ARTISTS='&lt;search-string&gt;'
6184                              <list>
6185                                  <t>Restricts the search to instruments with artists info
6186                                  that satisfies the supplied search string (encapsulated into apostrophes,
6187                                  supporting escape sequences as described in chapter
6188                                  "<xref target="character_set">Character Set and Escape Sequences</xref>").</t>
6189                              </list>
6190                          </t>
6191    
6192                          <t>KEYWORDS='&lt;search-string&gt;'
6193                              <list>
6194                                  <t>Restricts the search to instruments with keyword list
6195                                  that satisfies the supplied search string (encapsulated into apostrophes,
6196                                  supporting escape sequences as described in chapter
6197                                  "<xref target="character_set">Character Set and Escape Sequences</xref>").</t>
6198                              </list>
6199                          </t>
6200    
6201                          <t>IS_DRUM=true | false
6202                              <list>
6203                                  <t>Either true or false. Restricts the search to
6204                                  drum kits or chromatic instruments.</t>
6205                              </list>
6206                          </t>
6207    
6208                          <t>FORMAT_FAMILIES='&lt;format-list&gt;'
6209                              <list>
6210                                  <t>Restricts the search to instruments of the supplied format families,
6211                                  where &lt;format-list&gt; is a comma separated list of format families.</t>
6212                              </list>
6213                          </t>
6214                        </t>
6215    
6216                        <t>Where &lt;search-string&gt; is either a regular expression, or a
6217                        word list separated with spaces for OR search and with '+' for AND search.</t>
6218    
6219                        <t>Possible Answers:</t>
6220                        <t>
6221                            <list>
6222                                <t>A comma separated list with the absolute path names (encapsulated into
6223                                apostrophes) of all instruments in the specified directory that satisfy
6224                                the supplied search criterias.</t>
6225                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
6226                                    <list>
6227                                        <t>if the given directory does not exist.</t>
6228                                    </list>
6229                                </t>
6230                            </list>
6231                        </t>
6232                        <t>Example:</t>
6233                        <t>
6234                            <list>
6235                                <t>C: "FIND DB_INSTRUMENTS '/Piano Collection' NAME='bosendorfer+290'"</t>
6236                                <t>S: "'/Piano Collection/Bosendorfer 290'"</t>
6237                            </list>
6238                        </t>
6239                        <t>
6240                            <list>
6241                                <t>C: "FIND DB_INSTRUMENTS '/Piano Collection' CREATED='2007-04-01 09:30:13..'"</t>
6242                                <t>S: "'/Piano Collection/Bosendorfer 290','/Piano Collection/Steinway D'"</t>
6243                            </list>
6244                        </t>
6245                    </section>
6246    
6247                    <section title="Getting job status information" anchor="GET DB_INSTRUMENTS_JOB INFO">
6248                        <t>The front-end can ask for the current status of a
6249                        particular database instruments job by sending the following command:</t>
6250                        <t>
6251                            <list>
6252                                <t>GET DB_INSTRUMENTS_JOB INFO &lt;job-id&gt;</t>
6253                            </list>
6254                        </t>
6255                        <t>Where &lt;job-id&gt; should be replaced by the numerical ID
6256                        of the job the front-end is interested in.</t>
6257    
6258                        <t>Possible Answers:</t>
6259                        <t>
6260                            <list>
6261                                <t>LinuxSampler will answer by sending a &lt;CRLF&gt; separated list.
6262                                Each answer line begins with the settings category name
6263                                followed by a colon and then a space character &lt;SP&gt; and finally
6264                                the info character string to that setting category. At the
6265                                moment the following categories are defined:</t>
6266    
6267                                <t>
6268                                    <list>
6269                                        <t>FILES_TOTAL -
6270                                            <list>
6271                                                <t>The total number of files scheduled for scanning</t>
6272                                            </list>
6273                                        </t>
6274                                        <t>FILES_SCANNED -
6275                                            <list>
6276                                                <t>The current number of scanned files</t>
6277                                            </list>
6278                                        </t>
6279                                        <t>SCANNING -
6280                                            <list>
6281                                                <t>The absolute path name of the file which is currently
6282                                                being scanned</t>
6283                                            </list>
6284                                        </t>
6285                                        <t>STATUS -
6286                                            <list>
6287                                                <t>An integer value between 0 and 100 indicating the
6288                                                scanning progress percentage of the file which is
6289                                                currently being scanned</t>
6290                                            </list>
6291                                        </t>
6292                                    </list>
6293                                </t>
6294                            </list>
6295                        </t>
6296                        <t>The mentioned fields above don't have to be in particular order.</t>
6297    
6298                        <t>Example:</t>
6299                        <t>
6300                            <list>
6301                                <t>C: "GET DB_INSTRUMENTS_JOB INFO 2"</t>
6302                                <t>S: "FILES_TOTAL: 12"</t>
6303                                <t>&nbsp;&nbsp;&nbsp;"FILES_SCANNED: 7"</t>
6304                                <t>&nbsp;&nbsp;&nbsp;"SCANNING: /home/me/gigs/Bosendorfer 290.gig"</t>
6305                                <t>&nbsp;&nbsp;&nbsp;"STATUS: 42"</t>
6306                                <t>&nbsp;&nbsp;&nbsp;"."</t>
6307                            </list>
6308                        </t>
6309                    </section>
6310    
6311                    <section title="Formatting the instruments database" anchor="FORMAT INSTRUMENTS_DB">
6312                        <t>The front-end can remove all instruments and directories and re-create
6313                        the instruments database structure (e.g., in case of a database corruption)
6314                        by sending the following command:</t>
6315                        <t>
6316                            <list>
6317                                <t>FORMAT INSTRUMENTS_DB</t>
6318                            </list>
6319                        </t>
6320    
6321                        <t>Possible Answers:</t>
6322                        <t>
6323                            <list>
6324                                <t>"OK" -
6325                                    <list>
6326                                        <t>on success</t>
6327                                    </list>
6328                                </t>
6329                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
6330                                    <list>
6331                                        <t>If the formatting of the instruments database
6332                                        failed.</t>
6333                                    </list>
6334                                </t>
6335                            </list>
6336                        </t>
6337                    </section>
6338    
6339                    <section title="Checking for lost instrument files" anchor="FIND LOST DB_INSTRUMENT_FILES">
6340                        <t>The front-end can retrieve the list of all instrument files in the instruments database
6341                        that don't exist in the filesystem by sending the following command:</t>
6342                        <t>
6343                            <list>
6344                                <t>FIND LOST DB_INSTRUMENT_FILES</t>
6345                            </list>
6346                        </t>
6347    
6348                        <t>Possible Answers:</t>
6349                        <t>
6350                            <list>
6351                                <t>A comma separated list with the absolute path names
6352                                (encapsulated into apostrophes) of all lost instrument files.</t>
6353                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
6354                                    <list>
6355                                        <t>in case it failed, providing an appropriate error code and error message.</t>
6356                                    </list>
6357                                </t>
6358                            </list>
6359                        </t>
6360                        <t>Example:</t>
6361                        <t>
6362                            <list>
6363                                <t>C: "FIND LOST DB_INSTRUMENT_FILES"</t>
6364                                <t>S: "'/gigs/Bosendorfer 290.gig','/gigs/Steinway D.gig','/gigs/Free Piano.gig'"</t>
6365                            </list>
6366                        </t>
6367                    </section>
6368    
6369                    <section title="Replacing an instrument file" anchor="SET DB_INSTRUMENT FILE_PATH">
6370                        <t>The front-end can substitute all occurrences of an instrument file
6371                        in the instruments database with a new one by sending the following command:</t>
6372                        <t>
6373                            <list>
6374                                <t>SET DB_INSTRUMENT FILE_PATH &lt;old_path&gt; &lt;new_path&gt;</t>
6375                            </list>
6376                        </t>
6377                        <t>Where &lt;old_path&gt; is the absolute path name of the instrument file
6378                        to substitute with &lt;new_path&gt;.</t>
6379    
6380                        <t>Possible Answers:</t>
6381                        <t>
6382                            <list>
6383                                <t>"OK" -
6384                                    <list>
6385                                        <t>on success</t>
6386                                    </list>
6387                                </t>
6388                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
6389                                    <list>
6390                                        <t>in case it failed, providing an appropriate error code and error message.</t>
6391                                    </list>
6392                                </t>
6393                            </list>
6394                        </t>
6395    
6396                        <t>Example:</t>
6397                        <t>
6398                            <list>
6399                                <t>C: "SET DB_INSTRUMENT FILE_PATH '/gigs/Bosendorfer 290.gig' '/gigs/pianos/Bosendorfer 290.gig'"</t>
6400                                <t>S: "OK"</t>
6401                            </list>
6402                        </t>
6403                    </section>
6404    
6405                </section>
6406    
6407    
6408    
6409                <section title="Editing Instruments" anchor="editing_instruments">
6410                    <t>The sampler allows to edit instruments while playing with the
6411                    sampler by spawning an external (3rd party) instrument editor
6412                    application for a given instrument. The 3rd party instrument
6413                    editor applications have to place a respective plugin DLL file
6414                    into the sampler's plugins directory. The sampler will
6415                    automatically try to load all plugin DLLs in that directory on
6416                    startup and only on startup!</t>
6417                    <t>At the moment there is only one command for this feature set,
6418                    but this will most probably change in future.</t>
6419    
6420                    <section title="Opening an appropriate instrument editor application" anchor="EDIT INSTRUMENT">
6421                        <t>The front-end can request to open an appropriate instrument
6422                        editor application by sending the following command:</t>
6423                        <t>
6424                            <list>
6425                                <t>EDIT CHANNEL INSTRUMENT &lt;sampler-channel&gt;</t>
6426                            </list>
6427                        </t>
6428                        <t>Where &lt;sampler-channel&gt; should be replaced by the
6429                        number of the sampler channel as given by the
6430                        <xref target="ADD CHANNEL">"ADD CHANNEL"</xref>
6431                        or <xref target="LIST CHANNELS">"LIST CHANNELS"</xref>
6432                        command.</t>
6433    
6434                        <t>The sampler will try to ask all registered instrument
6435                        editors (or to be more specific: their sampler plugins)
6436                        whether they are capable to handle the instrument on the
6437                        given sampler channel. The sampler will simply use the first
6438                        instrument editor application which replied with a positive
6439                        answer and spawn that instrument editor application within
6440                        the sampler's process and provide that application access
6441                        to the instrument's data structures, so both applications
6442                        can share and access the same instruments data at the same
6443                        time, thus allowing to immediately hear changes with the
6444                        sampler made by the instrument editor.</t>
6445    
6446                        <t>Note: consequently instrument editors are always spawned
6447                        locally on the same machine where the sampler is running
6448                        on!</t>
6449    
6450                        <t>Possible Answers:</t>
6451                        <t>
6452                            <list>
6453                                <t>"OK" -
6454                                    <list>
6455                                        <t>when an appropriate instrument editor was
6456                                        launched</t>
6457                                    </list>
6458                                </t>
6459                                <t>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
6460                                    <list>
6461                                        <t>when an appropriate instrument editor was
6462                                        launched, but there are noteworthy issues</t>
6463                                    </list>
6464                                </t>
6465                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
6466                                    <list>
6467                                        <t>when an appropriate instrument editor
6468                                        could not be launched</t>
6469                                    </list>
6470                                </t>
6471                            </list>
6472                        </t>
6473    
6474                        <t>Examples:</t>
6475                        <t>
6476                            <list>
6477                                <t>C: "EDIT CHANNEL INSTRUMENT 0"</t>
6478                                <t>S: "OK"</t>
6479                            </list>
6480                        </t>
6481                    </section>
6482                </section>
6483    
6484                <section title="Managing Files" anchor="file_management">
6485                    <t>You can query detailed informations about files located
6486                    at the same system where the sampler instance is running on.
6487                    Using this command set allows to retrieve file informations
6488                    even remotely from another machine.</t>
6489    
6490                    <section title="Retrieving amount of instruments of a file" anchor="GET FILE INSTRUMENTS">
6491                        <t>The front-end can retrieve the amount of instruments
6492                        within a given instrument file by sending the
6493                        following command:</t>
6494                        <t>
6495                            <list>
6496                                <t>GET FILE INSTRUMENTS &lt;filename&gt;</t>
6497                            </list>
6498                        </t>
6499                        <t>Where &lt;filename&gt; is the name of the instrument
6500                        file (encapsulated into apostrophes, supporting escape
6501                        sequences as described in chapter
6502                        "<xref target="character_set">Character Set and Escape
6503                            Sequences</xref>").</t>
6504    
6505                        <t>The sampler will try to ask all sampler engines,
6506                        whether they support the given file and ask the first
6507                        engine with a positive answer for the amount of
6508                        instruments.</t>
6509    
6510                        <t>Possible Answers:</t>
6511                        <t>
6512                            <list>
6513                                <t>On success, the sampler will answer by
6514                                   returning the amount of instruments.
6515                                </t>
6516                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
6517                                    <list>
6518                                        <t>if the file could not be handled</t>
6519                                    </list>
6520                                </t>
6521                            </list>
6522                        </t>
6523    
6524                        <t>Examples:</t>
6525                        <t>
6526                            <list>
6527                                <t>C: "GET FILE INSTRUMENTS 'D:/Sounds/Foo.gig'"</t>
6528                                <t>S: "10"</t>
6529                            </list>
6530                        </t>
6531                    </section>
6532    
6533                    <section title="Retrieving all instruments of a file" anchor="LIST FILE INSTRUMENTS">
6534                        <t>The front-end can retrieve a list of all instruments
6535                        within a given instrument file by sending the
6536                        following command:</t>
6537                        <t>
6538                            <list>
6539                                <t>LIST FILE INSTRUMENTS &lt;filename&gt;</t>
6540                            </list>
6541                        </t>
6542                        <t>Where &lt;filename&gt; is the name of the instrument
6543                        file (encapsulated into apostrophes, supporting escape
6544                        sequences as described in chapter
6545                        "<xref target="character_set">Character Set and Escape
6546                            Sequences</xref>").</t>
6547    
6548                        <t>The sampler will try to ask all sampler engines,
6549                        whether they support the given file and ask the first
6550                        engine with a positive answer for a list of IDs for the
6551                        instruments in the given file.</t>
6552    
6553                        <t>Possible Answers:</t>
6554                        <t>
6555                            <list>
6556                                <t>On success, the sampler will answer by
6557                                   returning a comma separated list of
6558                                   instrument IDs.
6559                                </t>
6560                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
6561                                    <list>
6562                                        <t>if the file could not be handled</t>
6563                                    </list>
6564                                </t>
6565                            </list>
6566                        </t>
6567    
6568                        <t>Examples:</t>
6569                        <t>
6570                            <list>
6571                                <t>C: "LIST FILE INSTRUMENTS 'D:/Sounds/Foo.gig'"</t>
6572                                <t>S: "0,1,2,3,4,5,6,7,8,9"</t>
6573                            </list>
6574                        </t>
6575                    </section>
6576    
6577                    <section title="Retrieving informations about one instrument in a file" anchor="GET FILE INSTRUMENT INFO">
6578                        <t>The front-end can retrieve detailed informations
6579                        about a specific instrument within a given instrument
6580                        file by sending the following command:</t>
6581                        <t>
6582                            <list>
6583                                <t>GET FILE INSTRUMENT INFO &lt;filename&gt;
6584                                &lt;instr-id&gt;</t>
6585                            </list>
6586                        </t>
6587                        <t>Where &lt;filename&gt; is the name of the instrument
6588                        file (encapsulated into apostrophes, supporting escape
6589                        sequences as described in chapter
6590                        "<xref target="character_set">Character Set and Escape
6591                            Sequences</xref>") and &lt;instr-id&gt; is the numeric
6592                        instrument ID as returned by the
6593                        <xref target="LIST FILE INSTRUMENTS">
6594                        "LIST FILE INSTRUMENTS"</xref> command.</t>
6595    
6596                        <t>The sampler will try to ask all sampler engines,
6597                        whether they support the given file and ask the first
6598                        engine with a positive answer for informations about the
6599                        specific instrument in the given file.</t>
6600    
6601                        <t>Possible Answers:</t>
6602                        <t>
6603                            <list>
6604                                <t>LinuxSampler will answer by sending a &lt;CRLF&gt; separated list.
6605                                Each answer line begins with the settings category name
6606                                followed by a colon and then a space character &lt;SP&gt; and finally
6607                                the info character string to that setting category. At the
6608                                moment the following categories are defined:</t>
6609    
6610                                <t>
6611                                    <list>
6612                                        <t>NAME -
6613                                            <list>
6614                                                <t>name of the instrument as
6615                                                stored in the instrument file</t>
6616                                            </list>
6617                                        </t>
6618                                        <t>FORMAT_FAMILY -
6619                                            <list>
6620                                                <t>name of the sampler format
6621                                                of the given instrument</t>
6622                                            </list>
6623                                        </t>
6624                                        <t>FORMAT_VERSION -
6625                                            <list>
6626                                                <t>version of the sampler format
6627                                                the instrumen is stored as</t>
6628                                            </list>
6629                                        </t>
6630                                        <t>PRODUCT -
6631                                            <list>
6632                                                <t>official product name of the
6633                                                instrument as stored in the file
6634                                                </t>
6635                                            </list>
6636                                        </t>
6637                                        <t>ARTISTS -
6638                                            <list>
6639                                                <t>artists / sample library
6640                                                vendor of the instrument</t>
6641                                            </list>
6642                                        </t>
6643                                        <t>KEY_BINDINGS -
6644                                            <list>
6645                                                <t>comma separated list of integer values representing
6646                                                   the instrument's key mapping in the range between 0 .. 127,
6647                                                   reflecting the analog meaning of the MIDI specification.</t>
6648                                            </list>
6649                                        </t>
6650                                        <t>KEYSWITCH_BINDINGS -
6651                                            <list>
6652                                                <t>comma separated list of integer values representing
6653                                                   the instrument's keyswitch mapping in the range between 0 .. 127,
6654                                                   reflecting the analog meaning of the MIDI specification.</t>
6655                                            </list>
6656                                        </t>
6657                                    </list>
6658                                </t>
6659                            </list>
6660                        </t>
6661                        <t>The mentioned fields above don't have to be in particular order.</t>
6662    
6663                        <t>Example:</t>
6664                        <t>
6665                            <list>
6666                                <t>C: "GET FILE INSTRUMENT INFO 'D:/Sounds/Foo.gig' 0"</t>
6667                                <t>S: "NAME: Lunatic Loops"</t>
6668                                <t>&nbsp;&nbsp;&nbsp;"FORMAT_FAMILY: GIG"</t>
6669                                <t>&nbsp;&nbsp;&nbsp;"FORMAT_VERSION: 3"</t>
6670                                <t>&nbsp;&nbsp;&nbsp;"PRODUCT: The Backbone Bongo Beats"</t>
6671                                <t>&nbsp;&nbsp;&nbsp;"ARTISTS: Jimmy the Fish"</t>
6672                                <t>&nbsp;&nbsp;&nbsp;"."</t>
6673                            </list>
6674                        </t>
6675                    </section>
6676                </section>
6677                <section title="Managing Effects" anchor="effects">
6678                    <t>Audio effects (e.g. reverb, delay, compression) can be
6679                    applied to the audio signals generated by the sampler. The
6680                    sampler usually provides a set of internal audio effects for
6681                    this task. The exact set of effects depends on the availability
6682                    of third party effect plugins installed on the system where the
6683                    sampler runs on.</t>
6684                    <t>At the moment only "send effects" are supported. Support for
6685                    "insert effects" and "master effects" is planned to be added at
6686                    a later point.</t>
6687                    <t>The following commands allow to retrieve the set of internal
6688                    effects available to the sampler, detailed informations about
6689                    those effects and to create and destroy instances of such
6690                    effects. After an instance of an effect is created, the effect
6691                    instance can be inserted into the audio signal path of the
6692                    sampler, e.g. as send effect.</t>
6693                    <t>The sampler allows to create an arbitrary amount of so called
6694                    send effect chains. Each effect chain can host an arbitrary
6695                    amount of effect instances. The output of the first effect
6696                    instance in an effect chain is fed to the input of the second
6697                    effect instance of the chain and so on. So effects in one chain
6698                    are processed sequentially. Send effect chains however are
6699                    processed in parallel to other send effect chains. Audio signals
6700                    of sampler channels are fed to send effects by creating FX sends
6701                    to the respective sampler channel and assigning a destination
6702                    send effect to that FX by using the
6703                    <xref target="SET FX_SEND EFFECT">"SET FX_SEND EFFECT"</xref>
6704                    command. The latter allows to route the FX send to the beginning
6705                    of a send effect chain, as well as directly to any other
6706                    position of the send effect chain.</t>
6707    
6708                    <section title="Retrieve amount of available effects" anchor="GET AVAILABLE_EFFECTS">
6709                        <t>The front-end can retrieve the amount of internal
6710                        effects, available to the sampler by sending
6711                        the following command:</t>
6712                        <t>
6713                            <list>
6714                                <t>GET AVAILABLE_EFFECTS</t>
6715                            </list>
6716                        </t>
6717    
6718                        <t>Possible Answers:</t>
6719                        <t>
6720                            <list>
6721                                <t>The sampler will answer by returning the current
6722                                number of effects available to the sampler.</t>
6723                            </list>
6724                        </t>
6725    
6726                        <t>Examples:</t>
6727                        <t>
6728                            <list>
6729                                <t>C: "GET AVAILABLE_EFFECTS"</t>
6730                                <t>S: "129"</t>
6731                            </list>
6732                        </t>
6733                    </section>
6734    
6735                    <section title="Get list of available effects" anchor="LIST AVAILABLE_EFFECTS">
6736                        <t>The set of available internal effects can change at
6737                        runtime. The front-end can retrieve the list of internal
6738                        effects, available to the sampler by sending the following
6739                        command:</t>
6740                        <t>
6741                            <list>
6742                                <t>LIST AVAILABLE_EFFECTS</t>
6743                            </list>
6744                        </t>
6745    
6746                        <t>Possible Answers:</t>
6747                        <t>
6748                            <list>
6749                                <t>The sampler will answer by returning a comma
6750                                separated list with numerical IDs of effects. Note:
6751                                the numercial ID of an effect is generated by the
6752                                sampler for the current moment. The numerical ID of
6753                                the same effect can change at runtime, e.g. when the
6754                                user requests a rescan of available effect plugins.
6755                                </t>
6756                            </list>
6757                        </t>
6758                        <t>Example:</t>
6759                        <t>
6760                            <list>
6761                                <t>C: "LIST AVAILABLE_EFFECTS"</t>
6762                                <t>S: "5,6,7,120,121,122,123,124"</t>
6763                            </list>
6764                        </t>
6765                    </section>
6766    
6767                    <section title="Retrieving general information about an effect" anchor="GET EFFECT INFO">
6768                        <t>The front-end can ask for general informations about an
6769                        effect by sending the following command:</t>
6770                        <t>
6771                            <list>
6772                                <t>GET EFFECT INFO &lt;effect-index&gt;</t>
6773                            </list>
6774                        </t>
6775                        <t>Where &lt;effect-index&gt; is the numerical ID of an
6776                        effect as returned by the
6777                        <xref target="LIST AVAILABLE_EFFECTS">"LIST AVAILABLE_EFFECTS"</xref>
6778                        command.</t>
6779                        <t>Possible Answers:</t>
6780                        <t>
6781                            <list>
6782                                <t>LinuxSampler will answer by sending a &lt;CRLF&gt; separated list.
6783                                Each answer line begins with the effect information
6784                                category name, followed by a colon and then a space
6785                                character &lt;SP&gt; and finally the info character
6786                                string to that effect information category. At the
6787                                moment the following categories are defined:</t>
6788                                <t>
6789                                    <list>
6790                                        <t>SYSTEM -
6791                                            <list>
6792                                                <t>name of the effect plugin system
6793                                                the effect is based on
6794                                                (e.g. "LADSPA")</t>
6795                                            </list>
6796                                        </t>
6797                                        <t>MODULE -
6798                                            <list>
6799                                                <t>module of the effect plugin
6800                                                system that contains this effect,
6801                                                the module is usually the
6802                                                dynamic-linked library (DLL)
6803                                                filename of the effect plugin,
6804                                                including full path (note that this
6805                                                filename may contain
6806                                                <xref target="character_set">escape sequences</xref>)</t>
6807                                            </list>
6808                                        </t>
6809                                        <t>NAME -
6810                                            <list>
6811                                                <t>character string defining the
6812                                                unique name of the effect within its
6813                                                module (note that the character
6814                                                string may contain
6815                                                <xref target="character_set">escape sequences</xref>)</t>
6816                                            </list>
6817                                        </t>
6818                                        <t>DESCRIPTION -
6819                                            <list>
6820                                                <t>human readable name of the
6821                                                effect, intended to be displayed in
6822                                                user interfaces (note that the
6823                                                character string may contain
6824                                                <xref target="character_set">escape sequences</xref>)</t>
6825                                            </list>
6826                                        </t>
6827                                    </list>
6828                                </t>
6829                            </list>
6830                        </t>
6831                        <t>The mentioned fields above don't have to be in particular order.</t>
6832    
6833                        <t>Example:</t>
6834                        <t>
6835                            <list>
6836                                <t>C: "GET EFFECT INFO 121"</t>
6837                                <t>S: "SYSTEM: LADSPA"</t>
6838                                <t>&nbsp;&nbsp;&nbsp;"MODULE: /usr/lib/ladspa/lowpass_iir_1891.so"</t>
6839                                <t>&nbsp;&nbsp;&nbsp;"NAME: lowpass_iir"</t>
6840                                <t>&nbsp;&nbsp;&nbsp;"DESCRIPTION: Glame Lowpass Filter"</t>
6841                                <t>&nbsp;&nbsp;&nbsp;"."</t>
6842                            </list>
6843                        </t>
6844                    </section>
6845    
6846                    <section title="Creating an instance of an effect by its portable ID" anchor="CREATE EFFECT_INSTANCE">
6847                        <t>The front-end can spawn an instance of the desired
6848                        effect by sending the following command:</t>
6849                        <t>
6850                            <list>
6851                                <t>CREATE EFFECT_INSTANCE &lt;effect-system&gt; &lt;module&gt; &lt;effect-name&gt;</t>
6852                            </list>
6853                        </t>
6854                        <t>Where &lt;effect-system&gt; is the "SYSTEM" field,
6855                        &lt;module&gt; the "MODULE" field and &lt;effect-name&gt;
6856                        the "NAME" field as returned by the
6857                        <xref target="GET EFFECT INFO">"GET EFFECT INFO"</xref>
6858                        command. The filename of argument &lt;module&gt; and the
6859                        character string of argument &lt;effect-name&gt; may contain
6860                        <xref target="character_set">escape sequences</xref>.</t>
6861    
6862                        <t>The sampler will try to load the requested effect and to
6863                        create an instance of it. To allow loading the same effect
6864                        on a different machine, probably even running a completely
6865                        different operating system (e.g. Linux vs. Windows), the
6866                        sampler tries to match &lt;module&gt; "softly". That means
6867                        it first tries to find an effect that exactly matches the
6868                        given &lt;module&gt; argument. If there is no exact match,
6869                        the sampler will try to lower the restrictions on matching
6870                        the &lt;module&gt; argument more and more, e.g. by ignoring
6871                        upper / lower case differences and by ignoring the path of
6872                        the DLL filename and file extension. If there is still no
6873                        match at the end, the sampler will try to ignore the
6874                        &lt;module&gt; argument completely and as a last resort
6875                        search for an effect that only matches the given
6876                        &lt;effect-system&gt; and &lt;effect-name&gt; arguments.</t>
6877    
6878                        <t>Possible Answers:</t>
6879                        <t>
6880                            <list>
6881                                <t>"OK[&lt;effect-instance&gt;]" -
6882                                    <list>
6883                                        <t>in case the effect instance was
6884                                        successfully created, where
6885                                        &lt;effect-instance&gt; is the numerical ID
6886                                        of the new effect instance</t>
6887                                    </list>
6888                                </t>
6889                                <t>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
6890                                    <list>
6891                                        <t>in case the effect instance was spawned
6892                                        successfully, but there are noteworthy
6893                                        issue(s) related, providing an appropriate
6894                                        warning code and warning message</t>
6895                                    </list>
6896                                </t>
6897                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
6898                                    <list>
6899                                        <t>if the effect could not be instantiated</t>
6900                                    </list>
6901                                </t>
6902                            </list>
6903                        </t>
6904    
6905                        <t>Examples:</t>
6906                        <t>
6907                            <list>
6908                                <t>C: "CREATE EFFECT_INSTANCE LADSPA '/usr/lib/ladspa/mod_delay_1419.so' 'modDelay'"</t>
6909                                <t>S: "OK[0]"</t>
6910                            </list>
6911                        </t>
6912                    </section>
6913    
6914                    <section title="Creating an instance of an effect by its numerical ID" anchor="CREATE EFFECT_INSTANCE (non-portable)">
6915                        <t>The front-end can spawn an instance of the desired
6916                        effect by sending the following command:</t>
6917                        <t>
6918                            <list>
6919                                <t>CREATE EFFECT_INSTANCE &lt;effect-index&gt;</t>
6920                            </list>
6921                        </t>
6922                        <t>Where &lt;effect-index&gt; is the numerical ID of the
6923                        effect as returned by the
6924                        <xref target="LIST AVAILABLE_EFFECTS">"LIST AVAILABLE_EFFECTS"</xref>
6925                        command.</t>
6926    
6927                        <t>The sampler will try to load the requested effect and to
6928                        create an instance of it.</t>
6929    
6930                        <t>Note: Since the numerical ID of a certain effect can
6931                        change at any time, you should not use this command in
6932                        LSCP files to restore a certain effect at a later time! To
6933                        store a sampler session including all its effects, use the
6934                        <xref target="CREATE EFFECT_INSTANCE">portable text-based
6935                        version of "CREATE EFFECT_INSTANCE"</xref> instead! This
6936                        allows to restore a sampler session with all its effects
6937                        also on other machines, possibly even running a completely
6938                        different operating system (e.g. Linux vs. Windows), with
6939                        different plugin directories or plugin DLL names.</t>
6940    
6941                        <t>Possible Answers:</t>
6942                        <t>
6943                            <list>
6944                                <t>"OK[&lt;effect-instance&gt;]" -
6945                                    <list>
6946                                        <t>in case the effect instance was
6947                                        successfully created, where
6948                                        &lt;effect-instance&gt; is the numerical ID
6949                                        of the new effect instance</t>
6950                                    </list>
6951                                </t>
6952                                <t>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
6953                                    <list>
6954                                        <t>in case the effect instance was spawned
6955                                        successfully, but there are noteworthy
6956                                        issue(s) related, providing an appropriate
6957                                        warning code and warning message</t>
6958                                    </list>
6959                                </t>
6960                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
6961                                    <list>
6962                                        <t>if the effect could not be instantiated</t>
6963                                    </list>
6964                                </t>
6965                            </list>
6966                        </t>
6967    
6968                        <t>Examples:</t>
6969                        <t>
6970                            <list>
6971                                <t>C: "CREATE EFFECT_INSTANCE 72"</t>
6972                                <t>S: "OK[5]"</t>
6973                            </list>
6974                        </t>
6975                    </section>
6976    
6977                    <section title="Destroy an effect instance" anchor="DESTROY EFFECT_INSTANCE">
6978                        <t>The front-end can destroy an unusued effect instance and
6979                        thus freeing it from memory by sending the following command:</t>
6980                        <t>
6981                            <list>
6982                                <t>DESTROY EFFECT_INSTANCE &lt;effect-instance&gt;</t>
6983                            </list>
6984                        </t>
6985                        <t>Where &lt;effect-instance&gt; is the numerical ID of the
6986                        effect instance as returned by the
6987                        <xref target="CREATE EFFECT_INSTANCE">"CREATE EFFECT_INSTANCE"</xref> or
6988                        <xref target="LIST EFFECT_INSTANCES">"LIST EFFECT_INSTANCES"</xref>
6989                        command.</t>
6990    
6991                        <t>The effect instance can only be destroyed if it's not
6992                        used in any part of the sampler's audio signal path anymore.
6993                        If the effect instance is still in use somewhere, trying to
6994                        destroy the effect instance will result in an error
6995                        message.</t>
6996    
6997                        <t>Possible Answers:</t>
6998                        <t>
6999                            <list>
7000                                <t>"OK" -
7001                                    <list>
7002                                        <t>in case the effect instance was successfully destroyed</t>
7003                                    </list>
7004                                </t>
7005                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
7006                                    <list>
7007                                        <t>in case it failed, providing an appropriate error code and
7008                                        error message</t>
7009                                    </list>
7010                                </t>
7011                            </list>
7012                        </t>
7013    
7014                        <t>Examples:</t>
7015                        <t>
7016                            <list>
7017                                <t>C: "DESTROY EFFECT_INSTANCE 5"</t>
7018                                <t>S: "OK"</t>
7019                            </list>
7020                        </t>
7021                    </section>
7022    
7023                    <section title="Retrieve amount of effect instances" anchor="GET EFFECT_INSTANCES">
7024                        <t>The front-end can retrieve the current amount of effect
7025                        instances by sending the following command:</t>
7026                        <t>
7027                            <list>
7028                                <t>GET EFFECT_INSTANCES</t>
7029                            </list>
7030                        </t>
7031    
7032                        <t>Possible Answers:</t>
7033                        <t>
7034                            <list>
7035                                <t>The sampler will answer by returning the current
7036                                number of effect instances created and not yet
7037                                destroyed in the current sampler session.</t>
7038                            </list>
7039                        </t>
7040    
7041                        <t>Examples:</t>
7042                        <t>
7043                            <list>
7044                                <t>C: "GET EFFECT_INSTANCES"</t>
7045                                <t>S: "14"</t>
7046                            </list>
7047                        </t>
7048                    </section>
7049    
7050                    <section title="Get list of effect instances" anchor="LIST EFFECT_INSTANCES">
7051                        <t>The front-end can retrieve the current list of effect
7052                        instances by sending the following command:</t>
7053                        <t>
7054                            <list>
7055                                <t>LIST EFFECT_INSTANCES</t>
7056                            </list>
7057                        </t>
7058    
7059                        <t>Possible Answers:</t>
7060                        <t>
7061                            <list>
7062                                <t>The sampler will answer by returning a comma
7063                                separated list with numerical IDs of effects
7064                                instances.
7065                                </t>
7066                            </list>
7067                        </t>
7068                        <t>Example:</t>
7069                        <t>
7070                            <list>
7071                                <t>C: "LIST EFFECT_INSTANCES"</t>
7072                                <t>S: "9,11,14,15,16,17,25"</t>
7073                            </list>
7074                        </t>
7075                    </section>
7076    
7077                    <section title="Retrieving current information about an effect instance" anchor="GET EFFECT_INSTANCE INFO">
7078                        <t>The front-end can ask for the current informations about
7079                        a particular effect instance by sending the following command:</t>
7080                        <t>
7081                            <list>
7082                                <t>GET EFFECT_INSTANCE INFO &lt;effect-instance&gt;</t>
7083                            </list>
7084                        </t>
7085                        <t>Where &lt;effect-instance&gt; is the numerical ID of an
7086                        effect instance as returned by the
7087                        <xref target="CREATE EFFECT_INSTANCE">"CREATE EFFECT_INSTANCE"</xref>
7088                        or
7089                        <xref target="LIST EFFECT_INSTANCES">"LIST EFFECT_INSTANCES"</xref>
7090                        command.</t>
7091    
7092                        <t>Possible Answers:</t>
7093                        <t>
7094                            <list>
7095                                <t>LinuxSampler will answer by sending a &lt;CRLF&gt; separated list.
7096                                Each answer line begins with the information
7097                                category name, followed by a colon and then a space
7098                                character &lt;SP&gt; and finally the info character
7099                                string to that information category. At the
7100                                moment the following categories are defined:</t>
7101                                <t>
7102                                    <list>
7103                                        <t>SYSTEM -
7104                                            <list>
7105                                                <t>name of the effect plugin system
7106                                                the effect is based on
7107                                                (e.g. "LADSPA")</t>
7108                                            </list>
7109                                        </t>
7110                                        <t>MODULE -
7111                                            <list>
7112                                                <t>module of the effect plugin
7113                                                system that contains this effect,
7114                                                the module is usually the
7115                                                dynamic-linked library (DLL)
7116                                                filename of the effect plugin,
7117                                                including full path (note that this
7118                                                filename may contain
7119                                                <xref target="character_set">escape sequences</xref>)</t>
7120                                            </list>
7121                                        </t>
7122                                        <t>NAME -
7123                                            <list>
7124                                                <t>character string defining the
7125                                                unique name of the effect within its
7126                                                module (note that the character
7127                                                string may contain
7128                                                <xref target="character_set">escape sequences</xref>)</t>
7129                                            </list>
7130                                        </t>
7131                                        <t>DESCRIPTION -
7132                                            <list>
7133                                                <t>human readable name of the
7134                                                effect, intended to be displayed in
7135                                                user interfaces (note that the
7136                                                character string may contain
7137                                                <xref target="character_set">escape sequences</xref>)</t>
7138                                            </list>
7139                                        </t>
7140                                        <t>INPUT_CONTROLS -
7141                                            <list>
7142                                                <t>amount of input controls the
7143                                                effect instance provides, to allow
7144                                                controlling the effect parameters in
7145                                                realtime</t>
7146                                            </list>
7147                                        </t>
7148                                    </list>
7149                                </t>
7150                            </list>
7151                        </t>
7152                        <t>The mentioned fields above don't have to be in particular order.</t>
7153    
7154                        <t>Example:</t>
7155                        <t>
7156                            <list>
7157                                <t>C: "GET EFFECT_INSTANCE INFO 3"</t>
7158                                <t>S: "SYSTEM: LADSPA"</t>
7159                                <t>&nbsp;&nbsp;&nbsp;"MODULE: /usr/lib/ladspa/mod_delay_1419.so"</t>
7160                                <t>&nbsp;&nbsp;&nbsp;"NAME: modDelay"</t>
7161                                <t>&nbsp;&nbsp;&nbsp;"DESCRIPTION: Modulatable delay"</t>
7162                                <t>&nbsp;&nbsp;&nbsp;"INPUT_CONTROLS: 1"</t>
7163                                <t>&nbsp;&nbsp;&nbsp;"."</t>
7164                            </list>
7165                        </t>
7166                    </section>
7167    
7168                    <section title="Retrieving information about an effect parameter" anchor="GET EFFECT_INSTANCE_INPUT_CONTROL INFO">
7169                        <t>Effects typically provide a certain set of effect
7170                        parameters which can be altered by the user in realtime
7171                        (e.g. depth of a reverb effect, duration of a delay effect,
7172                        dry / wet signal ratio). Those controllable effect parameters
7173                        are called "input controls". The front-end can ask for the
7174                        current informations of an effect instance's input control
7175                        by sending the following command:</t>
7176                        <t>
7177                            <list>
7178                                <t>GET EFFECT_INSTANCE_INPUT_CONTROL INFO &lt;effect-instance&gt; &lt;input-control&gt;</t>
7179                            </list>
7180                        </t>
7181                        <t>Where &lt;effect-instance&gt; is the numerical ID of an
7182                        effect instance as returned by the
7183                        <xref target="CREATE EFFECT_INSTANCE">"CREATE EFFECT_INSTANCE"</xref>
7184                        or
7185                        <xref target="LIST EFFECT_INSTANCES">"LIST EFFECT_INSTANCES"</xref>
7186                        command and &lt;input-control&gt; is the index of the input
7187                        control within the numerical bounds as returned by the
7188                        "INPUT_CONTROLS" field of the
7189                        <xref target="GET EFFECT_INSTANCE INFO">"GET EFFECT_INSTANCE INFO"</xref>
7190                        command.</t>
7191    
7192                        <t>Possible Answers:</t>
7193                        <t>
7194                            <list>
7195                                <t>LinuxSampler will answer by sending a &lt;CRLF&gt; separated list.
7196                                Each answer line begins with the information
7197                                category name, followed by a colon and then a space
7198                                character &lt;SP&gt; and finally the info character
7199                                string to that information category. There are
7200                                information categories which are always returned,
7201                                independent of the respective effect parameter and
7202                                there are optional information categories
7203                                which are only shown for certain effect parameters.
7204                                At the moment the following categories are defined:</t>
7205                                <t>
7206                                    <list>
7207                                        <t>DESCRIPTION -
7208                                            <list>
7209                                                <t>(always returned)
7210                                                human readable name of the
7211                                                effect parameter, intended to be
7212                                                displayed in user interfaces (note
7213                                                that the character string may
7214                                                contain <xref target="character_set">escape sequences</xref>)</t>
7215                                            </list>
7216                                        </t>
7217                                        <t>VALUE -
7218                                            <list>
7219                                                <t>
7220                                                (always returned)
7221                                                current (optional dotted)
7222                                                floating point value of this effect
7223                                                parameter</t>
7224                                            </list>
7225                                        </t>
7226                                        <t>RANGE_MIN -
7227                                            <list>
7228                                                <t>
7229                                                (optionally returned)
7230                                                minimum allowed value for this
7231                                                effect parameter</t>
7232                                            </list>
7233                                        </t>
7234                                        <t>RANGE_MAX -
7235                                            <list>
7236                                                <t>
7237                                                (optionally returned)
7238                                                maximum allowed value for this
7239                                                effect parameter</t>
7240                                            </list>
7241                                        </t>
7242                                        <t>POSSIBILITIES -
7243                                            <list>
7244                                                <t>
7245                                                (optionally returned)
7246                                                comma separated list of
7247                                                (optional dotted) floating point
7248                                                numbers, reflecting the exact set of
7249                                                possible values for this effect
7250                                                parameter</t>
7251                                            </list>
7252                                        </t>
7253                                        <t>DEFAULT -
7254                                            <list>
7255                                                <t>
7256                                                (optionally returned)
7257                                                default value of this effect
7258                                                parameter</t>
7259                                            </list>
7260                                        </t>
7261                                    </list>
7262                                </t>
7263                            </list>
7264                        </t>
7265                        <t>The mentioned fields above don't have to be in particular order.</t>
7266    
7267                        <t>Example:</t>
7268                        <t>
7269                            <list>
7270                                <t>C: "GET EFFECT_INSTANCE_INPUT_CONTROL INFO 1 0"</t>
7271                                <t>S: "SYSTEM: LADSPA"</t>
7272                                <t>&nbsp;&nbsp;&nbsp;"DESCRIPTION: Base delay (s)"</t>
7273                                <t>&nbsp;&nbsp;&nbsp;"VALUE: 0.500"</t>
7274                                <t>&nbsp;&nbsp;&nbsp;"RANGE_MIN: 0.000"</t>
7275                                <t>&nbsp;&nbsp;&nbsp;"."</t>
7276                            </list>
7277                        </t>
7278                    </section>
7279    
7280                    <section title="Altering an effect parameter" anchor="SET EFFECT_INSTANCE_INPUT_CONTROL VALUE">
7281                        <t>The front-end can alter the current value of an effect
7282                        parameter by sending the following command:</t>
7283                        <t>
7284                            <list>
7285                                <t>SET EFFECT_INSTANCE_INPUT_CONTROL VALUE &lt;effect-instance&gt; &lt;input-control&gt; &lt;value&gt;</t>
7286                            </list>
7287                        </t>
7288                        <t>Where &lt;effect-instance&gt; is the numerical ID of the
7289                        effect instance as returned by the
7290                        <xref target="CREATE EFFECT_INSTANCE">"CREATE EFFECT_INSTANCE"</xref> or
7291                        <xref target="LIST EFFECT_INSTANCES">"LIST EFFECT_INSTANCES"</xref>
7292                        command, &lt;input-control&gt; is the index of the input
7293                        control within the numerical bounds as returned by the
7294                        "INPUT_CONTROLS" field of the
7295                        <xref target="GET EFFECT_INSTANCE INFO">"GET EFFECT_INSTANCE INFO"</xref>
7296                        command and &lt;value&gt; is the new (optional dotted)
7297                        floating point value for this effect parameter.</t>
7298    
7299                        <t>Possible Answers:</t>
7300                        <t>
7301                            <list>
7302                                <t>"OK" -
7303                                    <list>
7304                                        <t>in case the effect was altered successfully</t>
7305                                    </list>
7306                                </t>
7307                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
7308                                    <list>
7309                                        <t>in case it failed, providing an appropriate error code and
7310                                        error message</t>
7311                                    </list>
7312                                </t>
7313                            </list>
7314                        </t>
7315    
7316                        <t>Examples:</t>
7317                        <t>
7318                            <list>
7319                                <t>C: "SET EFFECT_INSTANCE_INPUT_CONTROL VALUE 0 1 0.5"</t>
7320                                <t>S: "OK"</t>
7321                            </list>
7322                        </t>
7323                    </section>
7324    
7325                    <section title="Retrieve amount of send effect chains" anchor="GET SEND_EFFECT_CHAINS">
7326                        <t>The front-end can retrieve the current amount of send
7327                        effect chains of an audio output device by sending the
7328                        following command:</t>
7329                        <t>
7330                            <list>
7331                                <t>GET SEND_EFFECT_CHAINS &lt;audio-device&gt;</t>
7332                            </list>
7333                        </t>
7334                        <t>Where &lt;audio-device&gt; should be replaced by the
7335                        numerical ID of the audio output device as given by the
7336                        <xref target="CREATE AUDIO_OUTPUT_DEVICE">"CREATE AUDIO_OUTPUT_DEVICE"</xref>
7337                        or <xref target="LIST AUDIO_OUTPUT_DEVICES">"LIST AUDIO_OUTPUT_DEVICES"</xref>
7338                        command.</t>
7339    
7340                        <t>Possible Answers:</t>
7341                        <t>
7342                            <list>
7343                                <t>The sampler will answer by returning the current
7344                                number of send effect chains of the supplied audio
7345                                output device.</t>
7346                            </list>
7347                        </t>
7348    
7349                        <t>Examples:</t>
7350                        <t>
7351                            <list>
7352                                <t>C: "GET SEND_EFFECT_CHAINS 0"</t>
7353                                <t>S: "4"</t>
7354                            </list>
7355                        </t>
7356                    </section>
7357    
7358                    <section title="Retrieve list of send effect chains" anchor="LIST SEND_EFFECT_CHAINS">
7359                        <t>The front-end can retrieve the current list of send
7360                        effect chains of an audio output device by sending the
7361                        following command:</t>
7362                        <t>
7363                            <list>
7364                                <t>LIST SEND_EFFECT_CHAINS &lt;audio-device&gt;</t>
7365                            </list>
7366                        </t>
7367                        <t>Where &lt;audio-device&gt; should be replaced by the
7368                        numerical ID of the audio output device as given by the
7369                        <xref target="CREATE AUDIO_OUTPUT_DEVICE">"CREATE AUDIO_OUTPUT_DEVICE"</xref>
7370                        or <xref target="LIST AUDIO_OUTPUT_DEVICES">"LIST AUDIO_OUTPUT_DEVICES"</xref>
7371                        command.</t>
7372    
7373                        <t>Possible Answers:</t>
7374                        <t>
7375                            <list>
7376                                <t>The sampler will answer by returning a comma
7377                                separated list with numerical IDs of send effect
7378                                chains of the supplied audio output device.
7379                                </t>
7380                            </list>
7381                        </t>
7382    
7383                        <t>Examples:</t>
7384                        <t>
7385                            <list>
7386                                <t>C: "LIST SEND_EFFECT_CHAINS 0"</t>
7387                                <t>S: "3,4,7"</t>
7388                            </list>
7389                        </t>
7390                    </section>
7391    
7392                    <section title="Add send effect chain" anchor="ADD SEND_EFFECT_CHAIN">
7393                        <t>The front-end can add a send effect chain by sending the
7394                        following command:</t>
7395                        <t>
7396                            <list>
7397                                <t>ADD SEND_EFFECT_CHAIN &lt;audio-device&gt;</t>
7398                            </list>
7399                        </t>
7400                        <t>Where &lt;audio-device&gt; should be replaced by the
7401                        numerical ID of the audio output device as given by the
7402                        <xref target="CREATE AUDIO_OUTPUT_DEVICE">"CREATE AUDIO_OUTPUT_DEVICE"</xref>
7403                        or <xref target="LIST AUDIO_OUTPUT_DEVICES">"LIST AUDIO_OUTPUT_DEVICES"</xref>
7404                        command.</t>
7405    
7406                        <t>Possible Answers:</t>
7407                        <t>
7408                            <list>
7409                                <t>"OK[&lt;effect-chain&gt;]" -
7410                                    <list>
7411                                        <t>in case the send effect chain was
7412                                        added successfully, where
7413                                        &lt;effect-chain&gt; is the numerical ID
7414                                        of the new send effect chain</t>
7415                                    </list>
7416                                </t>
7417                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
7418                                    <list>
7419                                        <t>if the send effect chain could not be added</t>
7420                                    </list>
7421                                </t>
7422                            </list>
7423                        </t>
7424    
7425                        <t>Examples:</t>
7426                        <t>
7427                            <list>
7428                                <t>C: "ADD SEND_EFFECT_CHAIN 0"</t>
7429                                <t>S: "OK[2]"</t>
7430                            </list>
7431                        </t>
7432                    </section>
7433    
7434                    <section title="Remove send effect chain" anchor="REMOVE SEND_EFFECT_CHAIN">
7435                        <t>The front-end can remove a send effect chain by sending
7436                        the following command:</t>
7437                        <t>
7438                            <list>
7439                                <t>REMOVE SEND_EFFECT_CHAIN &lt;audio-device&gt; &lt;effect-chain&gt;</t>
7440                            </list>
7441                        </t>
7442                        <t>Where &lt;audio-device&gt; should be replaced by the
7443                        numerical ID of the audio output device as given by the
7444                        <xref target="CREATE AUDIO_OUTPUT_DEVICE">"CREATE AUDIO_OUTPUT_DEVICE"</xref>
7445                        or <xref target="LIST AUDIO_OUTPUT_DEVICES">"LIST AUDIO_OUTPUT_DEVICES"</xref>
7446                        command and &lt;effect-chain&gt; by the numerical ID as
7447                        returned by the
7448                        <xref target="ADD SEND_EFFECT_CHAIN">"ADD SEND_EFFECT_CHAIN"</xref>
7449                        or
7450                        <xref target="LIST SEND_EFFECT_CHAINS">"LIST SEND_EFFECT_CHAINS"</xref>
7451                        command.</t>
7452    
7453                        <t>Possible Answers:</t>
7454                        <t>
7455                            <list>
7456                                <t>"OK" -
7457                                    <list>
7458                                        <t>in case the send effect chain was
7459                                        removed successfully</t>
7460                                    </list>
7461                                </t>
7462                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
7463                                    <list>
7464                                        <t>if the send effect chain could not be removed</t>
7465                                    </list>
7466                                </t>
7467                            </list>
7468                        </t>
7469    
7470                        <t>Examples:</t>
7471                        <t>
7472                            <list>
7473                                <t>C: "REMOVE SEND_EFFECT_CHAIN 0 2"</t>
7474                                <t>S: "OK"</t>
7475                            </list>
7476                        </t>
7477                    </section>
7478    
7479                    <section title="Retrieving information about a send effect chain" anchor="GET SEND_EFFECT_CHAIN INFO">
7480                        <t>The front-end can ask for informations of a send effect
7481                        chain by sending the following command:</t>
7482                        <t>
7483                            <list>
7484                                <t>GET SEND_EFFECT_CHAIN INFO &lt;audio-device&gt; &lt;effect-chain&gt;</t>
7485                            </list>
7486                        </t>
7487                        <t>Where &lt;audio-device&gt; should be replaced by the
7488                        numerical ID of the audio output device as given by the
7489                        <xref target="CREATE AUDIO_OUTPUT_DEVICE">"CREATE AUDIO_OUTPUT_DEVICE"</xref>
7490                        or <xref target="LIST AUDIO_OUTPUT_DEVICES">"LIST AUDIO_OUTPUT_DEVICES"</xref>
7491                        command and &lt;effect-chain&gt; by the numerical ID as
7492                        returned by the
7493                        <xref target="ADD SEND_EFFECT_CHAIN">"ADD SEND_EFFECT_CHAIN"</xref>
7494                        or
7495                        <xref target="LIST SEND_EFFECT_CHAINS">"LIST SEND_EFFECT_CHAINS"</xref>
7496                        command.</t>
7497    
7498                        <t>Possible Answers:</t>
7499                        <t>
7500                            <list>
7501                                <t>LinuxSampler will answer by sending a &lt;CRLF&gt; separated list.
7502                                Each answer line begins with the information
7503                                category name, followed by a colon and then a space
7504                                character &lt;SP&gt; and finally the info character
7505                                string to that information category.
7506                                At the moment the following categories are defined:</t>
7507                                <t>
7508                                    <list>
7509                                        <t>EFFECT_COUNT -
7510                                            <list>
7511                                                <t>amount of effects in this send
7512                                                effect chain</t>
7513                                            </list>
7514                                        </t>
7515                                        <t>EFFECT_SEQUENCE -
7516                                            <list>
7517                                                <t>comma separated list of the
7518                                                numerical IDs of the effect
7519                                                instances in this send effect chain,
7520                                                in the order as they are procssed in
7521                                                the effect chain</t>
7522                                            </list>
7523                                        </t>
7524                                    </list>
7525                                </t>
7526                            </list>
7527                        </t>
7528                        <t>The mentioned fields above don't have to be in particular order.</t>
7529    
7530                        <t>Example:</t>
7531                        <t>
7532                            <list>
7533                                <t>C: "GET SEND_EFFECT_CHAIN INFO 0 2"</t>
7534                                <t>S: "EFFECT_COUNT: 3"</t>
7535                                <t>&nbsp;&nbsp;&nbsp;"EFFECT_SEQUENCE: 31,4,7"</t>
7536                                <t>&nbsp;&nbsp;&nbsp;"."</t>
7537                            </list>
7538                        </t>
7539                    </section>
7540    
7541                    <section title="Append effect instance to a send effect chain" anchor="APPEND SEND_EFFECT_CHAIN EFFECT">
7542                        <t>The front-end can add an unused effect instance to the
7543                        end of a send effect chain by sending the following command:</t>
7544                        <t>
7545                            <list>
7546                                <t>APPEND SEND_EFFECT_CHAIN EFFECT &lt;audio-device&gt; &lt;effect-chain&gt; &lt;effect-instance&gt;</t>
7547                            </list>
7548                        </t>
7549                        <t>Where &lt;audio-device&gt; should be replaced by the
7550                        numerical ID of the audio output device as given by the
7551                        <xref target="CREATE AUDIO_OUTPUT_DEVICE">"CREATE AUDIO_OUTPUT_DEVICE"</xref>
7552                        or <xref target="LIST AUDIO_OUTPUT_DEVICES">"LIST AUDIO_OUTPUT_DEVICES"</xref>
7553                        command and &lt;effect-chain&gt; by the numerical ID as
7554                        returned by the
7555                        <xref target="ADD SEND_EFFECT_CHAIN">"ADD SEND_EFFECT_CHAIN"</xref>
7556                        or
7557                        <xref target="LIST SEND_EFFECT_CHAINS">"LIST SEND_EFFECT_CHAINS"</xref>
7558                        command and &lt;effect-instance&gt; as returned by the
7559                        <xref target="CREATE EFFECT_INSTANCE">"CREATE EFFECT_INSTANCE"</xref> or
7560                        <xref target="LIST EFFECT_INSTANCES">"LIST EFFECT_INSTANCES"</xref>
7561                        command.</t>
7562                        <t>Only unused effect instances can be added to the effect
7563                        chain. Trying to add an effect instance which is already in
7564                        use somewhere in the audio signal path of the sampler will
7565                        result in an error.</t>
7566    
7567                        <t>Possible Answers:</t>
7568                        <t>
7569                            <list>
7570                                <t>"OK" -
7571                                    <list>
7572                                        <t>in case the effect instance was
7573                                        added successfully to the chain</t>
7574                                    </list>
7575                                </t>
7576                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
7577                                    <list>
7578                                        <t>if the effect instance could not be added</t>
7579                                    </list>
7580                                </t>
7581                            </list>
7582                        </t>
7583    
7584                        <t>Examples:</t>
7585                        <t>
7586                            <list>
7587                                <t>C: "APPEND SEND_EFFECT_CHAIN EFFECT 0 2 38"</t>
7588                                <t>S: "OK"</t>
7589                            </list>
7590                        </t>
7591                    </section>
7592    
7593                    <section title="Insert effect instance to a send effect chain" anchor="INSERT SEND_EFFECT_CHAIN EFFECT">
7594                        <t>The front-end can add an unused effect instance to a
7595                        certain position of a send effect chain by sending the
7596                        following command:</t>
7597                        <t>
7598                            <list>
7599                                <t>INSERT SEND_EFFECT_CHAIN EFFECT &lt;audio-device&gt; &lt;effect-chain&gt; &lt;chain-pos&gt; &lt;effect-instance&gt;</t>
7600                            </list>
7601                        </t>
7602                        <t>Where &lt;audio-device&gt; should be replaced by the
7603                        numerical ID of the audio output device as given by the
7604                        <xref target="CREATE AUDIO_OUTPUT_DEVICE">"CREATE AUDIO_OUTPUT_DEVICE"</xref>
7605                        or <xref target="LIST AUDIO_OUTPUT_DEVICES">"LIST AUDIO_OUTPUT_DEVICES"</xref>
7606                        command, &lt;effect-chain&gt; by the numerical ID as
7607                        returned by the
7608                        <xref target="ADD SEND_EFFECT_CHAIN">"ADD SEND_EFFECT_CHAIN"</xref>
7609                        or
7610                        <xref target="LIST SEND_EFFECT_CHAINS">"LIST SEND_EFFECT_CHAINS"</xref>
7611                        command, &lt;effect-instance&gt; as returned by the
7612                        <xref target="CREATE EFFECT_INSTANCE">"CREATE EFFECT_INSTANCE"</xref> or
7613                        <xref target="LIST EFFECT_INSTANCES">"LIST EFFECT_INSTANCES"</xref>
7614                        command and &lt;chain-pos&gt; the exact position of the
7615                        effect chain where the supplied effect shall be inserted
7616                        to.</t>
7617                        <t>Only unused effect instances can be added to the effect
7618                        chain. Trying to add an effect instance which is already in
7619                        use somewhere in the audio signal path of the sampler will
7620                        result in an error.</t>
7621    
7622                        <t>Possible Answers:</t>
7623                        <t>
7624                            <list>
7625                                <t>"OK" -
7626                                    <list>
7627                                        <t>in case the effect instance was
7628                                        added successfully to the chain</t>
7629                                    </list>
7630                                </t>
7631                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
7632                                    <list>
7633                                        <t>if the effect instance could not be added</t>
7634                                    </list>
7635                                </t>
7636                            </list>
7637                        </t>
7638    
7639                        <t>Examples:</t>
7640                        <t>
7641                            <list>
7642                                <t>C: "INSERT SEND_EFFECT_CHAIN EFFECT 0 2 4 38"</t>
7643                                <t>S: "OK"</t>
7644                            </list>
7645                        </t>
7646                    </section>
7647    
7648                    <section title="Remove effect instance from send effect chain" anchor="REMOVE SEND_EFFECT_CHAIN EFFECT">
7649                        <t>The front-end can remove an effect instance from a
7650                        certain position of a send effect chain by sending the
7651                        following command:</t>
7652                        <t>
7653                            <list>
7654                                <t>REMOVE SEND_EFFECT_CHAIN EFFECT &lt;audio-device&gt; &lt;effect-chain&gt; &lt;chain-pos&gt;</t>
7655                            </list>
7656                        </t>
7657                        <t>Where &lt;audio-device&gt; should be replaced by the
7658                        numerical ID of the audio output device as given by the
7659                        <xref target="CREATE AUDIO_OUTPUT_DEVICE">"CREATE AUDIO_OUTPUT_DEVICE"</xref>
7660                        or <xref target="LIST AUDIO_OUTPUT_DEVICES">"LIST AUDIO_OUTPUT_DEVICES"</xref>
7661                        command, &lt;effect-chain&gt; by the numerical ID as
7662                        returned by the
7663                        <xref target="ADD SEND_EFFECT_CHAIN">"ADD SEND_EFFECT_CHAIN"</xref>
7664                        or
7665                        <xref target="LIST SEND_EFFECT_CHAINS">"LIST SEND_EFFECT_CHAINS"</xref>
7666                        command and &lt;chain-pos&gt; the exact position of the
7667                        effect instance to be removed from the effect chain.</t>
7668    
7669                        <t>Possible Answers:</t>
7670                        <t>
7671                            <list>
7672                                <t>"OK" -
7673                                    <list>
7674                                        <t>in case the effect instance was
7675                                        removed successfully</t>
7676                                    </list>
7677                                </t>
7678                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
7679                                    <list>
7680                                        <t>if the effect instance could not be removed</t>
7681                                    </list>
7682                                </t>
7683                            </list>
7684                        </t>
7685    
7686                        <t>Examples:</t>
7687                        <t>
7688                            <list>
7689                                <t>C: "REMOVE SEND_EFFECT_CHAIN EFFECT 0 2 4"</t>
7690                                <t>S: "OK"</t>
7691                            </list>
7692                        </t>
7693                    </section>
7694    
7695                </section>
7696            </section>
7697    
7698          <section title="Command Syntax" anchor="command_syntax">          <section title="Command Syntax" anchor="command_syntax">
7699              <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 4809  Schoenebeck'> Line 7767  Schoenebeck'>
7767                  </t>                  </t>
7768                  <t>/ UNSUBSCRIBE SP unsubscribe_event                  <t>/ UNSUBSCRIBE SP unsubscribe_event
7769                  </t>                  </t>
                 <t>/ SELECT SP text  
                 </t>  
7770                  <t>/ RESET SP reset_instruction                  <t>/ RESET SP reset_instruction
7771                  </t>                  </t>
7772                  <t>/ CLEAR SP clear_instruction                  <t>/ CLEAR SP clear_instruction
7773                  </t>                  </t>
7774                    <t>/ FIND SP find_instruction
7775                    </t>
7776                    <t>/ MOVE SP move_instruction
7777                    </t>
7778                    <t>/ COPY SP copy_instruction
7779                    </t>
7780                    <t>/ EDIT SP edit_instruction
7781                    </t>
7782                    <t>/ FORMAT SP format_instruction
7783                    </t>
7784                    <t>/ SEND SP send_instruction
7785                    </t>
7786                    <t>/ APPEND SP append_instruction
7787                    </t>
7788                    <t>/ INSERT SP insert_instruction
7789                    </t>
7790                  <t>/ RESET                  <t>/ RESET
7791                  </t>                  </t>
7792                  <t>/ QUIT                  <t>/ QUIT
# Line 4825  Schoenebeck'> Line 7797  Schoenebeck'>
7797          <list>          <list>
7798                  <t>CHANNEL                  <t>CHANNEL
7799                  </t>                  </t>
7800                    <t>/ DB_INSTRUMENT_DIRECTORY SP db_path
7801                    </t>
7802                    <t>/ DB_INSTRUMENTS SP NON_MODAL SP scan_mode SP db_path SP filename
7803                    </t>
7804                    <t>/ DB_INSTRUMENTS SP NON_MODAL SP scan_mode SP FILE_AS_DIR SP db_path SP filename
7805                    </t>
7806                    <t>/ DB_INSTRUMENTS SP scan_mode SP db_path SP filename
7807                    </t>
7808                    <t>/ DB_INSTRUMENTS SP scan_mode SP FILE_AS_DIR SP db_path SP filename
7809                    </t>
7810                    <t>/ DB_INSTRUMENTS SP NON_MODAL SP db_path SP filename
7811                    </t>
7812                    <t>/ DB_INSTRUMENTS SP NON_MODAL SP db_path SP filename SP instrument_index
7813                    </t>
7814                    <t>/ DB_INSTRUMENTS SP db_path SP filename
7815                    </t>
7816                    <t>/ DB_INSTRUMENTS SP db_path SP filename SP instrument_index
7817                    </t>
7818                  <t>/ MIDI_INSTRUMENT_MAP                  <t>/ MIDI_INSTRUMENT_MAP
7819                  </t>                  </t>
7820                  <t>/ MIDI_INSTRUMENT_MAP SP map_name                  <t>/ MIDI_INSTRUMENT_MAP SP map_name
7821                  </t>                  </t>
7822                    <t>/ SEND_EFFECT_CHAIN SP device_index
7823                    </t>
7824          </list>          </list>
7825  </t>  </t>
7826  <t>subscribe_event =  <t>subscribe_event =
# Line 4843  Schoenebeck'> Line 7835  Schoenebeck'>
7835                  </t>                  </t>
7836                  <t>/ CHANNEL_COUNT                  <t>/ CHANNEL_COUNT
7837                  </t>                  </t>
7838                    <t>/ CHANNEL_MIDI
7839                    </t>
7840                    <t>/ DEVICE_MIDI
7841                    </t>
7842                  <t>/ VOICE_COUNT                  <t>/ VOICE_COUNT
7843                  </t>                  </t>
7844                  <t>/ STREAM_COUNT                  <t>/ STREAM_COUNT
# Line 4863  Schoenebeck'> Line 7859  Schoenebeck'>
7859                  </t>                  </t>
7860                  <t>/ MIDI_INSTRUMENT_INFO                  <t>/ MIDI_INSTRUMENT_INFO
7861                  </t>                  </t>
7862                    <t>/ DB_INSTRUMENT_DIRECTORY_COUNT
7863                    </t>
7864                    <t>/ DB_INSTRUMENT_DIRECTORY_INFO
7865                    </t>
7866                    <t>/ DB_INSTRUMENT_COUNT
7867                    </t>
7868                    <t>/ DB_INSTRUMENT_INFO
7869                    </t>
7870                    <t>/ DB_INSTRUMENTS_JOB_INFO
7871                    </t>
7872                  <t>/ MISCELLANEOUS                  <t>/ MISCELLANEOUS
7873                  </t>                  </t>
7874                    <t>/ TOTAL_STREAM_COUNT
7875                    </t>
7876                  <t>/ TOTAL_VOICE_COUNT                  <t>/ TOTAL_VOICE_COUNT
7877                  </t>                  </t>
7878                  <t>/ GLOBAL_INFO                  <t>/ GLOBAL_INFO
# Line 4883  Schoenebeck'> Line 7891  Schoenebeck'>
7891                  </t>                  </t>
7892                  <t>/ CHANNEL_COUNT                  <t>/ CHANNEL_COUNT
7893                  </t>                  </t>
7894                    <t>/ CHANNEL_MIDI
7895                    </t>
7896                    <t>/ DEVICE_MIDI
7897                    </t>
7898                  <t>/ VOICE_COUNT                  <t>/ VOICE_COUNT
7899                  </t>                  </t>
7900                  <t>/ STREAM_COUNT                  <t>/ STREAM_COUNT
# Line 4903  Schoenebeck'> Line 7915  Schoenebeck'>
7915                  </t>                  </t>
7916                  <t>/ MIDI_INSTRUMENT_INFO                  <t>/ MIDI_INSTRUMENT_INFO
7917                  </t>                  </t>
7918                    <t>/ DB_INSTRUMENT_DIRECTORY_COUNT
7919                    </t>
7920                    <t>/ DB_INSTRUMENT_DIRECTORY_INFO
7921                    </t>
7922                    <t>/ DB_INSTRUMENT_COUNT
7923                    </t>
7924                    <t>/ DB_INSTRUMENT_INFO
7925                    </t>
7926                    <t>/ DB_INSTRUMENTS_JOB_INFO
7927                    </t>
7928                  <t>/ MISCELLANEOUS                  <t>/ MISCELLANEOUS
7929                  </t>                  </t>
7930                    <t>/ TOTAL_STREAM_COUNT
7931                    </t>
7932                  <t>/ TOTAL_VOICE_COUNT                  <t>/ TOTAL_VOICE_COUNT
7933                  </t>                  </t>
7934                  <t>/ GLOBAL_INFO                  <t>/ GLOBAL_INFO
# Line 4937  Schoenebeck'> Line 7961  Schoenebeck'>
7961                  </t>                  </t>
7962                  <t>/ MIDI_INSTRUMENT_MAP SP ALL                  <t>/ MIDI_INSTRUMENT_MAP SP ALL
7963                  </t>                  </t>
7964                    <t>/ SEND_EFFECT_CHAIN SP device_index SP effect_chain
7965                    </t>
7966                    <t>/ SEND_EFFECT_CHAIN SP EFFECT SP device_index SP effect_chain SP chain_pos
7967                    </t>
7968                    <t>/ FX_SEND SP EFFECT SP sampler_channel SP fx_send_id
7969                    </t>
7970                    <t>/ DB_INSTRUMENT_DIRECTORY SP FORCE SP db_path
7971                    </t>
7972                    <t>/ DB_INSTRUMENT_DIRECTORY SP db_path
7973                    </t>
7974                    <t>/ DB_INSTRUMENT SP db_path
7975                    </t>
7976          </list>          </list>
7977  </t>  </t>
7978  <t>get_instruction =  <t>get_instruction =
7979          <list>          <list>
7980                  <t>AVAILABLE_ENGINES                  <t>AVAILABLE_ENGINES
7981                  </t>                  </t>
7982                    <t>/ AVAILABLE_EFFECTS
7983                    </t>
7984                    <t>/ EFFECT_INSTANCES
7985                    </t>
7986                    <t>/ EFFECT SP INFO SP effect_index
7987                    </t>
7988                    <t>/ EFFECT_INSTANCE SP INFO SP effect_instance
7989                    </t>
7990                    <t>/ EFFECT_INSTANCE_INPUT_CONTROL SP INFO SP effect_instance SP input_control
7991                    </t>
7992                    <t>/ SEND_EFFECT_CHAINS SP device_index
7993                    </t>
7994                    <t>/ SEND_EFFECT_CHAIN SP INFO SP device_index SP effect_chain
7995                    </t>
7996                  <t>/ AVAILABLE_MIDI_INPUT_DRIVERS                  <t>/ AVAILABLE_MIDI_INPUT_DRIVERS
7997                  </t>                  </t>
7998                  <t>/ MIDI_INPUT_DRIVER SP INFO SP string                  <t>/ MIDI_INPUT_DRIVER SP INFO SP string
# Line 4989  Schoenebeck'> Line 8039  Schoenebeck'>
8039                  </t>                  </t>
8040                  <t>/ SERVER SP INFO                  <t>/ SERVER SP INFO
8041                  </t>                  </t>
8042                    <t>/ TOTAL_STREAM_COUNT
8043                    </t>
8044                  <t>/ TOTAL_VOICE_COUNT                  <t>/ TOTAL_VOICE_COUNT
8045                  </t>                  </t>
8046                  <t>/ TOTAL_VOICE_COUNT_MAX                  <t>/ TOTAL_VOICE_COUNT_MAX
# Line 5007  Schoenebeck'> Line 8059  Schoenebeck'>
8059                  </t>                  </t>
8060                  <t>/ FX_SEND SP INFO SP sampler_channel SP fx_send_id                  <t>/ FX_SEND SP INFO SP sampler_channel SP fx_send_id
8061                  </t>                  </t>
8062                    <t>/ DB_INSTRUMENT_DIRECTORIES SP RECURSIVE SP db_path
8063                    </t>
8064                    <t>/ DB_INSTRUMENT_DIRECTORIES SP db_path
8065                    </t>
8066                    <t>/ DB_INSTRUMENT_DIRECTORY SP INFO SP db_path
8067                    </t>
8068                    <t>/ DB_INSTRUMENTS SP RECURSIVE SP db_path
8069                    </t>
8070                    <t>/ DB_INSTRUMENTS SP db_path
8071                    </t>
8072                    <t>/ DB_INSTRUMENT SP INFO SP db_path
8073                    </t>
8074                    <t>/ DB_INSTRUMENTS_JOB SP INFO SP number
8075                    </t>
8076                  <t>/ VOLUME                  <t>/ VOLUME
8077                  </t>                  </t>
8078                    <t>/ VOICES
8079                    </t>
8080                    <t>/ STREAMS
8081                    </t>
8082                    <t>/ FILE SP INSTRUMENTS SP filename
8083                    </t>
8084                    <t>/ FILE SP INSTRUMENT SP INFO SP filename SP instrument_index
8085                    </t>
8086          </list>          </list>
8087  </t>  </t>
8088  <t>set_instruction =  <t>set_instruction =
# Line 5019  Schoenebeck'> Line 8093  Schoenebeck'>
8093                  </t>                  </t>
8094                  <t>/ MIDI_INPUT_DEVICE_PARAMETER SP number SP string '=' param_val_list                  <t>/ MIDI_INPUT_DEVICE_PARAMETER SP number SP string '=' param_val_list
8095                  </t>                  </t>
8096                    <t>/ MIDI_INPUT_PORT_PARAMETER SP number SP number SP string '=' NONE
8097                    </t>
8098                  <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
8099                  </t>                  </t>
8100                    <t>/ EFFECT_INSTANCE_INPUT_CONTROL SP VALUE SP effect_instance SP input_control SP control_value
8101                    </t>
8102                  <t>/ CHANNEL SP set_chan_instruction                  <t>/ CHANNEL SP set_chan_instruction
8103                  </t>                  </t>
8104                  <t>/ MIDI_INSTRUMENT_MAP SP NAME SP midi_map SP map_name                  <t>/ MIDI_INSTRUMENT_MAP SP NAME SP midi_map SP map_name
# Line 5033  Schoenebeck'> Line 8111  Schoenebeck'>
8111                  </t>                  </t>
8112                  <t>/ FX_SEND SP LEVEL SP sampler_channel SP fx_send_id SP volume_value                  <t>/ FX_SEND SP LEVEL SP sampler_channel SP fx_send_id SP volume_value
8113                  </t>                  </t>
8114                    <t>/ FX_SEND SP EFFECT SP sampler_channel SP fx_send_id SP effect_chain SP chain_pos
8115                    </t>
8116                    <t>/ DB_INSTRUMENT_DIRECTORY SP NAME SP db_path SP stringval_escaped
8117                    </t>
8118                    <t>/ DB_INSTRUMENT_DIRECTORY SP DESCRIPTION SP db_path SP stringval_escaped
8119                    </t>
8120                    <t>/ DB_INSTRUMENT SP NAME SP db_path SP stringval_escaped
8121                    </t>
8122                    <t>/ DB_INSTRUMENT SP DESCRIPTION SP db_path SP stringval_escaped
8123                    </t>
8124                    <t>/ DB_INSTRUMENT SP FILE_PATH SP filename SP filename
8125                    </t>
8126                  <t>/ ECHO SP boolean                  <t>/ ECHO SP boolean
8127                  </t>                  </t>
8128                  <t>/ VOLUME SP volume_value                  <t>/ VOLUME SP volume_value
8129                  </t>                  </t>
8130                    <t>/ VOICES SP number
8131                    </t>
8132                    <t>/ STREAMS SP number
8133                    </t>
8134          </list>          </list>
8135  </t>  </t>
8136  <t>create_instruction =  <t>create_instruction =
# Line 5053  Schoenebeck'> Line 8147  Schoenebeck'>
8147                  </t>                  </t>
8148                  <t>/ FX_SEND SP sampler_channel SP midi_ctrl SP fx_send_name                  <t>/ FX_SEND SP sampler_channel SP midi_ctrl SP fx_send_name
8149                  </t>                  </t>
8150                    <t>/ EFFECT_INSTANCE SP effect_index
8151                    </t>
8152                    <t>/ EFFECT_INSTANCE SP effect_system SP module SP effect_name
8153                    </t>
8154          </list>          </list>
8155  </t>  </t>
8156  <t>reset_instruction =  <t>reset_instruction =
# Line 5069  Schoenebeck'> Line 8167  Schoenebeck'>
8167                  </t>                  </t>
8168          </list>          </list>
8169  </t>  </t>
8170    <t>find_instruction =
8171            <list>
8172                    <t>DB_INSTRUMENTS SP NON_RECURSIVE SP db_path SP query_val_list
8173                    </t>
8174                    <t>/ DB_INSTRUMENTS SP db_path SP query_val_list
8175                    </t>
8176                    <t>/ DB_INSTRUMENT_DIRECTORIES SP NON_RECURSIVE SP db_path SP query_val_list
8177                    </t>
8178                    <t>/ DB_INSTRUMENT_DIRECTORIES SP db_path SP query_val_list
8179                    </t>
8180                    <t>/ LOST SP DB_INSTRUMENT_FILES
8181                    </t>
8182            </list>
8183    </t>
8184    <t>move_instruction =
8185            <list>
8186                    <t>DB_INSTRUMENT_DIRECTORY SP db_path SP db_path
8187                    </t>
8188                    <t>/ DB_INSTRUMENT SP db_path SP db_path
8189                    </t>
8190            </list>
8191    </t>
8192    <t>copy_instruction =
8193            <list>
8194                    <t>DB_INSTRUMENT_DIRECTORY SP db_path SP db_path
8195                    </t>
8196                    <t>/ DB_INSTRUMENT SP db_path SP db_path
8197                    </t>
8198            </list>
8199    </t>
8200  <t>destroy_instruction =  <t>destroy_instruction =
8201          <list>          <list>
8202                  <t>AUDIO_OUTPUT_DEVICE SP number                  <t>AUDIO_OUTPUT_DEVICE SP number
# Line 5077  Schoenebeck'> Line 8205  Schoenebeck'>
8205                  </t>                  </t>
8206                  <t>/ FX_SEND SP sampler_channel SP fx_send_id                  <t>/ FX_SEND SP sampler_channel SP fx_send_id
8207                  </t>                  </t>
8208                    <t>/ EFFECT_INSTANCE SP number
8209                    </t>
8210          </list>          </list>
8211  </t>  </t>
8212  <t>load_instruction =  <t>load_instruction =
# Line 5087  Schoenebeck'> Line 8217  Schoenebeck'>
8217                  </t>                  </t>
8218          </list>          </list>
8219  </t>  </t>
8220    <t>append_instruction =
8221            <list>
8222                    <t>SEND_EFFECT_CHAIN SP EFFECT SP device_index SP effect_chain SP effect_instance
8223                    </t>
8224            </list>
8225    </t>
8226    <t>insert_instruction =
8227            <list>
8228                    <t>SEND_EFFECT_CHAIN SP EFFECT SP device_index SP effect_chain SP chain_pos SP effect_instance
8229                    </t>
8230            </list>
8231    </t>
8232  <t>set_chan_instruction =  <t>set_chan_instruction =
8233          <list>          <list>
8234                  <t>AUDIO_OUTPUT_DEVICE SP sampler_channel SP device_index                  <t>AUDIO_OUTPUT_DEVICE SP sampler_channel SP device_index
# Line 5119  Schoenebeck'> Line 8261  Schoenebeck'>
8261                  </t>                  </t>
8262          </list>          </list>
8263  </t>  </t>
8264    <t>edit_instruction =
8265            <list>
8266                    <t>CHANNEL SP INSTRUMENT SP sampler_channel
8267                    </t>
8268            </list>
8269    </t>
8270    <t>format_instruction =
8271            <list>
8272                    <t>INSTRUMENTS_DB
8273                    </t>
8274            </list>
8275    </t>
8276  <t>modal_arg =  <t>modal_arg =
8277          <list>          <list>
8278                  <t>/* epsilon (empty argument) */                  <t>/* epsilon (empty argument) */
# Line 5153  Schoenebeck'> Line 8307  Schoenebeck'>
8307                  </t>                  </t>
8308                  <t>/ AVAILABLE_ENGINES                  <t>/ AVAILABLE_ENGINES
8309                  </t>                  </t>
8310                    <t>/ AVAILABLE_EFFECTS
8311                    </t>
8312                    <t>/ EFFECT_INSTANCES
8313                    </t>
8314                    <t>/ SEND_EFFECT_CHAINS SP number
8315                    </t>
8316                  <t>/ AVAILABLE_MIDI_INPUT_DRIVERS                  <t>/ AVAILABLE_MIDI_INPUT_DRIVERS
8317                  </t>                  </t>
8318                  <t>/ AVAILABLE_AUDIO_OUTPUT_DRIVERS                  <t>/ AVAILABLE_AUDIO_OUTPUT_DRIVERS
# Line 5165  Schoenebeck'> Line 8325  Schoenebeck'>
8325                  </t>                  </t>
8326                  <t>/ FX_SENDS SP sampler_channel                  <t>/ FX_SENDS SP sampler_channel
8327                  </t>                  </t>
8328                    <t>/ DB_INSTRUMENT_DIRECTORIES SP RECURSIVE SP db_path
8329                    </t>
8330                    <t>/ DB_INSTRUMENT_DIRECTORIES SP db_path
8331                    </t>
8332                    <t>/ DB_INSTRUMENTS SP RECURSIVE SP db_path
8333                    </t>
8334                    <t>/ DB_INSTRUMENTS SP db_path
8335                    </t>
8336                    <t>/ FILE SP INSTRUMENTS SP filename
8337                    </t>
8338            </list>
8339    </t>
8340    <t>send_instruction =
8341            <list>
8342                    <t>CHANNEL SP MIDI_DATA SP string SP sampler_channel SP number SP number
8343                    </t>
8344          </list>          </list>
8345  </t>  </t>
8346  <t>load_instr_args =  <t>load_instr_args =
# Line 5191  Schoenebeck'> Line 8367  Schoenebeck'>
8367                  </t>                  </t>
8368          </list>          </list>
8369  </t>  </t>
8370    <t>effect_instance =
8371            <list>
8372                    <t>number
8373                    </t>
8374            </list>
8375    </t>
8376  <t>device_index =  <t>device_index =
8377          <list>          <list>
8378                  <t>number                  <t>number
# Line 5261  Schoenebeck'> Line 8443  Schoenebeck'>
8443                  </t>                  </t>
8444          </list>          </list>
8445  </t>  </t>
8446    <t>control_value =
8447            <list>
8448                    <t>real
8449                    </t>
8450            </list>
8451    </t>
8452  <t>sampler_channel =  <t>sampler_channel =
8453          <list>          <list>
8454                  <t>number                  <t>number
# Line 5287  Schoenebeck'> Line 8475  Schoenebeck'>
8475  </t>  </t>
8476  <t>filename =  <t>filename =
8477          <list>          <list>
8478                  <t>stringval                  <t>path
8479                    </t>
8480            </list>
8481    </t>
8482    <t>db_path =
8483            <list>
8484                    <t>path
8485                  </t>                  </t>
8486          </list>          </list>
8487  </t>  </t>
8488  <t>map_name =  <t>map_name =
8489          <list>          <list>
8490                  <t>stringval                  <t>stringval_escaped
8491                  </t>                  </t>
8492          </list>          </list>
8493  </t>  </t>
8494  <t>entry_name =  <t>entry_name =
8495          <list>          <list>
8496                  <t>stringval                  <t>stringval_escaped
8497                  </t>                  </t>
8498          </list>          </list>
8499  </t>  </t>
8500  <t>fx_send_name =  <t>fx_send_name =
8501          <list>          <list>
8502                  <t>stringval                  <t>stringval_escaped
8503                    </t>
8504            </list>
8505    </t>
8506    <t>effect_name =
8507            <list>
8508                    <t>stringval_escaped
8509                    </t>
8510            </list>
8511    </t>
8512    <t>effect_index =
8513            <list>
8514                    <t>number
8515                    </t>
8516            </list>
8517    </t>
8518    <t>effect_chain =
8519            <list>
8520                    <t>number
8521                    </t>
8522            </list>
8523    </t>
8524    <t>chain_pos =
8525            <list>
8526                    <t>number
8527                    </t>
8528            </list>
8529    </t>
8530    <t>input_control =
8531            <list>
8532                    <t>number
8533                  </t>                  </t>
8534          </list>          </list>
8535  </t>  </t>
# Line 5317  Schoenebeck'> Line 8541  Schoenebeck'>
8541                  </t>                  </t>
8542          </list>          </list>
8543  </t>  </t>
8544    
8545  <t>param_val =  <t>param_val =
8546          <list>          <list>
8547                  <t>string                  <t>string
# Line 5329  Schoenebeck'> Line 8554  Schoenebeck'>
8554                  </t>                  </t>
8555          </list>          </list>
8556  </t>  </t>
8557    <t>query_val_list =
8558            <list>
8559                    <t>string '=' query_val
8560                    </t>
8561                    <t>/ query_val_list SP string '=' query_val
8562                    </t>
8563            </list>
8564    </t>
8565    <t>query_val =
8566            <list>
8567                    <t>text_escaped
8568                    </t>
8569                    <t>/ stringval_escaped
8570                    </t>
8571            </list>
8572    </t>
8573    <t>scan_mode =
8574            <list>
8575                    <t>RECURSIVE
8576                    </t>
8577                    <t>/ NON_RECURSIVE
8578                    </t>
8579                    <t>/ FLAT
8580                    </t>
8581            </list>
8582    </t>
8583    <t>effect_system =
8584            <list>
8585                    <t>string
8586                    </t>
8587            </list>
8588    </t>
8589    <t>module =
8590            <list>
8591                    <t>filename
8592                    </t>
8593            </list>
8594    </t>
8595    
8596              <!-- GRAMMAR_BNF_END - do NOT delete or modify this line !!! -->              <!-- GRAMMAR_BNF_END - do NOT delete or modify this line !!! -->
8597    
8598                <section title="Character Set and Escape Sequences" anchor="character_set">
8599                    <t>Older versions of this protocol up to and including v1.1 only
8600                    supported the standard ASCII character set (ASCII code 0 - 127)
8601                    <xref target="RFC20"/>, all younger versions of this protocol
8602                    however support the Extended ASCII character set (ASCII code
8603                    0 - 255). The same group of younger protocols also support
8604                    escape sequences, but only for certain, explicitly declared
8605                    parts of the protocol. The supported escape sequences are
8606                    defined as follows:</t>
8607                    <texttable>
8608                        <ttcol>ASCII Character Sequence</ttcol>
8609                        <ttcol>Translated into (Name)</ttcol>
8610                        <c>\n</c> <c>new line</c>
8611                        <c>\r</c> <c>carriage return</c>
8612                        <c>\f</c> <c>form feed</c>
8613                        <c>\t</c> <c>horizontal tab</c>
8614                        <c>\v</c> <c>vertical tab</c>
8615                        <c>\'</c> <c>apostrophe</c>
8616                        <c>\"</c> <c>quotation mark</c>
8617                        <c>\\</c> <c>backslash</c>
8618                        <c>\OOO</c> <c>three digit octal ASCII code of the character</c>
8619                        <c>\xHH</c> <c>two digit hex ASCII code of the character</c>
8620                    </texttable>
8621                    <t>Notice: due to the transition of certain parts of the
8622                    protocol which now support escape sequences, a slight backward
8623                    incompatibility to protocols version v1.1 and younger has been
8624                    introduced. The only difference is that in parts of the protocol
8625                    where escape characters are now supported, a backslash characters
8626                    MUST be escaped as well (that is as double backslash), whereas
8627                    in the old versions a single backslash was sufficient.</t>
8628    
8629                    <t>The following LSCP commands support escape sequences as part
8630                    of their filename / path based arguments and / or may contain
8631                    a filename / path with escape sequences in their response:
8632                    <list>
8633                        <t><xref target="LOAD INSTRUMENT">"LOAD INSTRUMENT"</xref></t>
8634                        <t><xref target="GET CHANNEL INFO">"GET CHANNEL INFO"</xref></t>
8635                        <t><xref target="MAP MIDI_INSTRUMENT">"MAP MIDI_INSTRUMENT"</xref></t>
8636                        <t><xref target="GET MIDI_INSTRUMENT INFO">"GET MIDI_INSTRUMENT INFO"</xref></t>
8637                        <t><xref target="ADD DB_INSTRUMENT_DIRECTORY">"ADD DB_INSTRUMENT_DIRECTORY"</xref></t>
8638                        <t><xref target="ADD DB_INSTRUMENTS">"ADD DB_INSTRUMENTS"</xref></t>
8639                        <t><xref target="REMOVE DB_INSTRUMENT_DIRECTORY">"REMOVE DB_INSTRUMENT_DIRECTORY"</xref></t>
8640                        <t><xref target="REMOVE DB_INSTRUMENT">"REMOVE DB_INSTRUMENT"</xref></t>
8641                        <t><xref target="GET DB_INSTRUMENT_DIRECTORIES">"GET DB_INSTRUMENT_DIRECTORIES"</xref></t>
8642                        <t><xref target="LIST DB_INSTRUMENT_DIRECTORIES">"LIST DB_INSTRUMENT_DIRECTORIES"</xref></t>
8643                        <t><xref target="GET DB_INSTRUMENT_DIRECTORY INFO">"GET DB_INSTRUMENT_DIRECTORY INFO"</xref></t>
8644                        <t><xref target="GET DB_INSTRUMENTS">"GET DB_INSTRUMENTS"</xref></t>
8645                        <t><xref target="LIST DB_INSTRUMENTS">"LIST DB_INSTRUMENTS"</xref></t>
8646                        <t><xref target="GET DB_INSTRUMENT INFO">"GET DB_INSTRUMENT INFO"</xref></t>
8647                        <t><xref target="SET DB_INSTRUMENT_DIRECTORY NAME">"SET DB_INSTRUMENT_DIRECTORY NAME"</xref></t>
8648                        <t><xref target="SET DB_INSTRUMENT_DIRECTORY DESCRIPTION">"SET DB_INSTRUMENT_DIRECTORY DESCRIPTION"</xref></t>
8649                        <t><xref target="SET DB_INSTRUMENT NAME">"SET DB_INSTRUMENT NAME"</xref></t>
8650                        <t><xref target="SET DB_INSTRUMENT DESCRIPTION">"SET DB_INSTRUMENT DESCRIPTION"</xref></t>
8651                        <t><xref target="FIND DB_INSTRUMENTS">"FIND DB_INSTRUMENTS"</xref></t>
8652                        <t><xref target="FIND DB_INSTRUMENT_DIRECTORIES">"FIND DB_INSTRUMENT_DIRECTORIES"</xref></t>
8653                        <t><xref target="MOVE DB_INSTRUMENT">"MOVE DB_INSTRUMENT"</xref></t>
8654                        <t><xref target="MOVE DB_INSTRUMENT_DIRECTORY">"MOVE DB_INSTRUMENT_DIRECTORY"</xref></t>
8655                        <t><xref target="COPY DB_INSTRUMENT">"COPY DB_INSTRUMENT"</xref></t>
8656                        <t><xref target="COPY DB_INSTRUMENT_DIRECTORY">"COPY DB_INSTRUMENT_DIRECTORY"</xref></t>
8657                        <t><xref target="FIND LOST DB_INSTRUMENT_FILES">"FIND LOST DB_INSTRUMENT_FILES"</xref></t>
8658                        <t><xref target="SET DB_INSTRUMENT FILE_PATH">"SET DB_INSTRUMENT FILE_PATH"</xref></t>
8659                        <t><xref target="GET FILE INSTRUMENTS">"GET FILE INSTRUMENTS"</xref></t>
8660                        <t><xref target="LIST FILE INSTRUMENTS">"LIST FILE INSTRUMENTS"</xref></t>
8661                        <t><xref target="GET FILE INSTRUMENT INFO">"GET FILE INSTRUMENT INFO"</xref></t>
8662                        <t><xref target="GET EFFECT INFO">"GET EFFECT INFO"</xref></t>
8663                        <t><xref target="GET EFFECT_INSTANCE INFO">"GET EFFECT_INSTANCE INFO"</xref></t>
8664                        <t><xref target="CREATE EFFECT_INSTANCE">"CREATE EFFECT_INSTANCE"</xref></t>
8665                    </list>
8666                    Note that the forward slash character ('/') has a special meaning in
8667                    filename / path based arguments: it acts as separator of the nodes in
8668                    the path, thus if a directory- or filename includes a forward slash
8669                    (not intended as path node separator), you MUST escape that slash
8670                    either with the respective hex escape sequence ("\x2f") or with the
8671                    respective octal escape sequence ("\057").
8672                    </t>
8673    
8674                    <t>
8675                    Note for Windows: file path arguments in LSCP are expected
8676                    to use forward slashes as directory node separator similar
8677                    to Unix based operating systems. In contrast to Unix however
8678                    a Windows typical drive character is expected to be
8679                    prefixed to the path. That is an original Windows file path
8680                    like "D:\Sounds\My.gig" would become in LSCP:
8681                    "D:/Sounds/My.gig".
8682                    </t>
8683    
8684                    <t>
8685                    The following LSCP commands even support escape sequences as
8686                    part of at least one of their text-based arguments (i.e. entity name,
8687                    description) and / or may contain escape sequences in at least one of
8688                    their text-based fields in their response:
8689                    <list>
8690                        <t><xref target="GET SERVER INFO">"GET SERVER INFO"</xref></t>
8691                        <t><xref target="GET ENGINE INFO">"GET ENGINE INFO"</xref></t>
8692                        <t><xref target="GET CHANNEL INFO">"GET CHANNEL INFO"</xref></t>
8693                        <t><xref target="CREATE FX_SEND">"CREATE FX_SEND"</xref></t>
8694                        <t><xref target="GET FX_SEND INFO">"GET FX_SEND INFO"</xref></t>
8695                        <t><xref target="SET FX_SEND NAME">"SET FX_SEND NAME"</xref></t>
8696                        <t><xref target="GET MIDI_INSTRUMENT INFO">"GET MIDI_INSTRUMENT INFO"</xref></t>
8697                        <t><xref target="GET MIDI_INSTRUMENT_MAP INFO">"GET MIDI_INSTRUMENT_MAP INFO"</xref></t>
8698                        <t><xref target="ADD MIDI_INSTRUMENT_MAP">"ADD MIDI_INSTRUMENT_MAP"</xref></t>
8699                        <t><xref target="MAP MIDI_INSTRUMENT">"MAP MIDI_INSTRUMENT"</xref></t>
8700                        <t><xref target="SET MIDI_INSTRUMENT_MAP NAME">"SET MIDI_INSTRUMENT_MAP NAME"</xref></t>
8701                        <t><xref target="GET DB_INSTRUMENT_DIRECTORY INFO">"GET DB_INSTRUMENT_DIRECTORY INFO"</xref></t>
8702                        <t><xref target="SET DB_INSTRUMENT_DIRECTORY NAME">"SET DB_INSTRUMENT_DIRECTORY NAME"</xref></t>
8703                        <t><xref target="SET DB_INSTRUMENT_DIRECTORY DESCRIPTION">"SET DB_INSTRUMENT_DIRECTORY DESCRIPTION"</xref></t>
8704                        <t><xref target="FIND DB_INSTRUMENT_DIRECTORIES">"FIND DB_INSTRUMENT_DIRECTORIES"</xref></t>
8705                        <t><xref target="GET DB_INSTRUMENT INFO">"GET DB_INSTRUMENT INFO"</xref></t>
8706                        <t><xref target="SET DB_INSTRUMENT NAME">"SET DB_INSTRUMENT NAME"</xref></t>
8707                        <t><xref target="SET DB_INSTRUMENT DESCRIPTION">"SET DB_INSTRUMENT DESCRIPTION"</xref></t>
8708                        <t><xref target="FIND DB_INSTRUMENTS">"FIND DB_INSTRUMENTS"</xref></t>
8709                        <t><xref target="GET EFFECT INFO">"GET EFFECT INFO"</xref></t>
8710                        <t><xref target="GET EFFECT_INSTANCE INFO">"GET EFFECT_INSTANCE INFO"</xref></t>
8711                        <t><xref target="CREATE EFFECT_INSTANCE">"CREATE EFFECT_INSTANCE"</xref></t>
8712                    </list>
8713                    Please note that these lists are manually maintained. If you
8714                    find a command that also supports escape sequences we forgot to
8715                    mention here, please report it!
8716                    </t>
8717                </section>
8718          </section>          </section>
8719    
8720          <section title="Events" anchor="events">          <section title="Events" anchor="events">
# Line 5434  Schoenebeck'> Line 8818  Schoenebeck'>
8818                  of sampler channels.</t>                  of sampler channels.</t>
8819              </section>              </section>
8820    
8821                <section title="MIDI data on a sampler channel arrived" anchor="SUBSCRIBE CHANNEL_MIDI">
8822                    <t>Client may want to be notified when MIDI data arrive on sampler channels on
8823                    back-end side, by issuing the following command:</t>
8824                    <t>
8825                        <list>
8826                            <t>SUBSCRIBE CHANNEL_MIDI</t>
8827                        </list>
8828                    </t>
8829                    <t>Server will start sending one of the the following notification messages:</t>
8830                    <t>
8831                        <list>
8832                            <t>"NOTIFY:CHANNEL_MIDI:&lt;channel-id&gt; NOTE_ON  &lt;note&gt; &lt;velocity&gt;"</t>
8833                            <t>"NOTIFY:CHANNEL_MIDI:&lt;channel-id&gt; NOTE_OFF &lt;note&gt; &lt;velocity&gt;"</t>
8834                        </list>
8835                    </t>
8836                    <t>where &lt;channel-id&gt; will be replaced by the ID of the sampler channel where the MIDI
8837                    data arrived. &lt;note&gt; and &lt;velocity&gt; are integer values in the range between
8838                    0 .. 127, reflecting the analog meaning of the MIDI specification.
8839                    </t>
8840                    <t>CAUTION: no guarantee whatsoever will be made that MIDI events are actually all
8841                    delivered by this mechanism! With other words: events could be lost at any time!
8842                    This restriction was made to keep the RT-safeness of the backend's MIDI and audio
8843                    thread unaffected by this feature.</t>
8844                </section>
8845    
8846                <section title="MIDI data on a MIDI input device arrived" anchor="SUBSCRIBE DEVICE_MIDI">
8847                        <t>Client may want to be notified when MIDI data arrive on MIDI input devices by issuing the following command:</t>
8848                        <t>
8849                                <list>
8850                                        <t>SUBSCRIBE DEVICE_MIDI</t>
8851                                </list>
8852                        </t>
8853                        <t>Server will start sending one of the the following notification messages:</t>
8854                        <t>
8855                                <list>
8856                                        <t>"NOTIFY:DEVICE_MIDI:&lt;device-id&gt; &lt;port-id&gt; NOTE_ON &lt;note&gt; &lt;velocity&gt;"</t>
8857                                        <t>"NOTIFY:DEVICE_MIDI:&lt;device-id&gt; &lt;port-id&gt; NOTE_OFF &lt;note&gt; &lt;velocity&gt;"</t>
8858                                </list>
8859                        </t>
8860                        <t>where &lt;device-id&gt; &lt;port-id&gt; will be replaced
8861                           by the IDs of the respective MIDI input device and the device's MIDI port where the MIDI
8862                           data arrived. &lt;note&gt; and &lt;velocity&gt; are integer values in the range between
8863                           0 .. 127, reflecting the analog meaning of the MIDI specification.
8864                        </t>
8865                        <t>CAUTION: no guarantee whatsoever will be made that MIDI events are actually all
8866                           delivered by this mechanism! With other words: events could be lost at any time!
8867                           This restriction was made to keep the RT-safeness of the backend's MIDI and audio
8868                           thread unaffected by this feature.</t>
8869                </section>
8870    
8871              <section title="Number of active voices changed" anchor="SUBSCRIBE VOICE_COUNT">              <section title="Number of active voices changed" anchor="SUBSCRIBE VOICE_COUNT">
8872                  <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
8873                  back-end changes by issuing the following command:</t>                  back-end changes by issuing the following command:</t>
# Line 5516  Schoenebeck'> Line 8950  Schoenebeck'>
8950              </section>              </section>
8951    
8952              <section title="Number of effect sends changed" anchor="SUBSCRIBE FX_SEND_COUNT">              <section title="Number of effect sends changed" anchor="SUBSCRIBE FX_SEND_COUNT">
8953                  <t>Client may want to be notified when the number of effect sends on                  <t>Client may want to be notified when the number of effect sends on
8954                  a particular sampler channel is changed by issuing the following command:</t>                  a particular sampler channel is changed by issuing the following command:</t>
8955                  <t>                  <t>
8956                      <list>                      <list>
# Line 5571  Schoenebeck'> Line 9005  Schoenebeck'>
9005                  all currently active voices.</t>                  all currently active voices.</t>
9006              </section>              </section>
9007    
9008                <section title="Total number of active disk streams changed" anchor="SUBSCRIBE TOTAL_STREAM_COUNT">
9009                    <t>Client may want to be notified when the total number of disk streams on the
9010                    back-end changes by issuing the following command:</t>
9011                    <t>
9012                        <list>
9013                            <t>SUBSCRIBE TOTAL_STREAM_COUNT</t>
9014                        </list>
9015                    </t>
9016                    <t>Server will start sending the following notification messages:</t>
9017                    <t>
9018                        <list>
9019                            <t>"NOTIFY:TOTAL_STREAM_COUNT:&lt;streams&gt;"</t>
9020                        </list>
9021                    </t>
9022                    <t>where &lt;streams&gt; will be replaced by the new number of
9023                    all currently active disk streams.</t>
9024                </section>
9025    
9026              <section title="Number of MIDI instrument maps changed" anchor="SUBSCRIBE MIDI_INSTRUMENT_MAP_COUNT">              <section title="Number of MIDI instrument maps changed" anchor="SUBSCRIBE MIDI_INSTRUMENT_MAP_COUNT">
9027                  <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
9028                  back-end changes by issuing the following command:</t>                  back-end changes by issuing the following command:</t>
# Line 5669  Schoenebeck'> Line 9121  Schoenebeck'>
9121                          replaced by the optional dotted floating point value, reflecting the                          replaced by the optional dotted floating point value, reflecting the
9122                          new global volume parameter.</t>                          new global volume parameter.</t>
9123                      </list>                      </list>
9124                        <list>
9125                            <t>"NOTIFY:GLOBAL_INFO:VOICES &lt;max-voices&gt;" - Notifies that the
9126                            golbal limit of the sampler for maximum voices is changed, where
9127                            &lt;max-voices&gt; will be an integer value, reflecting the
9128                            new global voice limit parameter.</t>
9129                        </list>
9130                        <list>
9131                            <t>"NOTIFY:GLOBAL_INFO:STREAMS &lt;max-streams&gt;" - Notifies that the
9132                            golbal limit of the sampler for maximum disk streams is changed, where
9133                            &lt;max-streams&gt; will be an integer value, reflecting the
9134                            new global disk streams limit parameter.</t>
9135                        </list>
9136                    </t>
9137                </section>
9138    
9139                <section title="Number of database instrument directories changed" anchor="SUBSCRIBE DB_INSTRUMENT_DIRECTORY_COUNT">
9140                    <t>Client may want to be notified when the number of instrument
9141                    directories in a particular directory in the instruments database
9142                    is changed by issuing the following command:</t>
9143                    <t>
9144                        <list>
9145                            <t>SUBSCRIBE DB_INSTRUMENT_DIRECTORY_COUNT</t>
9146                        </list>
9147                    </t>
9148                    <t>Server will start sending the following notification messages:</t>
9149                    <t>
9150                        <list>
9151                            <t>"NOTIFY:DB_INSTRUMENT_DIRECTORY_COUNT:&lt;dir-path&gt;"</t>
9152                        </list>
9153                    </t>
9154                    <t>where &lt;dir-path&gt; will be replaced by the absolute path
9155                    name of the directory in the instruments database,
9156                    in which the number of directories is changed.</t>
9157                    <t>Note that when a non-empty directory is removed, this event
9158                    is not sent for the subdirectories in that directory.</t>
9159                </section>
9160    
9161                <section title="Database instrument directory information changed" anchor="SUBSCRIBE DB_INSTRUMENT_DIRECTORY_INFO">
9162                    <t>Client may want to be notified when changes were made to directories
9163                    in the instruments database by issuing the following command:</t>
9164                    <t>
9165                        <list>
9166                            <t>SUBSCRIBE DB_INSTRUMENT_DIRECTORY_INFO</t>
9167                        </list>
9168                    </t>
9169                    <t>Server will start sending the following notification messages:</t>
9170                    <t>
9171                        <list>
9172                            <t>"NOTIFY:DB_INSTRUMENT_DIRECTORY_INFO:&lt;dir-path&gt;"</t>
9173                        </list>
9174                    </t>
9175                    <t>where &lt;dir-path&gt; will be replaced by the absolute path name
9176                    of the directory, for which information changes occurred. The front-end will have to send
9177                    the respective command to actually get the updated directory info. Because these messages
9178                    will be triggered by LSCP commands issued by other clients rather than real
9179                    time events happening on the server, it is believed that an empty notification
9180                    message is sufficient here.</t>
9181                    <t>
9182                        <list>
9183                            <t>"NOTIFY:DB_INSTRUMENT_DIRECTORY_INFO:NAME &lt;old-dir-path&gt; &lt;new-name&gt;"</t>
9184                        </list>
9185                  </t>                  </t>
9186                    <t>where &lt;old-dir-path&gt; is the old absolute path name of the directory
9187                    (encapsulated into apostrophes), which name is changes and &lt;new-name&gt; is
9188                    the new name of the directory, encapsulated into apostrophes.</t>
9189                </section>
9190    
9191                <section title="Number of database instruments changed" anchor="SUBSCRIBE DB_INSTRUMENT_COUNT">
9192                    <t>Client may want to be notified when the number of instruments
9193                    in a particular directory in the instruments database
9194                    is changed by issuing the following command:</t>
9195                    <t>
9196                        <list>
9197                            <t>SUBSCRIBE DB_INSTRUMENT_COUNT</t>
9198                        </list>
9199                    </t>
9200                    <t>Server will start sending the following notification messages:</t>
9201                    <t>
9202                        <list>
9203                            <t>"NOTIFY:DB_INSTRUMENT_COUNT:&lt;dir-path&gt;"</t>
9204                        </list>
9205                    </t>
9206                    <t>where &lt;dir-path&gt; will be replaced by the absolute path
9207                    name of the directory in the instruments database,
9208                    in which the number of instruments is changed.</t>
9209                    <t>Note that when a non-empty directory is removed, this event
9210                    is not sent for the instruments in that directory.</t>
9211                </section>
9212    
9213                <section title="Database instrument information changed" anchor="SUBSCRIBE DB_INSTRUMENT_INFO">
9214                    <t>Client may want to be notified when changes were made to instruments
9215                    in the instruments database by issuing the following command:</t>
9216                    <t>
9217                        <list>
9218                            <t>SUBSCRIBE DB_INSTRUMENT_INFO</t>
9219                        </list>
9220                    </t>
9221                    <t>Server will start sending the following notification messages:</t>
9222                    <t>
9223                        <list>
9224                            <t>"NOTIFY:DB_INSTRUMENT_INFO:&lt;instr-path&gt;"</t>
9225                        </list>
9226                    </t>
9227                    <t>where &lt;instr-path&gt; will be replaced by the absolute path name
9228                    of the instrument, which settings are changed. The front-end will have to send
9229                    the respective command to actually get the updated directory info. Because these messages
9230                    will be triggered by LSCP commands issued by other clients rather than real
9231                    time events happening on the server, it is believed that an empty notification
9232                    message is sufficient here.</t>
9233                    <t>
9234                        <list>
9235                            <t>"NOTIFY:DB_INSTRUMENT_INFO:NAME &lt;old-instr-path&gt; &lt;new-name&gt;"</t>
9236                        </list>
9237                    </t>
9238                    <t>where &lt;old-instr-path&gt; is the old absolute path name of the instrument
9239                    (encapsulated into apostrophes), which name is changes and &lt;new-name&gt; is
9240                    the new name of the instrument, encapsulated into apostrophes.</t>
9241                </section>
9242    
9243                <section title="Database job status information changed" anchor="SUBSCRIBE DB_INSTRUMENTS_JOB_INFO">
9244                    <t>Client may want to be notified when the status of particular database
9245                    instruments job is changed by issuing the following command:</t>
9246                    <t>
9247                        <list>
9248                            <t>SUBSCRIBE DB_INSTRUMENTS_JOB_INFO</t>
9249                        </list>
9250                    </t>
9251                    <t>Server will start sending the following notification messages:</t>
9252                    <t>
9253                        <list>
9254                            <t>"NOTIFY:DB_INSTRUMENTS_JOB_INFO:&lt;job-id&gt;"</t>
9255                        </list>
9256                    </t>
9257                    <t>where &lt;job-id&gt; will be replaced by the numerical ID of the job,
9258                    which status is changed. The front-end will have to send the respective
9259                    command to actually get the status info. Because these messages
9260                    will be triggered by LSCP commands issued by other clients rather than real
9261                    time events happening on the server, it is believed that an empty notification
9262                    message is sufficient here.</t>
9263              </section>              </section>
9264    
9265              <section title="Miscellaneous and debugging events" anchor="SUBSCRIBE MISCELLANEOUS">              <section title="Miscellaneous and debugging events" anchor="SUBSCRIBE MISCELLANEOUS">
# Line 5750  Schoenebeck'> Line 9340  Schoenebeck'>
9340                  </front>                  </front>
9341                  <seriesInfo name="RFC" value="2234" />                  <seriesInfo name="RFC" value="2234" />
9342              </reference>              </reference>
9343                <reference anchor="RFC20">
9344                    <front>
9345                        <title>ASCII format for Network Interchange</title>
9346                        <author>
9347                            <organization>UCLA</organization>
9348                        </author>
9349                        <date year="1969"></date>
9350                    </front>
9351                    <seriesInfo name="RFC" value="20" />
9352                </reference>
9353           </references>           </references>
9354      </back>      </back>
9355    
Legend:
Removed from v.1136  
changed lines
  Added in v.2140
  ViewVC Help
Powered by ViewVC