/[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 1772 by iliev, Wed Sep 10 15:11:41 2008 UTC
# Line 16  Line 16 
16       to an annoying "missing Normative/Informative References" error message -->       to an annoying "missing Normative/Informative References" error message -->
17  <?rfc strict="no" ?>  <?rfc strict="no" ?>
18    
19  <rfc category="std" ipr="full3978" docName="LSCP 1.2">  <rfc category="std" ipr="full3978" docName="LSCP 1.4">
20      <front>      <front>
21          <title>LinuxSampler Control Protocol</title>          <title>LinuxSampler Control Protocol</title>
22          <author initials='C.S.' surname="Schoenebeck" fullname='C.          <author initials='C.S.' surname="Schoenebeck" fullname='C.
# Line 34  Schoenebeck'> Line 34  Schoenebeck'>
34                  <email>schoenebeck at software minus engineering dot org</email>                  <email>schoenebeck at software minus engineering dot org</email>
35              </address>              </address>
36          </author>          </author>
37          <date month="December" year="2006"/>          <date month="September" year="2008"/>
38          <workgroup>LinuxSampler Developers</workgroup>          <workgroup>LinuxSampler Developers</workgroup>
39          <keyword>LSCP</keyword>          <keyword>LSCP</keyword>
40          <abstract>          <abstract>
# Line 61  Schoenebeck'> Line 61  Schoenebeck'>
61              (front-end) and server (LinuxSampler) respectively. Lines in              (front-end) and server (LinuxSampler) respectively. Lines in
62              examples must be interpreted as every line being CRLF              examples must be interpreted as every line being CRLF
63              terminated (carriage return character followed by line feed              terminated (carriage return character followed by line feed
64              character as defined in the ASCII standard), thus the following              character as defined in the ASCII standard <xref target="RFC20"/>),
65              example:</t>              thus the following example:</t>
66    
67              <t>              <t>
68                  <list>                  <list>
# Line 2061  Schoenebeck'> Line 2061  Schoenebeck'>
2061                      or <xref target="LIST MIDI_INPUT_DEVICES">"LIST MIDI_INPUT_DEVICES"</xref>                      or <xref target="LIST MIDI_INPUT_DEVICES">"LIST MIDI_INPUT_DEVICES"</xref>
2062                      command, &lt;port&gt; by the MIDI port number, &lt;key&gt; by the name of                      command, &lt;port&gt; by the MIDI port number, &lt;key&gt; by the name of
2063                      the parameter to change and &lt;value&gt; by the new value for this                      the parameter to change and &lt;value&gt; by the new value for this
2064                      parameter.</t>                      parameter (encapsulated into apostrophes) or NONE (not encapsulated into apostrophes)
2065                        for specifying no value for parameters allowing a list of values.</t>
2066    
2067                      <t>Possible Answers:</t>                      <t>Possible Answers:</t>
2068                      <t>                      <t>
# Line 2088  Schoenebeck'> Line 2089  Schoenebeck'>
2089                      <t>Example:</t>                      <t>Example:</t>
2090                      <t>                      <t>
2091                          <list>                          <list>
2092                              <t></t>                              <t>C: "SET MIDI_INPUT_PORT_PARAMETER 0 0 ALSA_SEQ_BINDINGS='20:0'"</t>
2093                                <t>S: "OK"</t>
2094                            </list>
2095                        </t>
2096                        <t>
2097                            <list>
2098                                <t>C: "SET MIDI_INPUT_PORT_PARAMETER 0 0 ALSA_SEQ_BINDINGS=NONE"</t>
2099                                <t>S: "OK"</t>
2100                          </list>                          </list>
2101                      </t>                      </t>
2102                  </section>                  </section>
# Line 2113  Schoenebeck'> Line 2121  Schoenebeck'>
2121                      number of the sampler channel the instrument should be assigned to.                      number of the sampler channel the instrument should be assigned to.
2122                      Each sampler channel can only have one instrument.</t>                      Each sampler channel can only have one instrument.</t>
2123    
2124                        <t>Notice: since LSCP 1.2 the &lt;filename&gt; argument supports
2125                        escape characters for special characters (see chapter
2126                        "<xref target="character_set">Character Set and Escape Sequences</xref>"
2127                        for details) and accordingly backslash characters in the filename
2128                        MUST now be escaped as well!</t>
2129    
2130                      <t>The difference between regular and NON_MODAL versions of the command                      <t>The difference between regular and NON_MODAL versions of the command
2131                      is that the regular command returns OK only after the instrument has been                      is that the regular command returns OK only after the instrument has been
2132                      fully loaded and the channel is ready to be used while NON_MODAL version                      fully loaded and the channel is ready to be used while NON_MODAL version
# Line 2148  Schoenebeck'> Line 2162  Schoenebeck'>
2162                              </t>                              </t>
2163                          </list>                          </list>
2164                      </t>                      </t>
2165                      <t>Example:</t>                      <t>Example (Unix):</t>
2166                      <t>                      <t>
2167                          <list>                          <list>
2168                              <t></t>                              <t>C: LOAD INSTRUMENT '/home/joe/gigs/cello.gig' 0 0</t>
2169                                <t>S: OK</t>
2170                            </list>
2171                        </t>
2172                        <t>Example (Windows):</t>
2173                        <t>
2174                            <list>
2175                                <t>C: LOAD INSTRUMENT 'D:/MySounds/cello.gig' 0 0</t>
2176                                <t>S: OK</t>
2177                          </list>                          </list>
2178                      </t>                      </t>
2179                  </section>                  </section>
# Line 2429  Schoenebeck'> Line 2451  Schoenebeck'>
2451                                  <list>                                  <list>
2452                                      <t>DESCRIPTION -                                      <t>DESCRIPTION -
2453                                          <list>                                          <list>
2454                                              <t>arbitrary description text about the engine</t>                                              <t>arbitrary description text about the engine
2455                                                (note that the character string may contain
2456                                                <xref target="character_set">escape sequences</xref>)</t>
2457                                          </list>                                          </list>
2458                                      </t>                                      </t>
2459                                       <t>VERSION -                                       <t>VERSION -
# Line 2513  Schoenebeck'> Line 2537  Schoenebeck'>
2537                                          <list>                                          <list>
2538                                              <t>the file name of the loaded instrument, "NONE" if                                              <t>the file name of the loaded instrument, "NONE" if
2539                                              there's no instrument yet loaded for this sampler                                              there's no instrument yet loaded for this sampler
2540                                              channel</t>                                              channel (note: since LSCP 1.2 this path may contain
2541                                                <xref target="character_set">escape sequences</xref>)</t>
2542                                          </list>                                          </list>
2543                                      </t>                                      </t>
2544                                      <t>INSTRUMENT_NR -                                      <t>INSTRUMENT_NR -
# Line 2523  Schoenebeck'> Line 2548  Schoenebeck'>
2548                                      </t>                                      </t>
2549                                      <t>INSTRUMENT_NAME -                                      <t>INSTRUMENT_NAME -
2550                                          <list>                                          <list>
2551                                              <t>the instrument name of the loaded instrument</t>                                              <t>the instrument name of the loaded instrument
2552                                                (note: since LSCP 1.2 this character string may contain
2553                                                <xref target="character_set">escape sequences</xref>)</t>
2554                                          </list>                                          </list>
2555                                      </t>                                      </t>
2556                                      <t>INSTRUMENT_STATUS -                                      <t>INSTRUMENT_STATUS -
# Line 2555  Schoenebeck'> Line 2582  Schoenebeck'>
2582                                      <t>VOLUME -                                      <t>VOLUME -
2583                                          <list>                                          <list>
2584                                              <t>optionally dotted number for the channel volume factor                                              <t>optionally dotted number for the channel volume factor
2585                                              (where a value < 1.0 means attenuation and a value >                                              (where a value &lt; 1.0 means attenuation and a value >
2586                                              1.0 means amplification)</t>                                              1.0 means amplification)</t>
2587                                          </list>                                          </list>
2588                                      </t>                                      </t>
# Line 3227  Schoenebeck'> Line 3254  Schoenebeck'>
3254                      </t>                      </t>
3255                  </section>                  </section>
3256    
3257                    <section title="Adding an effect send to a sampler channel" anchor="CREATE FX_SEND">
3258                        <t>The front-end can create an additional effect send on a specific sampler channel
3259                        by sending the following command:</t>
3260                        <t>
3261                            <list>
3262                                <t>CREATE FX_SEND &lt;sampler-channel&gt; &lt;midi-ctrl&gt; [&lt;name&gt;]</t>
3263                            </list>
3264                        </t>
3265                        <t>Where &lt;sampler-channel&gt; is the respective sampler channel
3266                        number as returned by the <xref target="ADD CHANNEL">"ADD CHANNEL"</xref>
3267                        or <xref target="LIST CHANNELS">"LIST CHANNELS"</xref> command, that is the
3268                        sampler channel on which the effect send should be created on, &lt;midi-ctrl&gt;
3269                        is a number between 0..127 defining the MIDI controller which can alter the
3270                        effect send level and &lt;name&gt; is an optional argument defining a name
3271                        for the effect send entity. The name does not have to be unique, but MUST be
3272                        encapsulated into apostrophes and supports escape sequences as described in chapter
3273                        "<xref target="character_set">Character Set and Escape Sequences</xref>".</t>
3274    
3275                        <t>By default, that is as initial routing, the effect send's audio channels
3276                        are automatically routed to the last audio channels of the sampler channel's
3277                        audio output device, that way you can i.e. first increase the amount of audio
3278                        channels on the audio output device for having dedicated effect send output
3279                        channels and when "CREATE FX_SEND" is called, those channels will automatically
3280                        be picked. You can alter the destination channels however with
3281                        <xref target="SET FX_SEND AUDIO_OUTPUT_CHANNEL">"SET FX_SEND AUDIO_OUTPUT_CHANNEL"</xref>.
3282                        </t>
3283    
3284                        <t>Note: Create effect sends on a sampler channel only when needed, because having effect
3285                        sends on a sampler channel will decrease runtime performance, because for implementing channel
3286                        effect sends, separate (sampler channel local) audio buffers are needed to render and mix
3287                        the voices and route the audio signal afterwards to the master outputs and effect send
3288                        outputs (along with their respective effect send levels). A sampler channel without effect
3289                        sends however can mix its voices directly into the audio output devices's audio buffers
3290                        and is thus faster.
3291                        </t>
3292    
3293                        <t>Possible Answers:</t>
3294                        <t>
3295                            <list>
3296                                <t>"OK[&lt;fx-send-id&gt;]" -
3297                                    <list>
3298                                        <t>in case a new effect send could be added to the
3299                                        sampler channel, where &lt;fx-send-id&gt; reflects the
3300                                        unique ID of the newly created effect send entity</t>
3301                                    </list>
3302                                </t>
3303                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
3304                                    <list>
3305                                        <t>when a new effect send could not be added, i.e.
3306                                        due to invalid parameters</t>
3307                                    </list>
3308                                </t>
3309                            </list>
3310                        </t>
3311    
3312                        <t>Examples:</t>
3313                        <t>
3314                            <list>
3315                                <t>C: "CREATE FX_SEND 0 91 'Reverb Send'"</t>
3316                                <t>S: "OK[0]"</t>
3317                            </list>
3318                        </t>
3319                        <t>
3320                            <list>
3321                                <t>C: "CREATE FX_SEND 0 93"</t>
3322                                <t>S: "OK[1]"</t>
3323                            </list>
3324                        </t>
3325                    </section>
3326    
3327                    <section title="Removing an effect send from a sampler channel" anchor="DESTROY FX_SEND">
3328                        <t>The front-end can remove an existing effect send on a specific sampler channel
3329                        by sending the following command:</t>
3330                        <t>
3331                            <list>
3332                                <t>DESTROY FX_SEND &lt;sampler-channel&gt; &lt;fx-send-id&gt;</t>
3333                            </list>
3334                        </t>
3335                        <t>Where &lt;sampler-channel&gt; is the respective sampler channel
3336                        number as returned by the <xref target="ADD CHANNEL">"ADD CHANNEL"</xref>
3337                        or <xref target="LIST CHANNELS">"LIST CHANNELS"</xref> command, that is the
3338                        sampler channel from which the effect send should be removed from and
3339                        &lt;fx-send-id&gt; is the respective effect send number as returned by the
3340                        <xref target="CREATE FX_SEND">"CREATE FX_SEND"</xref>
3341                        or <xref target="LIST FX_SENDS">"LIST FX_SENDS"</xref> command.</t>
3342    
3343                        <t>Possible Answers:</t>
3344                        <t>
3345                            <list>
3346                                <t>"OK" -
3347                                    <list>
3348                                        <t>on success</t>
3349                                    </list>
3350                                </t>
3351                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
3352                                    <list>
3353                                        <t>in case it failed, providing an appropriate error code and
3354                                        error message</t>
3355                                    </list>
3356                                </t>
3357                            </list>
3358                        </t>
3359    
3360                        <t>Example:</t>
3361                        <t>
3362                            <list>
3363                                <t>C: "DESTROY FX_SEND 0 0"</t>
3364                                <t>S: "OK"</t>
3365                            </list>
3366                        </t>
3367                    </section>
3368    
3369                    <section title="Getting amount of effect sends on a sampler channel" anchor="GET FX_SENDS">
3370                        <t>The front-end can ask for the amount of effect sends on a specific sampler channel
3371                        by sending the following command:</t>
3372                        <t>
3373                            <list>
3374                                <t>GET FX_SENDS &lt;sampler-channel&gt;</t>
3375                            </list>
3376                        </t>
3377                        <t>Where &lt;sampler-channel&gt; is the respective sampler channel
3378                        number as returned by the <xref target="ADD CHANNEL">"ADD CHANNEL"</xref>
3379                        or <xref target="LIST CHANNELS">"LIST CHANNELS"</xref> command.</t>
3380    
3381                        <t>Possible Answers:</t>
3382                        <t>
3383                            <list>
3384                                <t>The sampler will answer by returning the number of effect
3385                                sends on the given sampler channel.</t>
3386                            </list>
3387                        </t>
3388    
3389                        <t>Example:</t>
3390                        <t>
3391                            <list>
3392                                <t>C: "GET FX_SENDS 0"</t>
3393                                <t>S: "2"</t>
3394                            </list>
3395                        </t>
3396                    </section>
3397    
3398                    <section title="Listing all effect sends on a sampler channel" anchor="LIST FX_SENDS">
3399                        <t>The front-end can ask for a list of effect sends on a specific sampler channel
3400                        by sending the following command:</t>
3401                        <t>
3402                            <list>
3403                                <t>LIST FX_SENDS &lt;sampler-channel&gt;</t>
3404                            </list>
3405                        </t>
3406                        <t>Where &lt;sampler-channel&gt; is the respective sampler channel
3407                        number as returned by the <xref target="ADD CHANNEL">"ADD CHANNEL"</xref>
3408                        or <xref target="LIST CHANNELS">"LIST CHANNELS"</xref> command.</t>
3409    
3410                        <t>Possible Answers:</t>
3411                        <t>
3412                            <list>
3413                                <t>The sampler will answer by returning a comma separated list
3414                                with all effect sends' numerical IDs on the given sampler
3415                                channel.</t>
3416                            </list>
3417                        </t>
3418    
3419                        <t>Examples:</t>
3420                        <t>
3421                            <list>
3422                                <t>C: "LIST FX_SENDS 0"</t>
3423                                <t>S: "0,1"</t>
3424                            </list>
3425                        </t>
3426                        <t>
3427                            <list>
3428                                <t>C: "LIST FX_SENDS 1"</t>
3429                                <t>S: ""</t>
3430                            </list>
3431                        </t>
3432                    </section>
3433    
3434                    <section title="Getting effect send information" anchor="GET FX_SEND INFO">
3435                        <t>The front-end can ask for the current settings of an effect send entity
3436                        by sending the following command:</t>
3437                        <t>
3438                            <list>
3439                                <t>GET FX_SEND INFO &lt;sampler-channel&gt; &lt;fx-send-id&gt;</t>
3440                            </list>
3441                        </t>
3442                        <t>Where &lt;sampler-channel&gt; is the sampler channel number
3443                        as returned by the <xref target="ADD CHANNEL">"ADD CHANNEL"</xref>
3444                        or <xref target="LIST CHANNELS">"LIST CHANNELS"</xref> command and
3445                        &lt;fx-send-id&gt; reflects the numerical ID of the effect send entity
3446                        as returned by the <xref target="CREATE FX_SEND">"CREATE FX_SEND"</xref>
3447                        or <xref target="LIST FX_SENDS">"LIST FX_SENDS"</xref> command.
3448                       </t>
3449    
3450                        <t>Possible Answers:</t>
3451                        <t>
3452                            <list>
3453                                <t>The sampler will answer by sending a &lt;CRLF&gt; separated list.
3454                                Each answer line begins with the settings category name
3455                                followed by a colon and then a space character &lt;SP&gt; and finally
3456                                the info character string to that setting category. At the
3457                                moment the following categories are defined:</t>
3458    
3459                                <t>
3460                                    <list>
3461                                        <t>NAME -
3462                                            <list>
3463                                                <t>name of the effect send entity
3464                                                (note that this character string may contain
3465                                                 <xref target="character_set">escape sequences</xref>)</t>
3466                                            </list>
3467                                        </t>
3468                                        <t>MIDI_CONTROLLER -
3469                                            <list>
3470                                                <t>a value between 0 and 127 reflecting the MIDI controller
3471                                                which is able to modify the effect send's send level</t>
3472                                            </list>
3473                                        </t>
3474                                        <t>LEVEL -
3475                                            <list>
3476                                                <t>optionally dotted number reflecting the effect send's
3477                                                current send level (where a value &lt; 1.0 means attenuation
3478                                                and a value > 1.0 means amplification)</t>
3479                                            </list>
3480                                        </t>
3481                                        <t>AUDIO_OUTPUT_ROUTING -
3482                                            <list>
3483                                                <t>comma separated list which reflects to which audio
3484                                                channel of the selected audio output device each
3485                                                effect send output channel is routed to, e.g. "0,3" would
3486                                                mean the effect send's output channel 0 is routed to channel
3487                                                0 of the audio output device and the effect send's output
3488                                                channel 1 is routed to the channel 3 of the audio
3489                                                output device (see
3490                                                <xref target="SET FX_SEND AUDIO_OUTPUT_CHANNEL">"SET FX_SEND AUDIO_OUTPUT_CHANNEL"</xref>
3491                                                for details)</t>
3492                                            </list>
3493                                        </t>
3494                                    </list>
3495                                </t>
3496                            </list>
3497                        </t>
3498                        <t>The mentioned fields above don't have to be in particular order.</t>
3499    
3500                        <t>Example:</t>
3501                        <t>
3502                            <list>
3503                                <t>C: "GET FX_SEND INFO 0 0"</t>
3504                                <t>S: "NAME: Reverb Send"</t>
3505                                <t>&nbsp;&nbsp;&nbsp;"MIDI_CONTROLLER: 91"</t>
3506                                <t>&nbsp;&nbsp;&nbsp;"LEVEL: 0.3"</t>
3507                                <t>&nbsp;&nbsp;&nbsp;"AUDIO_OUTPUT_ROUTING: 2,3"</t>
3508                                <t>&nbsp;&nbsp;&nbsp;"."</t>
3509                            </list>
3510                        </t>
3511                    </section>
3512    
3513                    <section title="Changing effect send's name" anchor="SET FX_SEND NAME">
3514                        <t>The front-end can alter the current name of an effect
3515                        send entity by sending the following command:</t>
3516                        <t>
3517                            <list>
3518                                <t>SET FX_SEND NAME &lt;sampler-chan&gt; &lt;fx-send-id&gt; &lt;name&gt;</t>
3519                            </list>
3520                        </t>
3521                        <t>Where &lt;sampler-chan&gt; is the sampler channel number
3522                        as returned by the <xref target="ADD CHANNEL">"ADD CHANNEL"</xref>
3523                        or <xref target="LIST CHANNELS">"LIST CHANNELS"</xref> command,
3524                        &lt;fx-send-id&gt; reflects the numerical ID of the effect send entity
3525                        as returned by the <xref target="CREATE FX_SEND">"CREATE FX_SEND"</xref>
3526                        or <xref target="LIST FX_SENDS">"LIST FX_SENDS"</xref> command and
3527                        &lt;name&gt; is the new name of the effect send entity, which
3528                        does not have to be unique (name MUST be encapsulated into apostrophes
3529                        and supports escape sequences as described in chapter
3530                        "<xref target="character_set">Character Set and Escape Sequences</xref>").
3531                        </t>
3532    
3533                        <t>Possible Answers:</t>
3534                        <t>
3535                            <list>
3536                                <t>"OK" -
3537                                    <list>
3538                                        <t>on success</t>
3539                                    </list>
3540                                </t>
3541                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
3542                                    <list>
3543                                        <t>in case it failed, providing an appropriate error code and error message</t>
3544                                    </list>
3545                                </t>
3546                            </list>
3547                        </t>
3548                        <t>Example:</t>
3549                        <t>
3550                            <list>
3551                                <t>C: "SET FX_SEND NAME 0 0 'Fx Send 1'"</t>
3552                                <t>S: "OK"</t>
3553                            </list>
3554                        </t>
3555                    </section>
3556    
3557                    <section title="Altering effect send's audio routing" anchor="SET FX_SEND AUDIO_OUTPUT_CHANNEL">
3558                        <t>The front-end can alter the destination of an effect send's audio channel on a specific
3559                        sampler channel by sending the following command:</t>
3560                        <t>
3561                            <list>
3562                                <t>SET FX_SEND AUDIO_OUTPUT_CHANNEL &lt;sampler-chan&gt; &lt;fx-send-id&gt; &lt;audio-src&gt; &lt;audio-dst&gt;</t>
3563                            </list>
3564                        </t>
3565                        <t>Where &lt;sampler-chan&gt; is the sampler channel number
3566                        as returned by the <xref target="ADD CHANNEL">"ADD CHANNEL"</xref>
3567                        or <xref target="LIST CHANNELS">"LIST CHANNELS"</xref> command,
3568                        &lt;fx-send-id&gt; reflects the numerical ID of the effect send entity
3569                        as returned by the <xref target="CREATE FX_SEND">"CREATE FX_SEND"</xref>
3570                        or <xref target="LIST FX_SENDS">"LIST FX_SENDS"</xref> command,
3571                        &lt;audio-src&gt; is the numerical ID of the effect send's audio channel
3572                        which should be rerouted and &lt;audio-dst&gt; is the numerical ID of
3573                        the audio channel of the selected audio output device where &lt;audio-src&gt;
3574                        should be routed to.</t>
3575    
3576                        <t>Note that effect sends can only route audio to the same audio output
3577                        device as assigned to the effect send's sampler channel. Also note that an
3578                        effect send entity does always have exactly as much audio channels as its
3579                        sampler channel. So if the sampler channel is stereo, the effect send does
3580                        have two audio channels as well. Also keep in mind that the amount of audio
3581                        channels on a sampler channel might be dependant not only to the deployed
3582                        sampler engine on the sampler channel, but also dependant to the instrument
3583                        currently loaded. However you can (effectively) turn an i.e. stereo effect
3584                        send into a mono one by simply altering its audio routing appropriately.</t>
3585    
3586                        <t>Possible Answers:</t>
3587                        <t>
3588                            <list>
3589                                <t>"OK" -
3590                                    <list>
3591                                        <t>on success</t>
3592                                    </list>
3593                                </t>
3594                                <t>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
3595                                    <list>
3596                                        <t>if audio output channel was set, but there are noteworthy
3597                                        issue(s) related, providing an appropriate warning code and
3598                                        warning message</t>
3599                                    </list>
3600                                </t>
3601                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
3602                                    <list>
3603                                        <t>in case it failed, providing an appropriate error code and error message</t>
3604                                    </list>
3605                                </t>
3606                            </list>
3607                        </t>
3608                        <t>Example:</t>
3609                        <t>
3610                            <list>
3611                                <t>C: "SET FX_SEND AUDIO_OUTPUT_CHANNEL 0 0 0 2"</t>
3612                                <t>S: "OK"</t>
3613                            </list>
3614                        </t>
3615                    </section>
3616    
3617                    <section title="Altering effect send's MIDI controller" anchor="SET FX_SEND MIDI_CONTROLLER">
3618                        <t>The front-end can alter the MIDI controller of an effect
3619                        send entity by sending the following command:</t>
3620                        <t>
3621                            <list>
3622                                <t>SET FX_SEND MIDI_CONTROLLER &lt;sampler-chan&gt; &lt;fx-send-id&gt; &lt;midi-ctrl&gt;</t>
3623                            </list>
3624                        </t>
3625                        <t>Where &lt;sampler-chan&gt; is the sampler channel number
3626                        as returned by the <xref target="ADD CHANNEL">"ADD CHANNEL"</xref>
3627                        or <xref target="LIST CHANNELS">"LIST CHANNELS"</xref> command,
3628                        &lt;fx-send-id&gt; reflects the numerical ID of the effect send entity
3629                        as returned by the <xref target="CREATE FX_SEND">"CREATE FX_SEND"</xref>
3630                        or <xref target="LIST FX_SENDS">"LIST FX_SENDS"</xref> command and
3631                        &lt;midi-ctrl&gt; reflects the MIDI controller which shall be
3632                        able to modify the effect send's send level.</t>
3633    
3634                        <t>Possible Answers:</t>
3635                        <t>
3636                            <list>
3637                                <t>"OK" -
3638                                    <list>
3639                                        <t>on success</t>
3640                                    </list>
3641                                </t>
3642                                <t>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
3643                                    <list>
3644                                        <t>if MIDI controller was set, but there are noteworthy
3645                                        issue(s) related, providing an appropriate warning code and
3646                                        warning message</t>
3647                                    </list>
3648                                </t>
3649                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
3650                                    <list>
3651                                        <t>in case it failed, providing an appropriate error code and error message</t>
3652                                    </list>
3653                                </t>
3654                            </list>
3655                        </t>
3656                        <t>Example:</t>
3657                        <t>
3658                            <list>
3659                                <t>C: "SET FX_SEND MIDI_CONTROLLER 0 0 91"</t>
3660                                <t>S: "OK"</t>
3661                            </list>
3662                        </t>
3663                    </section>
3664    
3665                    <section title="Altering effect send's send level" anchor="SET FX_SEND LEVEL">
3666                        <t>The front-end can alter the current send level of an effect
3667                        send entity by sending the following command:</t>
3668                        <t>
3669                            <list>
3670                                <t>SET FX_SEND LEVEL &lt;sampler-chan&gt; &lt;fx-send-id&gt; &lt;volume&gt;</t>
3671                            </list>
3672                        </t>
3673                        <t>Where &lt;sampler-chan&gt; is the sampler channel number
3674                        as returned by the <xref target="ADD CHANNEL">"ADD CHANNEL"</xref>
3675                        or <xref target="LIST CHANNELS">"LIST CHANNELS"</xref> command,
3676                        &lt;fx-send-id&gt; reflects the numerical ID of the effect send entity
3677                        as returned by the <xref target="CREATE FX_SEND">"CREATE FX_SEND"</xref>
3678                        or <xref target="LIST FX_SENDS">"LIST FX_SENDS"</xref> command and
3679                        &lt;volume&gt; is an optionally dotted positive number (a value
3680                        smaller than 1.0 means attenuation, whereas a value greater than
3681                        1.0 means amplification) reflecting the new send level.</t>
3682    
3683                        <t>Possible Answers:</t>
3684                        <t>
3685                            <list>
3686                                <t>"OK" -
3687                                    <list>
3688                                        <t>on success</t>
3689                                    </list>
3690                                </t>
3691                                <t>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
3692                                    <list>
3693                                        <t>if new send level was set, but there are noteworthy
3694                                        issue(s) related, providing an appropriate warning code and
3695                                        warning message</t>
3696                                    </list>
3697                                </t>
3698                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
3699                                    <list>
3700                                        <t>in case it failed, providing an appropriate error code and error message</t>
3701                                    </list>
3702                                </t>
3703                            </list>
3704                        </t>
3705                        <t>Example:</t>
3706                        <t>
3707                            <list>
3708                                <t>C: "SET FX_SEND LEVEL 0 0 0.15"</t>
3709                                <t>S: "OK"</t>
3710                            </list>
3711                        </t>
3712                    </section>
3713    
3714                    <section title="Sending MIDI messages to sampler channel" anchor="SEND CHANNEL MIDI_DATA">
3715                        <t>The front-end can send MIDI events to specific sampler channel
3716                        by sending the following command:</t>
3717                        <t>
3718                            <list>
3719                                <t>SEND CHANNEL MIDI_DATA &lt;midi-msg&gt; &lt;sampler-chan&gt; &lt;arg1&gt; &lt;arg2&gt;</t>
3720                            </list>
3721                        </t>
3722                        <t>Where &lt;sampler-chan&gt; is the sampler channel number
3723                        as returned by the <xref target="ADD CHANNEL">"ADD CHANNEL"</xref>
3724                        or <xref target="LIST CHANNELS">"LIST CHANNELS"</xref> command,
3725                        &lt;arg1&gt; and &lt;arg2&gt; arguments depend on the &lt;midi-msg&gt; argument, which
3726                        specifies the MIDI message type. Currently, the following MIDI messages are supported:</t>
3727                        <t>
3728                            <list>
3729                                <t>"NOTE_ON" -
3730                                    <list>
3731                                        <t>For turning on MIDI notes, where &lt;arg1&gt;
3732                                        specifies the key number and &lt;arg2&gt; the velocity
3733                                        as described in the MIDI specification.</t>
3734                                    </list>
3735                                </t>
3736                                <t>"NOTE_OFF" -
3737                                    <list>
3738                                        <t>For turning a currently playing MIDI note off, where &lt;arg1&gt;
3739                                        specifies the key number and &lt;arg2&gt; the velocity
3740                                        as described in the MIDI specification.</t>
3741                                    </list>
3742                                </t>
3743                            </list>
3744                        </t>
3745                        <t>CAUTION: This command is provided for implementations of virtual MIDI keyboards
3746                        and no realtime guarantee whatsoever will be made!</t>
3747                        <t>Possible Answers:</t>
3748                        <t>
3749                            <list>
3750                                <t>"OK" -
3751                                    <list>
3752                                        <t>on success</t>
3753                                    </list>
3754                                </t>
3755                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
3756                                    <list>
3757                                        <t>in case it failed, providing an appropriate error code and error message</t>
3758                                    </list>
3759                                </t>
3760                            </list>
3761                        </t>
3762                        <t>Example:</t>
3763                        <t>
3764                            <list>
3765                                <t>C: "SEND CHANNEL MIDI_DATA NOTE_ON 0 56 112"</t>
3766                                <t>S: "OK"</t>
3767                            </list>
3768                        </t>
3769                    </section>
3770    
3771                  <section title="Resetting a sampler channel" anchor="RESET CHANNEL">                  <section title="Resetting a sampler channel" anchor="RESET CHANNEL">
3772                      <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>
3773                      <t>                      <t>
# Line 3448  Schoenebeck'> Line 3989  Schoenebeck'>
3989                      </t>                      </t>
3990                  </section>                  </section>
3991    
3992                    <section title="Current number of active disk streams" anchor="GET TOTAL_STREAM_COUNT">
3993                        <t>The front-end can ask for the current number of active disk streams on
3994                        the sampler by sending the following command:</t>
3995                        <t>
3996                            <list>
3997                                <t>GET TOTAL_STREAM_COUNT</t>
3998                            </list>
3999                        </t>
4000    
4001                        <t>Possible Answers:</t>
4002                        <t>
4003                            <list>
4004                                <t>LinuxSampler will answer by returning the number of all active
4005                                disk streams on the sampler.</t>
4006                            </list>
4007                        </t>
4008                    </section>
4009    
4010                  <section title="Reset sampler" anchor="RESET">                  <section title="Reset sampler" anchor="RESET">
4011                      <t>The front-end can reset the whole sampler by sending the following command:</t>                      <t>The front-end can reset the whole sampler by sending the following command:</t>
4012                      <t>                      <t>
# Line 3495  Schoenebeck'> Line 4054  Schoenebeck'>
4054                                  <list>                                  <list>
4055                                      <t>DESCRIPTION -                                      <t>DESCRIPTION -
4056                                          <list>                                          <list>
4057                                              <t>arbitrary textual description about the sampler</t>                                              <t>arbitrary textual description about the sampler
4058                                                (note that the character string may contain
4059                                                <xref target="character_set">escape sequences</xref>)</t>
4060                                          </list>                                          </list>
4061                                      </t>                                      </t>
4062                                      <t>VERSION -                                      <t>VERSION -
# Line 3509  Schoenebeck'> Line 4070  Schoenebeck'>
4070                                              complies with (see <xref target="LSCP versioning" /> for details)</t>                                              complies with (see <xref target="LSCP versioning" /> for details)</t>
4071                                          </list>                                          </list>
4072                                      </t>                                      </t>
4073                                        <t>INSTRUMENTS_DB_SUPPORT -
4074                                            <list>
4075                                                <t>either yes or no, specifies whether the
4076                                                sampler is build with instruments database support.</t>
4077                                            </list>
4078                                        </t>
4079                                  </list>                                  </list>
4080                              </t>                              </t>
4081                          </list>                          </list>
# Line 3516  Schoenebeck'> Line 4083  Schoenebeck'>
4083                      <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.
4084                      Other fields might be added in future.</t>                      Other fields might be added in future.</t>
4085                  </section>                  </section>
4086    
4087                    <section title="Getting global volume attenuation" anchor="GET VOLUME">
4088                        <t>The client can ask for the current global sampler-wide volume
4089                        attenuation by sending the following command:</t>
4090                        <t>
4091                            <list>
4092                                <t>GET VOLUME</t>
4093                            </list>
4094                        </t>
4095                        <t>Possible Answers:</t>
4096                        <t>
4097                            <list>
4098                                <t>The sampler will always answer by returning the optional
4099                                dotted floating point coefficient, reflecting the current
4100                                global volume attenuation.
4101                                </t>
4102                            </list>
4103                        </t>
4104                        <t>Note: it is up to the respective sampler engine whether to obey
4105                        that global volume parameter or not, but in general all engines SHOULD
4106                        use this parameter.</t>
4107                    </section>
4108    
4109                    <section title="Setting global volume attenuation" anchor="SET VOLUME">
4110                        <t>The client can alter the current global sampler-wide volume
4111                        attenuation by sending the following command:</t>
4112                        <t>
4113                            <list>
4114                                <t>SET VOLUME &lt;volume&gt;</t>
4115                            </list>
4116                        </t>
4117                       <t>Where &lt;volume&gt; should be replaced by the optional dotted
4118                       floating point value, reflecting the new global volume parameter.
4119                       This value might usually be in the range between 0.0 and 1.0, that
4120                       is for attenuating the overall volume.</t>
4121    
4122                        <t>Possible Answers:</t>
4123                        <t>
4124                            <list>
4125                                <t>"OK" -
4126                                    <list>
4127                                        <t>on success</t>
4128                                    </list>
4129                                </t>
4130                                <t>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
4131                                    <list>
4132                                        <t>if the global volume was set, but there are noteworthy
4133                                        issue(s) related, providing an appropriate warning code and
4134                                        warning message</t>
4135                                    </list>
4136                                </t>
4137                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
4138                                    <list>
4139                                        <t>in case it failed, providing an appropriate error code and error message</t>
4140                                    </list>
4141                                </t>
4142                            </list>
4143                        </t>
4144                    </section>
4145              </section>              </section>
4146    
4147    
# Line 3546  Schoenebeck'> Line 4172  Schoenebeck'>
4172                  cause the sampler to switch to the respective instrument as                  cause the sampler to switch to the respective instrument as
4173                  reflected by the current MIDI instrument map.</t>                  reflected by the current MIDI instrument map.</t>
4174    
4175                  <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">
4176                      <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
4177                      the following command:</t>                      the following command:</t>
4178                      <t>                      <t>
# Line 3556  Schoenebeck'> Line 4182  Schoenebeck'>
4182                      </t>                      </t>
4183                      <t>Where &lt;name&gt; is an optional argument allowing to                      <t>Where &lt;name&gt; is an optional argument allowing to
4184                      assign a custom name to the new map. MIDI instrument Map                      assign a custom name to the new map. MIDI instrument Map
4185                      names do not have to be unique.</t>                      names do not have to be unique, but MUST be encapsulated
4186                        into apostrophes and support escape sequences as described
4187                        in chapter "<xref target="character_set">Character Set and Escape Sequences</xref>".
4188                        </t>
4189    
4190                      <t>Possible Answers:</t>                      <t>Possible Answers:</t>
4191                      <t>                      <t>
# Line 3727  Schoenebeck'> Line 4356  Schoenebeck'>
4356                                      <t>NAME -                                      <t>NAME -
4357                                          <list>                                          <list>
4358                                              <t>custom name of the given map,                                              <t>custom name of the given map,
4359                                              which does not have to be unique</t>                                              which does not have to be unique
4360                                                (note that this character string may contain
4361                                                 <xref target="character_set">escape sequences</xref>)</t>
4362                                            </list>
4363                                        </t>
4364                                        <t>DEFAULT -
4365                                            <list>
4366                                                <t>either true or false,
4367                                                defines whether this map is the default map</t>
4368                                          </list>                                          </list>
4369                                      </t>                                      </t>
4370                                  </list>                                  </list>
# Line 3741  Schoenebeck'> Line 4378  Schoenebeck'>
4378                          <list>                          <list>
4379                              <t>C: "GET MIDI_INSTRUMENT_MAP INFO 0"</t>                              <t>C: "GET MIDI_INSTRUMENT_MAP INFO 0"</t>
4380                              <t>S: "NAME: Standard Map"</t>                              <t>S: "NAME: Standard Map"</t>
4381                                <t>&nbsp;&nbsp;&nbsp;"DEFAULT: true"</t>
4382                              <t>&nbsp;&nbsp;&nbsp;"."</t>                              <t>&nbsp;&nbsp;&nbsp;"."</t>
4383                          </list>                          </list>
4384                      </t>                      </t>
# Line 3756  Schoenebeck'> Line 4394  Schoenebeck'>
4394                      </t>                      </t>
4395                      <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
4396                      &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
4397                      have to be unique.</t>                      have to be unique (name MUST be encapsulated into apostrophes
4398                        and supports escape sequences as described in chapter
4399                        "<xref target="character_set">Character Set and Escape Sequences</xref>").
4400                        </t>
4401    
4402                      <t>Possible Answers:</t>                      <t>Possible Answers:</t>
4403                      <t>                      <t>
# Line 3789  Schoenebeck'> Line 4430  Schoenebeck'>
4430                      command:</t>                      command:</t>
4431                      <t>                      <t>
4432                          <list>                          <list>
4433                              <t>MAP MIDI_INSTRUMENT &lt;map&gt;                              <t>MAP MIDI_INSTRUMENT [NON_MODAL] &lt;map&gt;
4434                              &lt;midi_bank&gt; &lt;midi_prog&gt; &lt;engine_name&gt;                              &lt;midi_bank&gt; &lt;midi_prog&gt; &lt;engine_name&gt;
4435                              &lt;filename&gt; &lt;instrument_index&gt; &lt;volume_value&gt;                              &lt;filename&gt; &lt;instrument_index&gt; &lt;volume_value&gt;
4436                              [&lt;instr_load_mode&gt;] [&lt;name&gt;]</t>                              [&lt;instr_load_mode&gt;] [&lt;name&gt;]</t>
# Line 3803  Schoenebeck'> Line 4444  Schoenebeck'>
4444                      index, &lt;engine_name&gt; a sampler engine name as returned by                      index, &lt;engine_name&gt; a sampler engine name as returned by
4445                      the <xref target="LIST AVAILABLE_ENGINES">"LIST AVAILABLE_ENGINES"</xref>                      the <xref target="LIST AVAILABLE_ENGINES">"LIST AVAILABLE_ENGINES"</xref>
4446                      command (not encapsulated into apostrophes), &lt;filename&gt; the name                      command (not encapsulated into apostrophes), &lt;filename&gt; the name
4447                      of the instrument's file to be deployed (encapsulated into apostrophes),                      of the instrument's file to be deployed (encapsulated into apostrophes,
4448                        supporting escape sequences as described in chapter
4449                        "<xref target="character_set">Character Set and Escape Sequences</xref>"),
4450                      &lt;instrument_index&gt; the index (integer value) of the instrument                      &lt;instrument_index&gt; the index (integer value) of the instrument
4451                      within the given file, &lt;volume_value&gt; reflects the master                      within the given file, &lt;volume_value&gt; reflects the master
4452                      volume of the instrument as optionally dotted number (where a                      volume of the instrument as optionally dotted number (where a
4453                      value < 1.0 means attenuation and a value > 1.0 means                      value &lt; 1.0 means attenuation and a value > 1.0 means
4454                      amplification). This parameter easily allows to adjust the                      amplification). This parameter easily allows to adjust the
4455                      volume of all intruments within a custom instrument map                      volume of all intruments within a custom instrument map
4456                      without having to adjust their instrument files. The                      without having to adjust their instrument files. The
# Line 3842  Schoenebeck'> Line 4485  Schoenebeck'>
4485                              <t>"PERSISTENT" -                              <t>"PERSISTENT" -
4486                                  <list>                                  <list>
4487                                      <t>The instrument will immediately be loaded                                      <t>The instrument will immediately be loaded
4488                                      into memory in the background when this mapping                                      into memory when this mapping
4489                                      command is sent and the instrument is kept all                                      command is sent and the instrument is kept all
4490                                      the time. Instruments with this mode are                                      the time. Instruments with this mode are
4491                                      only freed when the sampler is reset or all                                      only freed when the sampler is reset or all
# Line 3885  Schoenebeck'> Line 4528  Schoenebeck'>
4528                      load modes of entries, the frontend should retrieve the actual                      load modes of entries, the frontend should retrieve the actual
4529                      mode by i.e. sending                      mode by i.e. sending
4530                      <xref target="GET MIDI_INSTRUMENT INFO">"GET MIDI_INSTRUMENT INFO"</xref>                      <xref target="GET MIDI_INSTRUMENT INFO">"GET MIDI_INSTRUMENT INFO"</xref>
4531                      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
4532                      set a custom name (encapsulated into apostrophes) for the mapping                      (encapsulated into apostrophes, supporting escape sequences as described in chapter
4533                      entry, useful for frontends for displaying an appropriate name for                      "<xref target="character_set">Character Set and Escape Sequences</xref>") for the
4534                        mapping entry, useful for frontends for displaying an appropriate name for
4535                      mapped instruments (using                      mapped instruments (using
4536                      <xref target="GET MIDI_INSTRUMENT INFO">"GET MIDI_INSTRUMENT INFO"</xref>).                      <xref target="GET MIDI_INSTRUMENT INFO">"GET MIDI_INSTRUMENT INFO"</xref>).
4537                      </t>                      </t>
4538                      <t>                      <t>
4539                      The "MAP MIDI_INSTRUMENT" command                      By default, "MAP MIDI_INSTRUMENT" commands block until the mapping is
4540                      will immediately return, thus it will not block when an                      completely established in the sampler. The OPTIONAL "NON_MODAL" argument
4541                      instrument is to be loaded due to a "PERSISTENT" type                      however causes the respective "MAP MIDI_INSTRUMENT" command to return
4542                      entry as instruments are loaded in the background. As a                      immediately, that is to let the sampler establish the mapping in the
4543                      consequence this command may not necessarily return an error                      background. So this argument might be especially useful for mappings with
4544                      i.e. when the given instrument file does not exist or may                      a "PERSISTENT" type, because these have to load the respective instruments
4545                      turn out to be corrupt.                      immediately and might thus block for a very long time. It is recommended
4546                        however to use the OPTIONAL "NON_MODAL" argument only if really necessary,
4547                        because it has the following drawbacks: as "NON_MODAL" instructions return
4548                        immediately, they may not necessarily return an error i.e. when the given
4549                        instrument file turns out to be corrupt, beside that subsequent commands
4550                        in a LSCP instruction sequence might fail, because mandatory mappings are
4551                        not yet completed.
4552                      </t>                      </t>
4553    
4554                      <t>Possible Answers:</t>                      <t>Possible Answers:</t>
# Line 3941  Schoenebeck'> Line 4591  Schoenebeck'>
4591                      </t>                      </t>
4592                      <t>                      <t>
4593                          <list>                          <list>
4594                              <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>
4595                              <t>S: "OK"</t>                              <t>S: "OK"</t>
4596                          </list>                          </list>
4597                      </t>                      </t>
# Line 4105  Schoenebeck'> Line 4755  Schoenebeck'>
4755                                      name for this mapped instrument. It can be set and                                      name for this mapped instrument. It can be set and
4756                                      changed with the                                      changed with the
4757                                      <xref target="MAP MIDI_INSTRUMENT">"MAP MIDI_INSTRUMENT"</xref>                                      <xref target="MAP MIDI_INSTRUMENT">"MAP MIDI_INSTRUMENT"</xref>
4758                                      command and does not have to be unique.</t>                                      command and does not have to be unique.
4759                                        (note that this character string may contain
4760                                        <xref target="character_set">escape sequences</xref>)</t>
4761                                  </list>                                  </list>
4762                              </t>                              </t>
4763                              <t>"ENGINE_NAME" -                              <t>"ENGINE_NAME" -
# Line 4116  Schoenebeck'> Line 4768  Schoenebeck'>
4768                              </t>                              </t>
4769                              <t>"INSTRUMENT_FILE" -                              <t>"INSTRUMENT_FILE" -
4770                                  <list>                                  <list>
4771                                      <t>File name of the instrument.</t>                                      <t>File name of the instrument
4772                                        (note that this path may contain
4773                                        <xref target="character_set">escape sequences</xref>).</t>
4774                                  </list>                                  </list>
4775                              </t>                              </t>
4776                              <t>"INSTRUMENT_NR" -                              <t>"INSTRUMENT_NR" -
# Line 4128  Schoenebeck'> Line 4782  Schoenebeck'>
4782                                  <list>                                  <list>
4783                                      <t>Name of the loaded instrument as reflected by its file.                                      <t>Name of the loaded instrument as reflected by its file.
4784                                      In contrast to the "NAME" field, the "INSTRUMENT_NAME" field                                      In contrast to the "NAME" field, the "INSTRUMENT_NAME" field
4785                                      cannot be changed.</t>                                      cannot be changed (note that this character string may contain
4786                                        <xref target="character_set">escape sequences</xref>).</t>
4787                                  </list>                                  </list>
4788                              </t>                              </t>
4789                              <t>"LOAD_MODE" -                              <t>"LOAD_MODE" -
# Line 4140  Schoenebeck'> Line 4795  Schoenebeck'>
4795                              <t>"VOLUME" -                              <t>"VOLUME" -
4796                                  <list>                                  <list>
4797                                      <t>master volume of the instrument as optionally                                      <t>master volume of the instrument as optionally
4798                                      dotted number (where a value < 1.0 means attenuation                                      dotted number (where a value &lt; 1.0 means attenuation
4799                                      and a value > 1.0 means amplification)</t>                                      and a value > 1.0 means amplification)</t>
4800                                  </list>                                  </list>
4801                              </t>                              </t>
# Line 4212  Schoenebeck'> Line 4867  Schoenebeck'>
4867                  </section>                  </section>
4868              </section>              </section>
4869    
         </section>  
4870    
4871                <section title="Managing Instruments Database" anchor="Managing Instruments Database">
4872                    <t>The following commands describe how to use and manage
4873                    the instruments database.</t>
4874                    <t>Notice:</t>
4875                        <t>
4876                            <list>
4877                                <t>All command arguments representing a path or
4878                                instrument/directory name support escape sequences as described in chapter
4879                                "<xref target="character_set">Character Set and Escape Sequences</xref>".
4880                                </t>
4881                                <t>All occurrences of a forward slash in instrument and directory
4882                                   names are escaped with its hex (\x2f) or octal (\057) escape sequence.
4883                                </t>
4884                            </list>
4885                        </t>
4886    
4887                    <section title="Creating a new instrument directory" anchor="ADD DB_INSTRUMENT_DIRECTORY">
4888                        <t>The front-end can add a new instrument directory to the
4889                        instruments database by sending the following command:</t>
4890                        <t>
4891                            <list>
4892                                <t>ADD DB_INSTRUMENT_DIRECTORY &lt;dir&gt;</t>
4893                            </list>
4894                        </t>
4895                        <t>Where &lt;dir&gt; is the absolute path name of the directory
4896                        to be created (encapsulated into apostrophes).</t>
4897    
4898                        <t>Possible Answers:</t>
4899                        <t>
4900                            <list>
4901                                <t>"OK" -
4902                                    <list>
4903                                        <t>on success</t>
4904                                    </list>
4905                                </t>
4906                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
4907                                    <list>
4908                                        <t>when the directory could not be created, which
4909                                        can happen if the directory already exists or the
4910                                        name contains not allowed symbols</t>
4911                                    </list>
4912                                </t>
4913                            </list>
4914                        </t>
4915    
4916                        <t>Examples:</t>
4917                        <t>
4918                            <list>
4919                                <t>C: "ADD DB_INSTRUMENT_DIRECTORY '/Piano Collection'"</t>
4920                                <t>S: "OK"</t>
4921                            </list>
4922                        </t>
4923                    </section>
4924    
4925                    <section title="Deleting an instrument directory" anchor="REMOVE DB_INSTRUMENT_DIRECTORY">
4926                        <t>The front-end can delete a particular instrument directory
4927                        from the instruments database by sending the following command:</t>
4928                        <t>
4929                            <list>
4930                                <t>REMOVE DB_INSTRUMENT_DIRECTORY [FORCE] &lt;dir&gt;</t>
4931                            </list>
4932                        </t>
4933                        <t>Where &lt;dir&gt; is the absolute path name of the directory
4934                        to delete. The optional FORCE argument can be used to
4935                        force the deletion of a non-empty directory and all its content.</t>
4936    
4937                        <t>Possible Answers:</t>
4938                        <t>
4939                            <list>
4940                                <t>"OK" -
4941                                    <list>
4942                                        <t>if the directory is deleted successfully</t>
4943                                    </list>
4944                                </t>
4945                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
4946                                    <list>
4947                                        <t>if the given directory does not exist, or
4948                                        if trying to delete a non-empty directory,
4949                                        without using the FORCE argument.</t>
4950                                    </list>
4951                                </t>
4952                            </list>
4953                        </t>
4954    
4955                        <t>Examples:</t>
4956                        <t>
4957                            <list>
4958                                <t>C: "REMOVE DB_INSTRUMENT_DIRECTORY FORCE '/Piano Collection'"</t>
4959                                <t>S: "OK"</t>
4960                            </list>
4961                        </t>
4962                    </section>
4963    
4964                    <section title="Getting amount of instrument directories" anchor="GET DB_INSTRUMENT_DIRECTORIES">
4965                        <t>The front-end can retrieve the current amount of
4966                        directories in a specific directory by sending the following command:</t>
4967                        <t>
4968                            <list>
4969                                <t>GET DB_INSTRUMENT_DIRECTORIES [RECURSIVE] &lt;dir&gt;</t>
4970                            </list>
4971                        </t>
4972                        <t>Where &lt;dir&gt; should be replaced by the absolute path
4973                        name of the directory. If RECURSIVE is specified, the number of
4974                        all directories, including those located in subdirectories of the
4975                        specified directory, will be returned.</t>
4976    
4977                        <t>Possible Answers:</t>
4978                        <t>
4979                            <list>
4980                                <t>The current number of instrument directories
4981                                in the specified directory.</t>
4982                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
4983                                    <list>
4984                                        <t>if the given directory does not exist.</t>
4985                                    </list>
4986                                </t>
4987                            </list>
4988                        </t>
4989    
4990                        <t>Example:</t>
4991                        <t>
4992                            <list>
4993                                <t>C: "GET DB_INSTRUMENT_DIRECTORIES '/'"</t>
4994                                <t>S: "2"</t>
4995                            </list>
4996                        </t>
4997                    </section>
4998    
4999                    <section title="Listing all directories in specific directory" anchor="LIST DB_INSTRUMENT_DIRECTORIES">
5000                        <t>The front-end can retrieve the current list of directories
5001                        in specific directory by sending the following command:</t>
5002                        <t>
5003                            <list>
5004                                <t>LIST DB_INSTRUMENT_DIRECTORIES [RECURSIVE] &lt;dir&gt;</t>
5005                            </list>
5006                        </t>
5007                        <t>Where &lt;dir&gt; should be replaced by the absolute path
5008                        name of the directory. If RECURSIVE is specified, the absolute path names
5009                        of all directories, including those located in subdirectories of the
5010                        specified directory, will be returned.</t>
5011    
5012                        <t>Possible Answers:</t>
5013                        <t>
5014                            <list>
5015                                <t>A comma separated list of all instrument directories
5016                                (encapsulated into apostrophes) in the specified directory.</t>
5017                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
5018                                    <list>
5019                                        <t>if the given directory does not exist.</t>
5020                                    </list>
5021                                </t>
5022                            </list>
5023                        </t>
5024                        <t>Example:</t>
5025                        <t>
5026                            <list>
5027                                <t>C: "LIST DB_INSTRUMENT_DIRECTORIES '/'"</t>
5028                                <t>S: "'Piano Collection','Percussion Collection'"</t>
5029                            </list>
5030                        </t>
5031                        <t>
5032                            <list>
5033                                <t>C: "LIST DB_INSTRUMENT_DIRECTORIES RECURSIVE '/'"</t>
5034                                <t>S: "'/Piano Collection','/Piano Collection/Acoustic','/Piano Collection/Acoustic/New','/Percussion Collection'"</t>
5035                            </list>
5036                        </t>
5037                    </section>
5038    
5039                    <section title="Getting instrument directory information" anchor="GET DB_INSTRUMENT_DIRECTORY INFO">
5040                        <t>The front-end can ask for the current settings of an
5041                        instrument directory by sending the following command:</t>
5042                        <t>
5043                            <list>
5044                                <t>GET DB_INSTRUMENT_DIRECTORY INFO &lt;dir&gt;</t>
5045                            </list>
5046                        </t>
5047                        <t>Where &lt;dir&gt; should be replaced by the absolute path
5048                        name of the directory the front-end is interested in.</t>
5049    
5050                        <t>Possible Answers:</t>
5051                        <t>
5052                            <list>
5053                                <t>LinuxSampler will answer by sending a &lt;CRLF&gt; separated list.
5054                                Each answer line begins with the settings category name
5055                                followed by a colon and then a space character &lt;SP&gt; and finally
5056                                the info character string to that setting category. At the
5057                                moment the following categories are defined:</t>
5058    
5059                                <t>
5060                                    <list>
5061                                        <t>DESCRIPTION -
5062                                            <list>
5063                                                <t>A brief description of the directory content.
5064                                                Note that the character string may contain
5065                                                <xref target="character_set">escape sequences</xref>.</t>
5066                                            </list>
5067                                        </t>
5068                                        <t>CREATED -
5069                                            <list>
5070                                                <t>The creation date and time of the directory,
5071                                                represented in "YYYY-MM-DD HH:MM:SS" format</t>
5072                                            </list>
5073                                        </t>
5074                                        <t>MODIFIED -
5075                                            <list>
5076                                                <t>The date and time of the last modification of the
5077                                                directory, represented in "YYYY-MM-DD HH:MM:SS" format</t>
5078                                            </list>
5079                                        </t>
5080                                    </list>
5081                                </t>
5082                            </list>
5083                        </t>
5084                        <t>The mentioned fields above don't have to be in particular order.</t>
5085    
5086                        <t>Example:</t>
5087                        <t>
5088                            <list>
5089                                <t>C: "GET DB_INSTRUMENT_DIRECTORY INFO '/Piano Collection'"</t>
5090                                <t>S: "DESCRIPTION: Piano collection of instruments in GigaSampler format."</t>
5091                                <t>&nbsp;&nbsp;&nbsp;"CREATED: 2007-02-05 10:23:12"</t>
5092                                <t>&nbsp;&nbsp;&nbsp;"MODIFIED: 2007-04-07 12:50:21"</t>
5093                                <t>&nbsp;&nbsp;&nbsp;"."</t>
5094                            </list>
5095                        </t>
5096                    </section>
5097    
5098                    <section title="Renaming an instrument directory" anchor="SET DB_INSTRUMENT_DIRECTORY NAME">
5099                        <t>The front-end can alter the name of a specific
5100                        instrument directory by sending the following command:</t>
5101                        <t>
5102                            <list>
5103                                <t>SET DB_INSTRUMENT_DIRECTORY NAME &lt;dir&gt; &lt;name&gt;</t>
5104                            </list>
5105                        </t>
5106                        <t>Where &lt;dir&gt; is the absolute path name of the directory and
5107                        &lt;name&gt; is the new name for that directory.</t>
5108    
5109                        <t>Possible Answers:</t>
5110                        <t>
5111                            <list>
5112                                <t>"OK" -
5113                                    <list>
5114                                        <t>on success</t>
5115                                    </list>
5116                                </t>
5117                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
5118                                    <list>
5119                                        <t>in case the given directory does not exists,
5120                                        or if a directory with name equal to the new
5121                                        name already exists.</t>
5122                                    </list>
5123                                </t>
5124                            </list>
5125                        </t>
5126    
5127                        <t>Example:</t>
5128                        <t>
5129                            <list>
5130                                <t>C: "SET DB_INSTRUMENT_DIRECTORY NAME '/Piano Collection/Acustic' 'Acoustic'"</t>
5131                                <t>S: "OK"</t>
5132                            </list>
5133                        </t>
5134                    </section>
5135    
5136                    <section title="Moving an instrument directory" anchor="MOVE DB_INSTRUMENT_DIRECTORY">
5137                        <t>The front-end can move a specific
5138                        instrument directory by sending the following command:</t>
5139                        <t>
5140                            <list>
5141                                <t>MOVE DB_INSTRUMENT_DIRECTORY &lt;dir&gt; &lt;dst&gt;</t>
5142                            </list>
5143                        </t>
5144                        <t>Where &lt;dir&gt; is the absolute path name of the directory
5145                        to move and &lt;dst&gt; is the location where the directory will
5146                        be moved to.</t>
5147    
5148                        <t>Possible Answers:</t>
5149                        <t>
5150                            <list>
5151                                <t>"OK" -
5152                                    <list>
5153                                        <t>on success</t>
5154                                    </list>
5155                                </t>
5156                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
5157                                    <list>
5158                                        <t>in case a given directory does not exists,
5159                                        or if a directory with name equal to the name
5160                                        of the specified directory already exists in
5161                                        the destination directory. Error is also thrown
5162                                        when trying to move a directory to a subdirectory
5163                                        of itself.</t>
5164                                    </list>
5165                                </t>
5166                            </list>
5167                        </t>
5168    
5169                        <t>Example:</t>
5170                        <t>
5171                            <list>
5172                                <t>C: "MOVE DB_INSTRUMENT_DIRECTORY '/Acoustic' '/Piano Collection/Acoustic'"</t>
5173                                <t>S: "OK"</t>
5174                            </list>
5175                        </t>
5176                    </section>
5177    
5178                    <section title="Copying instrument directories" anchor="COPY DB_INSTRUMENT_DIRECTORY">
5179                        <t>The front-end can copy a specific
5180                        instrument directory by sending the following command:</t>
5181                        <t>
5182                            <list>
5183                                <t>COPY DB_INSTRUMENT_DIRECTORY &lt;dir&gt; &lt;dst&gt;</t>
5184                            </list>
5185                        </t>
5186                        <t>Where &lt;dir&gt; is the absolute path name of the directory
5187                        to copy and &lt;dst&gt; is the location where the directory will
5188                        be copied to.</t>
5189    
5190                        <t>Possible Answers:</t>
5191                        <t>
5192                            <list>
5193                                <t>"OK" -
5194                                    <list>
5195                                        <t>on success</t>
5196                                    </list>
5197                                </t>
5198                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
5199                                    <list>
5200                                        <t>in case a given directory does not exists,
5201                                        or if a directory with name equal to the name
5202                                        of the specified directory already exists in
5203                                        the destination directory. Error is also thrown
5204                                        when trying to copy a directory to a subdirectory
5205                                        of itself.</t>
5206                                    </list>
5207                                </t>
5208                            </list>
5209                        </t>
5210    
5211                        <t>Example:</t>
5212                        <t>
5213                            <list>
5214                                <t>C: "COPY DB_INSTRUMENT_DIRECTORY '/Piano Collection/Acoustic' '/Acoustic/Pianos'"</t>
5215                                <t>S: "OK"</t>
5216                            </list>
5217                        </t>
5218                    </section>
5219    
5220                    <section title="Changing the description of directory" anchor="SET DB_INSTRUMENT_DIRECTORY DESCRIPTION">
5221                        <t>The front-end can alter the description of a specific
5222                        instrument directory by sending the following command:</t>
5223                        <t>
5224                            <list>
5225                                <t>SET DB_INSTRUMENT_DIRECTORY DESCRIPTION &lt;dir&gt; &lt;desc&gt;</t>
5226                            </list>
5227                        </t>
5228                        <t>Where &lt;dir&gt; is the absolute path name of the directory and
5229                        &lt;desc&gt; is the new description for the directory
5230                        (encapsulated into apostrophes, supporting escape sequences as described in chapter
5231                        "<xref target="character_set">Character Set and Escape Sequences</xref>").</t>
5232    
5233                        <t>Possible Answers:</t>
5234                        <t>
5235                            <list>
5236                                <t>"OK" -
5237                                    <list>
5238                                        <t>on success</t>
5239                                    </list>
5240                                </t>
5241                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
5242                                    <list>
5243                                        <t>in case the given directory does not exists.</t>
5244                                    </list>
5245                                </t>
5246                            </list>
5247                        </t>
5248    
5249                        <t>Example:</t>
5250                        <t>
5251                            <list>
5252                                <t>C: "SET DB_INSTRUMENT_DIRECTORY DESCRIPTION '/Piano Collection' 'A collection of piano instruments in various format.'"</t>
5253                                <t>S: "OK"</t>
5254                            </list>
5255                        </t>
5256                    </section>
5257    
5258                    <section title="Finding directories" anchor="FIND DB_INSTRUMENT_DIRECTORIES">
5259                        <t>The front-end can search for directories
5260                        in specific directory by sending the following command:</t>
5261                        <t>
5262                            <list>
5263                                <t>FIND DB_INSTRUMENT_DIRECTORIES [NON_RECURSIVE] &lt;dir&gt; &lt;criteria-list&gt;</t>
5264                            </list>
5265                        </t>
5266                        <t>Where &lt;dir&gt; should be replaced by the absolute path
5267                        name of the directory to search in. If NON_RECURSIVE is specified, the
5268                        directories located in subdirectories of the specified directory will not
5269                        be searched. &lt;criteria-list&gt; is a list of search criterias
5270                        in form of "key1=val1 key2=val2 ...". The following criterias are
5271                        allowed:</t>
5272                        <t>
5273                          <t>NAME='&lt;search-string&gt;'
5274                              <list>
5275                                  <t>Restricts the search to directories, which names
5276                                  satisfy the supplied search string (encapsulated into apostrophes,
5277                                  supporting escape sequences as described in chapter
5278                                  "<xref target="character_set">Character Set and Escape Sequences</xref>").</t>
5279                              </list>
5280                          </t>
5281    
5282                          <t>CREATED='[&lt;date-after&gt;]..[&lt;date-before&gt;]'
5283                              <list>
5284                                  <t>Restricts the search to directories, which creation
5285                                  date satisfies the specified period, where &lt;date-after&gt;
5286                                  and &lt;date-before&gt; are in "YYYY-MM-DD HH:MM:SS" format.
5287                                  If &lt;date-after&gt; is omitted the search is restricted to
5288                                  directories created before &lt;date-before&gt;. If
5289                                  &lt;date-before&gt; is omitted, the search is restricted
5290                                  to directories created after &lt;date-after&gt;.</t>
5291                              </list>
5292                          </t>
5293    
5294                          <t>MODIFIED='[&lt;date-after&gt;]..[&lt;date-before&gt;]'
5295                              <list>
5296                                  <t>Restricts the search to directories, which
5297                                  date of last modification satisfies the specified period, where
5298                                  &lt;date-after&gt; and &lt;date-before&gt; are in "YYYY-MM-DD HH:MM:SS"
5299                                  format. If &lt;date-after&gt; is omitted the search is restricted to
5300                                  directories, which are last modified before &lt;date-before&gt;. If
5301                                  &lt;date-before&gt; is omitted, the search is restricted to directories,
5302                                  which are last modified after &lt;date-after&gt;.</t>
5303                              </list>
5304                          </t>
5305    
5306                          <t>DESCRIPTION='&lt;search-string&gt;'
5307                              <list>
5308                                  <t>Restricts the search to directories with description
5309                                  that satisfies the supplied search string
5310                                  (encapsulated into apostrophes, supporting escape
5311                                  sequences as described in chapter
5312                                  "<xref target="character_set">Character Set and Escape Sequences</xref>").</t>
5313                              </list>
5314                          </t>
5315                        </t>
5316    
5317                        <t>Where &lt;search-string&gt; is either a regular expression, or a
5318                        word list separated with spaces for OR search and with '+' for AND search.</t>
5319    
5320                        <t>Possible Answers:</t>
5321                        <t>
5322                            <list>
5323                                <t>A comma separated list with the absolute path names (encapsulated into
5324                                apostrophes) of all directories in the specified directory that satisfy
5325                                the supplied search criterias.</t>
5326                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
5327                                    <list>
5328                                        <t>if the given directory does not exist.</t>
5329                                    </list>
5330                                </t>
5331                            </list>
5332                        </t>
5333                        <t>Example:</t>
5334                        <t>
5335                            <list>
5336                                <t>C: "FIND DB_INSTRUMENT_DIRECTORIES '/' NAME='Piano'"</t>
5337                                <t>S: "'/Piano Collection'"</t>
5338                            </list>
5339                        </t>
5340                        <t>
5341                            <list>
5342                                <t>C: "FIND DB_INSTRUMENT_DIRECTORIES '/' CREATED='..2007-04-01 09:30:13'"</t>
5343                                <t>S: "'/Piano Collection','/Percussions'"</t>
5344                            </list>
5345                        </t>
5346                    </section>
5347    
5348                    <section title="Adding instruments to the instruments database" anchor="ADD DB_INSTRUMENTS">
5349                        <t>The front-end can add one or more instruments
5350                        to the instruments database by sending the following command:</t>
5351                        <t>
5352                            <list>
5353                                <t>ADD DB_INSTRUMENTS [NON_MODAL] [&lt;mode&gt;] &lt;db_dir&gt; &lt;file_path&gt; [&lt;instr_index&gt;]</t>
5354                            </list>
5355                        </t>
5356                        <t>Where &lt;db_dir&gt; is the absolute path name of a directory
5357                        (encapsulated into apostrophes) in the instruments database in which
5358                        only the new instruments (that are not already in the database) will
5359                        be added, &lt;file_path&gt; is the absolute path name of a file or
5360                        directory in the file system (encapsulated into apostrophes). In case
5361                        an instrument file is supplied, only the instruments in the specified
5362                        file will be added to the instruments database. If the optional
5363                        &lt;instr_index&gt; (the index of the instrument within the given file)
5364                        is supplied too, then only the specified instrument will be added.
5365                        In case a directory is supplied, the instruments in that directory
5366                        will be added. The OPTIONAL &lt;mode&gt; argument is only applied
5367                        when a directory is provided as &lt;file_path&gt; and specifies how the
5368                        scanning will be done and has exactly the following possibilities:</t>
5369                        <t>
5370                            <list>
5371                                <t>"RECURSIVE" -
5372                                    <list>
5373                                        <t>All instruments will be processed, including those
5374                                        in the subdirectories, and the respective subdirectory
5375                                        tree structure will be recreated in the instruments
5376                                        database</t>
5377                                    </list>
5378                                </t>
5379                                <t>"NON_RECURSIVE" -
5380                                    <list>
5381                                        <t>Only the instruments in the specified directory
5382                                        will be added, the instruments in the subdirectories
5383                                        will not be processed.</t>
5384                                    </list>
5385                                </t>
5386                                <t>"FLAT" -
5387                                    <list>
5388                                        <t>All instruments will be processed, including those
5389                                        in the subdirectories, but the respective subdirectory
5390                                        structure will not be recreated in the instruments
5391                                        database. All instruments will be added directly in
5392                                        the specified database directory.</t>
5393                                    </list>
5394                                </t>
5395                            </list>
5396                        </t>
5397    
5398                     <t>The difference between regular and NON_MODAL versions of the command
5399                        is that the regular command returns when the scanning is finished
5400                        while NON_MODAL version returns immediately and a background process is launched.
5401                        The <xref target="GET DB_INSTRUMENTS_JOB INFO">GET DB_INSTRUMENTS_JOB INFO</xref>
5402                        command can be used to monitor the scanning progress.</t>
5403    
5404                        <t>Possible Answers:</t>
5405                        <t>
5406                            <list>
5407                                <t>"OK" -
5408                                    <list>
5409                                        <t>on success when NON_MODAL is not supplied</t>
5410                                    </list>
5411                                </t>
5412                                <t>"OK[&lt;job-id&gt;]" -
5413                                    <list>
5414                                        <t>on success when NON_MODAL is supplied, where &lt;job-id&gt;
5415                                        is a numerical ID used to obtain status information about the job progress.
5416                                        See <xref target="GET DB_INSTRUMENTS_JOB INFO">GET DB_INSTRUMENTS_JOB INFO</xref>
5417                                        </t>
5418                                    </list>
5419                                </t>
5420                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
5421                                    <list>
5422                                        <t>if an invalid path is specified.</t>
5423                                    </list>
5424                                </t>
5425                            </list>
5426                        </t>
5427    
5428                        <t>Examples:</t>
5429                        <t>
5430                            <list>
5431                                <t>C: "ADD DB_INSTRUMENTS '/Piano Collection' '/home/me/gigs/PMI Bosendorfer 290.gig' 0"</t>
5432                                <t>S: "OK"</t>
5433                            </list>
5434                        </t>
5435                    </section>
5436    
5437                    <section title="Removing an instrument" anchor="REMOVE DB_INSTRUMENT">
5438                        <t>The front-end can remove a particular instrument
5439                        from the instruments database by sending the following command:</t>
5440                        <t>
5441                            <list>
5442                                <t>REMOVE DB_INSTRUMENT &lt;instr_path&gt;</t>
5443                            </list>
5444                        </t>
5445                        <t>Where &lt;instr_path&gt; is the absolute path name
5446                        (in the instruments database) of the instrument to remove.</t>
5447    
5448                        <t>Possible Answers:</t>
5449                        <t>
5450                            <list>
5451                                <t>"OK" -
5452                                    <list>
5453                                        <t>if the instrument is removed successfully</t>
5454                                    </list>
5455                                </t>
5456                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
5457                                    <list>
5458                                        <t>if the given path does not exist or
5459                                        is a directory.</t>
5460                                    </list>
5461                                </t>
5462                            </list>
5463                        </t>
5464    
5465                        <t>Examples:</t>
5466                        <t>
5467                            <list>
5468                                <t>C: "REMOVE DB_INSTRUMENT '/Piano Collection/Bosendorfer 290'"</t>
5469                                <t>S: "OK"</t>
5470                            </list>
5471                        </t>
5472                    </section>
5473    
5474                    <section title="Getting amount of instruments" anchor="GET DB_INSTRUMENTS">
5475                        <t>The front-end can retrieve the current amount of
5476                        instruments in a specific directory by sending the following command:</t>
5477                        <t>
5478                            <list>
5479                                <t>GET DB_INSTRUMENTS [RECURSIVE] &lt;dir&gt;</t>
5480                            </list>
5481                        </t>
5482                        <t>Where &lt;dir&gt; should be replaced by the absolute path name
5483                        of the directory. If RECURSIVE is specified, the number of all
5484                        instruments, including those located in subdirectories of the
5485                        specified directory, will be returned.</t>
5486    
5487                        <t>Possible Answers:</t>
5488                        <t>
5489                            <list>
5490                                <t>The current number of instruments
5491                                in the specified directory.</t>
5492                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
5493                                    <list>
5494                                        <t>if the given directory does not exist.</t>
5495                                    </list>
5496                                </t>
5497                            </list>
5498                        </t>
5499    
5500                        <t>Example:</t>
5501                        <t>
5502                            <list>
5503                                <t>C: "GET DB_INSTRUMENTS '/Piano Collection'"</t>
5504                                <t>S: "2"</t>
5505                            </list>
5506                        </t>
5507                    </section>
5508    
5509                    <section title="Listing all instruments in specific directory" anchor="LIST DB_INSTRUMENTS">
5510                        <t>The front-end can retrieve the current list of instruments
5511                        in specific directory by sending the following command:</t>
5512                        <t>
5513                            <list>
5514                                <t>LIST DB_INSTRUMENTS [RECURSIVE] &lt;dir&gt;</t>
5515                            </list>
5516                        </t>
5517                        <t>Where &lt;dir&gt; should be replaced by the absolute path
5518                        name of the directory. If RECURSIVE is specified, the absolute path
5519                        names of all instruments, including those located in subdirectories
5520                        of the specified directory, will be returned.</t>
5521    
5522                        <t>Possible Answers:</t>
5523                        <t>
5524                            <list>
5525                                <t>A comma separated list of all instruments
5526                                (encapsulated into apostrophes) in the specified directory.</t>
5527                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
5528                                    <list>
5529                                        <t>if the given directory does not exist.</t>
5530                                    </list>
5531                                </t>
5532                            </list>
5533                        </t>
5534                        <t>Example:</t>
5535                        <t>
5536                            <list>
5537                                <t>C: "LIST DB_INSTRUMENTS '/Piano Collection'"</t>
5538                                <t>S: "'Bosendorfer 290','Steinway D'"</t>
5539                            </list>
5540                        </t>
5541                        <t>
5542                            <list>
5543                                <t>C: "LIST DB_INSTRUMENTS RECURSIVE '/Piano Collection'"</t>
5544                                <t>S: "'/Piano Collection/Bosendorfer 290','/Piano Collection/Steinway D','/Piano Collection/Lite/Free Piano'"</t>
5545                            </list>
5546                        </t>
5547                    </section>
5548    
5549                    <section title="Getting instrument information" anchor="GET DB_INSTRUMENT INFO">
5550                        <t>The front-end can ask for the current settings of an
5551                        instrument by sending the following command:</t>
5552                        <t>
5553                            <list>
5554                                <t>GET DB_INSTRUMENT INFO &lt;instr_path&gt;</t>
5555                            </list>
5556                        </t>
5557                        <t>Where &lt;instr_path&gt; should be replaced by the absolute path
5558                        name of the instrument the front-end is interested in.</t>
5559    
5560                        <t>Possible Answers:</t>
5561                        <t>
5562                            <list>
5563                                <t>LinuxSampler will answer by sending a &lt;CRLF&gt; separated list.
5564                                Each answer line begins with the settings category name
5565                                followed by a colon and then a space character &lt;SP&gt; and finally
5566                                the info character string to that setting category. At the
5567                                moment the following categories are defined:</t>
5568    
5569                                <t>
5570                                    <list>
5571                                        <t>INSTRUMENT_FILE -
5572                                            <list>
5573                                                <t>File name of the instrument.
5574                                                Note that the character string may contain
5575                                                <xref target="character_set">escape sequences</xref>.</t>
5576                                            </list>
5577                                        </t>
5578                                        <t>INSTRUMENT_NR -
5579                                            <list>
5580                                                <t>Index of the instrument within the file.</t>
5581                                            </list>
5582                                        </t>
5583                                        <t>FORMAT_FAMILY -
5584                                            <list>
5585                                                <t>The format family of the instrument.</t>
5586                                            </list>
5587                                        </t>
5588                                        <t>FORMAT_VERSION -
5589                                            <list>
5590                                                <t>The format version of the instrument.</t>
5591                                            </list>
5592                                        </t>
5593                                        <t>SIZE -
5594                                            <list>
5595                                                <t>The size of the instrument in bytes.</t>
5596                                            </list>
5597                                        </t>
5598                                        <t>CREATED -
5599                                            <list>
5600                                                <t>The date and time when the instrument is added
5601                                                in the instruments database, represented in
5602                                               "YYYY-MM-DD HH:MM:SS" format</t>
5603                                            </list>
5604                                        </t>
5605                                        <t>MODIFIED -
5606                                            <list>
5607                                                <t>The date and time of the last modification of the
5608                                                instrument's database settings, represented in
5609                                                "YYYY-MM-DD HH:MM:SS" format</t>
5610                                            </list>
5611                                        </t>
5612                                        <t>DESCRIPTION -
5613                                            <list>
5614                                                <t>A brief description of the instrument.
5615                                                Note that the character string may contain
5616                                                <xref target="character_set">escape sequences</xref>.</t>
5617                                            </list>
5618                                        </t>
5619                                        <t>IS_DRUM -
5620                                            <list>
5621                                                <t>either true or false, determines whether the
5622                                                instrument is a drumkit or a chromatic instrument</t>
5623                                            </list>
5624                                        </t>
5625                                        <t>PRODUCT -
5626                                            <list>
5627                                                <t>The product title of the instrument.
5628                                                Note that the character string may contain
5629                                                <xref target="character_set">escape sequences</xref>.</t>
5630                                            </list>
5631                                        </t>
5632                                        <t>ARTISTS -
5633                                            <list>
5634                                                <t>Lists the artist names.
5635                                                Note that the character string may contain
5636                                                <xref target="character_set">escape sequences</xref>.</t>
5637                                            </list>
5638                                        </t>
5639                                        <t>KEYWORDS -
5640                                            <list>
5641                                                <t>Provides a list of keywords that refer to the instrument.
5642                                                Keywords are separated with semicolon and blank.
5643                                                Note that the character string may contain
5644                                                <xref target="character_set">escape sequences</xref>.</t>
5645                                            </list>
5646                                        </t>
5647                                    </list>
5648                                </t>
5649                            </list>
5650                        </t>
5651                        <t>The mentioned fields above don't have to be in particular order.</t>
5652    
5653                        <t>Example:</t>
5654                        <t>
5655                            <list>
5656                                <t>C: "GET DB_INSTRUMENT INFO '/Piano Collection/Bosendorfer 290'"</t>
5657                                <t>S: "INSTRUMENT_FILE: /home/me/gigs/Bosendorfer 290.gig"</t>
5658                                <t>&nbsp;&nbsp;&nbsp;"INSTRUMENT_NR: 0"</t>
5659                                <t>&nbsp;&nbsp;&nbsp;"FORMAT_FAMILY: GIG"</t>
5660                                <t>&nbsp;&nbsp;&nbsp;"FORMAT_VERSION: 2"</t>
5661                                <t>&nbsp;&nbsp;&nbsp;"SIZE: 2050871870"</t>
5662                                <t>&nbsp;&nbsp;&nbsp;"CREATED: 2007-02-05 10:23:12"</t>
5663                                <t>&nbsp;&nbsp;&nbsp;"MODIFIED: 2007-04-07 12:50:21"</t>
5664                                <t>&nbsp;&nbsp;&nbsp;"DESCRIPTION: "</t>
5665                                <t>&nbsp;&nbsp;&nbsp;"IS_DRUM: false"</t>
5666                                <t>&nbsp;&nbsp;&nbsp;"PRODUCT: GRANDIOSO Bosendorfer 290"</t>
5667                                <t>&nbsp;&nbsp;&nbsp;"ARTISTS: Post Musical Instruments"</t>
5668                                <t>&nbsp;&nbsp;&nbsp;"KEYWORDS: Bosendorfer"</t>
5669                                <t>&nbsp;&nbsp;&nbsp;"."</t>
5670                            </list>
5671                        </t>
5672                    </section>
5673    
5674                    <section title="Renaming an instrument" anchor="SET DB_INSTRUMENT NAME">
5675                        <t>The front-end can alter the name of a specific
5676                        instrument by sending the following command:</t>
5677                        <t>
5678                            <list>
5679                                <t>SET DB_INSTRUMENT NAME &lt;instr&gt; &lt;name&gt;</t>
5680                            </list>
5681                        </t>
5682                        <t>Where &lt;instr&gt; is the absolute path name of the instrument and
5683                        &lt;name&gt; is the new name for that instrument.</t>
5684    
5685                        <t>Possible Answers:</t>
5686                        <t>
5687                            <list>
5688                                <t>"OK" -
5689                                    <list>
5690                                        <t>on success</t>
5691                                    </list>
5692                                </t>
5693                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
5694                                    <list>
5695                                        <t>in case the given instrument does not exists,
5696                                        or if an instrument with name equal to the new
5697                                        name already exists.</t>
5698                                    </list>
5699                                </t>
5700                            </list>
5701                        </t>
5702    
5703                        <t>Example:</t>
5704                        <t>
5705                            <list>
5706                                <t>C: "SET DB_INSTRUMENT NAME '/Piano Collection/Bosendorfer' 'Bosendorfer 290'"</t>
5707                                <t>S: "OK"</t>
5708                            </list>
5709                        </t>
5710                    </section>
5711    
5712                    <section title="Moving an instrument" anchor="MOVE DB_INSTRUMENT">
5713                        <t>The front-end can move a specific instrument to another directory by
5714                        sending the following command:</t>
5715                        <t>
5716                            <list>
5717                                <t>MOVE DB_INSTRUMENT &lt;instr&gt; &lt;dst&gt;</t>
5718                            </list>
5719                        </t>
5720                        <t>Where &lt;instr&gt; is the absolute path name of the instrument
5721                        to move and &lt;dst&gt; is the directory where the instrument will
5722                        be moved to.</t>
5723    
5724                        <t>Possible Answers:</t>
5725                        <t>
5726                            <list>
5727                                <t>"OK" -
5728                                    <list>
5729                                        <t>on success</t>
5730                                    </list>
5731                                </t>
5732                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
5733                                    <list>
5734                                        <t>in case the given instrument does not exists,
5735                                        or if an instrument with name equal to the name of the
5736                                        specified instrument already exists in the destination
5737                                        directory.</t>
5738                                    </list>
5739                                </t>
5740                            </list>
5741                        </t>
5742    
5743                        <t>Example:</t>
5744                        <t>
5745                            <list>
5746                                <t>C: "MOVE DB_INSTRUMENT '/Piano Collection/Bosendorfer 290' '/Piano Collection/Acoustic'"</t>
5747                                <t>S: "OK"</t>
5748                            </list>
5749                        </t>
5750                    </section>
5751    
5752                    <section title="Copying instruments" anchor="COPY DB_INSTRUMENT">
5753                        <t>The front-end can copy a specific instrument to another directory by
5754                        sending the following command:</t>
5755                        <t>
5756                            <list>
5757                                <t>COPY DB_INSTRUMENT &lt;instr&gt; &lt;dst&gt;</t>
5758                            </list>
5759                        </t>
5760                        <t>Where &lt;instr&gt; is the absolute path name of the instrument
5761                        to copy and &lt;dst&gt; is the directory where the instrument will
5762                        be copied to.</t>
5763    
5764                        <t>Possible Answers:</t>
5765                        <t>
5766                            <list>
5767                                <t>"OK" -
5768                                    <list>
5769                                        <t>on success</t>
5770                                    </list>
5771                                </t>
5772                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
5773                                    <list>
5774                                        <t>in case the given instrument does not exists,
5775                                        or if an instrument with name equal to the name of the
5776                                        specified instrument already exists in the destination
5777                                        directory.</t>
5778                                    </list>
5779                                </t>
5780                            </list>
5781                        </t>
5782    
5783                        <t>Example:</t>
5784                        <t>
5785                            <list>
5786                                <t>C: "COPY DB_INSTRUMENT '/Piano Collection/Bosendorfer 290' '/Acoustic/Pianos/'"</t>
5787                                <t>S: "OK"</t>
5788                            </list>
5789                        </t>
5790                    </section>
5791    
5792                    <section title="Changing the description of instrument" anchor="SET DB_INSTRUMENT DESCRIPTION">
5793                        <t>The front-end can alter the description of a specific
5794                        instrument by sending the following command:</t>
5795                        <t>
5796                            <list>
5797                                <t>SET DB_INSTRUMENT DESCRIPTION &lt;instr&gt; &lt;desc&gt;</t>
5798                            </list>
5799                        </t>
5800                        <t>Where &lt;instr&gt; is the absolute path name of the instrument and
5801                        &lt;desc&gt; is the new description for the instrument
5802                        (encapsulated into apostrophes, supporting escape sequences as described in chapter
5803                        "<xref target="character_set">Character Set and Escape Sequences</xref>").</t>
5804    
5805                        <t>Possible Answers:</t>
5806                        <t>
5807                            <list>
5808                                <t>"OK" -
5809                                    <list>
5810                                        <t>on success</t>
5811                                    </list>
5812                                </t>
5813                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
5814                                    <list>
5815                                        <t>in case the given instrument does not exists.</t>
5816                                    </list>
5817                                </t>
5818                            </list>
5819                        </t>
5820    
5821                        <t>Example:</t>
5822                        <t>
5823                            <list>
5824                                <t>C: "SET DB_INSTRUMENT DESCRIPTION '/Piano Collection/Acoustic/Bosendorfer 290' 'No comment :)'"</t>
5825                                <t>S: "OK"</t>
5826                            </list>
5827                        </t>
5828                    </section>
5829    
5830                    <section title="Finding instruments" anchor="FIND DB_INSTRUMENTS">
5831                        <t>The front-end can search for instruments
5832                        in specific directory by sending the following command:</t>
5833                        <t>
5834                            <list>
5835                                <t>FIND DB_INSTRUMENTS [NON_RECURSIVE] &lt;dir&gt; &lt;criteria-list&gt;</t>
5836                            </list>
5837                        </t>
5838                        <t>Where &lt;dir&gt; should be replaced by the absolute path
5839                        name of the directory to search in. If NON_RECURSIVE is specified, the
5840                        directories located in subdirectories of the specified directory will not
5841                        be searched. &lt;criteria-list&gt; is a list of search criterias
5842                        in form of "key1=val1 key2=val2 ...". The following criterias are
5843                        allowed:</t>
5844                        <t>
5845                          <t>NAME='&lt;search-string&gt;'
5846                              <list>
5847                                  <t>Restricts the search to instruments, which names
5848                                  satisfy the supplied search string (encapsulated into apostrophes,
5849                                  supporting escape sequences as described in chapter
5850                                  "<xref target="character_set">Character Set and Escape Sequences</xref>").</t>
5851                              </list>
5852                          </t>
5853    
5854                          <t>SIZE=[&lt;min&gt;]..[&lt;max&gt;]
5855                              <list>
5856                                  <t>Restricts the search to instruments, which
5857                                  size is in the specified range. If &lt;min&gt; is omitted,
5858                                  the search results are restricted to instruments with size less then
5859                                  or equal to &lt;max&gt;. If &lt;max&gt; is omitted, the
5860                                  search is restricted to instruments with size greater then
5861                                  or equal to &lt;min&gt;.</t>
5862                              </list>
5863                          </t>
5864    
5865                          <t>CREATED='[&lt;date-after&gt;]..[&lt;date-before&gt;]'
5866                              <list>
5867                                  <t>Restricts the search to instruments, which creation
5868                                  date satisfies the specified period, where &lt;date-after&gt;
5869                                  and &lt;date-before&gt; are in "YYYY-MM-DD HH:MM:SS" format.
5870                                  If &lt;date-after&gt; is omitted the search is restricted to
5871                                  instruments created before &lt;date-before&gt;. If
5872                                  &lt;date-before&gt; is omitted, the search is restricted
5873                                  to instruments created after &lt;date-after&gt;.</t>
5874                              </list>
5875                          </t>
5876    
5877                          <t>MODIFIED='[&lt;date-after&gt;]..[&lt;date-before&gt;]'
5878                              <list>
5879                                  <t>Restricts the search to instruments, which
5880                                  date of last modification satisfies the specified period, where
5881                                  &lt;date-after&gt; and &lt;date-before&gt; are in "YYYY-MM-DD HH:MM:SS"
5882                                  format. If &lt;date-after&gt; is omitted the search is restricted to
5883                                  instruments, which are last modified before &lt;date-before&gt;. If
5884                                  &lt;date-before&gt; is omitted, the search is restricted to instruments,
5885                                  which are last modified after &lt;date-after&gt;.</t>
5886                              </list>
5887                          </t>
5888    
5889                          <t>DESCRIPTION='&lt;search-string&gt;'
5890                              <list>
5891                                  <t>Restricts the search to instruments with description
5892                                  that satisfies the supplied search string (encapsulated into apostrophes,
5893                                  supporting escape sequences as described in chapter
5894                                  "<xref target="character_set">Character Set and Escape Sequences</xref>").</t>
5895                              </list>
5896                          </t>
5897    
5898                          <t>PRODUCT='&lt;search-string&gt;'
5899                              <list>
5900                                  <t>Restricts the search to instruments with product info
5901                                  that satisfies the supplied search string (encapsulated into apostrophes,
5902                                  supporting escape sequences as described in chapter
5903                                  "<xref target="character_set">Character Set and Escape Sequences</xref>").</t>
5904                              </list>
5905                          </t>
5906    
5907                          <t>ARTISTS='&lt;search-string&gt;'
5908                              <list>
5909                                  <t>Restricts the search to instruments with artists info
5910                                  that satisfies the supplied search string (encapsulated into apostrophes,
5911                                  supporting escape sequences as described in chapter
5912                                  "<xref target="character_set">Character Set and Escape Sequences</xref>").</t>
5913                              </list>
5914                          </t>
5915    
5916                          <t>KEYWORDS='&lt;search-string&gt;'
5917                              <list>
5918                                  <t>Restricts the search to instruments with keyword list
5919                                  that satisfies the supplied search string (encapsulated into apostrophes,
5920                                  supporting escape sequences as described in chapter
5921                                  "<xref target="character_set">Character Set and Escape Sequences</xref>").</t>
5922                              </list>
5923                          </t>
5924    
5925                          <t>IS_DRUM=true | false
5926                              <list>
5927                                  <t>Either true or false. Restricts the search to
5928                                  drum kits or chromatic instruments.</t>
5929                              </list>
5930                          </t>
5931    
5932                          <t>FORMAT_FAMILIES='&lt;format-list&gt;'
5933                              <list>
5934                                  <t>Restricts the search to instruments of the supplied format families,
5935                                  where &lt;format-list&gt; is a comma separated list of format families.</t>
5936                              </list>
5937                          </t>
5938                        </t>
5939    
5940                        <t>Where &lt;search-string&gt; is either a regular expression, or a
5941                        word list separated with spaces for OR search and with '+' for AND search.</t>
5942    
5943                        <t>Possible Answers:</t>
5944                        <t>
5945                            <list>
5946                                <t>A comma separated list with the absolute path names (encapsulated into
5947                                apostrophes) of all instruments in the specified directory that satisfy
5948                                the supplied search criterias.</t>
5949                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
5950                                    <list>
5951                                        <t>if the given directory does not exist.</t>
5952                                    </list>
5953                                </t>
5954                            </list>
5955                        </t>
5956                        <t>Example:</t>
5957                        <t>
5958                            <list>
5959                                <t>C: "FIND DB_INSTRUMENTS '/Piano Collection' NAME='bosendorfer+290'"</t>
5960                                <t>S: "'/Piano Collection/Bosendorfer 290'"</t>
5961                            </list>
5962                        </t>
5963                        <t>
5964                            <list>
5965                                <t>C: "FIND DB_INSTRUMENTS '/Piano Collection' CREATED='2007-04-01 09:30:13..'"</t>
5966                                <t>S: "'/Piano Collection/Bosendorfer 290','/Piano Collection/Steinway D'"</t>
5967                            </list>
5968                        </t>
5969                    </section>
5970    
5971                    <section title="Getting job status information" anchor="GET DB_INSTRUMENTS_JOB INFO">
5972                        <t>The front-end can ask for the current status of a
5973                        particular database instruments job by sending the following command:</t>
5974                        <t>
5975                            <list>
5976                                <t>GET DB_INSTRUMENTS_JOB INFO &lt;job-id&gt;</t>
5977                            </list>
5978                        </t>
5979                        <t>Where &lt;job-id&gt; should be replaced by the numerical ID
5980                        of the job the front-end is interested in.</t>
5981    
5982                        <t>Possible Answers:</t>
5983                        <t>
5984                            <list>
5985                                <t>LinuxSampler will answer by sending a &lt;CRLF&gt; separated list.
5986                                Each answer line begins with the settings category name
5987                                followed by a colon and then a space character &lt;SP&gt; and finally
5988                                the info character string to that setting category. At the
5989                                moment the following categories are defined:</t>
5990    
5991                                <t>
5992                                    <list>
5993                                        <t>FILES_TOTAL -
5994                                            <list>
5995                                                <t>The total number of files scheduled for scanning</t>
5996                                            </list>
5997                                        </t>
5998                                        <t>FILES_SCANNED -
5999                                            <list>
6000                                                <t>The current number of scanned files</t>
6001                                            </list>
6002                                        </t>
6003                                        <t>SCANNING -
6004                                            <list>
6005                                                <t>The absolute path name of the file which is currently
6006                                                being scanned</t>
6007                                            </list>
6008                                        </t>
6009                                        <t>STATUS -
6010                                            <list>
6011                                                <t>An integer value between 0 and 100 indicating the
6012                                                scanning progress percentage of the file which is
6013                                                currently being scanned</t>
6014                                            </list>
6015                                        </t>
6016                                    </list>
6017                                </t>
6018                            </list>
6019                        </t>
6020                        <t>The mentioned fields above don't have to be in particular order.</t>
6021    
6022                        <t>Example:</t>
6023                        <t>
6024                            <list>
6025                                <t>C: "GET DB_INSTRUMENTS_JOB INFO 2"</t>
6026                                <t>S: "FILES_TOTAL: 12"</t>
6027                                <t>&nbsp;&nbsp;&nbsp;"FILES_SCANNED: 7"</t>
6028                                <t>&nbsp;&nbsp;&nbsp;"SCANNING: /home/me/gigs/Bosendorfer 290.gig"</t>
6029                                <t>&nbsp;&nbsp;&nbsp;"STATUS: 42"</t>
6030                                <t>&nbsp;&nbsp;&nbsp;"."</t>
6031                            </list>
6032                        </t>
6033                    </section>
6034    
6035                    <section title="Formatting the instruments database" anchor="FORMAT INSTRUMENTS_DB">
6036                        <t>The front-end can remove all instruments and directories and re-create
6037                        the instruments database structure (e.g., in case of a database corruption)
6038                        by sending the following command:</t>
6039                        <t>
6040                            <list>
6041                                <t>FORMAT INSTRUMENTS_DB</t>
6042                            </list>
6043                        </t>
6044    
6045                        <t>Possible Answers:</t>
6046                        <t>
6047                            <list>
6048                                <t>"OK" -
6049                                    <list>
6050                                        <t>on success</t>
6051                                    </list>
6052                                </t>
6053                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
6054                                    <list>
6055                                        <t>If the formatting of the instruments database
6056                                        failed.</t>
6057                                    </list>
6058                                </t>
6059                            </list>
6060                        </t>
6061                    </section>
6062    
6063                    <section title="Checking for lost instrument files" anchor="FIND LOST DB_INSTRUMENT_FILES">
6064                        <t>The front-end can retrieve the list of all instrument files in the instruments database
6065                        that don't exist in the filesystem by sending the following command:</t>
6066                        <t>
6067                            <list>
6068                                <t>FIND LOST DB_INSTRUMENT_FILES</t>
6069                            </list>
6070                        </t>
6071    
6072                        <t>Possible Answers:</t>
6073                        <t>
6074                            <list>
6075                                <t>A comma separated list with the absolute path names
6076                                (encapsulated into apostrophes) of all lost instrument files.</t>
6077                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
6078                                    <list>
6079                                        <t>in case it failed, providing an appropriate error code and error message.</t>
6080                                    </list>
6081                                </t>
6082                            </list>
6083                        </t>
6084                        <t>Example:</t>
6085                        <t>
6086                            <list>
6087                                <t>C: "FIND LOST DB_INSTRUMENT_FILES"</t>
6088                                <t>S: "'/gigs/Bosendorfer 290.gig','/gigs/Steinway D.gig','/gigs/Free Piano.gig'"</t>
6089                            </list>
6090                        </t>
6091                    </section>
6092    
6093                    <section title="Replacing an instrument file" anchor="SET DB_INSTRUMENT FILE_PATH">
6094                        <t>The front-end can substitute all occurrences of an instrument file
6095                        in the instruments database with a new one by sending the following command:</t>
6096                        <t>
6097                            <list>
6098                                <t>SET DB_INSTRUMENT FILE_PATH &lt;old_path&gt; &lt;new_path&gt;</t>
6099                            </list>
6100                        </t>
6101                        <t>Where &lt;old_path&gt; is the absolute path name of the instrument file
6102                        to substitute with &lt;new_path&gt;.</t>
6103    
6104                        <t>Possible Answers:</t>
6105                        <t>
6106                            <list>
6107                                <t>"OK" -
6108                                    <list>
6109                                        <t>on success</t>
6110                                    </list>
6111                                </t>
6112                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
6113                                    <list>
6114                                        <t>in case it failed, providing an appropriate error code and error message.</t>
6115                                    </list>
6116                                </t>
6117                            </list>
6118                        </t>
6119    
6120                        <t>Example:</t>
6121                        <t>
6122                            <list>
6123                                <t>C: "SET DB_INSTRUMENT FILE_PATH '/gigs/Bosendorfer 290.gig' '/gigs/pianos/Bosendorfer 290.gig'"</t>
6124                                <t>S: "OK"</t>
6125                            </list>
6126                        </t>
6127                    </section>
6128    
6129                </section>
6130    
6131    
6132    
6133                <section title="Editing Instruments" anchor="editing_instruments">
6134                    <t>The sampler allows to edit instruments while playing with the
6135                    sampler by spawning an external (3rd party) instrument editor
6136                    application for a given instrument. The 3rd party instrument
6137                    editor applications have to place a respective plugin DLL file
6138                    into the sampler's plugins directory. The sampler will
6139                    automatically try to load all plugin DLLs in that directory on
6140                    startup and only on startup!</t>
6141                    <t>At the moment there is only one command for this feature set,
6142                    but this will most probably change in future.</t>
6143    
6144                    <section title="Opening an appropriate instrument editor application" anchor="EDIT INSTRUMENT">
6145                        <t>The front-end can request to open an appropriate instrument
6146                        editor application by sending the following command:</t>
6147                        <t>
6148                            <list>
6149                                <t>EDIT CHANNEL INSTRUMENT &lt;sampler-channel&gt;</t>
6150                            </list>
6151                        </t>
6152                        <t>Where &lt;sampler-channel&gt; should be replaced by the
6153                        number of the sampler channel as given by the
6154                        <xref target="ADD CHANNEL">"ADD CHANNEL"</xref>
6155                        or <xref target="LIST CHANNELS">"LIST CHANNELS"</xref>
6156                        command.</t>
6157    
6158                        <t>The sampler will try to ask all registered instrument
6159                        editors (or to be more specific: their sampler plugins)
6160                        whether they are capable to handle the instrument on the
6161                        given sampler channel. The sampler will simply use the first
6162                        instrument editor application which replied with a positive
6163                        answer and spawn that instrument editor application within
6164                        the sampler's process and provide that application access
6165                        to the instrument's data structures, so both applications
6166                        can share and access the same instruments data at the same
6167                        time, thus allowing to immediately hear changes with the
6168                        sampler made by the instrument editor.</t>
6169    
6170                        <t>Note: consequently instrument editors are always spawned
6171                        locally on the same machine where the sampler is running
6172                        on!</t>
6173    
6174                        <t>Possible Answers:</t>
6175                        <t>
6176                            <list>
6177                                <t>"OK" -
6178                                    <list>
6179                                        <t>when an appropriate instrument editor was
6180                                        launched</t>
6181                                    </list>
6182                                </t>
6183                                <t>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
6184                                    <list>
6185                                        <t>when an appropriate instrument editor was
6186                                        launched, but there are noteworthy issues</t>
6187                                    </list>
6188                                </t>
6189                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
6190                                    <list>
6191                                        <t>when an appropriate instrument editor
6192                                        could not be launched</t>
6193                                    </list>
6194                                </t>
6195                            </list>
6196                        </t>
6197    
6198                        <t>Examples:</t>
6199                        <t>
6200                            <list>
6201                                <t>C: "EDIT CHANNEL INSTRUMENT 0"</t>
6202                                <t>S: "OK"</t>
6203                            </list>
6204                        </t>
6205                    </section>
6206                </section>
6207    
6208                <section title="Managing Files" anchor="file_management">
6209                    <t>You can query detailed informations about files located
6210                    at the same system where the sampler instance is running on.
6211                    Using this command set allows to retrieve file informations
6212                    even remotely from another machine.</t>
6213    
6214                    <section title="Retrieving amount of instruments of a file" anchor="GET FILE INSTRUMENTS">
6215                        <t>The front-end can retrieve the amount of instruments
6216                        within a given instrument file by sending the
6217                        following command:</t>
6218                        <t>
6219                            <list>
6220                                <t>GET FILE INSTRUMENTS &lt;filename&gt;</t>
6221                            </list>
6222                        </t>
6223                        <t>Where &lt;filename&gt; is the name of the instrument
6224                        file (encapsulated into apostrophes, supporting escape
6225                        sequences as described in chapter
6226                        "<xref target="character_set">Character Set and Escape
6227                            Sequences</xref>").</t>
6228    
6229                        <t>The sampler will try to ask all sampler engines,
6230                        whether they support the given file and ask the first
6231                        engine with a positive answer for the amount of
6232                        instruments.</t>
6233    
6234                        <t>Possible Answers:</t>
6235                        <t>
6236                            <list>
6237                                <t>On success, the sampler will answer by
6238                                   returning the amount of instruments.
6239                                </t>
6240                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
6241                                    <list>
6242                                        <t>if the file could not be handled</t>
6243                                    </list>
6244                                </t>
6245                            </list>
6246                        </t>
6247    
6248                        <t>Examples:</t>
6249                        <t>
6250                            <list>
6251                                <t>C: "GET FILE INSTRUMENTS 'D:/Sounds/Foo.gig'"</t>
6252                                <t>S: "10"</t>
6253                            </list>
6254                        </t>
6255                    </section>
6256    
6257                    <section title="Retrieving all instruments of a file" anchor="LIST FILE INSTRUMENTS">
6258                        <t>The front-end can retrieve a list of all instruments
6259                        within a given instrument file by sending the
6260                        following command:</t>
6261                        <t>
6262                            <list>
6263                                <t>LIST FILE INSTRUMENTS &lt;filename&gt;</t>
6264                            </list>
6265                        </t>
6266                        <t>Where &lt;filename&gt; is the name of the instrument
6267                        file (encapsulated into apostrophes, supporting escape
6268                        sequences as described in chapter
6269                        "<xref target="character_set">Character Set and Escape
6270                            Sequences</xref>").</t>
6271    
6272                        <t>The sampler will try to ask all sampler engines,
6273                        whether they support the given file and ask the first
6274                        engine with a positive answer for a list of IDs for the
6275                        instruments in the given file.</t>
6276    
6277                        <t>Possible Answers:</t>
6278                        <t>
6279                            <list>
6280                                <t>On success, the sampler will answer by
6281                                   returning a comma separated list of
6282                                   instrument IDs.
6283                                </t>
6284                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
6285                                    <list>
6286                                        <t>if the file could not be handled</t>
6287                                    </list>
6288                                </t>
6289                            </list>
6290                        </t>
6291    
6292                        <t>Examples:</t>
6293                        <t>
6294                            <list>
6295                                <t>C: "LIST FILE INSTRUMENTS 'D:/Sounds/Foo.gig'"</t>
6296                                <t>S: "0,1,2,3,4,5,6,7,8,9"</t>
6297                            </list>
6298                        </t>
6299                    </section>
6300    
6301                    <section title="Retrieving informations about one instrument in a file" anchor="GET FILE INSTRUMENT INFO">
6302                        <t>The front-end can retrieve detailed informations
6303                        about a specific instrument within a given instrument
6304                        file by sending the following command:</t>
6305                        <t>
6306                            <list>
6307                                <t>GET FILE INSTRUMENT INFO &lt;filename&gt;
6308                                &lt;instr-id&gt;</t>
6309                            </list>
6310                        </t>
6311                        <t>Where &lt;filename&gt; is the name of the instrument
6312                        file (encapsulated into apostrophes, supporting escape
6313                        sequences as described in chapter
6314                        "<xref target="character_set">Character Set and Escape
6315                            Sequences</xref>") and &lt;instr-id&gt; is the numeric
6316                        instrument ID as returned by the
6317                        <xref target="LIST FILE INSTRUMENTS">
6318                        "LIST FILE INSTRUMENTS"</xref> command.</t>
6319    
6320                        <t>The sampler will try to ask all sampler engines,
6321                        whether they support the given file and ask the first
6322                        engine with a positive answer for informations about the
6323                        specific instrument in the given file.</t>
6324    
6325                        <t>Possible Answers:</t>
6326                        <t>
6327                            <list>
6328                                <t>LinuxSampler will answer by sending a &lt;CRLF&gt; separated list.
6329                                Each answer line begins with the settings category name
6330                                followed by a colon and then a space character &lt;SP&gt; and finally
6331                                the info character string to that setting category. At the
6332                                moment the following categories are defined:</t>
6333    
6334                                <t>
6335                                    <list>
6336                                        <t>NAME -
6337                                            <list>
6338                                                <t>name of the instrument as
6339                                                stored in the instrument file</t>
6340                                            </list>
6341                                        </t>
6342                                        <t>FORMAT_FAMILY -
6343                                            <list>
6344                                                <t>name of the sampler format
6345                                                of the given instrument</t>
6346                                            </list>
6347                                        </t>
6348                                        <t>FORMAT_VERSION -
6349                                            <list>
6350                                                <t>version of the sampler format
6351                                                the instrumen is stored as</t>
6352                                            </list>
6353                                        </t>
6354                                        <t>PRODUCT -
6355                                            <list>
6356                                                <t>official product name of the
6357                                                instrument as stored in the file
6358                                                </t>
6359                                            </list>
6360                                        </t>
6361                                        <t>ARTISTS -
6362                                            <list>
6363                                                <t>artists / sample library
6364                                                vendor of the instrument</t>
6365                                            </list>
6366                                        </t>
6367                                        <t>KEY_BINDINGS -
6368                                            <list>
6369                                                <t>comma separated list of integer values representing
6370                                                   the instrument's key mapping in the range between 0 .. 127,
6371                                                   reflecting the analog meaning of the MIDI specification.</t>
6372                                            </list>
6373                                        </t>
6374                                        <t>KEYSWITCH_BINDINGS -
6375                                            <list>
6376                                                <t>comma separated list of integer values representing
6377                                                   the instrument's keyswitch mapping in the range between 0 .. 127,
6378                                                   reflecting the analog meaning of the MIDI specification.</t>
6379                                            </list>
6380                                        </t>
6381                                    </list>
6382                                </t>
6383                            </list>
6384                        </t>
6385                        <t>The mentioned fields above don't have to be in particular order.</t>
6386    
6387                        <t>Example:</t>
6388                        <t>
6389                            <list>
6390                                <t>C: "GET FILE INSTRUMENT INFO 'D:/Sounds/Foo.gig' 0"</t>
6391                                <t>S: "NAME: Lunatic Loops"</t>
6392                                <t>&nbsp;&nbsp;&nbsp;"FORMAT_FAMILY: GIG"</t>
6393                                <t>&nbsp;&nbsp;&nbsp;"FORMAT_VERSION: 3"</t>
6394                                <t>&nbsp;&nbsp;&nbsp;"PRODUCT: The Backbone Bongo Beats"</t>
6395                                <t>&nbsp;&nbsp;&nbsp;"ARTISTS: Jimmy the Fish"</t>
6396                                <t>&nbsp;&nbsp;&nbsp;"."</t>
6397                            </list>
6398                        </t>
6399                    </section>
6400                </section>
6401            </section>
6402    
6403          <section title="Command Syntax" anchor="command_syntax">          <section title="Command Syntax" anchor="command_syntax">
6404              <t>The grammar of the control protocol as descibed in <xref target="control_commands"/>              <t>The grammar of the control protocol as descibed in <xref target="control_commands"/>
# Line 4287  Schoenebeck'> Line 6472  Schoenebeck'>
6472                  </t>                  </t>
6473                  <t>/ UNSUBSCRIBE SP unsubscribe_event                  <t>/ UNSUBSCRIBE SP unsubscribe_event
6474                  </t>                  </t>
                 <t>/ SELECT SP text  
                 </t>  
6475                  <t>/ RESET SP reset_instruction                  <t>/ RESET SP reset_instruction
6476                  </t>                  </t>
6477                  <t>/ CLEAR SP clear_instruction                  <t>/ CLEAR SP clear_instruction
6478                  </t>                  </t>
6479                    <t>/ FIND SP find_instruction
6480                    </t>
6481                    <t>/ MOVE SP move_instruction
6482                    </t>
6483                    <t>/ COPY SP copy_instruction
6484                    </t>
6485                    <t>/ EDIT SP edit_instruction
6486                    </t>
6487                    <t>/ FORMAT SP format_instruction
6488                    </t>
6489                    <t>SEND SP send_instruction
6490                    </t>
6491                  <t>/ RESET                  <t>/ RESET
6492                  </t>                  </t>
6493                  <t>/ QUIT                  <t>/ QUIT
# Line 4303  Schoenebeck'> Line 6498  Schoenebeck'>
6498          <list>          <list>
6499                  <t>CHANNEL                  <t>CHANNEL
6500                  </t>                  </t>
6501                    <t>/ DB_INSTRUMENT_DIRECTORY SP db_path
6502                    </t>
6503                    <t>/ DB_INSTRUMENTS SP NON_MODAL SP scan_mode SP db_path SP filename
6504                    </t>
6505                    <t>/ DB_INSTRUMENTS SP scan_mode SP db_path SP filename
6506                    </t>
6507                    <t>/ DB_INSTRUMENTS SP NON_MODAL SP db_path SP filename
6508                    </t>
6509                    <t>/ DB_INSTRUMENTS SP NON_MODAL SP db_path SP filename SP instrument_index
6510                    </t>
6511                    <t>/ DB_INSTRUMENTS SP db_path SP filename
6512                    </t>
6513                    <t>/ DB_INSTRUMENTS SP db_path SP filename SP instrument_index
6514                    </t>
6515                  <t>/ MIDI_INSTRUMENT_MAP                  <t>/ MIDI_INSTRUMENT_MAP
6516                  </t>                  </t>
6517                  <t>/ MIDI_INSTRUMENT_MAP SP map_name                  <t>/ MIDI_INSTRUMENT_MAP SP map_name
# Line 4311  Schoenebeck'> Line 6520  Schoenebeck'>
6520  </t>  </t>
6521  <t>subscribe_event =  <t>subscribe_event =
6522          <list>          <list>
6523                  <t>CHANNEL_COUNT                  <t>AUDIO_OUTPUT_DEVICE_COUNT
6524                    </t>
6525                    <t>/ AUDIO_OUTPUT_DEVICE_INFO
6526                    </t>
6527                    <t>/ MIDI_INPUT_DEVICE_COUNT
6528                    </t>
6529                    <t>/ MIDI_INPUT_DEVICE_INFO
6530                    </t>
6531                    <t>/ CHANNEL_COUNT
6532                    </t>
6533                    <t>/ CHANNEL_MIDI
6534                    </t>
6535                    <t>/ DEVICE_MIDI
6536                  </t>                  </t>
6537                  <t>/ VOICE_COUNT                  <t>/ VOICE_COUNT
6538                  </t>                  </t>
# Line 4321  Schoenebeck'> Line 6542  Schoenebeck'>
6542                  </t>                  </t>
6543                  <t>/ CHANNEL_INFO                  <t>/ CHANNEL_INFO
6544                  </t>                  </t>
6545                    <t>/ FX_SEND_COUNT
6546                    </t>
6547                    <t>/ FX_SEND_INFO
6548                    </t>
6549                    <t>/ MIDI_INSTRUMENT_MAP_COUNT
6550                    </t>
6551                    <t>/ MIDI_INSTRUMENT_MAP_INFO
6552                    </t>
6553                    <t>/ MIDI_INSTRUMENT_COUNT
6554                    </t>
6555                    <t>/ MIDI_INSTRUMENT_INFO
6556                    </t>
6557                    <t>/ DB_INSTRUMENT_DIRECTORY_COUNT
6558                    </t>
6559                    <t>/ DB_INSTRUMENT_DIRECTORY_INFO
6560                    </t>
6561                    <t>/ DB_INSTRUMENT_COUNT
6562                    </t>
6563                    <t>/ DB_INSTRUMENT_INFO
6564                    </t>
6565                    <t>/ DB_INSTRUMENTS_JOB_INFO
6566                    </t>
6567                  <t>/ MISCELLANEOUS                  <t>/ MISCELLANEOUS
6568                  </t>                  </t>
6569                    <t>/ TOTAL_STREAM_COUNT
6570                    </t>
6571                  <t>/ TOTAL_VOICE_COUNT                  <t>/ TOTAL_VOICE_COUNT
6572                  </t>                  </t>
6573                    <t>/ GLOBAL_INFO
6574                    </t>
6575          </list>          </list>
6576  </t>  </t>
6577  <t>unsubscribe_event =  <t>unsubscribe_event =
6578          <list>          <list>
6579                  <t>CHANNEL_COUNT                  <t>AUDIO_OUTPUT_DEVICE_COUNT
6580                    </t>
6581                    <t>/ AUDIO_OUTPUT_DEVICE_INFO
6582                    </t>
6583                    <t>/ MIDI_INPUT_DEVICE_COUNT
6584                    </t>
6585                    <t>/ MIDI_INPUT_DEVICE_INFO
6586                    </t>
6587                    <t>/ CHANNEL_COUNT
6588                    </t>
6589                    <t>/ CHANNEL_MIDI
6590                    </t>
6591                    <t>/ DEVICE_MIDI
6592                  </t>                  </t>
6593                  <t>/ VOICE_COUNT                  <t>/ VOICE_COUNT
6594                  </t>                  </t>
# Line 4339  Schoenebeck'> Line 6598  Schoenebeck'>
6598                  </t>                  </t>
6599                  <t>/ CHANNEL_INFO                  <t>/ CHANNEL_INFO
6600                  </t>                  </t>
6601                    <t>/ FX_SEND_COUNT
6602                    </t>
6603                    <t>/ FX_SEND_INFO
6604                    </t>
6605                    <t>/ MIDI_INSTRUMENT_MAP_COUNT
6606                    </t>
6607                    <t>/ MIDI_INSTRUMENT_MAP_INFO
6608                    </t>
6609                    <t>/ MIDI_INSTRUMENT_COUNT
6610                    </t>
6611                    <t>/ MIDI_INSTRUMENT_INFO
6612                    </t>
6613                    <t>/ DB_INSTRUMENT_DIRECTORY_COUNT
6614                    </t>
6615                    <t>/ DB_INSTRUMENT_DIRECTORY_INFO
6616                    </t>
6617                    <t>/ DB_INSTRUMENT_COUNT
6618                    </t>
6619                    <t>/ DB_INSTRUMENT_INFO
6620                    </t>
6621                    <t>/ DB_INSTRUMENTS_JOB_INFO
6622                    </t>
6623                  <t>/ MISCELLANEOUS                  <t>/ MISCELLANEOUS
6624                  </t>                  </t>
6625                    <t>/ TOTAL_STREAM_COUNT
6626                    </t>
6627                  <t>/ TOTAL_VOICE_COUNT                  <t>/ TOTAL_VOICE_COUNT
6628                  </t>                  </t>
6629                    <t>/ GLOBAL_INFO
6630                    </t>
6631          </list>          </list>
6632  </t>  </t>
6633  <t>map_instruction =  <t>map_instruction =
6634          <list>          <list>
6635                  <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
6636                  </t>                  </t>
6637                  <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
6638                  </t>                  </t>
6639                  <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
6640                  </t>                  </t>
6641                  <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
6642                  </t>                  </t>
6643          </list>          </list>
6644  </t>  </t>
# Line 4371  Schoenebeck'> Line 6656  Schoenebeck'>
6656                  </t>                  </t>
6657                  <t>/ MIDI_INSTRUMENT_MAP SP ALL                  <t>/ MIDI_INSTRUMENT_MAP SP ALL
6658                  </t>                  </t>
6659                    <t>/ DB_INSTRUMENT_DIRECTORY SP FORCE SP db_path
6660                    </t>
6661                    <t>/ DB_INSTRUMENT_DIRECTORY SP db_path
6662                    </t>
6663                    <t>/ DB_INSTRUMENT SP db_path
6664                    </t>
6665          </list>          </list>
6666  </t>  </t>
6667  <t>get_instruction =  <t>get_instruction =
# Line 4423  Schoenebeck'> Line 6714  Schoenebeck'>
6714                  </t>                  </t>
6715                  <t>/ SERVER SP INFO                  <t>/ SERVER SP INFO
6716                  </t>                  </t>
6717                    <t>/ TOTAL_STREAM_COUNT
6718                    </t>
6719                  <t>/ TOTAL_VOICE_COUNT                  <t>/ TOTAL_VOICE_COUNT
6720                  </t>                  </t>
6721                  <t>/ TOTAL_VOICE_COUNT_MAX                  <t>/ TOTAL_VOICE_COUNT_MAX
# Line 4437  Schoenebeck'> Line 6730  Schoenebeck'>
6730                  </t>                  </t>
6731                  <t>/ MIDI_INSTRUMENT_MAP SP INFO SP midi_map                  <t>/ MIDI_INSTRUMENT_MAP SP INFO SP midi_map
6732                  </t>                  </t>
6733                    <t>/ FX_SENDS SP sampler_channel
6734                    </t>
6735                    <t>/ FX_SEND SP INFO SP sampler_channel SP fx_send_id
6736                    </t>
6737                    <t>/ DB_INSTRUMENT_DIRECTORIES SP RECURSIVE SP db_path
6738                    </t>
6739                    <t>/ DB_INSTRUMENT_DIRECTORIES SP db_path
6740                    </t>
6741                    <t>/ DB_INSTRUMENT_DIRECTORY SP INFO SP db_path
6742                    </t>
6743                    <t>/ DB_INSTRUMENTS SP RECURSIVE SP db_path
6744                    </t>
6745                    <t>/ DB_INSTRUMENTS SP db_path
6746                    </t>
6747                    <t>/ DB_INSTRUMENT SP INFO SP db_path
6748                    </t>
6749                    <t>/ DB_INSTRUMENTS_JOB SP INFO SP number
6750                    </t>
6751                    <t>/ VOLUME
6752                    </t>
6753                    <t>/ FILE SP INSTRUMENTS SP filename
6754                    </t>
6755                    <t>/ FILE SP INSTRUMENT SP INFO SP filename SP instrument_index
6756                    </t>
6757          </list>          </list>
6758  </t>  </t>
6759  <t>set_instruction =  <t>set_instruction =
# Line 4447  Schoenebeck'> Line 6764  Schoenebeck'>
6764                  </t>                  </t>
6765                  <t>/ MIDI_INPUT_DEVICE_PARAMETER SP number SP string '=' param_val_list                  <t>/ MIDI_INPUT_DEVICE_PARAMETER SP number SP string '=' param_val_list
6766                  </t>                  </t>
6767                    <t>/ MIDI_INPUT_PORT_PARAMETER SP number SP number SP string '=' NONE
6768                    </t>
6769                  <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
6770                  </t>                  </t>
6771                  <t>/ CHANNEL SP set_chan_instruction                  <t>/ CHANNEL SP set_chan_instruction
6772                  </t>                  </t>
6773                  <t>/ MIDI_INSTRUMENT_MAP SP NAME SP midi_map SP map_name                  <t>/ MIDI_INSTRUMENT_MAP SP NAME SP midi_map SP map_name
6774                  </t>                  </t>
6775                    <t>/ FX_SEND SP NAME SP sampler_channel SP fx_send_id SP fx_send_name
6776                    </t>
6777                    <t>/ FX_SEND SP AUDIO_OUTPUT_CHANNEL SP sampler_channel SP fx_send_id SP audio_channel_index SP audio_channel_index
6778                    </t>
6779                    <t>/ FX_SEND SP MIDI_CONTROLLER SP sampler_channel SP fx_send_id SP midi_ctrl
6780                    </t>
6781                    <t>/ FX_SEND SP LEVEL SP sampler_channel SP fx_send_id SP volume_value
6782                    </t>
6783                    <t>/ DB_INSTRUMENT_DIRECTORY SP NAME SP db_path SP stringval_escaped
6784                    </t>
6785                    <t>/ DB_INSTRUMENT_DIRECTORY SP DESCRIPTION SP db_path SP stringval_escaped
6786                    </t>
6787                    <t>/ DB_INSTRUMENT SP NAME SP db_path SP stringval_escaped
6788                    </t>
6789                    <t>/ DB_INSTRUMENT SP DESCRIPTION SP db_path SP stringval_escaped
6790                    </t>
6791                    <t>/ DB_INSTRUMENT SP FILE_PATH SP filename SP filename
6792                    </t>
6793                  <t>/ ECHO SP boolean                  <t>/ ECHO SP boolean
6794                  </t>                  </t>
6795                    <t>/ VOLUME SP volume_value
6796                    </t>
6797          </list>          </list>
6798  </t>  </t>
6799  <t>create_instruction =  <t>create_instruction =
# Line 4467  Schoenebeck'> Line 6806  Schoenebeck'>
6806                  </t>                  </t>
6807                  <t>/ MIDI_INPUT_DEVICE SP string                  <t>/ MIDI_INPUT_DEVICE SP string
6808                  </t>                  </t>
6809                    <t>/ FX_SEND SP sampler_channel SP midi_ctrl
6810                    </t>
6811                    <t>/ FX_SEND SP sampler_channel SP midi_ctrl SP fx_send_name
6812                    </t>
6813          </list>          </list>
6814  </t>  </t>
6815  <t>reset_instruction =  <t>reset_instruction =
# Line 4483  Schoenebeck'> Line 6826  Schoenebeck'>
6826                  </t>                  </t>
6827          </list>          </list>
6828  </t>  </t>
6829    <t>find_instruction =
6830            <list>
6831                    <t>DB_INSTRUMENTS SP NON_RECURSIVE SP db_path SP query_val_list
6832                    </t>
6833                    <t>/ DB_INSTRUMENTS SP db_path SP query_val_list
6834                    </t>
6835                    <t>/ DB_INSTRUMENT_DIRECTORIES SP NON_RECURSIVE SP db_path SP query_val_list
6836                    </t>
6837                    <t>/ DB_INSTRUMENT_DIRECTORIES SP db_path SP query_val_list
6838                    </t>
6839                    <t>/ LOST SP DB_INSTRUMENT_FILES
6840                    </t>
6841            </list>
6842    </t>
6843    <t>move_instruction =
6844            <list>
6845                    <t>DB_INSTRUMENT_DIRECTORY SP db_path SP db_path
6846                    </t>
6847                    <t>/ DB_INSTRUMENT SP db_path SP db_path
6848                    </t>
6849            </list>
6850    </t>
6851    <t>copy_instruction =
6852            <list>
6853                    <t>DB_INSTRUMENT_DIRECTORY SP db_path SP db_path
6854                    </t>
6855                    <t>/ DB_INSTRUMENT SP db_path SP db_path
6856                    </t>
6857            </list>
6858    </t>
6859  <t>destroy_instruction =  <t>destroy_instruction =
6860          <list>          <list>
6861                  <t>AUDIO_OUTPUT_DEVICE SP number                  <t>AUDIO_OUTPUT_DEVICE SP number
6862                  </t>                  </t>
6863                  <t>/ MIDI_INPUT_DEVICE SP number                  <t>/ MIDI_INPUT_DEVICE SP number
6864                  </t>                  </t>
6865                    <t>/ FX_SEND SP sampler_channel SP fx_send_id
6866                    </t>
6867          </list>          </list>
6868  </t>  </t>
6869  <t>load_instruction =  <t>load_instruction =
# Line 4531  Schoenebeck'> Line 6906  Schoenebeck'>
6906                  </t>                  </t>
6907          </list>          </list>
6908  </t>  </t>
6909    <t>edit_instruction =
6910            <list>
6911                    <t>CHANNEL SP INSTRUMENT SP sampler_channel
6912                    </t>
6913            </list>
6914    </t>
6915    <t>format_instruction =
6916            <list>
6917                    <t>INSTRUMENTS_DB
6918                    </t>
6919            </list>
6920    </t>
6921    <t>modal_arg =
6922            <list>
6923                    <t>/* epsilon (empty argument) */
6924                    </t>
6925                    <t>/ NON_MODAL SP
6926                    </t>
6927            </list>
6928    </t>
6929  <t>key_val_list =  <t>key_val_list =
6930          <list>          <list>
6931                  <t>string '=' param_val_list                  <t>string '=' param_val_list
# Line 4567  Schoenebeck'> Line 6962  Schoenebeck'>
6962                  </t>                  </t>
6963                  <t>/ MIDI_INSTRUMENT_MAPS                  <t>/ MIDI_INSTRUMENT_MAPS
6964                  </t>                  </t>
6965                    <t>/ FX_SENDS SP sampler_channel
6966                    </t>
6967                    <t>/ DB_INSTRUMENT_DIRECTORIES SP RECURSIVE SP db_path
6968                    </t>
6969                    <t>/ DB_INSTRUMENT_DIRECTORIES SP db_path
6970                    </t>
6971                    <t>/ DB_INSTRUMENTS SP RECURSIVE SP db_path
6972                    </t>
6973                    <t>/ DB_INSTRUMENTS SP db_path
6974                    </t>
6975                    <t>/ FILE SP INSTRUMENTS SP filename
6976                    </t>
6977            </list>
6978    </t>
6979    <t>send_instruction =
6980            <list>
6981                    <t>CHANNEL SP MIDI_DATA SP string SP sampler_channel SP number SP number
6982                    </t>
6983          </list>          </list>
6984  </t>  </t>
6985  <t>load_instr_args =  <t>load_instr_args =
# Line 4649  Schoenebeck'> Line 7062  Schoenebeck'>
7062                  </t>                  </t>
7063          </list>          </list>
7064  </t>  </t>
7065    <t>midi_ctrl =
7066            <list>
7067                    <t>number
7068                    </t>
7069            </list>
7070    </t>
7071  <t>volume_value =  <t>volume_value =
7072          <list>          <list>
7073                  <t>dotnum                  <t>dotnum
# Line 4669  Schoenebeck'> Line 7088  Schoenebeck'>
7088                  </t>                  </t>
7089          </list>          </list>
7090  </t>  </t>
7091    <t>fx_send_id =
7092            <list>
7093                    <t>number
7094                    </t>
7095            </list>
7096    </t>
7097  <t>engine_name =  <t>engine_name =
7098          <list>          <list>
7099                  <t>string                  <t>string
# Line 4677  Schoenebeck'> Line 7102  Schoenebeck'>
7102  </t>  </t>
7103  <t>filename =  <t>filename =
7104          <list>          <list>
7105                  <t>stringval                  <t>path
7106                    </t>
7107            </list>
7108    </t>
7109    <t>db_path =
7110            <list>
7111                    <t>path
7112                  </t>                  </t>
7113          </list>          </list>
7114  </t>  </t>
7115  <t>map_name =  <t>map_name =
7116          <list>          <list>
7117                  <t>stringval                  <t>stringval_escaped
7118                  </t>                  </t>
7119          </list>          </list>
7120  </t>  </t>
7121  <t>entry_name =  <t>entry_name =
7122          <list>          <list>
7123                  <t>stringval                  <t>stringval_escaped
7124                    </t>
7125            </list>
7126    </t>
7127    <t>fx_send_name =
7128            <list>
7129                    <t>stringval_escaped
7130                  </t>                  </t>
7131          </list>          </list>
7132  </t>  </t>
# Line 4701  Schoenebeck'> Line 7138  Schoenebeck'>
7138                  </t>                  </t>
7139          </list>          </list>
7140  </t>  </t>
7141    
7142  <t>param_val =  <t>param_val =
7143          <list>          <list>
7144                  <t>string                  <t>string
# Line 4713  Schoenebeck'> Line 7151  Schoenebeck'>
7151                  </t>                  </t>
7152          </list>          </list>
7153  </t>  </t>
7154    <t>query_val_list =
7155            <list>
7156                    <t>string '=' query_val
7157                    </t>
7158                    <t>/ query_val_list SP string '=' query_val
7159                    </t>
7160            </list>
7161    </t>
7162    <t>query_val =
7163            <list>
7164                    <t>text_escaped
7165                    </t>
7166                    <t>/ stringval_escaped
7167                    </t>
7168            </list>
7169    </t>
7170    <t>scan_mode =
7171            <list>
7172                    <t>RECURSIVE
7173                    </t>
7174                    <t>/ NON_RECURSIVE
7175                    </t>
7176                    <t>/ FLAT
7177                    </t>
7178            </list>
7179    </t>
7180    
7181              <!-- GRAMMAR_BNF_END - do NOT delete or modify this line !!! -->              <!-- GRAMMAR_BNF_END - do NOT delete or modify this line !!! -->
7182    
7183                <section title="Character Set and Escape Sequences" anchor="character_set">
7184                    <t>Older versions of this protocol up to and including v1.1 only
7185                    supported the standard ASCII character set (ASCII code 0 - 127)
7186                    <xref target="RFC20"/>, all younger versions of this protocol
7187                    however support the Extended ASCII character set (ASCII code
7188                    0 - 255). The same group of younger protocols also support
7189                    escape sequences, but only for certain, explicitly declared
7190                    parts of the protocol. The supported escape sequences are
7191                    defined as follows:</t>
7192                    <texttable>
7193                        <ttcol>ASCII Character Sequence</ttcol>
7194                        <ttcol>Translated into (Name)</ttcol>
7195                        <c>\n</c> <c>new line</c>
7196                        <c>\r</c> <c>carriage return</c>
7197                        <c>\f</c> <c>form feed</c>
7198                        <c>\t</c> <c>horizontal tab</c>
7199                        <c>\v</c> <c>vertical tab</c>
7200                        <c>\'</c> <c>apostrophe</c>
7201                        <c>\"</c> <c>quotation mark</c>
7202                        <c>\\</c> <c>backslash</c>
7203                        <c>\OOO</c> <c>three digit octal ASCII code of the character</c>
7204                        <c>\xHH</c> <c>two digit hex ASCII code of the character</c>
7205                    </texttable>
7206                    <t>Notice: due to the transition of certain parts of the
7207                    protocol which now support escape sequences, a slight backward
7208                    incompatibility to protocols version v1.1 and younger has been
7209                    introduced. The only difference is that in parts of the protocol
7210                    where escape characters are now supported, a backslash characters
7211                    MUST be escaped as well (that is as double backslash), whereas
7212                    in the old versions a single backslash was sufficient.</t>
7213    
7214                    <t>The following LSCP commands support escape sequences as part
7215                    of their filename / path based arguments and / or may contain
7216                    a filename / path with escape sequences in their response:
7217                    <list>
7218                        <t><xref target="LOAD INSTRUMENT">"LOAD INSTRUMENT"</xref></t>
7219                        <t><xref target="GET CHANNEL INFO">"GET CHANNEL INFO"</xref></t>
7220                        <t><xref target="MAP MIDI_INSTRUMENT">"MAP MIDI_INSTRUMENT"</xref></t>
7221                        <t><xref target="GET MIDI_INSTRUMENT INFO">"GET MIDI_INSTRUMENT INFO"</xref></t>
7222                        <t><xref target="ADD DB_INSTRUMENT_DIRECTORY">"ADD DB_INSTRUMENT_DIRECTORY"</xref></t>
7223                        <t><xref target="ADD DB_INSTRUMENTS">"ADD DB_INSTRUMENTS"</xref></t>
7224                        <t><xref target="REMOVE DB_INSTRUMENT_DIRECTORY">"REMOVE DB_INSTRUMENT_DIRECTORY"</xref></t>
7225                        <t><xref target="REMOVE DB_INSTRUMENT">"REMOVE DB_INSTRUMENT"</xref></t>
7226                        <t><xref target="GET DB_INSTRUMENT_DIRECTORIES">"GET DB_INSTRUMENT_DIRECTORIES"</xref></t>
7227                        <t><xref target="LIST DB_INSTRUMENT_DIRECTORIES">"LIST DB_INSTRUMENT_DIRECTORIES"</xref></t>
7228                        <t><xref target="GET DB_INSTRUMENT_DIRECTORY INFO">"GET DB_INSTRUMENT_DIRECTORY INFO"</xref></t>
7229                        <t><xref target="GET DB_INSTRUMENTS">"GET DB_INSTRUMENTS"</xref></t>
7230                        <t><xref target="LIST DB_INSTRUMENTS">"LIST DB_INSTRUMENTS"</xref></t>
7231                        <t><xref target="GET DB_INSTRUMENT INFO">"GET DB_INSTRUMENT INFO"</xref></t>
7232                        <t><xref target="SET DB_INSTRUMENT_DIRECTORY NAME">"SET DB_INSTRUMENT_DIRECTORY NAME"</xref></t>
7233                        <t><xref target="SET DB_INSTRUMENT_DIRECTORY DESCRIPTION">"SET DB_INSTRUMENT_DIRECTORY DESCRIPTION"</xref></t>
7234                        <t><xref target="SET DB_INSTRUMENT NAME">"SET DB_INSTRUMENT NAME"</xref></t>
7235                        <t><xref target="SET DB_INSTRUMENT DESCRIPTION">"SET DB_INSTRUMENT DESCRIPTION"</xref></t>
7236                        <t><xref target="FIND DB_INSTRUMENTS">"FIND DB_INSTRUMENTS"</xref></t>
7237                        <t><xref target="FIND DB_INSTRUMENT_DIRECTORIES">"FIND DB_INSTRUMENT_DIRECTORIES"</xref></t>
7238                        <t><xref target="MOVE DB_INSTRUMENT">"MOVE DB_INSTRUMENT"</xref></t>
7239                        <t><xref target="MOVE DB_INSTRUMENT_DIRECTORY">"MOVE DB_INSTRUMENT_DIRECTORY"</xref></t>
7240                        <t><xref target="COPY DB_INSTRUMENT">"COPY DB_INSTRUMENT"</xref></t>
7241                        <t><xref target="COPY DB_INSTRUMENT_DIRECTORY">"COPY DB_INSTRUMENT_DIRECTORY"</xref></t>
7242                        <t><xref target="FIND LOST DB_INSTRUMENT_FILES">"FIND LOST DB_INSTRUMENT_FILES"</xref></t>
7243                        <t><xref target="SET DB_INSTRUMENT FILE_PATH">"SET DB_INSTRUMENT FILE_PATH"</xref></t>
7244                        <t><xref target="GET FILE INSTRUMENTS">"GET FILE INSTRUMENTS"</xref></t>
7245                        <t><xref target="LIST FILE INSTRUMENTS">"LIST FILE INSTRUMENTS"</xref></t>
7246                        <t><xref target="GET FILE INSTRUMENT INFO">"GET FILE INSTRUMENT INFO"</xref></t>
7247                    </list>
7248                    Note that the forward slash character ('/') has a special meaning in
7249                    filename / path based arguments: it acts as separator of the nodes in
7250                    the path, thus if a directory- or filename includes a forward slash
7251                    (not intended as path node separator), you MUST escape that slash
7252                    either with the respective hex escape sequence ("\x2f") or with the
7253                    respective octal escape sequence ("\057").
7254                    </t>
7255    
7256                    <t>
7257                    Note for Windows: file path arguments in LSCP are expected
7258                    to use forward slashes as directory node separator similar
7259                    to Unix based operating systems. In contrast to Unix however
7260                    a Windows typical drive character is expected to be
7261                    prefixed to the path. That is an original Windows file path
7262                    like "D:\Sounds\My.gig" would become in LSCP:
7263                    "D:/Sounds/My.gig".
7264                    </t>
7265    
7266                    <t>
7267                    The following LSCP commands even support escape sequences as
7268                    part of at least one of their text-based arguments (i.e. entity name,
7269                    description) and / or may contain escape sequences in at least one of
7270                    their text-based fields in their response:
7271                    <list>
7272                        <t><xref target="GET SERVER INFO">"GET SERVER INFO"</xref></t>
7273                        <t><xref target="GET ENGINE INFO">"GET ENGINE INFO"</xref></t>
7274                        <t><xref target="GET CHANNEL INFO">"GET CHANNEL INFO"</xref></t>
7275                        <t><xref target="CREATE FX_SEND">"CREATE FX_SEND"</xref></t>
7276                        <t><xref target="GET FX_SEND INFO">"GET FX_SEND INFO"</xref></t>
7277                        <t><xref target="SET FX_SEND NAME">"SET FX_SEND NAME"</xref></t>
7278                        <t><xref target="GET MIDI_INSTRUMENT INFO">"GET MIDI_INSTRUMENT INFO"</xref></t>
7279                        <t><xref target="GET MIDI_INSTRUMENT_MAP INFO">"GET MIDI_INSTRUMENT_MAP INFO"</xref></t>
7280                        <t><xref target="ADD MIDI_INSTRUMENT_MAP">"ADD MIDI_INSTRUMENT_MAP"</xref></t>
7281                        <t><xref target="MAP MIDI_INSTRUMENT">"MAP MIDI_INSTRUMENT"</xref></t>
7282                        <t><xref target="SET MIDI_INSTRUMENT_MAP NAME">"SET MIDI_INSTRUMENT_MAP NAME"</xref></t>
7283                        <t><xref target="GET DB_INSTRUMENT_DIRECTORY INFO">"GET DB_INSTRUMENT_DIRECTORY INFO"</xref></t>
7284                        <t><xref target="SET DB_INSTRUMENT_DIRECTORY NAME">"SET DB_INSTRUMENT_DIRECTORY NAME"</xref></t>
7285                        <t><xref target="SET DB_INSTRUMENT_DIRECTORY DESCRIPTION">"SET DB_INSTRUMENT_DIRECTORY DESCRIPTION"</xref></t>
7286                        <t><xref target="FIND DB_INSTRUMENT_DIRECTORIES">"FIND DB_INSTRUMENT_DIRECTORIES"</xref></t>
7287                        <t><xref target="GET DB_INSTRUMENT INFO">"GET DB_INSTRUMENT INFO"</xref></t>
7288                        <t><xref target="SET DB_INSTRUMENT NAME">"SET DB_INSTRUMENT NAME"</xref></t>
7289                        <t><xref target="SET DB_INSTRUMENT DESCRIPTION">"SET DB_INSTRUMENT DESCRIPTION"</xref></t>
7290                        <t><xref target="FIND DB_INSTRUMENTS">"FIND DB_INSTRUMENTS"</xref></t>
7291                    </list>
7292                    Please note that these lists are manually maintained. If you
7293                    find a command that also supports escape sequences we forgot to
7294                    mention here, please report it!
7295                    </t>
7296                </section>
7297          </section>          </section>
7298    
7299          <section title="Events" anchor="events">          <section title="Events" anchor="events">
# Line 4818  Schoenebeck'> Line 7397  Schoenebeck'>
7397                  of sampler channels.</t>                  of sampler channels.</t>
7398              </section>              </section>
7399    
7400                <section title="MIDI data on a sampler channel arrived" anchor="SUBSCRIBE CHANNEL_MIDI">
7401                    <t>Client may want to be notified when MIDI data arrive on sampler channels on
7402                    back-end side, by issuing the following command:</t>
7403                    <t>
7404                        <list>
7405                            <t>SUBSCRIBE CHANNEL_MIDI</t>
7406                        </list>
7407                    </t>
7408                    <t>Server will start sending one of the the following notification messages:</t>
7409                    <t>
7410                        <list>
7411                            <t>"NOTIFY:CHANNEL_MIDI:&lt;channel-id&gt; NOTE_ON  &lt;note&gt; &lt;velocity&gt;"</t>
7412                            <t>"NOTIFY:CHANNEL_MIDI:&lt;channel-id&gt; NOTE_OFF &lt;note&gt; &lt;velocity&gt;"</t>
7413                        </list>
7414                    </t>
7415                    <t>where &lt;channel-id&gt; will be replaced by the ID of the sampler channel where the MIDI
7416                    data arrived. &lt;note&gt; and &lt;velocity&gt; are integer values in the range between
7417                    0 .. 127, reflecting the analog meaning of the MIDI specification.
7418                    </t>
7419                    <t>CAUTION: no guarantee whatsoever will be made that MIDI events are actually all
7420                    delivered by this mechanism! With other words: events could be lost at any time!
7421                    This restriction was made to keep the RT-safeness of the backend's MIDI and audio
7422                    thread unaffected by this feature.</t>
7423                </section>
7424    
7425                <section title="MIDI data on a MIDI input device arrived" anchor="SUBSCRIBE DEVICE_MIDI">
7426                        <t>Client may want to be notified when MIDI data arrive on MIDI input devices by issuing the following command:</t>
7427                        <t>
7428                                <list>
7429                                        <t>SUBSCRIBE DEVICE_MIDI</t>
7430                                </list>
7431                        </t>
7432                        <t>Server will start sending one of the the following notification messages:</t>
7433                        <t>
7434                                <list>
7435                                        <t>"NOTIFY:DEVICE_MIDI:&lt;device-id&gt; &lt;port-id&gt; NOTE_ON &lt;note&gt; &lt;velocity&gt;"</t>
7436                                        <t>"NOTIFY:DEVICE_MIDI:&lt;device-id&gt; &lt;port-id&gt; NOTE_OFF &lt;note&gt; &lt;velocity&gt;"</t>
7437                                </list>
7438                        </t>
7439                        <t>where &lt;device-id&gt; &lt;port-id&gt; will be replaced
7440                           by the IDs of the respective MIDI input device and the device's MIDI port where the MIDI
7441                           data arrived. &lt;note&gt; and &lt;velocity&gt; are integer values in the range between
7442                           0 .. 127, reflecting the analog meaning of the MIDI specification.
7443                        </t>
7444                        <t>CAUTION: no guarantee whatsoever will be made that MIDI events are actually all
7445                           delivered by this mechanism! With other words: events could be lost at any time!
7446                           This restriction was made to keep the RT-safeness of the backend's MIDI and audio
7447                           thread unaffected by this feature.</t>
7448                </section>
7449    
7450              <section title="Number of active voices changed" anchor="SUBSCRIBE VOICE_COUNT">              <section title="Number of active voices changed" anchor="SUBSCRIBE VOICE_COUNT">
7451                  <t>Client may want to be notified when the number of voices on the                  <t>Client may want to be notified when the number of voices on the
7452                  back-end changes by issuing the following command:</t>                  back-end changes by issuing the following command:</t>
# Line 4829  Schoenebeck'> Line 7458  Schoenebeck'>
7458                  <t>Server will start sending the following notification messages:</t>                  <t>Server will start sending the following notification messages:</t>
7459                  <t>                  <t>
7460                      <list>                      <list>
7461                          <t>"NOTIFY:VOICE_COUNT:&lt;sampler-channel&gt; &lt;voices&gt;</t>                          <t>"NOTIFY:VOICE_COUNT:&lt;sampler-channel&gt; &lt;voices&gt;"</t>
7462                      </list>                      </list>
7463                  </t>                  </t>
7464                  <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 7528  Schoenebeck'>
7528                  message is sufficient here.</t>                  message is sufficient here.</t>
7529              </section>              </section>
7530    
7531                <section title="Number of effect sends changed" anchor="SUBSCRIBE FX_SEND_COUNT">
7532                    <t>Client may want to be notified when the number of effect sends on
7533                    a particular sampler channel is changed by issuing the following command:</t>
7534                    <t>
7535                        <list>
7536                            <t>SUBSCRIBE FX_SEND_COUNT</t>
7537                        </list>
7538                    </t>
7539                    <t>Server will start sending the following notification messages:</t>
7540                    <t>
7541                        <list>
7542                            <t>"NOTIFY:FX_SEND_COUNT:&lt;channel-id&gt; &lt;fx-sends&gt;"</t>
7543                        </list>
7544                    </t>
7545                    <t>where &lt;channel-id&gt; will be replaced by the numerical ID of the sampler
7546                    channel, on which the effect sends number is changed and &lt;fx-sends&gt; will
7547                    be replaced by the new number of effect sends on that channel.</t>
7548                </section>
7549    
7550                <section title="Effect send information changed" anchor="SUBSCRIBE FX_SEND_INFO">
7551                    <t>Client may want to be notified when changes were made to effect sends on a
7552                    a particular sampler channel by issuing the following command:</t>
7553                    <t>
7554                        <list>
7555                            <t>SUBSCRIBE FX_SEND_INFO</t>
7556                        </list>
7557                    </t>
7558                    <t>Server will start sending the following notification messages:</t>
7559                    <t>
7560                        <list>
7561                            <t>"NOTIFY:FX_SEND_INFO:&lt;channel-id&gt; &lt;fx-send-id&gt;"</t>
7562                        </list>
7563                    </t>
7564                    <t>where &lt;channel-id&gt; will be replaced by the numerical ID of the sampler
7565                    channel, on which an effect send entity is changed and &lt;fx-send-id&gt; will
7566                    be replaced by the numerical ID of the changed effect send.</t>
7567                </section>
7568    
7569              <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">
7570                  <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
7571                  back-end changes by issuing the following command:</t>                  back-end changes by issuing the following command:</t>
# Line 4910  Schoenebeck'> Line 7577  Schoenebeck'>
7577                  <t>Server will start sending the following notification messages:</t>                  <t>Server will start sending the following notification messages:</t>
7578                  <t>                  <t>
7579                      <list>                      <list>
7580                          <t>"NOTIFY:TOTAL_VOICE_COUNT:&lt;voices&gt;</t>                          <t>"NOTIFY:TOTAL_VOICE_COUNT:&lt;voices&gt;"</t>
7581                      </list>                      </list>
7582                  </t>                  </t>
7583                  <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
7584                  all currently active voices.</t>                  all currently active voices.</t>
7585              </section>              </section>
7586    
7587                <section title="Total number of active disk streams changed" anchor="SUBSCRIBE TOTAL_STREAM_COUNT">
7588                    <t>Client may want to be notified when the total number of disk streams on the
7589                    back-end changes by issuing the following command:</t>
7590                    <t>
7591                        <list>
7592                            <t>SUBSCRIBE TOTAL_STREAM_COUNT</t>
7593                        </list>
7594                    </t>
7595                    <t>Server will start sending the following notification messages:</t>
7596                    <t>
7597                        <list>
7598                            <t>"NOTIFY:TOTAL_STREAM_COUNT:&lt;streams&gt;"</t>
7599                        </list>
7600                    </t>
7601                    <t>where &lt;streams&gt; will be replaced by the new number of
7602                    all currently active disk streams.</t>
7603                </section>
7604    
7605              <section title="Number of MIDI instrument maps changed" anchor="SUBSCRIBE MIDI_INSTRUMENT_MAP_COUNT">              <section title="Number of MIDI instrument maps changed" anchor="SUBSCRIBE MIDI_INSTRUMENT_MAP_COUNT">
7606                  <t>Client may want to be notified when the number of MIDI instrument maps on the                  <t>Client may want to be notified when the number of MIDI instrument maps on the
7607                  back-end changes by issuing the following command:</t>                  back-end changes by issuing the following command:</t>
# Line 4971  Schoenebeck'> Line 7656  Schoenebeck'>
7656                          <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>
7657                      </list>                      </list>
7658                  </t>                  </t>
7659                  <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
7660                  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
7661                  the new number of MIDI instruments in the specified map.</t>                  the new number of MIDI instruments in the specified map.</t>
7662              </section>              </section>
# Line 4991  Schoenebeck'> Line 7676  Schoenebeck'>
7676                      </list>                      </list>
7677                  </t>                  </t>
7678                  <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,
7679                  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
7680                  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
7681                  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
7682                  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 7684  Schoenebeck'>
7684                  message is sufficient here.</t>                  message is sufficient here.</t>
7685              </section>              </section>
7686    
7687              <<section title="Miscellaneous and debugging events" anchor="SUBSCRIBE MISCELLANEOUS">              <section title="Global settings changed" anchor="SUBSCRIBE GLOBAL_INFO">
7688                    <t>Client may want to be notified when changes to the global settings
7689                    of the sampler were made by issuing the following command:</t>
7690                    <t>
7691                        <list>
7692                            <t>SUBSCRIBE GLOBAL_INFO</t>
7693                        </list>
7694                    </t>
7695                    <t>Server will start sending the following types of notification messages:</t>
7696                    <t>
7697                        <list>
7698                            <t>"NOTIFY:GLOBAL_INFO:VOLUME &lt;volume&gt;" - Notifies that the
7699                            golbal volume of the sampler is changed, where &lt;volume&gt; will be
7700                            replaced by the optional dotted floating point value, reflecting the
7701                            new global volume parameter.</t>
7702                        </list>
7703                    </t>
7704                </section>
7705    
7706                <section title="Number of database instrument directories changed" anchor="SUBSCRIBE DB_INSTRUMENT_DIRECTORY_COUNT">
7707                    <t>Client may want to be notified when the number of instrument
7708                    directories in a particular directory in the instruments database
7709                    is changed by issuing the following command:</t>
7710                    <t>
7711                        <list>
7712                            <t>SUBSCRIBE DB_INSTRUMENT_DIRECTORY_COUNT</t>
7713                        </list>
7714                    </t>
7715                    <t>Server will start sending the following notification messages:</t>
7716                    <t>
7717                        <list>
7718                            <t>"NOTIFY:DB_INSTRUMENT_DIRECTORY_COUNT:&lt;dir-path&gt;"</t>
7719                        </list>
7720                    </t>
7721                    <t>where &lt;dir-path&gt; will be replaced by the absolute path
7722                    name of the directory in the instruments database,
7723                    in which the number of directories is changed.</t>
7724                    <t>Note that when a non-empty directory is removed, this event
7725                    is not sent for the subdirectories in that directory.</t>
7726                </section>
7727    
7728                <section title="Database instrument directory information changed" anchor="SUBSCRIBE DB_INSTRUMENT_DIRECTORY_INFO">
7729                    <t>Client may want to be notified when changes were made to directories
7730                    in the instruments database by issuing the following command:</t>
7731                    <t>
7732                        <list>
7733                            <t>SUBSCRIBE DB_INSTRUMENT_DIRECTORY_INFO</t>
7734                        </list>
7735                    </t>
7736                    <t>Server will start sending the following notification messages:</t>
7737                    <t>
7738                        <list>
7739                            <t>"NOTIFY:DB_INSTRUMENT_DIRECTORY_INFO:&lt;dir-path&gt;"</t>
7740                        </list>
7741                    </t>
7742                    <t>where &lt;dir-path&gt; will be replaced by the absolute path name
7743                    of the directory, for which information changes occurred. The front-end will have to send
7744                    the respective command to actually get the updated directory info. Because these messages
7745                    will be triggered by LSCP commands issued by other clients rather than real
7746                    time events happening on the server, it is believed that an empty notification
7747                    message is sufficient here.</t>
7748                    <t>
7749                        <list>
7750                            <t>"NOTIFY:DB_INSTRUMENT_DIRECTORY_INFO:NAME &lt;old-dir-path&gt; &lt;new-name&gt;"</t>
7751                        </list>
7752                    </t>
7753                    <t>where &lt;old-dir-path&gt; is the old absolute path name of the directory
7754                    (encapsulated into apostrophes), which name is changes and &lt;new-name&gt; is
7755                    the new name of the directory, encapsulated into apostrophes.</t>
7756                </section>
7757    
7758                <section title="Number of database instruments changed" anchor="SUBSCRIBE DB_INSTRUMENT_COUNT">
7759                    <t>Client may want to be notified when the number of instruments
7760                    in a particular directory in the instruments database
7761                    is changed by issuing the following command:</t>
7762                    <t>
7763                        <list>
7764                            <t>SUBSCRIBE DB_INSTRUMENT_COUNT</t>
7765                        </list>
7766                    </t>
7767                    <t>Server will start sending the following notification messages:</t>
7768                    <t>
7769                        <list>
7770                            <t>"NOTIFY:DB_INSTRUMENT_COUNT:&lt;dir-path&gt;"</t>
7771                        </list>
7772                    </t>
7773                    <t>where &lt;dir-path&gt; will be replaced by the absolute path
7774                    name of the directory in the instruments database,
7775                    in which the number of instruments is changed.</t>
7776                    <t>Note that when a non-empty directory is removed, this event
7777                    is not sent for the instruments in that directory.</t>
7778                </section>
7779    
7780                <section title="Database instrument information changed" anchor="SUBSCRIBE DB_INSTRUMENT_INFO">
7781                    <t>Client may want to be notified when changes were made to instruments
7782                    in the instruments database by issuing the following command:</t>
7783                    <t>
7784                        <list>
7785                            <t>SUBSCRIBE DB_INSTRUMENT_INFO</t>
7786                        </list>
7787                    </t>
7788                    <t>Server will start sending the following notification messages:</t>
7789                    <t>
7790                        <list>
7791                            <t>"NOTIFY:DB_INSTRUMENT_INFO:&lt;instr-path&gt;"</t>
7792                        </list>
7793                    </t>
7794                    <t>where &lt;instr-path&gt; will be replaced by the absolute path name
7795                    of the instrument, which settings are changed. The front-end will have to send
7796                    the respective command to actually get the updated directory info. Because these messages
7797                    will be triggered by LSCP commands issued by other clients rather than real
7798                    time events happening on the server, it is believed that an empty notification
7799                    message is sufficient here.</t>
7800                    <t>
7801                        <list>
7802                            <t>"NOTIFY:DB_INSTRUMENT_INFO:NAME &lt;old-instr-path&gt; &lt;new-name&gt;"</t>
7803                        </list>
7804                    </t>
7805                    <t>where &lt;old-instr-path&gt; is the old absolute path name of the instrument
7806                    (encapsulated into apostrophes), which name is changes and &lt;new-name&gt; is
7807                    the new name of the instrument, encapsulated into apostrophes.</t>
7808                </section>
7809    
7810                <section title="Database job status information changed" anchor="SUBSCRIBE DB_INSTRUMENTS_JOB_INFO">
7811                    <t>Client may want to be notified when the status of particular database
7812                    instruments job is changed by issuing the following command:</t>
7813                    <t>
7814                        <list>
7815                            <t>SUBSCRIBE DB_INSTRUMENTS_JOB_INFO</t>
7816                        </list>
7817                    </t>
7818                    <t>Server will start sending the following notification messages:</t>
7819                    <t>
7820                        <list>
7821                            <t>"NOTIFY:DB_INSTRUMENTS_JOB_INFO:&lt;job-id&gt;"</t>
7822                        </list>
7823                    </t>
7824                    <t>where &lt;job-id&gt; will be replaced by the numerical ID of the job,
7825                    which status is changed. The front-end will have to send the respective
7826                    command to actually get the status info. Because these messages
7827                    will be triggered by LSCP commands issued by other clients rather than real
7828                    time events happening on the server, it is believed that an empty notification
7829                    message is sufficient here.</t>
7830                </section>
7831    
7832                <section title="Miscellaneous and debugging events" anchor="SUBSCRIBE MISCELLANEOUS">
7833                  <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
7834                  the server by issuing the following command:</t>                  the server by issuing the following command:</t>
7835                  <t>                  <t>
# Line 5077  Schoenebeck'> Line 7907  Schoenebeck'>
7907                  </front>                  </front>
7908                  <seriesInfo name="RFC" value="2234" />                  <seriesInfo name="RFC" value="2234" />
7909              </reference>              </reference>
7910                <reference anchor="RFC20">
7911                    <front>
7912                        <title>ASCII format for Network Interchange</title>
7913                        <author>
7914                            <organization>UCLA</organization>
7915                        </author>
7916                        <date year="1969"></date>
7917                    </front>
7918                    <seriesInfo name="RFC" value="20" />
7919                </reference>
7920           </references>           </references>
7921      </back>      </back>
7922    
Legend:
Removed from v.981  
changed lines
  Added in v.1772
  ViewVC Help
Powered by ViewVC