/[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 973 by schoenebeck, Fri Dec 15 21:40:27 2006 UTC revision 1552 by schoenebeck, Wed Dec 5 22:37:42 2007 UTC
# 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="October" year="2007"/>
38          <workgroup>LinuxSampler Developers</workgroup>          <workgroup>LinuxSampler Developers</workgroup>
39          <keyword>LSCP</keyword>          <keyword>LSCP</keyword>
40          <abstract>          <abstract>
# Line 61  Schoenebeck'> Line 61  Schoenebeck'>
61              (front-end) and server (LinuxSampler) respectively. Lines in              (front-end) and server (LinuxSampler) respectively. Lines in
62              examples must be interpreted as every line being CRLF              examples must be interpreted as every line being CRLF
63              terminated (carriage return character followed by line feed              terminated (carriage return character followed by line feed
64              character as defined in the ASCII standard), thus the following              character as defined in the ASCII standard <xref target="RFC20"/>),
65              example:</t>              thus the following example:</t>
66    
67              <t>              <t>
68                  <list>                  <list>
# Line 2061  Schoenebeck'> Line 2061  Schoenebeck'>
2061                      or <xref target="LIST MIDI_INPUT_DEVICES">"LIST MIDI_INPUT_DEVICES"</xref>                      or <xref target="LIST MIDI_INPUT_DEVICES">"LIST MIDI_INPUT_DEVICES"</xref>
2062                      command, &lt;port&gt; by the MIDI port number, &lt;key&gt; by the name of                      command, &lt;port&gt; by the MIDI port number, &lt;key&gt; by the name of
2063                      the parameter to change and &lt;value&gt; by the new value for this                      the parameter to change and &lt;value&gt; by the new value for this
2064                      parameter.</t>                      parameter (encapsulated into apostrophes) or NONE (not encapsulated into apostrophes)
2065                        for specifying no value for parameters allowing a list of values.</t>
2066    
2067                      <t>Possible Answers:</t>                      <t>Possible Answers:</t>
2068                      <t>                      <t>
# Line 2088  Schoenebeck'> Line 2089  Schoenebeck'>
2089                      <t>Example:</t>                      <t>Example:</t>
2090                      <t>                      <t>
2091                          <list>                          <list>
2092                              <t></t>                              <t>C: "SET MIDI_INPUT_PORT_PARAMETER 0 0 ALSA_SEQ_BINDINGS='20:0'"</t>
2093                                <t>S: "OK"</t>
2094                            </list>
2095                        </t>
2096                        <t>
2097                            <list>
2098                                <t>C: "SET MIDI_INPUT_PORT_PARAMETER 0 0 ALSA_SEQ_BINDINGS=NONE"</t>
2099                                <t>S: "OK"</t>
2100                          </list>                          </list>
2101                      </t>                      </t>
2102                  </section>                  </section>
# Line 2113  Schoenebeck'> Line 2121  Schoenebeck'>
2121                      number of the sampler channel the instrument should be assigned to.                      number of the sampler channel the instrument should be assigned to.
2122                      Each sampler channel can only have one instrument.</t>                      Each sampler channel can only have one instrument.</t>
2123    
2124                        <t>Notice: since LSCP 1.2 the &lt;filename&gt; argument supports
2125                        escape characters for special characters (see chapter
2126                        "<xref target="character_set">Character Set and Escape Sequences</xref>"
2127                        for details) and accordingly backslash characters in the filename
2128                        MUST now be escaped as well!</t>
2129    
2130                      <t>The difference between regular and NON_MODAL versions of the command                      <t>The difference between regular and NON_MODAL versions of the command
2131                      is that the regular command returns OK only after the instrument has been                      is that the regular command returns OK only after the instrument has been
2132                      fully loaded and the channel is ready to be used while NON_MODAL version                      fully loaded and the channel is ready to be used while NON_MODAL version
# Line 2429  Schoenebeck'> Line 2443  Schoenebeck'>
2443                                  <list>                                  <list>
2444                                      <t>DESCRIPTION -                                      <t>DESCRIPTION -
2445                                          <list>                                          <list>
2446                                              <t>arbitrary description text about the engine</t>                                              <t>arbitrary description text about the engine
2447                                                (note that the character string may contain
2448                                                <xref target="character_set">escape sequences</xref>)</t>
2449                                          </list>                                          </list>
2450                                      </t>                                      </t>
2451                                       <t>VERSION -                                       <t>VERSION -
# Line 2513  Schoenebeck'> Line 2529  Schoenebeck'>
2529                                          <list>                                          <list>
2530                                              <t>the file name of the loaded instrument, "NONE" if                                              <t>the file name of the loaded instrument, "NONE" if
2531                                              there's no instrument yet loaded for this sampler                                              there's no instrument yet loaded for this sampler
2532                                              channel</t>                                              channel (note: since LSCP 1.2 this path may contain
2533                                                <xref target="character_set">escape sequences</xref>)</t>
2534                                          </list>                                          </list>
2535                                      </t>                                      </t>
2536                                      <t>INSTRUMENT_NR -                                      <t>INSTRUMENT_NR -
# Line 2523  Schoenebeck'> Line 2540  Schoenebeck'>
2540                                      </t>                                      </t>
2541                                      <t>INSTRUMENT_NAME -                                      <t>INSTRUMENT_NAME -
2542                                          <list>                                          <list>
2543                                              <t>the instrument name of the loaded instrument</t>                                              <t>the instrument name of the loaded instrument
2544                                                (note: since LSCP 1.2 this character string may contain
2545                                                <xref target="character_set">escape sequences</xref>)</t>
2546                                          </list>                                          </list>
2547                                      </t>                                      </t>
2548                                      <t>INSTRUMENT_STATUS -                                      <t>INSTRUMENT_STATUS -
# Line 2555  Schoenebeck'> Line 2574  Schoenebeck'>
2574                                      <t>VOLUME -                                      <t>VOLUME -
2575                                          <list>                                          <list>
2576                                              <t>optionally dotted number for the channel volume factor                                              <t>optionally dotted number for the channel volume factor
2577                                              (where a value < 1.0 means attenuation and a value >                                              (where a value &lt; 1.0 means attenuation and a value >
2578                                              1.0 means amplification)</t>                                              1.0 means amplification)</t>
2579                                          </list>                                          </list>
2580                                      </t>                                      </t>
# Line 3227  Schoenebeck'> Line 3246  Schoenebeck'>
3246                      </t>                      </t>
3247                  </section>                  </section>
3248    
3249                    <section title="Adding an effect send to a sampler channel" anchor="CREATE FX_SEND">
3250                        <t>The front-end can create an additional effect send on a specific sampler channel
3251                        by sending the following command:</t>
3252                        <t>
3253                            <list>
3254                                <t>CREATE FX_SEND &lt;sampler-channel&gt; &lt;midi-ctrl&gt; [&lt;name&gt;]</t>
3255                            </list>
3256                        </t>
3257                        <t>Where &lt;sampler-channel&gt; is the respective sampler channel
3258                        number as returned by the <xref target="ADD CHANNEL">"ADD CHANNEL"</xref>
3259                        or <xref target="LIST CHANNELS">"LIST CHANNELS"</xref> command, that is the
3260                        sampler channel on which the effect send should be created on, &lt;midi-ctrl&gt;
3261                        is a number between 0..127 defining the MIDI controller which can alter the
3262                        effect send level and &lt;name&gt; is an optional argument defining a name
3263                        for the effect send entity. The name does not have to be unique, but MUST be
3264                        encapsulated into apostrophes and supports escape sequences as described in chapter
3265                        "<xref target="character_set">Character Set and Escape Sequences</xref>".</t>
3266    
3267                        <t>By default, that is as initial routing, the effect send's audio channels
3268                        are automatically routed to the last audio channels of the sampler channel's
3269                        audio output device, that way you can i.e. first increase the amount of audio
3270                        channels on the audio output device for having dedicated effect send output
3271                        channels and when "CREATE FX_SEND" is called, those channels will automatically
3272                        be picked. You can alter the destination channels however with
3273                        <xref target="SET FX_SEND AUDIO_OUTPUT_CHANNEL">"SET FX_SEND AUDIO_OUTPUT_CHANNEL"</xref>.
3274                        </t>
3275    
3276                        <t>Note: Create effect sends on a sampler channel only when needed, because having effect
3277                        sends on a sampler channel will decrease runtime performance, because for implementing channel
3278                        effect sends, separate (sampler channel local) audio buffers are needed to render and mix
3279                        the voices and route the audio signal afterwards to the master outputs and effect send
3280                        outputs (along with their respective effect send levels). A sampler channel without effect
3281                        sends however can mix its voices directly into the audio output devices's audio buffers
3282                        and is thus faster.
3283                        </t>
3284    
3285                        <t>Possible Answers:</t>
3286                        <t>
3287                            <list>
3288                                <t>"OK[&lt;fx-send-id&gt;]" -
3289                                    <list>
3290                                        <t>in case a new effect send could be added to the
3291                                        sampler channel, where &lt;fx-send-id&gt; reflects the
3292                                        unique ID of the newly created effect send entity</t>
3293                                    </list>
3294                                </t>
3295                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
3296                                    <list>
3297                                        <t>when a new effect send could not be added, i.e.
3298                                        due to invalid parameters</t>
3299                                    </list>
3300                                </t>
3301                            </list>
3302                        </t>
3303    
3304                        <t>Examples:</t>
3305                        <t>
3306                            <list>
3307                                <t>C: "CREATE FX_SEND 0 91 'Reverb Send'"</t>
3308                                <t>S: "OK[0]"</t>
3309                            </list>
3310                        </t>
3311                        <t>
3312                            <list>
3313                                <t>C: "CREATE FX_SEND 0 93"</t>
3314                                <t>S: "OK[1]"</t>
3315                            </list>
3316                        </t>
3317                    </section>
3318    
3319                    <section title="Removing an effect send from a sampler channel" anchor="DESTROY FX_SEND">
3320                        <t>The front-end can remove an existing effect send on a specific sampler channel
3321                        by sending the following command:</t>
3322                        <t>
3323                            <list>
3324                                <t>DESTROY FX_SEND &lt;sampler-channel&gt; &lt;fx-send-id&gt;</t>
3325                            </list>
3326                        </t>
3327                        <t>Where &lt;sampler-channel&gt; is the respective sampler channel
3328                        number as returned by the <xref target="ADD CHANNEL">"ADD CHANNEL"</xref>
3329                        or <xref target="LIST CHANNELS">"LIST CHANNELS"</xref> command, that is the
3330                        sampler channel from which the effect send should be removed from and
3331                        &lt;fx-send-id&gt; is the respective effect send number as returned by the
3332                        <xref target="CREATE FX_SEND">"CREATE FX_SEND"</xref>
3333                        or <xref target="LIST FX_SENDS">"LIST FX_SENDS"</xref> command.</t>
3334    
3335                        <t>Possible Answers:</t>
3336                        <t>
3337                            <list>
3338                                <t>"OK" -
3339                                    <list>
3340                                        <t>on success</t>
3341                                    </list>
3342                                </t>
3343                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
3344                                    <list>
3345                                        <t>in case it failed, providing an appropriate error code and
3346                                        error message</t>
3347                                    </list>
3348                                </t>
3349                            </list>
3350                        </t>
3351    
3352                        <t>Example:</t>
3353                        <t>
3354                            <list>
3355                                <t>C: "DESTROY FX_SEND 0 0"</t>
3356                                <t>S: "OK"</t>
3357                            </list>
3358                        </t>
3359                    </section>
3360    
3361                    <section title="Getting amount of effect sends on a sampler channel" anchor="GET FX_SENDS">
3362                        <t>The front-end can ask for the amount of effect sends on a specific sampler channel
3363                        by sending the following command:</t>
3364                        <t>
3365                            <list>
3366                                <t>GET FX_SENDS &lt;sampler-channel&gt;</t>
3367                            </list>
3368                        </t>
3369                        <t>Where &lt;sampler-channel&gt; is the respective sampler channel
3370                        number as returned by the <xref target="ADD CHANNEL">"ADD CHANNEL"</xref>
3371                        or <xref target="LIST CHANNELS">"LIST CHANNELS"</xref> command.</t>
3372    
3373                        <t>Possible Answers:</t>
3374                        <t>
3375                            <list>
3376                                <t>The sampler will answer by returning the number of effect
3377                                sends on the given sampler channel.</t>
3378                            </list>
3379                        </t>
3380    
3381                        <t>Example:</t>
3382                        <t>
3383                            <list>
3384                                <t>C: "GET FX_SENDS 0"</t>
3385                                <t>S: "2"</t>
3386                            </list>
3387                        </t>
3388                    </section>
3389    
3390                    <section title="Listing all effect sends on a sampler channel" anchor="LIST FX_SENDS">
3391                        <t>The front-end can ask for a list of effect sends on a specific sampler channel
3392                        by sending the following command:</t>
3393                        <t>
3394                            <list>
3395                                <t>LIST FX_SENDS &lt;sampler-channel&gt;</t>
3396                            </list>
3397                        </t>
3398                        <t>Where &lt;sampler-channel&gt; is the respective sampler channel
3399                        number as returned by the <xref target="ADD CHANNEL">"ADD CHANNEL"</xref>
3400                        or <xref target="LIST CHANNELS">"LIST CHANNELS"</xref> command.</t>
3401    
3402                        <t>Possible Answers:</t>
3403                        <t>
3404                            <list>
3405                                <t>The sampler will answer by returning a comma separated list
3406                                with all effect sends' numerical IDs on the given sampler
3407                                channel.</t>
3408                            </list>
3409                        </t>
3410    
3411                        <t>Examples:</t>
3412                        <t>
3413                            <list>
3414                                <t>C: "LIST FX_SENDS 0"</t>
3415                                <t>S: "0,1"</t>
3416                            </list>
3417                        </t>
3418                        <t>
3419                            <list>
3420                                <t>C: "LIST FX_SENDS 1"</t>
3421                                <t>S: ""</t>
3422                            </list>
3423                        </t>
3424                    </section>
3425    
3426                    <section title="Getting effect send information" anchor="GET FX_SEND INFO">
3427                        <t>The front-end can ask for the current settings of an effect send entity
3428                        by sending the following command:</t>
3429                        <t>
3430                            <list>
3431                                <t>GET FX_SEND INFO &lt;sampler-channel&gt; &lt;fx-send-id&gt;</t>
3432                            </list>
3433                        </t>
3434                        <t>Where &lt;sampler-channel&gt; is the sampler channel number
3435                        as returned by the <xref target="ADD CHANNEL">"ADD CHANNEL"</xref>
3436                        or <xref target="LIST CHANNELS">"LIST CHANNELS"</xref> command and
3437                        &lt;fx-send-id&gt; reflects the numerical ID of the effect send entity
3438                        as returned by the <xref target="CREATE FX_SEND">"CREATE FX_SEND"</xref>
3439                        or <xref target="LIST FX_SENDS">"LIST FX_SENDS"</xref> command.
3440                       </t>
3441    
3442                        <t>Possible Answers:</t>
3443                        <t>
3444                            <list>
3445                                <t>The sampler will answer by sending a &lt;CRLF&gt; separated list.
3446                                Each answer line begins with the settings category name
3447                                followed by a colon and then a space character &lt;SP&gt; and finally
3448                                the info character string to that setting category. At the
3449                                moment the following categories are defined:</t>
3450    
3451                                <t>
3452                                    <list>
3453                                        <t>NAME -
3454                                            <list>
3455                                                <t>name of the effect send entity
3456                                                (note that this character string may contain
3457                                                 <xref target="character_set">escape sequences</xref>)</t>
3458                                            </list>
3459                                        </t>
3460                                        <t>MIDI_CONTROLLER -
3461                                            <list>
3462                                                <t>a value between 0 and 127 reflecting the MIDI controller
3463                                                which is able to modify the effect send's send level</t>
3464                                            </list>
3465                                        </t>
3466                                        <t>LEVEL -
3467                                            <list>
3468                                                <t>optionally dotted number reflecting the effect send's
3469                                                current send level (where a value &lt; 1.0 means attenuation
3470                                                and a value > 1.0 means amplification)</t>
3471                                            </list>
3472                                        </t>
3473                                        <t>AUDIO_OUTPUT_ROUTING -
3474                                            <list>
3475                                                <t>comma separated list which reflects to which audio
3476                                                channel of the selected audio output device each
3477                                                effect send output channel is routed to, e.g. "0,3" would
3478                                                mean the effect send's output channel 0 is routed to channel
3479                                                0 of the audio output device and the effect send's output
3480                                                channel 1 is routed to the channel 3 of the audio
3481                                                output device (see
3482                                                <xref target="SET FX_SEND AUDIO_OUTPUT_CHANNEL">"SET FX_SEND AUDIO_OUTPUT_CHANNEL"</xref>
3483                                                for details)</t>
3484                                            </list>
3485                                        </t>
3486                                    </list>
3487                                </t>
3488                            </list>
3489                        </t>
3490                        <t>The mentioned fields above don't have to be in particular order.</t>
3491    
3492                        <t>Example:</t>
3493                        <t>
3494                            <list>
3495                                <t>C: "GET FX_SEND INFO 0 0"</t>
3496                                <t>S: "NAME: Reverb Send"</t>
3497                                <t>&nbsp;&nbsp;&nbsp;"MIDI_CONTROLLER: 91"</t>
3498                                <t>&nbsp;&nbsp;&nbsp;"LEVEL: 0.3"</t>
3499                                <t>&nbsp;&nbsp;&nbsp;"AUDIO_OUTPUT_ROUTING: 2,3"</t>
3500                                <t>&nbsp;&nbsp;&nbsp;"."</t>
3501                            </list>
3502                        </t>
3503                    </section>
3504    
3505                    <section title="Changing effect send's name" anchor="SET FX_SEND NAME">
3506                        <t>The front-end can alter the current name of an effect
3507                        send entity by sending the following command:</t>
3508                        <t>
3509                            <list>
3510                                <t>SET FX_SEND NAME &lt;sampler-chan&gt; &lt;fx-send-id&gt; &lt;name&gt;</t>
3511                            </list>
3512                        </t>
3513                        <t>Where &lt;sampler-chan&gt; is the sampler channel number
3514                        as returned by the <xref target="ADD CHANNEL">"ADD CHANNEL"</xref>
3515                        or <xref target="LIST CHANNELS">"LIST CHANNELS"</xref> command,
3516                        &lt;fx-send-id&gt; reflects the numerical ID of the effect send entity
3517                        as returned by the <xref target="CREATE FX_SEND">"CREATE FX_SEND"</xref>
3518                        or <xref target="LIST FX_SENDS">"LIST FX_SENDS"</xref> command and
3519                        &lt;name&gt; is the new name of the effect send entity, which
3520                        does not have to be unique (name MUST be encapsulated into apostrophes
3521                        and supports escape sequences as described in chapter
3522                        "<xref target="character_set">Character Set and Escape Sequences</xref>").
3523                        </t>
3524    
3525                        <t>Possible Answers:</t>
3526                        <t>
3527                            <list>
3528                                <t>"OK" -
3529                                    <list>
3530                                        <t>on success</t>
3531                                    </list>
3532                                </t>
3533                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
3534                                    <list>
3535                                        <t>in case it failed, providing an appropriate error code and error message</t>
3536                                    </list>
3537                                </t>
3538                            </list>
3539                        </t>
3540                        <t>Example:</t>
3541                        <t>
3542                            <list>
3543                                <t>C: "SET FX_SEND NAME 0 0 'Fx Send 1'"</t>
3544                                <t>S: "OK"</t>
3545                            </list>
3546                        </t>
3547                    </section>
3548    
3549                    <section title="Altering effect send's audio routing" anchor="SET FX_SEND AUDIO_OUTPUT_CHANNEL">
3550                        <t>The front-end can alter the destination of an effect send's audio channel on a specific
3551                        sampler channel by sending the following command:</t>
3552                        <t>
3553                            <list>
3554                                <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>
3555                            </list>
3556                        </t>
3557                        <t>Where &lt;sampler-chan&gt; is the sampler channel number
3558                        as returned by the <xref target="ADD CHANNEL">"ADD CHANNEL"</xref>
3559                        or <xref target="LIST CHANNELS">"LIST CHANNELS"</xref> command,
3560                        &lt;fx-send-id&gt; reflects the numerical ID of the effect send entity
3561                        as returned by the <xref target="CREATE FX_SEND">"CREATE FX_SEND"</xref>
3562                        or <xref target="LIST FX_SENDS">"LIST FX_SENDS"</xref> command,
3563                        &lt;audio-src&gt; is the numerical ID of the effect send's audio channel
3564                        which should be rerouted and &lt;audio-dst&gt; is the numerical ID of
3565                        the audio channel of the selected audio output device where &lt;audio-src&gt;
3566                        should be routed to.</t>
3567    
3568                        <t>Note that effect sends can only route audio to the same audio output
3569                        device as assigned to the effect send's sampler channel. Also note that an
3570                        effect send entity does always have exactly as much audio channels as its
3571                        sampler channel. So if the sampler channel is stereo, the effect send does
3572                        have two audio channels as well. Also keep in mind that the amount of audio
3573                        channels on a sampler channel might be dependant not only to the deployed
3574                        sampler engine on the sampler channel, but also dependant to the instrument
3575                        currently loaded. However you can (effectively) turn an i.e. stereo effect
3576                        send into a mono one by simply altering its audio routing appropriately.</t>
3577    
3578                        <t>Possible Answers:</t>
3579                        <t>
3580                            <list>
3581                                <t>"OK" -
3582                                    <list>
3583                                        <t>on success</t>
3584                                    </list>
3585                                </t>
3586                                <t>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
3587                                    <list>
3588                                        <t>if audio output channel was set, but there are noteworthy
3589                                        issue(s) related, providing an appropriate warning code and
3590                                        warning message</t>
3591                                    </list>
3592                                </t>
3593                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
3594                                    <list>
3595                                        <t>in case it failed, providing an appropriate error code and error message</t>
3596                                    </list>
3597                                </t>
3598                            </list>
3599                        </t>
3600                        <t>Example:</t>
3601                        <t>
3602                            <list>
3603                                <t>C: "SET FX_SEND AUDIO_OUTPUT_CHANNEL 0 0 0 2"</t>
3604                                <t>S: "OK"</t>
3605                            </list>
3606                        </t>
3607                    </section>
3608    
3609                    <section title="Altering effect send's MIDI controller" anchor="SET FX_SEND MIDI_CONTROLLER">
3610                        <t>The front-end can alter the MIDI controller of an effect
3611                        send entity by sending the following command:</t>
3612                        <t>
3613                            <list>
3614                                <t>SET FX_SEND MIDI_CONTROLLER &lt;sampler-chan&gt; &lt;fx-send-id&gt; &lt;midi-ctrl&gt;</t>
3615                            </list>
3616                        </t>
3617                        <t>Where &lt;sampler-chan&gt; is the sampler channel number
3618                        as returned by the <xref target="ADD CHANNEL">"ADD CHANNEL"</xref>
3619                        or <xref target="LIST CHANNELS">"LIST CHANNELS"</xref> command,
3620                        &lt;fx-send-id&gt; reflects the numerical ID of the effect send entity
3621                        as returned by the <xref target="CREATE FX_SEND">"CREATE FX_SEND"</xref>
3622                        or <xref target="LIST FX_SENDS">"LIST FX_SENDS"</xref> command and
3623                        &lt;midi-ctrl&gt; reflects the MIDI controller which shall be
3624                        able to modify the effect send's send level.</t>
3625    
3626                        <t>Possible Answers:</t>
3627                        <t>
3628                            <list>
3629                                <t>"OK" -
3630                                    <list>
3631                                        <t>on success</t>
3632                                    </list>
3633                                </t>
3634                                <t>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
3635                                    <list>
3636                                        <t>if MIDI controller was set, but there are noteworthy
3637                                        issue(s) related, providing an appropriate warning code and
3638                                        warning message</t>
3639                                    </list>
3640                                </t>
3641                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
3642                                    <list>
3643                                        <t>in case it failed, providing an appropriate error code and error message</t>
3644                                    </list>
3645                                </t>
3646                            </list>
3647                        </t>
3648                        <t>Example:</t>
3649                        <t>
3650                            <list>
3651                                <t>C: "SET FX_SEND MIDI_CONTROLLER 0 0 91"</t>
3652                                <t>S: "OK"</t>
3653                            </list>
3654                        </t>
3655                    </section>
3656    
3657                    <section title="Altering effect send's send level" anchor="SET FX_SEND LEVEL">
3658                        <t>The front-end can alter the current send level of an effect
3659                        send entity by sending the following command:</t>
3660                        <t>
3661                            <list>
3662                                <t>SET FX_SEND LEVEL &lt;sampler-chan&gt; &lt;fx-send-id&gt; &lt;volume&gt;</t>
3663                            </list>
3664                        </t>
3665                        <t>Where &lt;sampler-chan&gt; is the sampler channel number
3666                        as returned by the <xref target="ADD CHANNEL">"ADD CHANNEL"</xref>
3667                        or <xref target="LIST CHANNELS">"LIST CHANNELS"</xref> command,
3668                        &lt;fx-send-id&gt; reflects the numerical ID of the effect send entity
3669                        as returned by the <xref target="CREATE FX_SEND">"CREATE FX_SEND"</xref>
3670                        or <xref target="LIST FX_SENDS">"LIST FX_SENDS"</xref> command and
3671                        &lt;volume&gt; is an optionally dotted positive number (a value
3672                        smaller than 1.0 means attenuation, whereas a value greater than
3673                        1.0 means amplification) reflecting the new send level.</t>
3674    
3675                        <t>Possible Answers:</t>
3676                        <t>
3677                            <list>
3678                                <t>"OK" -
3679                                    <list>
3680                                        <t>on success</t>
3681                                    </list>
3682                                </t>
3683                                <t>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
3684                                    <list>
3685                                        <t>if new send level was set, but there are noteworthy
3686                                        issue(s) related, providing an appropriate warning code and
3687                                        warning message</t>
3688                                    </list>
3689                                </t>
3690                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
3691                                    <list>
3692                                        <t>in case it failed, providing an appropriate error code and error message</t>
3693                                    </list>
3694                                </t>
3695                            </list>
3696                        </t>
3697                        <t>Example:</t>
3698                        <t>
3699                            <list>
3700                                <t>C: "SET FX_SEND LEVEL 0 0 0.15"</t>
3701                                <t>S: "OK"</t>
3702                            </list>
3703                        </t>
3704                    </section>
3705    
3706                  <section title="Resetting a sampler channel" anchor="RESET CHANNEL">                  <section title="Resetting a sampler channel" anchor="RESET CHANNEL">
3707                      <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>
3708                      <t>                      <t>
# Line 3448  Schoenebeck'> Line 3924  Schoenebeck'>
3924                      </t>                      </t>
3925                  </section>                  </section>
3926    
3927                    <section title="Current number of active disk streams" anchor="GET TOTAL_STREAM_COUNT">
3928                        <t>The front-end can ask for the current number of active disk streams on
3929                        the sampler by sending the following command:</t>
3930                        <t>
3931                            <list>
3932                                <t>GET TOTAL_STREAM_COUNT</t>
3933                            </list>
3934                        </t>
3935    
3936                        <t>Possible Answers:</t>
3937                        <t>
3938                            <list>
3939                                <t>LinuxSampler will answer by returning the number of all active
3940                                disk streams on the sampler.</t>
3941                            </list>
3942                        </t>
3943                    </section>
3944    
3945                  <section title="Reset sampler" anchor="RESET">                  <section title="Reset sampler" anchor="RESET">
3946                      <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>
3947                      <t>                      <t>
# Line 3495  Schoenebeck'> Line 3989  Schoenebeck'>
3989                                  <list>                                  <list>
3990                                      <t>DESCRIPTION -                                      <t>DESCRIPTION -
3991                                          <list>                                          <list>
3992                                              <t>arbitrary textual description about the sampler</t>                                              <t>arbitrary textual description about the sampler
3993                                                (note that the character string may contain
3994                                                <xref target="character_set">escape sequences</xref>)</t>
3995                                          </list>                                          </list>
3996                                      </t>                                      </t>
3997                                      <t>VERSION -                                      <t>VERSION -
# Line 3509  Schoenebeck'> Line 4005  Schoenebeck'>
4005                                              complies with (see <xref target="LSCP versioning" /> for details)</t>                                              complies with (see <xref target="LSCP versioning" /> for details)</t>
4006                                          </list>                                          </list>
4007                                      </t>                                      </t>
4008                                        <t>INSTRUMENTS_DB_SUPPORT -
4009                                            <list>
4010                                                <t>either yes or no, specifies whether the
4011                                                sampler is build with instruments database support.</t>
4012                                            </list>
4013                                        </t>
4014                                  </list>                                  </list>
4015                              </t>                              </t>
4016                          </list>                          </list>
# Line 3516  Schoenebeck'> Line 4018  Schoenebeck'>
4018                      <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.
4019                      Other fields might be added in future.</t>                      Other fields might be added in future.</t>
4020                  </section>                  </section>
4021    
4022                    <section title="Getting global volume attenuation" anchor="GET VOLUME">
4023                        <t>The client can ask for the current global sampler-wide volume
4024                        attenuation by sending the following command:</t>
4025                        <t>
4026                            <list>
4027                                <t>GET VOLUME</t>
4028                            </list>
4029                        </t>
4030                        <t>Possible Answers:</t>
4031                        <t>
4032                            <list>
4033                                <t>The sampler will always answer by returning the optional
4034                                dotted floating point coefficient, reflecting the current
4035                                global volume attenuation.
4036                                </t>
4037                            </list>
4038                        </t>
4039                        <t>Note: it is up to the respective sampler engine whether to obey
4040                        that global volume parameter or not, but in general all engines SHOULD
4041                        use this parameter.</t>
4042                    </section>
4043    
4044                    <section title="Setting global volume attenuation" anchor="SET VOLUME">
4045                        <t>The client can alter the current global sampler-wide volume
4046                        attenuation by sending the following command:</t>
4047                        <t>
4048                            <list>
4049                                <t>SET VOLUME &lt;volume&gt;</t>
4050                            </list>
4051                        </t>
4052                       <t>Where &lt;volume&gt; should be replaced by the optional dotted
4053                       floating point value, reflecting the new global volume parameter.
4054                       This value might usually be in the range between 0.0 and 1.0, that
4055                       is for attenuating the overall volume.</t>
4056    
4057                        <t>Possible Answers:</t>
4058                        <t>
4059                            <list>
4060                                <t>"OK" -
4061                                    <list>
4062                                        <t>on success</t>
4063                                    </list>
4064                                </t>
4065                                <t>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
4066                                    <list>
4067                                        <t>if the global volume was set, but there are noteworthy
4068                                        issue(s) related, providing an appropriate warning code and
4069                                        warning message</t>
4070                                    </list>
4071                                </t>
4072                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
4073                                    <list>
4074                                        <t>in case it failed, providing an appropriate error code and error message</t>
4075                                    </list>
4076                                </t>
4077                            </list>
4078                        </t>
4079                    </section>
4080              </section>              </section>
4081    
4082    
# Line 3546  Schoenebeck'> Line 4107  Schoenebeck'>
4107                  cause the sampler to switch to the respective instrument as                  cause the sampler to switch to the respective instrument as
4108                  reflected by the current MIDI instrument map.</t>                  reflected by the current MIDI instrument map.</t>
4109    
4110                  <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">
4111                      <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
4112                      the following command:</t>                      the following command:</t>
4113                      <t>                      <t>
# Line 3556  Schoenebeck'> Line 4117  Schoenebeck'>
4117                      </t>                      </t>
4118                      <t>Where &lt;name&gt; is an optional argument allowing to                      <t>Where &lt;name&gt; is an optional argument allowing to
4119                      assign a custom name to the new map. MIDI instrument Map                      assign a custom name to the new map. MIDI instrument Map
4120                      names do not have to be unique.</t>                      names do not have to be unique, but MUST be encapsulated
4121                        into apostrophes and support escape sequences as described
4122                        in chapter "<xref target="character_set">Character Set and Escape Sequences</xref>".
4123                        </t>
4124    
4125                      <t>Possible Answers:</t>                      <t>Possible Answers:</t>
4126                      <t>                      <t>
# Line 3727  Schoenebeck'> Line 4291  Schoenebeck'>
4291                                      <t>NAME -                                      <t>NAME -
4292                                          <list>                                          <list>
4293                                              <t>custom name of the given map,                                              <t>custom name of the given map,
4294                                              which does not have to be unique</t>                                              which does not have to be unique
4295                                                (note that this character string may contain
4296                                                 <xref target="character_set">escape sequences</xref>)</t>
4297                                            </list>
4298                                        </t>
4299                                        <t>DEFAULT -
4300                                            <list>
4301                                                <t>either true or false,
4302                                                defines whether this map is the default map</t>
4303                                          </list>                                          </list>
4304                                      </t>                                      </t>
4305                                  </list>                                  </list>
# Line 3741  Schoenebeck'> Line 4313  Schoenebeck'>
4313                          <list>                          <list>
4314                              <t>C: "GET MIDI_INSTRUMENT_MAP INFO 0"</t>                              <t>C: "GET MIDI_INSTRUMENT_MAP INFO 0"</t>
4315                              <t>S: "NAME: Standard Map"</t>                              <t>S: "NAME: Standard Map"</t>
4316                                <t>&nbsp;&nbsp;&nbsp;"DEFAULT: true"</t>
4317                              <t>&nbsp;&nbsp;&nbsp;"."</t>                              <t>&nbsp;&nbsp;&nbsp;"."</t>
4318                          </list>                          </list>
4319                      </t>                      </t>
# Line 3756  Schoenebeck'> Line 4329  Schoenebeck'>
4329                      </t>                      </t>
4330                      <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
4331                      &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
4332                      have to be unique.</t>                      have to be unique (name MUST be encapsulated into apostrophes
4333                        and supports escape sequences as described in chapter
4334                        "<xref target="character_set">Character Set and Escape Sequences</xref>").
4335                        </t>
4336    
4337                      <t>Possible Answers:</t>                      <t>Possible Answers:</t>
4338                      <t>                      <t>
# Line 3789  Schoenebeck'> Line 4365  Schoenebeck'>
4365                      command:</t>                      command:</t>
4366                      <t>                      <t>
4367                          <list>                          <list>
4368                              <t>MAP MIDI_INSTRUMENT &lt;map&gt;                              <t>MAP MIDI_INSTRUMENT [NON_MODAL] &lt;map&gt;
4369                              &lt;midi_bank&gt; &lt;midi_prog&gt; &lt;engine_name&gt;                              &lt;midi_bank&gt; &lt;midi_prog&gt; &lt;engine_name&gt;
4370                              &lt;filename&gt; &lt;instrument_index&gt; &lt;volume_value&gt;                              &lt;filename&gt; &lt;instrument_index&gt; &lt;volume_value&gt;
4371                              [&lt;instr_load_mode&gt;] [&lt;name&gt;]</t>                              [&lt;instr_load_mode&gt;] [&lt;name&gt;]</t>
# Line 3803  Schoenebeck'> Line 4379  Schoenebeck'>
4379                      index, &lt;engine_name&gt; a sampler engine name as returned by                      index, &lt;engine_name&gt; a sampler engine name as returned by
4380                      the <xref target="LIST AVAILABLE_ENGINES">"LIST AVAILABLE_ENGINES"</xref>                      the <xref target="LIST AVAILABLE_ENGINES">"LIST AVAILABLE_ENGINES"</xref>
4381                      command (not encapsulated into apostrophes), &lt;filename&gt; the name                      command (not encapsulated into apostrophes), &lt;filename&gt; the name
4382                      of the instrument's file to be deployed (encapsulated into apostrophes),                      of the instrument's file to be deployed (encapsulated into apostrophes,
4383                        supporting escape sequences as described in chapter
4384                        "<xref target="character_set">Character Set and Escape Sequences</xref>"),
4385                      &lt;instrument_index&gt; the index (integer value) of the instrument                      &lt;instrument_index&gt; the index (integer value) of the instrument
4386                      within the given file, &lt;volume_value&gt; reflects the master                      within the given file, &lt;volume_value&gt; reflects the master
4387                      volume of the instrument as optionally dotted number (where a                      volume of the instrument as optionally dotted number (where a
4388                      value < 1.0 means attenuation and a value > 1.0 means                      value &lt; 1.0 means attenuation and a value > 1.0 means
4389                      amplification). This parameter easily allows to adjust the                      amplification). This parameter easily allows to adjust the
4390                      volume of all intruments within a custom instrument map                      volume of all intruments within a custom instrument map
4391                      without having to adjust their instrument files. The                      without having to adjust their instrument files. The
# Line 3842  Schoenebeck'> Line 4420  Schoenebeck'>
4420                              <t>"PERSISTENT" -                              <t>"PERSISTENT" -
4421                                  <list>                                  <list>
4422                                      <t>The instrument will immediately be loaded                                      <t>The instrument will immediately be loaded
4423                                      into memory in the background when this mapping                                      into memory when this mapping
4424                                      command is sent and the instrument is kept all                                      command is sent and the instrument is kept all
4425                                      the time. Instruments with this mode are                                      the time. Instruments with this mode are
4426                                      only freed when the sampler is reset or all                                      only freed when the sampler is reset or all
# Line 3885  Schoenebeck'> Line 4463  Schoenebeck'>
4463                      load modes of entries, the frontend should retrieve the actual                      load modes of entries, the frontend should retrieve the actual
4464                      mode by i.e. sending                      mode by i.e. sending
4465                      <xref target="GET MIDI_INSTRUMENT INFO">"GET MIDI_INSTRUMENT INFO"</xref>                      <xref target="GET MIDI_INSTRUMENT INFO">"GET MIDI_INSTRUMENT INFO"</xref>
4466                      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
4467                      set a custom name (encapsulated into apostrophes) for the mapping                      (encapsulated into apostrophes, supporting escape sequences as described in chapter
4468                      entry, useful for frontends for displaying an appropriate name for                      "<xref target="character_set">Character Set and Escape Sequences</xref>") for the
4469                        mapping entry, useful for frontends for displaying an appropriate name for
4470                      mapped instruments (using                      mapped instruments (using
4471                      <xref target="GET MIDI_INSTRUMENT INFO">"GET MIDI_INSTRUMENT INFO"</xref>).                      <xref target="GET MIDI_INSTRUMENT INFO">"GET MIDI_INSTRUMENT INFO"</xref>).
4472                      </t>                      </t>
4473                      <t>                      <t>
4474                      The "MAP MIDI_INSTRUMENT" command                      By default, "MAP MIDI_INSTRUMENT" commands block until the mapping is
4475                      will immediately return, thus it will not block when an                      completely established in the sampler. The OPTIONAL "NON_MODAL" argument
4476                      instrument is to be loaded due to a "PERSISTENT" type                      however causes the respective "MAP MIDI_INSTRUMENT" command to return
4477                      entry as instruments are loaded in the background. As a                      immediately, that is to let the sampler establish the mapping in the
4478                      consequence this command may not necessarily return an error                      background. So this argument might be especially useful for mappings with
4479                      i.e. when the given instrument file does not exist or may                      a "PERSISTENT" type, because these have to load the respective instruments
4480                      turn out to be corrupt.                      immediately and might thus block for a very long time. It is recommended
4481                        however to use the OPTIONAL "NON_MODAL" argument only if really necessary,
4482                        because it has the following drawbacks: as "NON_MODAL" instructions return
4483                        immediately, they may not necessarily return an error i.e. when the given
4484                        instrument file turns out to be corrupt, beside that subsequent commands
4485                        in a LSCP instruction sequence might fail, because mandatory mappings are
4486                        not yet completed.
4487                      </t>                      </t>
4488    
4489                      <t>Possible Answers:</t>                      <t>Possible Answers:</t>
# Line 3941  Schoenebeck'> Line 4526  Schoenebeck'>
4526                      </t>                      </t>
4527                      <t>                      <t>
4528                          <list>                          <list>
4529                              <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>
4530                              <t>S: "OK"</t>                              <t>S: "OK"</t>
4531                          </list>                          </list>
4532                      </t>                      </t>
# Line 4105  Schoenebeck'> Line 4690  Schoenebeck'>
4690                                      name for this mapped instrument. It can be set and                                      name for this mapped instrument. It can be set and
4691                                      changed with the                                      changed with the
4692                                      <xref target="MAP MIDI_INSTRUMENT">"MAP MIDI_INSTRUMENT"</xref>                                      <xref target="MAP MIDI_INSTRUMENT">"MAP MIDI_INSTRUMENT"</xref>
4693                                      command and does not have to be unique.</t>                                      command and does not have to be unique.
4694                                        (note that this character string may contain
4695                                        <xref target="character_set">escape sequences</xref>)</t>
4696                                  </list>                                  </list>
4697                              </t>                              </t>
4698                              <t>"ENGINE_NAME" -                              <t>"ENGINE_NAME" -
# Line 4116  Schoenebeck'> Line 4703  Schoenebeck'>
4703                              </t>                              </t>
4704                              <t>"INSTRUMENT_FILE" -                              <t>"INSTRUMENT_FILE" -
4705                                  <list>                                  <list>
4706                                      <t>File name of the instrument.</t>                                      <t>File name of the instrument
4707                                        (note that this path may contain
4708                                        <xref target="character_set">escape sequences</xref>).</t>
4709                                  </list>                                  </list>
4710                              </t>                              </t>
4711                              <t>"INSTRUMENT_NR" -                              <t>"INSTRUMENT_NR" -
# Line 4128  Schoenebeck'> Line 4717  Schoenebeck'>
4717                                  <list>                                  <list>
4718                                      <t>Name of the loaded instrument as reflected by its file.                                      <t>Name of the loaded instrument as reflected by its file.
4719                                      In contrast to the "NAME" field, the "INSTRUMENT_NAME" field                                      In contrast to the "NAME" field, the "INSTRUMENT_NAME" field
4720                                      cannot be changed.</t>                                      cannot be changed (note that this character string may contain
4721                                        <xref target="character_set">escape sequences</xref>).</t>
4722                                  </list>                                  </list>
4723                              </t>                              </t>
4724                              <t>"LOAD_MODE" -                              <t>"LOAD_MODE" -
# Line 4140  Schoenebeck'> Line 4730  Schoenebeck'>
4730                              <t>"VOLUME" -                              <t>"VOLUME" -
4731                                  <list>                                  <list>
4732                                      <t>master volume of the instrument as optionally                                      <t>master volume of the instrument as optionally
4733                                      dotted number (where a value < 1.0 means attenuation                                      dotted number (where a value &lt; 1.0 means attenuation
4734                                      and a value > 1.0 means amplification)</t>                                      and a value > 1.0 means amplification)</t>
4735                                  </list>                                  </list>
4736                              </t>                              </t>
# Line 4212  Schoenebeck'> Line 4802  Schoenebeck'>
4802                  </section>                  </section>
4803              </section>              </section>
4804    
4805    
4806                <section title="Managing Instruments Database" anchor="Managing Instruments Database">
4807                    <t>The following commands describe how to use and manage
4808                    the instruments database.</t>
4809                    <t>Notice:</t>
4810                        <t>
4811                            <list>
4812                                <t>All command arguments representing a path or
4813                                instrument/directory name support escape sequences as described in chapter
4814                                "<xref target="character_set">Character Set and Escape Sequences</xref>".
4815                                </t>
4816                                <t>All occurrences of a forward slash in instrument and directory
4817                                   names are escaped with its hex (\x2f) or octal (\057) escape sequence.
4818                                </t>
4819                            </list>
4820                        </t>
4821    
4822                    <section title="Creating a new instrument directory" anchor="ADD DB_INSTRUMENT_DIRECTORY">
4823                        <t>The front-end can add a new instrument directory to the
4824                        instruments database by sending the following command:</t>
4825                        <t>
4826                            <list>
4827                                <t>ADD DB_INSTRUMENT_DIRECTORY &lt;dir&gt;</t>
4828                            </list>
4829                        </t>
4830                        <t>Where &lt;dir&gt; is the absolute path name of the directory
4831                        to be created (encapsulated into apostrophes).</t>
4832    
4833                        <t>Possible Answers:</t>
4834                        <t>
4835                            <list>
4836                                <t>"OK" -
4837                                    <list>
4838                                        <t>on success</t>
4839                                    </list>
4840                                </t>
4841                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
4842                                    <list>
4843                                        <t>when the directory could not be created, which
4844                                        can happen if the directory already exists or the
4845                                        name contains not allowed symbols</t>
4846                                    </list>
4847                                </t>
4848                            </list>
4849                        </t>
4850    
4851                        <t>Examples:</t>
4852                        <t>
4853                            <list>
4854                                <t>C: "ADD DB_INSTRUMENT_DIRECTORY '/Piano Collection'"</t>
4855                                <t>S: "OK"</t>
4856                            </list>
4857                        </t>
4858                    </section>
4859    
4860                    <section title="Deleting an instrument directory" anchor="REMOVE DB_INSTRUMENT_DIRECTORY">
4861                        <t>The front-end can delete a particular instrument directory
4862                        from the instruments database by sending the following command:</t>
4863                        <t>
4864                            <list>
4865                                <t>REMOVE DB_INSTRUMENT_DIRECTORY [FORCE] &lt;dir&gt;</t>
4866                            </list>
4867                        </t>
4868                        <t>Where &lt;dir&gt; is the absolute path name of the directory
4869                        to delete. The optional FORCE argument can be used to
4870                        force the deletion of a non-empty directory and all its content.</t>
4871    
4872                        <t>Possible Answers:</t>
4873                        <t>
4874                            <list>
4875                                <t>"OK" -
4876                                    <list>
4877                                        <t>if the directory is deleted successfully</t>
4878                                    </list>
4879                                </t>
4880                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
4881                                    <list>
4882                                        <t>if the given directory does not exist, or
4883                                        if trying to delete a non-empty directory,
4884                                        without using the FORCE argument.</t>
4885                                    </list>
4886                                </t>
4887                            </list>
4888                        </t>
4889    
4890                        <t>Examples:</t>
4891                        <t>
4892                            <list>
4893                                <t>C: "REMOVE DB_INSTRUMENT_DIRECTORY FORCE '/Piano Collection'"</t>
4894                                <t>S: "OK"</t>
4895                            </list>
4896                        </t>
4897                    </section>
4898    
4899                    <section title="Getting amount of instrument directories" anchor="GET DB_INSTRUMENT_DIRECTORIES">
4900                        <t>The front-end can retrieve the current amount of
4901                        directories in a specific directory by sending the following command:</t>
4902                        <t>
4903                            <list>
4904                                <t>GET DB_INSTRUMENT_DIRECTORIES [RECURSIVE] &lt;dir&gt;</t>
4905                            </list>
4906                        </t>
4907                        <t>Where &lt;dir&gt; should be replaced by the absolute path
4908                        name of the directory. If RECURSIVE is specified, the number of
4909                        all directories, including those located in subdirectories of the
4910                        specified directory, will be returned.</t>
4911    
4912                        <t>Possible Answers:</t>
4913                        <t>
4914                            <list>
4915                                <t>The current number of instrument directories
4916                                in the specified directory.</t>
4917                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
4918                                    <list>
4919                                        <t>if the given directory does not exist.</t>
4920                                    </list>
4921                                </t>
4922                            </list>
4923                        </t>
4924    
4925                        <t>Example:</t>
4926                        <t>
4927                            <list>
4928                                <t>C: "GET DB_INSTRUMENT_DIRECTORIES '/'"</t>
4929                                <t>S: "2"</t>
4930                            </list>
4931                        </t>
4932                    </section>
4933    
4934                    <section title="Listing all directories in specific directory" anchor="LIST DB_INSTRUMENT_DIRECTORIES">
4935                        <t>The front-end can retrieve the current list of directories
4936                        in specific directory by sending the following command:</t>
4937                        <t>
4938                            <list>
4939                                <t>LIST DB_INSTRUMENT_DIRECTORIES [RECURSIVE] &lt;dir&gt;</t>
4940                            </list>
4941                        </t>
4942                        <t>Where &lt;dir&gt; should be replaced by the absolute path
4943                        name of the directory. If RECURSIVE is specified, the absolute path names
4944                        of all directories, including those located in subdirectories of the
4945                        specified directory, will be returned.</t>
4946    
4947                        <t>Possible Answers:</t>
4948                        <t>
4949                            <list>
4950                                <t>A comma separated list of all instrument directories
4951                                (encapsulated into apostrophes) in the specified directory.</t>
4952                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
4953                                    <list>
4954                                        <t>if the given directory does not exist.</t>
4955                                    </list>
4956                                </t>
4957                            </list>
4958                        </t>
4959                        <t>Example:</t>
4960                        <t>
4961                            <list>
4962                                <t>C: "LIST DB_INSTRUMENT_DIRECTORIES '/'"</t>
4963                                <t>S: "'Piano Collection','Percussion Collection'"</t>
4964                            </list>
4965                        </t>
4966                        <t>
4967                            <list>
4968                                <t>C: "LIST DB_INSTRUMENT_DIRECTORIES RECURSIVE '/'"</t>
4969                                <t>S: "'/Piano Collection','/Piano Collection/Acoustic','/Piano Collection/Acoustic/New','/Percussion Collection'"</t>
4970                            </list>
4971                        </t>
4972                    </section>
4973    
4974                    <section title="Getting instrument directory information" anchor="GET DB_INSTRUMENT_DIRECTORY INFO">
4975                        <t>The front-end can ask for the current settings of an
4976                        instrument directory by sending the following command:</t>
4977                        <t>
4978                            <list>
4979                                <t>GET DB_INSTRUMENT_DIRECTORY INFO &lt;dir&gt;</t>
4980                            </list>
4981                        </t>
4982                        <t>Where &lt;dir&gt; should be replaced by the absolute path
4983                        name of the directory the front-end is interested in.</t>
4984    
4985                        <t>Possible Answers:</t>
4986                        <t>
4987                            <list>
4988                                <t>LinuxSampler will answer by sending a &lt;CRLF&gt; separated list.
4989                                Each answer line begins with the settings category name
4990                                followed by a colon and then a space character &lt;SP&gt; and finally
4991                                the info character string to that setting category. At the
4992                                moment the following categories are defined:</t>
4993    
4994                                <t>
4995                                    <list>
4996                                        <t>DESCRIPTION -
4997                                            <list>
4998                                                <t>A brief description of the directory content.
4999                                                Note that the character string may contain
5000                                                <xref target="character_set">escape sequences</xref>.</t>
5001                                            </list>
5002                                        </t>
5003                                        <t>CREATED -
5004                                            <list>
5005                                                <t>The creation date and time of the directory,
5006                                                represented in "YYYY-MM-DD HH:MM:SS" format</t>
5007                                            </list>
5008                                        </t>
5009                                        <t>MODIFIED -
5010                                            <list>
5011                                                <t>The date and time of the last modification of the
5012                                                directory, represented in "YYYY-MM-DD HH:MM:SS" format</t>
5013                                            </list>
5014                                        </t>
5015                                    </list>
5016                                </t>
5017                            </list>
5018                        </t>
5019                        <t>The mentioned fields above don't have to be in particular order.</t>
5020    
5021                        <t>Example:</t>
5022                        <t>
5023                            <list>
5024                                <t>C: "GET DB_INSTRUMENT_DIRECTORY INFO '/Piano Collection'"</t>
5025                                <t>S: "DESCRIPTION: Piano collection of instruments in GigaSampler format."</t>
5026                                <t>&nbsp;&nbsp;&nbsp;"CREATED: 2007-02-05 10:23:12"</t>
5027                                <t>&nbsp;&nbsp;&nbsp;"MODIFIED: 2007-04-07 12:50:21"</t>
5028                                <t>&nbsp;&nbsp;&nbsp;"."</t>
5029                            </list>
5030                        </t>
5031                    </section>
5032    
5033                    <section title="Renaming an instrument directory" anchor="SET DB_INSTRUMENT_DIRECTORY NAME">
5034                        <t>The front-end can alter the name of a specific
5035                        instrument directory by sending the following command:</t>
5036                        <t>
5037                            <list>
5038                                <t>SET DB_INSTRUMENT_DIRECTORY NAME &lt;dir&gt; &lt;name&gt;</t>
5039                            </list>
5040                        </t>
5041                        <t>Where &lt;dir&gt; is the absolute path name of the directory and
5042                        &lt;name&gt; is the new name for that directory.</t>
5043    
5044                        <t>Possible Answers:</t>
5045                        <t>
5046                            <list>
5047                                <t>"OK" -
5048                                    <list>
5049                                        <t>on success</t>
5050                                    </list>
5051                                </t>
5052                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
5053                                    <list>
5054                                        <t>in case the given directory does not exists,
5055                                        or if a directory with name equal to the new
5056                                        name already exists.</t>
5057                                    </list>
5058                                </t>
5059                            </list>
5060                        </t>
5061    
5062                        <t>Example:</t>
5063                        <t>
5064                            <list>
5065                                <t>C: "SET DB_INSTRUMENT_DIRECTORY NAME '/Piano Collection/Acustic' 'Acoustic'"</t>
5066                                <t>S: "OK"</t>
5067                            </list>
5068                        </t>
5069                    </section>
5070    
5071                    <section title="Moving an instrument directory" anchor="MOVE DB_INSTRUMENT_DIRECTORY">
5072                        <t>The front-end can move a specific
5073                        instrument directory by sending the following command:</t>
5074                        <t>
5075                            <list>
5076                                <t>MOVE DB_INSTRUMENT_DIRECTORY &lt;dir&gt; &lt;dst&gt;</t>
5077                            </list>
5078                        </t>
5079                        <t>Where &lt;dir&gt; is the absolute path name of the directory
5080                        to move and &lt;dst&gt; is the location where the directory will
5081                        be moved to.</t>
5082    
5083                        <t>Possible Answers:</t>
5084                        <t>
5085                            <list>
5086                                <t>"OK" -
5087                                    <list>
5088                                        <t>on success</t>
5089                                    </list>
5090                                </t>
5091                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
5092                                    <list>
5093                                        <t>in case a given directory does not exists,
5094                                        or if a directory with name equal to the name
5095                                        of the specified directory already exists in
5096                                        the destination directory. Error is also thrown
5097                                        when trying to move a directory to a subdirectory
5098                                        of itself.</t>
5099                                    </list>
5100                                </t>
5101                            </list>
5102                        </t>
5103    
5104                        <t>Example:</t>
5105                        <t>
5106                            <list>
5107                                <t>C: "MOVE DB_INSTRUMENT_DIRECTORY '/Acoustic' '/Piano Collection/Acoustic'"</t>
5108                                <t>S: "OK"</t>
5109                            </list>
5110                        </t>
5111                    </section>
5112    
5113                    <section title="Copying instrument directories" anchor="COPY DB_INSTRUMENT_DIRECTORY">
5114                        <t>The front-end can copy a specific
5115                        instrument directory by sending the following command:</t>
5116                        <t>
5117                            <list>
5118                                <t>COPY DB_INSTRUMENT_DIRECTORY &lt;dir&gt; &lt;dst&gt;</t>
5119                            </list>
5120                        </t>
5121                        <t>Where &lt;dir&gt; is the absolute path name of the directory
5122                        to copy and &lt;dst&gt; is the location where the directory will
5123                        be copied to.</t>
5124    
5125                        <t>Possible Answers:</t>
5126                        <t>
5127                            <list>
5128                                <t>"OK" -
5129                                    <list>
5130                                        <t>on success</t>
5131                                    </list>
5132                                </t>
5133                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
5134                                    <list>
5135                                        <t>in case a given directory does not exists,
5136                                        or if a directory with name equal to the name
5137                                        of the specified directory already exists in
5138                                        the destination directory. Error is also thrown
5139                                        when trying to copy a directory to a subdirectory
5140                                        of itself.</t>
5141                                    </list>
5142                                </t>
5143                            </list>
5144                        </t>
5145    
5146                        <t>Example:</t>
5147                        <t>
5148                            <list>
5149                                <t>C: "COPY DB_INSTRUMENT_DIRECTORY '/Piano Collection/Acoustic' '/Acoustic/Pianos'"</t>
5150                                <t>S: "OK"</t>
5151                            </list>
5152                        </t>
5153                    </section>
5154    
5155                    <section title="Changing the description of directory" anchor="SET DB_INSTRUMENT_DIRECTORY DESCRIPTION">
5156                        <t>The front-end can alter the description of a specific
5157                        instrument directory by sending the following command:</t>
5158                        <t>
5159                            <list>
5160                                <t>SET DB_INSTRUMENT_DIRECTORY DESCRIPTION &lt;dir&gt; &lt;desc&gt;</t>
5161                            </list>
5162                        </t>
5163                        <t>Where &lt;dir&gt; is the absolute path name of the directory and
5164                        &lt;desc&gt; is the new description for the directory
5165                        (encapsulated into apostrophes, supporting escape sequences as described in chapter
5166                        "<xref target="character_set">Character Set and Escape Sequences</xref>").</t>
5167    
5168                        <t>Possible Answers:</t>
5169                        <t>
5170                            <list>
5171                                <t>"OK" -
5172                                    <list>
5173                                        <t>on success</t>
5174                                    </list>
5175                                </t>
5176                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
5177                                    <list>
5178                                        <t>in case the given directory does not exists.</t>
5179                                    </list>
5180                                </t>
5181                            </list>
5182                        </t>
5183    
5184                        <t>Example:</t>
5185                        <t>
5186                            <list>
5187                                <t>C: "SET DB_INSTRUMENT_DIRECTORY DESCRIPTION '/Piano Collection' 'A collection of piano instruments in various format.'"</t>
5188                                <t>S: "OK"</t>
5189                            </list>
5190                        </t>
5191                    </section>
5192    
5193                    <section title="Finding directories" anchor="FIND DB_INSTRUMENT_DIRECTORIES">
5194                        <t>The front-end can search for directories
5195                        in specific directory by sending the following command:</t>
5196                        <t>
5197                            <list>
5198                                <t>FIND DB_INSTRUMENT_DIRECTORIES [NON_RECURSIVE] &lt;dir&gt; &lt;criteria-list&gt;</t>
5199                            </list>
5200                        </t>
5201                        <t>Where &lt;dir&gt; should be replaced by the absolute path
5202                        name of the directory to search in. If NON_RECURSIVE is specified, the
5203                        directories located in subdirectories of the specified directory will not
5204                        be searched. &lt;criteria-list&gt; is a list of search criterias
5205                        in form of "key1=val1 key2=val2 ...". The following criterias are
5206                        allowed:</t>
5207                        <t>
5208                          <t>NAME='&lt;search-string&gt;'
5209                              <list>
5210                                  <t>Restricts the search to directories, which names
5211                                  satisfy the supplied search string (encapsulated into apostrophes,
5212                                  supporting escape sequences as described in chapter
5213                                  "<xref target="character_set">Character Set and Escape Sequences</xref>").</t>
5214                              </list>
5215                          </t>
5216    
5217                          <t>CREATED='[&lt;date-after&gt;]..[&lt;date-before&gt;]'
5218                              <list>
5219                                  <t>Restricts the search to directories, which creation
5220                                  date satisfies the specified period, where &lt;date-after&gt;
5221                                  and &lt;date-before&gt; are in "YYYY-MM-DD HH:MM:SS" format.
5222                                  If &lt;date-after&gt; is omitted the search is restricted to
5223                                  directories created before &lt;date-before&gt;. If
5224                                  &lt;date-before&gt; is omitted, the search is restricted
5225                                  to directories created after &lt;date-after&gt;.</t>
5226                              </list>
5227                          </t>
5228    
5229                          <t>MODIFIED='[&lt;date-after&gt;]..[&lt;date-before&gt;]'
5230                              <list>
5231                                  <t>Restricts the search to directories, which
5232                                  date of last modification satisfies the specified period, where
5233                                  &lt;date-after&gt; and &lt;date-before&gt; are in "YYYY-MM-DD HH:MM:SS"
5234                                  format. If &lt;date-after&gt; is omitted the search is restricted to
5235                                  directories, which are last modified before &lt;date-before&gt;. If
5236                                  &lt;date-before&gt; is omitted, the search is restricted to directories,
5237                                  which are last modified after &lt;date-after&gt;.</t>
5238                              </list>
5239                          </t>
5240    
5241                          <t>DESCRIPTION='&lt;search-string&gt;'
5242                              <list>
5243                                  <t>Restricts the search to directories with description
5244                                  that satisfies the supplied search string
5245                                  (encapsulated into apostrophes, supporting escape
5246                                  sequences as described in chapter
5247                                  "<xref target="character_set">Character Set and Escape Sequences</xref>").</t>
5248                              </list>
5249                          </t>
5250                        </t>
5251    
5252                        <t>Where &lt;search-string&gt; is either a regular expression, or a
5253                        word list separated with spaces for OR search and with '+' for AND search.</t>
5254    
5255                        <t>Possible Answers:</t>
5256                        <t>
5257                            <list>
5258                                <t>A comma separated list with the absolute path names (encapsulated into
5259                                apostrophes) of all directories in the specified directory that satisfy
5260                                the supplied search criterias.</t>
5261                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
5262                                    <list>
5263                                        <t>if the given directory does not exist.</t>
5264                                    </list>
5265                                </t>
5266                            </list>
5267                        </t>
5268                        <t>Example:</t>
5269                        <t>
5270                            <list>
5271                                <t>C: "FIND DB_INSTRUMENT_DIRECTORIES '/' NAME='Piano'"</t>
5272                                <t>S: "'/Piano Collection'"</t>
5273                            </list>
5274                        </t>
5275                        <t>
5276                            <list>
5277                                <t>C: "FIND DB_INSTRUMENT_DIRECTORIES '/' CREATED='..2007-04-01 09:30:13'"</t>
5278                                <t>S: "'/Piano Collection','/Percussions'"</t>
5279                            </list>
5280                        </t>
5281                    </section>
5282    
5283                    <section title="Adding instruments to the instruments database" anchor="ADD DB_INSTRUMENTS">
5284                        <t>The front-end can add one or more instruments
5285                        to the instruments database by sending the following command:</t>
5286                        <t>
5287                            <list>
5288                                <t>ADD DB_INSTRUMENTS [NON_MODAL] [&lt;mode&gt;] &lt;db_dir&gt; &lt;file_path&gt; [&lt;instr_index&gt;]</t>
5289                            </list>
5290                        </t>
5291                        <t>Where &lt;db_dir&gt; is the absolute path name of a directory
5292                        (encapsulated into apostrophes) in the instruments database in which
5293                        only the new instruments (that are not already in the database) will
5294                        be added, &lt;file_path&gt; is the absolute path name of a file or
5295                        directory in the file system (encapsulated into apostrophes). In case
5296                        an instrument file is supplied, only the instruments in the specified
5297                        file will be added to the instruments database. If the optional
5298                        &lt;instr_index&gt; (the index of the instrument within the given file)
5299                        is supplied too, then only the specified instrument will be added.
5300                        In case a directory is supplied, the instruments in that directory
5301                        will be added. The OPTIONAL &lt;mode&gt; argument is only applied
5302                        when a directory is provided as &lt;file_path&gt; and specifies how the
5303                        scanning will be done and has exactly the following possibilities:</t>
5304                        <t>
5305                            <list>
5306                                <t>"RECURSIVE" -
5307                                    <list>
5308                                        <t>All instruments will be processed, including those
5309                                        in the subdirectories, and the respective subdirectory
5310                                        tree structure will be recreated in the instruments
5311                                        database</t>
5312                                    </list>
5313                                </t>
5314                                <t>"NON_RECURSIVE" -
5315                                    <list>
5316                                        <t>Only the instruments in the specified directory
5317                                        will be added, the instruments in the subdirectories
5318                                        will not be processed.</t>
5319                                    </list>
5320                                </t>
5321                                <t>"FLAT" -
5322                                    <list>
5323                                        <t>All instruments will be processed, including those
5324                                        in the subdirectories, but the respective subdirectory
5325                                        structure will not be recreated in the instruments
5326                                        database. All instruments will be added directly in
5327                                        the specified database directory.</t>
5328                                    </list>
5329                                </t>
5330                            </list>
5331                        </t>
5332    
5333                     <t>The difference between regular and NON_MODAL versions of the command
5334                        is that the regular command returns when the scanning is finished
5335                        while NON_MODAL version returns immediately and a background process is launched.
5336                        The <xref target="GET DB_INSTRUMENTS_JOB INFO">GET DB_INSTRUMENTS_JOB INFO</xref>
5337                        command can be used to monitor the scanning progress.</t>
5338    
5339                        <t>Possible Answers:</t>
5340                        <t>
5341                            <list>
5342                                <t>"OK" -
5343                                    <list>
5344                                        <t>on success when NON_MODAL is not supplied</t>
5345                                    </list>
5346                                </t>
5347                                <t>"OK[&lt;job-id&gt;]" -
5348                                    <list>
5349                                        <t>on success when NON_MODAL is supplied, where &lt;job-id&gt;
5350                                        is a numerical ID used to obtain status information about the job progress.
5351                                        See <xref target="GET DB_INSTRUMENTS_JOB INFO">GET DB_INSTRUMENTS_JOB INFO</xref>
5352                                        </t>
5353                                    </list>
5354                                </t>
5355                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
5356                                    <list>
5357                                        <t>if an invalid path is specified.</t>
5358                                    </list>
5359                                </t>
5360                            </list>
5361                        </t>
5362    
5363                        <t>Examples:</t>
5364                        <t>
5365                            <list>
5366                                <t>C: "ADD DB_INSTRUMENTS '/Piano Collection' '/home/me/gigs/PMI Bosendorfer 290.gig' 0"</t>
5367                                <t>S: "OK"</t>
5368                            </list>
5369                        </t>
5370                    </section>
5371    
5372                    <section title="Removing an instrument" anchor="REMOVE DB_INSTRUMENT">
5373                        <t>The front-end can remove a particular instrument
5374                        from the instruments database by sending the following command:</t>
5375                        <t>
5376                            <list>
5377                                <t>REMOVE DB_INSTRUMENT &lt;instr_path&gt;</t>
5378                            </list>
5379                        </t>
5380                        <t>Where &lt;instr_path&gt; is the absolute path name
5381                        (in the instruments database) of the instrument to remove.</t>
5382    
5383                        <t>Possible Answers:</t>
5384                        <t>
5385                            <list>
5386                                <t>"OK" -
5387                                    <list>
5388                                        <t>if the instrument is removed successfully</t>
5389                                    </list>
5390                                </t>
5391                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
5392                                    <list>
5393                                        <t>if the given path does not exist or
5394                                        is a directory.</t>
5395                                    </list>
5396                                </t>
5397                            </list>
5398                        </t>
5399    
5400                        <t>Examples:</t>
5401                        <t>
5402                            <list>
5403                                <t>C: "REMOVE DB_INSTRUMENT '/Piano Collection/Bosendorfer 290'"</t>
5404                                <t>S: "OK"</t>
5405                            </list>
5406                        </t>
5407                    </section>
5408    
5409                    <section title="Getting amount of instruments" anchor="GET DB_INSTRUMENTS">
5410                        <t>The front-end can retrieve the current amount of
5411                        instruments in a specific directory by sending the following command:</t>
5412                        <t>
5413                            <list>
5414                                <t>GET DB_INSTRUMENTS [RECURSIVE] &lt;dir&gt;</t>
5415                            </list>
5416                        </t>
5417                        <t>Where &lt;dir&gt; should be replaced by the absolute path name
5418                        of the directory. If RECURSIVE is specified, the number of all
5419                        instruments, including those located in subdirectories of the
5420                        specified directory, will be returned.</t>
5421    
5422                        <t>Possible Answers:</t>
5423                        <t>
5424                            <list>
5425                                <t>The current number of instruments
5426                                in the specified directory.</t>
5427                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
5428                                    <list>
5429                                        <t>if the given directory does not exist.</t>
5430                                    </list>
5431                                </t>
5432                            </list>
5433                        </t>
5434    
5435                        <t>Example:</t>
5436                        <t>
5437                            <list>
5438                                <t>C: "GET DB_INSTRUMENTS '/Piano Collection'"</t>
5439                                <t>S: "2"</t>
5440                            </list>
5441                        </t>
5442                    </section>
5443    
5444                    <section title="Listing all instruments in specific directory" anchor="LIST DB_INSTRUMENTS">
5445                        <t>The front-end can retrieve the current list of instruments
5446                        in specific directory by sending the following command:</t>
5447                        <t>
5448                            <list>
5449                                <t>LIST DB_INSTRUMENTS [RECURSIVE] &lt;dir&gt;</t>
5450                            </list>
5451                        </t>
5452                        <t>Where &lt;dir&gt; should be replaced by the absolute path
5453                        name of the directory. If RECURSIVE is specified, the absolute path
5454                        names of all instruments, including those located in subdirectories
5455                        of the specified directory, will be returned.</t>
5456    
5457                        <t>Possible Answers:</t>
5458                        <t>
5459                            <list>
5460                                <t>A comma separated list of all instruments
5461                                (encapsulated into apostrophes) in the specified directory.</t>
5462                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
5463                                    <list>
5464                                        <t>if the given directory does not exist.</t>
5465                                    </list>
5466                                </t>
5467                            </list>
5468                        </t>
5469                        <t>Example:</t>
5470                        <t>
5471                            <list>
5472                                <t>C: "LIST DB_INSTRUMENTS '/Piano Collection'"</t>
5473                                <t>S: "'Bosendorfer 290','Steinway D'"</t>
5474                            </list>
5475                        </t>
5476                        <t>
5477                            <list>
5478                                <t>C: "LIST DB_INSTRUMENTS RECURSIVE '/Piano Collection'"</t>
5479                                <t>S: "'/Piano Collection/Bosendorfer 290','/Piano Collection/Steinway D','/Piano Collection/Lite/Free Piano'"</t>
5480                            </list>
5481                        </t>
5482                    </section>
5483    
5484                    <section title="Getting instrument information" anchor="GET DB_INSTRUMENT INFO">
5485                        <t>The front-end can ask for the current settings of an
5486                        instrument by sending the following command:</t>
5487                        <t>
5488                            <list>
5489                                <t>GET DB_INSTRUMENT INFO &lt;instr_path&gt;</t>
5490                            </list>
5491                        </t>
5492                        <t>Where &lt;instr_path&gt; should be replaced by the absolute path
5493                        name of the instrument the front-end is interested in.</t>
5494    
5495                        <t>Possible Answers:</t>
5496                        <t>
5497                            <list>
5498                                <t>LinuxSampler will answer by sending a &lt;CRLF&gt; separated list.
5499                                Each answer line begins with the settings category name
5500                                followed by a colon and then a space character &lt;SP&gt; and finally
5501                                the info character string to that setting category. At the
5502                                moment the following categories are defined:</t>
5503    
5504                                <t>
5505                                    <list>
5506                                        <t>INSTRUMENT_FILE -
5507                                            <list>
5508                                                <t>File name of the instrument.
5509                                                Note that the character string may contain
5510                                                <xref target="character_set">escape sequences</xref>.</t>
5511                                            </list>
5512                                        </t>
5513                                        <t>INSTRUMENT_NR -
5514                                            <list>
5515                                                <t>Index of the instrument within the file.</t>
5516                                            </list>
5517                                        </t>
5518                                        <t>FORMAT_FAMILY -
5519                                            <list>
5520                                                <t>The format family of the instrument.</t>
5521                                            </list>
5522                                        </t>
5523                                        <t>FORMAT_VERSION -
5524                                            <list>
5525                                                <t>The format version of the instrument.</t>
5526                                            </list>
5527                                        </t>
5528                                        <t>SIZE -
5529                                            <list>
5530                                                <t>The size of the instrument in bytes.</t>
5531                                            </list>
5532                                        </t>
5533                                        <t>CREATED -
5534                                            <list>
5535                                                <t>The date and time when the instrument is added
5536                                                in the instruments database, represented in
5537                                               "YYYY-MM-DD HH:MM:SS" format</t>
5538                                            </list>
5539                                        </t>
5540                                        <t>MODIFIED -
5541                                            <list>
5542                                                <t>The date and time of the last modification of the
5543                                                instrument's database settings, represented in
5544                                                "YYYY-MM-DD HH:MM:SS" format</t>
5545                                            </list>
5546                                        </t>
5547                                        <t>DESCRIPTION -
5548                                            <list>
5549                                                <t>A brief description of the instrument.
5550                                                Note that the character string may contain
5551                                                <xref target="character_set">escape sequences</xref>.</t>
5552                                            </list>
5553                                        </t>
5554                                        <t>IS_DRUM -
5555                                            <list>
5556                                                <t>either true or false, determines whether the
5557                                                instrument is a drumkit or a chromatic instrument</t>
5558                                            </list>
5559                                        </t>
5560                                        <t>PRODUCT -
5561                                            <list>
5562                                                <t>The product title of the instrument.
5563                                                Note that the character string may contain
5564                                                <xref target="character_set">escape sequences</xref>.</t>
5565                                            </list>
5566                                        </t>
5567                                        <t>ARTISTS -
5568                                            <list>
5569                                                <t>Lists the artist names.
5570                                                Note that the character string may contain
5571                                                <xref target="character_set">escape sequences</xref>.</t>
5572                                            </list>
5573                                        </t>
5574                                        <t>KEYWORDS -
5575                                            <list>
5576                                                <t>Provides a list of keywords that refer to the instrument.
5577                                                Keywords are separated with semicolon and blank.
5578                                                Note that the character string may contain
5579                                                <xref target="character_set">escape sequences</xref>.</t>
5580                                            </list>
5581                                        </t>
5582                                    </list>
5583                                </t>
5584                            </list>
5585                        </t>
5586                        <t>The mentioned fields above don't have to be in particular order.</t>
5587    
5588                        <t>Example:</t>
5589                        <t>
5590                            <list>
5591                                <t>C: "GET DB_INSTRUMENT INFO '/Piano Collection/Bosendorfer 290'"</t>
5592                                <t>S: "INSTRUMENT_FILE: /home/me/gigs/Bosendorfer 290.gig"</t>
5593                                <t>&nbsp;&nbsp;&nbsp;"INSTRUMENT_NR: 0"</t>
5594                                <t>&nbsp;&nbsp;&nbsp;"FORMAT_FAMILY: GIG"</t>
5595                                <t>&nbsp;&nbsp;&nbsp;"FORMAT_VERSION: 2"</t>
5596                                <t>&nbsp;&nbsp;&nbsp;"SIZE: 2050871870"</t>
5597                                <t>&nbsp;&nbsp;&nbsp;"CREATED: 2007-02-05 10:23:12"</t>
5598                                <t>&nbsp;&nbsp;&nbsp;"MODIFIED: 2007-04-07 12:50:21"</t>
5599                                <t>&nbsp;&nbsp;&nbsp;"DESCRIPTION: "</t>
5600                                <t>&nbsp;&nbsp;&nbsp;"IS_DRUM: false"</t>
5601                                <t>&nbsp;&nbsp;&nbsp;"PRODUCT: GRANDIOSO Bosendorfer 290"</t>
5602                                <t>&nbsp;&nbsp;&nbsp;"ARTISTS: Post Musical Instruments"</t>
5603                                <t>&nbsp;&nbsp;&nbsp;"KEYWORDS: Bosendorfer"</t>
5604                                <t>&nbsp;&nbsp;&nbsp;"."</t>
5605                            </list>
5606                        </t>
5607                    </section>
5608    
5609                    <section title="Renaming an instrument" anchor="SET DB_INSTRUMENT NAME">
5610                        <t>The front-end can alter the name of a specific
5611                        instrument by sending the following command:</t>
5612                        <t>
5613                            <list>
5614                                <t>SET DB_INSTRUMENT NAME &lt;instr&gt; &lt;name&gt;</t>
5615                            </list>
5616                        </t>
5617                        <t>Where &lt;instr&gt; is the absolute path name of the instrument and
5618                        &lt;name&gt; is the new name for that instrument.</t>
5619    
5620                        <t>Possible Answers:</t>
5621                        <t>
5622                            <list>
5623                                <t>"OK" -
5624                                    <list>
5625                                        <t>on success</t>
5626                                    </list>
5627                                </t>
5628                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
5629                                    <list>
5630                                        <t>in case the given instrument does not exists,
5631                                        or if an instrument with name equal to the new
5632                                        name already exists.</t>
5633                                    </list>
5634                                </t>
5635                            </list>
5636                        </t>
5637    
5638                        <t>Example:</t>
5639                        <t>
5640                            <list>
5641                                <t>C: "SET DB_INSTRUMENT NAME '/Piano Collection/Bosendorfer' 'Bosendorfer 290'"</t>
5642                                <t>S: "OK"</t>
5643                            </list>
5644                        </t>
5645                    </section>
5646    
5647                    <section title="Moving an instrument" anchor="MOVE DB_INSTRUMENT">
5648                        <t>The front-end can move a specific instrument to another directory by
5649                        sending the following command:</t>
5650                        <t>
5651                            <list>
5652                                <t>MOVE DB_INSTRUMENT &lt;instr&gt; &lt;dst&gt;</t>
5653                            </list>
5654                        </t>
5655                        <t>Where &lt;instr&gt; is the absolute path name of the instrument
5656                        to move and &lt;dst&gt; is the directory where the instrument will
5657                        be moved to.</t>
5658    
5659                        <t>Possible Answers:</t>
5660                        <t>
5661                            <list>
5662                                <t>"OK" -
5663                                    <list>
5664                                        <t>on success</t>
5665                                    </list>
5666                                </t>
5667                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
5668                                    <list>
5669                                        <t>in case the given instrument does not exists,
5670                                        or if an instrument with name equal to the name of the
5671                                        specified instrument already exists in the destination
5672                                        directory.</t>
5673                                    </list>
5674                                </t>
5675                            </list>
5676                        </t>
5677    
5678                        <t>Example:</t>
5679                        <t>
5680                            <list>
5681                                <t>C: "MOVE DB_INSTRUMENT '/Piano Collection/Bosendorfer 290' '/Piano Collection/Acoustic'"</t>
5682                                <t>S: "OK"</t>
5683                            </list>
5684                        </t>
5685                    </section>
5686    
5687                    <section title="Copying instruments" anchor="COPY DB_INSTRUMENT">
5688                        <t>The front-end can copy a specific instrument to another directory by
5689                        sending the following command:</t>
5690                        <t>
5691                            <list>
5692                                <t>COPY DB_INSTRUMENT &lt;instr&gt; &lt;dst&gt;</t>
5693                            </list>
5694                        </t>
5695                        <t>Where &lt;instr&gt; is the absolute path name of the instrument
5696                        to copy and &lt;dst&gt; is the directory where the instrument will
5697                        be copied to.</t>
5698    
5699                        <t>Possible Answers:</t>
5700                        <t>
5701                            <list>
5702                                <t>"OK" -
5703                                    <list>
5704                                        <t>on success</t>
5705                                    </list>
5706                                </t>
5707                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
5708                                    <list>
5709                                        <t>in case the given instrument does not exists,
5710                                        or if an instrument with name equal to the name of the
5711                                        specified instrument already exists in the destination
5712                                        directory.</t>
5713                                    </list>
5714                                </t>
5715                            </list>
5716                        </t>
5717    
5718                        <t>Example:</t>
5719                        <t>
5720                            <list>
5721                                <t>C: "COPY DB_INSTRUMENT '/Piano Collection/Bosendorfer 290' '/Acoustic/Pianos/'"</t>
5722                                <t>S: "OK"</t>
5723                            </list>
5724                        </t>
5725                    </section>
5726    
5727                    <section title="Changing the description of instrument" anchor="SET DB_INSTRUMENT DESCRIPTION">
5728                        <t>The front-end can alter the description of a specific
5729                        instrument by sending the following command:</t>
5730                        <t>
5731                            <list>
5732                                <t>SET DB_INSTRUMENT DESCRIPTION &lt;instr&gt; &lt;desc&gt;</t>
5733                            </list>
5734                        </t>
5735                        <t>Where &lt;instr&gt; is the absolute path name of the instrument and
5736                        &lt;desc&gt; is the new description for the instrument
5737                        (encapsulated into apostrophes, supporting escape sequences as described in chapter
5738                        "<xref target="character_set">Character Set and Escape Sequences</xref>").</t>
5739    
5740                        <t>Possible Answers:</t>
5741                        <t>
5742                            <list>
5743                                <t>"OK" -
5744                                    <list>
5745                                        <t>on success</t>
5746                                    </list>
5747                                </t>
5748                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
5749                                    <list>
5750                                        <t>in case the given instrument does not exists.</t>
5751                                    </list>
5752                                </t>
5753                            </list>
5754                        </t>
5755    
5756                        <t>Example:</t>
5757                        <t>
5758                            <list>
5759                                <t>C: "SET DB_INSTRUMENT DESCRIPTION '/Piano Collection/Acoustic/Bosendorfer 290' 'No comment :)'"</t>
5760                                <t>S: "OK"</t>
5761                            </list>
5762                        </t>
5763                    </section>
5764    
5765                    <section title="Finding instruments" anchor="FIND DB_INSTRUMENTS">
5766                        <t>The front-end can search for instruments
5767                        in specific directory by sending the following command:</t>
5768                        <t>
5769                            <list>
5770                                <t>FIND DB_INSTRUMENTS [NON_RECURSIVE] &lt;dir&gt; &lt;criteria-list&gt;</t>
5771                            </list>
5772                        </t>
5773                        <t>Where &lt;dir&gt; should be replaced by the absolute path
5774                        name of the directory to search in. If NON_RECURSIVE is specified, the
5775                        directories located in subdirectories of the specified directory will not
5776                        be searched. &lt;criteria-list&gt; is a list of search criterias
5777                        in form of "key1=val1 key2=val2 ...". The following criterias are
5778                        allowed:</t>
5779                        <t>
5780                          <t>NAME='&lt;search-string&gt;'
5781                              <list>
5782                                  <t>Restricts the search to instruments, which names
5783                                  satisfy the supplied search string (encapsulated into apostrophes,
5784                                  supporting escape sequences as described in chapter
5785                                  "<xref target="character_set">Character Set and Escape Sequences</xref>").</t>
5786                              </list>
5787                          </t>
5788    
5789                          <t>SIZE=[&lt;min&gt;]..[&lt;max&gt;]
5790                              <list>
5791                                  <t>Restricts the search to instruments, which
5792                                  size is in the specified range. If &lt;min&gt; is omitted,
5793                                  the search results are restricted to instruments with size less then
5794                                  or equal to &lt;max&gt;. If &lt;max&gt; is omitted, the
5795                                  search is restricted to instruments with size greater then
5796                                  or equal to &lt;min&gt;.</t>
5797                              </list>
5798                          </t>
5799    
5800                          <t>CREATED='[&lt;date-after&gt;]..[&lt;date-before&gt;]'
5801                              <list>
5802                                  <t>Restricts the search to instruments, which creation
5803                                  date satisfies the specified period, where &lt;date-after&gt;
5804                                  and &lt;date-before&gt; are in "YYYY-MM-DD HH:MM:SS" format.
5805                                  If &lt;date-after&gt; is omitted the search is restricted to
5806                                  instruments created before &lt;date-before&gt;. If
5807                                  &lt;date-before&gt; is omitted, the search is restricted
5808                                  to instruments created after &lt;date-after&gt;.</t>
5809                              </list>
5810                          </t>
5811    
5812                          <t>MODIFIED='[&lt;date-after&gt;]..[&lt;date-before&gt;]'
5813                              <list>
5814                                  <t>Restricts the search to instruments, which
5815                                  date of last modification satisfies the specified period, where
5816                                  &lt;date-after&gt; and &lt;date-before&gt; are in "YYYY-MM-DD HH:MM:SS"
5817                                  format. If &lt;date-after&gt; is omitted the search is restricted to
5818                                  instruments, which are last modified before &lt;date-before&gt;. If
5819                                  &lt;date-before&gt; is omitted, the search is restricted to instruments,
5820                                  which are last modified after &lt;date-after&gt;.</t>
5821                              </list>
5822                          </t>
5823    
5824                          <t>DESCRIPTION='&lt;search-string&gt;'
5825                              <list>
5826                                  <t>Restricts the search to instruments with description
5827                                  that satisfies the supplied search string (encapsulated into apostrophes,
5828                                  supporting escape sequences as described in chapter
5829                                  "<xref target="character_set">Character Set and Escape Sequences</xref>").</t>
5830                              </list>
5831                          </t>
5832    
5833                          <t>PRODUCT='&lt;search-string&gt;'
5834                              <list>
5835                                  <t>Restricts the search to instruments with product info
5836                                  that satisfies the supplied search string (encapsulated into apostrophes,
5837                                  supporting escape sequences as described in chapter
5838                                  "<xref target="character_set">Character Set and Escape Sequences</xref>").</t>
5839                              </list>
5840                          </t>
5841    
5842                          <t>ARTISTS='&lt;search-string&gt;'
5843                              <list>
5844                                  <t>Restricts the search to instruments with artists info
5845                                  that satisfies the supplied search string (encapsulated into apostrophes,
5846                                  supporting escape sequences as described in chapter
5847                                  "<xref target="character_set">Character Set and Escape Sequences</xref>").</t>
5848                              </list>
5849                          </t>
5850    
5851                          <t>KEYWORDS='&lt;search-string&gt;'
5852                              <list>
5853                                  <t>Restricts the search to instruments with keyword list
5854                                  that satisfies the supplied search string (encapsulated into apostrophes,
5855                                  supporting escape sequences as described in chapter
5856                                  "<xref target="character_set">Character Set and Escape Sequences</xref>").</t>
5857                              </list>
5858                          </t>
5859    
5860                          <t>IS_DRUM=true | false
5861                              <list>
5862                                  <t>Either true or false. Restricts the search to
5863                                  drum kits or chromatic instruments.</t>
5864                              </list>
5865                          </t>
5866    
5867                          <t>FORMAT_FAMILIES='&lt;format-list&gt;'
5868                              <list>
5869                                  <t>Restricts the search to instruments of the supplied format families,
5870                                  where &lt;format-list&gt; is a comma separated list of format families.</t>
5871                              </list>
5872                          </t>
5873                        </t>
5874    
5875                        <t>Where &lt;search-string&gt; is either a regular expression, or a
5876                        word list separated with spaces for OR search and with '+' for AND search.</t>
5877    
5878                        <t>Possible Answers:</t>
5879                        <t>
5880                            <list>
5881                                <t>A comma separated list with the absolute path names (encapsulated into
5882                                apostrophes) of all instruments in the specified directory that satisfy
5883                                the supplied search criterias.</t>
5884                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
5885                                    <list>
5886                                        <t>if the given directory does not exist.</t>
5887                                    </list>
5888                                </t>
5889                            </list>
5890                        </t>
5891                        <t>Example:</t>
5892                        <t>
5893                            <list>
5894                                <t>C: "FIND DB_INSTRUMENTS '/Piano Collection' NAME='bosendorfer+290'"</t>
5895                                <t>S: "'/Piano Collection/Bosendorfer 290'"</t>
5896                            </list>
5897                        </t>
5898                        <t>
5899                            <list>
5900                                <t>C: "FIND DB_INSTRUMENTS '/Piano Collection' CREATED='2007-04-01 09:30:13..'"</t>
5901                                <t>S: "'/Piano Collection/Bosendorfer 290','/Piano Collection/Steinway D'"</t>
5902                            </list>
5903                        </t>
5904                    </section>
5905    
5906                    <section title="Getting job status information" anchor="GET DB_INSTRUMENTS_JOB INFO">
5907                        <t>The front-end can ask for the current status of a
5908                        particular database instruments job by sending the following command:</t>
5909                        <t>
5910                            <list>
5911                                <t>GET DB_INSTRUMENTS_JOB INFO &lt;job-id&gt;</t>
5912                            </list>
5913                        </t>
5914                        <t>Where &lt;job-id&gt; should be replaced by the numerical ID
5915                        of the job the front-end is interested in.</t>
5916    
5917                        <t>Possible Answers:</t>
5918                        <t>
5919                            <list>
5920                                <t>LinuxSampler will answer by sending a &lt;CRLF&gt; separated list.
5921                                Each answer line begins with the settings category name
5922                                followed by a colon and then a space character &lt;SP&gt; and finally
5923                                the info character string to that setting category. At the
5924                                moment the following categories are defined:</t>
5925    
5926                                <t>
5927                                    <list>
5928                                        <t>FILES_TOTAL -
5929                                            <list>
5930                                                <t>The total number of files scheduled for scanning</t>
5931                                            </list>
5932                                        </t>
5933                                        <t>FILES_SCANNED -
5934                                            <list>
5935                                                <t>The current number of scanned files</t>
5936                                            </list>
5937                                        </t>
5938                                        <t>SCANNING -
5939                                            <list>
5940                                                <t>The absolute path name of the file which is currently
5941                                                being scanned</t>
5942                                            </list>
5943                                        </t>
5944                                        <t>STATUS -
5945                                            <list>
5946                                                <t>An integer value between 0 and 100 indicating the
5947                                                scanning progress percentage of the file which is
5948                                                currently being scanned</t>
5949                                            </list>
5950                                        </t>
5951                                    </list>
5952                                </t>
5953                            </list>
5954                        </t>
5955                        <t>The mentioned fields above don't have to be in particular order.</t>
5956    
5957                        <t>Example:</t>
5958                        <t>
5959                            <list>
5960                                <t>C: "GET DB_INSTRUMENTS_JOB INFO 2"</t>
5961                                <t>S: "FILES_TOTAL: 12"</t>
5962                                <t>&nbsp;&nbsp;&nbsp;"FILES_SCANNED: 7"</t>
5963                                <t>&nbsp;&nbsp;&nbsp;"SCANNING: /home/me/gigs/Bosendorfer 290.gig"</t>
5964                                <t>&nbsp;&nbsp;&nbsp;"STATUS: 42"</t>
5965                                <t>&nbsp;&nbsp;&nbsp;"."</t>
5966                            </list>
5967                        </t>
5968                    </section>
5969    
5970                    <section title="Formatting the instruments database" anchor="FORMAT INSTRUMENTS_DB">
5971                        <t>The front-end can remove all instruments and directories and re-create
5972                        the instruments database structure (e.g., in case of a database corruption)
5973                        by sending the following command:</t>
5974                        <t>
5975                            <list>
5976                                <t>FORMAT INSTRUMENTS_DB</t>
5977                            </list>
5978                        </t>
5979                        
5980                        <t>Possible Answers:</t>
5981                        <t>
5982                            <list>
5983                                <t>"OK" -
5984                                    <list>
5985                                        <t>on success</t>
5986                                    </list>
5987                                </t>
5988                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
5989                                    <list>
5990                                        <t>If the formatting of the instruments database
5991                                        failed.</t>
5992                                    </list>
5993                                </t>
5994                            </list>
5995                        </t>
5996                    </section>
5997    
5998                </section>
5999    
6000    
6001    
6002                <section title="Editing Instruments" anchor="editing_instruments">
6003                    <t>The sampler allows to edit instruments while playing with the
6004                    sampler by spawning an external (3rd party) instrument editor
6005                    application for a given instrument. The 3rd party instrument
6006                    editor applications have to place a respective plugin DLL file
6007                    into the sampler's plugins directory. The sampler will
6008                    automatically try to load all plugin DLLs in that directory on
6009                    startup and only on startup!</t>
6010                    <t>At the moment there is only one command for this feature set,
6011                    but this will most probably change in future.</t>
6012    
6013                    <section title="Opening an appropriate instrument editor application" anchor="EDIT INSTRUMENT">
6014                        <t>The front-end can request to open an appropriate instrument
6015                        editor application by sending the following command:</t>
6016                        <t>
6017                            <list>
6018                                <t>EDIT CHANNEL INSTRUMENT &lt;sampler-channel&gt;</t>
6019                            </list>
6020                        </t>
6021                        <t>Where &lt;sampler-channel&gt; should be replaced by the
6022                        number of the sampler channel as given by the
6023                        <xref target="ADD CHANNEL">"ADD CHANNEL"</xref>
6024                        or <xref target="LIST CHANNELS">"LIST CHANNELS"</xref>
6025                        command.</t>
6026    
6027                        <t>The sampler will try to ask all registered instrument
6028                        editors (or to be more specific: their sampler plugins)
6029                        whether they are capable to handle the instrument on the
6030                        given sampler channel. The sampler will simply use the first
6031                        instrument editor application which replied with a positive
6032                        answer and spawn that instrument editor application within
6033                        the sampler's process and provide that application access
6034                        to the instrument's data structures, so both applications
6035                        can share and access the same instruments data at the same
6036                        time, thus allowing to immediately hear changes with the
6037                        sampler made by the instrument editor.</t>
6038    
6039                        <t>Note: consequently instrument editors are always spawned
6040                        locally on the same machine where the sampler is running
6041                        on!</t>
6042    
6043                        <t>Possible Answers:</t>
6044                        <t>
6045                            <list>
6046                                <t>"OK" -
6047                                    <list>
6048                                        <t>when an appropriate instrument editor was
6049                                        launched</t>
6050                                    </list>
6051                                </t>
6052                                <t>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
6053                                    <list>
6054                                        <t>when an appropriate instrument editor was
6055                                        launched, but there are noteworthy issues</t>
6056                                    </list>
6057                                </t>
6058                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
6059                                    <list>
6060                                        <t>when an appropriate instrument editor
6061                                        could not be launched</t>
6062                                    </list>
6063                                </t>
6064                            </list>
6065                        </t>
6066    
6067                        <t>Examples:</t>
6068                        <t>
6069                            <list>
6070                                <t>C: "EDIT CHANNEL INSTRUMENT 0"</t>
6071                                <t>S: "OK"</t>
6072                            </list>
6073                        </t>
6074                    </section>
6075                </section>
6076          </section>          </section>
6077    
6078    
# Line 4287  Schoenebeck'> Line 6148  Schoenebeck'>
6148                  </t>                  </t>
6149                  <t>/ UNSUBSCRIBE SP unsubscribe_event                  <t>/ UNSUBSCRIBE SP unsubscribe_event
6150                  </t>                  </t>
                 <t>/ SELECT SP text  
                 </t>  
6151                  <t>/ RESET SP reset_instruction                  <t>/ RESET SP reset_instruction
6152                  </t>                  </t>
6153                  <t>/ CLEAR SP clear_instruction                  <t>/ CLEAR SP clear_instruction
6154                  </t>                  </t>
6155                    <t>/ FIND SP find_instruction
6156                    </t>
6157                    <t>/ MOVE SP move_instruction
6158                    </t>
6159                    <t>/ COPY SP copy_instruction
6160                    </t>
6161                    <t>/ EDIT SP edit_instruction
6162                    </t>
6163                    <t>/ FORMAT SP format_instruction
6164                    </t>
6165                  <t>/ RESET                  <t>/ RESET
6166                  </t>                  </t>
6167                  <t>/ QUIT                  <t>/ QUIT
# Line 4303  Schoenebeck'> Line 6172  Schoenebeck'>
6172          <list>          <list>
6173                  <t>CHANNEL                  <t>CHANNEL
6174                  </t>                  </t>
6175                    <t>/ DB_INSTRUMENT_DIRECTORY SP db_path
6176                    </t>
6177                    <t>/ DB_INSTRUMENTS SP NON_MODAL SP scan_mode SP db_path SP filename
6178                    </t>
6179                    <t>/ DB_INSTRUMENTS SP scan_mode SP db_path SP filename
6180                    </t>
6181                    <t>/ DB_INSTRUMENTS SP NON_MODAL SP db_path SP filename
6182                    </t>
6183                    <t>/ DB_INSTRUMENTS SP NON_MODAL SP db_path SP filename SP instrument_index
6184                    </t>
6185                    <t>/ DB_INSTRUMENTS SP db_path SP filename
6186                    </t>
6187                    <t>/ DB_INSTRUMENTS SP db_path SP filename SP instrument_index
6188                    </t>
6189                  <t>/ MIDI_INSTRUMENT_MAP                  <t>/ MIDI_INSTRUMENT_MAP
6190                  </t>                  </t>
6191                  <t>/ MIDI_INSTRUMENT_MAP SP map_name                  <t>/ MIDI_INSTRUMENT_MAP SP map_name
# Line 4311  Schoenebeck'> Line 6194  Schoenebeck'>
6194  </t>  </t>
6195  <t>subscribe_event =  <t>subscribe_event =
6196          <list>          <list>
6197                  <t>CHANNEL_COUNT                  <t>AUDIO_OUTPUT_DEVICE_COUNT
6198                    </t>
6199                    <t>/ AUDIO_OUTPUT_DEVICE_INFO
6200                    </t>
6201                    <t>/ MIDI_INPUT_DEVICE_COUNT
6202                    </t>
6203                    <t>/ MIDI_INPUT_DEVICE_INFO
6204                    </t>
6205                    <t>/ CHANNEL_COUNT
6206                  </t>                  </t>
6207                  <t>/ VOICE_COUNT                  <t>/ VOICE_COUNT
6208                  </t>                  </t>
# Line 4321  Schoenebeck'> Line 6212  Schoenebeck'>
6212                  </t>                  </t>
6213                  <t>/ CHANNEL_INFO                  <t>/ CHANNEL_INFO
6214                  </t>                  </t>
6215                    <t>/ FX_SEND_COUNT
6216                    </t>
6217                    <t>/ FX_SEND_INFO
6218                    </t>
6219                    <t>/ MIDI_INSTRUMENT_MAP_COUNT
6220                    </t>
6221                    <t>/ MIDI_INSTRUMENT_MAP_INFO
6222                    </t>
6223                    <t>/ MIDI_INSTRUMENT_COUNT
6224                    </t>
6225                    <t>/ MIDI_INSTRUMENT_INFO
6226                    </t>
6227                    <t>/ DB_INSTRUMENT_DIRECTORY_COUNT
6228                    </t>
6229                    <t>/ DB_INSTRUMENT_DIRECTORY_INFO
6230                    </t>
6231                    <t>/ DB_INSTRUMENT_COUNT
6232                    </t>
6233                    <t>/ DB_INSTRUMENT_INFO
6234                    </t>
6235                    <t>/ DB_INSTRUMENTS_JOB_INFO
6236                    </t>
6237                  <t>/ MISCELLANEOUS                  <t>/ MISCELLANEOUS
6238                  </t>                  </t>
6239                    <t>/ TOTAL_STREAM_COUNT
6240                    </t>
6241                  <t>/ TOTAL_VOICE_COUNT                  <t>/ TOTAL_VOICE_COUNT
6242                  </t>                  </t>
6243                    <t>/ GLOBAL_INFO
6244                    </t>
6245          </list>          </list>
6246  </t>  </t>
6247  <t>unsubscribe_event =  <t>unsubscribe_event =
6248          <list>          <list>
6249                  <t>CHANNEL_COUNT                  <t>AUDIO_OUTPUT_DEVICE_COUNT
6250                    </t>
6251                    <t>/ AUDIO_OUTPUT_DEVICE_INFO
6252                    </t>
6253                    <t>/ MIDI_INPUT_DEVICE_COUNT
6254                    </t>
6255                    <t>/ MIDI_INPUT_DEVICE_INFO
6256                    </t>
6257                    <t>/ CHANNEL_COUNT
6258                  </t>                  </t>
6259                  <t>/ VOICE_COUNT                  <t>/ VOICE_COUNT
6260                  </t>                  </t>
# Line 4339  Schoenebeck'> Line 6264  Schoenebeck'>
6264                  </t>                  </t>
6265                  <t>/ CHANNEL_INFO                  <t>/ CHANNEL_INFO
6266                  </t>                  </t>
6267                    <t>/ FX_SEND_COUNT
6268                    </t>
6269                    <t>/ FX_SEND_INFO
6270                    </t>
6271                    <t>/ MIDI_INSTRUMENT_MAP_COUNT
6272                    </t>
6273                    <t>/ MIDI_INSTRUMENT_MAP_INFO
6274                    </t>
6275                    <t>/ MIDI_INSTRUMENT_COUNT
6276                    </t>
6277                    <t>/ MIDI_INSTRUMENT_INFO
6278                    </t>
6279                    <t>/ DB_INSTRUMENT_DIRECTORY_COUNT
6280                    </t>
6281                    <t>/ DB_INSTRUMENT_DIRECTORY_INFO
6282                    </t>
6283                    <t>/ DB_INSTRUMENT_COUNT
6284                    </t>
6285                    <t>/ DB_INSTRUMENT_INFO
6286                    </t>
6287                    <t>/ DB_INSTRUMENTS_JOB_INFO
6288                    </t>
6289                  <t>/ MISCELLANEOUS                  <t>/ MISCELLANEOUS
6290                  </t>                  </t>
6291                    <t>/ TOTAL_STREAM_COUNT
6292                    </t>
6293                  <t>/ TOTAL_VOICE_COUNT                  <t>/ TOTAL_VOICE_COUNT
6294                  </t>                  </t>
6295                    <t>/ GLOBAL_INFO
6296                    </t>
6297          </list>          </list>
6298  </t>  </t>
6299  <t>map_instruction =  <t>map_instruction =
6300          <list>          <list>
6301                  <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
6302                  </t>                  </t>
6303                  <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
6304                  </t>                  </t>
6305                  <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
6306                  </t>                  </t>
6307                  <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
6308                  </t>                  </t>
6309          </list>          </list>
6310  </t>  </t>
# Line 4371  Schoenebeck'> Line 6322  Schoenebeck'>
6322                  </t>                  </t>
6323                  <t>/ MIDI_INSTRUMENT_MAP SP ALL                  <t>/ MIDI_INSTRUMENT_MAP SP ALL
6324                  </t>                  </t>
6325                    <t>/ DB_INSTRUMENT_DIRECTORY SP FORCE SP db_path
6326                    </t>
6327                    <t>/ DB_INSTRUMENT_DIRECTORY SP db_path
6328                    </t>
6329                    <t>/ DB_INSTRUMENT SP db_path
6330                    </t>
6331          </list>          </list>
6332  </t>  </t>
6333  <t>get_instruction =  <t>get_instruction =
# Line 4423  Schoenebeck'> Line 6380  Schoenebeck'>
6380                  </t>                  </t>
6381                  <t>/ SERVER SP INFO                  <t>/ SERVER SP INFO
6382                  </t>                  </t>
6383                    <t>/ TOTAL_STREAM_COUNT
6384                    </t>
6385                  <t>/ TOTAL_VOICE_COUNT                  <t>/ TOTAL_VOICE_COUNT
6386                  </t>                  </t>
6387                  <t>/ TOTAL_VOICE_COUNT_MAX                  <t>/ TOTAL_VOICE_COUNT_MAX
# Line 4437  Schoenebeck'> Line 6396  Schoenebeck'>
6396                  </t>                  </t>
6397                  <t>/ MIDI_INSTRUMENT_MAP SP INFO SP midi_map                  <t>/ MIDI_INSTRUMENT_MAP SP INFO SP midi_map
6398                  </t>                  </t>
6399                    <t>/ FX_SENDS SP sampler_channel
6400                    </t>
6401                    <t>/ FX_SEND SP INFO SP sampler_channel SP fx_send_id
6402                    </t>
6403                    <t>/ DB_INSTRUMENT_DIRECTORIES SP RECURSIVE SP db_path
6404                    </t>
6405                    <t>/ DB_INSTRUMENT_DIRECTORIES SP db_path
6406                    </t>
6407                    <t>/ DB_INSTRUMENT_DIRECTORY SP INFO SP db_path
6408                    </t>
6409                    <t>/ DB_INSTRUMENTS SP RECURSIVE SP db_path
6410                    </t>
6411                    <t>/ DB_INSTRUMENTS SP db_path
6412                    </t>
6413                    <t>/ DB_INSTRUMENT SP INFO SP db_path
6414                    </t>
6415                    <t>/ DB_INSTRUMENTS_JOB SP INFO SP number
6416                    </t>
6417                    <t>/ VOLUME
6418                    </t>
6419                    <t>/ FILE SP INSTRUMENTS SP filename
6420                    </t>
6421                    <t>/ FILE SP INSTRUMENT SP INFO SP filename SP instrument_index
6422                    </t>
6423          </list>          </list>
6424  </t>  </t>
6425  <t>set_instruction =  <t>set_instruction =
# Line 4447  Schoenebeck'> Line 6430  Schoenebeck'>
6430                  </t>                  </t>
6431                  <t>/ MIDI_INPUT_DEVICE_PARAMETER SP number SP string '=' param_val_list                  <t>/ MIDI_INPUT_DEVICE_PARAMETER SP number SP string '=' param_val_list
6432                  </t>                  </t>
6433                    <t>/ MIDI_INPUT_PORT_PARAMETER SP number SP number SP string '=' NONE
6434                    </t>
6435                  <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
6436                  </t>                  </t>
6437                  <t>/ CHANNEL SP set_chan_instruction                  <t>/ CHANNEL SP set_chan_instruction
6438                  </t>                  </t>
6439                  <t>/ MIDI_INSTRUMENT_MAP SP NAME SP midi_map SP map_name                  <t>/ MIDI_INSTRUMENT_MAP SP NAME SP midi_map SP map_name
6440                  </t>                  </t>
6441                    <t>/ FX_SEND SP NAME SP sampler_channel SP fx_send_id SP fx_send_name
6442                    </t>
6443                    <t>/ FX_SEND SP AUDIO_OUTPUT_CHANNEL SP sampler_channel SP fx_send_id SP audio_channel_index SP audio_channel_index
6444                    </t>
6445                    <t>/ FX_SEND SP MIDI_CONTROLLER SP sampler_channel SP fx_send_id SP midi_ctrl
6446                    </t>
6447                    <t>/ FX_SEND SP LEVEL SP sampler_channel SP fx_send_id SP volume_value
6448                    </t>
6449                    <t>/ DB_INSTRUMENT_DIRECTORY SP NAME SP db_path SP stringval_escaped
6450                    </t>
6451                    <t>/ DB_INSTRUMENT_DIRECTORY SP DESCRIPTION SP db_path SP stringval_escaped
6452                    </t>
6453                    <t>/ DB_INSTRUMENT SP NAME SP db_path SP stringval_escaped
6454                    </t>
6455                    <t>/ DB_INSTRUMENT SP DESCRIPTION SP db_path SP stringval_escaped
6456                    </t>
6457                  <t>/ ECHO SP boolean                  <t>/ ECHO SP boolean
6458                  </t>                  </t>
6459                    <t>/ VOLUME SP volume_value
6460                    </t>
6461          </list>          </list>
6462  </t>  </t>
6463  <t>create_instruction =  <t>create_instruction =
# Line 4467  Schoenebeck'> Line 6470  Schoenebeck'>
6470                  </t>                  </t>
6471                  <t>/ MIDI_INPUT_DEVICE SP string                  <t>/ MIDI_INPUT_DEVICE SP string
6472                  </t>                  </t>
6473                    <t>/ FX_SEND SP sampler_channel SP midi_ctrl
6474                    </t>
6475                    <t>/ FX_SEND SP sampler_channel SP midi_ctrl SP fx_send_name
6476                    </t>
6477          </list>          </list>
6478  </t>  </t>
6479  <t>reset_instruction =  <t>reset_instruction =
# Line 4483  Schoenebeck'> Line 6490  Schoenebeck'>
6490                  </t>                  </t>
6491          </list>          </list>
6492  </t>  </t>
6493    <t>find_instruction =
6494            <list>
6495                    <t>DB_INSTRUMENTS SP NON_RECURSIVE SP db_path SP query_val_list
6496                    </t>
6497                    <t>/ DB_INSTRUMENTS SP db_path SP query_val_list
6498                    </t>
6499                    <t>/ DB_INSTRUMENT_DIRECTORIES SP NON_RECURSIVE SP db_path SP query_val_list
6500                    </t>
6501                    <t>/ DB_INSTRUMENT_DIRECTORIES SP db_path SP query_val_list
6502                    </t>
6503            </list>
6504    </t>
6505    <t>move_instruction =
6506            <list>
6507                    <t>DB_INSTRUMENT_DIRECTORY SP db_path SP db_path
6508                    </t>
6509                    <t>/ DB_INSTRUMENT SP db_path SP db_path
6510                    </t>
6511            </list>
6512    </t>
6513    <t>copy_instruction =
6514            <list>
6515                    <t>DB_INSTRUMENT_DIRECTORY SP db_path SP db_path
6516                    </t>
6517                    <t>/ DB_INSTRUMENT SP db_path SP db_path
6518                    </t>
6519            </list>
6520    </t>
6521  <t>destroy_instruction =  <t>destroy_instruction =
6522          <list>          <list>
6523                  <t>AUDIO_OUTPUT_DEVICE SP number                  <t>AUDIO_OUTPUT_DEVICE SP number
6524                  </t>                  </t>
6525                  <t>/ MIDI_INPUT_DEVICE SP number                  <t>/ MIDI_INPUT_DEVICE SP number
6526                  </t>                  </t>
6527                    <t>/ FX_SEND SP sampler_channel SP fx_send_id
6528                    </t>
6529          </list>          </list>
6530  </t>  </t>
6531  <t>load_instruction =  <t>load_instruction =
# Line 4531  Schoenebeck'> Line 6568  Schoenebeck'>
6568                  </t>                  </t>
6569          </list>          </list>
6570  </t>  </t>
6571    <t>edit_instruction =
6572            <list>
6573                    <t>CHANNEL SP INSTRUMENT SP sampler_channel
6574                    </t>
6575            </list>
6576    </t>
6577    <t>format_instruction =
6578            <list>
6579                    <t>INSTRUMENTS_DB
6580                    </t>
6581            </list>
6582    </t>
6583    <t>modal_arg =
6584            <list>
6585                    <t>/* epsilon (empty argument) */
6586                    </t>
6587                    <t>/ NON_MODAL SP
6588                    </t>
6589            </list>
6590    </t>
6591  <t>key_val_list =  <t>key_val_list =
6592          <list>          <list>
6593                  <t>string '=' param_val_list                  <t>string '=' param_val_list
# Line 4567  Schoenebeck'> Line 6624  Schoenebeck'>
6624                  </t>                  </t>
6625                  <t>/ MIDI_INSTRUMENT_MAPS                  <t>/ MIDI_INSTRUMENT_MAPS
6626                  </t>                  </t>
6627                    <t>/ FX_SENDS SP sampler_channel
6628                    </t>
6629                    <t>/ DB_INSTRUMENT_DIRECTORIES SP RECURSIVE SP db_path
6630                    </t>
6631                    <t>/ DB_INSTRUMENT_DIRECTORIES SP db_path
6632                    </t>
6633                    <t>/ DB_INSTRUMENTS SP RECURSIVE SP db_path
6634                    </t>
6635                    <t>/ DB_INSTRUMENTS SP db_path
6636                    </t>
6637                    <t>/ FILE SP INSTRUMENTS SP filename
6638                    </t>
6639          </list>          </list>
6640  </t>  </t>
6641  <t>load_instr_args =  <t>load_instr_args =
# Line 4649  Schoenebeck'> Line 6718  Schoenebeck'>
6718                  </t>                  </t>
6719          </list>          </list>
6720  </t>  </t>
6721    <t>midi_ctrl =
6722            <list>
6723                    <t>number
6724                    </t>
6725            </list>
6726    </t>
6727  <t>volume_value =  <t>volume_value =
6728          <list>          <list>
6729                  <t>dotnum                  <t>dotnum
# Line 4669  Schoenebeck'> Line 6744  Schoenebeck'>
6744                  </t>                  </t>
6745          </list>          </list>
6746  </t>  </t>
6747    <t>fx_send_id =
6748            <list>
6749                    <t>number
6750                    </t>
6751            </list>
6752    </t>
6753  <t>engine_name =  <t>engine_name =
6754          <list>          <list>
6755                  <t>string                  <t>string
# Line 4677  Schoenebeck'> Line 6758  Schoenebeck'>
6758  </t>  </t>
6759  <t>filename =  <t>filename =
6760          <list>          <list>
6761                  <t>stringval                  <t>path
6762                    </t>
6763            </list>
6764    </t>
6765    <t>db_path =
6766            <list>
6767                    <t>path
6768                  </t>                  </t>
6769          </list>          </list>
6770  </t>  </t>
6771  <t>map_name =  <t>map_name =
6772          <list>          <list>
6773                  <t>stringval                  <t>stringval_escaped
6774                  </t>                  </t>
6775          </list>          </list>
6776  </t>  </t>
6777  <t>entry_name =  <t>entry_name =
6778          <list>          <list>
6779                  <t>stringval                  <t>stringval_escaped
6780                    </t>
6781            </list>
6782    </t>
6783    <t>fx_send_name =
6784            <list>
6785                    <t>stringval_escaped
6786                  </t>                  </t>
6787          </list>          </list>
6788  </t>  </t>
# Line 4701  Schoenebeck'> Line 6794  Schoenebeck'>
6794                  </t>                  </t>
6795          </list>          </list>
6796  </t>  </t>
6797    
6798  <t>param_val =  <t>param_val =
6799          <list>          <list>
6800                  <t>string                  <t>string
# Line 4713  Schoenebeck'> Line 6807  Schoenebeck'>
6807                  </t>                  </t>
6808          </list>          </list>
6809  </t>  </t>
6810    <t>query_val_list =
6811            <list>
6812                    <t>string '=' query_val
6813                    </t>
6814                    <t>/ query_val_list SP string '=' query_val
6815                    </t>
6816            </list>
6817    </t>
6818    <t>query_val =
6819            <list>
6820                    <t>text_escaped
6821                    </t>
6822                    <t>/ stringval_escaped
6823                    </t>
6824            </list>
6825    </t>
6826    <t>scan_mode =
6827            <list>
6828                    <t>RECURSIVE
6829                    </t>
6830                    <t>/ NON_RECURSIVE
6831                    </t>
6832                    <t>/ FLAT
6833                    </t>
6834            </list>
6835    </t>
6836    
6837              <!-- GRAMMAR_BNF_END - do NOT delete or modify this line !!! -->              <!-- GRAMMAR_BNF_END - do NOT delete or modify this line !!! -->
6838    
6839                <section title="Character Set and Escape Sequences" anchor="character_set">
6840                    <t>Older versions of this protocol up to and including v1.1 only
6841                    supported the standard ASCII character set (ASCII code 0 - 127)
6842                    <xref target="RFC20"/>, all younger versions of this protocol
6843                    however support the Extended ASCII character set (ASCII code
6844                    0 - 255). The same group of younger protocols also support
6845                    escape sequences, but only for certain, explicitly declared
6846                    parts of the protocol. The supported escape sequences are
6847                    defined as follows:</t>
6848                    <texttable>
6849                        <ttcol>ASCII Character Sequence</ttcol>
6850                        <ttcol>Translated into (Name)</ttcol>
6851                        <c>\n</c> <c>new line</c>
6852                        <c>\r</c> <c>carriage return</c>
6853                        <c>\f</c> <c>form feed</c>
6854                        <c>\t</c> <c>horizontal tab</c>
6855                        <c>\v</c> <c>vertical tab</c>
6856                        <c>\'</c> <c>apostrophe</c>
6857                        <c>\"</c> <c>quotation mark</c>
6858                        <c>\\</c> <c>backslash</c>
6859                        <c>\OOO</c> <c>three digit octal ASCII code of the character</c>
6860                        <c>\xHH</c> <c>two digit hex ASCII code of the character</c>
6861                    </texttable>
6862                    <t>Notice: due to the transition of certain parts of the
6863                    protocol which now support escape sequences, a slight backward
6864                    incompatibility to protocols version v1.1 and younger has been
6865                    introduced. The only difference is that in parts of the protocol
6866                    where escape characters are now supported, a backslash characters
6867                    MUST be escaped as well (that is as double backslash), whereas
6868                    in the old versions a single backslash was sufficient.</t>
6869    
6870                    <t>The following LSCP commands support escape sequences as part
6871                    of their filename / path based arguments and / or may contain
6872                    a filename / path with escape sequences in their response:
6873                    <list>
6874                        <t><xref target="LOAD INSTRUMENT">"LOAD INSTRUMENT"</xref></t>
6875                        <t><xref target="GET CHANNEL INFO">"GET CHANNEL INFO"</xref></t>
6876                        <t><xref target="MAP MIDI_INSTRUMENT">"MAP MIDI_INSTRUMENT"</xref></t>
6877                        <t><xref target="GET MIDI_INSTRUMENT INFO">"GET MIDI_INSTRUMENT INFO"</xref></t>
6878                        <t><xref target="ADD DB_INSTRUMENT_DIRECTORY">"ADD DB_INSTRUMENT_DIRECTORY"</xref></t>
6879                        <t><xref target="ADD DB_INSTRUMENTS">"ADD DB_INSTRUMENTS"</xref></t>
6880                        <t><xref target="REMOVE DB_INSTRUMENT_DIRECTORY">"REMOVE DB_INSTRUMENT_DIRECTORY"</xref></t>
6881                        <t><xref target="REMOVE DB_INSTRUMENT">"REMOVE DB_INSTRUMENT"</xref></t>
6882                        <t><xref target="GET DB_INSTRUMENT_DIRECTORIES">"GET DB_INSTRUMENT_DIRECTORIES"</xref></t>
6883                        <t><xref target="LIST DB_INSTRUMENT_DIRECTORIES">"LIST DB_INSTRUMENT_DIRECTORIES"</xref></t>
6884                        <t><xref target="GET DB_INSTRUMENT_DIRECTORY INFO">"GET DB_INSTRUMENT_DIRECTORY INFO"</xref></t>
6885                        <t><xref target="GET DB_INSTRUMENTS">"GET DB_INSTRUMENTS"</xref></t>
6886                        <t><xref target="LIST DB_INSTRUMENTS">"LIST DB_INSTRUMENTS"</xref></t>
6887                        <t><xref target="GET DB_INSTRUMENT INFO">"GET DB_INSTRUMENT INFO"</xref></t>
6888                        <t><xref target="SET DB_INSTRUMENT_DIRECTORY NAME">"SET DB_INSTRUMENT_DIRECTORY NAME"</xref></t>
6889                        <t><xref target="SET DB_INSTRUMENT_DIRECTORY DESCRIPTION">"SET DB_INSTRUMENT_DIRECTORY DESCRIPTION"</xref></t>
6890                        <t><xref target="SET DB_INSTRUMENT NAME">"SET DB_INSTRUMENT NAME"</xref></t>
6891                        <t><xref target="SET DB_INSTRUMENT DESCRIPTION">"SET DB_INSTRUMENT DESCRIPTION"</xref></t>
6892                        <t><xref target="FIND DB_INSTRUMENTS">"FIND DB_INSTRUMENTS"</xref></t>
6893                        <t><xref target="FIND DB_INSTRUMENT_DIRECTORIES">"FIND DB_INSTRUMENT_DIRECTORIES"</xref></t>
6894                        <t><xref target="MOVE DB_INSTRUMENT">"MOVE DB_INSTRUMENT"</xref></t>
6895                        <t><xref target="MOVE DB_INSTRUMENT_DIRECTORY">"MOVE DB_INSTRUMENT_DIRECTORY"</xref></t>
6896                        <t><xref target="COPY DB_INSTRUMENT">"COPY DB_INSTRUMENT"</xref></t>
6897                        <t><xref target="COPY DB_INSTRUMENT_DIRECTORY">"COPY DB_INSTRUMENT_DIRECTORY"</xref></t>
6898                    </list>
6899                    Note that the forward slash character ('/') has a special meaning in
6900                    filename / path based arguments: it acts as separator of the nodes in
6901                    the path, thus if a directory- or filename includes a forward slash
6902                    (not intended as path node separator), you MUST escape that slash
6903                    either with the respective hex escape sequence ("\x2f") or with the
6904                    respective octal escape sequence ("\057").
6905                    </t>
6906    
6907                    <t>
6908                    The following LSCP commands even support escape sequences as
6909                    part of at least one of their text-based arguments (i.e. entity name,
6910                    description) and / or may contain escape sequences in at least one of
6911                    their text-based fields in their response:
6912                    <list>
6913                        <t><xref target="GET SERVER INFO">"GET SERVER INFO"</xref></t>
6914                        <t><xref target="GET ENGINE INFO">"GET ENGINE INFO"</xref></t>
6915                        <t><xref target="GET CHANNEL INFO">"GET CHANNEL INFO"</xref></t>
6916                        <t><xref target="CREATE FX_SEND">"CREATE FX_SEND"</xref></t>
6917                        <t><xref target="GET FX_SEND INFO">"GET FX_SEND INFO"</xref></t>
6918                        <t><xref target="SET FX_SEND NAME">"SET FX_SEND NAME"</xref></t>
6919                        <t><xref target="GET MIDI_INSTRUMENT INFO">"GET MIDI_INSTRUMENT INFO"</xref></t>
6920                        <t><xref target="GET MIDI_INSTRUMENT_MAP INFO">"GET MIDI_INSTRUMENT_MAP INFO"</xref></t>
6921                        <t><xref target="ADD MIDI_INSTRUMENT_MAP">"ADD MIDI_INSTRUMENT_MAP"</xref></t>
6922                        <t><xref target="MAP MIDI_INSTRUMENT">"MAP MIDI_INSTRUMENT"</xref></t>
6923                        <t><xref target="SET MIDI_INSTRUMENT_MAP NAME">"SET MIDI_INSTRUMENT_MAP NAME"</xref></t>
6924                        <t><xref target="GET DB_INSTRUMENT_DIRECTORY INFO">"GET DB_INSTRUMENT_DIRECTORY INFO"</xref></t>
6925                        <t><xref target="SET DB_INSTRUMENT_DIRECTORY NAME">"SET DB_INSTRUMENT_DIRECTORY NAME"</xref></t>
6926                        <t><xref target="SET DB_INSTRUMENT_DIRECTORY DESCRIPTION">"SET DB_INSTRUMENT_DIRECTORY DESCRIPTION"</xref></t>
6927                        <t><xref target="FIND DB_INSTRUMENT_DIRECTORIES">"FIND DB_INSTRUMENT_DIRECTORIES"</xref></t>
6928                        <t><xref target="GET DB_INSTRUMENT INFO">"GET DB_INSTRUMENT INFO"</xref></t>
6929                        <t><xref target="SET DB_INSTRUMENT NAME">"SET DB_INSTRUMENT NAME"</xref></t>
6930                        <t><xref target="SET DB_INSTRUMENT DESCRIPTION">"SET DB_INSTRUMENT DESCRIPTION"</xref></t>
6931                        <t><xref target="FIND DB_INSTRUMENTS">"FIND DB_INSTRUMENTS"</xref></t>
6932                    </list>
6933                    Please note that these lists are manually maintained. If you
6934                    find a command that also supports escape sequences we forgot to
6935                    mention here, please report it!
6936                    </t>
6937                </section>
6938          </section>          </section>
6939    
6940          <section title="Events" anchor="events">          <section title="Events" anchor="events">
6941              <t>This chapter will describe all currently defined events supported by LinuxSampler.</t>              <t>This chapter will describe all currently defined events supported by LinuxSampler.</t>
6942    
6943              <section title="Number of sampler channels changed" anchor="SUBSCRIBE CHANNEL">              <section title="Number of audio output devices changed" anchor="SUBSCRIBE AUDIO_OUTPUT_DEVICE_COUNT">
6944                    <t>Client may want to be notified when the total number of audio output devices on the
6945                    back-end changes by issuing the following command:</t>
6946                    <t>
6947                        <list>
6948                            <t>SUBSCRIBE AUDIO_OUTPUT_DEVICE_COUNT</t>
6949                        </list>
6950                    </t>
6951                    <t>Server will start sending the following notification messages:</t>
6952                    <t>
6953                        <list>
6954                            <t>"NOTIFY:AUDIO_OUTPUT_DEVICE_COUNT:&lt;devices&gt;"</t>
6955                        </list>
6956                    </t>
6957                    <t>where &lt;devices&gt; will be replaced by the new number
6958                    of audio output devices.</t>
6959                </section>
6960    
6961                <section title="Audio output device's settings changed" anchor="SUBSCRIBE AUDIO_OUTPUT_DEVICE_INFO">
6962                    <t>Client may want to be notified when changes were made to audio output devices on the
6963                    back-end by issuing the following command:</t>
6964                    <t>
6965                        <list>
6966                            <t>SUBSCRIBE AUDIO_OUTPUT_DEVICE_INFO</t>
6967                        </list>
6968                    </t>
6969                    <t>Server will start sending the following notification messages:</t>
6970                    <t>
6971                        <list>
6972                            <t>"NOTIFY:AUDIO_OUTPUT_DEVICE_INFO:&lt;device-id&gt;"</t>
6973                        </list>
6974                    </t>
6975                    <t>where &lt;device-id&gt; will be replaced by the numerical ID of the audio output device,
6976                    which settings has been changed. The front-end will have to send
6977                    the respective command to actually get the audio output device info. Because these messages
6978                    will be triggered by LSCP commands issued by other clients rather than real
6979                    time events happening on the server, it is believed that an empty notification
6980                    message is sufficient here.</t>
6981                </section>
6982    
6983                <section title="Number of MIDI input devices changed" anchor="SUBSCRIBE MIDI_INPUT_DEVICE_COUNT">
6984                    <t>Client may want to be notified when the total number of MIDI input devices on the
6985                    back-end changes by issuing the following command:</t>
6986                    <t>
6987                        <list>
6988                            <t>SUBSCRIBE MIDI_INPUT_DEVICE_COUNT</t>
6989                        </list>
6990                    </t>
6991                    <t>Server will start sending the following notification messages:</t>
6992                    <t>
6993                        <list>
6994                            <t>"NOTIFY:MIDI_INPUT_DEVICE_COUNT:&lt;devices&gt;"</t>
6995                        </list>
6996                    </t>
6997                    <t>where &lt;devices&gt; will be replaced by the new number
6998                    of MIDI input devices.</t>
6999                </section>
7000    
7001                <section title="MIDI input device's settings changed" anchor="SUBSCRIBE MIDI_INPUT_DEVICE_INFO">
7002                    <t>Client may want to be notified when changes were made to MIDI input devices on the
7003                    back-end by issuing the following command:</t>
7004                    <t>
7005                        <list>
7006                            <t>SUBSCRIBE MIDI_INPUT_DEVICE_INFO</t>
7007                        </list>
7008                    </t>
7009                    <t>Server will start sending the following notification messages:</t>
7010                    <t>
7011                        <list>
7012                            <t>"NOTIFY:MIDI_INPUT_DEVICE_INFO:&lt;device-id&gt;"</t>
7013                        </list>
7014                    </t>
7015                    <t>where &lt;device-id&gt; will be replaced by the numerical ID of the MIDI input device,
7016                    which settings has been changed. The front-end will have to send
7017                    the respective command to actually get the MIDI input device info. Because these messages
7018                    will be triggered by LSCP commands issued by other clients rather than real
7019                    time events happening on the server, it is believed that an empty notification
7020                    message is sufficient here.</t>
7021                </section>
7022    
7023                <section title="Number of sampler channels changed" anchor="SUBSCRIBE CHANNEL_COUNT">
7024                  <t>Client may want to be notified when the total number of channels on the                  <t>Client may want to be notified when the total number of channels on the
7025                  back-end changes by issuing the following command:</t>                  back-end changes by issuing the following command:</t>
7026                  <t>                  <t>
# Line 4749  Schoenebeck'> Line 7049  Schoenebeck'>
7049                  <t>Server will start sending the following notification messages:</t>                  <t>Server will start sending the following notification messages:</t>
7050                  <t>                  <t>
7051                      <list>                      <list>
7052                          <t>"NOTIFY:VOICE_COUNT:&lt;sampler-channel&gt; &lt;voices&gt;</t>                          <t>"NOTIFY:VOICE_COUNT:&lt;sampler-channel&gt; &lt;voices&gt;"</t>
7053                      </list>                      </list>
7054                  </t>                  </t>
7055                  <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 4797  Schoenebeck'> Line 7097  Schoenebeck'>
7097                  "GET CHANNEL BUFFER_FILL PERCENTAGE"</xref> command was issued on this channel.</t>                  "GET CHANNEL BUFFER_FILL PERCENTAGE"</xref> command was issued on this channel.</t>
7098              </section>              </section>
7099    
7100              <section title="Channel information changed" anchor="SUBSCRIBE INFO">              <section title="Channel information changed" anchor="SUBSCRIBE CHANNEL_INFO">
7101                  <t>Client may want to be notified when changes were made to sampler channels on the                  <t>Client may want to be notified when changes were made to sampler channels on the
7102                  back-end by issuing the following command:</t>                  back-end by issuing the following command:</t>
7103                  <t>                  <t>
# Line 4819  Schoenebeck'> Line 7119  Schoenebeck'>
7119                  message is sufficient here.</t>                  message is sufficient here.</t>
7120              </section>              </section>
7121    
7122                <section title="Number of effect sends changed" anchor="SUBSCRIBE FX_SEND_COUNT">
7123                    <t>Client may want to be notified when the number of effect sends on
7124                    a particular sampler channel is changed by issuing the following command:</t>
7125                    <t>
7126                        <list>
7127                            <t>SUBSCRIBE FX_SEND_COUNT</t>
7128                        </list>
7129                    </t>
7130                    <t>Server will start sending the following notification messages:</t>
7131                    <t>
7132                        <list>
7133                            <t>"NOTIFY:FX_SEND_COUNT:&lt;channel-id&gt; &lt;fx-sends&gt;"</t>
7134                        </list>
7135                    </t>
7136                    <t>where &lt;channel-id&gt; will be replaced by the numerical ID of the sampler
7137                    channel, on which the effect sends number is changed and &lt;fx-sends&gt; will
7138                    be replaced by the new number of effect sends on that channel.</t>
7139                </section>
7140    
7141                <section title="Effect send information changed" anchor="SUBSCRIBE FX_SEND_INFO">
7142                    <t>Client may want to be notified when changes were made to effect sends on a
7143                    a particular sampler channel by issuing the following command:</t>
7144                    <t>
7145                        <list>
7146                            <t>SUBSCRIBE FX_SEND_INFO</t>
7147                        </list>
7148                    </t>
7149                    <t>Server will start sending the following notification messages:</t>
7150                    <t>
7151                        <list>
7152                            <t>"NOTIFY:FX_SEND_INFO:&lt;channel-id&gt; &lt;fx-send-id&gt;"</t>
7153                        </list>
7154                    </t>
7155                    <t>where &lt;channel-id&gt; will be replaced by the numerical ID of the sampler
7156                    channel, on which an effect send entity is changed and &lt;fx-send-id&gt; will
7157                    be replaced by the numerical ID of the changed effect send.</t>
7158                </section>
7159    
7160              <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">
7161                  <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
7162                  back-end changes by issuing the following command:</t>                  back-end changes by issuing the following command:</t>
# Line 4830  Schoenebeck'> Line 7168  Schoenebeck'>
7168                  <t>Server will start sending the following notification messages:</t>                  <t>Server will start sending the following notification messages:</t>
7169                  <t>                  <t>
7170                      <list>                      <list>
7171                          <t>"NOTIFY:TOTAL_VOICE_COUNT:&lt;voices&gt;</t>                          <t>"NOTIFY:TOTAL_VOICE_COUNT:&lt;voices&gt;"</t>
7172                      </list>                      </list>
7173                  </t>                  </t>
7174                  <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
7175                  all currently active voices.</t>                  all currently active voices.</t>
7176              </section>              </section>
7177    
7178                <section title="Total number of active disk streams changed" anchor="SUBSCRIBE TOTAL_STREAM_COUNT">
7179                    <t>Client may want to be notified when the total number of disk streams on the
7180                    back-end changes by issuing the following command:</t>
7181                    <t>
7182                        <list>
7183                            <t>SUBSCRIBE TOTAL_STREAM_COUNT</t>
7184                        </list>
7185                    </t>
7186                    <t>Server will start sending the following notification messages:</t>
7187                    <t>
7188                        <list>
7189                            <t>"NOTIFY:TOTAL_STREAM_COUNT:&lt;streams&gt;"</t>
7190                        </list>
7191                    </t>
7192                    <t>where &lt;streams&gt; will be replaced by the new number of
7193                    all currently active disk streams.</t>
7194                </section>
7195    
7196                <section title="Number of MIDI instrument maps changed" anchor="SUBSCRIBE MIDI_INSTRUMENT_MAP_COUNT">
7197                    <t>Client may want to be notified when the number of MIDI instrument maps on the
7198                    back-end changes by issuing the following command:</t>
7199                    <t>
7200                        <list>
7201                            <t>SUBSCRIBE MIDI_INSTRUMENT_MAP_COUNT</t>
7202                        </list>
7203                    </t>
7204                    <t>Server will start sending the following notification messages:</t>
7205                    <t>
7206                        <list>
7207                            <t>"NOTIFY:MIDI_INSTRUMENT_MAP_COUNT:&lt;maps&gt;"</t>
7208                        </list>
7209                    </t>
7210                    <t>where &lt;maps&gt; will be replaced by the new number
7211                    of MIDI instrument maps.</t>
7212                </section>
7213    
7214                <section title="MIDI instrument map information changed" anchor="SUBSCRIBE MIDI_INSTRUMENT_MAP_INFO">
7215                    <t>Client may want to be notified when changes were made to MIDI instrument maps on the
7216                    back-end by issuing the following command:</t>
7217                    <t>
7218                        <list>
7219                            <t>SUBSCRIBE MIDI_INSTRUMENT_MAP_INFO</t>
7220                        </list>
7221                    </t>
7222                    <t>Server will start sending the following notification messages:</t>
7223                    <t>
7224                        <list>
7225                            <t>"NOTIFY:MIDI_INSTRUMENT_MAP_INFO:&lt;map-id&gt;"</t>
7226                        </list>
7227                    </t>
7228                    <t>where &lt;map-id&gt; will be replaced by the numerical ID of the MIDI instrument map,
7229                    for which information changes occurred. The front-end will have to send
7230                    the respective command to actually get the MIDI instrument map info. Because these messages
7231                    will be triggered by LSCP commands issued by other clients rather than real
7232                    time events happening on the server, it is believed that an empty notification
7233                    message is sufficient here.</t>
7234                </section>
7235    
7236                <section title="Number of MIDI instruments changed" anchor="SUBSCRIBE MIDI_INSTRUMENT_COUNT">
7237                    <t>Client may want to be notified when the number of MIDI instrument maps on the
7238                    back-end changes by issuing the following command:</t>
7239                    <t>
7240                        <list>
7241                            <t>SUBSCRIBE MIDI_INSTRUMENT_COUNT</t>
7242                        </list>
7243                    </t>
7244                    <t>Server will start sending the following notification messages:</t>
7245                    <t>
7246                        <list>
7247                            <t>"NOTIFY:MIDI_INSTRUMENT_COUNT:&lt;map-id&gt; &lt;instruments&gt;"</t>
7248                        </list>
7249                    </t>
7250                    <t>where &lt;map-id&gt; is the numerical ID of the MIDI instrument map, in which
7251                    the nuber of instruments has changed and &lt;instruments&gt; will be replaced by
7252                    the new number of MIDI instruments in the specified map.</t>
7253                </section>
7254    
7255                <section title="MIDI instrument information changed" anchor="SUBSCRIBE MIDI_INSTRUMENT_INFO">
7256                    <t>Client may want to be notified when changes were made to MIDI instruments on the
7257                    back-end by issuing the following command:</t>
7258                    <t>
7259                        <list>
7260                            <t>SUBSCRIBE MIDI_INSTRUMENT_INFO</t>
7261                        </list>
7262                    </t>
7263                    <t>Server will start sending the following notification messages:</t>
7264                    <t>
7265                        <list>
7266                            <t>"NOTIFY:MIDI_INSTRUMENT_INFO:&lt;map-id&gt; &lt;bank&gt; &lt;program&gt;"</t>
7267                        </list>
7268                    </t>
7269                    <t>where &lt;map-id&gt; will be replaced by the numerical ID of the MIDI instrument map,
7270                    in which a MIDI instrument is changed. &lt;bank&gt; and &lt;program&gt; specifies
7271                    the location of the changed MIDI instrument in the map. The front-end will have to send
7272                    the respective command to actually get the MIDI instrument info. Because these messages
7273                    will be triggered by LSCP commands issued by other clients rather than real
7274                    time events happening on the server, it is believed that an empty notification
7275                    message is sufficient here.</t>
7276                </section>
7277    
7278                <section title="Global settings changed" anchor="SUBSCRIBE GLOBAL_INFO">
7279                    <t>Client may want to be notified when changes to the global settings
7280                    of the sampler were made by issuing the following command:</t>
7281                    <t>
7282                        <list>
7283                            <t>SUBSCRIBE GLOBAL_INFO</t>
7284                        </list>
7285                    </t>
7286                    <t>Server will start sending the following types of notification messages:</t>
7287                    <t>
7288                        <list>
7289                            <t>"NOTIFY:GLOBAL_INFO:VOLUME &lt;volume&gt;" - Notifies that the
7290                            golbal volume of the sampler is changed, where &lt;volume&gt; will be
7291                            replaced by the optional dotted floating point value, reflecting the
7292                            new global volume parameter.</t>
7293                        </list>
7294                    </t>
7295                </section>
7296    
7297                <section title="Number of database instrument directories changed" anchor="SUBSCRIBE DB_INSTRUMENT_DIRECTORY_COUNT">
7298                    <t>Client may want to be notified when the number of instrument
7299                    directories in a particular directory in the instruments database
7300                    is changed by issuing the following command:</t>
7301                    <t>
7302                        <list>
7303                            <t>SUBSCRIBE DB_INSTRUMENT_DIRECTORY_COUNT</t>
7304                        </list>
7305                    </t>
7306                    <t>Server will start sending the following notification messages:</t>
7307                    <t>
7308                        <list>
7309                            <t>"NOTIFY:DB_INSTRUMENT_DIRECTORY_COUNT:&lt;dir-path&gt;"</t>
7310                        </list>
7311                    </t>
7312                    <t>where &lt;dir-path&gt; will be replaced by the absolute path
7313                    name of the directory in the instruments database,
7314                    in which the number of directories is changed.</t>
7315                    <t>Note that when a non-empty directory is removed, this event
7316                    is not sent for the subdirectories in that directory.</t>
7317                </section>
7318    
7319                <section title="Database instrument directory information changed" anchor="SUBSCRIBE DB_INSTRUMENT_DIRECTORY_INFO">
7320                    <t>Client may want to be notified when changes were made to directories
7321                    in the instruments database by issuing the following command:</t>
7322                    <t>
7323                        <list>
7324                            <t>SUBSCRIBE DB_INSTRUMENT_DIRECTORY_INFO</t>
7325                        </list>
7326                    </t>
7327                    <t>Server will start sending the following notification messages:</t>
7328                    <t>
7329                        <list>
7330                            <t>"NOTIFY:DB_INSTRUMENT_DIRECTORY_INFO:&lt;dir-path&gt;"</t>
7331                        </list>
7332                    </t>
7333                    <t>where &lt;dir-path&gt; will be replaced by the absolute path name
7334                    of the directory, for which information changes occurred. The front-end will have to send
7335                    the respective command to actually get the updated directory info. Because these messages
7336                    will be triggered by LSCP commands issued by other clients rather than real
7337                    time events happening on the server, it is believed that an empty notification
7338                    message is sufficient here.</t>
7339                    <t>
7340                        <list>
7341                            <t>"NOTIFY:DB_INSTRUMENT_DIRECTORY_INFO:NAME &lt;old-dir-path&gt; &lt;new-name&gt;"</t>
7342                        </list>
7343                    </t>
7344                    <t>where &lt;old-dir-path&gt; is the old absolute path name of the directory
7345                    (encapsulated into apostrophes), which name is changes and &lt;new-name&gt; is
7346                    the new name of the directory, encapsulated into apostrophes.</t>
7347                </section>
7348    
7349                <section title="Number of database instruments changed" anchor="SUBSCRIBE DB_INSTRUMENT_COUNT">
7350                    <t>Client may want to be notified when the number of instruments
7351                    in a particular directory in the instruments database
7352                    is changed by issuing the following command:</t>
7353                    <t>
7354                        <list>
7355                            <t>SUBSCRIBE DB_INSTRUMENT_COUNT</t>
7356                        </list>
7357                    </t>
7358                    <t>Server will start sending the following notification messages:</t>
7359                    <t>
7360                        <list>
7361                            <t>"NOTIFY:DB_INSTRUMENT_COUNT:&lt;dir-path&gt;"</t>
7362                        </list>
7363                    </t>
7364                    <t>where &lt;dir-path&gt; will be replaced by the absolute path
7365                    name of the directory in the instruments database,
7366                    in which the number of instruments is changed.</t>
7367                    <t>Note that when a non-empty directory is removed, this event
7368                    is not sent for the instruments in that directory.</t>
7369                </section>
7370    
7371                <section title="Database instrument information changed" anchor="SUBSCRIBE DB_INSTRUMENT_INFO">
7372                    <t>Client may want to be notified when changes were made to instruments
7373                    in the instruments database by issuing the following command:</t>
7374                    <t>
7375                        <list>
7376                            <t>SUBSCRIBE DB_INSTRUMENT_INFO</t>
7377                        </list>
7378                    </t>
7379                    <t>Server will start sending the following notification messages:</t>
7380                    <t>
7381                        <list>
7382                            <t>"NOTIFY:DB_INSTRUMENT_INFO:&lt;instr-path&gt;"</t>
7383                        </list>
7384                    </t>
7385                    <t>where &lt;instr-path&gt; will be replaced by the absolute path name
7386                    of the instrument, which settings are changed. The front-end will have to send
7387                    the respective command to actually get the updated directory info. Because these messages
7388                    will be triggered by LSCP commands issued by other clients rather than real
7389                    time events happening on the server, it is believed that an empty notification
7390                    message is sufficient here.</t>
7391                    <t>
7392                        <list>
7393                            <t>"NOTIFY:DB_INSTRUMENT_INFO:NAME &lt;old-instr-path&gt; &lt;new-name&gt;"</t>
7394                        </list>
7395                    </t>
7396                    <t>where &lt;old-instr-path&gt; is the old absolute path name of the instrument
7397                    (encapsulated into apostrophes), which name is changes and &lt;new-name&gt; is
7398                    the new name of the instrument, encapsulated into apostrophes.</t>
7399                </section>
7400    
7401                <section title="Database job status information changed" anchor="SUBSCRIBE DB_INSTRUMENTS_JOB_INFO">
7402                    <t>Client may want to be notified when the status of particular database
7403                    instruments job is changed by issuing the following command:</t>
7404                    <t>
7405                        <list>
7406                            <t>SUBSCRIBE DB_INSTRUMENTS_JOB_INFO</t>
7407                        </list>
7408                    </t>
7409                    <t>Server will start sending the following notification messages:</t>
7410                    <t>
7411                        <list>
7412                            <t>"NOTIFY:DB_INSTRUMENTS_JOB_INFO:&lt;job-id&gt;"</t>
7413                        </list>
7414                    </t>
7415                    <t>where &lt;job-id&gt; will be replaced by the numerical ID of the job,
7416                    which status is changed. The front-end will have to send the respective
7417                    command to actually get the status info. Because these messages
7418                    will be triggered by LSCP commands issued by other clients rather than real
7419                    time events happening on the server, it is believed that an empty notification
7420                    message is sufficient here.</t>
7421                </section>
7422    
7423              <section title="Miscellaneous and debugging events" anchor="SUBSCRIBE MISCELLANEOUS">              <section title="Miscellaneous and debugging events" anchor="SUBSCRIBE MISCELLANEOUS">
7424                  <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
7425                  the server by issuing the following command:</t>                  the server by issuing the following command:</t>
# Line 4915  Schoenebeck'> Line 7498  Schoenebeck'>
7498                  </front>                  </front>
7499                  <seriesInfo name="RFC" value="2234" />                  <seriesInfo name="RFC" value="2234" />
7500              </reference>              </reference>
7501                <reference anchor="RFC20">
7502                    <front>
7503                        <title>ASCII format for Network Interchange</title>
7504                        <author>
7505                            <organization>UCLA</organization>
7506                        </author>
7507                        <date year="1969"></date>
7508                    </front>
7509                    <seriesInfo name="RFC" value="20" />
7510                </reference>
7511           </references>           </references>
7512      </back>      </back>
7513    
Legend:
Removed from v.973  
changed lines
  Added in v.1552
  ViewVC Help
Powered by ViewVC