/[svn]/linuxsampler/trunk/Documentation/lscp.xml
ViewVC logotype

Diff of /linuxsampler/trunk/Documentation/lscp.xml

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

revision 981 by iliev, Sun Dec 17 22:35:01 2006 UTC revision 1686 by schoenebeck, Thu Feb 14 14:58:50 2008 UTC
# Line 16  Line 16 
16       to an annoying "missing Normative/Informative References" error message -->       to an annoying "missing Normative/Informative References" error message -->
17  <?rfc strict="no" ?>  <?rfc strict="no" ?>
18    
19  <rfc category="std" ipr="full3978" docName="LSCP 1.2">  <rfc category="std" ipr="full3978" docName="LSCP 1.4">
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="December" year="2006"/>          <date month="February" year="2008"/>
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 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 -
# Line 2523  Schoenebeck'> Line 2548  Schoenebeck'>
2548                                      </t>                                      </t>
2549                                      <t>INSTRUMENT_NAME -                                      <t>INSTRUMENT_NAME -
2550                                          <list>                                          <list>
2551                                              <t>the instrument name of the loaded instrument</t>                                              <t>the instrument name of the loaded instrument
2552                                                (note: since LSCP 1.2 this character string may contain
2553                                                <xref target="character_set">escape sequences</xref>)</t>
2554                                          </list>                                          </list>
2555                                      </t>                                      </t>
2556                                      <t>INSTRUMENT_STATUS -                                      <t>INSTRUMENT_STATUS -
# Line 2555  Schoenebeck'> Line 2582  Schoenebeck'>
2582                                      <t>VOLUME -                                      <t>VOLUME -
2583                                          <list>                                          <list>
2584                                              <t>optionally dotted number for the channel volume factor                                              <t>optionally dotted number for the channel volume factor
2585                                              (where a value < 1.0 means attenuation and a value >                                              (where a value &lt; 1.0 means attenuation and a value >
2586                                              1.0 means amplification)</t>                                              1.0 means amplification)</t>
2587                                          </list>                                          </list>
2588                                      </t>                                      </t>
# Line 3227  Schoenebeck'> Line 3254  Schoenebeck'>
3254                      </t>                      </t>
3255                  </section>                  </section>
3256    
3257                    <section title="Adding an effect send to a sampler channel" anchor="CREATE FX_SEND">
3258                        <t>The front-end can create an additional effect send on a specific sampler channel
3259                        by sending the following command:</t>
3260                        <t>
3261                            <list>
3262                                <t>CREATE FX_SEND &lt;sampler-channel&gt; &lt;midi-ctrl&gt; [&lt;name&gt;]</t>
3263                            </list>
3264                        </t>
3265                        <t>Where &lt;sampler-channel&gt; is the respective sampler channel
3266                        number as returned by the <xref target="ADD CHANNEL">"ADD CHANNEL"</xref>
3267                        or <xref target="LIST CHANNELS">"LIST CHANNELS"</xref> command, that is the
3268                        sampler channel on which the effect send should be created on, &lt;midi-ctrl&gt;
3269                        is a number between 0..127 defining the MIDI controller which can alter the
3270                        effect send level and &lt;name&gt; is an optional argument defining a name
3271                        for the effect send entity. The name does not have to be unique, but MUST be
3272                        encapsulated into apostrophes and supports escape sequences as described in chapter
3273                        "<xref target="character_set">Character Set and Escape Sequences</xref>".</t>
3274    
3275                        <t>By default, that is as initial routing, the effect send's audio channels
3276                        are automatically routed to the last audio channels of the sampler channel's
3277                        audio output device, that way you can i.e. first increase the amount of audio
3278                        channels on the audio output device for having dedicated effect send output
3279                        channels and when "CREATE FX_SEND" is called, those channels will automatically
3280                        be picked. You can alter the destination channels however with
3281                        <xref target="SET FX_SEND AUDIO_OUTPUT_CHANNEL">"SET FX_SEND AUDIO_OUTPUT_CHANNEL"</xref>.
3282                        </t>
3283    
3284                        <t>Note: Create effect sends on a sampler channel only when needed, because having effect
3285                        sends on a sampler channel will decrease runtime performance, because for implementing channel
3286                        effect sends, separate (sampler channel local) audio buffers are needed to render and mix
3287                        the voices and route the audio signal afterwards to the master outputs and effect send
3288                        outputs (along with their respective effect send levels). A sampler channel without effect
3289                        sends however can mix its voices directly into the audio output devices's audio buffers
3290                        and is thus faster.
3291                        </t>
3292    
3293                        <t>Possible Answers:</t>
3294                        <t>
3295                            <list>
3296                                <t>"OK[&lt;fx-send-id&gt;]" -
3297                                    <list>
3298                                        <t>in case a new effect send could be added to the
3299                                        sampler channel, where &lt;fx-send-id&gt; reflects the
3300                                        unique ID of the newly created effect send entity</t>
3301                                    </list>
3302                                </t>
3303                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
3304                                    <list>
3305                                        <t>when a new effect send could not be added, i.e.
3306                                        due to invalid parameters</t>
3307                                    </list>
3308                                </t>
3309                            </list>
3310                        </t>
3311    
3312                        <t>Examples:</t>
3313                        <t>
3314                            <list>
3315                                <t>C: "CREATE FX_SEND 0 91 'Reverb Send'"</t>
3316                                <t>S: "OK[0]"</t>
3317                            </list>
3318                        </t>
3319                        <t>
3320                            <list>
3321                                <t>C: "CREATE FX_SEND 0 93"</t>
3322                                <t>S: "OK[1]"</t>
3323                            </list>
3324                        </t>
3325                    </section>
3326    
3327                    <section title="Removing an effect send from a sampler channel" anchor="DESTROY FX_SEND">
3328                        <t>The front-end can remove an existing effect send on a specific sampler channel
3329                        by sending the following command:</t>
3330                        <t>
3331                            <list>
3332                                <t>DESTROY FX_SEND &lt;sampler-channel&gt; &lt;fx-send-id&gt;</t>
3333                            </list>
3334                        </t>
3335                        <t>Where &lt;sampler-channel&gt; is the respective sampler channel
3336                        number as returned by the <xref target="ADD CHANNEL">"ADD CHANNEL"</xref>
3337                        or <xref target="LIST CHANNELS">"LIST CHANNELS"</xref> command, that is the
3338                        sampler channel from which the effect send should be removed from and
3339                        &lt;fx-send-id&gt; is the respective effect send number as returned by the
3340                        <xref target="CREATE FX_SEND">"CREATE FX_SEND"</xref>
3341                        or <xref target="LIST FX_SENDS">"LIST FX_SENDS"</xref> command.</t>
3342    
3343                        <t>Possible Answers:</t>
3344                        <t>
3345                            <list>
3346                                <t>"OK" -
3347                                    <list>
3348                                        <t>on success</t>
3349                                    </list>
3350                                </t>
3351                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
3352                                    <list>
3353                                        <t>in case it failed, providing an appropriate error code and
3354                                        error message</t>
3355                                    </list>
3356                                </t>
3357                            </list>
3358                        </t>
3359    
3360                        <t>Example:</t>
3361                        <t>
3362                            <list>
3363                                <t>C: "DESTROY FX_SEND 0 0"</t>
3364                                <t>S: "OK"</t>
3365                            </list>
3366                        </t>
3367                    </section>
3368    
3369                    <section title="Getting amount of effect sends on a sampler channel" anchor="GET FX_SENDS">
3370                        <t>The front-end can ask for the amount of effect sends on a specific sampler channel
3371                        by sending the following command:</t>
3372                        <t>
3373                            <list>
3374                                <t>GET FX_SENDS &lt;sampler-channel&gt;</t>
3375                            </list>
3376                        </t>
3377                        <t>Where &lt;sampler-channel&gt; is the respective sampler channel
3378                        number as returned by the <xref target="ADD CHANNEL">"ADD CHANNEL"</xref>
3379                        or <xref target="LIST CHANNELS">"LIST CHANNELS"</xref> command.</t>
3380    
3381                        <t>Possible Answers:</t>
3382                        <t>
3383                            <list>
3384                                <t>The sampler will answer by returning the number of effect
3385                                sends on the given sampler channel.</t>
3386                            </list>
3387                        </t>
3388    
3389                        <t>Example:</t>
3390                        <t>
3391                            <list>
3392                                <t>C: "GET FX_SENDS 0"</t>
3393                                <t>S: "2"</t>
3394                            </list>
3395                        </t>
3396                    </section>
3397    
3398                    <section title="Listing all effect sends on a sampler channel" anchor="LIST FX_SENDS">
3399                        <t>The front-end can ask for a list of effect sends on a specific sampler channel
3400                        by sending the following command:</t>
3401                        <t>
3402                            <list>
3403                                <t>LIST FX_SENDS &lt;sampler-channel&gt;</t>
3404                            </list>
3405                        </t>
3406                        <t>Where &lt;sampler-channel&gt; is the respective sampler channel
3407                        number as returned by the <xref target="ADD CHANNEL">"ADD CHANNEL"</xref>
3408                        or <xref target="LIST CHANNELS">"LIST CHANNELS"</xref> command.</t>
3409    
3410                        <t>Possible Answers:</t>
3411                        <t>
3412                            <list>
3413                                <t>The sampler will answer by returning a comma separated list
3414                                with all effect sends' numerical IDs on the given sampler
3415                                channel.</t>
3416                            </list>
3417                        </t>
3418    
3419                        <t>Examples:</t>
3420                        <t>
3421                            <list>
3422                                <t>C: "LIST FX_SENDS 0"</t>
3423                                <t>S: "0,1"</t>
3424                            </list>
3425                        </t>
3426                        <t>
3427                            <list>
3428                                <t>C: "LIST FX_SENDS 1"</t>
3429                                <t>S: ""</t>
3430                            </list>
3431                        </t>
3432                    </section>
3433    
3434                    <section title="Getting effect send information" anchor="GET FX_SEND INFO">
3435                        <t>The front-end can ask for the current settings of an effect send entity
3436                        by sending the following command:</t>
3437                        <t>
3438                            <list>
3439                                <t>GET FX_SEND INFO &lt;sampler-channel&gt; &lt;fx-send-id&gt;</t>
3440                            </list>
3441                        </t>
3442                        <t>Where &lt;sampler-channel&gt; is the sampler channel number
3443                        as returned by the <xref target="ADD CHANNEL">"ADD CHANNEL"</xref>
3444                        or <xref target="LIST CHANNELS">"LIST CHANNELS"</xref> command and
3445                        &lt;fx-send-id&gt; reflects the numerical ID of the effect send entity
3446                        as returned by the <xref target="CREATE FX_SEND">"CREATE FX_SEND"</xref>
3447                        or <xref target="LIST FX_SENDS">"LIST FX_SENDS"</xref> command.
3448                       </t>
3449    
3450                        <t>Possible Answers:</t>
3451                        <t>
3452                            <list>
3453                                <t>The sampler will answer by sending a &lt;CRLF&gt; separated list.
3454                                Each answer line begins with the settings category name
3455                                followed by a colon and then a space character &lt;SP&gt; and finally
3456                                the info character string to that setting category. At the
3457                                moment the following categories are defined:</t>
3458    
3459                                <t>
3460                                    <list>
3461                                        <t>NAME -
3462                                            <list>
3463                                                <t>name of the effect send entity
3464                                                (note that this character string may contain
3465                                                 <xref target="character_set">escape sequences</xref>)</t>
3466                                            </list>
3467                                        </t>
3468                                        <t>MIDI_CONTROLLER -
3469                                            <list>
3470                                                <t>a value between 0 and 127 reflecting the MIDI controller
3471                                                which is able to modify the effect send's send level</t>
3472                                            </list>
3473                                        </t>
3474                                        <t>LEVEL -
3475                                            <list>
3476                                                <t>optionally dotted number reflecting the effect send's
3477                                                current send level (where a value &lt; 1.0 means attenuation
3478                                                and a value > 1.0 means amplification)</t>
3479                                            </list>
3480                                        </t>
3481                                        <t>AUDIO_OUTPUT_ROUTING -
3482                                            <list>
3483                                                <t>comma separated list which reflects to which audio
3484                                                channel of the selected audio output device each
3485                                                effect send output channel is routed to, e.g. "0,3" would
3486                                                mean the effect send's output channel 0 is routed to channel
3487                                                0 of the audio output device and the effect send's output
3488                                                channel 1 is routed to the channel 3 of the audio
3489                                                output device (see
3490                                                <xref target="SET FX_SEND AUDIO_OUTPUT_CHANNEL">"SET FX_SEND AUDIO_OUTPUT_CHANNEL"</xref>
3491                                                for details)</t>
3492                                            </list>
3493                                        </t>
3494                                    </list>
3495                                </t>
3496                            </list>
3497                        </t>
3498                        <t>The mentioned fields above don't have to be in particular order.</t>
3499    
3500                        <t>Example:</t>
3501                        <t>
3502                            <list>
3503                                <t>C: "GET FX_SEND INFO 0 0"</t>
3504                                <t>S: "NAME: Reverb Send"</t>
3505                                <t>&nbsp;&nbsp;&nbsp;"MIDI_CONTROLLER: 91"</t>
3506                                <t>&nbsp;&nbsp;&nbsp;"LEVEL: 0.3"</t>
3507                                <t>&nbsp;&nbsp;&nbsp;"AUDIO_OUTPUT_ROUTING: 2,3"</t>
3508                                <t>&nbsp;&nbsp;&nbsp;"."</t>
3509                            </list>
3510                        </t>
3511                    </section>
3512    
3513                    <section title="Changing effect send's name" anchor="SET FX_SEND NAME">
3514                        <t>The front-end can alter the current name of an effect
3515                        send entity by sending the following command:</t>
3516                        <t>
3517                            <list>
3518                                <t>SET FX_SEND NAME &lt;sampler-chan&gt; &lt;fx-send-id&gt; &lt;name&gt;</t>
3519                            </list>
3520                        </t>
3521                        <t>Where &lt;sampler-chan&gt; is the sampler channel number
3522                        as returned by the <xref target="ADD CHANNEL">"ADD CHANNEL"</xref>
3523                        or <xref target="LIST CHANNELS">"LIST CHANNELS"</xref> command,
3524                        &lt;fx-send-id&gt; reflects the numerical ID of the effect send entity
3525                        as returned by the <xref target="CREATE FX_SEND">"CREATE FX_SEND"</xref>
3526                        or <xref target="LIST FX_SENDS">"LIST FX_SENDS"</xref> command and
3527                        &lt;name&gt; is the new name of the effect send entity, which
3528                        does not have to be unique (name MUST be encapsulated into apostrophes
3529                        and supports escape sequences as described in chapter
3530                        "<xref target="character_set">Character Set and Escape Sequences</xref>").
3531                        </t>
3532    
3533                        <t>Possible Answers:</t>
3534                        <t>
3535                            <list>
3536                                <t>"OK" -
3537                                    <list>
3538                                        <t>on success</t>
3539                                    </list>
3540                                </t>
3541                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
3542                                    <list>
3543                                        <t>in case it failed, providing an appropriate error code and error message</t>
3544                                    </list>
3545                                </t>
3546                            </list>
3547                        </t>
3548                        <t>Example:</t>
3549                        <t>
3550                            <list>
3551                                <t>C: "SET FX_SEND NAME 0 0 'Fx Send 1'"</t>
3552                                <t>S: "OK"</t>
3553                            </list>
3554                        </t>
3555                    </section>
3556    
3557                    <section title="Altering effect send's audio routing" anchor="SET FX_SEND AUDIO_OUTPUT_CHANNEL">
3558                        <t>The front-end can alter the destination of an effect send's audio channel on a specific
3559                        sampler channel by sending the following command:</t>
3560                        <t>
3561                            <list>
3562                                <t>SET FX_SEND AUDIO_OUTPUT_CHANNEL &lt;sampler-chan&gt; &lt;fx-send-id&gt; &lt;audio-src&gt; &lt;audio-dst&gt;</t>
3563                            </list>
3564                        </t>
3565                        <t>Where &lt;sampler-chan&gt; is the sampler channel number
3566                        as returned by the <xref target="ADD CHANNEL">"ADD CHANNEL"</xref>
3567                        or <xref target="LIST CHANNELS">"LIST CHANNELS"</xref> command,
3568                        &lt;fx-send-id&gt; reflects the numerical ID of the effect send entity
3569                        as returned by the <xref target="CREATE FX_SEND">"CREATE FX_SEND"</xref>
3570                        or <xref target="LIST FX_SENDS">"LIST FX_SENDS"</xref> command,
3571                        &lt;audio-src&gt; is the numerical ID of the effect send's audio channel
3572                        which should be rerouted and &lt;audio-dst&gt; is the numerical ID of
3573                        the audio channel of the selected audio output device where &lt;audio-src&gt;
3574                        should be routed to.</t>
3575    
3576                        <t>Note that effect sends can only route audio to the same audio output
3577                        device as assigned to the effect send's sampler channel. Also note that an
3578                        effect send entity does always have exactly as much audio channels as its
3579                        sampler channel. So if the sampler channel is stereo, the effect send does
3580                        have two audio channels as well. Also keep in mind that the amount of audio
3581                        channels on a sampler channel might be dependant not only to the deployed
3582                        sampler engine on the sampler channel, but also dependant to the instrument
3583                        currently loaded. However you can (effectively) turn an i.e. stereo effect
3584                        send into a mono one by simply altering its audio routing appropriately.</t>
3585    
3586                        <t>Possible Answers:</t>
3587                        <t>
3588                            <list>
3589                                <t>"OK" -
3590                                    <list>
3591                                        <t>on success</t>
3592                                    </list>
3593                                </t>
3594                                <t>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
3595                                    <list>
3596                                        <t>if audio output channel was set, but there are noteworthy
3597                                        issue(s) related, providing an appropriate warning code and
3598                                        warning message</t>
3599                                    </list>
3600                                </t>
3601                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
3602                                    <list>
3603                                        <t>in case it failed, providing an appropriate error code and error message</t>
3604                                    </list>
3605                                </t>
3606                            </list>
3607                        </t>
3608                        <t>Example:</t>
3609                        <t>
3610                            <list>
3611                                <t>C: "SET FX_SEND AUDIO_OUTPUT_CHANNEL 0 0 0 2"</t>
3612                                <t>S: "OK"</t>
3613                            </list>
3614                        </t>
3615                    </section>
3616    
3617                    <section title="Altering effect send's MIDI controller" anchor="SET FX_SEND MIDI_CONTROLLER">
3618                        <t>The front-end can alter the MIDI controller of an effect
3619                        send entity by sending the following command:</t>
3620                        <t>
3621                            <list>
3622                                <t>SET FX_SEND MIDI_CONTROLLER &lt;sampler-chan&gt; &lt;fx-send-id&gt; &lt;midi-ctrl&gt;</t>
3623                            </list>
3624                        </t>
3625                        <t>Where &lt;sampler-chan&gt; is the sampler channel number
3626                        as returned by the <xref target="ADD CHANNEL">"ADD CHANNEL"</xref>
3627                        or <xref target="LIST CHANNELS">"LIST CHANNELS"</xref> command,
3628                        &lt;fx-send-id&gt; reflects the numerical ID of the effect send entity
3629                        as returned by the <xref target="CREATE FX_SEND">"CREATE FX_SEND"</xref>
3630                        or <xref target="LIST FX_SENDS">"LIST FX_SENDS"</xref> command and
3631                        &lt;midi-ctrl&gt; reflects the MIDI controller which shall be
3632                        able to modify the effect send's send level.</t>
3633    
3634                        <t>Possible Answers:</t>
3635                        <t>
3636                            <list>
3637                                <t>"OK" -
3638                                    <list>
3639                                        <t>on success</t>
3640                                    </list>
3641                                </t>
3642                                <t>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
3643                                    <list>
3644                                        <t>if MIDI controller was set, but there are noteworthy
3645                                        issue(s) related, providing an appropriate warning code and
3646                                        warning message</t>
3647                                    </list>
3648                                </t>
3649                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
3650                                    <list>
3651                                        <t>in case it failed, providing an appropriate error code and error message</t>
3652                                    </list>
3653                                </t>
3654                            </list>
3655                        </t>
3656                        <t>Example:</t>
3657                        <t>
3658                            <list>
3659                                <t>C: "SET FX_SEND MIDI_CONTROLLER 0 0 91"</t>
3660                                <t>S: "OK"</t>
3661                            </list>
3662                        </t>
3663                    </section>
3664    
3665                    <section title="Altering effect send's send level" anchor="SET FX_SEND LEVEL">
3666                        <t>The front-end can alter the current send level of an effect
3667                        send entity by sending the following command:</t>
3668                        <t>
3669                            <list>
3670                                <t>SET FX_SEND LEVEL &lt;sampler-chan&gt; &lt;fx-send-id&gt; &lt;volume&gt;</t>
3671                            </list>
3672                        </t>
3673                        <t>Where &lt;sampler-chan&gt; is the sampler channel number
3674                        as returned by the <xref target="ADD CHANNEL">"ADD CHANNEL"</xref>
3675                        or <xref target="LIST CHANNELS">"LIST CHANNELS"</xref> command,
3676                        &lt;fx-send-id&gt; reflects the numerical ID of the effect send entity
3677                        as returned by the <xref target="CREATE FX_SEND">"CREATE FX_SEND"</xref>
3678                        or <xref target="LIST FX_SENDS">"LIST FX_SENDS"</xref> command and
3679                        &lt;volume&gt; is an optionally dotted positive number (a value
3680                        smaller than 1.0 means attenuation, whereas a value greater than
3681                        1.0 means amplification) reflecting the new send level.</t>
3682    
3683                        <t>Possible Answers:</t>
3684                        <t>
3685                            <list>
3686                                <t>"OK" -
3687                                    <list>
3688                                        <t>on success</t>
3689                                    </list>
3690                                </t>
3691                                <t>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
3692                                    <list>
3693                                        <t>if new send level was set, but there are noteworthy
3694                                        issue(s) related, providing an appropriate warning code and
3695                                        warning message</t>
3696                                    </list>
3697                                </t>
3698                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
3699                                    <list>
3700                                        <t>in case it failed, providing an appropriate error code and error message</t>
3701                                    </list>
3702                                </t>
3703                            </list>
3704                        </t>
3705                        <t>Example:</t>
3706                        <t>
3707                            <list>
3708                                <t>C: "SET FX_SEND LEVEL 0 0 0.15"</t>
3709                                <t>S: "OK"</t>
3710                            </list>
3711                        </t>
3712                    </section>
3713    
3714                  <section title="Resetting a sampler channel" anchor="RESET CHANNEL">                  <section title="Resetting a sampler channel" anchor="RESET CHANNEL">
3715                      <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>
3716                      <t>                      <t>
# Line 3448  Schoenebeck'> Line 3932  Schoenebeck'>
3932                      </t>                      </t>
3933                  </section>                  </section>
3934    
3935                    <section title="Current number of active disk streams" anchor="GET TOTAL_STREAM_COUNT">
3936                        <t>The front-end can ask for the current number of active disk streams on
3937                        the sampler by sending the following command:</t>
3938                        <t>
3939                            <list>
3940                                <t>GET TOTAL_STREAM_COUNT</t>
3941                            </list>
3942                        </t>
3943    
3944                        <t>Possible Answers:</t>
3945                        <t>
3946                            <list>
3947                                <t>LinuxSampler will answer by returning the number of all active
3948                                disk streams on the sampler.</t>
3949                            </list>
3950                        </t>
3951                    </section>
3952    
3953                  <section title="Reset sampler" anchor="RESET">                  <section title="Reset sampler" anchor="RESET">
3954                      <t>The front-end can reset the whole sampler by sending the following command:</t>                      <t>The front-end can reset the whole sampler by sending the following command:</t>
3955                      <t>                      <t>
# Line 3495  Schoenebeck'> Line 3997  Schoenebeck'>
3997                                  <list>                                  <list>
3998                                      <t>DESCRIPTION -                                      <t>DESCRIPTION -
3999                                          <list>                                          <list>
4000                                              <t>arbitrary textual description about the sampler</t>                                              <t>arbitrary textual description about the sampler
4001                                                (note that the character string may contain
4002                                                <xref target="character_set">escape sequences</xref>)</t>
4003                                          </list>                                          </list>
4004                                      </t>                                      </t>
4005                                      <t>VERSION -                                      <t>VERSION -
# Line 3509  Schoenebeck'> Line 4013  Schoenebeck'>
4013                                              complies with (see <xref target="LSCP versioning" /> for details)</t>                                              complies with (see <xref target="LSCP versioning" /> for details)</t>
4014                                          </list>                                          </list>
4015                                      </t>                                      </t>
4016                                        <t>INSTRUMENTS_DB_SUPPORT -
4017                                            <list>
4018                                                <t>either yes or no, specifies whether the
4019                                                sampler is build with instruments database support.</t>
4020                                            </list>
4021                                        </t>
4022                                  </list>                                  </list>
4023                              </t>                              </t>
4024                          </list>                          </list>
# Line 3516  Schoenebeck'> Line 4026  Schoenebeck'>
4026                      <t>The mentioned fields above don't have to be in particular order.                      <t>The mentioned fields above don't have to be in particular order.
4027                      Other fields might be added in future.</t>                      Other fields might be added in future.</t>
4028                  </section>                  </section>
4029    
4030                    <section title="Getting global volume attenuation" anchor="GET VOLUME">
4031                        <t>The client can ask for the current global sampler-wide volume
4032                        attenuation by sending the following command:</t>
4033                        <t>
4034                            <list>
4035                                <t>GET VOLUME</t>
4036                            </list>
4037                        </t>
4038                        <t>Possible Answers:</t>
4039                        <t>
4040                            <list>
4041                                <t>The sampler will always answer by returning the optional
4042                                dotted floating point coefficient, reflecting the current
4043                                global volume attenuation.
4044                                </t>
4045                            </list>
4046                        </t>
4047                        <t>Note: it is up to the respective sampler engine whether to obey
4048                        that global volume parameter or not, but in general all engines SHOULD
4049                        use this parameter.</t>
4050                    </section>
4051    
4052                    <section title="Setting global volume attenuation" anchor="SET VOLUME">
4053                        <t>The client can alter the current global sampler-wide volume
4054                        attenuation by sending the following command:</t>
4055                        <t>
4056                            <list>
4057                                <t>SET VOLUME &lt;volume&gt;</t>
4058                            </list>
4059                        </t>
4060                       <t>Where &lt;volume&gt; should be replaced by the optional dotted
4061                       floating point value, reflecting the new global volume parameter.
4062                       This value might usually be in the range between 0.0 and 1.0, that
4063                       is for attenuating the overall volume.</t>
4064    
4065                        <t>Possible Answers:</t>
4066                        <t>
4067                            <list>
4068                                <t>"OK" -
4069                                    <list>
4070                                        <t>on success</t>
4071                                    </list>
4072                                </t>
4073                                <t>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
4074                                    <list>
4075                                        <t>if the global volume was set, but there are noteworthy
4076                                        issue(s) related, providing an appropriate warning code and
4077                                        warning message</t>
4078                                    </list>
4079                                </t>
4080                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
4081                                    <list>
4082                                        <t>in case it failed, providing an appropriate error code and error message</t>
4083                                    </list>
4084                                </t>
4085                            </list>
4086                        </t>
4087                    </section>
4088              </section>              </section>
4089    
4090    
# Line 3546  Schoenebeck'> Line 4115  Schoenebeck'>
4115                  cause the sampler to switch to the respective instrument as                  cause the sampler to switch to the respective instrument as
4116                  reflected by the current MIDI instrument map.</t>                  reflected by the current MIDI instrument map.</t>
4117    
4118                  <section title="Create a new MIDI instrument map" anchor="ADD MIDI_INSTRUMENT MAP">                  <section title="Create a new MIDI instrument map" anchor="ADD MIDI_INSTRUMENT_MAP">
4119                      <t>The front-end can add a new MIDI instrument map by sending                      <t>The front-end can add a new MIDI instrument map by sending
4120                      the following command:</t>                      the following command:</t>
4121                      <t>                      <t>
# Line 3556  Schoenebeck'> Line 4125  Schoenebeck'>
4125                      </t>                      </t>
4126                      <t>Where &lt;name&gt; is an optional argument allowing to                      <t>Where &lt;name&gt; is an optional argument allowing to
4127                      assign a custom name to the new map. MIDI instrument Map                      assign a custom name to the new map. MIDI instrument Map
4128                      names do not have to be unique.</t>                      names do not have to be unique, but MUST be encapsulated
4129                        into apostrophes and support escape sequences as described
4130                        in chapter "<xref target="character_set">Character Set and Escape Sequences</xref>".
4131                        </t>
4132    
4133                      <t>Possible Answers:</t>                      <t>Possible Answers:</t>
4134                      <t>                      <t>
# Line 3727  Schoenebeck'> Line 4299  Schoenebeck'>
4299                                      <t>NAME -                                      <t>NAME -
4300                                          <list>                                          <list>
4301                                              <t>custom name of the given map,                                              <t>custom name of the given map,
4302                                              which does not have to be unique</t>                                              which does not have to be unique
4303                                                (note that this character string may contain
4304                                                 <xref target="character_set">escape sequences</xref>)</t>
4305                                            </list>
4306                                        </t>
4307                                        <t>DEFAULT -
4308                                            <list>
4309                                                <t>either true or false,
4310                                                defines whether this map is the default map</t>
4311                                          </list>                                          </list>
4312                                      </t>                                      </t>
4313                                  </list>                                  </list>
# Line 3741  Schoenebeck'> Line 4321  Schoenebeck'>
4321                          <list>                          <list>
4322                              <t>C: "GET MIDI_INSTRUMENT_MAP INFO 0"</t>                              <t>C: "GET MIDI_INSTRUMENT_MAP INFO 0"</t>
4323                              <t>S: "NAME: Standard Map"</t>                              <t>S: "NAME: Standard Map"</t>
4324                                <t>&nbsp;&nbsp;&nbsp;"DEFAULT: true"</t>
4325                              <t>&nbsp;&nbsp;&nbsp;"."</t>                              <t>&nbsp;&nbsp;&nbsp;"."</t>
4326                          </list>                          </list>
4327                      </t>                      </t>
# Line 3756  Schoenebeck'> Line 4337  Schoenebeck'>
4337                      </t>                      </t>
4338                      <t>Where &lt;map&gt; is the numerical ID of the map and                      <t>Where &lt;map&gt; is the numerical ID of the map and
4339                      &lt;name&gt; the new custom name of the map, which does not                      &lt;name&gt; the new custom name of the map, which does not
4340                      have to be unique.</t>                      have to be unique (name MUST be encapsulated into apostrophes
4341                        and supports escape sequences as described in chapter
4342                        "<xref target="character_set">Character Set and Escape Sequences</xref>").
4343                        </t>
4344    
4345                      <t>Possible Answers:</t>                      <t>Possible Answers:</t>
4346                      <t>                      <t>
# Line 3789  Schoenebeck'> Line 4373  Schoenebeck'>
4373                      command:</t>                      command:</t>
4374                      <t>                      <t>
4375                          <list>                          <list>
4376                              <t>MAP MIDI_INSTRUMENT &lt;map&gt;                              <t>MAP MIDI_INSTRUMENT [NON_MODAL] &lt;map&gt;
4377                              &lt;midi_bank&gt; &lt;midi_prog&gt; &lt;engine_name&gt;                              &lt;midi_bank&gt; &lt;midi_prog&gt; &lt;engine_name&gt;
4378                              &lt;filename&gt; &lt;instrument_index&gt; &lt;volume_value&gt;                              &lt;filename&gt; &lt;instrument_index&gt; &lt;volume_value&gt;
4379                              [&lt;instr_load_mode&gt;] [&lt;name&gt;]</t>                              [&lt;instr_load_mode&gt;] [&lt;name&gt;]</t>
# Line 3803  Schoenebeck'> Line 4387  Schoenebeck'>
4387                      index, &lt;engine_name&gt; a sampler engine name as returned by                      index, &lt;engine_name&gt; a sampler engine name as returned by
4388                      the <xref target="LIST AVAILABLE_ENGINES">"LIST AVAILABLE_ENGINES"</xref>                      the <xref target="LIST AVAILABLE_ENGINES">"LIST AVAILABLE_ENGINES"</xref>
4389                      command (not encapsulated into apostrophes), &lt;filename&gt; the name                      command (not encapsulated into apostrophes), &lt;filename&gt; the name
4390                      of the instrument's file to be deployed (encapsulated into apostrophes),                      of the instrument's file to be deployed (encapsulated into apostrophes,
4391                        supporting escape sequences as described in chapter
4392                        "<xref target="character_set">Character Set and Escape Sequences</xref>"),
4393                      &lt;instrument_index&gt; the index (integer value) of the instrument                      &lt;instrument_index&gt; the index (integer value) of the instrument
4394                      within the given file, &lt;volume_value&gt; reflects the master                      within the given file, &lt;volume_value&gt; reflects the master
4395                      volume of the instrument as optionally dotted number (where a                      volume of the instrument as optionally dotted number (where a
4396                      value < 1.0 means attenuation and a value > 1.0 means                      value &lt; 1.0 means attenuation and a value > 1.0 means
4397                      amplification). This parameter easily allows to adjust the                      amplification). This parameter easily allows to adjust the
4398                      volume of all intruments within a custom instrument map                      volume of all intruments within a custom instrument map
4399                      without having to adjust their instrument files. The                      without having to adjust their instrument files. The
# Line 3842  Schoenebeck'> Line 4428  Schoenebeck'>
4428                              <t>"PERSISTENT" -                              <t>"PERSISTENT" -
4429                                  <list>                                  <list>
4430                                      <t>The instrument will immediately be loaded                                      <t>The instrument will immediately be loaded
4431                                      into memory in the background when this mapping                                      into memory when this mapping
4432                                      command is sent and the instrument is kept all                                      command is sent and the instrument is kept all
4433                                      the time. Instruments with this mode are                                      the time. Instruments with this mode are
4434                                      only freed when the sampler is reset or all                                      only freed when the sampler is reset or all
# Line 3885  Schoenebeck'> Line 4471  Schoenebeck'>
4471                      load modes of entries, the frontend should retrieve the actual                      load modes of entries, the frontend should retrieve the actual
4472                      mode by i.e. sending                      mode by i.e. sending
4473                      <xref target="GET MIDI_INSTRUMENT INFO">"GET MIDI_INSTRUMENT INFO"</xref>                      <xref target="GET MIDI_INSTRUMENT INFO">"GET MIDI_INSTRUMENT INFO"</xref>
4474                      command(s). Finally the OPTIONAL &lt;name&gt; argument allows to                      command(s). Finally the OPTIONAL &lt;name&gt; argument allows to set a custom name
4475                      set a custom name (encapsulated into apostrophes) for the mapping                      (encapsulated into apostrophes, supporting escape sequences as described in chapter
4476                      entry, useful for frontends for displaying an appropriate name for                      "<xref target="character_set">Character Set and Escape Sequences</xref>") for the
4477                        mapping entry, useful for frontends for displaying an appropriate name for
4478                      mapped instruments (using                      mapped instruments (using
4479                      <xref target="GET MIDI_INSTRUMENT INFO">"GET MIDI_INSTRUMENT INFO"</xref>).                      <xref target="GET MIDI_INSTRUMENT INFO">"GET MIDI_INSTRUMENT INFO"</xref>).
4480                      </t>                      </t>
4481                      <t>                      <t>
4482                      The "MAP MIDI_INSTRUMENT" command                      By default, "MAP MIDI_INSTRUMENT" commands block until the mapping is
4483                      will immediately return, thus it will not block when an                      completely established in the sampler. The OPTIONAL "NON_MODAL" argument
4484                      instrument is to be loaded due to a "PERSISTENT" type                      however causes the respective "MAP MIDI_INSTRUMENT" command to return
4485                      entry as instruments are loaded in the background. As a                      immediately, that is to let the sampler establish the mapping in the
4486                      consequence this command may not necessarily return an error                      background. So this argument might be especially useful for mappings with
4487                      i.e. when the given instrument file does not exist or may                      a "PERSISTENT" type, because these have to load the respective instruments
4488                      turn out to be corrupt.                      immediately and might thus block for a very long time. It is recommended
4489                        however to use the OPTIONAL "NON_MODAL" argument only if really necessary,
4490                        because it has the following drawbacks: as "NON_MODAL" instructions return
4491                        immediately, they may not necessarily return an error i.e. when the given
4492                        instrument file turns out to be corrupt, beside that subsequent commands
4493                        in a LSCP instruction sequence might fail, because mandatory mappings are
4494                        not yet completed.
4495                      </t>                      </t>
4496    
4497                      <t>Possible Answers:</t>                      <t>Possible Answers:</t>
# Line 3941  Schoenebeck'> Line 4534  Schoenebeck'>
4534                      </t>                      </t>
4535                      <t>                      <t>
4536                          <list>                          <list>
4537                              <t>C: "MAP MIDI_INSTRUMENT 1 8 120 gig '/home/joe/foodrums.gig' 0 1.0 PERSISTENT 'Foo Drumkit'"</t>                              <t>C: "MAP MIDI_INSTRUMENT NON_MODAL 1 8 120 gig '/home/joe/foodrums.gig' 0 1.0 PERSISTENT 'Foo Drumkit'"</t>
4538                              <t>S: "OK"</t>                              <t>S: "OK"</t>
4539                          </list>                          </list>
4540                      </t>                      </t>
# Line 4105  Schoenebeck'> Line 4698  Schoenebeck'>
4698                                      name for this mapped instrument. It can be set and                                      name for this mapped instrument. It can be set and
4699                                      changed with the                                      changed with the
4700                                      <xref target="MAP MIDI_INSTRUMENT">"MAP MIDI_INSTRUMENT"</xref>                                      <xref target="MAP MIDI_INSTRUMENT">"MAP MIDI_INSTRUMENT"</xref>
4701                                      command and does not have to be unique.</t>                                      command and does not have to be unique.
4702                                        (note that this character string may contain
4703                                        <xref target="character_set">escape sequences</xref>)</t>
4704                                  </list>                                  </list>
4705                              </t>                              </t>
4706                              <t>"ENGINE_NAME" -                              <t>"ENGINE_NAME" -
# Line 4116  Schoenebeck'> Line 4711  Schoenebeck'>
4711                              </t>                              </t>
4712                              <t>"INSTRUMENT_FILE" -                              <t>"INSTRUMENT_FILE" -
4713                                  <list>                                  <list>
4714                                      <t>File name of the instrument.</t>                                      <t>File name of the instrument
4715                                        (note that this path may contain
4716                                        <xref target="character_set">escape sequences</xref>).</t>
4717                                  </list>                                  </list>
4718                              </t>                              </t>
4719                              <t>"INSTRUMENT_NR" -                              <t>"INSTRUMENT_NR" -
# Line 4128  Schoenebeck'> Line 4725  Schoenebeck'>
4725                                  <list>                                  <list>
4726                                      <t>Name of the loaded instrument as reflected by its file.                                      <t>Name of the loaded instrument as reflected by its file.
4727                                      In contrast to the "NAME" field, the "INSTRUMENT_NAME" field                                      In contrast to the "NAME" field, the "INSTRUMENT_NAME" field
4728                                      cannot be changed.</t>                                      cannot be changed (note that this character string may contain
4729                                        <xref target="character_set">escape sequences</xref>).</t>
4730                                  </list>                                  </list>
4731                              </t>                              </t>
4732                              <t>"LOAD_MODE" -                              <t>"LOAD_MODE" -
# Line 4140  Schoenebeck'> Line 4738  Schoenebeck'>
4738                              <t>"VOLUME" -                              <t>"VOLUME" -
4739                                  <list>                                  <list>
4740                                      <t>master volume of the instrument as optionally                                      <t>master volume of the instrument as optionally
4741                                      dotted number (where a value < 1.0 means attenuation                                      dotted number (where a value &lt; 1.0 means attenuation
4742                                      and a value > 1.0 means amplification)</t>                                      and a value > 1.0 means amplification)</t>
4743                                  </list>                                  </list>
4744                              </t>                              </t>
# Line 4212  Schoenebeck'> Line 4810  Schoenebeck'>
4810                  </section>                  </section>
4811              </section>              </section>
4812    
         </section>  
