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

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

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

revision 981 by iliev, Sun Dec 17 22:35:01 2006 UTC revision 1391 by iliev, Sun Oct 7 19:50:28 2007 UTC
# Line 16  Line 16 
16       to an annoying "missing Normative/Informative References" error message -->       to an annoying "missing Normative/Informative References" error message -->
17  <?rfc strict="no" ?>  <?rfc strict="no" ?>
18    
19  <rfc category="std" ipr="full3978" docName="LSCP 1.2">  <rfc category="std" ipr="full3978" docName="LSCP 1.2cvs">
20      <front>      <front>
21          <title>LinuxSampler Control Protocol</title>          <title>LinuxSampler Control Protocol (draft)</title>
22          <author initials='C.S.' surname="Schoenebeck" fullname='C.          <author initials='C.S.' surname="Schoenebeck" fullname='C.
23  Schoenebeck'>  Schoenebeck'>
24              <organization>              <organization>
# Line 34  Schoenebeck'> Line 34  Schoenebeck'>
34                  <email>schoenebeck at software minus engineering dot org</email>                  <email>schoenebeck at software minus engineering dot org</email>
35              </address>              </address>
36          </author>          </author>
37          <date month="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 2555  Schoenebeck'> Line 2569  Schoenebeck'>
2569                                      <t>VOLUME -                                      <t>VOLUME -
2570                                          <list>                                          <list>
2571                                              <t>optionally dotted number for the channel volume factor                                              <t>optionally dotted number for the channel volume factor
2572                                              (where a value < 1.0 means attenuation and a value >                                              (where a value &lt; 1.0 means attenuation and a value >
2573                                              1.0 means amplification)</t>                                              1.0 means amplification)</t>
2574                                          </list>                                          </list>
2575                                      </t>                                      </t>
# Line 3227  Schoenebeck'> Line 3241  Schoenebeck'>
3241                      </t>                      </t>
3242                  </section>                  </section>
3243    
3244                    <section title="Adding an effect send to a sampler channel" anchor="CREATE FX_SEND">
3245                        <t>The front-end can create an additional effect send on a specific sampler channel
3246                        by sending the following command:</t>
3247                        <t>
3248                            <list>
3249                                <t>CREATE FX_SEND &lt;sampler-channel&gt; &lt;midi-ctrl&gt; [&lt;name&gt;]</t>
3250                            </list>
3251                        </t>
3252                        <t>Where &lt;sampler-channel&gt; is the respective sampler channel
3253                        number as returned by the <xref target="ADD CHANNEL">"ADD CHANNEL"</xref>
3254                        or <xref target="LIST CHANNELS">"LIST CHANNELS"</xref> command, that is the
3255                        sampler channel on which the effect send should be created on, &lt;midi-ctrl&gt;
3256                        is a number between 0..127 defining the MIDI controller which can alter the
3257                        effect send level and &lt;name&gt; is an optional argument defining a name
3258                        for the effect send entity. The name does not have to be unique, but MUST be
3259                        encapsulated into apostrophes and supports escape sequences as described in chapter
3260                        "<xref target="character_set">Character Set and Escape Sequences</xref>".</t>
3261    
3262                        <t>By default, that is as initial routing, the effect send's audio channels
3263                        are automatically routed to the last audio channels of the sampler channel's
3264                        audio output device, that way you can i.e. first increase the amount of audio
3265                        channels on the audio output device for having dedicated effect send output
3266                        channels and when "CREATE FX_SEND" is called, those channels will automatically
3267                        be picked. You can alter the destination channels however with
3268                        <xref target="SET FX_SEND AUDIO_OUTPUT_CHANNEL">"SET FX_SEND AUDIO_OUTPUT_CHANNEL"</xref>.
3269                        </t>
3270    
3271                        <t>Note: Create effect sends on a sampler channel only when needed, because having effect
3272                        sends on a sampler channel will decrease runtime performance, because for implementing channel
3273                        effect sends, separate (sampler channel local) audio buffers are needed to render and mix
3274                        the voices and route the audio signal afterwards to the master outputs and effect send
3275                        outputs (along with their respective effect send levels). A sampler channel without effect
3276                        sends however can mix its voices directly into the audio output devices's audio buffers
3277                        and is thus faster.
3278                        </t>
3279    
3280                        <t>Possible Answers:</t>
3281                        <t>
3282                            <list>
3283                                <t>"OK[&lt;fx-send-id&gt;]" -
3284                                    <list>
3285                                        <t>in case a new effect send could be added to the
3286                                        sampler channel, where &lt;fx-send-id&gt; reflects the
3287                                        unique ID of the newly created effect send entity</t>
3288                                    </list>
3289                                </t>
3290                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
3291                                    <list>
3292                                        <t>when a new effect send could not be added, i.e.
3293                                        due to invalid parameters</t>
3294                                    </list>
3295                                </t>
3296                            </list>
3297                        </t>
3298    
3299                        <t>Examples:</t>
3300                        <t>
3301                            <list>
3302                                <t>C: "CREATE FX_SEND 0 91 'Reverb Send'"</t>
3303                                <t>S: "OK[0]"</t>
3304                            </list>
3305                        </t>
3306                        <t>
3307                            <list>
3308                                <t>C: "CREATE FX_SEND 0 93"</t>
3309                                <t>S: "OK[1]"</t>
3310                            </list>
3311                        </t>
3312                    </section>
3313    
3314                    <section title="Removing an effect send from a sampler channel" anchor="DESTROY FX_SEND">
3315                        <t>The front-end can remove an existing effect send on a specific sampler channel
3316                        by sending the following command:</t>
3317                        <t>
3318                            <list>
3319                                <t>DESTROY FX_SEND &lt;sampler-channel&gt; &lt;fx-send-id&gt;</t>
3320                            </list>
3321                        </t>
3322                        <t>Where &lt;sampler-channel&gt; is the respective sampler channel
3323                        number as returned by the <xref target="ADD CHANNEL">"ADD CHANNEL"</xref>
3324                        or <xref target="LIST CHANNELS">"LIST CHANNELS"</xref> command, that is the
3325                        sampler channel from which the effect send should be removed from and
3326                        &lt;fx-send-id&gt; is the respective effect send number as returned by the
3327                        <xref target="CREATE FX_SEND">"CREATE FX_SEND"</xref>
3328                        or <xref target="LIST FX_SENDS">"LIST FX_SENDS"</xref> command.</t>
3329    
3330                        <t>Possible Answers:</t>
3331                        <t>
3332                            <list>
3333                                <t>"OK" -
3334                                    <list>
3335                                        <t>on success</t>
3336                                    </list>
3337                                </t>
3338                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
3339                                    <list>
3340                                        <t>in case it failed, providing an appropriate error code and
3341                                        error message</t>
3342                                    </list>
3343                                </t>
3344                            </list>
3345                        </t>
3346    
3347                        <t>Example:</t>
3348                        <t>
3349                            <list>
3350                                <t>C: "DESTROY FX_SEND 0 0"</t>
3351                                <t>S: "OK"</t>
3352                            </list>
3353                        </t>
3354                    </section>
3355    
3356                    <section title="Getting amount of effect sends on a sampler channel" anchor="GET FX_SENDS">
3357                        <t>The front-end can ask for the amount of effect sends on a specific sampler channel
3358                        by sending the following command:</t>
3359                        <t>
3360                            <list>
3361                                <t>GET FX_SENDS &lt;sampler-channel&gt;</t>
3362                            </list>
3363                        </t>
3364                        <t>Where &lt;sampler-channel&gt; is the respective sampler channel
3365                        number as returned by the <xref target="ADD CHANNEL">"ADD CHANNEL"</xref>
3366                        or <xref target="LIST CHANNELS">"LIST CHANNELS"</xref> command.</t>
3367    
3368                        <t>Possible Answers:</t>
3369                        <t>
3370                            <list>
3371                                <t>The sampler will answer by returning the number of effect
3372                                sends on the given sampler channel.</t>
3373                            </list>
3374                        </t>
3375    
3376                        <t>Example:</t>
3377                        <t>
3378                            <list>
3379                                <t>C: "GET FX_SENDS 0"</t>
3380                                <t>S: "2"</t>
3381                            </list>
3382                        </t>
3383                    </section>
3384    
3385                    <section title="Listing all effect sends on a sampler channel" anchor="LIST FX_SENDS">
3386                        <t>The front-end can ask for a list of effect sends on a specific sampler channel
3387                        by sending the following command:</t>
3388                        <t>
3389                            <list>
3390                                <t>LIST FX_SENDS &lt;sampler-channel&gt;</t>
3391                            </list>
3392                        </t>
3393                        <t>Where &lt;sampler-channel&gt; is the respective sampler channel
3394                        number as returned by the <xref target="ADD CHANNEL">"ADD CHANNEL"</xref>
3395                        or <xref target="LIST CHANNELS">"LIST CHANNELS"</xref> command.</t>
3396    
3397                        <t>Possible Answers:</t>
3398                        <t>
3399                            <list>
3400                                <t>The sampler will answer by returning a comma separated list
3401                                with all effect sends' numerical IDs on the given sampler
3402                                channel.</t>
3403                            </list>
3404                        </t>
3405    
3406                        <t>Examples:</t>
3407                        <t>
3408                            <list>
3409                                <t>C: "LIST FX_SENDS 0"</t>
3410                                <t>S: "0,1"</t>
3411                            </list>
3412                        </t>
3413                        <t>
3414                            <list>
3415                                <t>C: "LIST FX_SENDS 1"</t>
3416                                <t>S: ""</t>
3417                            </list>
3418                        </t>
3419                    </section>
3420    
3421                    <section title="Getting effect send information" anchor="GET FX_SEND INFO">
3422                        <t>The front-end can ask for the current settings of an effect send entity
3423                        by sending the following command:</t>
3424                        <t>
3425                            <list>
3426                                <t>GET FX_SEND INFO &lt;sampler-channel&gt; &lt;fx-send-id&gt;</t>
3427                            </list>
3428                        </t>
3429                        <t>Where &lt;sampler-channel&gt; is the sampler channel number
3430                        as returned by the <xref target="ADD CHANNEL">"ADD CHANNEL"</xref>
3431                        or <xref target="LIST CHANNELS">"LIST CHANNELS"</xref> command and
3432                        &lt;fx-send-id&gt; reflects the numerical ID of the effect send entity
3433                        as returned by the <xref target="CREATE FX_SEND">"CREATE FX_SEND"</xref>
3434                        or <xref target="LIST FX_SENDS">"LIST FX_SENDS"</xref> command.
3435                       </t>
3436    
3437                        <t>Possible Answers:</t>
3438                        <t>
3439                            <list>
3440                                <t>The sampler will answer by sending a &lt;CRLF&gt; separated list.
3441                                Each answer line begins with the settings category name
3442                                followed by a colon and then a space character &lt;SP&gt; and finally
3443                                the info character string to that setting category. At the
3444                                moment the following categories are defined:</t>
3445    
3446                                <t>
3447                                    <list>
3448                                        <t>NAME -
3449                                            <list>
3450                                                <t>name of the effect send entity</t>
3451                                            </list>
3452                                        </t>
3453                                        <t>MIDI_CONTROLLER -
3454                                            <list>
3455                                                <t>a value between 0 and 127 reflecting the MIDI controller
3456                                                which is able to modify the effect send's send level</t>
3457                                            </list>
3458                                        </t>
3459                                        <t>LEVEL -
3460                                            <list>
3461                                                <t>optionally dotted number reflecting the effect send's
3462                                                current send level (where a value &lt; 1.0 means attenuation
3463                                                and a value > 1.0 means amplification)</t>
3464                                            </list>
3465                                        </t>
3466                                        <t>AUDIO_OUTPUT_ROUTING -
3467                                            <list>
3468                                                <t>comma separated list which reflects to which audio
3469                                                channel of the selected audio output device each
3470                                                effect send output channel is routed to, e.g. "0,3" would
3471                                                mean the effect send's output channel 0 is routed to channel
3472                                                0 of the audio output device and the effect send's output
3473                                                channel 1 is routed to the channel 3 of the audio
3474                                                output device (see
3475                                                <xref target="SET FX_SEND AUDIO_OUTPUT_CHANNEL">"SET FX_SEND AUDIO_OUTPUT_CHANNEL"</xref>
3476                                                for details)</t>
3477                                            </list>
3478                                        </t>
3479                                    </list>
3480                                </t>
3481                            </list>
3482                        </t>
3483                        <t>The mentioned fields above don't have to be in particular order.</t>
3484    
3485                        <t>Example:</t>
3486                        <t>
3487                            <list>
3488                                <t>C: "GET FX_SEND INFO 0 0"</t>
3489                                <t>S: "NAME: Reverb Send"</t>
3490                                <t>&nbsp;&nbsp;&nbsp;"MIDI_CONTROLLER: 91"</t>
3491                                <t>&nbsp;&nbsp;&nbsp;"LEVEL: 0.3"</t>
3492                                <t>&nbsp;&nbsp;&nbsp;"AUDIO_OUTPUT_ROUTING: 2,3"</t>
3493                                <t>&nbsp;&nbsp;&nbsp;"."</t>
3494                            </list>
3495                        </t>
3496                    </section>
3497    
3498                    <section title="Changing effect send's name" anchor="SET FX_SEND NAME">
3499                        <t>The front-end can alter the current name of an effect
3500                        send entity by sending the following command:</t>
3501                        <t>
3502                            <list>
3503                                <t>SET FX_SEND NAME &lt;sampler-chan&gt; &lt;fx-send-id&gt; &lt;name&gt;</t>
3504                            </list>
3505                        </t>
3506                        <t>Where &lt;sampler-chan&gt; is the sampler channel number
3507                        as returned by the <xref target="ADD CHANNEL">"ADD CHANNEL"</xref>
3508                        or <xref target="LIST CHANNELS">"LIST CHANNELS"</xref> command,
3509                        &lt;fx-send-id&gt; reflects the numerical ID of the effect send entity
3510                        as returned by the <xref target="CREATE FX_SEND">"CREATE FX_SEND"</xref>
3511                        or <xref target="LIST FX_SENDS">"LIST FX_SENDS"</xref> command and
3512                        &lt;name&gt; is the new name of the effect send entity, which
3513                        does not have to be unique (name MUST be encapsulated into apostrophes
3514                        and supports escape sequences as described in chapter
3515                        "<xref target="character_set">Character Set and Escape Sequences</xref>").
3516                        </t>
3517    
3518                        <t>Possible Answers:</t>
3519                        <t>
3520                            <list>
3521                                <t>"OK" -
3522                                    <list>
3523                                        <t>on success</t>
3524                                    </list>
3525                                </t>
3526                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
3527                                    <list>
3528                                        <t>in case it failed, providing an appropriate error code and error message</t>
3529                                    </list>
3530                                </t>
3531                            </list>
3532                        </t>
3533                        <t>Example:</t>
3534                        <t>
3535                            <list>
3536                                <t>C: "SET FX_SEND NAME 0 0 'Fx Send 1'"</t>
3537                                <t>S: "OK"</t>
3538                            </list>
3539                        </t>
3540                    </section>
3541    
3542                    <section title="Altering effect send's audio routing" anchor="SET FX_SEND AUDIO_OUTPUT_CHANNEL">
3543                        <t>The front-end can alter the destination of an effect send's audio channel on a specific
3544                        sampler channel by sending the following command:</t>
3545                        <t>
3546                            <list>
3547                                <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>
3548                            </list>
3549                        </t>
3550                        <t>Where &lt;sampler-chan&gt; is the sampler channel number
3551                        as returned by the <xref target="ADD CHANNEL">"ADD CHANNEL"</xref>
3552                        or <xref target="LIST CHANNELS">"LIST CHANNELS"</xref> command,
3553                        &lt;fx-send-id&gt; reflects the numerical ID of the effect send entity
3554                        as returned by the <xref target="CREATE FX_SEND">"CREATE FX_SEND"</xref>
3555                        or <xref target="LIST FX_SENDS">"LIST FX_SENDS"</xref> command,
3556                        &lt;audio-src&gt; is the numerical ID of the effect send's audio channel
3557                        which should be rerouted and &lt;audio-dst&gt; is the numerical ID of
3558                        the audio channel of the selected audio output device where &lt;audio-src&gt;
3559                        should be routed to.</t>
3560    
3561                        <t>Note that effect sends can only route audio to the same audio output
3562                        device as assigned to the effect send's sampler channel. Also note that an
3563                        effect send entity does always have exactly as much audio channels as its
3564                        sampler channel. So if the sampler channel is stereo, the effect send does
3565                        have two audio channels as well. Also keep in mind that the amount of audio
3566                        channels on a sampler channel might be dependant not only to the deployed
3567                        sampler engine on the sampler channel, but also dependant to the instrument
3568                        currently loaded. However you can (effectively) turn an i.e. stereo effect
3569                        send into a mono one by simply altering its audio routing appropriately.</t>
3570    
3571                        <t>Possible Answers:</t>
3572                        <t>
3573                            <list>
3574                                <t>"OK" -
3575                                    <list>
3576                                        <t>on success</t>
3577                                    </list>
3578                                </t>
3579                                <t>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
3580                                    <list>
3581                                        <t>if audio output channel was set, but there are noteworthy
3582                                        issue(s) related, providing an appropriate warning code and
3583                                        warning message</t>
3584                                    </list>
3585                                </t>
3586                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
3587                                    <list>
3588                                        <t>in case it failed, providing an appropriate error code and error message</t>
3589                                    </list>
3590                                </t>
3591                            </list>
3592                        </t>
3593                        <t>Example:</t>
3594                        <t>
3595                            <list>
3596                                <t>C: "SET FX_SEND AUDIO_OUTPUT_CHANNEL 0 0 0 2"</t>
3597                                <t>S: "OK"</t>
3598                            </list>
3599                        </t>
3600                    </section>
3601    
3602                    <section title="Altering effect send's MIDI controller" anchor="SET FX_SEND MIDI_CONTROLLER">
3603                        <t>The front-end can alter the MIDI controller of an effect
3604                        send entity by sending the following command:</t>
3605                        <t>
3606                            <list>
3607                                <t>SET FX_SEND MIDI_CONTROLLER &lt;sampler-chan&gt; &lt;fx-send-id&gt; &lt;midi-ctrl&gt;</t>
3608                            </list>
3609                        </t>
3610                        <t>Where &lt;sampler-chan&gt; is the sampler channel number
3611                        as returned by the <xref target="ADD CHANNEL">"ADD CHANNEL"</xref>
3612                        or <xref target="LIST CHANNELS">"LIST CHANNELS"</xref> command,
3613                        &lt;fx-send-id&gt; reflects the numerical ID of the effect send entity
3614                        as returned by the <xref target="CREATE FX_SEND">"CREATE FX_SEND"</xref>
3615                        or <xref target="LIST FX_SENDS">"LIST FX_SENDS"</xref> command and
3616                        &lt;midi-ctrl&gt; reflects the MIDI controller which shall be
3617                        able to modify the effect send's send level.</t>
3618    
3619                        <t>Possible Answers:</t>
3620                        <t>
3621                            <list>
3622                                <t>"OK" -
3623                                    <list>
3624                                        <t>on success</t>
3625                                    </list>
3626                                </t>
3627                                <t>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
3628                                    <list>
3629                                        <t>if MIDI controller was set, but there are noteworthy
3630                                        issue(s) related, providing an appropriate warning code and
3631                                        warning message</t>
3632                                    </list>
3633                                </t>
3634                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
3635                                    <list>
3636                                        <t>in case it failed, providing an appropriate error code and error message</t>
3637                                    </list>
3638                                </t>
3639                            </list>
3640                        </t>
3641                        <t>Example:</t>
3642                        <t>
3643                            <list>
3644                                <t>C: "SET FX_SEND MIDI_CONTROLLER 0 0 91"</t>
3645                                <t>S: "OK"</t>
3646                            </list>
3647                        </t>
3648                    </section>
3649    
3650                    <section title="Altering effect send's send level" anchor="SET FX_SEND LEVEL">
3651                        <t>The front-end can alter the current send level of an effect
3652                        send entity by sending the following command:</t>
3653                        <t>
3654                            <list>
3655                                <t>SET FX_SEND LEVEL &lt;sampler-chan&gt; &lt;fx-send-id&gt; &lt;volume&gt;</t>
3656                            </list>
3657                        </t>
3658                        <t>Where &lt;sampler-chan&gt; is the sampler channel number
3659                        as returned by the <xref target="ADD CHANNEL">"ADD CHANNEL"</xref>
3660                        or <xref target="LIST CHANNELS">"LIST CHANNELS"</xref> command,
3661                        &lt;fx-send-id&gt; reflects the numerical ID of the effect send entity
3662                        as returned by the <xref target="CREATE FX_SEND">"CREATE FX_SEND"</xref>
3663                        or <xref target="LIST FX_SENDS">"LIST FX_SENDS"</xref> command and
3664                        &lt;volume&gt; is an optionally dotted positive number (a value
3665                        smaller than 1.0 means attenuation, whereas a value greater than
3666                        1.0 means amplification) reflecting the new send level.</t>
3667    
3668                        <t>Possible Answers:</t>
3669                        <t>
3670                            <list>
3671                                <t>"OK" -
3672                                    <list>
3673                                        <t>on success</t>
3674                                    </list>
3675                                </t>
3676                                <t>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
3677                                    <list>
3678                                        <t>if new send level was set, but there are noteworthy
3679                                        issue(s) related, providing an appropriate warning code and
3680                                        warning message</t>
3681                                    </list>
3682                                </t>
3683                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
3684                                    <list>
3685                                        <t>in case it failed, providing an appropriate error code and error message</t>
3686                                    </list>
3687                                </t>
3688                            </list>
3689                        </t>
3690                        <t>Example:</t>
3691                        <t>
3692                            <list>
3693                                <t>C: "SET FX_SEND LEVEL 0 0 0.15"</t>
3694                                <t>S: "OK"</t>
3695                            </list>
3696                        </t>
3697                    </section>
3698    
3699                  <section title="Resetting a sampler channel" anchor="RESET CHANNEL">                  <section title="Resetting a sampler channel" anchor="RESET CHANNEL">
3700                      <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>
3701                      <t>                      <t>
# Line 3495  Schoenebeck'> Line 3964  Schoenebeck'>
3964                                  <list>                                  <list>
3965                                      <t>DESCRIPTION -                                      <t>DESCRIPTION -
3966                                          <list>                                          <list>
3967                                              <t>arbitrary textual description about the sampler</t>                                              <t>arbitrary textual description about the sampler
3968                                                (note that the character string may contain
3969                                                <xref target="character_set">escape sequences</xref>)</t>
3970                                          </list>                                          </list>
3971                                      </t>                                      </t>
3972                                      <t>VERSION -                                      <t>VERSION -
# Line 3509  Schoenebeck'> Line 3980  Schoenebeck'>
3980                                              complies with (see <xref target="LSCP versioning" /> for details)</t>                                              complies with (see <xref target="LSCP versioning" /> for details)</t>
3981                                          </list>                                          </list>
3982                                      </t>                                      </t>
3983                                        <t>INSTRUMENTS_DB_SUPPORT -
3984                                            <list>
3985                                                <t>either yes or no, specifies whether the
3986                                                sampler is build with instruments database support.</t>
3987                                            </list>
3988                                        </t>
3989                                  </list>                                  </list>
3990                              </t>                              </t>
3991                          </list>                          </list>
# Line 3516  Schoenebeck'> Line 3993  Schoenebeck'>
3993                      <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.
3994                      Other fields might be added in future.</t>                      Other fields might be added in future.</t>
3995                  </section>                  </section>
3996    
3997                    <section title="Getting global volume attenuation" anchor="GET VOLUME">
3998                        <t>The client can ask for the current global sampler-wide volume
3999                        attenuation by sending the following command:</t>
4000                        <t>
4001                            <list>
4002                                <t>GET VOLUME</t>
4003                            </list>
4004                        </t>
4005                        <t>Possible Answers:</t>
4006                        <t>
4007                            <list>
4008                                <t>The sampler will always answer by returning the optional
4009                                dotted floating point coefficient, reflecting the current
4010                                global volume attenuation.
4011                                </t>
4012                            </list>
4013                        </t>
4014                        <t>Note: it is up to the respective sampler engine whether to obey
4015                        that global volume parameter or not, but in general all engines SHOULD
4016                        use this parameter.</t>
4017                    </section>
4018    
4019                    <section title="Setting global volume attenuation" anchor="SET VOLUME">
4020                        <t>The client can alter the current global sampler-wide volume
4021                        attenuation by sending the following command:</t>
4022                        <t>
4023                            <list>
4024                                <t>SET VOLUME &lt;volume&gt;</t>
4025                            </list>
4026                        </t>
4027                       <t>Where &lt;volume&gt; should be replaced by the optional dotted
4028                       floating point value, reflecting the new global volume parameter.
4029                       This value might usually be in the range between 0.0 and 1.0, that
4030                       is for attenuating the overall volume.</t>
4031    
4032                        <t>Possible Answers:</t>
4033                        <t>
4034                            <list>
4035                                <t>"OK" -
4036                                    <list>
4037                                        <t>on success</t>
4038                                    </list>
4039                                </t>
4040                                <t>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
4041                                    <list>
4042                                        <t>if the global volume was set, but there are noteworthy
4043                                        issue(s) related, providing an appropriate warning code and
4044                                        warning message</t>
4045                                    </list>
4046                                </t>
4047                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
4048                                    <list>
4049                                        <t>in case it failed, providing an appropriate error code and error message</t>
4050                                    </list>
4051                                </t>
4052                            </list>
4053                        </t>
4054                    </section>
4055              </section>              </section>
4056    
4057    
# Line 3546  Schoenebeck'> Line 4082  Schoenebeck'>
4082                  cause the sampler to switch to the respective instrument as                  cause the sampler to switch to the respective instrument as
4083                  reflected by the current MIDI instrument map.</t>                  reflected by the current MIDI instrument map.</t>
4084    
4085                  <section title="Create a new MIDI instrument map" anchor="ADD MIDI_INSTRUMENT MAP">                  <section title="Create a new MIDI instrument map" anchor="ADD MIDI_INSTRUMENT_MAP">
4086                      <t>The front-end can add a new MIDI instrument map by sending                      <t>The front-end can add a new MIDI instrument map by sending
4087                      the following command:</t>                      the following command:</t>
4088                      <t>                      <t>
# Line 3556  Schoenebeck'> Line 4092  Schoenebeck'>
4092                      </t>                      </t>
4093                      <t>Where &lt;name&gt; is an optional argument allowing to                      <t>Where &lt;name&gt; is an optional argument allowing to
4094                      assign a custom name to the new map. MIDI instrument Map                      assign a custom name to the new map. MIDI instrument Map
4095                      names do not have to be unique.</t>                      names do not have to be unique, but MUST be encapsulated
4096                        into apostrophes and support escape sequences as described
4097                        in chapter "<xref target="character_set">Character Set and Escape Sequences</xref>".
4098                        </t>
4099    
4100                      <t>Possible Answers:</t>                      <t>Possible Answers:</t>
4101                      <t>                      <t>
# Line 3730  Schoenebeck'> Line 4269  Schoenebeck'>
4269                                              which does not have to be unique</t>                                              which does not have to be unique</t>
4270                                          </list>                                          </list>
4271                                      </t>                                      </t>
4272                                        <t>DEFAULT -
4273                                            <list>
4274                                                <t>either true or false,
4275                                                defines whether this map is the default map</t>
4276                                            </list>
4277                                        </t>
4278                                  </list>                                  </list>
4279                              </t>                              </t>
4280                          </list>                          </list>
# Line 3741  Schoenebeck'> Line 4286  Schoenebeck'>
4286                          <list>                          <list>
4287                              <t>C: "GET MIDI_INSTRUMENT_MAP INFO 0"</t>                              <t>C: "GET MIDI_INSTRUMENT_MAP INFO 0"</t>
4288                              <t>S: "NAME: Standard Map"</t>                              <t>S: "NAME: Standard Map"</t>
4289                                <t>&nbsp;&nbsp;&nbsp;"DEFAULT: true"</t>
4290                              <t>&nbsp;&nbsp;&nbsp;"."</t>                              <t>&nbsp;&nbsp;&nbsp;"."</t>
4291                          </list>                          </list>
4292                      </t>                      </t>
# Line 3756  Schoenebeck'> Line 4302  Schoenebeck'>
4302                      </t>                      </t>
4303                      <t>Where &lt;map&gt; is the numerical ID of the map and                      <t>Where &lt;map&gt; is the numerical ID of the map and
4304                      &lt;name&gt; the new custom name of the map, which does not                      &lt;name&gt; the new custom name of the map, which does not
4305                      have to be unique.</t>                      have to be unique (name MUST be encapsulated into apostrophes
4306                        and supports escape sequences as described in chapter
4307                        "<xref target="character_set">Character Set and Escape Sequences</xref>").
4308                        </t>
4309    
4310                      <t>Possible Answers:</t>                      <t>Possible Answers:</t>
4311                      <t>                      <t>
# Line 3789  Schoenebeck'> Line 4338  Schoenebeck'>
4338                      command:</t>                      command:</t>
4339                      <t>                      <t>
4340                          <list>                          <list>
4341                              <t>MAP MIDI_INSTRUMENT &lt;map&gt;                              <t>MAP MIDI_INSTRUMENT [NON_MODAL] &lt;map&gt;
4342                              &lt;midi_bank&gt; &lt;midi_prog&gt; &lt;engine_name&gt;                              &lt;midi_bank&gt; &lt;midi_prog&gt; &lt;engine_name&gt;
4343                              &lt;filename&gt; &lt;instrument_index&gt; &lt;volume_value&gt;                              &lt;filename&gt; &lt;instrument_index&gt; &lt;volume_value&gt;
4344                              [&lt;instr_load_mode&gt;] [&lt;name&gt;]</t>                              [&lt;instr_load_mode&gt;] [&lt;name&gt;]</t>
# Line 3803  Schoenebeck'> Line 4352  Schoenebeck'>
4352                      index, &lt;engine_name&gt; a sampler engine name as returned by                      index, &lt;engine_name&gt; a sampler engine name as returned by
4353                      the <xref target="LIST AVAILABLE_ENGINES">"LIST AVAILABLE_ENGINES"</xref>                      the <xref target="LIST AVAILABLE_ENGINES">"LIST AVAILABLE_ENGINES"</xref>
4354                      command (not encapsulated into apostrophes), &lt;filename&gt; the name                      command (not encapsulated into apostrophes), &lt;filename&gt; the name
4355                      of the instrument's file to be deployed (encapsulated into apostrophes),                      of the instrument's file to be deployed (encapsulated into apostrophes,
4356                        supporting escape sequences as described in chapter
4357                        "<xref target="character_set">Character Set and Escape Sequences</xref>"),
4358                      &lt;instrument_index&gt; the index (integer value) of the instrument                      &lt;instrument_index&gt; the index (integer value) of the instrument
4359                      within the given file, &lt;volume_value&gt; reflects the master                      within the given file, &lt;volume_value&gt; reflects the master
4360                      volume of the instrument as optionally dotted number (where a                      volume of the instrument as optionally dotted number (where a
4361                      value < 1.0 means attenuation and a value > 1.0 means                      value &lt; 1.0 means attenuation and a value > 1.0 means
4362                      amplification). This parameter easily allows to adjust the                      amplification). This parameter easily allows to adjust the
4363                      volume of all intruments within a custom instrument map                      volume of all intruments within a custom instrument map
4364                      without having to adjust their instrument files. The                      without having to adjust their instrument files. The
# Line 3842  Schoenebeck'> Line 4393  Schoenebeck'>
4393                              <t>"PERSISTENT" -                              <t>"PERSISTENT" -
4394                                  <list>                                  <list>
4395                                      <t>The instrument will immediately be loaded                                      <t>The instrument will immediately be loaded
4396                                      into memory in the background when this mapping                                      into memory when this mapping
4397                                      command is sent and the instrument is kept all                                      command is sent and the instrument is kept all
4398                                      the time. Instruments with this mode are                                      the time. Instruments with this mode are
4399                                      only freed when the sampler is reset or all                                      only freed when the sampler is reset or all
# Line 3885  Schoenebeck'> Line 4436  Schoenebeck'>
4436                      load modes of entries, the frontend should retrieve the actual                      load modes of entries, the frontend should retrieve the actual
4437                      mode by i.e. sending                      mode by i.e. sending
4438                      <xref target="GET MIDI_INSTRUMENT INFO">"GET MIDI_INSTRUMENT INFO"</xref>                      <xref target="GET MIDI_INSTRUMENT INFO">"GET MIDI_INSTRUMENT INFO"</xref>
4439                      command(s). Finally the OPTIONAL &lt;name&gt; argument allows to                      command(s). Finally the OPTIONAL &lt;name&gt; argument allows to set a custom name
4440                      set a custom name (encapsulated into apostrophes) for the mapping                      (encapsulated into apostrophes, supporting escape sequences as described in chapter
4441                      entry, useful for frontends for displaying an appropriate name for                      "<xref target="character_set">Character Set and Escape Sequences</xref>") for the
4442                        mapping entry, useful for frontends for displaying an appropriate name for
4443                      mapped instruments (using                      mapped instruments (using
4444                      <xref target="GET MIDI_INSTRUMENT INFO">"GET MIDI_INSTRUMENT INFO"</xref>).                      <xref target="GET MIDI_INSTRUMENT INFO">"GET MIDI_INSTRUMENT INFO"</xref>).
4445                      </t>                      </t>
4446                      <t>                      <t>
4447                      The "MAP MIDI_INSTRUMENT" command                      By default, "MAP MIDI_INSTRUMENT" commands block until the mapping is
4448                      will immediately return, thus it will not block when an                      completely established in the sampler. The OPTIONAL "NON_MODAL" argument
4449                      instrument is to be loaded due to a "PERSISTENT" type                      however causes the respective "MAP MIDI_INSTRUMENT" command to return
4450                      entry as instruments are loaded in the background. As a                      immediately, that is to let the sampler establish the mapping in the
4451                      consequence this command may not necessarily return an error                      background. So this argument might be especially useful for mappings with
4452                      i.e. when the given instrument file does not exist or may                      a "PERSISTENT" type, because these have to load the respective instruments
4453                      turn out to be corrupt.                      immediately and might thus block for a very long time. It is recommended
4454                        however to use the OPTIONAL "NON_MODAL" argument only if really necessary,
4455                        because it has the following drawbacks: as "NON_MODAL" instructions return
4456                        immediately, they may not necessarily return an error i.e. when the given
4457                        instrument file turns out to be corrupt, beside that subsequent commands
4458                        in a LSCP instruction sequence might fail, because mandatory mappings are
4459                        not yet completed.
4460                      </t>                      </t>
4461    
4462                      <t>Possible Answers:</t>                      <t>Possible Answers:</t>
# Line 3941  Schoenebeck'> Line 4499  Schoenebeck'>
4499                      </t>                      </t>
4500                      <t>                      <t>
4501                          <list>                          <list>
4502                              <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>
4503                              <t>S: "OK"</t>                              <t>S: "OK"</t>
4504                          </list>                          </list>
4505                      </t>                      </t>
# Line 4140  Schoenebeck'> Line 4698  Schoenebeck'>
4698                              <t>"VOLUME" -                              <t>"VOLUME" -
4699                                  <list>                                  <list>
4700                                      <t>master volume of the instrument as optionally                                      <t>master volume of the instrument as optionally
4701                                      dotted number (where a value < 1.0 means attenuation                                      dotted number (where a value &lt; 1.0 means attenuation
4702                                      and a value > 1.0 means amplification)</t>                                      and a value > 1.0 means amplification)</t>
4703                                  </list>                                  </list>
4704                              </t>                              </t>
# Line 4212  Schoenebeck'> Line 4770  Schoenebeck'>
4770                  </section>                  </section>
4771              </section>              </section>
4772    
4773    
4774                <section title="Managing Instruments Database" anchor="Managing Instruments Database">
4775                    <t>The following commands describe how to use and manage
4776                    the instruments database.</t>
4777                    <t>Notice:</t>
4778                        <t>
4779                            <list>
4780                                <t>All command arguments representing a path or
4781                                instrument/directory name support escape sequences as described in chapter
4782                                "<xref target="character_set">Character Set and Escape Sequences</xref>".
4783                                </t>
4784                                <t>All occurrences of a forward slash in instrument and directory
4785                                   names are escaped with its hex (\x2f) or octal (\057) escape sequence.
4786                                </t>
4787                            </list>
4788                        </t>
4789    
4790                    <section title="Creating a new instrument directory" anchor="ADD DB_INSTRUMENT_DIRECTORY">
4791                        <t>The front-end can add a new instrument directory to the
4792                        instruments database by sending the following command:</t>
4793                        <t>
4794                            <list>
4795                                <t>ADD DB_INSTRUMENT_DIRECTORY &lt;dir&gt;</t>
4796                            </list>
4797                        </t>
4798                        <t>Where &lt;dir&gt; is the absolute path name of the directory
4799                        to be created (encapsulated into apostrophes).</t>
4800    
4801                        <t>Possible Answers:</t>
4802                        <t>
4803                            <list>
4804                                <t>"OK" -
4805                                    <list>
4806                                        <t>on success</t>
4807                                    </list>
4808                                </t>
4809                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
4810                                    <list>
4811                                        <t>when the directory could not be created, which
4812                                        can happen if the directory already exists or the
4813                                        name contains not allowed symbols</t>
4814                                    </list>
4815                                </t>
4816                            </list>
4817                        </t>
4818    
4819                        <t>Examples:</t>
4820                        <t>
4821                            <list>
4822                                <t>C: "ADD DB_INSTRUMENT_DIRECTORY '/Piano Collection'"</t>
4823                                <t>S: "OK"</t>
4824                            </list>
4825                        </t>
4826                    </section>
4827    
4828                    <section title="Deleting an instrument directory" anchor="REMOVE DB_INSTRUMENT_DIRECTORY">
4829                        <t>The front-end can delete a particular instrument directory
4830                        from the instruments database by sending the following command:</t>
4831                        <t>
4832                            <list>
4833                                <t>REMOVE DB_INSTRUMENT_DIRECTORY [FORCE] &lt;dir&gt;</t>
4834                            </list>
4835                        </t>
4836                        <t>Where &lt;dir&gt; is the absolute path name of the directory
4837                        to delete. The optional FORCE argument can be used to
4838                        force the deletion of a non-empty directory and all its content.</t>
4839    
4840                        <t>Possible Answers:</t>
4841                        <t>
4842                            <list>
4843                                <t>"OK" -
4844                                    <list>
4845                                        <t>if the directory is deleted successfully</t>
4846                                    </list>
4847                                </t>
4848                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
4849                                    <list>
4850                                        <t>if the given directory does not exist, or
4851                                        if trying to delete a non-empty directory,
4852                                        without using the FORCE argument.</t>
4853                                    </list>
4854                                </t>
4855                            </list>
4856                        </t>
4857    
4858                        <t>Examples:</t>
4859                        <t>
4860                            <list>
4861                                <t>C: "REMOVE DB_INSTRUMENT_DIRECTORY FORCE '/Piano Collection'"</t>
4862                                <t>S: "OK"</t>
4863                            </list>
4864                        </t>
4865                    </section>
4866    
4867                    <section title="Getting amount of instrument directories" anchor="GET DB_INSTRUMENT_DIRECTORIES">
4868                        <t>The front-end can retrieve the current amount of
4869                        directories in a specific directory by sending the following command:</t>
4870                        <t>
4871                            <list>
4872                                <t>GET DB_INSTRUMENT_DIRECTORIES [RECURSIVE] &lt;dir&gt;</t>
4873                            </list>
4874                        </t>
4875                        <t>Where &lt;dir&gt; should be replaced by the absolute path
4876                        name of the directory. If RECURSIVE is specified, the number of
4877                        all directories, including those located in subdirectories of the
4878                        specified directory, will be returned.</t>
4879    
4880                        <t>Possible Answers:</t>
4881                        <t>
4882                            <list>
4883                                <t>The current number of instrument directories
4884                                in the specified directory.</t>
4885                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
4886                                    <list>
4887                                        <t>if the given directory does not exist.</t>
4888                                    </list>
4889                                </t>
4890                            </list>
4891                        </t>
4892    
4893                        <t>Example:</t>
4894                        <t>
4895                            <list>
4896                                <t>C: "GET DB_INSTRUMENT_DIRECTORIES '/'"</t>
4897                                <t>S: "2"</t>
4898                            </list>
4899                        </t>
4900                    </section>
4901    
4902                    <section title="Listing all directories in specific directory" anchor="LIST DB_INSTRUMENT_DIRECTORIES">
4903                        <t>The front-end can retrieve the current list of directories
4904                        in specific directory by sending the following command:</t>
4905                        <t>
4906                            <list>
4907                                <t>LIST DB_INSTRUMENT_DIRECTORIES [RECURSIVE] &lt;dir&gt;</t>
4908                            </list>
4909                        </t>
4910                        <t>Where &lt;dir&gt; should be replaced by the absolute path
4911                        name of the directory. If RECURSIVE is specified, the absolute path names
4912                        of all directories, including those located in subdirectories of the
4913                        specified directory, will be returned.</t>
4914    
4915                        <t>Possible Answers:</t>
4916                        <t>
4917                            <list>
4918                                <t>A comma separated list of all instrument directories
4919                                (encapsulated into apostrophes) in the specified directory.</t>
4920                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
4921                                    <list>
4922                                        <t>if the given directory does not exist.</t>
4923                                    </list>
4924                                </t>
4925                            </list>
4926                        </t>
4927                        <t>Example:</t>
4928                        <t>
4929                            <list>
4930                                <t>C: "LIST DB_INSTRUMENT_DIRECTORIES '/'"</t>
4931                                <t>S: "'Piano Collection','Percussion Collection'"</t>
4932                            </list>
4933                        </t>
4934                        <t>
4935                            <list>
4936                                <t>C: "LIST DB_INSTRUMENT_DIRECTORIES RECURSIVE '/'"</t>
4937                                <t>S: "'/Piano Collection','/Piano Collection/Acoustic','/Piano Collection/Acoustic/New','/Percussion Collection'"</t>
4938                            </list>
4939                        </t>
4940                    </section>
4941    
4942                    <section title="Getting instrument directory information" anchor="GET DB_INSTRUMENT_DIRECTORY INFO">
4943                        <t>The front-end can ask for the current settings of an
4944                        instrument directory by sending the following command:</t>
4945                        <t>
4946                            <list>
4947                                <t>GET DB_INSTRUMENT_DIRECTORY INFO &lt;dir&gt;</t>
4948                            </list>
4949                        </t>
4950                        <t>Where &lt;dir&gt; should be replaced by the absolute path
4951                        name of the directory the front-end is interested in.</t>
4952    
4953                        <t>Possible Answers:</t>
4954                        <t>
4955                            <list>
4956                                <t>LinuxSampler will answer by sending a &lt;CRLF&gt; separated list.
4957                                Each answer line begins with the settings category name
4958                                followed by a colon and then a space character &lt;SP&gt; and finally
4959                                the info character string to that setting category. At the
4960                                moment the following categories are defined:</t>
4961    
4962                                <t>
4963                                    <list>
4964                                        <t>DESCRIPTION -
4965                                            <list>
4966                                                <t>A brief description of the directory content.
4967                                                Note that the character string may contain
4968                                                <xref target="character_set">escape sequences</xref>.</t>
4969                                            </list>
4970                                        </t>
4971                                        <t>CREATED -
4972                                            <list>
4973                                                <t>The creation date and time of the directory,
4974                                                represented in "YYYY-MM-DD HH:MM:SS" format</t>
4975                                            </list>
4976                                        </t>
4977                                        <t>MODIFIED -
4978                                            <list>
4979                                                <t>The date and time of the last modification of the
4980                                                directory, represented in "YYYY-MM-DD HH:MM:SS" format</t>
4981                                            </list>
4982                                        </t>
4983                                    </list>
4984                                </t>
4985                            </list>
4986                        </t>
4987                        <t>The mentioned fields above don't have to be in particular order.</t>
4988    
4989                        <t>Example:</t>
4990                        <t>
4991                            <list>
4992                                <t>C: "GET DB_INSTRUMENT_DIRECTORY INFO '/Piano Collection'"</t>
4993                                <t>S: "DESCRIPTION: Piano collection of instruments in GigaSampler format."</t>
4994                                <t>&nbsp;&nbsp;&nbsp;"CREATED: 2007-02-05 10:23:12"</t>
4995                                <t>&nbsp;&nbsp;&nbsp;"MODIFIED: 2007-04-07 12:50:21"</t>
4996                                <t>&nbsp;&nbsp;&nbsp;"."</t>
4997                            </list>
4998                        </t>
4999                    </section>
5000    
5001                    <section title="Renaming an instrument directory" anchor="SET DB_INSTRUMENT_DIRECTORY NAME">
5002                        <t>The front-end can alter the name of a specific
5003                        instrument directory by sending the following command:</t>
5004                        <t>
5005                            <list>
5006                                <t>SET DB_INSTRUMENT_DIRECTORY NAME &lt;dir&gt; &lt;name&gt;</t>
5007                            </list>
5008                        </t>
5009                        <t>Where &lt;dir&gt; is the absolute path name of the directory and
5010                        &lt;name&gt; is the new name for that directory.</t>
5011    
5012                        <t>Possible Answers:</t>
5013                        <t>
5014                            <list>
5015                                <t>"OK" -
5016                                    <list>
5017                                        <t>on success</t>
5018                                    </list>
5019                                </t>
5020                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
5021                                    <list>
5022                                        <t>in case the given directory does not exists,
5023                                        or if a directory with name equal to the new
5024                                        name already exists.</t>
5025                                    </list>
5026                                </t>
5027                            </list>
5028                        </t>
5029    
5030                        <t>Example:</t>
5031                        <t>
5032                            <list>
5033                                <t>C: "SET DB_INSTRUMENT_DIRECTORY NAME '/Piano Collection/Acustic' 'Acoustic'"</t>
5034                                <t>S: "OK"</t>
5035                            </list>
5036                        </t>
5037                    </section>
5038    
5039                    <section title="Moving an instrument directory" anchor="MOVE DB_INSTRUMENT_DIRECTORY">
5040                        <t>The front-end can move a specific
5041                        instrument directory by sending the following command:</t>
5042                        <t>
5043                            <list>
5044                                <t>MOVE DB_INSTRUMENT_DIRECTORY &lt;dir&gt; &lt;dst&gt;</t>
5045                            </list>
5046                        </t>
5047                        <t>Where &lt;dir&gt; is the absolute path name of the directory
5048                        to move and &lt;dst&gt; is the location where the directory will
5049                        be moved to.</t>
5050    
5051                        <t>Possible Answers:</t>
5052                        <t>
5053                            <list>
5054                                <t>"OK" -
5055                                    <list>
5056                                        <t>on success</t>
5057                                    </list>
5058                                </t>
5059                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
5060                                    <list>
5061                                        <t>in case a given directory does not exists,
5062                                        or if a directory with name equal to the name
5063                                        of the specified directory already exists in
5064                                        the destination directory. Error is also thrown
5065                                        when trying to move a directory to a subdirectory
5066                                        of itself.</t>
5067                                    </list>
5068                                </t>
5069                            </list>
5070                        </t>
5071    
5072                        <t>Example:</t>
5073                        <t>
5074                            <list>
5075                                <t>C: "MOVE DB_INSTRUMENT_DIRECTORY '/Acoustic' '/Piano Collection/Acoustic'"</t>
5076                                <t>S: "OK"</t>
5077                            </list>
5078                        </t>
5079                    </section>
5080    
5081                    <section title="Copying instrument directories" anchor="COPY DB_INSTRUMENT_DIRECTORY">
5082                        <t>The front-end can copy a specific
5083                        instrument directory by sending the following command:</t>
5084                        <t>
5085                            <list>
5086                                <t>COPY DB_INSTRUMENT_DIRECTORY &lt;dir&gt; &lt;dst&gt;</t>
5087                            </list>
5088                        </t>
5089                        <t>Where &lt;dir&gt; is the absolute path name of the directory
5090                        to copy and &lt;dst&gt; is the location where the directory will
5091                        be copied to.</t>
5092    
5093                        <t>Possible Answers:</t>
5094                        <t>
5095                            <list>
5096                                <t>"OK" -
5097                                    <list>
5098                                        <t>on success</t>
5099                                    </list>
5100                                </t>
5101                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
5102                                    <list>
5103                                        <t>in case a given directory does not exists,
5104                                        or if a directory with name equal to the name
5105                                        of the specified directory already exists in
5106                                        the destination directory. Error is also thrown
5107                                        when trying to copy a directory to a subdirectory
5108                                        of itself.</t>
5109                                    </list>
5110                                </t>
5111                            </list>
5112                        </t>
5113    
5114                        <t>Example:</t>
5115                        <t>
5116                            <list>
5117                                <t>C: "COPY DB_INSTRUMENT_DIRECTORY '/Piano Collection/Acoustic' '/Acoustic/Pianos'"</t>
5118                                <t>S: "OK"</t>
5119                            </list>
5120                        </t>
5121                    </section>
5122    
5123                    <section title="Changing the description of directory" anchor="SET DB_INSTRUMENT_DIRECTORY DESCRIPTION">
5124                        <t>The front-end can alter the description of a specific
5125                        instrument directory by sending the following command:</t>
5126                        <t>
5127                            <list>
5128                                <t>SET DB_INSTRUMENT_DIRECTORY DESCRIPTION &lt;dir&gt; &lt;desc&gt;</t>
5129                            </list>
5130                        </t>
5131                        <t>Where &lt;dir&gt; is the absolute path name of the directory and
5132                        &lt;desc&gt; is the new description for the directory
5133                        (encapsulated into apostrophes, supporting escape sequences as described in chapter
5134                        "<xref target="character_set">Character Set and Escape Sequences</xref>").</t>
5135    
5136                        <t>Possible Answers:</t>
5137                        <t>
5138                            <list>
5139                                <t>"OK" -
5140                                    <list>
5141                                        <t>on success</t>
5142                                    </list>
5143                                </t>
5144                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
5145                                    <list>
5146                                        <t>in case the given directory does not exists.</t>
5147                                    </list>
5148                                </t>
5149                            </list>
5150                        </t>
5151    
5152                        <t>Example:</t>
5153                        <t>
5154                            <list>
5155                                <t>C: "SET DB_INSTRUMENT_DIRECTORY DESCRIPTION '/Piano Collection' 'A collection of piano instruments in various format.'"</t>
5156                                <t>S: "OK"</t>
5157                            </list>
5158                        </t>
5159                    </section>
5160    
5161                    <section title="Finding directories" anchor="FIND DB_INSTRUMENT_DIRECTORIES">
5162                        <t>The front-end can search for directories
5163                        in specific directory by sending the following command:</t>
5164                        <t>
5165                            <list>
5166                                <t>FIND DB_INSTRUMENT_DIRECTORIES [NON_RECURSIVE] &lt;dir&gt; &lt;criteria-list&gt;</t>
5167                            </list>
5168                        </t>
5169                        <t>Where &lt;dir&gt; should be replaced by the absolute path
5170                        name of the directory to search in. If NON_RECURSIVE is specified, the
5171                        directories located in subdirectories of the specified directory will not
5172                        be searched. &lt;criteria-list&gt; is a list of search criterias
5173                        in form of "key1=val1 key2=val2 ...". The following criterias are
5174                        allowed:</t>
5175                        <t>
5176                          <t>NAME='&lt;search-string&gt;'
5177                              <list>
5178                                  <t>Restricts the search to directories, which names
5179                                  satisfy the supplied search string (encapsulated into apostrophes,
5180                                  supporting escape sequences as described in chapter
5181                                  "<xref target="character_set">Character Set and Escape Sequences</xref>").</t>
5182                              </list>
5183                          </t>
5184    
5185                          <t>CREATED='[&lt;date-after&gt;]..[&lt;date-before&gt;]'
5186                              <list>
5187                                  <t>Restricts the search to directories, which creation
5188                                  date satisfies the specified period, where &lt;date-after&gt;
5189                                  and &lt;date-before&gt; are in "YYYY-MM-DD HH:MM:SS" format.
5190                                  If &lt;date-after&gt; is omitted the search is restricted to
5191                                  directories created before &lt;date-before&gt;. If
5192                                  &lt;date-before&gt; is omitted, the search is restricted
5193                                  to directories created after &lt;date-after&gt;.</t>
5194                              </list>
5195                          </t>
5196    
5197                          <t>MODIFIED='[&lt;date-after&gt;]..[&lt;date-before&gt;]'
5198                              <list>
5199                                  <t>Restricts the search to directories, which
5200                                  date of last modification satisfies the specified period, where
5201                                  &lt;date-after&gt; and &lt;date-before&gt; are in "YYYY-MM-DD HH:MM:SS"
5202                                  format. If &lt;date-after&gt; is omitted the search is restricted to
5203                                  directories, which are last modified before &lt;date-before&gt;. If
5204                                  &lt;date-before&gt; is omitted, the search is restricted to directories,
5205                                  which are last modified after &lt;date-after&gt;.</t>
5206                              </list>
5207                          </t>
5208    
5209                          <t>DESCRIPTION='&lt;search-string&gt;'
5210                              <list>
5211                                  <t>Restricts the search to directories with description
5212                                  that satisfies the supplied search string
5213                                  (encapsulated into apostrophes, supporting escape
5214                                  sequences as described in chapter
5215                                  "<xref target="character_set">Character Set and Escape Sequences</xref>").</t>
5216                              </list>
5217                          </t>
5218                        </t>
5219    
5220                        <t>Where &lt;search-string&gt; is either a regular expression, or a
5221                        word list separated with spaces for OR search and with '+' for AND search.</t>
5222    
5223                        <t>Possible Answers:</t>
5224                        <t>
5225                            <list>
5226                                <t>A comma separated list with the absolute path names (encapsulated into
5227                                apostrophes) of all directories in the specified directory that satisfy
5228                                the supplied search criterias.</t>
5229                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
5230                                    <list>
5231                                        <t>if the given directory does not exist.</t>
5232                                    </list>
5233                                </t>
5234                            </list>
5235                        </t>
5236                        <t>Example:</t>
5237                        <t>
5238                            <list>
5239                                <t>C: "FIND DB_INSTRUMENT_DIRECTORIES '/' NAME='Piano'"</t>
5240                                <t>S: "'/Piano Collection'"</t>
5241                            </list>
5242                        </t>
5243                        <t>
5244                            <list>
5245                                <t>C: "FIND DB_INSTRUMENT_DIRECTORIES '/' CREATED='..2007-04-01 09:30:13'"</t>
5246                                <t>S: "'/Piano Collection','/Percussions'"</t>
5247                            </list>
5248                        </t>
5249                    </section>
5250    
5251                    <section title="Adding instruments to the instruments database" anchor="ADD DB_INSTRUMENTS">
5252                        <t>The front-end can add one or more instruments
5253                        to the instruments database by sending the following command:</t>
5254                        <t>
5255                            <list>
5256                                <t>ADD DB_INSTRUMENTS [NON_MODAL] [&lt;mode&gt;] &lt;db_dir&gt; &lt;file_path&gt; [&lt;instr_index&gt;]</t>
5257                            </list>
5258                        </t>
5259                        <t>Where &lt;db_dir&gt; is the absolute path name of a directory
5260                        (encapsulated into apostrophes) in the instruments database in which
5261                        only the new instruments (that are not already in the database) will
5262                        be added, &lt;file_path&gt; is the absolute path name of a file or
5263                        directory in the file system (encapsulated into apostrophes). In case
5264                        an instrument file is supplied, only the instruments in the specified
5265                        file will be added to the instruments database. If the optional
5266                        &lt;instr_index&gt; (the index of the instrument within the given file)
5267                        is supplied too, then only the specified instrument will be added.
5268                        In case a directory is supplied, the instruments in that directory
5269                        will be added. The OPTIONAL &lt;mode&gt; argument is only applied
5270                        when a directory is provided as &lt;file_path&gt; and specifies how the
5271                        scanning will be done and has exactly the following possibilities:</t>
5272                        <t>
5273                            <list>
5274                                <t>"RECURSIVE" -
5275                                    <list>
5276                                        <t>All instruments will be processed, including those
5277                                        in the subdirectories, and the respective subdirectory
5278                                        tree structure will be recreated in the instruments
5279                                        database</t>
5280                                    </list>
5281                                </t>
5282                                <t>"NON_RECURSIVE" -
5283                                    <list>
5284                                        <t>Only the instruments in the specified directory
5285                                        will be added, the instruments in the subdirectories
5286                                        will not be processed.</t>
5287                                    </list>
5288                                </t>
5289                                <t>"FLAT" -
5290                                    <list>
5291                                        <t>All instruments will be processed, including those
5292                                        in the subdirectories, but the respective subdirectory
5293                                        structure will not be recreated in the instruments
5294                                        database. All instruments will be added directly in
5295                                        the specified database directory.</t>
5296                                    </list>
5297                                </t>
5298                            </list>
5299                        </t>
5300    
5301                     <t>The difference between regular and NON_MODAL versions of the command
5302                        is that the regular command returns when the scanning is finished
5303                        while NON_MODAL version returns immediately and a background process is launched.
5304                        The <xref target="GET DB_INSTRUMENTS_JOB INFO">GET DB_INSTRUMENTS_JOB INFO</xref>
5305                        command can be used to monitor the scanning progress.</t>
5306    
5307                        <t>Possible Answers:</t>
5308                        <t>
5309                            <list>
5310                                <t>"OK" -
5311                                    <list>
5312                                        <t>on success when NON_MODAL is not supplied</t>
5313                                    </list>
5314                                </t>
5315                                <t>"OK[&lt;job-id&gt;]" -
5316                                    <list>
5317                                        <t>on success when NON_MODAL is supplied, where &lt;job-id&gt;
5318                                        is a numerical ID used to obtain status information about the job progress.
5319                                        See <xref target="GET DB_INSTRUMENTS_JOB INFO">GET DB_INSTRUMENTS_JOB INFO</xref>
5320                                        </t>
5321                                    </list>
5322                                </t>
5323                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
5324                                    <list>
5325                                        <t>if an invalid path is specified.</t>
5326                                    </list>
5327                                </t>
5328                            </list>
5329                        </t>
5330    
5331                        <t>Examples:</t>
5332                        <t>
5333                            <list>
5334                                <t>C: "ADD DB_INSTRUMENTS '/Piano Collection' '/home/me/gigs/PMI Bosendorfer 290.gig' 0"</t>
5335                                <t>S: "OK"</t>
5336                            </list>
5337                        </t>
5338                    </section>
5339    
5340                    <section title="Removing an instrument" anchor="REMOVE DB_INSTRUMENT">
5341                        <t>The front-end can remove a particular instrument
5342                        from the instruments database by sending the following command:</t>
5343                        <t>
5344                            <list>
5345                                <t>REMOVE DB_INSTRUMENT &lt;instr_path&gt;</t>
5346                            </list>
5347                        </t>
5348                        <t>Where &lt;instr_path&gt; is the absolute path name
5349                        (in the instruments database) of the instrument to remove.</t>
5350    
5351                        <t>Possible Answers:</t>
5352                        <t>
5353                            <list>
5354                                <t>"OK" -
5355                                    <list>
5356                                        <t>if the instrument is removed successfully</t>
5357                                    </list>
5358                                </t>
5359                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
5360                                    <list>
5361                                        <t>if the given path does not exist or
5362                                        is a directory.</t>
5363                                    </list>
5364                                </t>
5365                            </list>
5366                        </t>
5367    
5368                        <t>Examples:</t>
5369                        <t>
5370                            <list>
5371                                <t>C: "REMOVE DB_INSTRUMENT '/Piano Collection/Bosendorfer 290'"</t>
5372                                <t>S: "OK"</t>
5373                            </list>
5374                        </t>
5375                    </section>
5376    
5377                    <section title="Getting amount of instruments" anchor="GET DB_INSTRUMENTS">
5378                        <t>The front-end can retrieve the current amount of
5379                        instruments in a specific directory by sending the following command:</t>
5380                        <t>
5381                            <list>
5382                                <t>GET DB_INSTRUMENTS [RECURSIVE] &lt;dir&gt;</t>
5383                            </list>
5384                        </t>
5385                        <t>Where &lt;dir&gt; should be replaced by the absolute path name
5386                        of the directory. If RECURSIVE is specified, the number of all
5387                        instruments, including those located in subdirectories of the
5388                        specified directory, will be returned.</t>
5389    
5390                        <t>Possible Answers:</t>
5391                        <t>
5392                            <list>
5393                                <t>The current number of instruments
5394                                in the specified directory.</t>
5395                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
5396                                    <list>
5397                                        <t>if the given directory does not exist.</t>
5398                                    </list>
5399                                </t>
5400                            </list>
5401                        </t>
5402    
5403                        <t>Example:</t>
5404                        <t>
5405                            <list>
5406                                <t>C: "GET DB_INSTRUMENTS '/Piano Collection'"</t>
5407                                <t>S: "2"</t>
5408                            </list>
5409                        </t>
5410                    </section>
5411    
5412                    <section title="Listing all instruments in specific directory" anchor="LIST DB_INSTRUMENTS">
5413                        <t>The front-end can retrieve the current list of instruments
5414                        in specific directory by sending the following command:</t>
5415                        <t>
5416                            <list>
5417                                <t>LIST DB_INSTRUMENTS [RECURSIVE] &lt;dir&gt;</t>
5418                            </list>
5419                        </t>
5420                        <t>Where &lt;dir&gt; should be replaced by the absolute path
5421                        name of the directory. If RECURSIVE is specified, the absolute path
5422                        names of all instruments, including those located in subdirectories
5423                        of the specified directory, will be returned.</t>
5424    
5425                        <t>Possible Answers:</t>
5426                        <t>
5427                            <list>
5428                                <t>A comma separated list of all instruments
5429                                (encapsulated into apostrophes) in the specified directory.</t>
5430                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
5431                                    <list>
5432                                        <t>if the given directory does not exist.</t>
5433                                    </list>
5434                                </t>
5435                            </list>
5436                        </t>
5437                        <t>Example:</t>
5438                        <t>
5439                            <list>
5440                                <t>C: "LIST DB_INSTRUMENTS '/Piano Collection'"</t>
5441                                <t>S: "'Bosendorfer 290','Steinway D'"</t>
5442                            </list>
5443                        </t>
5444                        <t>
5445                            <list>
5446                                <t>C: "LIST DB_INSTRUMENTS RECURSIVE '/Piano Collection'"</t>
5447                                <t>S: "'/Piano Collection/Bosendorfer 290','/Piano Collection/Steinway D','/Piano Collection/Lite/Free Piano'"</t>
5448                            </list>
5449                        </t>
5450                    </section>
5451    
5452                    <section title="Getting instrument information" anchor="GET DB_INSTRUMENT INFO">
5453                        <t>The front-end can ask for the current settings of an
5454                        instrument by sending the following command:</t>
5455                        <t>
5456                            <list>
5457                                <t>GET DB_INSTRUMENT INFO &lt;instr_path&gt;</t>
5458                            </list>
5459                        </t>
5460                        <t>Where &lt;instr_path&gt; should be replaced by the absolute path
5461                        name of the instrument the front-end is interested in.</t>
5462    
5463                        <t>Possible Answers:</t>
5464                        <t>
5465                            <list>
5466                                <t>LinuxSampler will answer by sending a &lt;CRLF&gt; separated list.
5467                                Each answer line begins with the settings category name
5468                                followed by a colon and then a space character &lt;SP&gt; and finally
5469                                the info character string to that setting category. At the
5470                                moment the following categories are defined:</t>
5471    
5472                                <t>
5473                                    <list>
5474                                        <t>INSTRUMENT_FILE -
5475                                            <list>
5476                                                <t>File name of the instrument.
5477                                                Note that the character string may contain
5478                                                <xref target="character_set">escape sequences</xref>.</t>
5479                                            </list>
5480                                        </t>
5481                                        <t>INSTRUMENT_NR -
5482                                            <list>
5483                                                <t>Index of the instrument within the file.</t>
5484                                            </list>
5485                                        </t>
5486                                        <t>FORMAT_FAMILY -
5487                                            <list>
5488                                                <t>The format family of the instrument.</t>
5489                                            </list>
5490                                        </t>
5491                                        <t>FORMAT_VERSION -
5492                                            <list>
5493                                                <t>The format version of the instrument.</t>
5494                                            </list>
5495                                        </t>
5496                                        <t>SIZE -
5497                                            <list>
5498                                                <t>The size of the instrument in bytes.</t>
5499                                            </list>
5500                                        </t>
5501                                        <t>CREATED -
5502                                            <list>
5503                                                <t>The date and time when the instrument is added
5504                                                in the instruments database, represented in
5505                                               "YYYY-MM-DD HH:MM:SS" format</t>
5506                                            </list>
5507                                        </t>
5508                                        <t>MODIFIED -
5509                                            <list>
5510                                                <t>The date and time of the last modification of the
5511                                                instrument's database settings, represented in
5512                                                "YYYY-MM-DD HH:MM:SS" format</t>
5513                                            </list>
5514                                        </t>
5515                                        <t>DESCRIPTION -
5516                                            <list>
5517                                                <t>A brief description of the instrument.
5518                                                Note that the character string may contain
5519                                                <xref target="character_set">escape sequences</xref>.</t>
5520                                            </list>
5521                                        </t>
5522                                        <t>IS_DRUM -
5523                                            <list>
5524                                                <t>either true or false, determines whether the
5525                                                instrument is a drumkit or a chromatic instrument</t>
5526                                            </list>
5527                                        </t>
5528                                        <t>PRODUCT -
5529                                            <list>
5530                                                <t>The product title of the instrument.
5531                                                Note that the character string may contain
5532                                                <xref target="character_set">escape sequences</xref>.</t>
5533                                            </list>
5534                                        </t>
5535                                        <t>ARTISTS -
5536                                            <list>
5537                                                <t>Lists the artist names.
5538                                                Note that the character string may contain
5539                                                <xref target="character_set">escape sequences</xref>.</t>
5540                                            </list>
5541                                        </t>
5542                                        <t>KEYWORDS -
5543                                            <list>
5544                                                <t>Provides a list of keywords that refer to the instrument.
5545                                                Keywords are separated with semicolon and blank.
5546                                                Note that the character string may contain
5547                                                <xref target="character_set">escape sequences</xref>.</t>
5548                                            </list>
5549                                        </t>
5550                                    </list>
5551                                </t>
5552                            </list>
5553                        </t>
5554                        <t>The mentioned fields above don't have to be in particular order.</t>
5555    
5556                        <t>Example:</t>
5557                        <t>
5558                            <list>
5559                                <t>C: "GET DB_INSTRUMENT INFO '/Piano Collection/Bosendorfer 290'"</t>
5560                                <t>S: "INSTRUMENT_FILE: /home/me/gigs/Bosendorfer 290.gig"</t>
5561                                <t>&nbsp;&nbsp;&nbsp;"INSTRUMENT_NR: 0"</t>
5562                                <t>&nbsp;&nbsp;&nbsp;"FORMAT_FAMILY: GIG"</t>
5563                                <t>&nbsp;&nbsp;&nbsp;"FORMAT_VERSION: 2"</t>
5564                                <t>&nbsp;&nbsp;&nbsp;"SIZE: 2050871870"</t>
5565                                <t>&nbsp;&nbsp;&nbsp;"CREATED: 2007-02-05 10:23:12"</t>
5566                                <t>&nbsp;&nbsp;&nbsp;"MODIFIED: 2007-04-07 12:50:21"</t>
5567                                <t>&nbsp;&nbsp;&nbsp;"DESCRIPTION: "</t>
5568                                <t>&nbsp;&nbsp;&nbsp;"IS_DRUM: false"</t>
5569                                <t>&nbsp;&nbsp;&nbsp;"PRODUCT: GRANDIOSO Bosendorfer 290"</t>
5570                                <t>&nbsp;&nbsp;&nbsp;"ARTISTS: Post Musical Instruments"</t>
5571                                <t>&nbsp;&nbsp;&nbsp;"KEYWORDS: Bosendorfer"</t>
5572                                <t>&nbsp;&nbsp;&nbsp;"."</t>
5573                            </list>
5574                        </t>
5575                    </section>
5576    
5577                    <section title="Renaming an instrument" anchor="SET DB_INSTRUMENT NAME">
5578                        <t>The front-end can alter the name of a specific
5579                        instrument by sending the following command:</t>
5580                        <t>
5581                            <list>
5582                                <t>SET DB_INSTRUMENT NAME &lt;instr&gt; &lt;name&gt;</t>
5583                            </list>
5584                        </t>
5585                        <t>Where &lt;instr&gt; is the absolute path name of the instrument and
5586                        &lt;name&gt; is the new name for that instrument.</t>
5587    
5588                        <t>Possible Answers:</t>
5589                        <t>
5590                            <list>
5591                                <t>"OK" -
5592                                    <list>
5593                                        <t>on success</t>
5594                                    </list>
5595                                </t>
5596                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
5597                                    <list>
5598                                        <t>in case the given instrument does not exists,
5599                                        or if an instrument with name equal to the new
5600                                        name already exists.</t>
5601                                    </list>
5602                                </t>
5603                            </list>
5604                        </t>
5605    
5606                        <t>Example:</t>
5607                        <t>
5608                            <list>
5609                                <t>C: "SET DB_INSTRUMENT NAME '/Piano Collection/Bosendorfer' 'Bosendorfer 290'"</t>
5610                                <t>S: "OK"</t>
5611                            </list>
5612                        </t>
5613                    </section>
5614    
5615                    <section title="Moving an instrument" anchor="MOVE DB_INSTRUMENT">
5616                        <t>The front-end can move a specific instrument to another directory by
5617                        sending the following command:</t>
5618                        <t>
5619                            <list>
5620                                <t>MOVE DB_INSTRUMENT &lt;instr&gt; &lt;dst&gt;</t>
5621                            </list>
5622                        </t>
5623                        <t>Where &lt;instr&gt; is the absolute path name of the instrument
5624                        to move and &lt;dst&gt; is the directory where the instrument will
5625                        be moved to.</t>
5626    
5627                        <t>Possible Answers:</t>
5628                        <t>
5629                            <list>
5630                                <t>"OK" -
5631                                    <list>
5632                                        <t>on success</t>
5633                                    </list>
5634                                </t>
5635                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
5636                                    <list>
5637                                        <t>in case the given instrument does not exists,
5638                                        or if an instrument with name equal to the name of the
5639                                        specified instrument already exists in the destination
5640                                        directory.</t>
5641                                    </list>
5642                                </t>
5643                            </list>
5644                        </t>
5645    
5646                        <t>Example:</t>
5647                        <t>
5648                            <list>
5649                                <t>C: "MOVE DB_INSTRUMENT '/Piano Collection/Bosendorfer 290' '/Piano Collection/Acoustic'"</t>
5650                                <t>S: "OK"</t>
5651                            </list>
5652                        </t>
5653                    </section>
5654    
5655                    <section title="Copying instruments" anchor="COPY DB_INSTRUMENT">
5656                        <t>The front-end can copy a specific instrument to another directory by
5657                        sending the following command:</t>
5658                        <t>
5659                            <list>
5660                                <t>COPY DB_INSTRUMENT &lt;instr&gt; &lt;dst&gt;</t>
5661                            </list>
5662                        </t>
5663                        <t>Where &lt;instr&gt; is the absolute path name of the instrument
5664                        to copy and &lt;dst&gt; is the directory where the instrument will
5665                        be copied to.</t>
5666    
5667                        <t>Possible Answers:</t>
5668                        <t>
5669                            <list>
5670                                <t>"OK" -
5671                                    <list>
5672                                        <t>on success</t>
5673                                    </list>
5674                                </t>
5675                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
5676                                    <list>
5677                                        <t>in case the given instrument does not exists,
5678                                        or if an instrument with name equal to the name of the
5679                                        specified instrument already exists in the destination
5680                                        directory.</t>
5681                                    </list>
5682                                </t>
5683                            </list>
5684                        </t>
5685    
5686                        <t>Example:</t>
5687                        <t>
5688                            <list>
5689                                <t>C: "COPY DB_INSTRUMENT '/Piano Collection/Bosendorfer 290' '/Acoustic/Pianos/'"</t>
5690                                <t>S: "OK"</t>
5691                            </list>
5692                        </t>
5693                    </section>
5694    
5695                    <section title="Changing the description of instrument" anchor="SET DB_INSTRUMENT DESCRIPTION">
5696                        <t>The front-end can alter the description of a specific
5697                        instrument by sending the following command:</t>
5698                        <t>
5699                            <list>
5700                                <t>SET DB_INSTRUMENT DESCRIPTION &lt;instr&gt; &lt;desc&gt;</t>
5701                            </list>
5702                        </t>
5703                        <t>Where &lt;instr&gt; is the absolute path name of the instrument and
5704                        &lt;desc&gt; is the new description for the instrument
5705                        (encapsulated into apostrophes, supporting escape sequences as described in chapter
5706                        "<xref target="character_set">Character Set and Escape Sequences</xref>").</t>
5707    
5708                        <t>Possible Answers:</t>
5709                        <t>
5710                            <list>
5711                                <t>"OK" -
5712                                    <list>
5713                                        <t>on success</t>
5714                                    </list>
5715                                </t>
5716                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
5717                                    <list>
5718                                        <t>in case the given instrument does not exists.</t>
5719                                    </list>
5720                                </t>
5721                            </list>
5722                        </t>
5723    
5724                        <t>Example:</t>
5725                        <t>
5726                            <list>
5727                                <t>C: "SET DB_INSTRUMENT DESCRIPTION '/Piano Collection/Acoustic/Bosendorfer 290' 'No comment :)'"</t>
5728                                <t>S: "OK"</t>
5729                            </list>
5730                        </t>
5731                    </section>
5732    
5733                    <section title="Finding instruments" anchor="FIND DB_INSTRUMENTS">
5734                        <t>The front-end can search for instruments
5735                        in specific directory by sending the following command:</t>
5736                        <t>
5737                            <list>
5738                                <t>FIND DB_INSTRUMENTS [NON_RECURSIVE] &lt;dir&gt; &lt;criteria-list&gt;</t>
5739                            </list>
5740                        </t>
5741                        <t>Where &lt;dir&gt; should be replaced by the absolute path
5742                        name of the directory to search in. If NON_RECURSIVE is specified, the
5743                        directories located in subdirectories of the specified directory will not
5744                        be searched. &lt;criteria-list&gt; is a list of search criterias
5745                        in form of "key1=val1 key2=val2 ...". The following criterias are
5746                        allowed:</t>
5747                        <t>
5748                          <t>NAME='&lt;search-string&gt;'
5749                              <list>
5750                                  <t>Restricts the search to instruments, which names
5751                                  satisfy the supplied search string (encapsulated into apostrophes,
5752                                  supporting escape sequences as described in chapter
5753                                  "<xref target="character_set">Character Set and Escape Sequences</xref>").</t>
5754                              </list>
5755                          </t>
5756    
5757                          <t>SIZE=[&lt;min&gt;]..[&lt;max&gt;]
5758                              <list>
5759                                  <t>Restricts the search to instruments, which
5760                                  size is in the specified range. If &lt;min&gt; is omitted,
5761                                  the search results are restricted to instruments with size less then
5762                                  or equal to &lt;max&gt;. If &lt;max&gt; is omitted, the
5763                                  search is restricted to instruments with size greater then
5764                                  or equal to &lt;min&gt;.</t>
5765                              </list>
5766                          </t>
5767    
5768                          <t>CREATED='[&lt;date-after&gt;]..[&lt;date-before&gt;]'
5769                              <list>
5770                                  <t>Restricts the search to instruments, which creation
5771                                  date satisfies the specified period, where &lt;date-after&gt;
5772                                  and &lt;date-before&gt; are in "YYYY-MM-DD HH:MM:SS" format.
5773                                  If &lt;date-after&gt; is omitted the search is restricted to
5774                                  instruments created before &lt;date-before&gt;. If
5775                                  &lt;date-before&gt; is omitted, the search is restricted
5776                                  to instruments created after &lt;date-after&gt;.</t>
5777                              </list>
5778                          </t>
5779    
5780                          <t>MODIFIED='[&lt;date-after&gt;]..[&lt;date-before&gt;]'
5781                              <list>
5782                                  <t>Restricts the search to instruments, which
5783                                  date of last modification satisfies the specified period, where
5784                                  &lt;date-after&gt; and &lt;date-before&gt; are in "YYYY-MM-DD HH:MM:SS"
5785                                  format. If &lt;date-after&gt; is omitted the search is restricted to
5786                                  instruments, which are last modified before &lt;date-before&gt;. If
5787                                  &lt;date-before&gt; is omitted, the search is restricted to instruments,
5788                                  which are last modified after &lt;date-after&gt;.</t>
5789                              </list>
5790                          </t>
5791    
5792                          <t>DESCRIPTION='&lt;search-string&gt;'
5793                              <list>
5794                                  <t>Restricts the search to instruments with description
5795                                  that satisfies the supplied search string (encapsulated into apostrophes,
5796                                  supporting escape sequences as described in chapter
5797                                  "<xref target="character_set">Character Set and Escape Sequences</xref>").</t>
5798                              </list>
5799                          </t>
5800    
5801                          <t>PRODUCT='&lt;search-string&gt;'
5802                              <list>
5803                                  <t>Restricts the search to instruments with product info
5804                                  that satisfies the supplied search string (encapsulated into apostrophes,
5805                                  supporting escape sequences as described in chapter
5806                                  "<xref target="character_set">Character Set and Escape Sequences</xref>").</t>
5807                              </list>
5808                          </t>
5809    
5810                          <t>ARTISTS='&lt;search-string&gt;'
5811                              <list>
5812                                  <t>Restricts the search to instruments with artists info
5813                                  that satisfies the supplied search string (encapsulated into apostrophes,
5814                                  supporting escape sequences as described in chapter
5815                                  "<xref target="character_set">Character Set and Escape Sequences</xref>").</t>
5816                              </list>
5817                          </t>
5818    
5819                          <t>KEYWORDS='&lt;search-string&gt;'
5820                              <list>
5821                                  <t>Restricts the search to instruments with keyword list
5822                                  that satisfies the supplied search string (encapsulated into apostrophes,
5823                                  supporting escape sequences as described in chapter
5824                                  "<xref target="character_set">Character Set and Escape Sequences</xref>").</t>
5825                              </list>
5826                          </t>
5827    
5828                          <t>IS_DRUM=true | false
5829                              <list>
5830                                  <t>Either true or false. Restricts the search to
5831                                  drum kits or chromatic instruments.</t>
5832                              </list>
5833                          </t>
5834    
5835                          <t>FORMAT_FAMILIES='&lt;format-list&gt;'
5836                              <list>
5837                                  <t>Restricts the search to instruments of the supplied format families,
5838                                  where &lt;format-list&gt; is a comma separated list of format families.</t>
5839                              </list>
5840                          </t>
5841                        </t>
5842    
5843                        <t>Where &lt;search-string&gt; is either a regular expression, or a
5844                        word list separated with spaces for OR search and with '+' for AND search.</t>
5845    
5846                        <t>Possible Answers:</t>
5847                        <t>
5848                            <list>
5849                                <t>A comma separated list with the absolute path names (encapsulated into
5850                                apostrophes) of all instruments in the specified directory that satisfy
5851                                the supplied search criterias.</t>
5852                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
5853                                    <list>
5854                                        <t>if the given directory does not exist.</t>
5855                                    </list>
5856                                </t>
5857                            </list>
5858                        </t>
5859                        <t>Example:</t>
5860                        <t>
5861                            <list>
5862                                <t>C: "FIND DB_INSTRUMENTS '/Piano Collection' NAME='bosendorfer+290'"</t>
5863                                <t>S: "'/Piano Collection/Bosendorfer 290'"</t>
5864                            </list>
5865                        </t>
5866                        <t>
5867                            <list>
5868                                <t>C: "FIND DB_INSTRUMENTS '/Piano Collection' CREATED='2007-04-01 09:30:13..'"</t>
5869                                <t>S: "'/Piano Collection/Bosendorfer 290','/Piano Collection/Steinway D'"</t>
5870                            </list>
5871                        </t>
5872                    </section>
5873    
5874                    <section title="Getting job status information" anchor="GET DB_INSTRUMENTS_JOB INFO">
5875                        <t>The front-end can ask for the current status of a
5876                        particular database instruments job by sending the following command:</t>
5877                        <t>
5878                            <list>
5879                                <t>GET DB_INSTRUMENTS_JOB INFO &lt;job-id&gt;</t>
5880                            </list>
5881                        </t>
5882                        <t>Where &lt;job-id&gt; should be replaced by the numerical ID
5883                        of the job the front-end is interested in.</t>
5884    
5885                        <t>Possible Answers:</t>
5886                        <t>
5887                            <list>
5888                                <t>LinuxSampler will answer by sending a &lt;CRLF&gt; separated list.
5889                                Each answer line begins with the settings category name
5890                                followed by a colon and then a space character &lt;SP&gt; and finally
5891                                the info character string to that setting category. At the
5892                                moment the following categories are defined:</t>
5893    
5894                                <t>
5895                                    <list>
5896                                        <t>FILES_TOTAL -
5897                                            <list>
5898                                                <t>The total number of files scheduled for scanning</t>
5899                                            </list>
5900                                        </t>
5901                                        <t>FILES_SCANNED -
5902                                            <list>
5903                                                <t>The current number of scanned files</t>
5904                                            </list>
5905                                        </t>
5906                                        <t>SCANNING -
5907                                            <list>
5908                                                <t>The absolute path name of the file which is currently
5909                                                being scanned</t>
5910                                            </list>
5911                                        </t>
5912                                        <t>STATUS -
5913                                            <list>
5914                                                <t>An integer value between 0 and 100 indicating the
5915                                                scanning progress percentage of the file which is
5916                                                currently being scanned</t>
5917                                            </list>
5918                                        </t>
5919                                    </list>
5920                                </t>
5921                            </list>
5922                        </t>
5923                        <t>The mentioned fields above don't have to be in particular order.</t>
5924    
5925                        <t>Example:</t>
5926                        <t>
5927                            <list>
5928                                <t>C: "GET DB_INSTRUMENTS_JOB INFO 2"</t>
5929                                <t>S: "FILES_TOTAL: 12"</t>
5930                                <t>&nbsp;&nbsp;&nbsp;"FILES_SCANNED: 7"</t>
5931                                <t>&nbsp;&nbsp;&nbsp;"SCANNING: /home/me/gigs/Bosendorfer 290.gig"</t>
5932                                <t>&nbsp;&nbsp;&nbsp;"STATUS: 42"</t>
5933                                <t>&nbsp;&nbsp;&nbsp;"."</t>
5934                            </list>
5935                        </t>
5936                    </section>
5937    
5938                    <section title="Formatting the instruments database" anchor="FORMAT INSTRUMENTS_DB">
5939                        <t>The front-end can remove all instruments and directories and re-create
5940                        the instruments database structure (e.g., in case of a database corruption)
5941                        by sending the following command:</t>
5942                        <t>
5943                            <list>
5944                                <t>FORMAT INSTRUMENTS_DB</t>
5945                            </list>
5946                        </t>
5947                        
5948                        <t>Possible Answers:</t>
5949                        <t>
5950                            <list>
5951                                <t>"OK" -
5952                                    <list>
5953                                        <t>on success</t>
5954                                    </list>
5955                                </t>
5956                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
5957                                    <list>
5958                                        <t>If the formatting of the instruments database
5959                                        failed.</t>
5960                                    </list>
5961                                </t>
5962                            </list>
5963                        </t>
5964                    </section>
5965    
5966                </section>
5967    
5968    
5969    
5970                <section title="Editing Instruments" anchor="editing_instruments">
5971                    <t>The sampler allows to edit instruments while playing with the
5972                    sampler by spawning an external (3rd party) instrument editor
5973                    application for a given instrument. The 3rd party instrument
5974                    editor applications have to place a respective plugin DLL file
5975                    into the sampler's plugins directory. The sampler will
5976                    automatically try to load all plugin DLLs in that directory on
5977                    startup and only on startup!</t>
5978                    <t>At the moment there is only one command for this feature set,
5979                    but this will most probably change in future.</t>
5980    
5981                    <section title="Opening an appropriate instrument editor application" anchor="EDIT INSTRUMENT">
5982                        <t>The front-end can request to open an appropriate instrument
5983                        editor application by sending the following command:</t>
5984                        <t>
5985                            <list>
5986                                <t>EDIT INSTRUMENT &lt;sampler-channel&gt;</t>
5987                            </list>
5988                        </t>
5989                        <t>Where &lt;sampler-channel&gt; should be replaced by the
5990                        number of the sampler channel as given by the
5991                        <xref target="ADD CHANNEL">"ADD CHANNEL"</xref>
5992                        or <xref target="LIST CHANNELS">"LIST CHANNELS"</xref>
5993                        command.</t>
5994    
5995                        <t>The sampler will try to ask all registered instrument
5996                        editors (or to be more specific: their sampler plugins)
5997                        whether they are capable to handle the instrument on the
5998                        given sampler channel. The sampler will simply use the first
5999                        instrument editor application which replied with a positive
6000                        answer and spawn that instrument editor application within
6001                        the sampler's process and provide that application access
6002                        to the instrument's data structures, so both applications
6003                        can share and access the same instruments data at the same
6004                        time, thus allowing to immediately hear changes with the
6005                        sampler made by the instrument editor.</t>
6006    
6007                        <t>Note: consequently instrument editors are always spawned
6008                        locally on the same machine where the sampler is running
6009                        on!</t>
6010    
6011                        <t>Possible Answers:</t>
6012                        <t>
6013                            <list>
6014                                <t>"OK" -
6015                                    <list>
6016                                        <t>when an appropriate instrument editor was
6017                                        launched</t>
6018                                    </list>
6019                                </t>
6020                                <t>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
6021                                    <list>
6022                                        <t>when an appropriate instrument editor was
6023                                        launched, but there are noteworthy issues</t>
6024                                    </list>
6025                                </t>
6026                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
6027                                    <list>
6028                                        <t>when an appropriate instrument editor
6029                                        could not be launched</t>
6030                                    </list>
6031                                </t>
6032                            </list>
6033                        </t>
6034    
6035                        <t>Examples:</t>
6036                        <t>
6037                            <list>
6038                                <t>C: "EDIT INSTRUMENT 0"</t>
6039                                <t>S: "OK"</t>
6040                            </list>
6041                        </t>
6042                    </section>
6043                </section>
6044          </section>          </section>
6045    
6046    
# Line 4287  Schoenebeck'> Line 6116  Schoenebeck'>
6116                  </t>                  </t>
6117                  <t>/ UNSUBSCRIBE SP unsubscribe_event                  <t>/ UNSUBSCRIBE SP unsubscribe_event
6118                  </t>                  </t>
                 <t>/ SELECT SP text  
                 </t>  
