/[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 706 by iliev, Thu Jul 21 08:34:46 2005 UTC revision 1135 by iliev, Thu Mar 29 09:40:45 2007 UTC
# Line 11  Line 11 
11  <?rfc symrefs="yes" ?>  <?rfc symrefs="yes" ?>
12  <?rfc sortrefs="yes"?>  <?rfc sortrefs="yes"?>
13  <?rfc iprnotified="no" ?>  <?rfc iprnotified="no" ?>
 <?rfc strict="yes" ?>  
14    
15  <rfc category="std" ipr="full2026" docName="LSCP 1.1">  <!-- FIXME: next attribute should actually be "yes", temporarily disbled due
16         to an annoying "missing Normative/Informative References" error message -->
17    <?rfc strict="no" ?>
18    
19    <rfc category="std" ipr="full3978" docName="LSCP 1.2">
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 31  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="May" year="2005"/>          <date month="March" year="2007"/>
38          <workgroup>LinuxSampler Developers</workgroup>          <workgroup>LinuxSampler Developers</workgroup>
39          <keyword>LSCP</keyword>          <keyword>LSCP</keyword>
40          <abstract>          <abstract>
# Line 2552  Schoenebeck'> Line 2555  Schoenebeck'>
2555                                      <t>VOLUME -                                      <t>VOLUME -
2556                                          <list>                                          <list>
2557                                              <t>optionally dotted number for the channel volume factor                                              <t>optionally dotted number for the channel volume factor
2558                                              (where a value < 1.0 means attenuation and a value >                                              (where a value &lt; 1.0 means attenuation and a value >
2559                                              1.0 means amplification)</t>                                              1.0 means amplification)</t>
2560                                          </list>                                          </list>
2561                                      </t>                                      </t>
2562                                      <t>MUTE -                                      <t>MUTE -
2563                                          <list>                                          <list>
2564                                              <t>Determines whether the channel is muted, "true" if the                                              <t>Determines whether the channel is muted, "true" if the
2565                                              channel is muted, "false" if the channel is not muted, and                                              channel is muted, "false" if the channel is not muted, and
2566                                              "MUTED_BY_SOLO" if the channel is muted because of the                                              "MUTED_BY_SOLO" if the channel is muted because of the
2567                                              presence of a solo channel and will be unmuted when                                              presence of a solo channel and will be unmuted when
2568                                              there are no solo channels left</t>                                              there are no solo channels left</t>
2569                                          </list>                                          </list>
2570                                      </t>                                      </t>
# Line 2571  Schoenebeck'> Line 2574  Schoenebeck'>
2574                                              the channel is a solo channel; "false" otherwise</t>                                              the channel is a solo channel; "false" otherwise</t>
2575                                          </list>                                          </list>
2576                                      </t>                                      </t>
2577                                        <t>MIDI_INSTRUMENT_MAP -
2578                                            <list>
2579                                                <t>Determines to which MIDI instrument map this sampler
2580                                                channel is assigned to. Read chapter
2581                                                <xref target="SET CHANNEL MIDI_INSTRUMENT_MAP">"SET CHANNEL MIDI_INSTRUMENT_MAP"</xref>
2582                                                for a list of possible values.</t>
2583                                            </list>
2584                                        </t>
2585                                  </list>                                  </list>
2586                              </t>                              </t>
2587                          </list>                          </list>
# Line 2593  Schoenebeck'> Line 2604  Schoenebeck'>
2604                              <t>&nbsp;&nbsp;&nbsp;"MIDI_INPUT_DEVICE: 0"</t>                              <t>&nbsp;&nbsp;&nbsp;"MIDI_INPUT_DEVICE: 0"</t>
2605                              <t>&nbsp;&nbsp;&nbsp;"MIDI_INPUT_PORT: 0"</t>                              <t>&nbsp;&nbsp;&nbsp;"MIDI_INPUT_PORT: 0"</t>
2606                              <t>&nbsp;&nbsp;&nbsp;"MIDI_INPUT_CHANNEL: 5"</t>                              <t>&nbsp;&nbsp;&nbsp;"MIDI_INPUT_CHANNEL: 5"</t>
2607                                <t>&nbsp;&nbsp;&nbsp;"VOLUME: 1.0"</t>
2608                                <t>&nbsp;&nbsp;&nbsp;"MUTE: false"</t>
2609                                <t>&nbsp;&nbsp;&nbsp;"SOLO: false"</t>
2610                                <t>&nbsp;&nbsp;&nbsp;"MIDI_INSTRUMENT_MAP: NONE"</t>
2611                              <t>&nbsp;&nbsp;&nbsp;"."</t>                              <t>&nbsp;&nbsp;&nbsp;"."</t>
2612                          </list>                          </list>
2613                      </t>                      </t>
# Line 2753  Schoenebeck'> Line 2768  Schoenebeck'>
2768                      </t>                      </t>
2769                  </section>                  </section>
2770    
2771                  <section title="Setting audio output type" anchor="SET CHANNEL AUDIO_OUTPUT_TYP">                  <section title="Setting audio output type" anchor="SET CHANNEL AUDIO_OUTPUT_TYPE">
2772                      <t>DEPRECATED: THIS COMMAND WILL DISAPPEAR SOON!</t>                      <t>DEPRECATED: THIS COMMAND WILL DISAPPEAR SOON!</t>
2773    
2774                      <t>The front-end can alter the audio output type on a specific sampler                      <t>The front-end can alter the audio output type on a specific sampler
# Line 3144  Schoenebeck'> Line 3159  Schoenebeck'>
3159                      </t>                      </t>
3160                  </section>                  </section>
3161    
3162                    <section title="Assigning a MIDI instrument map to a sampler channel" anchor="SET CHANNEL MIDI_INSTRUMENT_MAP">
3163                        <t>The front-end can assign a MIDI instrument map to a specific sampler channel
3164                        by sending the following command:</t>
3165                        <t>
3166                            <list>
3167                                <t>SET CHANNEL MIDI_INSTRUMENT_MAP &lt;sampler-channel&gt; &lt;map&gt;</t>
3168                            </list>
3169                        </t>
3170                        <t>Where &lt;sampler-channel&gt; is the respective sampler channel
3171                        number as returned by the <xref target="ADD CHANNEL">"ADD CHANNEL"</xref>
3172                        or <xref target="LIST CHANNELS">"LIST CHANNELS"</xref> command and
3173                        &lt;map&gt; can have the following possibilites:</t>
3174                        <t>
3175                            <list>
3176                                <t>"NONE" -
3177                                    <list>
3178                                        <t>This is the default setting. In this case
3179                                        the sampler channel is not assigned any MIDI
3180                                        instrument map and thus will ignore all MIDI
3181                                        program change messages.</t>
3182                                    </list>
3183                                </t>
3184                                <t>"DEFAULT" -
3185                                    <list>
3186                                        <t>The sampler channel will always use the
3187                                        default MIDI instrument map to handle MIDI
3188                                        program change messages.</t>
3189                                    </list>
3190                                </t>
3191                                <t>numeric ID -
3192                                    <list>
3193                                        <t>You can assign a specific MIDI instrument map
3194                                        by replacing &lt;map&gt; with the respective numeric
3195                                        ID of the MIDI instrument map as returned by the
3196                                        <xref target="LIST MIDI_INSTRUMENT_MAPS">"LIST MIDI_INSTRUMENT_MAPS"</xref>
3197                                        command. Once that map will be deleted, the sampler
3198                                        channel would fall back to "NONE".</t>
3199                                    </list>
3200                                </t>
3201                            </list>
3202                        </t>
3203                        <t>Read chapter <xref target="MIDI Instrument Mapping">"MIDI Instrument Mapping"</xref>
3204                        for details regarding MIDI instrument mapping.</t>
3205    
3206                        <t>Possible Answers:</t>
3207                        <t>
3208                            <list>
3209                                <t>"OK" -
3210                                    <list>
3211                                        <t>on success</t>
3212                                    </list>
3213                                </t>
3214                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
3215                                    <list>
3216                                        <t>in case it failed, providing an appropriate error code and error message</t>
3217                                    </list>
3218                                </t>
3219                            </list>
3220                        </t>
3221    
3222                        <t>Examples:</t>
3223                        <t>
3224                            <list>
3225                                <t></t>
3226                            </list>
3227                        </t>
3228                    </section>
3229    
3230                    <section title="Adding an effect send to a sampler channel" anchor="CREATE FX_SEND">
3231                        <t>The front-end can create an additional effect send on a specific sampler channel
3232                        by sending the following command:</t>
3233                        <t>
3234                            <list>
3235                                <t>CREATE FX_SEND &lt;sampler-channel&gt; &lt;midi-ctrl&gt; [&lt;name&gt;]</t>
3236                            </list>
3237                        </t>
3238                        <t>Where &lt;sampler-channel&gt; is the respective sampler channel
3239                        number as returned by the <xref target="ADD CHANNEL">"ADD CHANNEL"</xref>
3240                        or <xref target="LIST CHANNELS">"LIST CHANNELS"</xref> command, that is the
3241                        sampler channel on which the effect send should be created on, &lt;midi-ctrl&gt;
3242                        is a number between 0..127 defining the MIDI controller which can alter the
3243                        effect send level and &lt;name&gt; is an optional argument defining a name
3244                        for the effect send entity. The name does not have to be unique.</t>
3245    
3246                        <t>By default, that is as initial routing, the effect send's audio channels
3247                        are automatically routed to the last audio channels of the sampler channel's
3248                        audio output device, that way you can i.e. first increase the amount of audio
3249                        channels on the audio output device for having dedicated effect send output
3250                        channels and when "CREATE FX_SEND" is called, those channels will automatically
3251                        be picked. You can alter the destination channels however with
3252                        <xref target="SET FX_SEND AUDIO_OUTPUT_CHANNEL">"SET FX_SEND AUDIO_OUTPUT_CHANNEL"</xref>.
3253                        </t>
3254    
3255                        <t>Note: Create effect sends on a sampler channel only when needed, because having effect
3256                        sends on a sampler channel will decrease runtime performance, because for implementing channel
3257                        effect sends, separate (sampler channel local) audio buffers are needed to render and mix
3258                        the voices and route the audio signal afterwards to the master outputs and effect send
3259                        outputs (along with their respective effect send levels). A sampler channel without effect
3260                        sends however can mix its voices directly into the audio output devices's audio buffers
3261                        and is thus faster.
3262                        </t>
3263    
3264                        <t>Possible Answers:</t>
3265                        <t>
3266                            <list>
3267                                <t>"OK[&lt;fx-send-id&gt;]" -
3268                                    <list>
3269                                        <t>in case a new effect send could be added to the
3270                                        sampler channel, where &lt;fx-send-id&gt; reflects the
3271                                        unique ID of the newly created effect send entity</t>
3272                                    </list>
3273                                </t>
3274                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
3275                                    <list>
3276                                        <t>when a new effect send could not be added, i.e.
3277                                        due to invalid parameters</t>
3278                                    </list>
3279                                </t>
3280                            </list>
3281                        </t>
3282    
3283                        <t>Examples:</t>
3284                        <t>
3285                            <list>
3286                                <t>C: "CREATE FX_SEND 0 91 'Reverb Send'"</t>
3287                                <t>S: "OK[0]"</t>
3288                            </list>
3289                        </t>
3290                        <t>
3291                            <list>
3292                                <t>C: "CREATE FX_SEND 0 93"</t>
3293                                <t>S: "OK[1]"</t>
3294                            </list>
3295                        </t>
3296                    </section>
3297    
3298                    <section title="Removing an effect send from a sampler channel" anchor="DESTROY FX_SEND">
3299                        <t>The front-end can remove an existing effect send on a specific sampler channel
3300                        by sending the following command:</t>
3301                        <t>
3302                            <list>
3303                                <t>DESTROY FX_SEND &lt;sampler-channel&gt; &lt;fx-send-id&gt;</t>
3304                            </list>
3305                        </t>
3306                        <t>Where &lt;sampler-channel&gt; is the respective sampler channel
3307                        number as returned by the <xref target="ADD CHANNEL">"ADD CHANNEL"</xref>
3308                        or <xref target="LIST CHANNELS">"LIST CHANNELS"</xref> command, that is the
3309                        sampler channel from which the effect send should be removed from and
3310                        &lt;fx-send-id&gt; is the respective effect send number as returned by the
3311                        <xref target="CREATE FX_SEND">"CREATE FX_SEND"</xref>
3312                        or <xref target="LIST FX_SENDS">"LIST FX_SENDS"</xref> command.</t>
3313    
3314                        <t>Possible Answers:</t>
3315                        <t>
3316                            <list>
3317                                <t>"OK" -
3318                                    <list>
3319                                        <t>on success</t>
3320                                    </list>
3321                                </t>
3322                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
3323                                    <list>
3324                                        <t>in case it failed, providing an appropriate error code and
3325                                        error message</t>
3326                                    </list>
3327                                </t>
3328                            </list>
3329                        </t>
3330    
3331                        <t>Example:</t>
3332                        <t>
3333                            <list>
3334                                <t>C: "DESTROY FX_SEND 0 0"</t>
3335                                <t>S: "OK"</t>
3336                            </list>
3337                        </t>
3338                    </section>
3339    
3340                    <section title="Getting amount of effect sends on a sampler channel" anchor="GET FX_SENDS">
3341                        <t>The front-end can ask for the amount of effect sends on a specific sampler channel
3342                        by sending the following command:</t>
3343                        <t>
3344                            <list>
3345                                <t>GET FX_SENDS &lt;sampler-channel&gt;</t>
3346                            </list>
3347                        </t>
3348                        <t>Where &lt;sampler-channel&gt; is the respective sampler channel
3349                        number as returned by the <xref target="ADD CHANNEL">"ADD CHANNEL"</xref>
3350                        or <xref target="LIST CHANNELS">"LIST CHANNELS"</xref> command.</t>
3351    
3352                        <t>Possible Answers:</t>
3353                        <t>
3354                            <list>
3355                                <t>The sampler will answer by returning the number of effect
3356                                sends on the given sampler channel.</t>
3357                            </list>
3358                        </t>
3359    
3360                        <t>Example:</t>
3361                        <t>
3362                            <list>
3363                                <t>C: "GET FX_SENDS 0"</t>
3364                                <t>S: "2"</t>
3365                            </list>
3366                        </t>
3367                    </section>
3368    
3369                    <section title="Listing all effect sends on a sampler channel" anchor="LIST FX_SENDS">
3370                        <t>The front-end can ask for a list of effect sends on a specific sampler channel
3371                        by sending the following command:</t>
3372                        <t>
3373                            <list>
3374                                <t>LIST 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 a comma separated list
3385                                with all effect sends' numerical IDs on the given sampler
3386                                channel.</t>
3387                            </list>
3388                        </t>
3389    
3390                        <t>Examples:</t>
3391                        <t>
3392                            <list>
3393                                <t>C: "LIST FX_SENDS 0"</t>
3394                                <t>S: "0,1"</t>
3395                            </list>
3396                        </t>
3397                        <t>
3398                            <list>
3399                                <t>C: "LIST FX_SENDS 1"</t>
3400                                <t>S: ""</t>
3401                            </list>
3402                        </t>
3403                    </section>
3404    
3405                    <section title="Getting effect send information" anchor="GET FX_SEND INFO">
3406                        <t>The front-end can ask for the current settings of an effect send entity
3407                        by sending the following command:</t>
3408                        <t>
3409                            <list>
3410                                <t>GET FX_SEND INFO &lt;sampler-channel&gt; &lt;fx-send-id&gt;</t>
3411                            </list>
3412                        </t>
3413                        <t>Where &lt;sampler-channel&gt; is the sampler channel number
3414                        as returned by the <xref target="ADD CHANNEL">"ADD CHANNEL"</xref>
3415                        or <xref target="LIST CHANNELS">"LIST CHANNELS"</xref> command and
3416                        &lt;fx-send-id&gt; reflects the numerical ID of the effect send entity
3417                        as returned by the <xref target="CREATE FX_SEND">"CREATE FX_SEND"</xref>
3418                        or <xref target="LIST FX_SENDS">"LIST FX_SENDS"</xref> command.
3419                       </t>
3420    
3421                        <t>Possible Answers:</t>
3422                        <t>
3423                            <list>
3424                                <t>The sampler will answer by sending a &lt;CRLF&gt; separated list.
3425                                Each answer line begins with the settings category name
3426                                followed by a colon and then a space character &lt;SP&gt; and finally
3427                                the info character string to that setting category. At the
3428                                moment the following categories are defined:</t>
3429    
3430                                <t>
3431                                    <list>
3432                                        <t>NAME -
3433                                            <list>
3434                                                <t>name of the effect send entity</t>
3435                                            </list>
3436                                        </t>
3437                                        <t>MIDI_CONTROLLER -
3438                                            <list>
3439                                                <t>a value between 0 and 127 reflecting the MIDI controller
3440                                                which is able to modify the effect send's send level</t>
3441                                            </list>
3442                                        </t>
3443                                        <t>LEVEL -
3444                                            <list>
3445                                                <t>optionally dotted number reflecting the effect send's
3446                                                current send level (where a value &lt; 1.0 means attenuation
3447                                                and a value > 1.0 means amplification)</t>
3448                                            </list>
3449                                        </t>
3450                                        <t>AUDIO_OUTPUT_ROUTING -
3451                                            <list>
3452                                                <t>comma separated list which reflects to which audio
3453                                                channel of the selected audio output device each
3454                                                effect send output channel is routed to, e.g. "0,3" would
3455                                                mean the effect send's output channel 0 is routed to channel
3456                                                0 of the audio output device and the effect send's output
3457                                                channel 1 is routed to the channel 3 of the audio
3458                                                output device (see
3459                                                <xref target="SET FX_SEND AUDIO_OUTPUT_CHANNEL">"SET FX_SEND AUDIO_OUTPUT_CHANNEL"</xref>
3460                                                for details)</t>
3461                                            </list>
3462                                        </t>
3463                                    </list>
3464                                </t>
3465                            </list>
3466                        </t>
3467                        <t>The mentioned fields above don't have to be in particular order.</t>
3468    
3469                        <t>Example:</t>
3470                        <t>
3471                            <list>
3472                                <t>C: "GET FX_SEND INFO 0 0"</t>
3473                                <t>S: "NAME: Reverb Send"</t>
3474                                <t>&nbsp;&nbsp;&nbsp;"MIDI_CONTROLLER: 91"</t>
3475                                <t>&nbsp;&nbsp;&nbsp;"LEVEL: 0.3"</t>
3476                                <t>&nbsp;&nbsp;&nbsp;"AUDIO_OUTPUT_ROUTING: 2,3"</t>
3477                                <t>&nbsp;&nbsp;&nbsp;"."</t>
3478                            </list>
3479                        </t>
3480                    </section>
3481    
3482                    <section title="Changing effect send's name" anchor="SET FX_SEND NAME">
3483                        <t>The front-end can alter the current name of an effect
3484                        send entity by sending the following command:</t>
3485                        <t>
3486                            <list>
3487                                <t>SET FX_SEND NAME &lt;sampler-chan&gt; &lt;fx-send-id&gt; &lt;name&gt;</t>
3488                            </list>
3489                        </t>
3490                        <t>Where &lt;sampler-chan&gt; is the sampler channel number
3491                        as returned by the <xref target="ADD CHANNEL">"ADD CHANNEL"</xref>
3492                        or <xref target="LIST CHANNELS">"LIST CHANNELS"</xref> command,
3493                        &lt;fx-send-id&gt; reflects the numerical ID of the effect send entity
3494                        as returned by the <xref target="CREATE FX_SEND">"CREATE FX_SEND"</xref>
3495                        or <xref target="LIST FX_SENDS">"LIST FX_SENDS"</xref> command and
3496                        &lt;name&gt; is the new name of the effect send entity, which
3497                        does not have to be unique.</t>
3498    
3499                        <t>Possible Answers:</t>
3500                        <t>
3501                            <list>
3502                                <t>"OK" -
3503                                    <list>
3504                                        <t>on success</t>
3505                                    </list>
3506                                </t>
3507                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
3508                                    <list>
3509                                        <t>in case it failed, providing an appropriate error code and error message</t>
3510                                    </list>
3511                                </t>
3512                            </list>
3513                        </t>
3514                        <t>Example:</t>
3515                        <t>
3516                            <list>
3517                                <t>C: "SET FX_SEND NAME 0 0 'Fx Send 1'"</t>
3518                                <t>S: "OK"</t>
3519                            </list>
3520                        </t>
3521                    </section>
3522    
3523                    <section title="Altering effect send's audio routing" anchor="SET FX_SEND AUDIO_OUTPUT_CHANNEL">
3524                        <t>The front-end can alter the destination of an effect send's audio channel on a specific
3525                        sampler channel by sending the following command:</t>
3526                        <t>
3527                            <list>
3528                                <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>
3529                            </list>
3530                        </t>
3531                        <t>Where &lt;sampler-chan&gt; is the sampler channel number
3532                        as returned by the <xref target="ADD CHANNEL">"ADD CHANNEL"</xref>
3533                        or <xref target="LIST CHANNELS">"LIST CHANNELS"</xref> command,
3534                        &lt;fx-send-id&gt; reflects the numerical ID of the effect send entity
3535                        as returned by the <xref target="CREATE FX_SEND">"CREATE FX_SEND"</xref>
3536                        or <xref target="LIST FX_SENDS">"LIST FX_SENDS"</xref> command,
3537                        &lt;audio-src&gt; is the numerical ID of the effect send's audio channel
3538                        which should be rerouted and &lt;audio-dst&gt; is the numerical ID of
3539                        the audio channel of the selected audio output device where &lt;audio-src&gt;
3540                        should be routed to.</t>
3541    
3542                        <t>Note that effect sends can only route audio to the same audio output
3543                        device as assigned to the effect send's sampler channel. Also note that an
3544                        effect send entity does always have exactly as much audio channels as its
3545                        sampler channel. So if the sampler channel is stereo, the effect send does
3546                        have two audio channels as well. Also keep in mind that the amount of audio
3547                        channels on a sampler channel might be dependant not only to the deployed
3548                        sampler engine on the sampler channel, but also dependant to the instrument
3549                        currently loaded. However you can (effectively) turn an i.e. stereo effect
3550                        send into a mono one by simply altering its audio routing appropriately.</t>
3551    
3552                        <t>Possible Answers:</t>
3553                        <t>
3554                            <list>
3555                                <t>"OK" -
3556                                    <list>
3557                                        <t>on success</t>
3558                                    </list>
3559                                </t>
3560                                <t>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
3561                                    <list>
3562                                        <t>if audio output channel was set, but there are noteworthy
3563                                        issue(s) related, providing an appropriate warning code and
3564                                        warning message</t>
3565                                    </list>
3566                                </t>
3567                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
3568                                    <list>
3569                                        <t>in case it failed, providing an appropriate error code and error message</t>
3570                                    </list>
3571                                </t>
3572                            </list>
3573                        </t>
3574                        <t>Example:</t>
3575                        <t>
3576                            <list>
3577                                <t>C: "SET FX_SEND AUDIO_OUTPUT_CHANNEL 0 0 0 2"</t>
3578                                <t>S: "OK"</t>
3579                            </list>
3580                        </t>
3581                    </section>
3582    
3583                    <section title="Altering effect send's MIDI controller" anchor="SET FX_SEND MIDI_CONTROLLER">
3584                        <t>The front-end can alter the MIDI controller of an effect
3585                        send entity by sending the following command:</t>
3586                        <t>
3587                            <list>
3588                                <t>SET FX_SEND MIDI_CONTROLLER &lt;sampler-chan&gt; &lt;fx-send-id&gt; &lt;midi-ctrl&gt;</t>
3589                            </list>
3590                        </t>
3591                        <t>Where &lt;sampler-chan&gt; is the sampler channel number
3592                        as returned by the <xref target="ADD CHANNEL">"ADD CHANNEL"</xref>
3593                        or <xref target="LIST CHANNELS">"LIST CHANNELS"</xref> command,
3594                        &lt;fx-send-id&gt; reflects the numerical ID of the effect send entity
3595                        as returned by the <xref target="CREATE FX_SEND">"CREATE FX_SEND"</xref>
3596                        or <xref target="LIST FX_SENDS">"LIST FX_SENDS"</xref> command and
3597                        &lt;midi-ctrl&gt; reflects the MIDI controller which shall be
3598                        able to modify the effect send's send level.</t>
3599    
3600                        <t>Possible Answers:</t>
3601                        <t>
3602                            <list>
3603                                <t>"OK" -
3604                                    <list>
3605                                        <t>on success</t>
3606                                    </list>
3607                                </t>
3608                                <t>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
3609                                    <list>
3610                                        <t>if MIDI controller was set, but there are noteworthy
3611                                        issue(s) related, providing an appropriate warning code and
3612                                        warning message</t>
3613                                    </list>
3614                                </t>
3615                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
3616                                    <list>
3617                                        <t>in case it failed, providing an appropriate error code and error message</t>
3618                                    </list>
3619                                </t>
3620                            </list>
3621                        </t>
3622                        <t>Example:</t>
3623                        <t>
3624                            <list>
3625                                <t>C: "SET FX_SEND MIDI_CONTROLLER 0 0 91"</t>
3626                                <t>S: "OK"</t>
3627                            </list>
3628                        </t>
3629                    </section>
3630    
3631                    <section title="Altering effect send's send level" anchor="SET FX_SEND LEVEL">
3632                        <t>The front-end can alter the current send level of an effect
3633                        send entity by sending the following command:</t>
3634                        <t>
3635                            <list>
3636                                <t>SET FX_SEND LEVEL &lt;sampler-chan&gt; &lt;fx-send-id&gt; &lt;volume&gt;</t>
3637                            </list>
3638                        </t>
3639                        <t>Where &lt;sampler-chan&gt; is the sampler channel number
3640                        as returned by the <xref target="ADD CHANNEL">"ADD CHANNEL"</xref>
3641                        or <xref target="LIST CHANNELS">"LIST CHANNELS"</xref> command,
3642                        &lt;fx-send-id&gt; reflects the numerical ID of the effect send entity
3643                        as returned by the <xref target="CREATE FX_SEND">"CREATE FX_SEND"</xref>
3644                        or <xref target="LIST FX_SENDS">"LIST FX_SENDS"</xref> command and
3645                        &lt;volume&gt; is an optionally dotted positive number (a value
3646                        smaller than 1.0 means attenuation, whereas a value greater than
3647                        1.0 means amplification) reflecting the new send level.</t>
3648    
3649                        <t>Possible Answers:</t>
3650                        <t>
3651                            <list>
3652                                <t>"OK" -
3653                                    <list>
3654                                        <t>on success</t>
3655                                    </list>
3656                                </t>
3657                                <t>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
3658                                    <list>
3659                                        <t>if new send level was set, but there are noteworthy
3660                                        issue(s) related, providing an appropriate warning code and
3661                                        warning message</t>
3662                                    </list>
3663                                </t>
3664                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
3665                                    <list>
3666                                        <t>in case it failed, providing an appropriate error code and error message</t>
3667                                    </list>
3668                                </t>
3669                            </list>
3670                        </t>
3671                        <t>Example:</t>
3672                        <t>
3673                            <list>
3674                                <t>C: "SET FX_SEND LEVEL 0 0 0.15"</t>
3675                                <t>S: "OK"</t>
3676                            </list>
3677                        </t>
3678                    </section>
3679    
3680                  <section title="Resetting a sampler channel" anchor="RESET CHANNEL">                  <section title="Resetting a sampler channel" anchor="RESET CHANNEL">
3681                      <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>
3682                      <t>                      <t>
# Line 3329  Schoenebeck'> Line 3862  Schoenebeck'>
3862              <section title="Global commands">              <section title="Global commands">
3863                  <t>The following commands have global impact on the sampler.</t>                  <t>The following commands have global impact on the sampler.</t>
3864    
3865                    <section title="Current number of active voices" anchor="GET TOTAL_VOICE_COUNT">
3866                        <t>The front-end can ask for the current number of active voices on
3867                        the sampler by sending the following command:</t>
3868                        <t>
3869                            <list>
3870                                <t>GET TOTAL_VOICE_COUNT</t>
3871                            </list>
3872                        </t>
3873    
3874                        <t>Possible Answers:</t>
3875                        <t>
3876                            <list>
3877                                <t>LinuxSampler will answer by returning the number of all active
3878                                voices on the sampler.</t>
3879                            </list>
3880                        </t>
3881                    </section>
3882    
3883                    <section title="Maximum amount of active voices" anchor="GET TOTAL_VOICE_COUNT_MAX">
3884                        <t>The front-end can ask for the maximum number of active voices
3885                        by sending the following command:</t>
3886                        <t>
3887                            <list>
3888                                <t>GET TOTAL_VOICE_COUNT_MAX</t>
3889                            </list>
3890                        </t>
3891    
3892                        <t>Possible Answers:</t>
3893                        <t>
3894                            <list>
3895                                <t>LinuxSampler will answer by returning the maximum number
3896                                of active voices.</t>
3897                            </list>
3898                        </t>
3899                    </section>
3900    
3901                  <section title="Reset sampler" anchor="RESET">                  <section title="Reset sampler" anchor="RESET">
3902                      <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>
3903                      <t>                      <t>
# Line 3397  Schoenebeck'> Line 3966  Schoenebeck'>
3966                      <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.
3967                      Other fields might be added in future.</t>                      Other fields might be added in future.</t>
3968                  </section>                  </section>
3969    
3970                    <section title="Getting global volume attenuation" anchor="GET VOLUME">
3971                        <t>The client can ask for the current global sampler-wide volume
3972                        attenuation by sending the following command:</t>
3973                        <t>
3974                            <list>
3975                                <t>GET VOLUME</t>
3976                            </list>
3977                        </t>
3978                        <t>Possible Answers:</t>
3979                        <t>
3980                            <list>
3981                                <t>The sampler will always answer by returning the optional
3982                                dotted floating point coefficient, reflecting the current
3983                                global volume attenuation.
3984                                </t>
3985                            </list>
3986                        </t>
3987                        <t>Note: it is up to the respective sampler engine whether to obey
3988                        that global volume parameter or not, but in general all engines SHOULD
3989                        use this parameter.</t>
3990                    </section>
3991    
3992                    <section title="Setting global volume attenuation" anchor="SET VOLUME">
3993                        <t>The client can alter the current global sampler-wide volume
3994                        attenuation by sending the following command:</t>
3995                        <t>
3996                            <list>
3997                                <t>SET VOLUME &lt;volume&gt;</t>
3998                            </list>
3999                        </t>
4000                       <t>Where &lt;volume&gt; should be replaced by the optional dotted
4001                       floating point value, reflecting the new global volume parameter.
4002                       This value might usually be in the range between 0.0 and 1.0, that
4003                       is for attenuating the overall volume.</t>
4004    
4005                        <t>Possible Answers:</t>
4006                        <t>
4007                            <list>
4008                                <t>"OK" -
4009                                    <list>
4010                                        <t>on success</t>
4011                                    </list>
4012                                </t>
4013                                <t>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
4014                                    <list>
4015                                        <t>if the global volume was set, but there are noteworthy
4016                                        issue(s) related, providing an appropriate warning code and
4017                                        warning message</t>
4018                                    </list>
4019                                </t>
4020                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
4021                                    <list>
4022                                        <t>in case it failed, providing an appropriate error code and error message</t>
4023                                    </list>
4024                                </t>
4025                            </list>
4026                        </t>
4027                    </section>
4028                </section>
4029    
4030    
4031                <section title="MIDI Instrument Mapping" anchor="MIDI Instrument Mapping">
4032                    <t>The MIDI protocol provides a way to switch between instruments
4033                    by sending so called MIDI bank select and MIDI program change
4034                    messages which are essentially just numbers. The following commands
4035                    allow to actually map arbitrary MIDI bank select / program change
4036                    numbers with real instruments.</t>
4037                    <t>The sampler allows to manage an arbitrary amount of MIDI
4038                    instrument maps which define which instrument to load on
4039                    which MIDI program change message.</t>
4040                    <t>By default, that is when the sampler is launched, there is no
4041                    map, thus the sampler will simply ignore all program change
4042                    messages. The front-end has to explicitly create at least one
4043                    map, add entries to the map and tell the respective sampler
4044                    channel(s) which MIDI instrument map to use, so the sampler
4045                    knows how to react on a given program change message on the
4046                    respective sampler channel, that is by switching to the
4047                    respectively defined engine type and loading the respective
4048                    instrument. See command
4049                    <xref target="SET CHANNEL MIDI_INSTRUMENT_MAP">"SET CHANNEL MIDI_INSTRUMENT_MAP"</xref>
4050                    for how to assign a MIDI instrument map to a sampler channel.</t>
4051                    <t>Also note per MIDI specification a bank select message does not
4052                    cause to switch to another instrument. Instead when receiving a
4053                    bank select message the bank value will be stored and a subsequent
4054                    program change message (which may occur at any time) will finally
4055                    cause the sampler to switch to the respective instrument as
4056                    reflected by the current MIDI instrument map.</t>
4057    
4058                    <section title="Create a new MIDI instrument map" anchor="ADD MIDI_INSTRUMENT MAP">
4059                        <t>The front-end can add a new MIDI instrument map by sending
4060                        the following command:</t>
4061                        <t>
4062                            <list>
4063                                <t>ADD MIDI_INSTRUMENT_MAP [&lt;name&gt;]</t>
4064                            </list>
4065                        </t>
4066                        <t>Where &lt;name&gt; is an optional argument allowing to
4067                        assign a custom name to the new map. MIDI instrument Map
4068                        names do not have to be unique.</t>
4069    
4070                        <t>Possible Answers:</t>
4071                        <t>
4072                            <list>
4073                                <t>"OK[&lt;map&gt;]" -
4074                                    <list>
4075                                        <t>in case a new MIDI instrument map could
4076                                        be added, where &lt;map&gt; reflects the
4077                                        unique ID of the newly created MIDI
4078                                        instrument map</t>
4079                                    </list>
4080                                </t>
4081                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
4082                                    <list>
4083                                        <t>when a new map could not be created, which
4084                                        might never occur in practice</t>
4085                                    </list>
4086                                </t>
4087                            </list>
4088                        </t>
4089    
4090                        <t>Examples:</t>
4091                        <t>
4092                            <list>
4093                                <t>C: "ADD MIDI_INSTRUMENT_MAP 'Standard Map'"</t>
4094                                <t>S: "OK[0]"</t>
4095                            </list>
4096                        </t>
4097                        <t>
4098                            <list>
4099                                <t>C: "ADD MIDI_INSTRUMENT_MAP 'Standard Drumkit'"</t>
4100                                <t>S: "OK[1]"</t>
4101                            </list>
4102                        </t>
4103                        <t>
4104                            <list>
4105                                <t>C: "ADD MIDI_INSTRUMENT_MAP"</t>
4106                                <t>S: "OK[5]"</t>
4107                            </list>
4108                        </t>
4109                    </section>
4110    
4111                    <section title="Delete one particular or all MIDI instrument maps" anchor="REMOVE MIDI_INSTRUMENT_MAP">
4112                        <t>The front-end can delete a particular MIDI instrument map
4113                        by sending the following command:</t>
4114                        <t>
4115                            <list>
4116                                <t>REMOVE MIDI_INSTRUMENT_MAP &lt;map&gt;</t>
4117                            </list>
4118                        </t>
4119                        <t>Where &lt;map&gt; reflects the unique ID of the map to delete
4120                        as returned by the <xref target="LIST MIDI_INSTRUMENT_MAPS">"LIST MIDI_INSTRUMENT_MAPS"</xref>
4121                        command.</t>
4122                        <t>The front-end can delete all MIDI instrument maps by
4123                        sending the following command:</t>
4124                        <t>
4125                            <list>
4126                                <t>REMOVE MIDI_INSTRUMENT_MAP ALL</t>
4127                            </list>
4128                        </t>
4129    
4130                        <t>Possible Answers:</t>
4131                        <t>
4132                            <list>
4133                                <t>"OK" -
4134                                    <list>
4135                                        <t>in case the map(s) could be deleted</t>
4136                                    </list>
4137                                </t>
4138                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
4139                                    <list>
4140                                        <t>when the given map does not exist</t>
4141                                    </list>
4142                                </t>
4143                            </list>
4144                        </t>
4145    
4146                        <t>Examples:</t>
4147                        <t>
4148                            <list>
4149                                <t>C: "REMOVE MIDI_INSTRUMENT_MAP 0"</t>
4150                                <t>S: "OK"</t>
4151                            </list>
4152                        </t>
4153                        <t>
4154                            <list>
4155                                <t>C: "REMOVE MIDI_INSTRUMENT_MAP ALL"</t>
4156                                <t>S: "OK"</t>
4157                            </list>
4158                        </t>
4159                    </section>
4160    
4161                    <section title="Get amount of existing MIDI instrument maps" anchor="GET MIDI_INSTRUMENT_MAPS">
4162                        <t>The front-end can retrieve the current amount of MIDI
4163                        instrument maps by sending the following command:</t>
4164                        <t>
4165                            <list>
4166                                <t>GET MIDI_INSTRUMENT_MAPS</t>
4167                            </list>
4168                        </t>
4169    
4170                        <t>Possible Answers:</t>
4171                        <t>
4172                            <list>
4173                                <t>The sampler will answer by returning the current
4174                                number of MIDI instrument maps.</t>
4175                            </list>
4176                        </t>
4177    
4178                        <t>Example:</t>
4179                        <t>
4180                            <list>
4181                                <t>C: "GET MIDI_INSTRUMENT_MAPS"</t>
4182                                <t>S: "2"</t>
4183                            </list>
4184                        </t>
4185                    </section>
4186    
4187                    <section title="Getting all created MIDI instrument maps" anchor="LIST MIDI_INSTRUMENT_MAPS">
4188                        <t>The number of MIDI instrument maps can change on runtime. To get the
4189                        current list of MIDI instrument maps, the front-end can send the
4190                        following command:</t>
4191                        <t>
4192                            <list>
4193                                <t>LIST MIDI_INSTRUMENT_MAPS</t>
4194                            </list>
4195                        </t>
4196                        <t>Possible Answers:</t>
4197                        <t>
4198                            <list>
4199                                <t>The sampler will answer by returning a comma separated list
4200                                with all MIDI instrument maps' numerical IDs.</t>
4201                            </list>
4202                        </t>
4203                        <t>Example:</t>
4204                        <t>
4205                            <list>
4206                                <t>C: "LIST MIDI_INSTRUMENT_MAPS"</t>
4207                                <t>S: "0,1,5,12"</t>
4208                            </list>
4209                        </t>
4210                    </section>
4211    
4212                    <section title="Getting MIDI instrument map information" anchor="GET MIDI_INSTRUMENT_MAP INFO">
4213                        <t>The front-end can ask for the current settings of a MIDI
4214                        instrument map by sending the following command:</t>
4215                        <t>
4216                            <list>
4217                                <t>GET MIDI_INSTRUMENT_MAP INFO &lt;map&gt;</t>
4218                            </list>
4219                        </t>
4220                        <t>Where &lt;map&gt; is the numerical ID of the map the
4221                        front-end is interested in as returned by the
4222                        <xref target="LIST MIDI_INSTRUMENT_MAPS">"LIST MIDI_INSTRUMENT_MAPS"</xref>
4223                        command.</t>
4224    
4225                        <t>Possible Answers:</t>
4226                        <t>
4227                            <list>
4228                                <t>LinuxSampler will answer by sending a &lt;CRLF&gt; separated list.
4229                                Each answer line begins with the settings category name
4230                                followed by a colon and then a space character &lt;SP&gt; and finally
4231                                the info character string to that setting category. At the
4232                                moment the following categories are defined:</t>
4233    
4234                                <t>
4235                                    <list>
4236                                        <t>NAME -
4237                                            <list>
4238                                                <t>custom name of the given map,
4239                                                which does not have to be unique</t>
4240                                            </list>
4241                                        </t>
4242                                        <t>DEFAULT -
4243                                            <list>
4244                                                <t>either true or false,
4245                                                defines whether this map is the default map</t>
4246                                            </list>
4247                                        </t>
4248                                    </list>
4249                                </t>
4250                            </list>
4251                        </t>
4252                        <t>The mentioned fields above don't have to be in particular order.</t>
4253    
4254                        <t>Example:</t>
4255                        <t>
4256                            <list>
4257                                <t>C: "GET MIDI_INSTRUMENT_MAP INFO 0"</t>
4258                                <t>S: "NAME: Standard Map"</t>
4259                                <t>&nbsp;&nbsp;&nbsp;"."</t>
4260                            </list>
4261                        </t>
4262                    </section>
4263    
4264                    <section title="Renaming a MIDI instrument map" anchor="SET MIDI_INSTRUMENT_MAP NAME">
4265                        <t>The front-end can alter the custom name of a MIDI
4266                        instrument map by sending the following command:</t>
4267                        <t>
4268                            <list>
4269                                <t>SET MIDI_INSTRUMENT_MAP NAME &lt;map&gt; &lt;name&gt;</t>
4270                            </list>
4271                        </t>
4272                        <t>Where &lt;map&gt; is the numerical ID of the map and
4273                        &lt;name&gt; the new custom name of the map, which does not
4274                        have to be unique.</t>
4275    
4276                        <t>Possible Answers:</t>
4277                        <t>
4278                            <list>
4279                                <t>"OK" -
4280                                    <list>
4281                                        <t>on success</t>
4282                                    </list>
4283                                </t>
4284                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
4285                                    <list>
4286                                        <t>in case the given map does not exist</t>
4287                                    </list>
4288                                </t>
4289                            </list>
4290                        </t>
4291    
4292                        <t>Example:</t>
4293                        <t>
4294                            <list>
4295                                <t>C: "SET MIDI_INSTRUMENT_MAP NAME 0 'Foo instruments'"</t>
4296                                <t>S: "OK"</t>
4297                            </list>
4298                        </t>
4299                    </section>
4300    
4301                    <section title="Create or replace a MIDI instrument map entry" anchor="MAP MIDI_INSTRUMENT">
4302                        <t>The front-end can create a new or replace an existing entry
4303                        in a sampler's MIDI instrument map by sending the following
4304                        command:</t>
4305                        <t>
4306                            <list>
4307                                <t>MAP MIDI_INSTRUMENT [NON_MODAL] &lt;map&gt;
4308                                &lt;midi_bank&gt; &lt;midi_prog&gt; &lt;engine_name&gt;
4309                                &lt;filename&gt; &lt;instrument_index&gt; &lt;volume_value&gt;
4310                                [&lt;instr_load_mode&gt;] [&lt;name&gt;]</t>
4311                            </list>
4312                        </t>
4313                        <t>Where &lt;map&gt; is the numeric ID of the map to alter,
4314                        &lt;midi_bank&gt; is an integer value between
4315                        0..16383 reflecting the MIDI bank select index,
4316                        &lt;midi_prog&gt; an
4317                        integer value between 0..127 reflecting the MIDI program change
4318                        index, &lt;engine_name&gt; a sampler engine name as returned by
4319                        the <xref target="LIST AVAILABLE_ENGINES">"LIST AVAILABLE_ENGINES"</xref>
4320                        command (not encapsulated into apostrophes), &lt;filename&gt; the name
4321                        of the instrument's file to be deployed (encapsulated into apostrophes),
4322                        &lt;instrument_index&gt; the index (integer value) of the instrument
4323                        within the given file, &lt;volume_value&gt; reflects the master
4324                        volume of the instrument as optionally dotted number (where a
4325                        value &lt; 1.0 means attenuation and a value > 1.0 means
4326                        amplification). This parameter easily allows to adjust the
4327                        volume of all intruments within a custom instrument map
4328                        without having to adjust their instrument files. The
4329                        OPTIONAL &lt;instr_load_mode&gt; argument defines the life
4330                        time of the instrument, that is when the instrument should
4331                        be loaded, when freed and has exactly the following
4332                        possibilities:</t>
4333                        <t>
4334                            <list>
4335                                <t>"ON_DEMAND" -
4336                                    <list>
4337                                        <t>The instrument will be loaded when needed,
4338                                        that is when demanded by at least one sampler
4339                                        channel. It will immediately be freed from memory
4340                                        when not needed by any sampler channel anymore.</t>
4341                                    </list>
4342                                </t>
4343                                <t>"ON_DEMAND_HOLD" -
4344                                    <list>
4345                                        <t>The instrument will be loaded when needed,
4346                                        that is when demanded by at least one sampler
4347                                        channel. It will be kept in memory even when
4348                                        not needed by any sampler channel anymore.
4349                                        Instruments with this mode are only freed
4350                                        when the sampler is reset or all mapping
4351                                        entries with this mode (and respective
4352                                        instrument) are explicitly changed to
4353                                        "ON_DEMAND" and no sampler channel is using
4354                                        the instrument anymore.</t>
4355                                    </list>
4356                                </t>
4357                                <t>"PERSISTENT" -
4358                                    <list>
4359                                        <t>The instrument will immediately be loaded
4360                                        into memory when this mapping
4361                                        command is sent and the instrument is kept all
4362                                        the time. Instruments with this mode are
4363                                        only freed when the sampler is reset or all
4364                                        mapping entries with this mode (and
4365                                        respective instrument) are explicitly
4366                                        changed to "ON_DEMAND" and no sampler
4367                                        channel is using the instrument anymore.</t>
4368                                    </list>
4369                                </t>
4370                                <t>not supplied -
4371                                    <list>
4372                                        <t>In case there is no &lt;instr_load_mode&gt;
4373                                        argument given, it will be up to the
4374                                        InstrumentManager to decide which mode to use.
4375                                        Usually it will use "ON_DEMAND" if an entry
4376                                        for the given instrument does not exist in
4377                                        the InstrumentManager's list yet, otherwise
4378                                        if an entry already exists, it will simply
4379                                        stick with the mode currently reflected by
4380                                        the already existing entry, that is it will
4381                                        not change the mode.</t>
4382                                    </list>
4383                                </t>
4384                            </list>
4385                        </t>
4386                        <t>
4387                        The &lt;instr_load_mode&gt; argument thus allows to define an
4388                        appropriate strategy (low memory consumption vs. fast
4389                        instrument switching) for each instrument individually. Note, the
4390                        following restrictions apply to this argument: "ON_DEMAND_HOLD" and
4391                        "PERSISTENT" have to be supported by the respective sampler engine
4392                        (which is technically the case when the engine provides an
4393                        InstrumentManager for its format). If this is not the case the
4394                        argument will automatically fall back to the default value
4395                        "ON_DEMAND". Also the load mode of one instrument may
4396                        automatically change the laod mode of other instrument(s), i.e.
4397                        because the instruments are part of the same file and the
4398                        engine does not allow a way to manage load modes for them
4399                        individually. Due to this, in case the frontend shows the
4400                        load modes of entries, the frontend should retrieve the actual
4401                        mode by i.e. sending
4402                        <xref target="GET MIDI_INSTRUMENT INFO">"GET MIDI_INSTRUMENT INFO"</xref>
4403                        command(s). Finally the OPTIONAL &lt;name&gt; argument allows to
4404                        set a custom name (encapsulated into apostrophes) for the mapping
4405                        entry, useful for frontends for displaying an appropriate name for
4406                        mapped instruments (using
4407                        <xref target="GET MIDI_INSTRUMENT INFO">"GET MIDI_INSTRUMENT INFO"</xref>).
4408                        </t>
4409                        <t>
4410                        By default, "MAP MIDI_INSTRUMENT" commands block until the mapping is
4411                        completely established in the sampler. The OPTIONAL "NON_MODAL" argument
4412                        however causes the respective "MAP MIDI_INSTRUMENT" command to return
4413                        immediately, that is to let the sampler establish the mapping in the
4414                        background. So this argument might be especially useful for mappings with
4415                        a "PERSISTENT" type, because these have to load the respective instruments
4416                        immediately and might thus block for a very long time. It is recommended
4417                        however to use the OPTIONAL "NON_MODAL" argument only if really necessary,
4418                        because it has the following drawbacks: as "NON_MODAL" instructions return
4419                        immediately, they may not necessarily return an error i.e. when the given
4420                        instrument file turns out to be corrupt, beside that subsequent commands
4421                        in a LSCP instruction sequence might fail, because mandatory mappings are
4422                        not yet completed.
4423                        </t>
4424    
4425                        <t>Possible Answers:</t>
4426                        <t>
4427                            <list>
4428                                <t>"OK" -
4429                                    <list>
4430                                        <t>usually</t>
4431                                    </list>
4432                                </t>
4433                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
4434                                    <list>
4435                                        <t>when the given map or engine does not exist or a value
4436                                        is out of range</t>
4437                                    </list>
4438                                </t>
4439                            </list>
4440                        </t>
4441    
4442                        <t>Examples:</t>
4443                        <t>
4444                            <list>
4445                                <t>C: "MAP MIDI_INSTRUMENT 0 3 0 gig '/usr/share/Steinway D.gig' 0 0.8 PERSISTENT"</t>
4446                                <t>S: "OK"</t>
4447                            </list>
4448                        </t>
4449                        <t>
4450                            <list>
4451                                <t>C: "MAP MIDI_INSTRUMENT 0 4 50 gig '/home/john/foostrings.gig' 7 1.0"</t>
4452                                <t>S: "OK"</t>
4453                            </list>
4454                        </t>
4455                        <t>
4456                            <list>
4457                                <t>C: "MAP MIDI_INSTRUMENT 0 0 0 gig '/usr/share/piano.gig' 0 1.0 'Normal Piano'"</t>
4458                                <t>S: "OK"</t>
4459                                <t>C: "MAP MIDI_INSTRUMENT 0 1 0 gig '/usr/share/piano.gig' 0 0.25 'Silent Piano'"</t>
4460                                <t>S: "OK"</t>
4461                            </list>
4462                        </t>
4463                        <t>
4464                            <list>
4465                                <t>C: "MAP MIDI_INSTRUMENT NON_MODAL 1 8 120 gig '/home/joe/foodrums.gig' 0 1.0 PERSISTENT 'Foo Drumkit'"</t>
4466                                <t>S: "OK"</t>
4467                            </list>
4468                        </t>
4469                    </section>
4470    
4471                    <section title="Getting ammount of MIDI instrument map entries" anchor="GET MIDI_INSTRUMENTS">
4472                        <t>The front-end can query the amount of currently existing
4473                        entries in a MIDI instrument map by sending the following
4474                        command:</t>
4475                        <t>
4476                            <list>
4477                                <t>GET MIDI_INSTRUMENTS &lt;map&gt;</t>
4478                            </list>
4479                        </t>
4480                        <t>The front-end can query the amount of currently existing
4481                        entries in all MIDI instrument maps by sending the following
4482                        command:</t>
4483                        <t>
4484                            <list>
4485                                <t>GET MIDI_INSTRUMENTS ALL</t>
4486                            </list>
4487                        </t>
4488                        <t>Possible Answers:</t>
4489                        <t>
4490                            <list>
4491                                <t>The sampler will answer by sending the current number of
4492                                entries in the MIDI instrument map(s).</t>
4493                            </list>
4494                        </t>
4495    
4496                        <t>Example:</t>
4497                        <t>
4498                            <list>
4499                                <t>C: "GET MIDI_INSTRUMENTS 0"</t>
4500                                <t>S: "234"</t>
4501                            </list>
4502                        </t>
4503                        <t>
4504                            <list>
4505                                <t>C: "GET MIDI_INSTRUMENTS ALL"</t>
4506                                <t>S: "954"</t>
4507                            </list>
4508                        </t>
4509                    </section>
4510    
4511                    <section title="Getting indeces of all entries of a MIDI instrument map" anchor="LIST MIDI_INSTRUMENTS">
4512                        <t>The front-end can query a list of all currently existing
4513                        entries in a certain MIDI instrument map by sending the following
4514                        command:</t>
4515                        <t>
4516                            <list>
4517                                <t>LIST MIDI_INSTRUMENTS &lt;map&gt;</t>
4518                            </list>
4519                        </t>
4520                        <t>Where &lt;map&gt; is the numeric ID of the MIDI instrument map.</t>
4521                        <t>The front-end can query a list of all currently existing
4522                        entries of all MIDI instrument maps by sending the following
4523                        command:</t>
4524                        <t>
4525                            <list>
4526                                <t>LIST MIDI_INSTRUMENTS ALL</t>
4527                            </list>
4528                        </t>
4529    
4530                        <t>Possible Answers:</t>
4531                        <t>
4532                            <list>
4533                                <t>The sampler will answer by sending a comma separated
4534                                list of map ID - MIDI bank - MIDI program triples, where
4535                                each triple is encapsulated into curly braces. The
4536                                list is returned in one single line. Each triple
4537                                just reflects the key of the respective map entry,
4538                                thus subsequent
4539                                <xref target="GET MIDI_INSTRUMENT INFO">"GET MIDI_INSTRUMENT INFO"</xref>
4540                                command(s) are necessary to retrieve detailed informations
4541                                about each entry.</t>
4542                            </list>
4543                        </t>
4544    
4545                        <t>Example:</t>
4546                        <t>
4547                            <list>
4548                                <t>C: "LIST MIDI_INSTRUMENTS 0"</t>
4549                                <t>S: "{0,0,0},{0,0,1},{0,0,3},{0,1,4},{1,127,127}"</t>
4550                            </list>
4551                        </t>
4552                    </section>
4553    
4554                    <section title="Remove an entry from the MIDI instrument map" anchor="UNMAP MIDI_INSTRUMENT">
4555                        <t>The front-end can delete an entry from a MIDI instrument
4556                        map by sending the following command:</t>
4557                        <t>
4558                            <list>
4559                                <t>UNMAP MIDI_INSTRUMENT &lt;map&gt; &lt;midi_bank&gt; &lt;midi_prog&gt;</t>
4560                            </list>
4561                        </t>
4562                        <t>
4563                        Where &lt;map&gt; is the numeric ID of the MIDI instrument map,
4564                        &lt;midi_bank&gt; is an integer value between 0..16383
4565                        reflecting the MIDI bank value and
4566                        &lt;midi_prog&gt; an integer value between
4567                        0..127 reflecting the MIDI program value of the map's entrie's key
4568                        index triple.
4569                        </t>
4570    
4571                        <t>Possible Answers:</t>
4572                        <t>
4573                            <list>
4574                                <t>"OK" -
4575                                    <list>
4576                                        <t>usually</t>
4577                                    </list>
4578                                </t>
4579                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
4580                                    <list>
4581                                        <t>when index out of bounds</t>
4582                                    </list>
4583                                </t>
4584                            </list>
4585                        </t>
4586    
4587                        <t>Example:</t>
4588                        <t>
4589                            <list>
4590                                <t>C: "UNMAP MIDI_INSTRUMENT 0 2 127"</t>
4591                                <t>S: "OK"</t>
4592                            </list>
4593                        </t>
4594                    </section>
4595    
4596                    <section title="Get current settings of MIDI instrument map entry" anchor="GET MIDI_INSTRUMENT INFO">
4597                        <t>The front-end can retrieve the current settings of a certain
4598                        instrument map entry by sending the following command:</t>
4599                        <t>
4600                            <list>
4601                                <t>GET MIDI_INSTRUMENT INFO &lt;map&gt; &lt;midi_bank&gt; &lt;midi_prog&gt;</t>
4602                            </list>
4603                        </t>
4604                        <t>
4605                        Where &lt;map&gt; is the numeric ID of the MIDI instrument map,
4606                        &lt;midi_bank&gt; is an integer value between 0..16383
4607                        reflecting the MIDI bank value, &lt;midi_bank&gt;
4608                        and &lt;midi_prog&gt; an integer value between
4609                        0..127 reflecting the MIDI program value of the map's entrie's key
4610                        index triple.
4611                        </t>
4612    
4613                        <t>Possible Answers:</t>
4614                        <t>
4615                            <list>
4616                                <t>LinuxSampler will answer by sending a &lt;CRLF&gt;
4617                                separated list. Each answer line begins with the
4618                                information category name followed by a colon and then
4619                                a space character &lt;SP&gt; and finally the info
4620                                character string to that info category. At the moment
4621                                the following categories are defined:</t>
4622                                <t>"NAME" -
4623                                    <list>
4624                                        <t>Name for this MIDI instrument map entry (if defined).
4625                                        This name shall be used by frontends for displaying a
4626                                        name for this mapped instrument. It can be set and
4627                                        changed with the
4628                                        <xref target="MAP MIDI_INSTRUMENT">"MAP MIDI_INSTRUMENT"</xref>
4629                                        command and does not have to be unique.</t>
4630                                    </list>
4631                                </t>
4632                                <t>"ENGINE_NAME" -
4633                                    <list>
4634                                        <t>Name of the engine to be deployed for this
4635                                        instrument.</t>
4636                                    </list>
4637                                </t>
4638                                <t>"INSTRUMENT_FILE" -
4639                                    <list>
4640                                        <t>File name of the instrument.</t>
4641                                    </list>
4642                                </t>
4643                                <t>"INSTRUMENT_NR" -
4644                                    <list>
4645                                        <t>Index of the instrument within the file.</t>
4646                                    </list>
4647                                </t>
4648                                <t>"INSTRUMENT_NAME" -
4649                                    <list>
4650                                        <t>Name of the loaded instrument as reflected by its file.
4651                                        In contrast to the "NAME" field, the "INSTRUMENT_NAME" field
4652                                        cannot be changed.</t>
4653                                    </list>
4654                                </t>
4655                                <t>"LOAD_MODE" -
4656                                    <list>
4657                                        <t>Life time of instrument
4658                                        (see <xref target="MAP MIDI_INSTRUMENT">"MAP MIDI_INSTRUMENT"</xref> for details about this setting).</t>
4659                                    </list>
4660                                </t>
4661                                <t>"VOLUME" -
4662                                    <list>
4663                                        <t>master volume of the instrument as optionally
4664                                        dotted number (where a value &lt; 1.0 means attenuation
4665                                        and a value > 1.0 means amplification)</t>
4666                                    </list>
4667                                </t>
4668                                <t>The mentioned fields above don't have to be in particular order.</t>
4669                            </list>
4670                        </t>
4671    
4672                        <t>Example:</t>
4673                        <t>
4674                            <list>
4675                                <t>C: "GET MIDI_INSTRUMENT INFO 1 45 120"</t>
4676                                <t>S: "NAME: Drums for Foo Song"</t>
4677                                <t>&nbsp;&nbsp;&nbsp;"ENGINE_NAME: GigEngine"</t>
4678                                <t>&nbsp;&nbsp;&nbsp;"INSTRUMENT_FILE: /usr/share/joesdrumkit.gig"</t>
4679                                <t>&nbsp;&nbsp;&nbsp;"INSTRUMENT_NR: 0"</t>
4680                                <t>&nbsp;&nbsp;&nbsp;"INSTRUMENT_NAME: Joe's Drumkit"</t>
4681                                <t>&nbsp;&nbsp;&nbsp;"LOAD_MODE: PERSISTENT"</t>
4682                                <t>&nbsp;&nbsp;&nbsp;"VOLUME: 1.0"</t>
4683                                <t>&nbsp;&nbsp;&nbsp;"."</t>
4684                            </list>
4685                        </t>
4686                    </section>
4687    
4688                    <section title="Clear MIDI instrument map" anchor="CLEAR MIDI_INSTRUMENTS">
4689                        <t>The front-end can clear a whole MIDI instrument map, that
4690                        is delete all its entries by sending the following command:</t>
4691                        <t>
4692                            <list>
4693                                <t>CLEAR MIDI_INSTRUMENTS &lt;map&gt;</t>
4694                            </list>
4695                        </t>
4696                        <t>Where &lt;map&gt; is the numeric ID of the map to clear.</t>
4697                        <t>The front-end can clear all MIDI instrument maps, that
4698                        is delete all entries of all maps by sending the following
4699                        command:</t>
4700                        <t>
4701                            <list>
4702                                <t>CLEAR MIDI_INSTRUMENTS ALL</t>
4703                            </list>
4704                        </t>
4705                        <t>The command "CLEAR MIDI_INSTRUMENTS ALL" does not delete the
4706                        maps, only their entries, thus the map's settings like
4707                        custom name will be preservevd.</t>
4708    
4709                       <t>Possible Answers:</t>
4710                        <t>
4711                            <list>
4712                                <t>"OK" -
4713                                    <list>
4714                                        <t>always</t>
4715                                    </list>
4716                                </t>
4717                            </list>
4718                        </t>
4719    
4720                        <t>Examples:</t>
4721                        <t>
4722                           <list>
4723                                <t>C: "CLEAR MIDI_INSTRUMENTS 0"</t>
4724                                <t>S: "OK"</t>
4725                            </list>
4726                        </t>
4727                        <t>
4728                           <list>
4729                                <t>C: "CLEAR MIDI_INSTRUMENTS ALL"</t>
4730                                <t>S: "OK"</t>
4731                            </list>
4732                        </t>
4733                    </section>
4734              </section>              </section>
4735    
4736          </section>          </section>
4737    
4738    
4739          <section title="Command Syntax" anchor="command_syntax">          <section title="Command Syntax" anchor="command_syntax">
4740              <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"/>
4741              is defined below using Backus-Naur Form (BNF as described in <xref target="RFC2234"/>)              is defined below using Backus-Naur Form (BNF as described in <xref target="RFC2234"/>)
# Line 3422  Schoenebeck'> Line 4758  Schoenebeck'>
4758  </t>  </t>
4759  <t>line =  <t>line =
4760          <list>          <list>
4761                  <t>/* epsilon (empty line ignored) */                  <t>/* epsilon (empty line ignored) */
4762                  </t>                  </t>
4763                  <t>/ comment                    <t>/ comment
4764                  </t>                  </t>
4765                  <t>/ command                    <t>/ command
4766                  </t>                  </t>
4767                  <t>/ error                      <t>/ error
4768                  </t>                  </t>
4769          </list>          </list>
4770  </t>  </t>
# Line 3448  Schoenebeck'> Line 4784  Schoenebeck'>
4784  </t>  </t>
4785  <t>command =  <t>command =
4786          <list>          <list>
4787                  <t>ADD SP CHANNEL                                          <t>ADD SP add_instruction
4788                    </t>
4789                    <t>/ MAP SP map_instruction
4790                    </t>
4791                    <t>/ UNMAP SP unmap_instruction
4792                    </t>
4793                    <t>/ GET SP get_instruction
4794                  </t>                  </t>
4795                  <t>/ GET SP get_instruction                                  <t>/ CREATE SP create_instruction
4796                  </t>                  </t>
4797                  <t>/ CREATE SP create_instruction                            <t>/ DESTROY SP destroy_instruction
4798                  </t>                  </t>
4799                  <t>/ DESTROY SP destroy_instruction                          <t>/ LIST SP list_instruction
4800                  </t>                  </t>
4801                  <t>/ LIST SP list_instruction                                <t>/ LOAD SP load_instruction
4802                  </t>                  </t>
4803                  <t>/ LOAD SP load_instruction                                <t>/ REMOVE SP remove_instruction
4804                  </t>                  </t>
4805                  <t>/ REMOVE SP CHANNEL SP sampler_channel                    <t>/ SET SP set_instruction
4806                  </t>                  </t>
4807                  <t>/ SET SP set_instruction                                  <t>/ SUBSCRIBE SP subscribe_event
4808                  </t>                  </t>
4809                  <t>/ SUBSCRIBE SP subscribe_event                            <t>/ UNSUBSCRIBE SP unsubscribe_event
4810                  </t>                  </t>
4811                  <t>/ UNSUBSCRIBE SP unsubscribe_event                        <t>/ SELECT SP text
4812                  </t>                  </t>
4813                  <t>/ SELECT SP text                                          <t>/ RESET SP reset_instruction
4814                  </t>                  </t>
4815                  <t>/ RESET SP CHANNEL SP sampler_channel                    <t>/ CLEAR SP clear_instruction
4816                  </t>                  </t>
4817                  <t>/ RESET                                                  <t>/ RESET
4818                  </t>                  </t>
4819                  <t>/ QUIT                                                    <t>/ QUIT
4820                    </t>
4821            </list>
4822    </t>
4823    <t>add_instruction =
4824            <list>
4825                    <t>CHANNEL
4826                    </t>
4827                    <t>/ MIDI_INSTRUMENT_MAP
4828                    </t>
4829                    <t>/ MIDI_INSTRUMENT_MAP SP map_name
4830                  </t>                  </t>
4831          </list>          </list>
4832  </t>  </t>
4833  <t>subscribe_event =  <t>subscribe_event =
4834          <list>          <list>
4835                  <t>CHANNEL_COUNT                                          <t>AUDIO_OUTPUT_DEVICE_COUNT
4836                    </t>
4837                    <t>/ AUDIO_OUTPUT_DEVICE_INFO
4838                    </t>
4839                    <t>/ MIDI_INPUT_DEVICE_COUNT
4840                    </t>
4841                    <t>/ MIDI_INPUT_DEVICE_INFO
4842                    </t>
4843                    <t>/ CHANNEL_COUNT
4844                    </t>
4845                    <t>/ VOICE_COUNT
4846                    </t>
4847                    <t>/ STREAM_COUNT
4848                  </t>                  </t>
4849                  <t>/ VOICE_COUNT                                            <t>/ BUFFER_FILL
4850                  </t>                  </t>
4851                  <t>/ STREAM_COUNT                                            <t>/ CHANNEL_INFO
4852                  </t>                  </t>
4853                  <t>/ BUFFER_FILL                                            <t>/ FX_SEND_COUNT
4854                  </t>                  </t>
4855                  <t>/ CHANNEL_INFO                                            <t>/ FX_SEND_INFO
4856                  </t>                  </t>
4857                  <t>/ MISCELLANEOUS                                          <t>/ MIDI_INSTRUMENT_MAP_COUNT
4858                    </t>
4859                    <t>/ MIDI_INSTRUMENT_MAP_INFO
4860                    </t>
4861                    <t>/ MIDI_INSTRUMENT_COUNT
4862                    </t>
4863                    <t>/ MIDI_INSTRUMENT_INFO
4864                    </t>
4865                    <t>/ MISCELLANEOUS
4866                    </t>
4867                    <t>/ TOTAL_VOICE_COUNT
4868                    </t>
4869                    <t>/ GLOBAL_INFO
4870                  </t>                  </t>
4871          </list>          </list>
4872  </t>  </t>
4873  <t>unsubscribe_event =  <t>unsubscribe_event =
4874          <list>          <list>
4875                  <t>CHANNEL_COUNT                                          <t>AUDIO_OUTPUT_DEVICE_COUNT
4876                    </t>
4877                    <t>/ AUDIO_OUTPUT_DEVICE_INFO
4878                    </t>
4879                    <t>/ MIDI_INPUT_DEVICE_COUNT
4880                    </t>
4881                    <t>/ MIDI_INPUT_DEVICE_INFO
4882                    </t>
4883                    <t>/ CHANNEL_COUNT
4884                    </t>
4885                    <t>/ VOICE_COUNT
4886                    </t>
4887                    <t>/ STREAM_COUNT
4888                    </t>
4889                    <t>/ BUFFER_FILL
4890                    </t>
4891                    <t>/ CHANNEL_INFO
4892                    </t>
4893                    <t>/ FX_SEND_COUNT
4894                    </t>
4895                    <t>/ FX_SEND_INFO
4896                    </t>
4897                    <t>/ MIDI_INSTRUMENT_MAP_COUNT
4898                    </t>
4899                    <t>/ MIDI_INSTRUMENT_MAP_INFO
4900                  </t>                  </t>
4901                  <t>/ VOICE_COUNT                                            <t>/ MIDI_INSTRUMENT_COUNT
4902                  </t>                  </t>
4903                  <t>/ STREAM_COUNT                                            <t>/ MIDI_INSTRUMENT_INFO
4904                  </t>                  </t>
4905                  <t>/ BUFFER_FILL                                            <t>/ MISCELLANEOUS
4906                    </t>
4907                    <t>/ TOTAL_VOICE_COUNT
4908                    </t>
4909                    <t>/ GLOBAL_INFO
4910                    </t>
4911            </list>
4912    </t>
4913    <t>map_instruction =
4914            <list>
4915                    <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
4916                    </t>
4917                    <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
4918                    </t>
4919                    <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
4920                    </t>
4921                    <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
4922                    </t>
4923            </list>
4924    </t>
4925    <t>unmap_instruction =
4926            <list>
4927                    <t>MIDI_INSTRUMENT SP midi_map SP midi_bank SP midi_prog
4928                    </t>
4929            </list>
4930    </t>
4931    <t>remove_instruction =
4932            <list>
4933                    <t>CHANNEL SP sampler_channel
4934                  </t>                  </t>
4935                  <t>/ CHANNEL_INFO                                            <t>/ MIDI_INSTRUMENT_MAP SP midi_map
4936                  </t>                  </t>
4937                  <t>/ MISCELLANEOUS                                          <t>/ MIDI_INSTRUMENT_MAP SP ALL
4938                  </t>                  </t>
4939          </list>          </list>
4940  </t>  </t>
4941  <t>get_instruction =  <t>get_instruction =
4942          <list>          <list>
4943                  <t>AVAILABLE_ENGINES                                                                            <t>AVAILABLE_ENGINES
4944                  </t>                  </t>
4945                  <t>/ AVAILABLE_MIDI_INPUT_DRIVERS                                                                <t>/ AVAILABLE_MIDI_INPUT_DRIVERS
4946                  </t>                  </t>
4947                  <t>/ MIDI_INPUT_DRIVER SP INFO SP string                                                          <t>/ MIDI_INPUT_DRIVER SP INFO SP string
4948                  </t>                  </t>
4949                  <t>/ MIDI_INPUT_DRIVER_PARAMETER SP INFO SP string SP string                                      <t>/ MIDI_INPUT_DRIVER_PARAMETER SP INFO SP string SP string
4950                  </t>                  </t>
4951                  <t>/ MIDI_INPUT_DRIVER_PARAMETER SP INFO SP string SP string SP key_val_list                      <t>/ MIDI_INPUT_DRIVER_PARAMETER SP INFO SP string SP string SP key_val_list
4952                  </t>                  </t>
4953                  <t>/ AVAILABLE_AUDIO_OUTPUT_DRIVERS                                                              <t>/ AVAILABLE_AUDIO_OUTPUT_DRIVERS
4954                  </t>                  </t>
4955                  <t>/ AUDIO_OUTPUT_DRIVER SP INFO SP string                                                        <t>/ AUDIO_OUTPUT_DRIVER SP INFO SP string
4956                  </t>                  </t>
4957                  <t>/ AUDIO_OUTPUT_DRIVER_PARAMETER SP INFO SP string SP string                                    <t>/ AUDIO_OUTPUT_DRIVER_PARAMETER SP INFO SP string SP string
4958                  </t>                  </t>
4959                  <t>/ AUDIO_OUTPUT_DRIVER_PARAMETER SP INFO SP string SP string SP key_val_list                    <t>/ AUDIO_OUTPUT_DRIVER_PARAMETER SP INFO SP string SP string SP key_val_list
4960                  </t>                  </t>
4961                  <t>/ AUDIO_OUTPUT_DEVICES                                                                        <t>/ AUDIO_OUTPUT_DEVICES
4962                  </t>                  </t>
4963                  <t>/ MIDI_INPUT_DEVICES                                                                          <t>/ MIDI_INPUT_DEVICES
4964                  </t>                  </t>
4965                  <t>/ AUDIO_OUTPUT_DEVICE SP INFO SP number                                                        <t>/ AUDIO_OUTPUT_DEVICE SP INFO SP number
4966                  </t>                  </t>
4967                  <t>/ MIDI_INPUT_DEVICE SP INFO SP number                                                          <t>/ MIDI_INPUT_DEVICE SP INFO SP number
4968                  </t>                  </t>
4969                  <t>/ MIDI_INPUT_PORT SP INFO SP number SP number                                                  <t>/ MIDI_INPUT_PORT SP INFO SP number SP number
4970                  </t>                  </t>
4971                  <t>/ MIDI_INPUT_PORT_PARAMETER SP INFO SP number SP number SP string                              <t>/ MIDI_INPUT_PORT_PARAMETER SP INFO SP number SP number SP string
4972                  </t>                  </t>
4973                  <t>/ AUDIO_OUTPUT_CHANNEL SP INFO SP number SP number                                            <t>/ AUDIO_OUTPUT_CHANNEL SP INFO SP number SP number
4974                  </t>                  </t>
4975                  <t>/ AUDIO_OUTPUT_CHANNEL_PARAMETER SP INFO SP number SP number SP string                        <t>/ AUDIO_OUTPUT_CHANNEL_PARAMETER SP INFO SP number SP number SP string
4976                  </t>                  </t>
4977                  <t>/ CHANNELS                                                                                    <t>/ CHANNELS
4978                  </t>                  </t>
4979                  <t>/ CHANNEL SP INFO SP sampler_channel                                                          <t>/ CHANNEL SP INFO SP sampler_channel
4980                  </t>                  </t>
4981                  <t>/ CHANNEL SP BUFFER_FILL SP buffer_size_type SP sampler_channel                                <t>/ CHANNEL SP BUFFER_FILL SP buffer_size_type SP sampler_channel
4982                  </t>                  </t>
4983                  <t>/ CHANNEL SP STREAM_COUNT SP sampler_channel                                                  <t>/ CHANNEL SP STREAM_COUNT SP sampler_channel
4984                  </t>                  </t>
4985                  <t>/ CHANNEL SP VOICE_COUNT SP sampler_channel                                                    <t>/ CHANNEL SP VOICE_COUNT SP sampler_channel
4986                  </t>                  </t>
4987                  <t>/ ENGINE SP INFO SP engine_name                                                                <t>/ ENGINE SP INFO SP engine_name
4988                  </t>                  </t>
4989                  <t>/ SERVER SP INFO                                                                              <t>/ SERVER SP INFO
4990                    </t>
4991                    <t>/ TOTAL_VOICE_COUNT
4992                    </t>
4993                    <t>/ TOTAL_VOICE_COUNT_MAX
4994                    </t>
4995                    <t>/ MIDI_INSTRUMENTS SP midi_map
4996                    </t>
4997                    <t>/ MIDI_INSTRUMENTS SP ALL
4998                    </t>
4999                    <t>/ MIDI_INSTRUMENT SP INFO SP midi_map SP midi_bank SP midi_prog
5000                    </t>
5001                    <t>/ MIDI_INSTRUMENT_MAPS
5002                    </t>
5003                    <t>/ MIDI_INSTRUMENT_MAP SP INFO SP midi_map
5004                    </t>
5005                    <t>/ FX_SENDS SP sampler_channel
5006                    </t>
5007                    <t>/ FX_SEND SP INFO SP sampler_channel SP fx_send_id
5008                    </t>
5009                    <t>/ VOLUME
5010                  </t>                  </t>
5011          </list>          </list>
5012  </t>  </t>
5013  <t>set_instruction =  <t>set_instruction =
5014          <list>          <list>
5015                  <t>AUDIO_OUTPUT_DEVICE_PARAMETER SP number SP string '=' param_val_list                              <t>AUDIO_OUTPUT_DEVICE_PARAMETER SP number SP string '=' param_val_list
5016                    </t>
5017                    <t>/ AUDIO_OUTPUT_CHANNEL_PARAMETER SP number SP number SP string '=' param_val_list
5018                    </t>
5019                    <t>/ MIDI_INPUT_DEVICE_PARAMETER SP number SP string '=' param_val_list
5020                    </t>
5021                    <t>/ MIDI_INPUT_PORT_PARAMETER SP number SP number SP string '=' param_val_list
5022                  </t>                  </t>
5023                  <t>/ AUDIO_OUTPUT_CHANNEL_PARAMETER SP number SP number SP string '=' param_val_list                    <t>/ CHANNEL SP set_chan_instruction
5024                  </t>                  </t>
5025                  <t>/ MIDI_INPUT_DEVICE_PARAMETER SP number SP string '=' param_val_list                                <t>/ MIDI_INSTRUMENT_MAP SP NAME SP midi_map SP map_name
5026                  </t>                  </t>
5027                  <t>/ MIDI_INPUT_PORT_PARAMETER SP number SP number SP string '=' param_val_list                        <t>/ FX_SEND SP NAME SP sampler_channel SP fx_send_id SP fx_send_name
5028                  </t>                  </t>
5029                  <t>/ CHANNEL SP set_chan_instruction                                                                    <t>/ FX_SEND SP AUDIO_OUTPUT_CHANNEL SP sampler_channel SP fx_send_id SP audio_channel_index SP audio_channel_index
5030                  </t>                  </t>
5031                  <t>/ ECHO SP boolean                                                                                    <t>/ FX_SEND SP MIDI_CONTROLLER SP sampler_channel SP fx_send_id SP midi_ctrl
5032                    </t>
5033                    <t>/ FX_SEND SP LEVEL SP sampler_channel SP fx_send_id SP volume_value
5034                    </t>
5035                    <t>/ ECHO SP boolean
5036                    </t>
5037                    <t>/ VOLUME SP volume_value
5038                  </t>                  </t>
5039          </list>          </list>
5040  </t>  </t>
5041  <t>create_instruction =  <t>create_instruction =
5042          <list>          <list>
5043                  <t>AUDIO_OUTPUT_DEVICE SP string SP key_val_list                    <t>AUDIO_OUTPUT_DEVICE SP string SP key_val_list
5044                    </t>
5045                    <t>/ AUDIO_OUTPUT_DEVICE SP string
5046                  </t>                  </t>
5047                  <t>/ AUDIO_OUTPUT_DEVICE SP string                                    <t>/ MIDI_INPUT_DEVICE SP string SP key_val_list
5048                  </t>                  </t>
5049                  <t>/ MIDI_INPUT_DEVICE SP string SP key_val_list                      <t>/ MIDI_INPUT_DEVICE SP string
5050                  </t>                  </t>
5051                  <t>/ MIDI_INPUT_DEVICE SP string                                      <t>/ FX_SEND SP sampler_channel SP midi_ctrl
5052                    </t>
5053                    <t>/ FX_SEND SP sampler_channel SP midi_ctrl SP fx_send_name
5054                    </t>
5055            </list>
5056    </t>
5057    <t>reset_instruction =
5058            <list>
5059                    <t>CHANNEL SP sampler_channel
5060                    </t>
5061            </list>
5062    </t>
5063    <t>clear_instruction =
5064            <list>
5065                    <t>MIDI_INSTRUMENTS SP midi_map
5066                    </t>
5067                    <t>/ MIDI_INSTRUMENTS SP ALL
5068                  </t>                  </t>
5069          </list>          </list>
5070  </t>  </t>
5071  <t>destroy_instruction =  <t>destroy_instruction =
5072          <list>          <list>
5073                  <t>AUDIO_OUTPUT_DEVICE SP number                    <t>AUDIO_OUTPUT_DEVICE SP number
5074                    </t>
5075                    <t>/ MIDI_INPUT_DEVICE SP number
5076                  </t>                  </t>
5077                  <t>/ MIDI_INPUT_DEVICE SP number                      <t>/ FX_SEND SP sampler_channel SP fx_send_id
5078                  </t>                  </t>
5079          </list>          </list>
5080  </t>  </t>
5081  <t>load_instruction =  <t>load_instruction =
5082          <list>          <list>
5083                  <t>INSTRUMENT SP load_instr_args                    <t>INSTRUMENT SP load_instr_args
5084                  </t>                  </t>
5085                  <t>/ ENGINE SP load_engine_args                      <t>/ ENGINE SP load_engine_args
5086                  </t>                  </t>
5087          </list>          </list>
5088  </t>  </t>
5089  <t>set_chan_instruction =  <t>set_chan_instruction =
5090          <list>          <list>
5091                  <t>AUDIO_OUTPUT_DEVICE SP sampler_channel SP device_index                                                                <t>AUDIO_OUTPUT_DEVICE SP sampler_channel SP device_index
5092                    </t>
5093                    <t>/ AUDIO_OUTPUT_CHANNEL SP sampler_channel SP audio_channel_index SP audio_channel_index
5094                    </t>
5095                    <t>/ AUDIO_OUTPUT_TYPE SP sampler_channel SP audio_output_type_name
5096                  </t>                  </t>
5097                  <t>/ AUDIO_OUTPUT_CHANNEL SP sampler_channel SP audio_channel_index SP audio_channel_index                                <t>/ MIDI_INPUT SP sampler_channel SP device_index SP midi_input_port_index SP midi_input_channel_index
5098                  </t>                  </t>
5099                  <t>/ AUDIO_OUTPUT_TYPE SP sampler_channel SP audio_output_type_name                                                        <t>/ MIDI_INPUT_DEVICE SP sampler_channel SP device_index
5100                  </t>                  </t>
5101                  <t>/ MIDI_INPUT SP sampler_channel SP device_index SP midi_input_port_index SP midi_input_channel_index                    <t>/ MIDI_INPUT_PORT SP sampler_channel SP midi_input_port_index
5102                  </t>                  </t>
5103                  <t>/ MIDI_INPUT_DEVICE SP sampler_channel SP device_index                                                                  <t>/ MIDI_INPUT_CHANNEL SP sampler_channel SP midi_input_channel_index
5104                  </t>                  </t>
5105                  <t>/ MIDI_INPUT_PORT SP sampler_channel SP midi_input_port_index                                                          <t>/ MIDI_INPUT_TYPE SP sampler_channel SP midi_input_type_name
5106                  </t>                  </t>
5107                  <t>/ MIDI_INPUT_CHANNEL SP sampler_channel SP midi_input_channel_index                                                    <t>/ VOLUME SP sampler_channel SP volume_value
5108                  </t>                  </t>
5109                  <t>/ MIDI_INPUT_TYPE SP sampler_channel SP midi_input_type_name                                                            <t>/ MUTE SP sampler_channel SP boolean
5110                  </t>                  </t>
5111                  <t>/ VOLUME SP sampler_channel SP volume_value                                                                            <t>/ SOLO SP sampler_channel SP boolean
5112                  </t>                  </t>
5113                  <t>/ MUTE SP sampler_channel SP boolean                                                                                    <t>/ MIDI_INSTRUMENT_MAP SP sampler_channel SP midi_map
5114                  </t>                  </t>
5115                  <t>/ SOLO SP sampler_channel SP boolean                                                                                    <t>/ MIDI_INSTRUMENT_MAP SP sampler_channel SP NONE
5116                    </t>
5117                    <t>/ MIDI_INSTRUMENT_MAP SP sampler_channel SP DEFAULT
5118                    </t>
5119            </list>
5120    </t>
5121    <t>modal_arg =
5122            <list>
5123                    <t>/* epsilon (empty argument) */
5124                    </t>
5125                    <t>/ NON_MODAL SP
5126                  </t>                  </t>
5127          </list>          </list>
5128  </t>  </t>
5129  <t>key_val_list =  <t>key_val_list =
5130          <list>          <list>
5131                  <t>string '=' param_val_list                                    <t>string '=' param_val_list
5132                  </t>                  </t>
5133                  <t>/ key_val_list SP string '=' param_val_list                    <t>/ key_val_list SP string '=' param_val_list
5134                  </t>                  </t>
5135          </list>          </list>
5136  </t>  </t>
5137  <t>buffer_size_type =  <t>buffer_size_type =
5138          <list>          <list>
5139                  <t>BYTES                        <t>BYTES
5140                  </t>                  </t>
5141                  <t>/ PERCENTAGE                    <t>/ PERCENTAGE
5142                  </t>                  </t>
5143          </list>          </list>
5144  </t>  </t>
5145  <t>list_instruction =  <t>list_instruction =
5146          <list>          <list>
5147                  <t>AUDIO_OUTPUT_DEVICES                              <t>AUDIO_OUTPUT_DEVICES
5148                    </t>
5149                    <t>/ MIDI_INPUT_DEVICES
5150                    </t>
5151                    <t>/ CHANNELS
5152                    </t>
5153                    <t>/ AVAILABLE_ENGINES
5154                  </t>                  </t>
5155                  <t>/ MIDI_INPUT_DEVICES                                <t>/ AVAILABLE_MIDI_INPUT_DRIVERS
5156                  </t>                  </t>
5157                  <t>/ CHANNELS                                          <t>/ AVAILABLE_AUDIO_OUTPUT_DRIVERS
5158                  </t>                  </t>
5159                  <t>/ AVAILABLE_ENGINES                                <t>/ MIDI_INSTRUMENTS SP midi_map
5160                  </t>                  </t>
5161                  <t>/ AVAILABLE_MIDI_INPUT_DRIVERS                      <t>/ MIDI_INSTRUMENTS SP ALL
5162                  </t>                  </t>
5163                  <t>/ AVAILABLE_AUDIO_OUTPUT_DRIVERS                    <t>/ MIDI_INSTRUMENT_MAPS
5164                    </t>
5165                    <t>/ FX_SENDS SP sampler_channel
5166                  </t>                  </t>
5167          </list>          </list>
5168  </t>  </t>
5169  <t>load_instr_args =  <t>load_instr_args =
5170          <list>          <list>
5171                  <t>filename SP instrument_index SP sampler_channel                                <t>filename SP instrument_index SP sampler_channel
5172                  </t>                  </t>
5173                  <t>/ NON_MODAL SP filename SP instrument_index SP sampler_channel                    <t>/ NON_MODAL SP filename SP instrument_index SP sampler_channel
5174                  </t>                  </t>
5175          </list>          </list>
5176  </t>  </t>
5177  <t>load_engine_args =  <t>load_engine_args =
5178          <list>          <list>
5179                  <t>engine_name SP sampler_channel                    <t>engine_name SP sampler_channel
5180                    </t>
5181            </list>
5182    </t>
5183    <t>instr_load_mode =
5184            <list>
5185                    <t>ON_DEMAND
5186                    </t>
5187                    <t>/ ON_DEMAND_HOLD
5188                    </t>
5189                    <t>/ PERSISTENT
5190                  </t>                  </t>
5191          </list>          </list>
5192  </t>  </t>
# Line 3706  Schoenebeck'> Line 5218  Schoenebeck'>
5218          <list>          <list>
5219                  <t>number                  <t>number
5220                  </t>                  </t>
5221                  <t>/ ALL                    <t>/ ALL
5222                  </t>                  </t>
5223          </list>          </list>
5224  </t>  </t>
# Line 3716  Schoenebeck'> Line 5228  Schoenebeck'>
5228                  </t>                  </t>
5229          </list>          </list>
5230  </t>  </t>
5231    <t>midi_map =
5232            <list>
5233                    <t>number
5234                    </t>
5235            </list>
5236    </t>
5237    <t>midi_bank =
5238            <list>
5239                    <t>number
5240                    </t>
5241            </list>
5242    </t>
5243    <t>midi_prog =
5244            <list>
5245                    <t>number
5246                    </t>
5247            </list>
5248    </t>
5249    <t>midi_ctrl =
5250            <list>
5251                    <t>number
5252                    </t>
5253            </list>
5254    </t>
5255  <t>volume_value =  <t>volume_value =
5256          <list>          <list>
5257                  <t>dotnum                  <t>dotnum
5258                  </t>                  </t>
5259                  <t>/ number                    <t>/ number
5260                  </t>                  </t>
5261          </list>          </list>
5262  </t>  </t>
# Line 3736  Schoenebeck'> Line 5272  Schoenebeck'>
5272                  </t>                  </t>
5273          </list>          </list>
5274  </t>  </t>
5275    <t>fx_send_id =
5276            <list>
5277                    <t>number
5278                    </t>
5279            </list>
5280    </t>
5281  <t>engine_name =  <t>engine_name =
5282          <list>          <list>
5283                  <t>string                  <t>string
# Line 3748  Schoenebeck'> Line 5290  Schoenebeck'>
5290                  </t>                  </t>
5291          </list>          </list>
5292  </t>  </t>
5293    <t>map_name =
5294            <list>
5295                    <t>stringval
5296                    </t>
5297            </list>
5298    </t>
5299    <t>entry_name =
5300            <list>
5301                    <t>stringval
5302                    </t>
5303            </list>
5304    </t>
5305    <t>fx_send_name =
5306            <list>
5307                    <t>stringval
5308                    </t>
5309            </list>
5310    </t>
5311  <t>param_val_list =  <t>param_val_list =
5312          <list>          <list>
5313                  <t>param_val                  <t>param_val
5314                  </t>                  </t>
5315                  <t>/ param_val_list','param_val                    <t>/ param_val_list','param_val
5316                  </t>                  </t>
5317          </list>          </list>
5318  </t>  </t>
# Line 3760  Schoenebeck'> Line 5320  Schoenebeck'>
5320          <list>          <list>
5321                  <t>string                  <t>string
5322                  </t>                  </t>
5323                  <t>/ '\'' string '\''                      <t>/ stringval
                 </t>  
                 <t>/ '\"' string '\"'      
5324                  </t>                  </t>
5325                  <t>/ number                              <t>/ number
5326                  </t>                  </t>
5327                  <t>/ dotnum                              <t>/ dotnum
5328                  </t>                  </t>
5329          </list>          </list>
5330  </t>  </t>
# Line 3777  Schoenebeck'> Line 5335  Schoenebeck'>
5335          <section title="Events" anchor="events">          <section title="Events" anchor="events">
5336              <t>This chapter will describe all currently defined events supported by LinuxSampler.</t>              <t>This chapter will describe all currently defined events supported by LinuxSampler.</t>
5337    
5338              <section title="Number of sampler channels changed" anchor="SUBSCRIBE CHANNEL">              <section title="Number of audio output devices changed" anchor="SUBSCRIBE AUDIO_OUTPUT_DEVICE_COUNT">
5339                    <t>Client may want to be notified when the total number of audio output devices on the
5340                    back-end changes by issuing the following command:</t>
5341                    <t>
5342                        <list>
5343                            <t>SUBSCRIBE AUDIO_OUTPUT_DEVICE_COUNT</t>
5344                        </list>
5345                    </t>
5346                    <t>Server will start sending the following notification messages:</t>
5347                    <t>
5348                        <list>
5349                            <t>"NOTIFY:AUDIO_OUTPUT_DEVICE_COUNT:&lt;devices&gt;"</t>
5350                        </list>
5351                    </t>
5352                    <t>where &lt;devices&gt; will be replaced by the new number
5353                    of audio output devices.</t>
5354                </section>
5355    
5356                <section title="Audio output device's settings changed" anchor="SUBSCRIBE AUDIO_OUTPUT_DEVICE_INFO">
5357                    <t>Client may want to be notified when changes were made to audio output devices on the
5358                    back-end by issuing the following command:</t>
5359                    <t>
5360                        <list>
5361                            <t>SUBSCRIBE AUDIO_OUTPUT_DEVICE_INFO</t>
5362                        </list>
5363                    </t>
5364                    <t>Server will start sending the following notification messages:</t>
5365                    <t>
5366                        <list>
5367                            <t>"NOTIFY:AUDIO_OUTPUT_DEVICE_INFO:&lt;device-id&gt;"</t>
5368                        </list>
5369                    </t>
5370                    <t>where &lt;device-id&gt; will be replaced by the numerical ID of the audio output device,
5371                    which settings has been changed. The front-end will have to send
5372                    the respective command to actually get the audio output device info. Because these messages
5373                    will be triggered by LSCP commands issued by other clients rather than real
5374                    time events happening on the server, it is believed that an empty notification
5375                    message is sufficient here.</t>
5376                </section>
5377    
5378                <section title="Number of MIDI input devices changed" anchor="SUBSCRIBE MIDI_INPUT_DEVICE_COUNT">
5379                    <t>Client may want to be notified when the total number of MIDI input devices on the
5380                    back-end changes by issuing the following command:</t>
5381                    <t>
5382                        <list>
5383                            <t>SUBSCRIBE MIDI_INPUT_DEVICE_COUNT</t>
5384                        </list>
5385                    </t>
5386                    <t>Server will start sending the following notification messages:</t>
5387                    <t>
5388                        <list>
5389                            <t>"NOTIFY:MIDI_INPUT_DEVICE_COUNT:&lt;devices&gt;"</t>
5390                        </list>
5391                    </t>
5392                    <t>where &lt;devices&gt; will be replaced by the new number
5393                    of MIDI input devices.</t>
5394                </section>
5395    
5396                <section title="MIDI input device's settings changed" anchor="SUBSCRIBE MIDI_INPUT_DEVICE_INFO">
5397                    <t>Client may want to be notified when changes were made to MIDI input devices on the
5398                    back-end by issuing the following command:</t>
5399                    <t>
5400                        <list>
5401                            <t>SUBSCRIBE MIDI_INPUT_DEVICE_INFO</t>
5402                        </list>
5403                    </t>
5404                    <t>Server will start sending the following notification messages:</t>
5405                    <t>
5406                        <list>
5407                            <t>"NOTIFY:MIDI_INPUT_DEVICE_INFO:&lt;device-id&gt;"</t>
5408                        </list>
5409                    </t>
5410                    <t>where &lt;device-id&gt; will be replaced by the numerical ID of the MIDI input device,
5411                    which settings has been changed. The front-end will have to send
5412                    the respective command to actually get the MIDI input device info. Because these messages
5413                    will be triggered by LSCP commands issued by other clients rather than real
5414                    time events happening on the server, it is believed that an empty notification
5415                    message is sufficient here.</t>
5416                </section>
5417    
5418                <section title="Number of sampler channels changed" anchor="SUBSCRIBE CHANNEL_COUNT">
5419                  <t>Client may want to be notified when the total number of channels on the                  <t>Client may want to be notified when the total number of channels on the
5420                  back-end changes by issuing the following command:</t>                  back-end changes by issuing the following command:</t>
5421                  <t>                  <t>
# Line 3806  Schoenebeck'> Line 5444  Schoenebeck'>
5444                  <t>Server will start sending the following notification messages:</t>                  <t>Server will start sending the following notification messages:</t>
5445                  <t>                  <t>
5446                      <list>                      <list>
5447                          <t>"NOTIFY:VOICE_COUNT:&lt;sampler-channel&gt; &lt;voices&gt;</t>                          <t>"NOTIFY:VOICE_COUNT:&lt;sampler-channel&gt; &lt;voices&gt;"</t>
5448                      </list>                      </list>
5449                  </t>                  </t>
5450                  <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 3854  Schoenebeck'> Line 5492  Schoenebeck'>
5492                  "GET CHANNEL BUFFER_FILL PERCENTAGE"</xref> command was issued on this channel.</t>                  "GET CHANNEL BUFFER_FILL PERCENTAGE"</xref> command was issued on this channel.</t>
5493              </section>              </section>
5494    
5495              <section title="Channel information changed" anchor="SUBSCRIBE INFO">              <section title="Channel information changed" anchor="SUBSCRIBE CHANNEL_INFO">
5496                  <t>Client may want to be notified when changes were made to sampler channels on the                  <t>Client may want to be notified when changes were made to sampler channels on the
5497                  back-end by issuing the following command:</t>                  back-end by issuing the following command:</t>
5498                  <t>                  <t>
# Line 3876  Schoenebeck'> Line 5514  Schoenebeck'>
5514                  message is sufficient here.</t>                  message is sufficient here.</t>
5515              </section>              </section>
5516    
5517                <section title="Number of effect sends changed" anchor="SUBSCRIBE FX_SEND_COUNT">
5518                    <t>Client may want to be notified when the number of effect sends on
5519                    a particular sampler channel is changed by issuing the following command:</t>
5520                    <t>
5521                        <list>
5522                            <t>SUBSCRIBE FX_SEND_COUNT</t>
5523                        </list>
5524                    </t>
5525                    <t>Server will start sending the following notification messages:</t>
5526                    <t>
5527                        <list>
5528                            <t>"NOTIFY:FX_SEND_COUNT:&lt;channel-id&gt; &lt;fx-sends&gt;"</t>
5529                        </list>
5530                    </t>
5531                    <t>where &lt;channel-id&gt; will be replaced by the numerical ID of the sampler
5532                    channel, on which the effect sends number is changed and &lt;fx-sends&gt; will
5533                    be replaced by the new number of effect sends on that channel.</t>
5534                </section>
5535    
5536                <section title="Effect send information changed" anchor="SUBSCRIBE FX_SEND_INFO">
5537                    <t>Client may want to be notified when changes were made to effect sends on a
5538                    a particular sampler channel by issuing the following command:</t>
5539                    <t>
5540                        <list>
5541                            <t>SUBSCRIBE FX_SEND_INFO</t>
5542                        </list>
5543                    </t>
5544                    <t>Server will start sending the following notification messages:</t>
5545                    <t>
5546                        <list>
5547                            <t>"NOTIFY:FX_SEND_INFO:&lt;channel-id&gt; &lt;fx-send-id&gt;"</t>
5548                        </list>
5549                    </t>
5550                    <t>where &lt;channel-id&gt; will be replaced by the numerical ID of the sampler
5551                    channel, on which an effect send entity is changed and &lt;fx-send-id&gt; will
5552                    be replaced by the numerical ID of the changed effect send.</t>
5553                </section>
5554    
5555                <section title="Total number of active voices changed" anchor="SUBSCRIBE TOTAL_VOICE_COUNT">
5556                    <t>Client may want to be notified when the total number of voices on the
5557                    back-end changes by issuing the following command:</t>
5558                    <t>
5559                        <list>
5560                            <t>SUBSCRIBE TOTAL_VOICE_COUNT</t>
5561                        </list>
5562                    </t>
5563                    <t>Server will start sending the following notification messages:</t>
5564                    <t>
5565                        <list>
5566                            <t>"NOTIFY:TOTAL_VOICE_COUNT:&lt;voices&gt;"</t>
5567                        </list>
5568                    </t>
5569                    <t>where &lt;voices&gt; will be replaced by the new number of
5570                    all currently active voices.</t>
5571                </section>
5572    
5573                <section title="Number of MIDI instrument maps changed" anchor="SUBSCRIBE MIDI_INSTRUMENT_MAP_COUNT">
5574                    <t>Client may want to be notified when the number of MIDI instrument maps on the
5575                    back-end changes by issuing the following command:</t>
5576                    <t>
5577                        <list>
5578                            <t>SUBSCRIBE MIDI_INSTRUMENT_MAP_COUNT</t>
5579                        </list>
5580                    </t>
5581                    <t>Server will start sending the following notification messages:</t>
5582                    <t>
5583                        <list>
5584                            <t>"NOTIFY:MIDI_INSTRUMENT_MAP_COUNT:&lt;maps&gt;"</t>
5585                        </list>
5586                    </t>
5587                    <t>where &lt;maps&gt; will be replaced by the new number
5588                    of MIDI instrument maps.</t>
5589                </section>
5590    
5591                <section title="MIDI instrument map information changed" anchor="SUBSCRIBE MIDI_INSTRUMENT_MAP_INFO">
5592                    <t>Client may want to be notified when changes were made to MIDI instrument maps on the
5593                    back-end by issuing the following command:</t>
5594                    <t>
5595                        <list>
5596                            <t>SUBSCRIBE MIDI_INSTRUMENT_MAP_INFO</t>
5597                        </list>
5598                    </t>
5599                    <t>Server will start sending the following notification messages:</t>
5600                    <t>
5601                        <list>
5602                            <t>"NOTIFY:MIDI_INSTRUMENT_MAP_INFO:&lt;map-id&gt;"</t>
5603                        </list>
5604                    </t>
5605                    <t>where &lt;map-id&gt; will be replaced by the numerical ID of the MIDI instrument map,
5606                    for which information changes occurred. The front-end will have to send
5607                    the respective command to actually get the MIDI instrument map info. Because these messages
5608                    will be triggered by LSCP commands issued by other clients rather than real
5609                    time events happening on the server, it is believed that an empty notification
5610                    message is sufficient here.</t>
5611                </section>
5612    
5613                <section title="Number of MIDI instruments changed" anchor="SUBSCRIBE MIDI_INSTRUMENT_COUNT">
5614                    <t>Client may want to be notified when the number of MIDI instrument maps on the
5615                    back-end changes by issuing the following command:</t>
5616                    <t>
5617                        <list>
5618                            <t>SUBSCRIBE MIDI_INSTRUMENT_COUNT</t>
5619                        </list>
5620                    </t>
5621                    <t>Server will start sending the following notification messages:</t>
5622                    <t>
5623                        <list>
5624                            <t>"NOTIFY:MIDI_INSTRUMENT_COUNT:&lt;map-id&gt; &lt;instruments&gt;"</t>
5625                        </list>
5626                    </t>
5627                    <t>where &lt;map-id&gt; is the numerical ID of the MIDI instrument map, in which
5628                    the nuber of instruments has changed and &lt;instruments&gt; will be replaced by
5629                    the new number of MIDI instruments in the specified map.</t>
5630                </section>
5631    
5632                <section title="MIDI instrument information changed" anchor="SUBSCRIBE MIDI_INSTRUMENT_INFO">
5633                    <t>Client may want to be notified when changes were made to MIDI instruments on the
5634                    back-end by issuing the following command:</t>
5635                    <t>
5636                        <list>
5637                            <t>SUBSCRIBE MIDI_INSTRUMENT_INFO</t>
5638                        </list>
5639                    </t>
5640                    <t>Server will start sending the following notification messages:</t>
5641                    <t>
5642                        <list>
5643                            <t>"NOTIFY:MIDI_INSTRUMENT_INFO:&lt;map-id&gt; &lt;bank&gt; &lt;program&gt;"</t>
5644                        </list>
5645                    </t>
5646                    <t>where &lt;map-id&gt; will be replaced by the numerical ID of the MIDI instrument map,
5647                    in which a MIDI instrument is changed. &lt;bank&gt; and &lt;program&gt; specifies
5648                    the location of the changed MIDI instrument in the map. The front-end will have to send
5649                    the respective command to actually get the MIDI instrument info. Because these messages
5650                    will be triggered by LSCP commands issued by other clients rather than real
5651                    time events happening on the server, it is believed that an empty notification
5652                    message is sufficient here.</t>
5653                </section>
5654    
5655                <section title="Global settings changed" anchor="SUBSCRIBE GLOBAL_INFO">
5656                    <t>Client may want to be notified when changes to the global settings
5657                    of the sampler were made by issuing the following command:</t>
5658                    <t>
5659                        <list>
5660                            <t>SUBSCRIBE GLOBAL_INFO</t>
5661                        </list>
5662                    </t>
5663                    <t>Server will start sending the following types of notification messages:</t>
5664                    <t>
5665                        <list>
5666                            <t>"NOTIFY:GLOBAL_INFO:VOLUME &lt;volume&gt;" - Notifies that the
5667                            golbal volume of the sampler is changed, where &lt;volume&gt; will be
5668                            replaced by the optional dotted floating point value, reflecting the
5669                            new global volume parameter.</t>
5670                        </list>
5671                    </t>
5672                </section>
5673    
5674              <section title="Miscellaneous and debugging events" anchor="SUBSCRIBE MISCELLANEOUS">              <section title="Miscellaneous and debugging events" anchor="SUBSCRIBE MISCELLANEOUS">
5675                  <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
5676                  the server by issuing the following command:</t>                  the server by issuing the following command:</t>

Legend:
Removed from v.706  
changed lines
  Added in v.1135

  ViewVC Help
Powered by ViewVC