4813    
4814                <section title="Managing Instruments Database" anchor="Managing Instruments Database">
4815                    <t>The following commands describe how to use and manage
4816                    the instruments database.</t>
4817                    <t>Notice:</t>
4818                        <t>
4819                            <list>
4820                                <t>All command arguments representing a path or
4821                                instrument/directory name support escape sequences as described in chapter
4822                                "<xref target="character_set">Character Set and Escape Sequences</xref>".
4823                                </t>
4824                                <t>All occurrences of a forward slash in instrument and directory
4825                                   names are escaped with its hex (\x2f) or octal (\057) escape sequence.
4826                                </t>
4827                            </list>
4828                        </t>
4829    
4830                    <section title="Creating a new instrument directory" anchor="ADD DB_INSTRUMENT_DIRECTORY">
4831                        <t>The front-end can add a new instrument directory to the
4832                        instruments database by sending the following command:</t>
4833                        <t>
4834                            <list>
4835                                <t>ADD DB_INSTRUMENT_DIRECTORY &lt;dir&gt;</t>
4836                            </list>
4837                        </t>
4838                        <t>Where &lt;dir&gt; is the absolute path name of the directory
4839                        to be created (encapsulated into apostrophes).</t>
4840    
4841                        <t>Possible Answers:</t>
4842                        <t>
4843                            <list>
4844                                <t>"OK" -
4845                                    <list>
4846                                        <t>on success</t>
4847                                    </list>
4848                                </t>
4849                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
4850                                    <list>
4851                                        <t>when the directory could not be created, which
4852                                        can happen if the directory already exists or the
4853                                        name contains not allowed symbols</t>
4854                                    </list>
4855                                </t>
4856                            </list>
4857                        </t>
4858    
4859                        <t>Examples:</t>
4860                        <t>
4861                            <list>
4862                                <t>C: "ADD DB_INSTRUMENT_DIRECTORY '/Piano Collection'"</t>
4863                                <t>S: "OK"</t>
4864                            </list>
4865                        </t>
4866                    </section>
4867    
4868                    <section title="Deleting an instrument directory" anchor="REMOVE DB_INSTRUMENT_DIRECTORY">
4869                        <t>The front-end can delete a particular instrument directory
4870                        from the instruments database by sending the following command:</t>
4871                        <t>
4872                            <list>
4873                                <t>REMOVE DB_INSTRUMENT_DIRECTORY [FORCE] &lt;dir&gt;</t>
4874                            </list>
4875                        </t>
4876                        <t>Where &lt;dir&gt; is the absolute path name of the directory
4877                        to delete. The optional FORCE argument can be used to
4878                        force the deletion of a non-empty directory and all its content.</t>
4879    
4880                        <t>Possible Answers:</t>
4881                        <t>
4882                            <list>
4883                                <t>"OK" -
4884                                    <list>
4885                                        <t>if the directory is deleted successfully</t>
4886                                    </list>
4887                                </t>
4888                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
4889                                    <list>
4890                                        <t>if the given directory does not exist, or
4891                                        if trying to delete a non-empty directory,
4892                                        without using the FORCE argument.</t>
4893                                    </list>
4894                                </t>
4895                            </list>
4896                        </t>
4897    
4898                        <t>Examples:</t>
4899                        <t>
4900                            <list>
4901                                <t>C: "REMOVE DB_INSTRUMENT_DIRECTORY FORCE '/Piano Collection'"</t>
4902                                <t>S: "OK"</t>
4903                            </list>
4904                        </t>
4905                    </section>
4906    
4907                    <section title="Getting amount of instrument directories" anchor="GET DB_INSTRUMENT_DIRECTORIES">
4908                        <t>The front-end can retrieve the current amount of
4909                        directories in a specific directory by sending the following command:</t>
4910                        <t>
4911                            <list>
4912                                <t>GET DB_INSTRUMENT_DIRECTORIES [RECURSIVE] &lt;dir&gt;</t>
4913                            </list>
4914                        </t>
4915                        <t>Where &lt;dir&gt; should be replaced by the absolute path
4916                        name of the directory. If RECURSIVE is specified, the number of
4917                        all directories, including those located in subdirectories of the
4918                        specified directory, will be returned.</t>
4919    
4920                        <t>Possible Answers:</t>
4921                        <t>
4922                            <list>
4923                                <t>The current number of instrument directories
4924                                in the specified directory.</t>
4925                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
4926                                    <list>
4927                                        <t>if the given directory does not exist.</t>
4928                                    </list>
4929                                </t>
4930                            </list>
4931                        </t>
4932    
4933                        <t>Example:</t>
4934                        <t>
4935                            <list>
4936                                <t>C: "GET DB_INSTRUMENT_DIRECTORIES '/'"</t>
4937                                <t>S: "2"</t>
4938                            </list>
4939                        </t>
4940                    </section>
4941    
4942                    <section title="Listing all directories in specific directory" anchor="LIST DB_INSTRUMENT_DIRECTORIES">
4943                        <t>The front-end can retrieve the current list of directories
4944                        in specific directory by sending the following command:</t>
4945                        <t>
4946                            <list>
4947                                <t>LIST DB_INSTRUMENT_DIRECTORIES [RECURSIVE] &lt;dir&gt;</t>
4948                            </list>
4949                        </t>
4950                        <t>Where &lt;dir&gt; should be replaced by the absolute path
4951                        name of the directory. If RECURSIVE is specified, the absolute path names
4952                        of all directories, including those located in subdirectories of the
4953                        specified directory, will be returned.</t>
4954    
4955                        <t>Possible Answers:</t>
4956                        <t>
4957                            <list>
4958                                <t>A comma separated list of all instrument directories
4959                                (encapsulated into apostrophes) in the specified directory.</t>
4960                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
4961                                    <list>
4962                                        <t>if the given directory does not exist.</t>
4963                                    </list>
4964                                </t>
4965                            </list>
4966                        </t>
4967                        <t>Example:</t>
4968                        <t>
4969                            <list>
4970                                <t>C: "LIST DB_INSTRUMENT_DIRECTORIES '/'"</t>
4971                                <t>S: "'Piano Collection','Percussion Collection'"</t>
4972                            </list>
4973                        </t>
4974                        <t>
4975                            <list>
4976                                <t>C: "LIST DB_INSTRUMENT_DIRECTORIES RECURSIVE '/'"</t>
4977                                <t>S: "'/Piano Collection','/Piano Collection/Acoustic','/Piano Collection/Acoustic/New','/Percussion Collection'"</t>
4978                            </list>
4979                        </t>
4980                    </section>
4981    
4982                    <section title="Getting instrument directory information" anchor="GET DB_INSTRUMENT_DIRECTORY INFO">
4983                        <t>The front-end can ask for the current settings of an
4984                        instrument directory by sending the following command:</t>
4985                        <t>
4986                            <list>
4987                                <t>GET DB_INSTRUMENT_DIRECTORY INFO &lt;dir&gt;</t>
4988                            </list>
4989                        </t>
4990                        <t>Where &lt;dir&gt; should be replaced by the absolute path
4991                        name of the directory the front-end is interested in.</t>
4992    
4993                        <t>Possible Answers:</t>
4994                        <t>
4995                            <list>
4996                                <t>LinuxSampler will answer by sending a &lt;CRLF&gt; separated list.
4997                                Each answer line begins with the settings category name
4998                                followed by a colon and then a space character &lt;SP&gt; and finally
4999                                the info character string to that setting category. At the
5000                                moment the following categories are defined:</t>
5001    
5002                                <t>
5003                                    <list>
5004                                        <t>DESCRIPTION -
5005                                            <list>
5006                                                <t>A brief description of the directory content.
5007                                                Note that the character string may contain
5008                                                <xref target="character_set">escape sequences</xref>.</t>
5009                                            </list>
5010                                        </t>
5011                                        <t>CREATED -
5012                                            <list>
5013                                                <t>The creation date and time of the directory,
5014                                                represented in "YYYY-MM-DD HH:MM:SS" format</t>
5015                                            </list>
5016                                        </t>
5017                                        <t>MODIFIED -
5018                                            <list>
5019                                                <t>The date and time of the last modification of the
5020                                                directory, represented in "YYYY-MM-DD HH:MM:SS" format</t>
5021                                            </list>
5022                                        </t>
5023                                    </list>
5024                                </t>
5025                            </list>
5026                        </t>
5027                        <t>The mentioned fields above don't have to be in particular order.</t>
5028    
5029                        <t>Example:</t>
5030                        <t>
5031                            <list>
5032                                <t>C: "GET DB_INSTRUMENT_DIRECTORY INFO '/Piano Collection'"</t>
5033                                <t>S: "DESCRIPTION: Piano collection of instruments in GigaSampler format."</t>
5034                                <t>&nbsp;&nbsp;&nbsp;"CREATED: 2007-02-05 10:23:12"</t>
5035                                <t>&nbsp;&nbsp;&nbsp;"MODIFIED: 2007-04-07 12:50:21"</t>
5036                                <t>&nbsp;&nbsp;&nbsp;"."</t>
5037                            </list>
5038                        </t>
5039                    </section>
5040    
5041                    <section title="Renaming an instrument directory" anchor="SET DB_INSTRUMENT_DIRECTORY NAME">
5042                        <t>The front-end can alter the name of a specific
5043                        instrument directory by sending the following command:</t>
5044                        <t>
5045                            <list>
5046                                <t>SET DB_INSTRUMENT_DIRECTORY NAME &lt;dir&gt; &lt;name&gt;</t>
5047                            </list>
5048                        </t>
5049                        <t>Where &lt;dir&gt; is the absolute path name of the directory and
5050                        &lt;name&gt; is the new name for that directory.</t>
5051    
5052                        <t>Possible Answers:</t>
5053                        <t>
5054                            <list>
5055                                <t>"OK" -
5056                                    <list>
5057                                        <t>on success</t>
5058                                    </list>
5059                                </t>
5060                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
5061                                    <list>
5062                                        <t>in case the given directory does not exists,
5063                                        or if a directory with name equal to the new
5064                                        name already exists.</t>
5065                                    </list>
5066                                </t>
5067                            </list>
5068                        </t>
5069    
5070                        <t>Example:</t>
5071                        <t>
5072                            <list>
5073                                <t>C: "SET DB_INSTRUMENT_DIRECTORY NAME '/Piano Collection/Acustic' 'Acoustic'"</t>
5074                                <t>S: "OK"</t>
5075                            </list>
5076                        </t>
5077                    </section>
5078    
5079                    <section title="Moving an instrument directory" anchor="MOVE DB_INSTRUMENT_DIRECTORY">
5080                        <t>The front-end can move a specific
5081                        instrument directory by sending the following command:</t>
5082                        <t>
5083                            <list>
5084                                <t>MOVE DB_INSTRUMENT_DIRECTORY &lt;dir&gt; &lt;dst&gt;</t>
5085                            </list>
5086                        </t>
5087                        <t>Where &lt;dir&gt; is the absolute path name of the directory
5088                        to move and &lt;dst&gt; is the location where the directory will
5089                        be moved to.</t>
5090    
5091                        <t>Possible Answers:</t>
5092                        <t>
5093                            <list>
5094                                <t>"OK" -
5095                                    <list>
5096                                        <t>on success</t>
5097                                    </list>
5098                                </t>
5099                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
5100                                    <list>
5101                                        <t>in case a given directory does not exists,
5102                                        or if a directory with name equal to the name
5103                                        of the specified directory already exists in
5104                                        the destination directory. Error is also thrown
5105                                        when trying to move a directory to a subdirectory
5106                                        of itself.</t>
5107                                    </list>
5108                                </t>
5109                            </list>
5110                        </t>
5111    
5112                        <t>Example:</t>
5113                        <t>
5114                            <list>
5115                                <t>C: "MOVE DB_INSTRUMENT_DIRECTORY '/Acoustic' '/Piano Collection/Acoustic'"</t>
5116                                <t>S: "OK"</t>
5117                            </list>
5118                        </t>
5119                    </section>
5120    
5121                    <section title="Copying instrument directories" anchor="COPY DB_INSTRUMENT_DIRECTORY">
5122                        <t>The front-end can copy a specific
5123                        instrument directory by sending the following command:</t>
5124                        <t>
5125                            <list>
5126                                <t>COPY DB_INSTRUMENT_DIRECTORY &lt;dir&gt; &lt;dst&gt;</t>
5127                            </list>
5128                        </t>
5129                        <t>Where &lt;dir&gt; is the absolute path name of the directory
5130                        to copy and &lt;dst&gt; is the location where the directory will
5131                        be copied to.</t>
5132    
5133                        <t>Possible Answers:</t>
5134                        <t>
5135                            <list>
5136                                <t>"OK" -
5137                                    <list>
5138                                        <t>on success</t>
5139                                    </list>
5140                                </t>
5141                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
5142                                    <list>
5143                                        <t>in case a given directory does not exists,
5144                                        or if a directory with name equal to the name
5145                                        of the specified directory already exists in
5146                                        the destination directory. Error is also thrown
5147                                        when trying to copy a directory to a subdirectory
5148                                        of itself.</t>
5149                                    </list>
5150                                </t>
5151                            </list>
5152                        </t>
5153    
5154                        <t>Example:</t>
5155                        <t>
5156                            <list>
5157                                <t>C: "COPY DB_INSTRUMENT_DIRECTORY '/Piano Collection/Acoustic' '/Acoustic/Pianos'"</t>
5158                                <t>S: "OK"</t>
5159                            </list>
5160                        </t>
5161                    </section>
5162    
5163                    <section title="Changing the description of directory" anchor="SET DB_INSTRUMENT_DIRECTORY DESCRIPTION">
5164                        <t>The front-end can alter the description of a specific
5165                        instrument directory by sending the following command:</t>
5166                        <t>
5167                            <list>
5168                                <t>SET DB_INSTRUMENT_DIRECTORY DESCRIPTION &lt;dir&gt; &lt;desc&gt;</t>
5169                            </list>
5170                        </t>
5171                        <t>Where &lt;dir&gt; is the absolute path name of the directory and
5172                        &lt;desc&gt; is the new description for the directory
5173                        (encapsulated into apostrophes, supporting escape sequences as described in chapter
5174                        "<xref target="character_set">Character Set and Escape Sequences</xref>").</t>
5175    
5176                        <t>Possible Answers:</t>
5177                        <t>
5178                            <list>
5179                                <t>"OK" -
5180                                    <list>
5181                                        <t>on success</t>
5182                                    </list>
5183                                </t>
5184                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
5185                                    <list>
5186                                        <t>in case the given directory does not exists.</t>
5187                                    </list>
5188                                </t>
5189                            </list>
5190                        </t>
5191    
5192                        <t>Example:</t>
5193                        <t>
5194                            <list>
5195                                <t>C: "SET DB_INSTRUMENT_DIRECTORY DESCRIPTION '/Piano Collection' 'A collection of piano instruments in various format.'"</t>
5196                                <t>S: "OK"</t>
5197                            </list>
5198                        </t>
5199                    </section>
5200    
5201                    <section title="Finding directories" anchor="FIND DB_INSTRUMENT_DIRECTORIES">
5202                        <t>The front-end can search for directories
5203                        in specific directory by sending the following command:</t>
5204                        <t>
5205                            <list>
5206                                <t>FIND DB_INSTRUMENT_DIRECTORIES [NON_RECURSIVE] &lt;dir&gt; &lt;criteria-list&gt;</t>
5207                            </list>
5208                        </t>
5209                        <t>Where &lt;dir&gt; should be replaced by the absolute path
5210                        name of the directory to search in. If NON_RECURSIVE is specified, the
5211                        directories located in subdirectories of the specified directory will not
5212                        be searched. &lt;criteria-list&gt; is a list of search criterias
5213                        in form of "key1=val1 key2=val2 ...". The following criterias are
5214                        allowed:</t>
5215                        <t>
5216                          <t>NAME='&lt;search-string&gt;'
5217                              <list>
5218                                  <t>Restricts the search to directories, which names
5219                                  satisfy the supplied search string (encapsulated into apostrophes,
5220                                  supporting escape sequences as described in chapter
5221                                  "<xref target="character_set">Character Set and Escape Sequences</xref>").</t>
5222                              </list>
5223                          </t>
5224    
5225                          <t>CREATED='[&lt;date-after&gt;]..[&lt;date-before&gt;]'
5226                              <list>
5227                                  <t>Restricts the search to directories, which creation
5228                                  date satisfies the specified period, where &lt;date-after&gt;
5229                                  and &lt;date-before&gt; are in "YYYY-MM-DD HH:MM:SS" format.
5230                                  If &lt;date-after&gt; is omitted the search is restricted to
5231                                  directories created before &lt;date-before&gt;. If
5232                                  &lt;date-before&gt; is omitted, the search is restricted
5233                                  to directories created after &lt;date-after&gt;.</t>
5234                              </list>
5235                          </t>
5236    
5237                          <t>MODIFIED='[&lt;date-after&gt;]..[&lt;date-before&gt;]'
5238                              <list>
5239                                  <t>Restricts the search to directories, which
5240                                  date of last modification satisfies the specified period, where
5241                                  &lt;date-after&gt; and &lt;date-before&gt; are in "YYYY-MM-DD HH:MM:SS"
5242                                  format. If &lt;date-after&gt; is omitted the search is restricted to
5243                                  directories, which are last modified before &lt;date-before&gt;. If
5244                                  &lt;date-before&gt; is omitted, the search is restricted to directories,
5245                                  which are last modified after &lt;date-after&gt;.</t>
5246                              </list>
5247                          </t>
5248    
5249                          <t>DESCRIPTION='&lt;search-string&gt;'
5250                              <list>
5251                                  <t>Restricts the search to directories with description
5252                                  that satisfies the supplied search string
5253                                  (encapsulated into apostrophes, supporting escape
5254                                  sequences as described in chapter
5255                                  "<xref target="character_set">Character Set and Escape Sequences</xref>").</t>
5256                              </list>
5257                          </t>
5258                        </t>
5259    
5260                        <t>Where &lt;search-string&gt; is either a regular expression, or a
5261                        word list separated with spaces for OR search and with '+' for AND search.</t>
5262    
5263                        <t>Possible Answers:</t>
5264                        <t>
5265                            <list>
5266                                <t>A comma separated list with the absolute path names (encapsulated into
5267                                apostrophes) of all directories in the specified directory that satisfy
5268                                the supplied search criterias.</t>
5269                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
5270                                    <list>
5271                                        <t>if the given directory does not exist.</t>
5272                                    </list>
5273                                </t>
5274                            </list>
5275                        </t>
5276                        <t>Example:</t>
5277                        <t>
5278                            <list>
5279                                <t>C: "FIND DB_INSTRUMENT_DIRECTORIES '/' NAME='Piano'"</t>
5280                                <t>S: "'/Piano Collection'"</t>
5281                            </list>
5282                        </t>
5283                        <t>
5284                            <list>
5285                                <t>C: "FIND DB_INSTRUMENT_DIRECTORIES '/' CREATED='..2007-04-01 09:30:13'"</t>
5286                                <t>S: "'/Piano Collection','/Percussions'"</t>
5287                            </list>
5288                        </t>
5289                    </section>
5290    
5291                    <section title="Adding instruments to the instruments database" anchor="ADD DB_INSTRUMENTS">
5292                        <t>The front-end can add one or more instruments
5293                        to the instruments database by sending the following command:</t>
5294                        <t>
5295                            <list>
5296                                <t>ADD DB_INSTRUMENTS [NON_MODAL] [&lt;mode&gt;] &lt;db_dir&gt; &lt;file_path&gt; [&lt;instr_index&gt;]</t>
5297                            </list>
5298                        </t>
5299                        <t>Where &lt;db_dir&gt; is the absolute path name of a directory
5300                        (encapsulated into apostrophes) in the instruments database in which
5301                        only the new instruments (that are not already in the database) will
5302                        be added, &lt;file_path&gt; is the absolute path name of a file or
5303                        directory in the file system (encapsulated into apostrophes). In case
5304                        an instrument file is supplied, only the instruments in the specified
5305                        file will be added to the instruments database. If the optional
5306                        &lt;instr_index&gt; (the index of the instrument within the given file)
5307                        is supplied too, then only the specified instrument will be added.
5308                        In case a directory is supplied, the instruments in that directory
5309                        will be added. The OPTIONAL &lt;mode&gt; argument is only applied
5310                        when a directory is provided as &lt;file_path&gt; and specifies how the
5311                        scanning will be done and has exactly the following possibilities:</t>
5312                        <t>
5313                            <list>
5314                                <t>"RECURSIVE" -
5315                                    <list>
5316                                        <t>All instruments will be processed, including those
5317                                        in the subdirectories, and the respective subdirectory
5318                                        tree structure will be recreated in the instruments
5319                                        database</t>
5320                                    </list>
5321                                </t>
5322                                <t>"NON_RECURSIVE" -
5323                                    <list>
5324                                        <t>Only the instruments in the specified directory
5325                                        will be added, the instruments in the subdirectories
5326                                        will not be processed.</t>
5327                                    </list>
5328                                </t>
5329                                <t>"FLAT" -
5330                                    <list>
5331                                        <t>All instruments will be processed, including those
5332                                        in the subdirectories, but the respective subdirectory
5333                                        structure will not be recreated in the instruments
5334                                        database. All instruments will be added directly in
5335                                        the specified database directory.</t>
5336                                    </list>
5337                                </t>
5338                            </list>
5339                        </t>
5340    
5341                     <t>The difference between regular and NON_MODAL versions of the command
5342                        is that the regular command returns when the scanning is finished
5343                        while NON_MODAL version returns immediately and a background process is launched.
5344                        The <xref target="GET DB_INSTRUMENTS_JOB INFO">GET DB_INSTRUMENTS_JOB INFO</xref>
5345                        command can be used to monitor the scanning progress.</t>
5346    
5347                        <t>Possible Answers:</t>
5348                        <t>
5349                            <list>
5350                                <t>"OK" -
5351                                    <list>
5352                                        <t>on success when NON_MODAL is not supplied</t>
5353                                    </list>
5354                                </t>
5355                                <t>"OK[&lt;job-id&gt;]" -
5356                                    <list>
5357                                        <t>on success when NON_MODAL is supplied, where &lt;job-id&gt;
5358                                        is a numerical ID used to obtain status information about the job progress.
5359                                        See <xref target="GET DB_INSTRUMENTS_JOB INFO">GET DB_INSTRUMENTS_JOB INFO</xref>
5360                                        </t>
5361                                    </list>
5362                                </t>
5363                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
5364                                    <list>
5365                                        <t>if an invalid path is specified.</t>
5366                                    </list>
5367                                </t>
5368                            </list>
5369                        </t>
5370    
5371                        <t>Examples:</t>
5372                        <t>
5373                            <list>
5374                                <t>C: "ADD DB_INSTRUMENTS '/Piano Collection' '/home/me/gigs/PMI Bosendorfer 290.gig' 0"</t>
5375                                <t>S: "OK"</t>
5376                            </list>
5377                        </t>
5378                    </section>
5379    
5380                    <section title="Removing an instrument" anchor="REMOVE DB_INSTRUMENT">
5381                        <t>The front-end can remove a particular instrument
5382                        from the instruments database by sending the following command:</t>
5383                        <t>
5384                            <list>
5385                                <t>REMOVE DB_INSTRUMENT &lt;instr_path&gt;</t>
5386                            </list>
5387                        </t>
5388                        <t>Where &lt;instr_path&gt; is the absolute path name
5389                        (in the instruments database) of the instrument to remove.</t>
5390    
5391                        <t>Possible Answers:</t>
5392                        <t>
5393                            <list>
5394                                <t>"OK" -
5395                                    <list>
5396                                        <t>if the instrument is removed successfully</t>
5397                                    </list>
5398                                </t>
5399                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
5400                                    <list>
5401                                        <t>if the given path does not exist or
5402                                        is a directory.</t>
5403                                    </list>
5404                                </t>
5405                            </list>
5406                        </t>
5407    
5408                        <t>Examples:</t>
5409                        <t>
5410                            <list>
5411                                <t>C: "REMOVE DB_INSTRUMENT '/Piano Collection/Bosendorfer 290'"</t>
5412                                <t>S: "OK"</t>
5413                            </list>
5414                        </t>
5415                    </section>
5416    
5417                    <section title="Getting amount of instruments" anchor="GET DB_INSTRUMENTS">
5418                        <t>The front-end can retrieve the current amount of
5419                        instruments in a specific directory by sending the following command:</t>
5420                        <t>
5421                            <list>
5422                                <t>GET DB_INSTRUMENTS [RECURSIVE] &lt;dir&gt;</t>
5423                            </list>
5424                        </t>
5425                        <t>Where &lt;dir&gt; should be replaced by the absolute path name
5426                        of the directory. If RECURSIVE is specified, the number of all
5427                        instruments, including those located in subdirectories of the
5428                        specified directory, will be returned.</t>
5429    
5430                        <t>Possible Answers:</t>
5431                        <t>
5432                            <list>
5433                                <t>The current number of instruments
5434                                in the specified directory.</t>
5435                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
5436                                    <list>
5437                                        <t>if the given directory does not exist.</t>
5438                                    </list>
5439                                </t>
5440                            </list>
5441                        </t>
5442    
5443                        <t>Example:</t>
5444                        <t>
5445                            <list>
5446                                <t>C: "GET DB_INSTRUMENTS '/Piano Collection'"</t>
5447                                <t>S: "2"</t>
5448                            </list>
5449                        </t>
5450                    </section>
5451    
5452                    <section title="Listing all instruments in specific directory" anchor="LIST DB_INSTRUMENTS">
5453                        <t>The front-end can retrieve the current list of instruments
5454                        in specific directory by sending the following command:</t>
5455                        <t>
5456                            <list>
5457                                <t>LIST DB_INSTRUMENTS [RECURSIVE] &lt;dir&gt;</t>
5458                            </list>
5459                        </t>
5460                        <t>Where &lt;dir&gt; should be replaced by the absolute path
5461                        name of the directory. If RECURSIVE is specified, the absolute path
5462                        names of all instruments, including those located in subdirectories
5463                        of the specified directory, will be returned.</t>
5464    
5465                        <t>Possible Answers:</t>
5466                        <t>
5467                            <list>
5468                                <t>A comma separated list of all instruments
5469                                (encapsulated into apostrophes) in the specified directory.</t>
5470                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
5471                                    <list>
5472                                        <t>if the given directory does not exist.</t>
5473                                    </list>
5474                                </t>
5475                            </list>
5476                        </t>
5477                        <t>Example:</t>
5478                        <t>
5479                            <list>
5480                                <t>C: "LIST DB_INSTRUMENTS '/Piano Collection'"</t>
5481                                <t>S: "'Bosendorfer 290','Steinway D'"</t>
5482                            </list>
5483                        </t>
5484                        <t>
5485                            <list>
5486                                <t>C: "LIST DB_INSTRUMENTS RECURSIVE '/Piano Collection'"</t>
5487                                <t>S: "'/Piano Collection/Bosendorfer 290','/Piano Collection/Steinway D','/Piano Collection/Lite/Free Piano'"</t>
5488                            </list>
5489                        </t>
5490                    </section>
5491    
5492                    <section title="Getting instrument information" anchor="GET DB_INSTRUMENT INFO">
5493                        <t>The front-end can ask for the current settings of an
5494                        instrument by sending the following command:</t>
5495                        <t>
5496                            <list>
5497                                <t>GET DB_INSTRUMENT INFO &lt;instr_path&gt;</t>
5498                            </list>
5499                        </t>
5500                        <t>Where &lt;instr_path&gt; should be replaced by the absolute path
5501                        name of the instrument the front-end is interested in.</t>
5502    
5503                        <t>Possible Answers:</t>
5504                        <t>
5505                            <list>
5506                                <t>LinuxSampler will answer by sending a &lt;CRLF&gt; separated list.
5507                                Each answer line begins with the settings category name
5508                                followed by a colon and then a space character &lt;SP&gt; and finally
5509                                the info character string to that setting category. At the
5510                                moment the following categories are defined:</t>
5511    
5512                                <t>
5513                                    <list>
5514                                        <t>INSTRUMENT_FILE -
5515                                            <list>
5516                                                <t>File name of the instrument.
5517                                                Note that the character string may contain
5518                                                <xref target="character_set">escape sequences</xref>.</t>
5519                                            </list>
5520                                        </t>
5521                                        <t>INSTRUMENT_NR -
5522                                            <list>
5523                                                <t>Index of the instrument within the file.</t>
5524                                            </list>
5525                                        </t>
5526                                        <t>FORMAT_FAMILY -
5527                                            <list>
5528                                                <t>The format family of the instrument.</t>
5529                                            </list>
5530                                        </t>
5531                                        <t>FORMAT_VERSION -
5532                                            <list>
5533                                                <t>The format version of the instrument.</t>
5534                                            </list>
5535                                        </t>
5536                                        <t>SIZE -
5537                                            <list>
5538                                                <t>The size of the instrument in bytes.</t>
5539                                            </list>
5540                                        </t>
5541                                        <t>CREATED -
5542                                            <list>
5543                                                <t>The date and time when the instrument is added
5544                                                in the instruments database, represented in
5545                                               "YYYY-MM-DD HH:MM:SS" format</t>
5546                                            </list>
5547                                        </t>
5548                                        <t>MODIFIED -
5549                                            <list>
5550                                                <t>The date and time of the last modification of the
5551                                                instrument's database settings, represented in
5552                                                "YYYY-MM-DD HH:MM:SS" format</t>
5553                                            </list>
5554                                        </t>
5555                                        <t>DESCRIPTION -
5556                                            <list>
5557                                                <t>A brief description of the instrument.
5558                                                Note that the character string may contain
5559                                                <xref target="character_set">escape sequences</xref>.</t>
5560                                            </list>
5561                                        </t>
5562                                        <t>IS_DRUM -
5563                                            <list>
5564                                                <t>either true or false, determines whether the
5565                                                instrument is a drumkit or a chromatic instrument</t>
5566                                            </list>
5567                                        </t>
5568                                        <t>PRODUCT -
5569                                            <list>
5570                                                <t>The product title of the instrument.
5571                                                Note that the character string may contain
5572                                                <xref target="character_set">escape sequences</xref>.</t>
5573                                            </list>
5574                                        </t>
5575                                        <t>ARTISTS -
5576                                            <list>
5577                                                <t>Lists the artist names.
5578                                                Note that the character string may contain
5579                                                <xref target="character_set">escape sequences</xref>.</t>
5580                                            </list>
5581                                        </t>
5582                                        <t>KEYWORDS -
5583                                            <list>
5584                                                <t>Provides a list of keywords that refer to the instrument.
5585                                                Keywords are separated with semicolon and blank.
5586                                                Note that the character string may contain
5587                                                <xref target="character_set">escape sequences</xref>.</t>
5588                                            </list>
5589                                        </t>
5590                                    </list>
5591                                </t>
5592                            </list>
5593                        </t>
5594                        <t>The mentioned fields above don't have to be in particular order.</t>
5595    
5596                        <t>Example:</t>
5597                        <t>
5598                            <list>
5599                                <t>C: "GET DB_INSTRUMENT INFO '/Piano Collection/Bosendorfer 290'"</t>
5600                                <t>S: "INSTRUMENT_FILE: /home/me/gigs/Bosendorfer 290.gig"</t>
5601                                <t>&nbsp;&nbsp;&nbsp;"INSTRUMENT_NR: 0"</t>
5602                                <t>&nbsp;&nbsp;&nbsp;"FORMAT_FAMILY: GIG"</t>
5603                                <t>&nbsp;&nbsp;&nbsp;"FORMAT_VERSION: 2"</t>
5604                                <t>&nbsp;&nbsp;&nbsp;"SIZE: 2050871870"</t>
5605                                <t>&nbsp;&nbsp;&nbsp;"CREATED: 2007-02-05 10:23:12"</t>
5606                                <t>&nbsp;&nbsp;&nbsp;"MODIFIED: 2007-04-07 12:50:21"</t>
5607                                <t>&nbsp;&nbsp;&nbsp;"DESCRIPTION: "</t>
5608                                <t>&nbsp;&nbsp;&nbsp;"IS_DRUM: false"</t>
5609                                <t>&nbsp;&nbsp;&nbsp;"PRODUCT: GRANDIOSO Bosendorfer 290"</t>
5610                                <t>&nbsp;&nbsp;&nbsp;"ARTISTS: Post Musical Instruments"</t>
5611                                <t>&nbsp;&nbsp;&nbsp;"KEYWORDS: Bosendorfer"</t>
5612                                <t>&nbsp;&nbsp;&nbsp;"."</t>
5613                            </list>
5614                        </t>
5615                    </section>
5616    
5617                    <section title="Renaming an instrument" anchor="SET DB_INSTRUMENT NAME">
5618                        <t>The front-end can alter the name of a specific
5619                        instrument by sending the following command:</t>
5620                        <t>
5621                            <list>
5622                                <t>SET DB_INSTRUMENT NAME &lt;instr&gt; &lt;name&gt;</t>
5623                            </list>
5624                        </t>
5625                        <t>Where &lt;instr&gt; is the absolute path name of the instrument and
5626                        &lt;name&gt; is the new name for that instrument.</t>
5627    
5628                        <t>Possible Answers:</t>
5629                        <t>
5630                            <list>
5631                                <t>"OK" -
5632                                    <list>
5633                                        <t>on success</t>
5634                                    </list>
5635                                </t>
5636                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
5637                                    <list>
5638                                        <t>in case the given instrument does not exists,
5639                                        or if an instrument with name equal to the new
5640                                        name already exists.</t>
5641                                    </list>
5642                                </t>
5643                            </list>
5644                        </t>
5645    
5646                        <t>Example:</t>
5647                        <t>
5648                            <list>
5649                                <t>C: "SET DB_INSTRUMENT NAME '/Piano Collection/Bosendorfer' 'Bosendorfer 290'"</t>
5650                                <t>S: "OK"</t>
5651                            </list>
5652                        </t>
5653                    </section>
5654    
5655                    <section title="Moving an instrument" anchor="MOVE DB_INSTRUMENT">
5656                        <t>The front-end can move a specific instrument to another directory by
5657                        sending the following command:</t>
5658                        <t>
5659                            <list>
5660                                <t>MOVE DB_INSTRUMENT &lt;instr&gt; &lt;dst&gt;</t>
5661                            </list>
5662                        </t>
5663                        <t>Where &lt;instr&gt; is the absolute path name of the instrument
5664                        to move and &lt;dst&gt; is the directory where the instrument will
5665                        be moved to.</t>
5666    
5667                        <t>Possible Answers:</t>
5668                        <t>
5669                            <list>
5670                                <t>"OK" -
5671                                    <list>
5672                                        <t>on success</t>
5673                                    </list>
5674                                </t>
5675                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
5676                                    <list>
5677                                        <t>in case the given instrument does not exists,
5678                                        or if an instrument with name equal to the name of the
5679                                        specified instrument already exists in the destination
5680                                        directory.</t>
5681                                    </list>
5682                                </t>
5683                            </list>
5684                        </t>
5685    
5686                        <t>Example:</t>
5687                        <t>
5688                            <list>
5689                                <t>C: "MOVE DB_INSTRUMENT '/Piano Collection/Bosendorfer 290' '/Piano Collection/Acoustic'"</t>
5690                                <t>S: "OK"</t>
5691                            </list>
5692                        </t>
5693                    </section>
5694    
5695                    <section title="Copying instruments" anchor="COPY DB_INSTRUMENT">
5696                        <t>The front-end can copy a specific instrument to another directory by
5697                        sending the following command:</t>
5698                        <t>
5699                            <list>
5700                                <t>COPY DB_INSTRUMENT &lt;instr&gt; &lt;dst&gt;</t>
5701                            </list>
5702                        </t>
5703                        <t>Where &lt;instr&gt; is the absolute path name of the instrument
5704                        to copy and &lt;dst&gt; is the directory where the instrument will
5705                        be copied to.</t>
5706    
5707                        <t>Possible Answers:</t>
5708                        <t>
5709                            <list>
5710                                <t>"OK" -
5711                                    <list>
5712                                        <t>on success</t>
5713                                    </list>
5714                                </t>
5715                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
5716                                    <list>
5717                                        <t>in case the given instrument does not exists,
5718                                        or if an instrument with name equal to the name of the
5719                                        specified instrument already exists in the destination
5720                                        directory.</t>
5721                                    </list>
5722                                </t>
5723                            </list>
5724                        </t>
5725    
5726                        <t>Example:</t>
5727                        <t>
5728                            <list>
5729                                <t>C: "COPY DB_INSTRUMENT '/Piano Collection/Bosendorfer 290' '/Acoustic/Pianos/'"</t>
5730                                <t>S: "OK"</t>
5731                            </list>
5732                        </t>
5733                    </section>
5734    
5735                    <section title="Changing the description of instrument" anchor="SET DB_INSTRUMENT DESCRIPTION">
5736                        <t>The front-end can alter the description of a specific
5737                        instrument by sending the following command:</t>
5738                        <t>
5739                            <list>
5740                                <t>SET DB_INSTRUMENT DESCRIPTION &lt;instr&gt; &lt;desc&gt;</t>
5741                            </list>
5742                        </t>
5743                        <t>Where &lt;instr&gt; is the absolute path name of the instrument and
5744                        &lt;desc&gt; is the new description for the instrument
5745                        (encapsulated into apostrophes, supporting escape sequences as described in chapter
5746                        "<xref target="character_set">Character Set and Escape Sequences</xref>").</t>
5747    
5748                        <t>Possible Answers:</t>
5749                        <t>
5750                            <list>
5751                                <t>"OK" -
5752                                    <list>
5753                                        <t>on success</t>
5754                                    </list>
5755                                </t>
5756                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
5757                                    <list>
5758                                        <t>in case the given instrument does not exists.</t>
5759                                    </list>
5760                                </t>
5761                            </list>
5762                        </t>
5763    
5764                        <t>Example:</t>
5765                        <t>
5766                            <list>
5767                                <t>C: "SET DB_INSTRUMENT DESCRIPTION '/Piano Collection/Acoustic/Bosendorfer 290' 'No comment :)'"</t>
5768                                <t>S: "OK"</t>
5769                            </list>
5770                        </t>
5771                    </section>
5772    
5773                    <section title="Finding instruments" anchor="FIND DB_INSTRUMENTS">
5774                        <t>The front-end can search for instruments
5775                        in specific directory by sending the following command:</t>
5776                        <t>
5777                            <list>
5778                                <t>FIND DB_INSTRUMENTS [NON_RECURSIVE] &lt;dir&gt; &lt;criteria-list&gt;</t>
5779                            </list>
5780                        </t>
5781                        <t>Where &lt;dir&gt; should be replaced by the absolute path
5782                        name of the directory to search in. If NON_RECURSIVE is specified, the
5783                        directories located in subdirectories of the specified directory will not
5784                        be searched. &lt;criteria-list&gt; is a list of search criterias
5785                        in form of "key1=val1 key2=val2 ...". The following criterias are
5786                        allowed:</t>
5787                        <t>
5788                          <t>NAME='&lt;search-string&gt;'
5789                              <list>
5790                                  <t>Restricts the search to instruments, which names
5791                                  satisfy the supplied search string (encapsulated into apostrophes,
5792                                  supporting escape sequences as described in chapter
5793                                  "<xref target="character_set">Character Set and Escape Sequences</xref>").</t>
5794                              </list>
5795                          </t>
5796    
5797                          <t>SIZE=[&lt;min&gt;]..[&lt;max&gt;]
5798                              <list>
5799                                  <t>Restricts the search to instruments, which
5800                                  size is in the specified range. If &lt;min&gt; is omitted,
5801                                  the search results are restricted to instruments with size less then
5802                                  or equal to &lt;max&gt;. If &lt;max&gt; is omitted, the
5803                                  search is restricted to instruments with size greater then
5804                                  or equal to &lt;min&gt;.</t>
5805                              </list>
5806                          </t>
5807    
5808                          <t>CREATED='[&lt;date-after&gt;]..[&lt;date-before&gt;]'
5809                              <list>
5810                                  <t>Restricts the search to instruments, which creation
5811                                  date satisfies the specified period, where &lt;date-after&gt;
5812                                  and &lt;date-before&gt; are in "YYYY-MM-DD HH:MM:SS" format.
5813                                  If &lt;date-after&gt; is omitted the search is restricted to
5814                                  instruments created before &lt;date-before&gt;. If
5815                                  &lt;date-before&gt; is omitted, the search is restricted
5816                                  to instruments created after &lt;date-after&gt;.</t>
5817                              </list>
5818                          </t>
5819    
5820                          <t>MODIFIED='[&lt;date-after&gt;]..[&lt;date-before&gt;]'
5821                              <list>
5822                                  <t>Restricts the search to instruments, which
5823                                  date of last modification satisfies the specified period, where
5824                                  &lt;date-after&gt; and &lt;date-before&gt; are in "YYYY-MM-DD HH:MM:SS"
5825                                  format. If &lt;date-after&gt; is omitted the search is restricted to
5826                                  instruments, which are last modified before &lt;date-before&gt;. If
5827                                  &lt;date-before&gt; is omitted, the search is restricted to instruments,
5828                                  which are last modified after &lt;date-after&gt;.</t>
5829                              </list>
5830                          </t>
5831    
5832                          <t>DESCRIPTION='&lt;search-string&gt;'
5833                              <list>
5834                                  <t>Restricts the search to instruments with description
5835                                  that satisfies the supplied search string (encapsulated into apostrophes,
5836                                  supporting escape sequences as described in chapter
5837                                  "<xref target="character_set">Character Set and Escape Sequences</xref>").</t>
5838                              </list>
5839                          </t>
5840    
5841                          <t>PRODUCT='&lt;search-string&gt;'
5842                              <list>
5843                                  <t>Restricts the search to instruments with product info
5844                                  that satisfies the supplied search string (encapsulated into apostrophes,
5845                                  supporting escape sequences as described in chapter
5846                                  "<xref target="character_set">Character Set and Escape Sequences</xref>").</t>
5847                              </list>
5848                          </t>
5849    
5850                          <t>ARTISTS='&lt;search-string&gt;'
5851                              <list>
5852                                  <t>Restricts the search to instruments with artists info
5853                                  that satisfies the supplied search string (encapsulated into apostrophes,
5854                                  supporting escape sequences as described in chapter
5855                                  "<xref target="character_set">Character Set and Escape Sequences</xref>").</t>
5856                              </list>
5857                          </t>
5858    
5859                          <t>KEYWORDS='&lt;search-string&gt;'
5860                              <list>
5861                                  <t>Restricts the search to instruments with keyword list
5862                                  that satisfies the supplied search string (encapsulated into apostrophes,
5863                                  supporting escape sequences as described in chapter
5864                                  "<xref target="character_set">Character Set and Escape Sequences</xref>").</t>
5865                              </list>
5866                          </t>
5867    
5868                          <t>IS_DRUM=true | false
5869                              <list>
5870                                  <t>Either true or false. Restricts the search to
5871                                  drum kits or chromatic instruments.</t>
5872                              </list>
5873                          </t>
5874    
5875                          <t>FORMAT_FAMILIES='&lt;format-list&gt;'
5876                              <list>
5877                                  <t>Restricts the search to instruments of the supplied format families,
5878                                  where &lt;format-list&gt; is a comma separated list of format families.</t>
5879                              </list>
5880                          </t>
5881                        </t>
5882    
5883                        <t>Where &lt;search-string&gt; is either a regular expression, or a
5884                        word list separated with spaces for OR search and with '+' for AND search.</t>
5885    
5886                        <t>Possible Answers:</t>
5887                        <t>
5888                            <list>
5889                                <t>A comma separated list with the absolute path names (encapsulated into
5890                                apostrophes) of all instruments in the specified directory that satisfy
5891                                the supplied search criterias.</t>
5892                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
5893                                    <list>
5894                                        <t>if the given directory does not exist.</t>
5895                                    </list>
5896                                </t>
5897                            </list>
5898                        </t>
5899                        <t>Example:</t>
5900                        <t>
5901                            <list>
5902                                <t>C: "FIND DB_INSTRUMENTS '/Piano Collection' NAME='bosendorfer+290'"</t>
5903                                <t>S: "'/Piano Collection/Bosendorfer 290'"</t>
5904                            </list>
5905                        </t>
5906                        <t>
5907                            <list>
5908                                <t>C: "FIND DB_INSTRUMENTS '/Piano Collection' CREATED='2007-04-01 09:30:13..'"</t>
5909                                <t>S: "'/Piano Collection/Bosendorfer 290','/Piano Collection/Steinway D'"</t>
5910                            </list>
5911                        </t>
5912                    </section>
5913    
5914                    <section title="Getting job status information" anchor="GET DB_INSTRUMENTS_JOB INFO">
5915                        <t>The front-end can ask for the current status of a
5916                        particular database instruments job by sending the following command:</t>
5917                        <t>
5918                            <list>
5919                                <t>GET DB_INSTRUMENTS_JOB INFO &lt;job-id&gt;</t>
5920                            </list>
5921                        </t>
5922                        <t>Where &lt;job-id&gt; should be replaced by the numerical ID
5923                        of the job the front-end is interested in.</t>
5924    
5925                        <t>Possible Answers:</t>
5926                        <t>
5927                            <list>
5928                                <t>LinuxSampler will answer by sending a &lt;CRLF&gt; separated list.
5929                                Each answer line begins with the settings category name
5930                                followed by a colon and then a space character &lt;SP&gt; and finally
5931                                the info character string to that setting category. At the
5932                                moment the following categories are defined:</t>
5933    
5934                                <t>
5935                                    <list>
5936                                        <t>FILES_TOTAL -
5937                                            <list>
5938                                                <t>The total number of files scheduled for scanning</t>
5939                                            </list>
5940                                        </t>
5941                                        <t>FILES_SCANNED -
5942                                            <list>
5943                                                <t>The current number of scanned files</t>
5944                                            </list>
5945                                        </t>
5946                                        <t>SCANNING -
5947                                            <list>
5948                                                <t>The absolute path name of the file which is currently
5949                                                being scanned</t>
5950                                            </list>
5951                                        </t>
5952                                        <t>STATUS -
5953                                            <list>
5954                                                <t>An integer value between 0 and 100 indicating the
5955                                                scanning progress percentage of the file which is
5956                                                currently being scanned</t>
5957                                            </list>
5958                                        </t>
5959                                    </list>
5960                                </t>
5961                            </list>
5962                        </t>
5963                        <t>The mentioned fields above don't have to be in particular order.</t>
5964    
5965                        <t>Example:</t>
5966                        <t>
5967                            <list>
5968                                <t>C: "GET DB_INSTRUMENTS_JOB INFO 2"</t>
5969                                <t>S: "FILES_TOTAL: 12"</t>
5970                                <t>&nbsp;&nbsp;&nbsp;"FILES_SCANNED: 7"</t>
5971                                <t>&nbsp;&nbsp;&nbsp;"SCANNING: /home/me/gigs/Bosendorfer 290.gig"</t>
5972                                <t>&nbsp;&nbsp;&nbsp;"STATUS: 42"</t>
5973                                <t>&nbsp;&nbsp;&nbsp;"."</t>
5974                            </list>
5975                        </t>
5976                    </section>
5977    
5978                    <section title="Formatting the instruments database" anchor="FORMAT INSTRUMENTS_DB">
5979                        <t>The front-end can remove all instruments and directories and re-create
5980                        the instruments database structure (e.g., in case of a database corruption)
5981                        by sending the following command:</t>
5982                        <t>
5983                            <list>
5984                                <t>FORMAT INSTRUMENTS_DB</t>
5985                            </list>
5986                        </t>
5987    
5988                        <t>Possible Answers:</t>
5989                        <t>
5990                            <list>
5991                                <t>"OK" -
5992                                    <list>
5993                                        <t>on success</t>
5994                                    </list>
5995                                </t>
5996                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
5997                                    <list>
5998                                        <t>If the formatting of the instruments database
5999                                        failed.</t>
6000                                    </list>
6001                                </t>
6002                            </list>
6003                        </t>
6004                    </section>
6005    
6006                </section>
6007    
6008    
6009    
6010                <section title="Editing Instruments" anchor="editing_instruments">
6011                    <t>The sampler allows to edit instruments while playing with the
6012                    sampler by spawning an external (3rd party) instrument editor
6013                    application for a given instrument. The 3rd party instrument
6014                    editor applications have to place a respective plugin DLL file
6015                    into the sampler's plugins directory. The sampler will
6016                    automatically try to load all plugin DLLs in that directory on
6017                    startup and only on startup!</t>
6018                    <t>At the moment there is only one command for this feature set,
6019                    but this will most probably change in future.</t>
6020    
6021                    <section title="Opening an appropriate instrument editor application" anchor="EDIT INSTRUMENT">
6022                        <t>The front-end can request to open an appropriate instrument
6023                        editor application by sending the following command:</t>
6024                        <t>
6025                            <list>
6026                                <t>EDIT CHANNEL INSTRUMENT &lt;sampler-channel&gt;</t>
6027                            </list>
6028                        </t>
6029                        <t>Where &lt;sampler-channel&gt; should be replaced by the
6030                        number of the sampler channel as given by the
6031                        <xref target="ADD CHANNEL">"ADD CHANNEL"</xref>
6032                        or <xref target="LIST CHANNELS">"LIST CHANNELS"</xref>
6033                        command.</t>
6034    
6035                        <t>The sampler will try to ask all registered instrument
6036                        editors (or to be more specific: their sampler plugins)
6037                        whether they are capable to handle the instrument on the
6038                        given sampler channel. The sampler will simply use the first
6039                        instrument editor application which replied with a positive
6040                        answer and spawn that instrument editor application within
6041                        the sampler's process and provide that application access
6042                        to the instrument's data structures, so both applications
6043                        can share and access the same instruments data at the same
6044                        time, thus allowing to immediately hear changes with the
6045                        sampler made by the instrument editor.</t>
6046    
6047                        <t>Note: consequently instrument editors are always spawned
6048                        locally on the same machine where the sampler is running
6049                        on!</t>
6050    
6051                        <t>Possible Answers:</t>
6052                        <t>
6053                            <list>
6054                                <t>"OK" -
6055                                    <list>
6056                                        <t>when an appropriate instrument editor was
6057                                        launched</t>
6058                                    </list>
6059                                </t>
6060                                <t>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
6061                                    <list>
6062                                        <t>when an appropriate instrument editor was
6063                                        launched, but there are noteworthy issues</t>
6064                                    </list>
6065                                </t>
6066                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
6067                                    <list>
6068                                        <t>when an appropriate instrument editor
6069                                        could not be launched</t>
6070                                    </list>
6071                                </t>
6072                            </list>
6073                        </t>
6074    
6075                        <t>Examples:</t>
6076                        <t>
6077                            <list>
6078                                <t>C: "EDIT CHANNEL INSTRUMENT 0"</t>
6079                                <t>S: "OK"</t>
6080                            </list>
6081                        </t>
6082                    </section>
6083                </section>
6084    
6085                <section title="Managing Files" anchor="file_management">
6086                    <t>You can query detailed informations about files located
6087                    at the same system where the sampler instance is running on.
6088                    Using this command set allows to retrieve file informations
6089                    even remotely from another machine.</t>
6090    
6091                    <section title="Retrieving amount of instruments of a file" anchor="GET FILE INSTRUMENTS">
6092                        <t>The front-end can retrieve the amount of instruments
6093                        within a given instrument file by sending the
6094                        following command:</t>
6095                        <t>
6096                            <list>
6097                                <t>GET FILE INSTRUMENTS &lt;filename&gt;</t>
6098                            </list>
6099                        </t>
6100                        <t>Where &lt;filename&gt; is the name of the instrument
6101                        file (encapsulated into apostrophes, supporting escape
6102                        sequences as described in chapter
6103                        "<xref target="character_set">Character Set and Escape
6104                            Sequences</xref>").</t>
6105    
6106                        <t>The sampler will try to ask all sampler engines,
6107                        whether they support the given file and ask the first
6108                        engine with a positive answer for the amount of
6109                        instruments.</t>
6110    
6111                        <t>Possible Answers:</t>
6112                        <t>
6113                            <list>
6114                                <t>On success, the sampler will answer by
6115                                   returning the amount of instruments.
6116                                </t>
6117                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
6118                                    <list>
6119                                        <t>if the file could not be handled</t>
6120                                    </list>
6121                                </t>
6122                            </list>
6123                        </t>
6124    
6125                        <t>Examples:</t>
6126                        <t>
6127                            <list>
6128                                <t>C: "GET FILE INSTRUMENTS 'D:/Sounds/Foo.gig'"</t>
6129                                <t>S: "10"</t>
6130                            </list>
6131                        </t>
6132                    </section>
6133    
6134                    <section title="Retrieving all instruments of a file" anchor="LIST FILE INSTRUMENTS">
6135                        <t>The front-end can retrieve a list of all instruments
6136                        within a given instrument file by sending the
6137                        following command:</t>
6138                        <t>
6139                            <list>
6140                                <t>LIST FILE INSTRUMENTS &lt;filename&gt;</t>
6141                            </list>
6142                        </t>
6143                        <t>Where &lt;filename&gt; is the name of the instrument
6144                        file (encapsulated into apostrophes, supporting escape
6145                        sequences as described in chapter
6146                        "<xref target="character_set">Character Set and Escape
6147                            Sequences</xref>").</t>
6148    
6149                        <t>The sampler will try to ask all sampler engines,
6150                        whether they support the given file and ask the first
6151                        engine with a positive answer for a list of IDs for the
6152                        instruments in the given file.</t>
6153    
6154                        <t>Possible Answers:</t>
6155                        <t>
6156                            <list>
6157                                <t>On success, the sampler will answer by
6158                                   returning a comma separated list of
6159                                   instrument IDs.
6160                                </t>
6161                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
6162                                    <list>
6163                                        <t>if the file could not be handled</t>
6164                                    </list>
6165                                </t>
6166                            </list>
6167                        </t>
6168    
6169                        <t>Examples:</t>
6170                        <t>
6171                            <list>
6172                                <t>C: "LIST FILE INSTRUMENTS 'D:/Sounds/Foo.gig'"</t>
6173                                <t>S: "0,1,2,3,4,5,6,7,8,9"</t>
6174                            </list>
6175                        </t>
6176                    </section>
6177    
6178                    <section title="Retrieving informations about one instrument in a file" anchor="GET FILE INSTRUMENT INFO">
6179                        <t>The front-end can retrieve detailed informations
6180                        about a specific instrument within a given instrument
6181                        file by sending the following command:</t>
6182                        <t>
6183                            <list>
6184                                <t>GET FILE INSTRUMENT INFO &lt;filename&gt;
6185                                &lt;instr-id&gt;</t>
6186                            </list>
6187                        </t>
6188                        <t>Where &lt;filename&gt; is the name of the instrument
6189                        file (encapsulated into apostrophes, supporting escape
6190                        sequences as described in chapter
6191                        "<xref target="character_set">Character Set and Escape
6192                            Sequences</xref>") and &lt;instr-id&gt; is the numeric
6193                        instrument ID as returned by the
6194                        <xref target="LIST FILE INSTRUMENTS">
6195                        "LIST FILE INSTRUMENTS"</xref> command.</t>
6196    
6197                        <t>The sampler will try to ask all sampler engines,
6198                        whether they support the given file and ask the first
6199                        engine with a positive answer for informations about the
6200                        specific instrument in the given file.</t>
6201    
6202                        <t>Possible Answers:</t>
6203                        <t>
6204                            <list>
6205                                <t>LinuxSampler will answer by sending a &lt;CRLF&gt; separated list.
6206                                Each answer line begins with the settings category name
6207                                followed by a colon and then a space character &lt;SP&gt; and finally
6208                                the info character string to that setting category. At the
6209                                moment the following categories are defined:</t>
6210    
6211                                <t>
6212                                    <list>
6213                                        <t>NAME -
6214                                            <list>
6215                                                <t>name of the instrument as
6216                                                stored in the instrument file</t>
6217                                            </list>
6218                                        </t>
6219                                        <t>FORMAT_FAMILY -
6220                                            <list>
6221                                                <t>name of the sampler format
6222                                                of the given instrument</t>
6223                                            </list>
6224                                        </t>
6225                                        <t>FORMAT_VERSION -
6226                                            <list>
6227                                                <t>version of the sampler format
6228                                                the instrumen is stored as</t>
6229                                            </list>
6230                                        </t>
6231                                        <t>PRODUCT -
6232                                            <list>
6233                                                <t>official product name of the
6234                                                instrument as stored in the file
6235                                                </t>
6236                                            </list>
6237                                        </t>
6238                                        <t>ARTISTS -
6239                                            <list>
6240                                                <t>artists / sample library
6241                                                vendor of the instrument</t>
6242                                            </list>
6243                                        </t>
6244                                    </list>
6245                                </t>
6246                            </list>
6247                        </t>
6248                        <t>The mentioned fields above don't have to be in particular order.</t>
6249    
6250                        <t>Example:</t>
6251                        <t>
6252                            <list>
6253                                <t>C: "GET FILE INSTRUMENT INFO 'D:/Sounds/Foo.gig' 0"</t>
6254                                <t>S: "NAME: Lunatic Loops"</t>
6255                                <t>&nbsp;&nbsp;&nbsp;"FORMAT_FAMILY: GIG"</t>
6256                                <t>&nbsp;&nbsp;&nbsp;"FORMAT_VERSION: 3"</t>
6257                                <t>&nbsp;&nbsp;&nbsp;"PRODUCT: The Backbone Bongo Beats"</t>
6258                                <t>&nbsp;&nbsp;&nbsp;"ARTISTS: Jimmy the Fish"</t>
6259                                <t>&nbsp;&nbsp;&nbsp;"."</t>
6260                            </list>
6261                        </t>
6262                    </section>
6263                </section>
6264            </section>
6265    
6266          <section title="Command Syntax" anchor="command_syntax">          <section title="Command Syntax" anchor="command_syntax">
6267              <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 4287  Schoenebeck'> Line 6335  Schoenebeck'>
6335                  </t>                  </t>
6336                  <t>/ UNSUBSCRIBE SP unsubscribe_event                  <t>/ UNSUBSCRIBE SP unsubscribe_event
6337                  </t>                  </t>
                 <t>/ SELECT SP text  
                 </t>  
6338                  <t>/ RESET SP reset_instruction                  <t>/ RESET SP reset_instruction
6339                  </t>                  </t>
6340                  <t>/ CLEAR SP clear_instruction                  <t>/ CLEAR SP clear_instruction
6341                  </t>                  </t>
6342                    <t>/ FIND SP find_instruction
6343                    </t>
6344                    <t>/ MOVE SP move_instruction
6345                    </t>
6346                    <t>/ COPY SP copy_instruction
6347                    </t>
6348                    <t>/ EDIT SP edit_instruction
6349                    </t>
6350                    <t>/ FORMAT SP format_instruction
6351                    </t>
6352                  <t>/ RESET                  <t>/ RESET
6353                  </t>                  </t>
6354                  <t>/ QUIT                  <t>/ QUIT
# Line 4303  Schoenebeck'> Line 6359  Schoenebeck'>
6359          <list>          <list>
6360                  <t>CHANNEL                  <t>CHANNEL
6361                  </t>                  </t>
6362                    <t>/ DB_INSTRUMENT_DIRECTORY SP db_path
6363                    </t>
6364                    <t>/ DB_INSTRUMENTS SP NON_MODAL SP scan_mode SP db_path SP filename
6365                    </t>
6366                    <t>/ DB_INSTRUMENTS SP scan_mode SP db_path SP filename
6367                    </t>
6368                    <t>/ DB_INSTRUMENTS SP NON_MODAL SP db_path SP filename
6369                    </t>
6370                    <t>/ DB_INSTRUMENTS SP NON_MODAL SP db_path SP filename SP instrument_index
6371                    </t>
6372                    <t>/ DB_INSTRUMENTS SP db_path SP filename
6373                    </t>
6374                    <t>/ DB_INSTRUMENTS SP db_path SP filename SP instrument_index
6375                    </t>
6376                  <t>/ MIDI_INSTRUMENT_MAP                  <t>/ MIDI_INSTRUMENT_MAP
6377                  </t>                  </t>
6378                  <t>/ MIDI_INSTRUMENT_MAP SP map_name                  <t>/ MIDI_INSTRUMENT_MAP SP map_name
# Line 4311  Schoenebeck'> Line 6381  Schoenebeck'>
6381  </t>  </t>
6382  <t>subscribe_event =  <t>subscribe_event =
6383          <list>          <list>
6384                  <t>CHANNEL_COUNT                  <t>AUDIO_OUTPUT_DEVICE_COUNT
6385                    </t>
6386                    <t>/ AUDIO_OUTPUT_DEVICE_INFO
6387                    </t>
6388                    <t>/ MIDI_INPUT_DEVICE_COUNT
6389                    </t>
6390                    <t>/ MIDI_INPUT_DEVICE_INFO
6391                    </t>
6392                    <t>/ CHANNEL_COUNT
6393                    </t>
6394                    <t>/ CHANNEL_MIDI
6395                  </t>                  </t>
6396                  <t>/ VOICE_COUNT                  <t>/ VOICE_COUNT
6397                  </t>                  </t>
# Line 4321  Schoenebeck'> Line 6401  Schoenebeck'>
6401                  </t>                  </t>
6402                  <t>/ CHANNEL_INFO                  <t>/ CHANNEL_INFO
6403                  </t>                  </t>
6404                    <t>/ FX_SEND_COUNT
6405                    </t>
6406                    <t>/ FX_SEND_INFO
6407                    </t>
6408                    <t>/ MIDI_INSTRUMENT_MAP_COUNT
6409                    </t>
6410                    <t>/ MIDI_INSTRUMENT_MAP_INFO
6411                    </t>
6412                    <t>/ MIDI_INSTRUMENT_COUNT
6413                    </t>
6414                    <t>/ MIDI_INSTRUMENT_INFO
6415                    </t>
6416                    <t>/ DB_INSTRUMENT_DIRECTORY_COUNT
6417                    </t>
6418                    <t>/ DB_INSTRUMENT_DIRECTORY_INFO
6419                    </t>
6420                    <t>/ DB_INSTRUMENT_COUNT
6421                    </t>
6422                    <t>/ DB_INSTRUMENT_INFO
6423                    </t>
6424                    <t>/ DB_INSTRUMENTS_JOB_INFO
6425                    </t>
6426                  <t>/ MISCELLANEOUS                  <t>/ MISCELLANEOUS
6427                  </t>                  </t>
6428                    <t>/ TOTAL_STREAM_COUNT
6429                    </t>
6430                  <t>/ TOTAL_VOICE_COUNT                  <t>/ TOTAL_VOICE_COUNT
6431                  </t>                  </t>
6432                    <t>/ GLOBAL_INFO
6433                    </t>
6434          </list>          </list>
6435  </t>  </t>
6436  <t>unsubscribe_event =  <t>unsubscribe_event =
6437          <list>          <list>
6438                  <t>CHANNEL_COUNT                  <t>AUDIO_OUTPUT_DEVICE_COUNT
6439                    </t>
6440                    <t>/ AUDIO_OUTPUT_DEVICE_INFO
6441                    </t>
6442                    <t>/ MIDI_INPUT_DEVICE_COUNT
6443                    </t>
6444                    <t>/ MIDI_INPUT_DEVICE_INFO
6445                    </t>
6446                    <t>/ CHANNEL_COUNT
6447                    </t>
6448                    <t>/ CHANNEL_MIDI
6449                  </t>                  </t>
6450                  <t>/ VOICE_COUNT                  <t>/ VOICE_COUNT
6451                  </t>                  </t>
# Line 4339  Schoenebeck'> Line 6455  Schoenebeck'>
6455                  </t>                  </t>
6456                  <t>/ CHANNEL_INFO                  <t>/ CHANNEL_INFO
6457                  </t>                  </t>
6458                    <t>/ FX_SEND_COUNT
6459                    </t>
6460                    <t>/ FX_SEND_INFO
6461                    </t>
6462                    <t>/ MIDI_INSTRUMENT_MAP_COUNT
6463                    </t>
6464                    <t>/ MIDI_INSTRUMENT_MAP_INFO
6465                    </t>
6466                    <t>/ MIDI_INSTRUMENT_COUNT
6467                    </t>
6468                    <t>/ MIDI_INSTRUMENT_INFO
6469                    </t>
6470                    <t>/ DB_INSTRUMENT_DIRECTORY_COUNT
6471                    </t>
6472                    <t>/ DB_INSTRUMENT_DIRECTORY_INFO
6473                    </t>
6474                    <t>/ DB_INSTRUMENT_COUNT
6475                    </t>
6476                    <t>/ DB_INSTRUMENT_INFO
6477                    </t>
6478                    <t>/ DB_INSTRUMENTS_JOB_INFO
6479                    </t>
6480                  <t>/ MISCELLANEOUS                  <t>/ MISCELLANEOUS
6481                  </t>                  </t>
6482                    <t>/ TOTAL_STREAM_COUNT
6483                    </t>
6484                  <t>/ TOTAL_VOICE_COUNT                  <t>/ TOTAL_VOICE_COUNT
6485                  </t>                  </t>
6486                    <t>/ GLOBAL_INFO
6487                    </t>
6488          </list>          </list>
6489  </t>  </t>
6490  <t>map_instruction =  <t>map_instruction =
6491          <list>          <list>
6492                  <t>MIDI_INSTRUMENT SP midi_map SP midi_bank SP midi_prog SP engine_name SP filename SP instrument_index SP volume_value                  <t>MIDI_INSTRUMENT SP modal_arg midi_map SP midi_bank SP midi_prog SP engine_name SP filename SP instrument_index SP volume_value
6493                  </t>                  </t>
6494                  <t>/ MIDI_INSTRUMENT SP midi_map SP midi_bank SP midi_prog SP engine_name SP filename SP instrument_index SP volume_value SP instr_load_mode                  <t>/ MIDI_INSTRUMENT SP modal_arg midi_map SP midi_bank SP midi_prog SP engine_name SP filename SP instrument_index SP volume_value SP instr_load_mode
6495                  </t>                  </t>
6496                  <t>/ MIDI_INSTRUMENT SP midi_map SP midi_bank SP midi_prog SP engine_name SP filename SP instrument_index SP volume_value SP entry_name                  <t>/ MIDI_INSTRUMENT SP modal_arg midi_map SP midi_bank SP midi_prog SP engine_name SP filename SP instrument_index SP volume_value SP entry_name
6497                  </t>                  </t>
6498                  <t>/ MIDI_INSTRUMENT SP midi_map SP midi_bank SP midi_prog SP engine_name SP filename SP instrument_index SP volume_value SP instr_load_mode SP entry_name                  <t>/ MIDI_INSTRUMENT SP modal_arg midi_map SP midi_bank SP midi_prog SP engine_name SP filename SP instrument_index SP volume_value SP instr_load_mode SP entry_name
6499                  </t>                  </t>
6500          </list>          </list>
6501  </t>  </t>
# Line 4371  Schoenebeck'> Line 6513  Schoenebeck'>
6513                  </t>                  </t>
6514                  <t>/ MIDI_INSTRUMENT_MAP SP ALL                  <t>/ MIDI_INSTRUMENT_MAP SP ALL
6515                  </t>                  </t>
6516                    <t>/ DB_INSTRUMENT_DIRECTORY SP FORCE SP db_path
6517                    </t>
6518                    <t>/ DB_INSTRUMENT_DIRECTORY SP db_path
6519                    </t>
6520                    <t>/ DB_INSTRUMENT SP db_path
6521                    </t>
6522          </list>          </list>
6523  </t>  </t>
6524  <t>get_instruction =  <t>get_instruction =
# Line 4423  Schoenebeck'> Line 6571  Schoenebeck'>
6571                  </t>                  </t>
6572                  <t>/ SERVER SP INFO                  <t>/ SERVER SP INFO
6573                  </t>                  </t>
6574                    <t>/ TOTAL_STREAM_COUNT
6575                    </t>
6576                  <t>/ TOTAL_VOICE_COUNT                  <t>/ TOTAL_VOICE_COUNT
6577                  </t>                  </t>
6578                  <t>/ TOTAL_VOICE_COUNT_MAX                  <t>/ TOTAL_VOICE_COUNT_MAX
# Line 4437  Schoenebeck'> Line 6587  Schoenebeck'>
6587                  </t>                  </t>
6588                  <t>/ MIDI_INSTRUMENT_MAP SP INFO SP midi_map                  <t>/ MIDI_INSTRUMENT_MAP SP INFO SP midi_map
6589                  </t>                  </t>
6590                    <t>/ FX_SENDS SP sampler_channel
6591                    </t>
6592                    <t>/ FX_SEND SP INFO SP sampler_channel SP fx_send_id
6593                    </t>
6594                    <t>/ DB_INSTRUMENT_DIRECTORIES SP RECURSIVE SP db_path
6595                    </t>
6596                    <t>/ DB_INSTRUMENT_DIRECTORIES SP db_path
6597                    </t>
6598                    <t>/ DB_INSTRUMENT_DIRECTORY SP INFO SP db_path
6599                    </t>
6600                    <t>/ DB_INSTRUMENTS SP RECURSIVE SP db_path
6601                    </t>
6602                    <t>/ DB_INSTRUMENTS SP db_path
6603                    </t>
6604                    <t>/ DB_INSTRUMENT SP INFO SP db_path
6605                    </t>
6606                    <t>/ DB_INSTRUMENTS_JOB SP INFO SP number
6607                    </t>
6608                    <t>/ VOLUME
6609                    </t>
6610                    <t>/ FILE SP INSTRUMENTS SP filename
6611                    </t>
6612                    <t>/ FILE SP INSTRUMENT SP INFO SP filename SP instrument_index
6613                    </t>
6614          </list>          </list>
6615  </t>  </t>
6616  <t>set_instruction =  <t>set_instruction =
# Line 4447  Schoenebeck'> Line 6621  Schoenebeck'>
6621                  </t>                  </t>
6622                  <t>/ MIDI_INPUT_DEVICE_PARAMETER SP number SP string '=' param_val_list                  <t>/ MIDI_INPUT_DEVICE_PARAMETER SP number SP string '=' param_val_list
6623                  </t>                  </t>
6624                    <t>/ MIDI_INPUT_PORT_PARAMETER SP number SP number SP string '=' NONE
6625                    </t>
6626                  <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
6627                  </t>                  </t>
6628                  <t>/ CHANNEL SP set_chan_instruction                  <t>/ CHANNEL SP set_chan_instruction
6629                  </t>                  </t>
6630                  <t>/ MIDI_INSTRUMENT_MAP SP NAME SP midi_map SP map_name                  <t>/ MIDI_INSTRUMENT_MAP SP NAME SP midi_map SP map_name
6631                  </t>                  </t>
6632                    <t>/ FX_SEND SP NAME SP sampler_channel SP fx_send_id SP fx_send_name
6633                    </t>
6634                    <t>/ FX_SEND SP AUDIO_OUTPUT_CHANNEL SP sampler_channel SP fx_send_id SP audio_channel_index SP audio_channel_index
6635                    </t>
6636                    <t>/ FX_SEND SP MIDI_CONTROLLER SP sampler_channel SP fx_send_id SP midi_ctrl
6637                    </t>
6638                    <t>/ FX_SEND SP LEVEL SP sampler_channel SP fx_send_id SP volume_value
6639                    </t>
6640                    <t>/ DB_INSTRUMENT_DIRECTORY SP NAME SP db_path SP stringval_escaped
6641                    </t>
6642                    <t>/ DB_INSTRUMENT_DIRECTORY SP DESCRIPTION SP db_path SP stringval_escaped
6643                    </t>
6644                    <t>/ DB_INSTRUMENT SP NAME SP db_path SP stringval_escaped
6645                    </t>
6646                    <t>/ DB_INSTRUMENT SP DESCRIPTION SP db_path SP stringval_escaped
6647                    </t>
6648                  <t>/ ECHO SP boolean                  <t>/ ECHO SP boolean
6649                  </t>                  </t>
6650                    <t>/ VOLUME SP volume_value
6651                    </t>
6652          </list>          </list>
6653  </t>  </t>
6654  <t>create_instruction =  <t>create_instruction =
# Line 4467  Schoenebeck'> Line 6661  Schoenebeck'>
6661                  </t>                  </t>
6662                  <t>/ MIDI_INPUT_DEVICE SP string                  <t>/ MIDI_INPUT_DEVICE SP string
6663                  </t>                  </t>
6664                    <t>/ FX_SEND SP sampler_channel SP midi_ctrl
6665                    </t>
6666                    <t>/ FX_SEND SP sampler_channel SP midi_ctrl SP fx_send_name
6667                    </t>
6668          </list>          </list>
6669  </t>  </t>
6670  <t>reset_instruction =  <t>reset_instruction =
# Line 4483  Schoenebeck'> Line 6681  Schoenebeck'>
6681                  </t>                  </t>
6682          </list>          </list>
6683  </t>  </t>
6684    <t>find_instruction =
6685            <list>
6686                    <t>DB_INSTRUMENTS SP NON_RECURSIVE SP db_path SP query_val_list
6687                    </t>
6688                    <t>/ DB_INSTRUMENTS SP db_path SP query_val_list
6689                    </t>
6690                    <t>/ DB_INSTRUMENT_DIRECTORIES SP NON_RECURSIVE SP db_path SP query_val_list
6691                    </t>
6692                    <t>/ DB_INSTRUMENT_DIRECTORIES SP db_path SP query_val_list
6693                    </t>
6694            </list>
6695    </t>
6696    <t>move_instruction =
6697            <list>
6698                    <t>DB_INSTRUMENT_DIRECTORY SP db_path SP db_path
6699                    </t>
6700                    <t>/ DB_INSTRUMENT SP db_path SP db_path
6701                    </t>
6702            </list>
6703    </t>
6704    <t>copy_instruction =
6705            <list>
6706                    <t>DB_INSTRUMENT_DIRECTORY SP db_path SP db_path
6707                    </t>
6708                    <t>/ DB_INSTRUMENT SP db_path SP db_path
6709                    </t>
6710            </list>
6711    </t>
6712  <t>destroy_instruction =  <t>destroy_instruction =
6713          <list>          <list>
6714                  <t>AUDIO_OUTPUT_DEVICE SP number                  <t>AUDIO_OUTPUT_DEVICE SP number
6715                  </t>                  </t>
6716                  <t>/ MIDI_INPUT_DEVICE SP number                  <t>/ MIDI_INPUT_DEVICE SP number
6717                  </t>                  </t>
6718                    <t>/ FX_SEND SP sampler_channel SP fx_send_id
6719                    </t>
6720          </list>          </list>
6721  </t>  </t>
6722  <t>load_instruction =  <t>load_instruction =
# Line 4531  Schoenebeck'> Line 6759  Schoenebeck'>
6759                  </t>                  </t>
6760          </list>          </list>
6761  </t>  </t>
6762    <t>edit_instruction =
6763            <list>
6764                    <t>CHANNEL SP INSTRUMENT SP sampler_channel
6765                    </t>
6766            </list>
6767    </t>
6768    <t>format_instruction =
6769            <list>
6770                    <t>INSTRUMENTS_DB
6771                    </t>
6772            </list>
6773    </t>
6774    <t>modal_arg =
6775            <list>
6776                    <t>/* epsilon (empty argument) */
6777                    </t>
6778                    <t>/ NON_MODAL SP
6779                    </t>
6780            </list>
6781    </t>
6782  <t>key_val_list =  <t>key_val_list =
6783          <list>          <list>
6784                  <t>string '=' param_val_list                  <t>string '=' param_val_list
# Line 4567  Schoenebeck'> Line 6815  Schoenebeck'>
6815                  </t>                  </t>
6816                  <t>/ MIDI_INSTRUMENT_MAPS                  <t>/ MIDI_INSTRUMENT_MAPS
6817                  </t>                  </t>
6818                    <t>/ FX_SENDS SP sampler_channel
6819                    </t>
6820                    <t>/ DB_INSTRUMENT_DIRECTORIES SP RECURSIVE SP db_path
6821                    </t>
6822                    <t>/ DB_INSTRUMENT_DIRECTORIES SP db_path
6823                    </t>
6824                    <t>/ DB_INSTRUMENTS SP RECURSIVE SP db_path
6825                    </t>
6826                    <t>/ DB_INSTRUMENTS SP db_path
6827                    </t>
6828                    <t>/ FILE SP INSTRUMENTS SP filename
6829                    </t>
6830          </list>          </list>
6831  </t>  </t>
6832  <t>load_instr_args =  <t>load_instr_args =
# Line 4649  Schoenebeck'> Line 6909  Schoenebeck'>
6909                  </t>                  </t>
6910          </list>          </list>
6911  </t>  </t>
6912    <t>midi_ctrl =
6913            <list>
6914                    <t>number
6915                    </t>
6916            </list>
6917    </t>
6918  <t>volume_value =  <t>volume_value =
6919          <list>          <list>
6920                  <t>dotnum                  <t>dotnum
# Line 4669  Schoenebeck'> Line 6935  Schoenebeck'>
6935                  </t>                  </t>
6936          </list>          </list>
6937  </t>  </t>
6938    <t>fx_send_id =
6939            <list>
6940                    <t>number
6941                    </t>
6942            </list>
6943    </t>
6944  <t>engine_name =  <t>engine_name =
6945          <list>          <list>
6946                  <t>string                  <t>string
# Line 4677  Schoenebeck'> Line 6949  Schoenebeck'>
6949  </t>  </t>
6950  <t>filename =  <t>filename =
6951          <list>          <list>
6952                  <t>stringval                  <t>path
6953                    </t>
6954            </list>
6955    </t>
6956    <t>db_path =
6957            <list>
6958                    <t>path
6959                  </t>                  </t>
6960          </list>          </list>
6961  </t>  </t>
6962  <t>map_name =  <t>map_name =
6963          <list>          <list>
6964                  <t>stringval                  <t>stringval_escaped
6965                  </t>                  </t>
6966          </list>          </list>
6967  </t>  </t>
6968  <t>entry_name =  <t>entry_name =
6969          <list>          <list>
6970                  <t>stringval                  <t>stringval_escaped
6971                    </t>
6972            </list>
6973    </t>
6974    <t>fx_send_name =
6975            <list>
6976                    <t>stringval_escaped
6977                  </t>                  </t>
6978          </list>          </list>
6979  </t>  </t>
# Line 4701  Schoenebeck'> Line 6985  Schoenebeck'>
6985                  </t>                  </t>
6986          </list>          </list>
6987  </t>  </t>
6988    
6989  <t>param_val =  <t>param_val =
6990          <list>          <list>
6991                  <t>string                  <t>string
# Line 4713  Schoenebeck'> Line 6998  Schoenebeck'>
6998                  </t>                  </t>
6999          </list>          </list>
7000  </t>  </t>
7001    <t>query_val_list =
7002            <list>
7003                    <t>string '=' query_val
7004                    </t>
7005                    <t>/ query_val_list SP string '=' query_val
7006                    </t>
7007            </list>
7008    </t>
7009    <t>query_val =
7010            <list>
7011                    <t>text_escaped
7012                    </t>
7013                    <t>/ stringval_escaped
7014                    </t>
7015            </list>
7016    </t>
7017    <t>scan_mode =
7018            <list>
7019                    <t>RECURSIVE
7020                    </t>
7021                    <t>/ NON_RECURSIVE
7022                    </t>
7023                    <t>/ FLAT
7024                    </t>
7025            </list>
7026    </t>
7027    
7028              <!-- GRAMMAR_BNF_END - do NOT delete or modify this line !!! -->              <!-- GRAMMAR_BNF_END - do NOT delete or modify this line !!! -->
7029    
7030                <section title="Character Set and Escape Sequences" anchor="character_set">
7031                    <t>Older versions of this protocol up to and including v1.1 only
7032                    supported the standard ASCII character set (ASCII code 0 - 127)
7033                    <xref target="RFC20"/>, all younger versions of this protocol
7034                    however support the Extended ASCII character set (ASCII code
7035                    0 - 255). The same group of younger protocols also support
7036                    escape sequences, but only for certain, explicitly declared
7037                    parts of the protocol. The supported escape sequences are
7038                    defined as follows:</t>
7039                    <texttable>
7040                        <ttcol>ASCII Character Sequence</ttcol>
7041                        <ttcol>Translated into (Name)</ttcol>
7042                        <c>\n</c> <c>new line</c>
7043                        <c>\r</c> <c>carriage return</c>
7044                        <c>\f</c> <c>form feed</c>
7045                        <c>\t</c> <c>horizontal tab</c>
7046                        <c>\v</c> <c>vertical tab</c>
7047                        <c>\'</c> <c>apostrophe</c>
7048                        <c>\"</c> <c>quotation mark</c>
7049                        <c>\\</c> <c>backslash</c>
7050                        <c>\OOO</c> <c>three digit octal ASCII code of the character</c>
7051                        <c>\xHH</c> <c>two digit hex ASCII code of the character</c>
7052                    </texttable>
7053                    <t>Notice: due to the transition of certain parts of the
7054                    protocol which now support escape sequences, a slight backward
7055                    incompatibility to protocols version v1.1 and younger has been
7056                    introduced. The only difference is that in parts of the protocol
7057                    where escape characters are now supported, a backslash characters
7058                    MUST be escaped as well (that is as double backslash), whereas
7059                    in the old versions a single backslash was sufficient.</t>
7060    
7061                    <t>The following LSCP commands support escape sequences as part
7062                    of their filename / path based arguments and / or may contain
7063                    a filename / path with escape sequences in their response:
7064                    <list>
7065                        <t><xref target="LOAD INSTRUMENT">"LOAD INSTRUMENT"</xref></t>
7066                        <t><xref target="GET CHANNEL INFO">"GET CHANNEL INFO"</xref></t>
7067                        <t><xref target="MAP MIDI_INSTRUMENT">"MAP MIDI_INSTRUMENT"</xref></t>
7068                        <t><xref target="GET MIDI_INSTRUMENT INFO">"GET MIDI_INSTRUMENT INFO"</xref></t>
7069                        <t><xref target="ADD DB_INSTRUMENT_DIRECTORY">"ADD DB_INSTRUMENT_DIRECTORY"</xref></t>
7070                        <t><xref target="ADD DB_INSTRUMENTS">"ADD DB_INSTRUMENTS"</xref></t>
7071                        <t><xref target="REMOVE DB_INSTRUMENT_DIRECTORY">"REMOVE DB_INSTRUMENT_DIRECTORY"</xref></t>
7072                        <t><xref target="REMOVE DB_INSTRUMENT">"REMOVE DB_INSTRUMENT"</xref></t>
7073                        <t><xref target="GET DB_INSTRUMENT_DIRECTORIES">"GET DB_INSTRUMENT_DIRECTORIES"</xref></t>
7074                        <t><xref target="LIST DB_INSTRUMENT_DIRECTORIES">"LIST DB_INSTRUMENT_DIRECTORIES"</xref></t>
7075                        <t><xref target="GET DB_INSTRUMENT_DIRECTORY INFO">"GET DB_INSTRUMENT_DIRECTORY INFO"</xref></t>
7076                        <t><xref target="GET DB_INSTRUMENTS">"GET DB_INSTRUMENTS"</xref></t>
7077                        <t><xref target="LIST DB_INSTRUMENTS">"LIST DB_INSTRUMENTS"</xref></t>
7078                        <t><xref target="GET DB_INSTRUMENT INFO">"GET DB_INSTRUMENT INFO"</xref></t>
7079                        <t><xref target="SET DB_INSTRUMENT_DIRECTORY NAME">"SET DB_INSTRUMENT_DIRECTORY NAME"</xref></t>
7080                        <t><xref target="SET DB_INSTRUMENT_DIRECTORY DESCRIPTION">"SET DB_INSTRUMENT_DIRECTORY DESCRIPTION"</xref></t>
7081                        <t><xref target="SET DB_INSTRUMENT NAME">"SET DB_INSTRUMENT NAME"</xref></t>
7082                        <t><xref target="SET DB_INSTRUMENT DESCRIPTION">"SET DB_INSTRUMENT DESCRIPTION"</xref></t>
7083                        <t><xref target="FIND DB_INSTRUMENTS">"FIND DB_INSTRUMENTS"</xref></t>
7084                        <t><xref target="FIND DB_INSTRUMENT_DIRECTORIES">"FIND DB_INSTRUMENT_DIRECTORIES"</xref></t>
7085                        <t><xref target="MOVE DB_INSTRUMENT">"MOVE DB_INSTRUMENT"</xref></t>
7086                        <t><xref target="MOVE DB_INSTRUMENT_DIRECTORY">"MOVE DB_INSTRUMENT_DIRECTORY"</xref></t>
7087                        <t><xref target="COPY DB_INSTRUMENT">"COPY DB_INSTRUMENT"</xref></t>
7088                        <t><xref target="COPY DB_INSTRUMENT_DIRECTORY">"COPY DB_INSTRUMENT_DIRECTORY"</xref></t>
7089                        <t><xref target="GET FILE INSTRUMENTS">"GET FILE INSTRUMENTS"</xref></t>
7090                        <t><xref target="LIST FILE INSTRUMENTS">"LIST FILE INSTRUMENTS"</xref></t>
7091                        <t><xref target="GET FILE INSTRUMENT INFO">"GET FILE INSTRUMENT INFO"</xref></t>
7092                    </list>
7093                    Note that the forward slash character ('/') has a special meaning in
7094                    filename / path based arguments: it acts as separator of the nodes in
7095                    the path, thus if a directory- or filename includes a forward slash
7096                    (not intended as path node separator), you MUST escape that slash
7097                    either with the respective hex escape sequence ("\x2f") or with the
7098                    respective octal escape sequence ("\057").
7099                    </t>
7100    
7101                    <t>
7102                    Note for Windows: file path arguments in LSCP are expected
7103                    to use forward slashes as directory node separator similar
7104                    to Unix based operating systems. In contrast to Unix however
7105                    a Windows typical drive character is expected to be
7106                    prefixed to the path. That is an original Windows file path
7107                    like "D:\Sounds\My.gig" would become in LSCP:
7108                    "D:/Sounds/My.gig".
7109                    </t>
7110    
7111                    <t>
7112                    The following LSCP commands even support escape sequences as
7113                    part of at least one of their text-based arguments (i.e. entity name,
7114                    description) and / or may contain escape sequences in at least one of
7115                    their text-based fields in their response:
7116                    <list>
7117                        <t><xref target="GET SERVER INFO">"GET SERVER INFO"</xref></t>
7118                        <t><xref target="GET ENGINE INFO">"GET ENGINE INFO"</xref></t>
7119                        <t><xref target="GET CHANNEL INFO">"GET CHANNEL INFO"</xref></t>
7120                        <t><xref target="CREATE FX_SEND">"CREATE FX_SEND"</xref></t>
7121                        <t><xref target="GET FX_SEND INFO">"GET FX_SEND INFO"</xref></t>
7122                        <t><xref target="SET FX_SEND NAME">"SET FX_SEND NAME"</xref></t>
7123                        <t><xref target="GET MIDI_INSTRUMENT INFO">"GET MIDI_INSTRUMENT INFO"</xref></t>
7124                        <t><xref target="GET MIDI_INSTRUMENT_MAP INFO">"GET MIDI_INSTRUMENT_MAP INFO"</xref></t>
7125                        <t><xref target="ADD MIDI_INSTRUMENT_MAP">"ADD MIDI_INSTRUMENT_MAP"</xref></t>
7126                        <t><xref target="MAP MIDI_INSTRUMENT">"MAP MIDI_INSTRUMENT"</xref></t>
7127                        <t><xref target="SET MIDI_INSTRUMENT_MAP NAME">"SET MIDI_INSTRUMENT_MAP NAME"</xref></t>
7128                        <t><xref target="GET DB_INSTRUMENT_DIRECTORY INFO">"GET DB_INSTRUMENT_DIRECTORY INFO"</xref></t>
7129                        <t><xref target="SET DB_INSTRUMENT_DIRECTORY NAME">"SET DB_INSTRUMENT_DIRECTORY NAME"</xref></t>
7130                        <t><xref target="SET DB_INSTRUMENT_DIRECTORY DESCRIPTION">"SET DB_INSTRUMENT_DIRECTORY DESCRIPTION"</xref></t>
7131                        <t><xref target="FIND DB_INSTRUMENT_DIRECTORIES">"FIND DB_INSTRUMENT_DIRECTORIES"</xref></t>
7132                        <t><xref target="GET DB_INSTRUMENT INFO">"GET DB_INSTRUMENT INFO"</xref></t>
7133                        <t><xref target="SET DB_INSTRUMENT NAME">"SET DB_INSTRUMENT NAME"</xref></t>
7134                        <t><xref target="SET DB_INSTRUMENT DESCRIPTION">"SET DB_INSTRUMENT DESCRIPTION"</xref></t>
7135                        <t><xref target="FIND DB_INSTRUMENTS">"FIND DB_INSTRUMENTS"</xref></t>
7136                    </list>
7137                    Please note that these lists are manually maintained. If you
7138                    find a command that also supports escape sequences we forgot to
7139                    mention here, please report it!
7140                    </t>
7141                </section>
7142          </section>          </section>
7143    
7144          <section title="Events" anchor="events">          <section title="Events" anchor="events">
# Line 4818  Schoenebeck'> Line 7242  Schoenebeck'>
7242                  of sampler channels.</t>                  of sampler channels.</t>
7243              </section>              </section>
7244    
7245                <section title="MIDI data on a sampler channel arrived" anchor="SUBSCRIBE CHANNEL_MIDI">
7246                    <t>Client may want to be notified when MIDI data arrive on sampler channels on
7247                    back-end side, by issuing the following command:</t>
7248                    <t>
7249                        <list>
7250                            <t>SUBSCRIBE CHANNEL_MIDI</t>
7251                        </list>
7252                    </t>
7253                    <t>Server will start sending one of the the following notification messages:</t>
7254                    <t>
7255                        <list>
7256                            <t>"NOTIFY:CHANNEL_MIDI:&lt;channel-id&gt; NOTE_ON  &lt;note&gt; &lt;velocity&gt;"</t>
7257                            <t>"NOTIFY:CHANNEL_MIDI:&lt;channel-id&gt; NOTE_OFF &lt;note&gt; &lt;velocity&gt;"</t>
7258                        </list>
7259                    </t>
7260                    <t>where &lt;channel-id&gt; will be replaced by the ID of the sampler channel where the MIDI
7261                    data arrived. &lt;note&gt; and &lt;velocity&gt; are integer values in the range between
7262                    0 .. 127, reflecting the analog meaning of the MIDI specification.
7263                    </t>
7264                    <t>CAUTION: no guarantee whatsoever will be made that MIDI events are actually all
7265                    delivered by this mechanism! With other words: events could be lost at any time!
7266                    This restriction was made to keep the RT-safeness of the backend's MIDI and audio
7267                    thread unaffected by this feature.</t>
7268                </section>
7269    
7270              <section title="Number of active voices changed" anchor="SUBSCRIBE VOICE_COUNT">              <section title="Number of active voices changed" anchor="SUBSCRIBE VOICE_COUNT">
7271                  <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
7272                  back-end changes by issuing the following command:</t>                  back-end changes by issuing the following command:</t>
# Line 4829  Schoenebeck'> Line 7278  Schoenebeck'>
7278                  <t>Server will start sending the following notification messages:</t>                  <t>Server will start sending the following notification messages:</t>
7279                  <t>                  <t>
7280                      <list>                      <list>
7281                          <t>"NOTIFY:VOICE_COUNT:&lt;sampler-channel&gt; &lt;voices&gt;</t>                          <t>"NOTIFY:VOICE_COUNT:&lt;sampler-channel&gt; &lt;voices&gt;"</t>
7282                      </list>                      </list>
7283                  </t>                  </t>
7284                  <t>where &lt;sampler-channel&gt; will be replaced by the sampler channel the                  <t>where &lt;sampler-channel&gt; will be replaced by the sampler channel the
# Line 4899  Schoenebeck'> Line 7348  Schoenebeck'>
7348                  message is sufficient here.</t>                  message is sufficient here.</t>
7349              </section>              </section>
7350    
7351                <section title="Number of effect sends changed" anchor="SUBSCRIBE FX_SEND_COUNT">
7352                    <t>Client may want to be notified when the number of effect sends on
7353                    a particular sampler channel is changed by issuing the following command:</t>
7354                    <t>
7355                        <list>
7356                            <t>SUBSCRIBE FX_SEND_COUNT</t>
7357                        </list>
7358                    </t>
7359                    <t>Server will start sending the following notification messages:</t>
7360                    <t>
7361                        <list>
7362                            <t>"NOTIFY:FX_SEND_COUNT:&lt;channel-id&gt; &lt;fx-sends&gt;"</t>
7363                        </list>
7364                    </t>
7365                    <t>where &lt;channel-id&gt; will be replaced by the numerical ID of the sampler
7366                    channel, on which the effect sends number is changed and &lt;fx-sends&gt; will
7367                    be replaced by the new number of effect sends on that channel.</t>
7368                </section>
7369    
7370                <section title="Effect send information changed" anchor="SUBSCRIBE FX_SEND_INFO">
7371                    <t>Client may want to be notified when changes were made to effect sends on a
7372                    a particular sampler channel by issuing the following command:</t>
7373                    <t>
7374                        <list>
7375                            <t>SUBSCRIBE FX_SEND_INFO</t>
7376                        </list>
7377                    </t>
7378                    <t>Server will start sending the following notification messages:</t>
7379                    <t>
7380                        <list>
7381                            <t>"NOTIFY:FX_SEND_INFO:&lt;channel-id&gt; &lt;fx-send-id&gt;"</t>
7382                        </list>
7383                    </t>
7384                    <t>where &lt;channel-id&gt; will be replaced by the numerical ID of the sampler
7385                    channel, on which an effect send entity is changed and &lt;fx-send-id&gt; will
7386                    be replaced by the numerical ID of the changed effect send.</t>
7387                </section>
7388    
7389              <section title="Total number of active voices changed" anchor="SUBSCRIBE TOTAL_VOICE_COUNT">              <section title="Total number of active voices changed" anchor="SUBSCRIBE TOTAL_VOICE_COUNT">
7390                  <t>Client may want to be notified when the total number of voices on the                  <t>Client may want to be notified when the total number of voices on the
7391                  back-end changes by issuing the following command:</t>                  back-end changes by issuing the following command:</t>
# Line 4910  Schoenebeck'> Line 7397  Schoenebeck'>
7397                  <t>Server will start sending the following notification messages:</t>                  <t>Server will start sending the following notification messages:</t>
7398                  <t>                  <t>
7399                      <list>                      <list>
7400                          <t>"NOTIFY:TOTAL_VOICE_COUNT:&lt;voices&gt;</t>                          <t>"NOTIFY:TOTAL_VOICE_COUNT:&lt;voices&gt;"</t>
7401                      </list>                      </list>
7402                  </t>                  </t>
7403                  <t>where &lt;voices&gt; will be replaced by the new number of                  <t>where &lt;voices&gt; will be replaced by the new number of
7404                  all currently active voices.</t>                  all currently active voices.</t>
7405              </section>              </section>
7406    
7407                <section title="Total number of active disk streams changed" anchor="SUBSCRIBE TOTAL_STREAM_COUNT">
7408                    <t>Client may want to be notified when the total number of disk streams on the
7409                    back-end changes by issuing the following command:</t>
7410                    <t>
7411                        <list>
7412                            <t>SUBSCRIBE TOTAL_STREAM_COUNT</t>
7413                        </list>
7414                    </t>
7415                    <t>Server will start sending the following notification messages:</t>
7416                    <t>
7417                        <list>
7418                            <t>"NOTIFY:TOTAL_STREAM_COUNT:&lt;streams&gt;"</t>
7419                        </list>
7420                    </t>
7421                    <t>where &lt;streams&gt; will be replaced by the new number of
7422                    all currently active disk streams.</t>
7423                </section>
7424    
7425              <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">
7426                  <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
7427                  back-end changes by issuing the following command:</t>                  back-end changes by issuing the following command:</t>
# Line 4971  Schoenebeck'> Line 7476  Schoenebeck'>
7476                          <t>"NOTIFY:MIDI_INSTRUMENT_COUNT:&lt;map-id&gt; &lt;instruments&gt;"</t>                          <t>"NOTIFY:MIDI_INSTRUMENT_COUNT:&lt;map-id&gt; &lt;instruments&gt;"</t>
7477                      </list>                      </list>
7478                  </t>                  </t>
7479                  <t>where &lt;map-id&gt; is the numerical ID of the MIDI instrument map, in which                  <t>where &lt;map-id&gt; is the numerical ID of the MIDI instrument map, in which
7480                  the nuber of instruments has changed and &lt;instruments&gt; will be replaced by                  the nuber of instruments has changed and &lt;instruments&gt; will be replaced by
7481                  the new number of MIDI instruments in the specified map.</t>                  the new number of MIDI instruments in the specified map.</t>
7482              </section>              </section>
# Line 4991  Schoenebeck'> Line 7496  Schoenebeck'>
7496                      </list>                      </list>
7497                  </t>                  </t>
7498                  <t>where &lt;map-id&gt; will be replaced by the numerical ID of the MIDI instrument map,                  <t>where &lt;map-id&gt; will be replaced by the numerical ID of the MIDI instrument map,
7499                  in which a MIDI instrument is changed. &lt;bank&gt; and &lt;program&gt; specifies                  in which a MIDI instrument is changed. &lt;bank&gt; and &lt;program&gt; specifies
7500                  the location of the changed MIDI instrument in the map. The front-end will have to send                  the location of the changed MIDI instrument in the map. The front-end will have to send
7501                  the respective command to actually get the MIDI instrument info. Because these messages                  the respective command to actually get the MIDI instrument info. Because these messages
7502                  will be triggered by LSCP commands issued by other clients rather than real                  will be triggered by LSCP commands issued by other clients rather than real
# Line 4999  Schoenebeck'> Line 7504  Schoenebeck'>
7504                  message is sufficient here.</t>                  message is sufficient here.</t>
7505              </section>              </section>
7506    
7507              <<section title="Miscellaneous and debugging events" anchor="SUBSCRIBE MISCELLANEOUS">              <section title="Global settings changed" anchor="SUBSCRIBE GLOBAL_INFO">
7508                    <t>Client may want to be notified when changes to the global settings
7509                    of the sampler were made by issuing the following command:</t>
7510                    <t>
7511                        <list>
7512                            <t>SUBSCRIBE GLOBAL_INFO</t>
7513                        </list>
7514                    </t>
7515                    <t>Server will start sending the following types of notification messages:</t>
7516                    <t>
7517                        <list>
7518                            <t>"NOTIFY:GLOBAL_INFO:VOLUME &lt;volume&gt;" - Notifies that the
7519                            golbal volume of the sampler is changed, where &lt;volume&gt; will be
7520                            replaced by the optional dotted floating point value, reflecting the
7521                            new global volume parameter.</t>
7522                        </list>
7523                    </t>
7524                </section>
7525    
7526                <section title="Number of database instrument directories changed" anchor="SUBSCRIBE DB_INSTRUMENT_DIRECTORY_COUNT">
7527                    <t>Client may want to be notified when the number of instrument
7528                    directories in a particular directory in the instruments database
7529                    is changed by issuing the following command:</t>
7530                    <t>
7531                        <list>
7532                            <t>SUBSCRIBE DB_INSTRUMENT_DIRECTORY_COUNT</t>
7533                        </list>
7534                    </t>
7535                    <t>Server will start sending the following notification messages:</t>
7536                    <t>
7537                        <list>
7538                            <t>"NOTIFY:DB_INSTRUMENT_DIRECTORY_COUNT:&lt;dir-path&gt;"</t>
7539                        </list>
7540                    </t>
7541                    <t>where &lt;dir-path&gt; will be replaced by the absolute path
7542                    name of the directory in the instruments database,
7543                    in which the number of directories is changed.</t>
7544                    <t>Note that when a non-empty directory is removed, this event
7545                    is not sent for the subdirectories in that directory.</t>
7546                </section>
7547    
7548                <section title="Database instrument directory information changed" anchor="SUBSCRIBE DB_INSTRUMENT_DIRECTORY_INFO">
7549                    <t>Client may want to be notified when changes were made to directories
7550                    in the instruments database by issuing the following command:</t>
7551                    <t>
7552                        <list>
7553                            <t>SUBSCRIBE DB_INSTRUMENT_DIRECTORY_INFO</t>
7554                        </list>
7555                    </t>
7556                    <t>Server will start sending the following notification messages:</t>
7557                    <t>
7558                        <list>
7559                            <t>"NOTIFY:DB_INSTRUMENT_DIRECTORY_INFO:&lt;dir-path&gt;"</t>
7560                        </list>
7561                    </t>
7562                    <t>where &lt;dir-path&gt; will be replaced by the absolute path name
7563                    of the directory, for which information changes occurred. The front-end will have to send
7564                    the respective command to actually get the updated directory info. Because these messages
7565                    will be triggered by LSCP commands issued by other clients rather than real
7566                    time events happening on the server, it is believed that an empty notification
7567                    message is sufficient here.</t>
7568                    <t>
7569                        <list>
7570                            <t>"NOTIFY:DB_INSTRUMENT_DIRECTORY_INFO:NAME &lt;old-dir-path&gt; &lt;new-name&gt;"</t>
7571                        </list>
7572                    </t>
7573                    <t>where &lt;old-dir-path&gt; is the old absolute path name of the directory
7574                    (encapsulated into apostrophes), which name is changes and &lt;new-name&gt; is
7575                    the new name of the directory, encapsulated into apostrophes.</t>
7576                </section>
7577    
7578                <section title="Number of database instruments changed" anchor="SUBSCRIBE DB_INSTRUMENT_COUNT">
7579                    <t>Client may want to be notified when the number of instruments
7580                    in a particular directory in the instruments database
7581                    is changed by issuing the following command:</t>
7582                    <t>
7583                        <list>
7584                            <t>SUBSCRIBE DB_INSTRUMENT_COUNT</t>
7585                        </list>
7586                    </t>
7587                    <t>Server will start sending the following notification messages:</t>
7588                    <t>
7589                        <list>
7590                            <t>"NOTIFY:DB_INSTRUMENT_COUNT:&lt;dir-path&gt;"</t>
7591                        </list>
7592                    </t>
7593                    <t>where &lt;dir-path&gt; will be replaced by the absolute path
7594                    name of the directory in the instruments database,
7595                    in which the number of instruments is changed.</t>
7596                    <t>Note that when a non-empty directory is removed, this event
7597                    is not sent for the instruments in that directory.</t>
7598                </section>
7599    
7600                <section title="Database instrument information changed" anchor="SUBSCRIBE DB_INSTRUMENT_INFO">
7601                    <t>Client may want to be notified when changes were made to instruments
7602                    in the instruments database by issuing the following command:</t>
7603                    <t>
7604                        <list>
7605                            <t>SUBSCRIBE DB_INSTRUMENT_INFO</t>
7606                        </list>
7607                    </t>
7608                    <t>Server will start sending the following notification messages:</t>
7609                    <t>
7610                        <list>
7611                            <t>"NOTIFY:DB_INSTRUMENT_INFO:&lt;instr-path&gt;"</t>
7612                        </list>
7613                    </t>
7614                    <t>where &lt;instr-path&gt; will be replaced by the absolute path name
7615                    of the instrument, which settings are changed. The front-end will have to send
7616                    the respective command to actually get the updated directory info. Because these messages
7617                    will be triggered by LSCP commands issued by other clients rather than real
7618                    time events happening on the server, it is believed that an empty notification
7619                    message is sufficient here.</t>
7620                    <t>
7621                        <list>
7622                            <t>"NOTIFY:DB_INSTRUMENT_INFO:NAME &lt;old-instr-path&gt; &lt;new-name&gt;"</t>
7623                        </list>
7624                    </t>
7625                    <t>where &lt;old-instr-path&gt; is the old absolute path name of the instrument
7626                    (encapsulated into apostrophes), which name is changes and &lt;new-name&gt; is
7627                    the new name of the instrument, encapsulated into apostrophes.</t>
7628                </section>
7629    
7630                <section title="Database job status information changed" anchor="SUBSCRIBE DB_INSTRUMENTS_JOB_INFO">
7631                    <t>Client may want to be notified when the status of particular database
7632                    instruments job is changed by issuing the following command:</t>
7633                    <t>
7634                        <list>
7635                            <t>SUBSCRIBE DB_INSTRUMENTS_JOB_INFO</t>
7636                        </list>
7637                    </t>
7638                    <t>Server will start sending the following notification messages:</t>
7639                    <t>
7640                        <list>
7641                            <t>"NOTIFY:DB_INSTRUMENTS_JOB_INFO:&lt;job-id&gt;"</t>
7642                        </list>
7643                    </t>
7644                    <t>where &lt;job-id&gt; will be replaced by the numerical ID of the job,
7645                    which status is changed. The front-end will have to send the respective
7646                    command to actually get the status info. Because these messages
7647                    will be triggered by LSCP commands issued by other clients rather than real
7648                    time events happening on the server, it is believed that an empty notification
7649                    message is sufficient here.</t>
7650                </section>
7651    
7652                <section title="Miscellaneous and debugging events" anchor="SUBSCRIBE MISCELLANEOUS">
7653                  <t>Client may want to be notified of miscellaneous and debugging events occurring at                  <t>Client may want to be notified of miscellaneous and debugging events occurring at
7654                  the server by issuing the following command:</t>                  the server by issuing the following command:</t>
7655                  <t>                  <t>
# Line 5077  Schoenebeck'> Line 7727  Schoenebeck'>
7727                  </front>                  </front>
7728                  <seriesInfo name="RFC" value="2234" />                  <seriesInfo name="RFC" value="2234" />
7729              </reference>              </reference>
7730                <reference anchor="RFC20">
7731                    <front>
7732                        <title>ASCII format for Network Interchange</title>
7733                        <author>
7734                            <organization>UCLA</organization>
7735                        </author>
7736                        <date year="1969"></date>
7737                    </front>
7738                    <seriesInfo name="RFC" value="20" />
7739                </reference>
7740           </references>           </references>
7741      </back>      </back>
7742    
Legend:
Removed from v.981  
changed lines
  Added in v.1686
  ViewVC Help
Powered by ViewVC