6119                  <t>/ RESET SP reset_instruction                  <t>/ RESET SP reset_instruction
6120                  </t>                  </t>
6121                  <t>/ CLEAR SP clear_instruction                  <t>/ CLEAR SP clear_instruction
6122                  </t>                  </t>
6123                    <t>/ FIND SP find_instruction
6124                    </t>
6125                    <t>/ MOVE SP move_instruction
6126                    </t>
6127                    <t>/ COPY SP copy_instruction
6128                    </t>
6129                    <t>/ EDIT SP edit_instruction
6130                    </t>
6131                    <t>/ FORMAT SP format_instruction
6132                    </t>
6133                  <t>/ RESET                  <t>/ RESET
6134                  </t>                  </t>
6135                  <t>/ QUIT                  <t>/ QUIT
# Line 4303  Schoenebeck'> Line 6140  Schoenebeck'>
6140          <list>          <list>
6141                  <t>CHANNEL                  <t>CHANNEL
6142                  </t>                  </t>
6143                    <t>/ DB_INSTRUMENT_DIRECTORY SP db_path
6144                    </t>
6145                    <t>/ DB_INSTRUMENTS SP NON_MODAL SP scan_mode SP db_path SP filename
6146                    </t>
6147                    <t>/ DB_INSTRUMENTS SP scan_mode SP db_path SP filename
6148                    </t>
6149                    <t>/ DB_INSTRUMENTS SP NON_MODAL SP db_path SP filename
6150                    </t>
6151                    <t>/ DB_INSTRUMENTS SP NON_MODAL SP db_path SP filename SP instrument_index
6152                    </t>
6153                    <t>/ DB_INSTRUMENTS SP db_path SP filename
6154                    </t>
6155                    <t>/ DB_INSTRUMENTS SP db_path SP filename SP instrument_index
6156                    </t>
6157                  <t>/ MIDI_INSTRUMENT_MAP                  <t>/ MIDI_INSTRUMENT_MAP
6158                  </t>                  </t>
6159                  <t>/ MIDI_INSTRUMENT_MAP SP map_name                  <t>/ MIDI_INSTRUMENT_MAP SP map_name
# Line 4311  Schoenebeck'> Line 6162  Schoenebeck'>
6162  </t>  </t>
6163  <t>subscribe_event =  <t>subscribe_event =
6164          <list>          <list>
6165                  <t>CHANNEL_COUNT                  <t>AUDIO_OUTPUT_DEVICE_COUNT
6166                    </t>
6167                    <t>/ AUDIO_OUTPUT_DEVICE_INFO
6168                    </t>
6169                    <t>/ MIDI_INPUT_DEVICE_COUNT
6170                    </t>
6171                    <t>/ MIDI_INPUT_DEVICE_INFO
6172                    </t>
6173                    <t>/ CHANNEL_COUNT
6174                  </t>                  </t>
6175                  <t>/ VOICE_COUNT                  <t>/ VOICE_COUNT
6176                  </t>                  </t>
# Line 4321  Schoenebeck'> Line 6180  Schoenebeck'>
6180                  </t>                  </t>
6181                  <t>/ CHANNEL_INFO                  <t>/ CHANNEL_INFO
6182                  </t>                  </t>
6183                    <t>/ FX_SEND_COUNT
6184                    </t>
6185                    <t>/ FX_SEND_INFO
6186                    </t>
6187                    <t>/ MIDI_INSTRUMENT_MAP_COUNT
6188                    </t>
6189                    <t>/ MIDI_INSTRUMENT_MAP_INFO
6190                    </t>
6191                    <t>/ MIDI_INSTRUMENT_COUNT
6192                    </t>
6193                    <t>/ MIDI_INSTRUMENT_INFO
6194                    </t>
6195                    <t>/ DB_INSTRUMENT_DIRECTORY_COUNT
6196                    </t>
6197                    <t>/ DB_INSTRUMENT_DIRECTORY_INFO
6198                    </t>
6199                    <t>/ DB_INSTRUMENT_COUNT
6200                    </t>
6201                    <t>/ DB_INSTRUMENT_INFO
6202                    </t>
6203                    <t>/ DB_INSTRUMENTS_JOB_INFO
6204                    </t>
6205                  <t>/ MISCELLANEOUS                  <t>/ MISCELLANEOUS
6206                  </t>                  </t>
6207                  <t>/ TOTAL_VOICE_COUNT                  <t>/ TOTAL_VOICE_COUNT
6208                  </t>                  </t>
6209                    <t>/ GLOBAL_INFO
6210                    </t>
6211          </list>          </list>
6212  </t>  </t>
6213  <t>unsubscribe_event =  <t>unsubscribe_event =
6214          <list>          <list>
6215                  <t>CHANNEL_COUNT                  <t>AUDIO_OUTPUT_DEVICE_COUNT
6216                    </t>
6217                    <t>/ AUDIO_OUTPUT_DEVICE_INFO
6218                    </t>
6219                    <t>/ MIDI_INPUT_DEVICE_COUNT
6220                    </t>
6221                    <t>/ MIDI_INPUT_DEVICE_INFO
6222                    </t>
6223                    <t>/ CHANNEL_COUNT
6224                  </t>                  </t>
6225                  <t>/ VOICE_COUNT                  <t>/ VOICE_COUNT
6226                  </t>                  </t>
# Line 4339  Schoenebeck'> Line 6230  Schoenebeck'>
6230                  </t>                  </t>
6231                  <t>/ CHANNEL_INFO                  <t>/ CHANNEL_INFO
6232                  </t>                  </t>
6233                    <t>/ FX_SEND_COUNT
6234                    </t>
6235                    <t>/ FX_SEND_INFO
6236                    </t>
6237                    <t>/ MIDI_INSTRUMENT_MAP_COUNT
6238                    </t>
6239                    <t>/ MIDI_INSTRUMENT_MAP_INFO
6240                    </t>
6241                    <t>/ MIDI_INSTRUMENT_COUNT
6242                    </t>
6243                    <t>/ MIDI_INSTRUMENT_INFO
6244                    </t>
6245                    <t>/ DB_INSTRUMENT_DIRECTORY_COUNT
6246                    </t>
6247                    <t>/ DB_INSTRUMENT_DIRECTORY_INFO
6248                    </t>
6249                    <t>/ DB_INSTRUMENT_COUNT
6250                    </t>
6251                    <t>/ DB_INSTRUMENT_INFO
6252                    </t>
6253                    <t>/ DB_INSTRUMENTS_JOB_INFO
6254                    </t>
6255                  <t>/ MISCELLANEOUS                  <t>/ MISCELLANEOUS
6256                  </t>                  </t>
6257                  <t>/ TOTAL_VOICE_COUNT                  <t>/ TOTAL_VOICE_COUNT
6258                  </t>                  </t>
6259                    <t>/ GLOBAL_INFO
6260                    </t>
6261          </list>          </list>
6262  </t>  </t>
6263  <t>map_instruction =  <t>map_instruction =
6264          <list>          <list>
6265                  <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
6266                  </t>                  </t>
6267                  <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
6268                  </t>                  </t>
6269                  <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
6270                  </t>                  </t>
6271                  <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
6272                  </t>                  </t>
6273          </list>          </list>
6274  </t>  </t>
# Line 4371  Schoenebeck'> Line 6286  Schoenebeck'>
6286                  </t>                  </t>
6287                  <t>/ MIDI_INSTRUMENT_MAP SP ALL                  <t>/ MIDI_INSTRUMENT_MAP SP ALL
6288                  </t>                  </t>
6289                    <t>/ DB_INSTRUMENT_DIRECTORY SP FORCE SP db_path
6290                    </t>
6291                    <t>/ DB_INSTRUMENT_DIRECTORY SP db_path
6292                    </t>
6293                    <t>/ DB_INSTRUMENT SP db_path
6294                    </t>
6295          </list>          </list>
6296  </t>  </t>
6297  <t>get_instruction =  <t>get_instruction =
# Line 4437  Schoenebeck'> Line 6358  Schoenebeck'>
6358                  </t>                  </t>
6359                  <t>/ MIDI_INSTRUMENT_MAP SP INFO SP midi_map                  <t>/ MIDI_INSTRUMENT_MAP SP INFO SP midi_map
6360                  </t>                  </t>
6361                    <t>/ FX_SENDS SP sampler_channel
6362                    </t>
6363                    <t>/ FX_SEND SP INFO SP sampler_channel SP fx_send_id
6364                    </t>
6365                    <t>/ DB_INSTRUMENT_DIRECTORIES SP RECURSIVE SP db_path
6366                    </t>
6367                    <t>/ DB_INSTRUMENT_DIRECTORIES SP db_path
6368                    </t>
6369                    <t>/ DB_INSTRUMENT_DIRECTORY SP INFO SP db_path
6370                    </t>
6371                    <t>/ DB_INSTRUMENTS SP RECURSIVE SP db_path
6372                    </t>
6373                    <t>/ DB_INSTRUMENTS SP db_path
6374                    </t>
6375                    <t>/ DB_INSTRUMENT SP INFO SP db_path
6376                    </t>
6377                    <t>/ DB_INSTRUMENTS_JOB SP INFO SP number
6378                    </t>
6379                    <t>/ VOLUME
6380                    </t>
6381          </list>          </list>
6382  </t>  </t>
6383  <t>set_instruction =  <t>set_instruction =
# Line 4447  Schoenebeck'> Line 6388  Schoenebeck'>
6388                  </t>                  </t>
6389                  <t>/ MIDI_INPUT_DEVICE_PARAMETER SP number SP string '=' param_val_list                  <t>/ MIDI_INPUT_DEVICE_PARAMETER SP number SP string '=' param_val_list
6390                  </t>                  </t>
6391                    <t>/ MIDI_INPUT_PORT_PARAMETER SP number SP number SP string '=' NONE
6392                    </t>
6393                  <t>/ MIDI_INPUT_PORT_PARAMETER SP number SP number SP string '=' param_val_list                  <t>/ MIDI_INPUT_PORT_PARAMETER SP number SP number SP string '=' param_val_list
6394                  </t>                  </t>
6395                  <t>/ CHANNEL SP set_chan_instruction                  <t>/ CHANNEL SP set_chan_instruction
6396                  </t>                  </t>
6397                  <t>/ MIDI_INSTRUMENT_MAP SP NAME SP midi_map SP map_name                  <t>/ MIDI_INSTRUMENT_MAP SP NAME SP midi_map SP map_name
6398                  </t>                  </t>
6399                    <t>/ FX_SEND SP NAME SP sampler_channel SP fx_send_id SP fx_send_name
6400                    </t>
6401                    <t>/ FX_SEND SP AUDIO_OUTPUT_CHANNEL SP sampler_channel SP fx_send_id SP audio_channel_index SP audio_channel_index
6402                    </t>
6403                    <t>/ FX_SEND SP MIDI_CONTROLLER SP sampler_channel SP fx_send_id SP midi_ctrl
6404                    </t>
6405                    <t>/ FX_SEND SP LEVEL SP sampler_channel SP fx_send_id SP volume_value
6406                    </t>
6407                    <t>/ DB_INSTRUMENT_DIRECTORY SP NAME SP db_path SP stringval_escaped
6408                    </t>
6409                    <t>/ DB_INSTRUMENT_DIRECTORY SP DESCRIPTION SP db_path SP stringval_escaped
6410                    </t>
6411                    <t>/ DB_INSTRUMENT SP NAME SP db_path SP stringval_escaped
6412                    </t>
6413                    <t>/ DB_INSTRUMENT SP DESCRIPTION SP db_path SP stringval_escaped
6414                    </t>
6415                  <t>/ ECHO SP boolean                  <t>/ ECHO SP boolean
6416                  </t>                  </t>
6417                    <t>/ VOLUME SP volume_value
6418                    </t>
6419          </list>          </list>
6420  </t>  </t>
6421  <t>create_instruction =  <t>create_instruction =
# Line 4467  Schoenebeck'> Line 6428  Schoenebeck'>
6428                  </t>                  </t>
6429                  <t>/ MIDI_INPUT_DEVICE SP string                  <t>/ MIDI_INPUT_DEVICE SP string
6430                  </t>                  </t>
6431                    <t>/ FX_SEND SP sampler_channel SP midi_ctrl
6432                    </t>
6433                    <t>/ FX_SEND SP sampler_channel SP midi_ctrl SP fx_send_name
6434                    </t>
6435          </list>          </list>
6436  </t>  </t>
6437  <t>reset_instruction =  <t>reset_instruction =
# Line 4483  Schoenebeck'> Line 6448  Schoenebeck'>
6448                  </t>                  </t>
6449          </list>          </list>
6450  </t>  </t>
6451    <t>find_instruction =
6452            <list>
6453                    <t>DB_INSTRUMENTS SP NON_RECURSIVE SP db_path SP query_val_list
6454                    </t>
6455                    <t>/ DB_INSTRUMENTS SP db_path SP query_val_list
6456                    </t>
6457                    <t>/ DB_INSTRUMENT_DIRECTORIES SP NON_RECURSIVE SP db_path SP query_val_list
6458                    </t>
6459                    <t>/ DB_INSTRUMENT_DIRECTORIES SP db_path SP query_val_list
6460                    </t>
6461            </list>
6462    </t>
6463    <t>move_instruction =
6464            <list>
6465                    <t>DB_INSTRUMENT_DIRECTORY SP db_path SP db_path
6466                    </t>
6467                    <t>/ DB_INSTRUMENT SP db_path SP db_path
6468                    </t>
6469            </list>
6470    </t>
6471    <t>copy_instruction =
6472            <list>
6473                    <t>DB_INSTRUMENT_DIRECTORY SP db_path SP db_path
6474                    </t>
6475                    <t>/ DB_INSTRUMENT SP db_path SP db_path
6476                    </t>
6477            </list>
6478    </t>
6479  <t>destroy_instruction =  <t>destroy_instruction =
6480          <list>          <list>
6481                  <t>AUDIO_OUTPUT_DEVICE SP number                  <t>AUDIO_OUTPUT_DEVICE SP number
6482                  </t>                  </t>
6483                  <t>/ MIDI_INPUT_DEVICE SP number                  <t>/ MIDI_INPUT_DEVICE SP number
6484                  </t>                  </t>
6485                    <t>/ FX_SEND SP sampler_channel SP fx_send_id
6486                    </t>
6487          </list>          </list>
6488  </t>  </t>
6489  <t>load_instruction =  <t>load_instruction =
# Line 4531  Schoenebeck'> Line 6526  Schoenebeck'>
6526                  </t>                  </t>
6527          </list>          </list>
6528  </t>  </t>
6529    <t>edit_instruction =
6530            <list>
6531                    <t>INSTRUMENT SP sampler_channel
6532                    </t>
6533            </list>
6534    </t>
6535    <t>format_instruction =
6536            <list>
6537                    <t>INSTRUMENTS_DB
6538                    </t>
6539            </list>
6540    </t>
6541    <t>modal_arg =
6542            <list>
6543                    <t>/* epsilon (empty argument) */
6544                    </t>
6545                    <t>/ NON_MODAL SP
6546                    </t>
6547            </list>
6548    </t>
6549  <t>key_val_list =  <t>key_val_list =
6550          <list>          <list>
6551                  <t>string '=' param_val_list                  <t>string '=' param_val_list
# Line 4567  Schoenebeck'> Line 6582  Schoenebeck'>
6582                  </t>                  </t>
6583                  <t>/ MIDI_INSTRUMENT_MAPS                  <t>/ MIDI_INSTRUMENT_MAPS
6584                  </t>                  </t>
6585                    <t>/ FX_SENDS SP sampler_channel
6586                    </t>
6587                    <t>/ DB_INSTRUMENT_DIRECTORIES SP RECURSIVE SP db_path
6588                    </t>
6589                    <t>/ DB_INSTRUMENT_DIRECTORIES SP db_path
6590                    </t>
6591                    <t>/ DB_INSTRUMENTS SP RECURSIVE SP db_path
6592                    </t>
6593                    <t>/ DB_INSTRUMENTS SP db_path
6594                    </t>
6595          </list>          </list>
6596  </t>  </t>
6597  <t>load_instr_args =  <t>load_instr_args =
# Line 4649  Schoenebeck'> Line 6674  Schoenebeck'>
6674                  </t>                  </t>
6675          </list>          </list>
6676  </t>  </t>
6677    <t>midi_ctrl =
6678            <list>
6679                    <t>number
6680                    </t>
6681            </list>
6682    </t>
6683  <t>volume_value =  <t>volume_value =
6684          <list>          <list>
6685                  <t>dotnum                  <t>dotnum
# Line 4669  Schoenebeck'> Line 6700  Schoenebeck'>
6700                  </t>                  </t>
6701          </list>          </list>
6702  </t>  </t>
6703    <t>fx_send_id =
6704            <list>
6705                    <t>number
6706                    </t>
6707            </list>
6708    </t>
6709  <t>engine_name =  <t>engine_name =
6710          <list>          <list>
6711                  <t>string                  <t>string
# Line 4677  Schoenebeck'> Line 6714  Schoenebeck'>
6714  </t>  </t>
6715  <t>filename =  <t>filename =
6716          <list>          <list>
6717                  <t>stringval                  <t>path
6718                    </t>
6719            </list>
6720    </t>
6721    <t>db_path =
6722            <list>
6723                    <t>path
6724                  </t>                  </t>
6725          </list>          </list>
6726  </t>  </t>
6727  <t>map_name =  <t>map_name =
6728          <list>          <list>
6729                  <t>stringval                  <t>stringval_escaped
6730                  </t>                  </t>
6731          </list>          </list>
6732  </t>  </t>
6733  <t>entry_name =  <t>entry_name =
6734          <list>          <list>
6735                  <t>stringval                  <t>stringval_escaped
6736                    </t>
6737            </list>
6738    </t>
6739    <t>fx_send_name =
6740            <list>
6741                    <t>stringval_escaped
6742                  </t>                  </t>
6743          </list>          </list>
6744  </t>  </t>
# Line 4701  Schoenebeck'> Line 6750  Schoenebeck'>
6750                  </t>                  </t>
6751          </list>          </list>
6752  </t>  </t>
6753    
6754  <t>param_val =  <t>param_val =
6755          <list>          <list>
6756                  <t>string                  <t>string
# Line 4713  Schoenebeck'> Line 6763  Schoenebeck'>
6763                  </t>                  </t>
6764          </list>          </list>
6765  </t>  </t>
6766    <t>query_val_list =
6767            <list>
6768                    <t>string '=' query_val
6769                    </t>
6770                    <t>/ query_val_list SP string '=' query_val
6771                    </t>
6772            </list>
6773    </t>
6774    <t>query_val =
6775            <list>
6776                    <t>text_escaped
6777                    </t>
6778                    <t>/ stringval_escaped
6779                    </t>
6780            </list>
6781    </t>
6782    <t>scan_mode =
6783            <list>
6784                    <t>RECURSIVE
6785                    </t>
6786                    <t>/ NON_RECURSIVE
6787                    </t>
6788                    <t>/ FLAT
6789                    </t>
6790            </list>
6791    </t>
6792    
6793              <!-- GRAMMAR_BNF_END - do NOT delete or modify this line !!! -->              <!-- GRAMMAR_BNF_END - do NOT delete or modify this line !!! -->
6794    
6795                <section title="Character Set and Escape Sequences" anchor="character_set">
6796                    <t>Older versions of this protocol up to and including v1.1 only
6797                    supported the standard ASCII character set (ASCII code 0 - 127)
6798                    <xref target="RFC20"/>, all younger versions of this protocol
6799                    however support the Extended ASCII character set (ASCII code
6800                    0 - 255). The same group of younger protocols also support
6801                    escape sequences, but only for certain, explicitly declared
6802                    parts of the protocol. The supported escape sequences are
6803                    defined as follows:</t>
6804                    <texttable>
6805                        <ttcol>ASCII Character Sequence</ttcol>
6806                        <ttcol>Translated into (Name)</ttcol>
6807                        <c>\n</c> <c>new line</c>
6808                        <c>\r</c> <c>carriage return</c>
6809                        <c>\f</c> <c>form feed</c>
6810                        <c>\t</c> <c>horizontal tab</c>
6811                        <c>\v</c> <c>vertical tab</c>
6812                        <c>\'</c> <c>apostrophe</c>
6813                        <c>\"</c> <c>quotation mark</c>
6814                        <c>\\</c> <c>backslash</c>
6815                        <c>\OOO</c> <c>three digit octal ASCII code of the character</c>
6816                        <c>\xHH</c> <c>two digit hex ASCII code of the character</c>
6817                    </texttable>
6818                    <t>Notice: due to the transition of certain parts of the
6819                    protocol which now support escape sequences, a slight backward
6820                    incompatibility to protocols version v1.1 and younger has been
6821                    introduced. The only difference is that in parts of the protocol
6822                    where escape characters are now supported, a backslash characters
6823                    MUST be escaped as well (that is as double backslash), whereas
6824                    in the old versions a single backslash was sufficient.</t>
6825    
6826                    <t>The following LSCP commands support escape sequences as part
6827                    of their filename / path based arguments:
6828                    <list>
6829                        <t><xref target="LOAD INSTRUMENT">"LOAD INSTRUMENT"</xref></t>
6830                        <t><xref target="MAP MIDI_INSTRUMENT">"MAP MIDI_INSTRUMENT"</xref></t>
6831                        <t><xref target="ADD DB_INSTRUMENT_DIRECTORY">"ADD DB_INSTRUMENT_DIRECTORY"</xref></t>
6832                        <t><xref target="ADD DB_INSTRUMENTS">"ADD DB_INSTRUMENTS"</xref></t>
6833                        <t><xref target="REMOVE DB_INSTRUMENT_DIRECTORY">"REMOVE DB_INSTRUMENT_DIRECTORY"</xref></t>
6834                        <t><xref target="REMOVE DB_INSTRUMENT">"REMOVE DB_INSTRUMENT"</xref></t>
6835                        <t><xref target="GET DB_INSTRUMENT_DIRECTORIES">"GET DB_INSTRUMENT_DIRECTORIES"</xref></t>
6836                        <t><xref target="LIST DB_INSTRUMENT_DIRECTORIES">"LIST DB_INSTRUMENT_DIRECTORIES"</xref></t>
6837                        <t><xref target="GET DB_INSTRUMENT_DIRECTORY INFO">"GET DB_INSTRUMENT_DIRECTORY INFO"</xref></t>
6838                        <t><xref target="GET DB_INSTRUMENTS">"GET DB_INSTRUMENTS"</xref></t>
6839                        <t><xref target="LIST DB_INSTRUMENTS">"LIST DB_INSTRUMENTS"</xref></t>
6840                        <t><xref target="GET DB_INSTRUMENT INFO">"GET DB_INSTRUMENT INFO"</xref></t>
6841                        <t><xref target="SET DB_INSTRUMENT_DIRECTORY NAME">"SET DB_INSTRUMENT_DIRECTORY NAME"</xref></t>
6842                        <t><xref target="SET DB_INSTRUMENT_DIRECTORY DESCRIPTION">"SET DB_INSTRUMENT_DIRECTORY DESCRIPTION"</xref></t>
6843                        <t><xref target="SET DB_INSTRUMENT NAME">"SET DB_INSTRUMENT NAME"</xref></t>
6844                        <t><xref target="SET DB_INSTRUMENT DESCRIPTION">"SET DB_INSTRUMENT DESCRIPTION"</xref></t>
6845                        <t><xref target="FIND DB_INSTRUMENTS">"FIND DB_INSTRUMENTS"</xref></t>
6846                        <t><xref target="FIND DB_INSTRUMENT_DIRECTORIES">"FIND DB_INSTRUMENT_DIRECTORIES"</xref></t>
6847                        <t><xref target="MOVE DB_INSTRUMENT">"MOVE DB_INSTRUMENT"</xref></t>
6848                        <t><xref target="MOVE DB_INSTRUMENT_DIRECTORY">"MOVE DB_INSTRUMENT_DIRECTORY"</xref></t>
6849                        <t><xref target="COPY DB_INSTRUMENT">"COPY DB_INSTRUMENT"</xref></t>
6850                        <t><xref target="COPY DB_INSTRUMENT_DIRECTORY">"COPY DB_INSTRUMENT_DIRECTORY"</xref></t>
6851                    </list>
6852                    Note that the forward slash character ('/') has a special meaning in
6853                    filename / path based arguments: it acts as separator of the nodes in
6854                    the path, thus if a directory- or filename includes a forward slash
6855                    (not intended as path node separator), you MUST escape that slash
6856                    either with the respective hex escape sequence ("\x2f") or with the
6857                    respective octal escape sequence ("\057").
6858                    </t>
6859    
6860                    <t>
6861                    The following LSCP commands even support escape sequences as
6862                    part of at least one of their text-based arguments (i.e. entity name,
6863                    description):
6864                    <list>
6865                        <t><xref target="CREATE FX_SEND">"CREATE FX_SEND"</xref></t>
6866                        <t><xref target="SET FX_SEND NAME">"SET FX_SEND NAME"</xref></t>
6867                        <t><xref target="ADD MIDI_INSTRUMENT_MAP">"ADD MIDI_INSTRUMENT_MAP"</xref></t>
6868                        <t><xref target="MAP MIDI_INSTRUMENT">"MAP MIDI_INSTRUMENT"</xref></t>
6869                        <t><xref target="SET MIDI_INSTRUMENT_MAP NAME">"SET MIDI_INSTRUMENT_MAP NAME"</xref></t>
6870                        <t><xref target="SET DB_INSTRUMENT_DIRECTORY NAME">"SET DB_INSTRUMENT_DIRECTORY NAME"</xref></t>
6871                        <t><xref target="SET DB_INSTRUMENT_DIRECTORY DESCRIPTION">"SET DB_INSTRUMENT_DIRECTORY DESCRIPTION"</xref></t>
6872                        <t><xref target="FIND DB_INSTRUMENT_DIRECTORIES">"FIND DB_INSTRUMENT_DIRECTORIES"</xref></t>
6873                        <t><xref target="SET DB_INSTRUMENT NAME">"SET DB_INSTRUMENT NAME"</xref></t>
6874                        <t><xref target="SET DB_INSTRUMENT DESCRIPTION">"SET DB_INSTRUMENT DESCRIPTION"</xref></t>
6875                        <t><xref target="FIND DB_INSTRUMENTS">"FIND DB_INSTRUMENTS"</xref></t>
6876                    </list>
6877                    Please note that these lists are manually maintained. If you
6878                    find a command that also supports escape sequences we forgot to
6879                    mention here, please report it!
6880                    </t>
6881                </section>
6882          </section>          </section>
6883    
6884          <section title="Events" anchor="events">          <section title="Events" anchor="events">
# Line 4829  Schoenebeck'> Line 6993  Schoenebeck'>
6993                  <t>Server will start sending the following notification messages:</t>                  <t>Server will start sending the following notification messages:</t>
6994                  <t>                  <t>
6995                      <list>                      <list>
6996                          <t>"NOTIFY:VOICE_COUNT:&lt;sampler-channel&gt; &lt;voices&gt;</t>                          <t>"NOTIFY:VOICE_COUNT:&lt;sampler-channel&gt; &lt;voices&gt;"</t>
6997                      </list>                      </list>
6998                  </t>                  </t>
6999                  <t>where &lt;sampler-channel&gt; will be replaced by the sampler channel the                  <t>where &lt;sampler-channel&gt; will be replaced by the sampler channel the
# Line 4899  Schoenebeck'> Line 7063  Schoenebeck'>
7063                  message is sufficient here.</t>                  message is sufficient here.</t>
7064              </section>              </section>
7065    
7066                <section title="Number of effect sends changed" anchor="SUBSCRIBE FX_SEND_COUNT">
7067                    <t>Client may want to be notified when the number of effect sends on
7068                    a particular sampler channel is changed by issuing the following command:</t>
7069                    <t>
7070                        <list>
7071                            <t>SUBSCRIBE FX_SEND_COUNT</t>
7072                        </list>
7073                    </t>
7074                    <t>Server will start sending the following notification messages:</t>
7075                    <t>
7076                        <list>
7077                            <t>"NOTIFY:FX_SEND_COUNT:&lt;channel-id&gt; &lt;fx-sends&gt;"</t>
7078                        </list>
7079                    </t>
7080                    <t>where &lt;channel-id&gt; will be replaced by the numerical ID of the sampler
7081                    channel, on which the effect sends number is changed and &lt;fx-sends&gt; will
7082                    be replaced by the new number of effect sends on that channel.</t>
7083                </section>
7084    
7085                <section title="Effect send information changed" anchor="SUBSCRIBE FX_SEND_INFO">
7086                    <t>Client may want to be notified when changes were made to effect sends on a
7087                    a particular sampler channel by issuing the following command:</t>
7088                    <t>
7089                        <list>
7090                            <t>SUBSCRIBE FX_SEND_INFO</t>
7091                        </list>
7092                    </t>
7093                    <t>Server will start sending the following notification messages:</t>
7094                    <t>
7095                        <list>
7096                            <t>"NOTIFY:FX_SEND_INFO:&lt;channel-id&gt; &lt;fx-send-id&gt;"</t>
7097                        </list>
7098                    </t>
7099                    <t>where &lt;channel-id&gt; will be replaced by the numerical ID of the sampler
7100                    channel, on which an effect send entity is changed and &lt;fx-send-id&gt; will
7101                    be replaced by the numerical ID of the changed effect send.</t>
7102                </section>
7103    
7104              <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">
7105                  <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
7106                  back-end changes by issuing the following command:</t>                  back-end changes by issuing the following command:</t>
# Line 4910  Schoenebeck'> Line 7112  Schoenebeck'>
7112                  <t>Server will start sending the following notification messages:</t>                  <t>Server will start sending the following notification messages:</t>
7113                  <t>                  <t>
7114                      <list>                      <list>
7115                          <t>"NOTIFY:TOTAL_VOICE_COUNT:&lt;voices&gt;</t>                          <t>"NOTIFY:TOTAL_VOICE_COUNT:&lt;voices&gt;"</t>
7116                      </list>                      </list>
7117                  </t>                  </t>
7118                  <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
# Line 4971  Schoenebeck'> Line 7173  Schoenebeck'>
7173                          <t>"NOTIFY:MIDI_INSTRUMENT_COUNT:&lt;map-id&gt; &lt;instruments&gt;"</t>                          <t>"NOTIFY:MIDI_INSTRUMENT_COUNT:&lt;map-id&gt; &lt;instruments&gt;"</t>
7174                      </list>                      </list>
7175                  </t>                  </t>
7176                  <t>where &lt;map-id&gt; is the numerical ID of the MIDI instrument map, in which                  <t>where &lt;map-id&gt; is the numerical ID of the MIDI instrument map, in which
7177                  the nuber of instruments has changed and &lt;instruments&gt; will be replaced by                  the nuber of instruments has changed and &lt;instruments&gt; will be replaced by
7178                  the new number of MIDI instruments in the specified map.</t>                  the new number of MIDI instruments in the specified map.</t>
7179              </section>              </section>
# Line 4991  Schoenebeck'> Line 7193  Schoenebeck'>
7193                      </list>                      </list>
7194                  </t>                  </t>
7195                  <t>where &lt;map-id&gt; will be replaced by the numerical ID of the MIDI instrument map,                  <t>where &lt;map-id&gt; will be replaced by the numerical ID of the MIDI instrument map,
7196                  in which a MIDI instrument is changed. &lt;bank&gt; and &lt;program&gt; specifies                  in which a MIDI instrument is changed. &lt;bank&gt; and &lt;program&gt; specifies
7197                  the location of the changed MIDI instrument in the map. The front-end will have to send                  the location of the changed MIDI instrument in the map. The front-end will have to send
7198                  the respective command to actually get the MIDI instrument info. Because these messages                  the respective command to actually get the MIDI instrument info. Because these messages
7199                  will be triggered by LSCP commands issued by other clients rather than real                  will be triggered by LSCP commands issued by other clients rather than real
# Line 4999  Schoenebeck'> Line 7201  Schoenebeck'>
7201                  message is sufficient here.</t>                  message is sufficient here.</t>
7202              </section>              </section>
7203    
7204              <<section title="Miscellaneous and debugging events" anchor="SUBSCRIBE MISCELLANEOUS">              <section title="Global settings changed" anchor="SUBSCRIBE GLOBAL_INFO">
7205                    <t>Client may want to be notified when changes to the global settings
7206                    of the sampler were made by issuing the following command:</t>
7207                    <t>
7208                        <list>
7209                            <t>SUBSCRIBE GLOBAL_INFO</t>
7210                        </list>
7211                    </t>
7212                    <t>Server will start sending the following types of notification messages:</t>
7213                    <t>
7214                        <list>
7215                            <t>"NOTIFY:GLOBAL_INFO:VOLUME &lt;volume&gt;" - Notifies that the
7216                            golbal volume of the sampler is changed, where &lt;volume&gt; will be
7217                            replaced by the optional dotted floating point value, reflecting the
7218                            new global volume parameter.</t>
7219                        </list>
7220                    </t>
7221                </section>
7222    
7223                <section title="Number of database instrument directories changed" anchor="SUBSCRIBE DB_INSTRUMENT_DIRECTORY_COUNT">
7224                    <t>Client may want to be notified when the number of instrument
7225                    directories in a particular directory in the instruments database
7226                    is changed by issuing the following command:</t>
7227                    <t>
7228                        <list>
7229                            <t>SUBSCRIBE DB_INSTRUMENT_DIRECTORY_COUNT</t>
7230                        </list>
7231                    </t>
7232                    <t>Server will start sending the following notification messages:</t>
7233                    <t>
7234                        <list>
7235                            <t>"NOTIFY:DB_INSTRUMENT_DIRECTORY_COUNT:&lt;dir-path&gt;"</t>
7236                        </list>
7237                    </t>
7238                    <t>where &lt;dir-path&gt; will be replaced by the absolute path
7239                    name of the directory in the instruments database,
7240                    in which the number of directories is changed.</t>
7241                    <t>Note that when a non-empty directory is removed, this event
7242                    is not sent for the subdirectories in that directory.</t>
7243                </section>
7244    
7245                <section title="Database instrument directory information changed" anchor="SUBSCRIBE DB_INSTRUMENT_DIRECTORY_INFO">
7246                    <t>Client may want to be notified when changes were made to directories
7247                    in the instruments database by issuing the following command:</t>
7248                    <t>
7249                        <list>
7250                            <t>SUBSCRIBE DB_INSTRUMENT_DIRECTORY_INFO</t>
7251                        </list>
7252                    </t>
7253                    <t>Server will start sending the following notification messages:</t>
7254                    <t>
7255                        <list>
7256                            <t>"NOTIFY:DB_INSTRUMENT_DIRECTORY_INFO:&lt;dir-path&gt;"</t>
7257                        </list>
7258                    </t>
7259                    <t>where &lt;dir-path&gt; will be replaced by the absolute path name
7260                    of the directory, for which information changes occurred. The front-end will have to send
7261                    the respective command to actually get the updated directory info. Because these messages
7262                    will be triggered by LSCP commands issued by other clients rather than real
7263                    time events happening on the server, it is believed that an empty notification
7264                    message is sufficient here.</t>
7265                    <t>
7266                        <list>
7267                            <t>"NOTIFY:DB_INSTRUMENT_DIRECTORY_INFO:NAME &lt;old-dir-path&gt; &lt;new-name&gt;"</t>
7268                        </list>
7269                    </t>
7270                    <t>where &lt;old-dir-path&gt; is the old absolute path name of the directory
7271                    (encapsulated into apostrophes), which name is changes and &lt;new-name&gt; is
7272                    the new name of the directory, encapsulated into apostrophes.</t>
7273                </section>
7274    
7275                <section title="Number of database instruments changed" anchor="SUBSCRIBE DB_INSTRUMENT_COUNT">
7276                    <t>Client may want to be notified when the number of instruments
7277                    in a particular directory in the instruments database
7278                    is changed by issuing the following command:</t>
7279                    <t>
7280                        <list>
7281                            <t>SUBSCRIBE DB_INSTRUMENT_COUNT</t>
7282                        </list>
7283                    </t>
7284                    <t>Server will start sending the following notification messages:</t>
7285                    <t>
7286                        <list>
7287                            <t>"NOTIFY:DB_INSTRUMENT_COUNT:&lt;dir-path&gt;"</t>
7288                        </list>
7289                    </t>
7290                    <t>where &lt;dir-path&gt; will be replaced by the absolute path
7291                    name of the directory in the instruments database,
7292                    in which the number of instruments is changed.</t>
7293                    <t>Note that when a non-empty directory is removed, this event
7294                    is not sent for the instruments in that directory.</t>
7295                </section>
7296    
7297                <section title="Database instrument information changed" anchor="SUBSCRIBE DB_INSTRUMENT_INFO">
7298                    <t>Client may want to be notified when changes were made to instruments
7299                    in the instruments database by issuing the following command:</t>
7300                    <t>
7301                        <list>
7302                            <t>SUBSCRIBE DB_INSTRUMENT_INFO</t>
7303                        </list>
7304                    </t>
7305                    <t>Server will start sending the following notification messages:</t>
7306                    <t>
7307                        <list>
7308                            <t>"NOTIFY:DB_INSTRUMENT_INFO:&lt;instr-path&gt;"</t>
7309                        </list>
7310                    </t>
7311                    <t>where &lt;instr-path&gt; will be replaced by the absolute path name
7312                    of the instrument, which settings are changed. The front-end will have to send
7313                    the respective command to actually get the updated directory info. Because these messages
7314                    will be triggered by LSCP commands issued by other clients rather than real
7315                    time events happening on the server, it is believed that an empty notification
7316                    message is sufficient here.</t>
7317                    <t>
7318                        <list>
7319                            <t>"NOTIFY:DB_INSTRUMENT_INFO:NAME &lt;old-instr-path&gt; &lt;new-name&gt;"</t>
7320                        </list>
7321                    </t>
7322                    <t>where &lt;old-instr-path&gt; is the old absolute path name of the instrument
7323                    (encapsulated into apostrophes), which name is changes and &lt;new-name&gt; is
7324                    the new name of the instrument, encapsulated into apostrophes.</t>
7325                </section>
7326    
7327                <section title="Database job status information changed" anchor="SUBSCRIBE DB_INSTRUMENTS_JOB_INFO">
7328                    <t>Client may want to be notified when the status of particular database
7329                    instruments job is changed by issuing the following command:</t>
7330                    <t>
7331                        <list>
7332                            <t>SUBSCRIBE DB_INSTRUMENTS_JOB_INFO</t>
7333                        </list>
7334                    </t>
7335                    <t>Server will start sending the following notification messages:</t>
7336                    <t>
7337                        <list>
7338                            <t>"NOTIFY:DB_INSTRUMENTS_JOB_INFO:&lt;job-id&gt;"</t>
7339                        </list>
7340                    </t>
7341                    <t>where &lt;job-id&gt; will be replaced by the numerical ID of the job,
7342                    which status is changed. The front-end will have to send the respective
7343                    command to actually get the status info. Because these messages
7344                    will be triggered by LSCP commands issued by other clients rather than real
7345                    time events happening on the server, it is believed that an empty notification
7346                    message is sufficient here.</t>
7347                </section>
7348    
7349                <section title="Miscellaneous and debugging events" anchor="SUBSCRIBE MISCELLANEOUS">
7350                  <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
7351                  the server by issuing the following command:</t>                  the server by issuing the following command:</t>
7352                  <t>                  <t>
# Line 5077  Schoenebeck'> Line 7424  Schoenebeck'>
7424                  </front>                  </front>
7425                  <seriesInfo name="RFC" value="2234" />                  <seriesInfo name="RFC" value="2234" />
7426              </reference>              </reference>
7427                <reference anchor="RFC20">
7428                    <front>
7429                        <title>ASCII format for Network Interchange</title>
7430                        <author>
7431                            <organization>UCLA</organization>
7432                        </author>
7433                        <date year="1969"></date>
7434                    </front>
7435                    <seriesInfo name="RFC" value="20" />
7436                </reference>
7437           </references>           </references>
7438      </back>      </back>
7439    
Legend:
Removed from v.981  
changed lines
  Added in v.1391
  ViewVC Help
Powered by ViewVC