/[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 984 by iliev, Mon Dec 18 10:28:00 2006 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="December" year="2006"/>
38          <workgroup>LinuxSampler Developers</workgroup>          <workgroup>LinuxSampler Developers</workgroup>
39          <keyword>LSCP</keyword>          <keyword>LSCP</keyword>
40          <abstract>          <abstract>
# Line 2559  Schoenebeck'> Line 2562  Schoenebeck'>
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="Resetting a sampler channel" anchor="RESET CHANNEL">                  <section title="Resetting a sampler channel" anchor="RESET CHANNEL">
3231                      <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>
3232                      <t>                      <t>
# Line 3329  Schoenebeck'> Line 3412  Schoenebeck'>
3412              <section title="Global commands">              <section title="Global commands">
3413                  <t>The following commands have global impact on the sampler.</t>                  <t>The following commands have global impact on the sampler.</t>
3414    
3415                    <section title="Current number of active voices" anchor="GET TOTAL_VOICE_COUNT">
3416                        <t>The front-end can ask for the current number of active voices on
3417                        the sampler by sending the following command:</t>
3418                        <t>
3419                            <list>
3420                                <t>GET TOTAL_VOICE_COUNT</t>
3421                            </list>
3422                        </t>
3423    
3424                        <t>Possible Answers:</t>
3425                        <t>
3426                            <list>
3427                                <t>LinuxSampler will answer by returning the number of all active
3428                                voices on the sampler.</t>
3429                            </list>
3430                        </t>
3431                    </section>
3432    
3433                    <section title="Maximum amount of active voices" anchor="GET TOTAL_VOICE_COUNT_MAX">
3434                        <t>The front-end can ask for the maximum number of active voices
3435                        by sending the following command:</t>
3436                        <t>
3437                            <list>
3438                                <t>GET TOTAL_VOICE_COUNT_MAX</t>
3439                            </list>
3440                        </t>
3441    
3442                        <t>Possible Answers:</t>
3443                        <t>
3444                            <list>
3445                                <t>LinuxSampler will answer by returning the maximum number
3446                                of active voices.</t>
3447                            </list>
3448                        </t>
3449                    </section>
3450    
3451                  <section title="Reset sampler" anchor="RESET">                  <section title="Reset sampler" anchor="RESET">
3452                      <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>
3453                      <t>                      <t>
# Line 3398  Schoenebeck'> Line 3517  Schoenebeck'>
3517                      Other fields might be added in future.</t>                      Other fields might be added in future.</t>
3518                  </section>                  </section>
3519              </section>              </section>
3520    
3521    
3522                <section title="MIDI Instrument Mapping" anchor="MIDI Instrument Mapping">
3523                    <t>The MIDI protocol provides a way to switch between instruments
3524                    by sending so called MIDI bank select and MIDI program change
3525                    messages which are essentially just numbers. The following commands
3526                    allow to actually map arbitrary MIDI bank select / program change
3527                    numbers with real instruments.</t>
3528                    <t>The sampler allows to manage an arbitrary amount of MIDI
3529                    instrument maps which define which instrument to load on
3530                    which MIDI program change message.</t>
3531                    <t>By default, that is when the sampler is launched, there is no
3532                    map, thus the sampler will simply ignore all program change
3533                    messages. The front-end has to explicitly create at least one
3534                    map, add entries to the map and tell the respective sampler
3535                    channel(s) which MIDI instrument map to use, so the sampler
3536                    knows how to react on a given program change message on the
3537                    respective sampler channel, that is by switching to the
3538                    respectively defined engine type and loading the respective
3539                    instrument. See command
3540                    <xref target="SET CHANNEL MIDI_INSTRUMENT_MAP">"SET CHANNEL MIDI_INSTRUMENT_MAP"</xref>
3541                    for how to assign a MIDI instrument map to a sampler channel.</t>
3542                    <t>Also note per MIDI specification a bank select message does not
3543                    cause to switch to another instrument. Instead when receiving a
3544                    bank select message the bank value will be stored and a subsequent
3545                    program change message (which may occur at any time) will finally
3546                    cause the sampler to switch to the respective instrument as
3547                    reflected by the current MIDI instrument map.</t>
3548    
3549                    <section title="Create a new MIDI instrument map" anchor="ADD MIDI_INSTRUMENT MAP">
3550                        <t>The front-end can add a new MIDI instrument map by sending
3551                        the following command:</t>
3552                        <t>
3553                            <list>
3554                                <t>ADD MIDI_INSTRUMENT_MAP [&lt;name&gt;]</t>
3555                            </list>
3556                        </t>
3557                        <t>Where &lt;name&gt; is an optional argument allowing to
3558                        assign a custom name to the new map. MIDI instrument Map
3559                        names do not have to be unique.</t>
3560    
3561                        <t>Possible Answers:</t>
3562                        <t>
3563                            <list>
3564                                <t>"OK[&lt;map&gt;]" -
3565                                    <list>
3566                                        <t>in case a new MIDI instrument map could
3567                                        be added, where &lt;map&gt; reflects the
3568                                        unique ID of the newly created MIDI
3569                                        instrument map</t>
3570                                    </list>
3571                                </t>
3572                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
3573                                    <list>
3574                                        <t>when a new map could not be created, which
3575                                        might never occur in practice</t>
3576                                    </list>
3577                                </t>
3578                            </list>
3579                        </t>
3580    
3581                        <t>Examples:</t>
3582                        <t>
3583                            <list>
3584                                <t>C: "ADD MIDI_INSTRUMENT_MAP 'Standard Map'"</t>
3585                                <t>S: "OK[0]"</t>
3586                            </list>
3587                        </t>
3588                        <t>
3589                            <list>
3590                                <t>C: "ADD MIDI_INSTRUMENT_MAP 'Standard Drumkit'"</t>
3591                                <t>S: "OK[1]"</t>
3592                            </list>
3593                        </t>
3594                        <t>
3595                            <list>
3596                                <t>C: "ADD MIDI_INSTRUMENT_MAP"</t>
3597                                <t>S: "OK[5]"</t>
3598                            </list>
3599                        </t>
3600                    </section>
3601    
3602                    <section title="Delete one particular or all MIDI instrument maps" anchor="REMOVE MIDI_INSTRUMENT_MAP">
3603                        <t>The front-end can delete a particular MIDI instrument map
3604                        by sending the following command:</t>
3605                        <t>
3606                            <list>
3607                                <t>REMOVE MIDI_INSTRUMENT_MAP &lt;map&gt;</t>
3608                            </list>
3609                        </t>
3610                        <t>Where &lt;map&gt; reflects the unique ID of the map to delete
3611                        as returned by the <xref target="LIST MIDI_INSTRUMENT_MAPS">"LIST MIDI_INSTRUMENT_MAPS"</xref>
3612                        command.</t>
3613                        <t>The front-end can delete all MIDI instrument maps by
3614                        sending the following command:</t>
3615                        <t>
3616                            <list>
3617                                <t>REMOVE MIDI_INSTRUMENT_MAP ALL</t>
3618                            </list>
3619                        </t>
3620    
3621                        <t>Possible Answers:</t>
3622                        <t>
3623                            <list>
3624                                <t>"OK" -
3625                                    <list>
3626                                        <t>in case the map(s) could be deleted</t>
3627                                    </list>
3628                                </t>
3629                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
3630                                    <list>
3631                                        <t>when the given map does not exist</t>
3632                                    </list>
3633                                </t>
3634                            </list>
3635                        </t>
3636    
3637                        <t>Examples:</t>
3638                        <t>
3639                            <list>
3640                                <t>C: "REMOVE MIDI_INSTRUMENT_MAP 0"</t>
3641                                <t>S: "OK"</t>
3642                            </list>
3643                        </t>
3644                        <t>
3645                            <list>
3646                                <t>C: "REMOVE MIDI_INSTRUMENT_MAP ALL"</t>
3647                                <t>S: "OK"</t>
3648                            </list>
3649                        </t>
3650                    </section>
3651    
3652                    <section title="Get amount of existing MIDI instrument maps" anchor="GET MIDI_INSTRUMENT_MAPS">
3653                        <t>The front-end can retrieve the current amount of MIDI
3654                        instrument maps by sending the following command:</t>
3655                        <t>
3656                            <list>
3657                                <t>GET MIDI_INSTRUMENT_MAPS</t>
3658                            </list>
3659                        </t>
3660    
3661                        <t>Possible Answers:</t>
3662                        <t>
3663                            <list>
3664                                <t>The sampler will answer by returning the current
3665                                number of MIDI instrument maps.</t>
3666                            </list>
3667                        </t>
3668    
3669                        <t>Example:</t>
3670                        <t>
3671                            <list>
3672                                <t>C: "GET MIDI_INSTRUMENT_MAPS"</t>
3673                                <t>S: "2"</t>
3674                            </list>
3675                        </t>
3676                    </section>
3677    
3678                    <section title="Getting all created MIDI instrument maps" anchor="LIST MIDI_INSTRUMENT_MAPS">
3679                        <t>The number of MIDI instrument maps can change on runtime. To get the
3680                        current list of MIDI instrument maps, the front-end can send the
3681                        following command:</t>
3682                        <t>
3683                            <list>
3684                                <t>LIST MIDI_INSTRUMENT_MAPS</t>
3685                            </list>
3686                        </t>
3687                        <t>Possible Answers:</t>
3688                        <t>
3689                            <list>
3690                                <t>The sampler will answer by returning a comma separated list
3691                                with all MIDI instrument maps' numerical IDs.</t>
3692                            </list>
3693                        </t>
3694                        <t>Example:</t>
3695                        <t>
3696                            <list>
3697                                <t>C: "LIST MIDI_INSTRUMENT_MAPS"</t>
3698                                <t>S: "0,1,5,12"</t>
3699                            </list>
3700                        </t>
3701                    </section>
3702    
3703                    <section title="Getting MIDI instrument map information" anchor="GET MIDI_INSTRUMENT_MAP INFO">
3704                        <t>The front-end can ask for the current settings of a MIDI
3705                        instrument map by sending the following command:</t>
3706                        <t>
3707                            <list>
3708                                <t>GET MIDI_INSTRUMENT_MAP INFO &lt;map&gt;</t>
3709                            </list>
3710                        </t>
3711                        <t>Where &lt;map&gt; is the numerical ID of the map the
3712                        front-end is interested in as returned by the
3713                        <xref target="LIST MIDI_INSTRUMENT_MAPS">"LIST MIDI_INSTRUMENT_MAPS"</xref>
3714                        command.</t>
3715    
3716                        <t>Possible Answers:</t>
3717                        <t>
3718                            <list>
3719                                <t>LinuxSampler will answer by sending a &lt;CRLF&gt; separated list.
3720                                Each answer line begins with the settings category name
3721                                followed by a colon and then a space character &lt;SP&gt; and finally
3722                                the info character string to that setting category. At the
3723                                moment the following categories are defined:</t>
3724    
3725                                <t>
3726                                    <list>
3727                                        <t>NAME -
3728                                            <list>
3729                                                <t>custom name of the given map,
3730                                                which does not have to be unique</t>
3731                                            </list>
3732                                        </t>
3733                                    </list>
3734                                </t>
3735                            </list>
3736                        </t>
3737                        <t>The mentioned fields above don't have to be in particular order.</t>
3738    
3739                        <t>Example:</t>
3740                        <t>
3741                            <list>
3742                                <t>C: "GET MIDI_INSTRUMENT_MAP INFO 0"</t>
3743                                <t>S: "NAME: Standard Map"</t>
3744                                <t>&nbsp;&nbsp;&nbsp;"."</t>
3745                            </list>
3746                        </t>
3747                    </section>
3748    
3749                    <section title="Renaming a MIDI instrument map" anchor="SET MIDI_INSTRUMENT_MAP NAME">
3750                        <t>The front-end can alter the custom name of a MIDI
3751                        instrument map by sending the following command:</t>
3752                        <t>
3753                            <list>
3754                                <t>SET MIDI_INSTRUMENT_MAP NAME &lt;map&gt; &lt;name&gt;</t>
3755                            </list>
3756                        </t>
3757                        <t>Where &lt;map&gt; is the numerical ID of the map and
3758                        &lt;name&gt; the new custom name of the map, which does not
3759                        have to be unique.</t>
3760    
3761                        <t>Possible Answers:</t>
3762                        <t>
3763                            <list>
3764                                <t>"OK" -
3765                                    <list>
3766                                        <t>on success</t>
3767                                    </list>
3768                                </t>
3769                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
3770                                    <list>
3771                                        <t>in case the given map does not exist</t>
3772                                    </list>
3773                                </t>
3774                            </list>
3775                        </t>
3776    
3777                        <t>Example:</t>
3778                        <t>
3779                            <list>
3780                                <t>C: "SET MIDI_INSTRUMENT_MAP NAME 0 'Foo instruments'"</t>
3781                                <t>S: "OK"</t>
3782                            </list>
3783                        </t>
3784                    </section>
3785    
3786                    <section title="Create or replace a MIDI instrument map entry" anchor="MAP MIDI_INSTRUMENT">
3787                        <t>The front-end can create a new or replace an existing entry
3788                        in a sampler's MIDI instrument map by sending the following
3789                        command:</t>
3790                        <t>
3791                            <list>
3792                                <t>MAP MIDI_INSTRUMENT &lt;map&gt;
3793                                &lt;midi_bank&gt; &lt;midi_prog&gt; &lt;engine_name&gt;
3794                                &lt;filename&gt; &lt;instrument_index&gt; &lt;volume_value&gt;
3795                                [&lt;instr_load_mode&gt;] [&lt;name&gt;]</t>
3796                            </list>
3797                        </t>
3798                        <t>Where &lt;map&gt; is the numeric ID of the map to alter,
3799                        &lt;midi_bank&gt; is an integer value between
3800                        0..16383 reflecting the MIDI bank select index,
3801                        &lt;midi_prog&gt; an
3802                        integer value between 0..127 reflecting the MIDI program change
3803                        index, &lt;engine_name&gt; a sampler engine name as returned by
3804                        the <xref target="LIST AVAILABLE_ENGINES">"LIST AVAILABLE_ENGINES"</xref>
3805                        command (not encapsulated into apostrophes), &lt;filename&gt; the name
3806                        of the instrument's file to be deployed (encapsulated into apostrophes),
3807                        &lt;instrument_index&gt; the index (integer value) of the instrument
3808                        within the given file, &lt;volume_value&gt; reflects the master
3809                        volume of the instrument as optionally dotted number (where a
3810                        value < 1.0 means attenuation and a value > 1.0 means
3811                        amplification). This parameter easily allows to adjust the
3812                        volume of all intruments within a custom instrument map
3813                        without having to adjust their instrument files. The
3814                        OPTIONAL &lt;instr_load_mode&gt; argument defines the life
3815                        time of the instrument, that is when the instrument should
3816                        be loaded, when freed and has exactly the following
3817                        possibilities:</t>
3818                        <t>
3819                            <list>
3820                                <t>"ON_DEMAND" -
3821                                    <list>
3822                                        <t>The instrument will be loaded when needed,
3823                                        that is when demanded by at least one sampler
3824                                        channel. It will immediately be freed from memory
3825                                        when not needed by any sampler channel anymore.</t>
3826                                    </list>
3827                                </t>
3828                                <t>"ON_DEMAND_HOLD" -
3829                                    <list>
3830                                        <t>The instrument will be loaded when needed,
3831                                        that is when demanded by at least one sampler
3832                                        channel. It will be kept in memory even when
3833                                        not needed by any sampler channel anymore.
3834                                        Instruments with this mode are only freed
3835                                        when the sampler is reset or all mapping
3836                                        entries with this mode (and respective
3837                                        instrument) are explicitly changed to
3838                                        "ON_DEMAND" and no sampler channel is using
3839                                        the instrument anymore.</t>
3840                                    </list>
3841                                </t>
3842                                <t>"PERSISTENT" -
3843                                    <list>
3844                                        <t>The instrument will immediately be loaded
3845                                        into memory in the background when this mapping
3846                                        command is sent and the instrument is kept all
3847                                        the time. Instruments with this mode are
3848                                        only freed when the sampler is reset or all
3849                                        mapping entries with this mode (and
3850                                        respective instrument) are explicitly
3851                                        changed to "ON_DEMAND" and no sampler
3852                                        channel is using the instrument anymore.</t>
3853                                    </list>
3854                                </t>
3855                                <t>not supplied -
3856                                    <list>
3857                                        <t>In case there is no &lt;instr_load_mode&gt;
3858                                        argument given, it will be up to the
3859                                        InstrumentManager to decide which mode to use.
3860                                        Usually it will use "ON_DEMAND" if an entry
3861                                        for the given instrument does not exist in
3862                                        the InstrumentManager's list yet, otherwise
3863                                        if an entry already exists, it will simply
3864                                        stick with the mode currently reflected by
3865                                        the already existing entry, that is it will
3866                                        not change the mode.</t>
3867                                    </list>
3868                                </t>
3869                            </list>
3870                        </t>
3871                        <t>
3872                        The &lt;instr_load_mode&gt; argument thus allows to define an
3873                        appropriate strategy (low memory consumption vs. fast
3874                        instrument switching) for each instrument individually. Note, the
3875                        following restrictions apply to this argument: "ON_DEMAND_HOLD" and
3876                        "PERSISTENT" have to be supported by the respective sampler engine
3877                        (which is technically the case when the engine provides an
3878                        InstrumentManager for its format). If this is not the case the
3879                        argument will automatically fall back to the default value
3880                        "ON_DEMAND". Also the load mode of one instrument may
3881                        automatically change the laod mode of other instrument(s), i.e.
3882                        because the instruments are part of the same file and the
3883                        engine does not allow a way to manage load modes for them
3884                        individually. Due to this, in case the frontend shows the
3885                        load modes of entries, the frontend should retrieve the actual
3886                        mode by i.e. sending
3887                        <xref target="GET MIDI_INSTRUMENT INFO">"GET MIDI_INSTRUMENT INFO"</xref>
3888                        command(s). Finally the OPTIONAL &lt;name&gt; argument allows to
3889                        set a custom name (encapsulated into apostrophes) for the mapping
3890                        entry, useful for frontends for displaying an appropriate name for
3891                        mapped instruments (using
3892                        <xref target="GET MIDI_INSTRUMENT INFO">"GET MIDI_INSTRUMENT INFO"</xref>).
3893                        </t>
3894                        <t>
3895                        The "MAP MIDI_INSTRUMENT" command
3896                        will immediately return, thus it will not block when an
3897                        instrument is to be loaded due to a "PERSISTENT" type
3898                        entry as instruments are loaded in the background. As a
3899                        consequence this command may not necessarily return an error
3900                        i.e. when the given instrument file does not exist or may
3901                        turn out to be corrupt.
3902                        </t>
3903    
3904                        <t>Possible Answers:</t>
3905                        <t>
3906                            <list>
3907                                <t>"OK" -
3908                                    <list>
3909                                        <t>usually</t>
3910                                    </list>
3911                                </t>
3912                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
3913                                    <list>
3914                                        <t>when the given map or engine does not exist or a value
3915                                        is out of range</t>
3916                                    </list>
3917                                </t>
3918                            </list>
3919                        </t>
3920    
3921                        <t>Examples:</t>
3922                        <t>
3923                            <list>
3924                                <t>C: "MAP MIDI_INSTRUMENT 0 3 0 gig '/usr/share/Steinway D.gig' 0 0.8 PERSISTENT"</t>
3925                                <t>S: "OK"</t>
3926                            </list>
3927                        </t>
3928                        <t>
3929                            <list>
3930                                <t>C: "MAP MIDI_INSTRUMENT 0 4 50 gig '/home/john/foostrings.gig' 7 1.0"</t>
3931                                <t>S: "OK"</t>
3932                            </list>
3933                        </t>
3934                        <t>
3935                            <list>
3936                                <t>C: "MAP MIDI_INSTRUMENT 0 0 0 gig '/usr/share/piano.gig' 0 1.0 'Normal Piano'"</t>
3937                                <t>S: "OK"</t>
3938                                <t>C: "MAP MIDI_INSTRUMENT 0 1 0 gig '/usr/share/piano.gig' 0 0.25 'Silent Piano'"</t>
3939                                <t>S: "OK"</t>
3940                            </list>
3941                        </t>
3942                        <t>
3943                            <list>
3944                                <t>C: "MAP MIDI_INSTRUMENT 1 8 120 gig '/home/joe/foodrums.gig' 0 1.0 PERSISTENT 'Foo Drumkit'"</t>
3945                                <t>S: "OK"</t>
3946                            </list>
3947                        </t>
3948                    </section>
3949    
3950                    <section title="Getting ammount of MIDI instrument map entries" anchor="GET MIDI_INSTRUMENTS">
3951                        <t>The front-end can query the amount of currently existing
3952                        entries in a MIDI instrument map by sending the following
3953                        command:</t>
3954                        <t>
3955                            <list>
3956                                <t>GET MIDI_INSTRUMENTS &lt;map&gt;</t>
3957                            </list>
3958                        </t>
3959                        <t>The front-end can query the amount of currently existing
3960                        entries in all MIDI instrument maps by sending the following
3961                        command:</t>
3962                        <t>
3963                            <list>
3964                                <t>GET MIDI_INSTRUMENTS ALL</t>
3965                            </list>
3966                        </t>
3967                        <t>Possible Answers:</t>
3968                        <t>
3969                            <list>
3970                                <t>The sampler will answer by sending the current number of
3971                                entries in the MIDI instrument map(s).</t>
3972                            </list>
3973                        </t>
3974    
3975                        <t>Example:</t>
3976                        <t>
3977                            <list>
3978                                <t>C: "GET MIDI_INSTRUMENTS 0"</t>
3979                                <t>S: "234"</t>
3980                            </list>
3981                        </t>
3982                        <t>
3983                            <list>
3984                                <t>C: "GET MIDI_INSTRUMENTS ALL"</t>
3985                                <t>S: "954"</t>
3986                            </list>
3987                        </t>
3988                    </section>
3989    
3990                    <section title="Getting indeces of all entries of a MIDI instrument map" anchor="LIST MIDI_INSTRUMENTS">
3991                        <t>The front-end can query a list of all currently existing
3992                        entries in a certain MIDI instrument map by sending the following
3993                        command:</t>
3994                        <t>
3995                            <list>
3996                                <t>LIST MIDI_INSTRUMENTS &lt;map&gt;</t>
3997                            </list>
3998                        </t>
3999                        <t>Where &lt;map&gt; is the numeric ID of the MIDI instrument map.</t>
4000                        <t>The front-end can query a list of all currently existing
4001                        entries of all MIDI instrument maps by sending the following
4002                        command:</t>
4003                        <t>
4004                            <list>
4005                                <t>LIST MIDI_INSTRUMENTS ALL</t>
4006                            </list>
4007                        </t>
4008    
4009                        <t>Possible Answers:</t>
4010                        <t>
4011                            <list>
4012                                <t>The sampler will answer by sending a comma separated
4013                                list of map ID - MIDI bank - MIDI program triples, where
4014                                each triple is encapsulated into curly braces. The
4015                                list is returned in one single line. Each triple
4016                                just reflects the key of the respective map entry,
4017                                thus subsequent
4018                                <xref target="GET MIDI_INSTRUMENT INFO">"GET MIDI_INSTRUMENT INFO"</xref>
4019                                command(s) are necessary to retrieve detailed informations
4020                                about each entry.</t>
4021                            </list>
4022                        </t>
4023    
4024                        <t>Example:</t>
4025                        <t>
4026                            <list>
4027                                <t>C: "LIST MIDI_INSTRUMENTS 0"</t>
4028                                <t>S: "{0,0,0},{0,0,1},{0,0,3},{0,1,4},{1,127,127}"</t>
4029                            </list>
4030                        </t>
4031                    </section>
4032    
4033                    <section title="Remove an entry from the MIDI instrument map" anchor="UNMAP MIDI_INSTRUMENT">
4034                        <t>The front-end can delete an entry from a MIDI instrument
4035                        map by sending the following command:</t>
4036                        <t>
4037                            <list>
4038                                <t>UNMAP MIDI_INSTRUMENT &lt;map&gt; &lt;midi_bank&gt; &lt;midi_prog&gt;</t>
4039                            </list>
4040                        </t>
4041                        <t>
4042                        Where &lt;map&gt; is the numeric ID of the MIDI instrument map,
4043                        &lt;midi_bank&gt; is an integer value between 0..16383
4044                        reflecting the MIDI bank value and
4045                        &lt;midi_prog&gt; an integer value between
4046                        0..127 reflecting the MIDI program value of the map's entrie's key
4047                        index triple.
4048                        </t>
4049    
4050                        <t>Possible Answers:</t>
4051                        <t>
4052                            <list>
4053                                <t>"OK" -
4054                                    <list>
4055                                        <t>usually</t>
4056                                    </list>
4057                                </t>
4058                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
4059                                    <list>
4060                                        <t>when index out of bounds</t>
4061                                    </list>
4062                                </t>
4063                            </list>
4064                        </t>
4065    
4066                        <t>Example:</t>
4067                        <t>
4068                            <list>
4069                                <t>C: "UNMAP MIDI_INSTRUMENT 0 2 127"</t>
4070                                <t>S: "OK"</t>
4071                            </list>
4072                        </t>
4073                    </section>
4074    
4075                    <section title="Get current settings of MIDI instrument map entry" anchor="GET MIDI_INSTRUMENT INFO">
4076                        <t>The front-end can retrieve the current settings of a certain
4077                        instrument map entry by sending the following command:</t>
4078                        <t>
4079                            <list>
4080                                <t>GET MIDI_INSTRUMENT INFO &lt;map&gt; &lt;midi_bank&gt; &lt;midi_prog&gt;</t>
4081                            </list>
4082                        </t>
4083                        <t>
4084                        Where &lt;map&gt; is the numeric ID of the MIDI instrument map,
4085                        &lt;midi_bank&gt; is an integer value between 0..16383
4086                        reflecting the MIDI bank value, &lt;midi_bank&gt;
4087                        and &lt;midi_prog&gt; an integer value between
4088                        0..127 reflecting the MIDI program value of the map's entrie's key
4089                        index triple.
4090                        </t>
4091    
4092                        <t>Possible Answers:</t>
4093                        <t>
4094                            <list>
4095                                <t>LinuxSampler will answer by sending a &lt;CRLF&gt;
4096                                separated list. Each answer line begins with the
4097                                information category name followed by a colon and then
4098                                a space character &lt;SP&gt; and finally the info
4099                                character string to that info category. At the moment
4100                                the following categories are defined:</t>
4101                                <t>"NAME" -
4102                                    <list>
4103                                        <t>Name for this MIDI instrument map entry (if defined).
4104                                        This name shall be used by frontends for displaying a
4105                                        name for this mapped instrument. It can be set and
4106                                        changed with the
4107                                        <xref target="MAP MIDI_INSTRUMENT">"MAP MIDI_INSTRUMENT"</xref>
4108                                        command and does not have to be unique.</t>
4109                                    </list>
4110                                </t>
4111                                <t>"ENGINE_NAME" -
4112                                    <list>
4113                                        <t>Name of the engine to be deployed for this
4114                                        instrument.</t>
4115                                    </list>
4116                                </t>
4117                                <t>"INSTRUMENT_FILE" -
4118                                    <list>
4119                                        <t>File name of the instrument.</t>
4120                                    </list>
4121                                </t>
4122                                <t>"INSTRUMENT_NR" -
4123                                    <list>
4124                                        <t>Index of the instrument within the file.</t>
4125                                    </list>
4126                                </t>
4127                                <t>"INSTRUMENT_NAME" -
4128                                    <list>
4129                                        <t>Name of the loaded instrument as reflected by its file.
4130                                        In contrast to the "NAME" field, the "INSTRUMENT_NAME" field
4131                                        cannot be changed.</t>
4132                                    </list>
4133                                </t>
4134                                <t>"LOAD_MODE" -
4135                                    <list>
4136                                        <t>Life time of instrument
4137                                        (see <xref target="MAP MIDI_INSTRUMENT">"MAP MIDI_INSTRUMENT"</xref> for details about this setting).</t>
4138                                    </list>
4139                                </t>
4140                                <t>"VOLUME" -
4141                                    <list>
4142                                        <t>master volume of the instrument as optionally
4143                                        dotted number (where a value < 1.0 means attenuation
4144                                        and a value > 1.0 means amplification)</t>
4145                                    </list>
4146                                </t>
4147                                <t>The mentioned fields above don't have to be in particular order.</t>
4148                            </list>
4149                        </t>
4150    
4151                        <t>Example:</t>
4152                        <t>
4153                            <list>
4154                                <t>C: "GET MIDI_INSTRUMENT INFO 1 45 120"</t>
4155                                <t>S: "NAME: Drums for Foo Song"</t>
4156                                <t>&nbsp;&nbsp;&nbsp;"ENGINE_NAME: GigEngine"</t>
4157                                <t>&nbsp;&nbsp;&nbsp;"INSTRUMENT_FILE: /usr/share/joesdrumkit.gig"</t>
4158                                <t>&nbsp;&nbsp;&nbsp;"INSTRUMENT_NR: 0"</t>
4159                                <t>&nbsp;&nbsp;&nbsp;"INSTRUMENT_NAME: Joe's Drumkit"</t>
4160                                <t>&nbsp;&nbsp;&nbsp;"LOAD_MODE: PERSISTENT"</t>
4161                                <t>&nbsp;&nbsp;&nbsp;"VOLUME: 1.0"</t>
4162                                <t>&nbsp;&nbsp;&nbsp;"."</t>
4163                            </list>
4164                        </t>
4165                    </section>
4166    
4167                    <section title="Clear MIDI instrument map" anchor="CLEAR MIDI_INSTRUMENTS">
4168                        <t>The front-end can clear a whole MIDI instrument map, that
4169                        is delete all its entries by sending the following command:</t>
4170                        <t>
4171                            <list>
4172                                <t>CLEAR MIDI_INSTRUMENTS &lt;map&gt;</t>
4173                            </list>
4174                        </t>
4175                        <t>Where &lt;map&gt; is the numeric ID of the map to clear.</t>
4176                        <t>The front-end can clear all MIDI instrument maps, that
4177                        is delete all entries of all maps by sending the following
4178                        command:</t>
4179                        <t>
4180                            <list>
4181                                <t>CLEAR MIDI_INSTRUMENTS ALL</t>
4182                            </list>
4183                        </t>
4184                        <t>The command "CLEAR MIDI_INSTRUMENTS ALL" does not delete the
4185                        maps, only their entries, thus the map's settings like
4186                        custom name will be preservevd.</t>
4187    
4188                       <t>Possible Answers:</t>
4189                        <t>
4190                            <list>
4191                                <t>"OK" -
4192                                    <list>
4193                                        <t>always</t>
4194                                    </list>
4195                                </t>
4196                            </list>
4197                        </t>
4198    
4199                        <t>Examples:</t>
4200                        <t>
4201                           <list>
4202                                <t>C: "CLEAR MIDI_INSTRUMENTS 0"</t>
4203                                <t>S: "OK"</t>
4204                            </list>
4205                        </t>
4206                        <t>
4207                           <list>
4208                                <t>C: "CLEAR MIDI_INSTRUMENTS ALL"</t>
4209                                <t>S: "OK"</t>
4210                            </list>
4211                        </t>
4212                    </section>
4213                </section>
4214    
4215          </section>          </section>
4216    
4217    
4218          <section title="Command Syntax" anchor="command_syntax">          <section title="Command Syntax" anchor="command_syntax">
4219              <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"/>
4220              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 4237  Schoenebeck'>
4237  </t>  </t>
4238  <t>line =  <t>line =
4239          <list>          <list>
4240                  <t>/* epsilon (empty line ignored) */                  <t>/* epsilon (empty line ignored) */
4241                  </t>                  </t>
4242                  <t>/ comment                    <t>/ comment
4243                  </t>                  </t>
4244                  <t>/ command                    <t>/ command
4245                  </t>                  </t>
4246                  <t>/ error                      <t>/ error
4247                  </t>                  </t>
4248          </list>          </list>
4249  </t>  </t>
# Line 3448  Schoenebeck'> Line 4263  Schoenebeck'>
4263  </t>  </t>
4264  <t>command =  <t>command =
4265          <list>          <list>
4266                  <t>ADD SP CHANNEL                                          <t>ADD SP add_instruction
4267                    </t>
4268                    <t>/ MAP SP map_instruction
4269                    </t>
4270                    <t>/ UNMAP SP unmap_instruction
4271                    </t>
4272                    <t>/ GET SP get_instruction
4273                    </t>
4274                    <t>/ CREATE SP create_instruction
4275                  </t>                  </t>
4276                  <t>/ GET SP get_instruction                                  <t>/ DESTROY SP destroy_instruction
4277                  </t>                  </t>
4278                  <t>/ CREATE SP create_instruction                            <t>/ LIST SP list_instruction
4279                  </t>                  </t>
4280                  <t>/ DESTROY SP destroy_instruction                          <t>/ LOAD SP load_instruction
4281                  </t>                  </t>
4282                  <t>/ LIST SP list_instruction                                <t>/ REMOVE SP remove_instruction
4283                  </t>                  </t>
4284                  <t>/ LOAD SP load_instruction                                <t>/ SET SP set_instruction
4285                  </t>                  </t>
4286                  <t>/ REMOVE SP CHANNEL SP sampler_channel                    <t>/ SUBSCRIBE SP subscribe_event
4287                  </t>                  </t>
4288                  <t>/ SET SP set_instruction                                  <t>/ UNSUBSCRIBE SP unsubscribe_event
4289                  </t>                  </t>
4290                  <t>/ SUBSCRIBE SP subscribe_event                            <t>/ SELECT SP text
4291                  </t>                  </t>
4292                  <t>/ UNSUBSCRIBE SP unsubscribe_event                        <t>/ RESET SP reset_instruction
4293                  </t>                  </t>
4294                  <t>/ SELECT SP text                                          <t>/ CLEAR SP clear_instruction
4295                  </t>                  </t>
4296                  <t>/ RESET SP CHANNEL SP sampler_channel                    <t>/ RESET
4297                    </t>
4298                    <t>/ QUIT
4299                    </t>
4300            </list>
4301    </t>
4302    <t>add_instruction =
4303            <list>
4304                    <t>CHANNEL
4305                  </t>                  </t>
4306                  <t>/ RESET                                                  <t>/ MIDI_INSTRUMENT_MAP
4307                  </t>                  </t>
4308                  <t>/ QUIT                                                    <t>/ MIDI_INSTRUMENT_MAP SP map_name
4309                  </t>                  </t>
4310          </list>          </list>
4311  </t>  </t>
4312  <t>subscribe_event =  <t>subscribe_event =
4313          <list>          <list>
4314                  <t>CHANNEL_COUNT                                          <t>AUDIO_OUTPUT_DEVICE_COUNT
4315                  </t>                  </t>
4316                  <t>/ VOICE_COUNT                                            <t>/ AUDIO_OUTPUT_DEVICE_INFO
4317                  </t>                  </t>
4318                  <t>/ STREAM_COUNT                                            <t>/ MIDI_INPUT_DEVICE_COUNT
4319                  </t>                  </t>
4320                  <t>/ BUFFER_FILL                                            <t>/ MIDI_INPUT_DEVICE_INFO
4321                  </t>                  </t>
4322                  <t>/ CHANNEL_INFO                                            <t>/ CHANNEL_COUNT
4323                  </t>                  </t>
4324                  <t>/ MISCELLANEOUS                                          <t>/ VOICE_COUNT
4325                    </t>
4326                    <t>/ STREAM_COUNT
4327                    </t>
4328                    <t>/ BUFFER_FILL
4329                    </t>
4330                    <t>/ CHANNEL_INFO
4331                    </t>
4332                    <t>/ MIDI_INSTRUMENT_MAP_COUNT
4333                    </t>
4334                    <t>/ MIDI_INSTRUMENT_MAP_INFO
4335                    </t>
4336                    <t>/ MIDI_INSTRUMENT_COUNT
4337                    </t>
4338                    <t>/ MIDI_INSTRUMENT_INFO
4339                    </t>
4340                    <t>/ MISCELLANEOUS
4341                    </t>
4342                    <t>/ TOTAL_VOICE_COUNT
4343                  </t>                  </t>
4344          </list>          </list>
4345  </t>  </t>
4346  <t>unsubscribe_event =  <t>unsubscribe_event =
4347          <list>          <list>
4348                  <t>CHANNEL_COUNT                                          <t>AUDIO_OUTPUT_DEVICE_COUNT
4349                    </t>
4350                    <t>/ AUDIO_OUTPUT_DEVICE_INFO
4351                    </t>
4352                    <t>/ MIDI_INPUT_DEVICE_COUNT
4353                    </t>
4354                    <t>/ MIDI_INPUT_DEVICE_INFO
4355                    </t>
4356                    <t>/ CHANNEL_COUNT
4357                    </t>
4358                    <t>/ VOICE_COUNT
4359                    </t>
4360                    <t>/ STREAM_COUNT
4361                    </t>
4362                    <t>/ BUFFER_FILL
4363                    </t>
4364                    <t>/ CHANNEL_INFO
4365                    </t>
4366                    <t>/ MIDI_INSTRUMENT_MAP_COUNT
4367                    </t>
4368                    <t>/ MIDI_INSTRUMENT_MAP_INFO
4369                    </t>
4370                    <t>/ MIDI_INSTRUMENT_COUNT
4371                    </t>
4372                    <t>/ MIDI_INSTRUMENT_INFO
4373                    </t>
4374                    <t>/ MISCELLANEOUS
4375                    </t>
4376                    <t>/ TOTAL_VOICE_COUNT
4377                    </t>
4378            </list>
4379    </t>
4380    <t>map_instruction =
4381            <list>
4382                    <t>MIDI_INSTRUMENT SP midi_map SP midi_bank SP midi_prog SP engine_name SP filename SP instrument_index SP volume_value
4383                  </t>                  </t>
4384                  <t>/ VOICE_COUNT                                            <t>/ MIDI_INSTRUMENT SP midi_map SP midi_bank SP midi_prog SP engine_name SP filename SP instrument_index SP volume_value SP instr_load_mode
4385                  </t>                  </t>
4386                  <t>/ STREAM_COUNT                                            <t>/ MIDI_INSTRUMENT SP midi_map SP midi_bank SP midi_prog SP engine_name SP filename SP instrument_index SP volume_value SP entry_name
4387                  </t>                  </t>
4388                  <t>/ BUFFER_FILL                                            <t>/ MIDI_INSTRUMENT SP midi_map SP midi_bank SP midi_prog SP engine_name SP filename SP instrument_index SP volume_value SP instr_load_mode SP entry_name
4389                  </t>                  </t>
4390                  <t>/ CHANNEL_INFO                                    </list>
4391    </t>
4392    <t>unmap_instruction =
4393            <list>
4394                    <t>MIDI_INSTRUMENT SP midi_map SP midi_bank SP midi_prog
4395                  </t>                  </t>
4396                  <t>/ MISCELLANEOUS                                  </list>
4397    </t>
4398    <t>remove_instruction =
4399            <list>
4400                    <t>CHANNEL SP sampler_channel
4401                    </t>
4402                    <t>/ MIDI_INSTRUMENT_MAP SP midi_map
4403                    </t>
4404                    <t>/ MIDI_INSTRUMENT_MAP SP ALL
4405                  </t>                  </t>
4406          </list>          </list>
4407  </t>  </t>
4408  <t>get_instruction =  <t>get_instruction =
4409          <list>          <list>
4410                  <t>AVAILABLE_ENGINES                                                                            <t>AVAILABLE_ENGINES
4411                    </t>
4412                    <t>/ AVAILABLE_MIDI_INPUT_DRIVERS
4413                    </t>
4414                    <t>/ MIDI_INPUT_DRIVER SP INFO SP string
4415                    </t>
4416                    <t>/ MIDI_INPUT_DRIVER_PARAMETER SP INFO SP string SP string
4417                    </t>
4418                    <t>/ MIDI_INPUT_DRIVER_PARAMETER SP INFO SP string SP string SP key_val_list
4419                    </t>
4420                    <t>/ AVAILABLE_AUDIO_OUTPUT_DRIVERS
4421                    </t>
4422                    <t>/ AUDIO_OUTPUT_DRIVER SP INFO SP string
4423                    </t>
4424                    <t>/ AUDIO_OUTPUT_DRIVER_PARAMETER SP INFO SP string SP string
4425                  </t>                  </t>
4426                  <t>/ AVAILABLE_MIDI_INPUT_DRIVERS                                                                <t>/ AUDIO_OUTPUT_DRIVER_PARAMETER SP INFO SP string SP string SP key_val_list
4427                  </t>                  </t>
4428                  <t>/ MIDI_INPUT_DRIVER SP INFO SP string                                                          <t>/ AUDIO_OUTPUT_DEVICES
4429                  </t>                  </t>
4430                  <t>/ MIDI_INPUT_DRIVER_PARAMETER SP INFO SP string SP string                                      <t>/ MIDI_INPUT_DEVICES
4431                  </t>                  </t>
4432                  <t>/ MIDI_INPUT_DRIVER_PARAMETER SP INFO SP string SP string SP key_val_list                      <t>/ AUDIO_OUTPUT_DEVICE SP INFO SP number
4433                  </t>                  </t>
4434                  <t>/ AVAILABLE_AUDIO_OUTPUT_DRIVERS                                                              <t>/ MIDI_INPUT_DEVICE SP INFO SP number
4435                  </t>                  </t>
4436                  <t>/ AUDIO_OUTPUT_DRIVER SP INFO SP string                                                        <t>/ MIDI_INPUT_PORT SP INFO SP number SP number
4437                  </t>                  </t>
4438                  <t>/ AUDIO_OUTPUT_DRIVER_PARAMETER SP INFO SP string SP string                                    <t>/ MIDI_INPUT_PORT_PARAMETER SP INFO SP number SP number SP string
4439                  </t>                  </t>
4440                  <t>/ AUDIO_OUTPUT_DRIVER_PARAMETER SP INFO SP string SP string SP key_val_list                    <t>/ AUDIO_OUTPUT_CHANNEL SP INFO SP number SP number
4441                  </t>                  </t>
4442                  <t>/ AUDIO_OUTPUT_DEVICES                                                                        <t>/ AUDIO_OUTPUT_CHANNEL_PARAMETER SP INFO SP number SP number SP string
4443                  </t>                  </t>
4444                  <t>/ MIDI_INPUT_DEVICES                                                                          <t>/ CHANNELS
4445                  </t>                  </t>
4446                  <t>/ AUDIO_OUTPUT_DEVICE SP INFO SP number                                                        <t>/ CHANNEL SP INFO SP sampler_channel
4447                  </t>                  </t>
4448                  <t>/ MIDI_INPUT_DEVICE SP INFO SP number                                                          <t>/ CHANNEL SP BUFFER_FILL SP buffer_size_type SP sampler_channel
4449                  </t>                  </t>
4450                  <t>/ MIDI_INPUT_PORT SP INFO SP number SP number                                                  <t>/ CHANNEL SP STREAM_COUNT SP sampler_channel
4451                  </t>                  </t>
4452                  <t>/ MIDI_INPUT_PORT_PARAMETER SP INFO SP number SP number SP string                              <t>/ CHANNEL SP VOICE_COUNT SP sampler_channel
4453                  </t>                  </t>
4454                  <t>/ AUDIO_OUTPUT_CHANNEL SP INFO SP number SP number                                            <t>/ ENGINE SP INFO SP engine_name
4455                  </t>                  </t>
4456                  <t>/ AUDIO_OUTPUT_CHANNEL_PARAMETER SP INFO SP number SP number SP string                        <t>/ SERVER SP INFO
4457                  </t>                  </t>
4458                  <t>/ CHANNELS                                                                                    <t>/ TOTAL_VOICE_COUNT
4459                  </t>                  </t>
4460                  <t>/ CHANNEL SP INFO SP sampler_channel                                                          <t>/ TOTAL_VOICE_COUNT_MAX
4461                  </t>                  </t>
4462                  <t>/ CHANNEL SP BUFFER_FILL SP buffer_size_type SP sampler_channel                                <t>/ MIDI_INSTRUMENTS SP midi_map
4463                  </t>                  </t>
4464                  <t>/ CHANNEL SP STREAM_COUNT SP sampler_channel                                                  <t>/ MIDI_INSTRUMENTS SP ALL
4465                  </t>                  </t>
4466                  <t>/ CHANNEL SP VOICE_COUNT SP sampler_channel                                                    <t>/ MIDI_INSTRUMENT SP INFO SP midi_map SP midi_bank SP midi_prog
4467                  </t>                  </t>
4468                  <t>/ ENGINE SP INFO SP engine_name                                                                <t>/ MIDI_INSTRUMENT_MAPS
4469                  </t>                  </t>
4470                  <t>/ SERVER SP INFO                                                                              <t>/ MIDI_INSTRUMENT_MAP SP INFO SP midi_map
4471                  </t>                  </t>
4472          </list>          </list>
4473  </t>  </t>
4474  <t>set_instruction =  <t>set_instruction =
4475          <list>          <list>
4476                  <t>AUDIO_OUTPUT_DEVICE_PARAMETER SP number SP string '=' param_val_list                              <t>AUDIO_OUTPUT_DEVICE_PARAMETER SP number SP string '=' param_val_list
4477                  </t>                  </t>
4478                  <t>/ AUDIO_OUTPUT_CHANNEL_PARAMETER SP number SP number SP string '=' param_val_list                    <t>/ AUDIO_OUTPUT_CHANNEL_PARAMETER SP number SP number SP string '=' param_val_list
4479                  </t>                  </t>
4480                  <t>/ MIDI_INPUT_DEVICE_PARAMETER SP number SP string '=' param_val_list                                <t>/ MIDI_INPUT_DEVICE_PARAMETER SP number SP string '=' param_val_list
4481                  </t>                  </t>
4482                  <t>/ MIDI_INPUT_PORT_PARAMETER SP number SP number SP string '=' param_val_list                        <t>/ MIDI_INPUT_PORT_PARAMETER SP number SP number SP string '=' param_val_list
4483                  </t>                  </t>
4484                  <t>/ CHANNEL SP set_chan_instruction                                                                    <t>/ CHANNEL SP set_chan_instruction
4485                  </t>                  </t>
4486                  <t>/ ECHO SP boolean                                                                                    <t>/ MIDI_INSTRUMENT_MAP SP NAME SP midi_map SP map_name
4487                    </t>
4488                    <t>/ ECHO SP boolean
4489                  </t>                  </t>
4490          </list>          </list>
4491  </t>  </t>
4492  <t>create_instruction =  <t>create_instruction =
4493          <list>          <list>
4494                  <t>AUDIO_OUTPUT_DEVICE SP string SP key_val_list                    <t>AUDIO_OUTPUT_DEVICE SP string SP key_val_list
4495                    </t>
4496                    <t>/ AUDIO_OUTPUT_DEVICE SP string
4497                  </t>                  </t>
4498                  <t>/ AUDIO_OUTPUT_DEVICE SP string                                    <t>/ MIDI_INPUT_DEVICE SP string SP key_val_list
4499                  </t>                  </t>
4500                  <t>/ MIDI_INPUT_DEVICE SP string SP key_val_list                      <t>/ MIDI_INPUT_DEVICE SP string
4501                  </t>                  </t>
4502                  <t>/ MIDI_INPUT_DEVICE SP string                              </list>
4503    </t>
4504    <t>reset_instruction =
4505            <list>
4506                    <t>CHANNEL SP sampler_channel
4507                    </t>
4508            </list>
4509    </t>
4510    <t>clear_instruction =
4511            <list>
4512                    <t>MIDI_INSTRUMENTS SP midi_map
4513                    </t>
4514                    <t>/ MIDI_INSTRUMENTS SP ALL
4515                  </t>                  </t>
4516          </list>          </list>
4517  </t>  </t>
4518  <t>destroy_instruction =  <t>destroy_instruction =
4519          <list>          <list>
4520                  <t>AUDIO_OUTPUT_DEVICE SP number                    <t>AUDIO_OUTPUT_DEVICE SP number
4521                  </t>                  </t>
4522                  <t>/ MIDI_INPUT_DEVICE SP number                      <t>/ MIDI_INPUT_DEVICE SP number
4523                  </t>                  </t>
4524          </list>          </list>
4525  </t>  </t>
4526  <t>load_instruction =  <t>load_instruction =
4527          <list>          <list>
4528                  <t>INSTRUMENT SP load_instr_args                    <t>INSTRUMENT SP load_instr_args
4529                  </t>                  </t>
4530                  <t>/ ENGINE SP load_engine_args                      <t>/ ENGINE SP load_engine_args
4531                  </t>                  </t>
4532          </list>          </list>
4533  </t>  </t>
4534  <t>set_chan_instruction =  <t>set_chan_instruction =
4535          <list>          <list>
4536                  <t>AUDIO_OUTPUT_DEVICE SP sampler_channel SP device_index                                                                <t>AUDIO_OUTPUT_DEVICE SP sampler_channel SP device_index
4537                    </t>
4538                    <t>/ AUDIO_OUTPUT_CHANNEL SP sampler_channel SP audio_channel_index SP audio_channel_index
4539                  </t>                  </t>
4540                  <t>/ AUDIO_OUTPUT_CHANNEL SP sampler_channel SP audio_channel_index SP audio_channel_index                                <t>/ AUDIO_OUTPUT_TYPE SP sampler_channel SP audio_output_type_name
4541                  </t>                  </t>
4542                  <t>/ AUDIO_OUTPUT_TYPE SP sampler_channel SP audio_output_type_name                                                        <t>/ MIDI_INPUT SP sampler_channel SP device_index SP midi_input_port_index SP midi_input_channel_index
4543                  </t>                  </t>
4544                  <t>/ MIDI_INPUT SP sampler_channel SP device_index SP midi_input_port_index SP midi_input_channel_index                    <t>/ MIDI_INPUT_DEVICE SP sampler_channel SP device_index
4545                  </t>                  </t>
4546                  <t>/ MIDI_INPUT_DEVICE SP sampler_channel SP device_index                                                                  <t>/ MIDI_INPUT_PORT SP sampler_channel SP midi_input_port_index
4547                  </t>                  </t>
4548                  <t>/ MIDI_INPUT_PORT SP sampler_channel SP midi_input_port_index                                                          <t>/ MIDI_INPUT_CHANNEL SP sampler_channel SP midi_input_channel_index
4549                  </t>                  </t>
4550                  <t>/ MIDI_INPUT_CHANNEL SP sampler_channel SP midi_input_channel_index                                                    <t>/ MIDI_INPUT_TYPE SP sampler_channel SP midi_input_type_name
4551                  </t>                  </t>
4552                  <t>/ MIDI_INPUT_TYPE SP sampler_channel SP midi_input_type_name                                                            <t>/ VOLUME SP sampler_channel SP volume_value
4553                  </t>                  </t>
4554                  <t>/ VOLUME SP sampler_channel SP volume_value                                                                            <t>/ MUTE SP sampler_channel SP boolean
4555                  </t>                  </t>
4556                  <t>/ MUTE SP sampler_channel SP boolean                                                                                    <t>/ SOLO SP sampler_channel SP boolean
4557                  </t>                  </t>
4558                  <t>/ SOLO SP sampler_channel SP boolean                                                                                    <t>/ MIDI_INSTRUMENT_MAP SP sampler_channel SP midi_map
4559                    </t>
4560                    <t>/ MIDI_INSTRUMENT_MAP SP sampler_channel SP NONE
4561                    </t>
4562                    <t>/ MIDI_INSTRUMENT_MAP SP sampler_channel SP DEFAULT
4563                  </t>                  </t>
4564          </list>          </list>
4565  </t>  </t>
4566  <t>key_val_list =  <t>key_val_list =
4567          <list>          <list>
4568                  <t>string '=' param_val_list                                    <t>string '=' param_val_list
4569                  </t>                  </t>
4570                  <t>/ key_val_list SP string '=' param_val_list                    <t>/ key_val_list SP string '=' param_val_list
4571                  </t>                  </t>
4572          </list>          </list>
4573  </t>  </t>
4574  <t>buffer_size_type =  <t>buffer_size_type =
4575          <list>          <list>
4576                  <t>BYTES                        <t>BYTES
4577                  </t>                  </t>
4578                  <t>/ PERCENTAGE                    <t>/ PERCENTAGE
4579                  </t>                  </t>
4580          </list>          </list>
4581  </t>  </t>
4582  <t>list_instruction =  <t>list_instruction =
4583          <list>          <list>
4584                  <t>AUDIO_OUTPUT_DEVICES                              <t>AUDIO_OUTPUT_DEVICES
4585                    </t>
4586                    <t>/ MIDI_INPUT_DEVICES
4587                    </t>
4588                    <t>/ CHANNELS
4589                    </t>
4590                    <t>/ AVAILABLE_ENGINES
4591                  </t>                  </t>
4592                  <t>/ MIDI_INPUT_DEVICES                                <t>/ AVAILABLE_MIDI_INPUT_DRIVERS
4593                  </t>                  </t>
4594                  <t>/ CHANNELS                                          <t>/ AVAILABLE_AUDIO_OUTPUT_DRIVERS
4595                  </t>                  </t>
4596                  <t>/ AVAILABLE_ENGINES                                <t>/ MIDI_INSTRUMENTS SP midi_map
4597                  </t>                  </t>
4598                  <t>/ AVAILABLE_MIDI_INPUT_DRIVERS                      <t>/ MIDI_INSTRUMENTS SP ALL
4599                  </t>                  </t>
4600                  <t>/ AVAILABLE_AUDIO_OUTPUT_DRIVERS                    <t>/ MIDI_INSTRUMENT_MAPS
4601                  </t>                  </t>
4602          </list>          </list>
4603  </t>  </t>
4604  <t>load_instr_args =  <t>load_instr_args =
4605          <list>          <list>
4606                  <t>filename SP instrument_index SP sampler_channel                                <t>filename SP instrument_index SP sampler_channel
4607                  </t>                  </t>
4608                  <t>/ NON_MODAL SP filename SP instrument_index SP sampler_channel                    <t>/ NON_MODAL SP filename SP instrument_index SP sampler_channel
4609                  </t>                  </t>
4610          </list>          </list>
4611  </t>  </t>
4612  <t>load_engine_args =  <t>load_engine_args =
4613          <list>          <list>
4614                  <t>engine_name SP sampler_channel                    <t>engine_name SP sampler_channel
4615                    </t>
4616            </list>
4617    </t>
4618    <t>instr_load_mode =
4619            <list>
4620                    <t>ON_DEMAND
4621                    </t>
4622                    <t>/ ON_DEMAND_HOLD
4623                    </t>
4624                    <t>/ PERSISTENT
4625                  </t>                  </t>
4626          </list>          </list>
4627  </t>  </t>
# Line 3706  Schoenebeck'> Line 4653  Schoenebeck'>
4653          <list>          <list>
4654                  <t>number                  <t>number
4655                  </t>                  </t>
4656                  <t>/ ALL                    <t>/ ALL
4657                  </t>                  </t>
4658          </list>          </list>
4659  </t>  </t>
# Line 3716  Schoenebeck'> Line 4663  Schoenebeck'>
4663                  </t>                  </t>
4664          </list>          </list>
4665  </t>  </t>
4666    <t>midi_map =
4667            <list>
4668                    <t>number
4669                    </t>
4670            </list>
4671    </t>
4672    <t>midi_bank =
4673            <list>
4674                    <t>number
4675                    </t>
4676            </list>
4677    </t>
4678    <t>midi_prog =
4679            <list>
4680                    <t>number
4681                    </t>
4682            </list>
4683    </t>
4684  <t>volume_value =  <t>volume_value =
4685          <list>          <list>
4686                  <t>dotnum                  <t>dotnum
4687                  </t>                  </t>
4688                  <t>/ number                    <t>/ number
4689                  </t>                  </t>
4690          </list>          </list>
4691  </t>  </t>
# Line 3748  Schoenebeck'> Line 4713  Schoenebeck'>
4713                  </t>                  </t>
4714          </list>          </list>
4715  </t>  </t>
4716    <t>map_name =
4717            <list>
4718                    <t>stringval
4719                    </t>
4720            </list>
4721    </t>
4722    <t>entry_name =
4723            <list>
4724                    <t>stringval
4725                    </t>
4726            </list>
4727    </t>
4728  <t>param_val_list =  <t>param_val_list =
4729          <list>          <list>
4730                  <t>param_val                  <t>param_val
4731                  </t>                  </t>
4732                  <t>/ param_val_list','param_val                    <t>/ param_val_list','param_val
4733                  </t>                  </t>
4734          </list>          </list>
4735  </t>  </t>
# Line 3760  Schoenebeck'> Line 4737  Schoenebeck'>
4737          <list>          <list>
4738                  <t>string                  <t>string
4739                  </t>                  </t>
4740                  <t>/ '\'' string '\''                      <t>/ stringval
                 </t>  
                 <t>/ '\"' string '\"'      
4741                  </t>                  </t>
4742                  <t>/ number                              <t>/ number
4743                  </t>                  </t>
4744                  <t>/ dotnum                              <t>/ dotnum
4745                  </t>                  </t>
4746          </list>          </list>
4747  </t>  </t>
# Line 3777  Schoenebeck'> Line 4752  Schoenebeck'>
4752          <section title="Events" anchor="events">          <section title="Events" anchor="events">
4753              <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>
4754    
4755              <section title="Number of sampler channels changed" anchor="SUBSCRIBE CHANNEL">              <section title="Number of audio output devices changed" anchor="SUBSCRIBE AUDIO_OUTPUT_DEVICE_COUNT">
4756                    <t>Client may want to be notified when the total number of audio output devices on the
4757                    back-end changes by issuing the following command:</t>
4758                    <t>
4759                        <list>
4760                            <t>SUBSCRIBE AUDIO_OUTPUT_DEVICE_COUNT</t>
4761                        </list>
4762                    </t>
4763                    <t>Server will start sending the following notification messages:</t>
4764                    <t>
4765                        <list>
4766                            <t>"NOTIFY:AUDIO_OUTPUT_DEVICE_COUNT:&lt;devices&gt;"</t>
4767                        </list>
4768                    </t>
4769                    <t>where &lt;devices&gt; will be replaced by the new number
4770                    of audio output devices.</t>
4771                </section>
4772    
4773                <section title="Audio output device's settings changed" anchor="SUBSCRIBE AUDIO_OUTPUT_DEVICE_INFO">
4774                    <t>Client may want to be notified when changes were made to audio output devices on the
4775                    back-end by issuing the following command:</t>
4776                    <t>
4777                        <list>
4778                            <t>SUBSCRIBE AUDIO_OUTPUT_DEVICE_INFO</t>
4779                        </list>
4780                    </t>
4781                    <t>Server will start sending the following notification messages:</t>
4782                    <t>
4783                        <list>
4784                            <t>"NOTIFY:AUDIO_OUTPUT_DEVICE_INFO:&lt;device-id&gt;"</t>
4785                        </list>
4786                    </t>
4787                    <t>where &lt;device-id&gt; will be replaced by the numerical ID of the audio output device,
4788                    which settings has been changed. The front-end will have to send
4789                    the respective command to actually get the audio output device info. Because these messages
4790                    will be triggered by LSCP commands issued by other clients rather than real
4791                    time events happening on the server, it is believed that an empty notification
4792                    message is sufficient here.</t>
4793                </section>
4794    
4795                <section title="Number of MIDI input devices changed" anchor="SUBSCRIBE MIDI_INPUT_DEVICE_COUNT">
4796                    <t>Client may want to be notified when the total number of MIDI input devices on the
4797                    back-end changes by issuing the following command:</t>
4798                    <t>
4799                        <list>
4800                            <t>SUBSCRIBE MIDI_INPUT_DEVICE_COUNT</t>
4801                        </list>
4802                    </t>
4803                    <t>Server will start sending the following notification messages:</t>
4804                    <t>
4805                        <list>
4806                            <t>"NOTIFY:MIDI_INPUT_DEVICE_COUNT:&lt;devices&gt;"</t>
4807                        </list>
4808                    </t>
4809                    <t>where &lt;devices&gt; will be replaced by the new number
4810                    of MIDI input devices.</t>
4811                </section>
4812    
4813                <section title="MIDI input device's settings changed" anchor="SUBSCRIBE MIDI_INPUT_DEVICE_INFO">
4814                    <t>Client may want to be notified when changes were made to MIDI input devices on the
4815                    back-end by issuing the following command:</t>
4816                    <t>
4817                        <list>
4818                            <t>SUBSCRIBE MIDI_INPUT_DEVICE_INFO</t>
4819                        </list>
4820                    </t>
4821                    <t>Server will start sending the following notification messages:</t>
4822                    <t>
4823                        <list>
4824                            <t>"NOTIFY:MIDI_INPUT_DEVICE_INFO:&lt;device-id&gt;"</t>
4825                        </list>
4826                    </t>
4827                    <t>where &lt;device-id&gt; will be replaced by the numerical ID of the MIDI input device,
4828                    which settings has been changed. The front-end will have to send
4829                    the respective command to actually get the MIDI input device info. Because these messages
4830                    will be triggered by LSCP commands issued by other clients rather than real
4831                    time events happening on the server, it is believed that an empty notification
4832                    message is sufficient here.</t>
4833                </section>
4834    
4835                <section title="Number of sampler channels changed" anchor="SUBSCRIBE CHANNEL_COUNT">
4836                  <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
4837                  back-end changes by issuing the following command:</t>                  back-end changes by issuing the following command:</t>
4838                  <t>                  <t>
# Line 3854  Schoenebeck'> Line 4909  Schoenebeck'>
4909                  "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>
4910              </section>              </section>
4911    
4912              <section title="Channel information changed" anchor="SUBSCRIBE INFO">              <section title="Channel information changed" anchor="SUBSCRIBE CHANNEL_INFO">
4913                  <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
4914                  back-end by issuing the following command:</t>                  back-end by issuing the following command:</t>
4915                  <t>                  <t>
# Line 3876  Schoenebeck'> Line 4931  Schoenebeck'>
4931                  message is sufficient here.</t>                  message is sufficient here.</t>
4932              </section>              </section>
4933    
4934              <section title="Miscellaneous and debugging events" anchor="SUBSCRIBE MISCELLANEOUS">              <section title="Total number of active voices changed" anchor="SUBSCRIBE TOTAL_VOICE_COUNT">
4935                    <t>Client may want to be notified when the total number of voices on the
4936                    back-end changes by issuing the following command:</t>
4937                    <t>
4938                        <list>
4939                            <t>SUBSCRIBE TOTAL_VOICE_COUNT</t>
4940                        </list>
4941                    </t>
4942                    <t>Server will start sending the following notification messages:</t>
4943                    <t>
4944                        <list>
4945                            <t>"NOTIFY:TOTAL_VOICE_COUNT:&lt;voices&gt;</t>
4946                        </list>
4947                    </t>
4948                    <t>where &lt;voices&gt; will be replaced by the new number of
4949                    all currently active voices.</t>
4950                </section>
4951    
4952                <section title="Number of MIDI instrument maps changed" anchor="SUBSCRIBE MIDI_INSTRUMENT_MAP_COUNT">
4953                    <t>Client may want to be notified when the number of MIDI instrument maps on the
4954                    back-end changes by issuing the following command:</t>
4955                    <t>
4956                        <list>
4957                            <t>SUBSCRIBE MIDI_INSTRUMENT_MAP_COUNT</t>
4958                        </list>
4959                    </t>
4960                    <t>Server will start sending the following notification messages:</t>
4961                    <t>
4962                        <list>
4963                            <t>"NOTIFY:MIDI_INSTRUMENT_MAP_COUNT:&lt;maps&gt;"</t>
4964                        </list>
4965                    </t>
4966                    <t>where &lt;maps&gt; will be replaced by the new number
4967                    of MIDI instrument maps.</t>
4968                </section>
4969    
4970                <section title="MIDI instrument map information changed" anchor="SUBSCRIBE MIDI_INSTRUMENT_MAP_INFO">
4971                    <t>Client may want to be notified when changes were made to MIDI instrument maps on the
4972                    back-end by issuing the following command:</t>
4973                    <t>
4974                        <list>
4975                            <t>SUBSCRIBE MIDI_INSTRUMENT_MAP_INFO</t>
4976                        </list>
4977                    </t>
4978                    <t>Server will start sending the following notification messages:</t>
4979                    <t>
4980                        <list>
4981                            <t>"NOTIFY:MIDI_INSTRUMENT_MAP_INFO:&lt;map-id&gt;"</t>
4982                        </list>
4983                    </t>
4984                    <t>where &lt;map-id&gt; will be replaced by the numerical ID of the MIDI instrument map,
4985                    for which information changes occurred. The front-end will have to send
4986                    the respective command to actually get the MIDI instrument map info. Because these messages
4987                    will be triggered by LSCP commands issued by other clients rather than real
4988                    time events happening on the server, it is believed that an empty notification
4989                    message is sufficient here.</t>
4990                </section>
4991    
4992                <section title="Number of MIDI instruments changed" anchor="SUBSCRIBE MIDI_INSTRUMENT_COUNT">
4993                    <t>Client may want to be notified when the number of MIDI instrument maps on the
4994                    back-end changes by issuing the following command:</t>
4995                    <t>
4996                        <list>
4997                            <t>SUBSCRIBE MIDI_INSTRUMENT_COUNT</t>
4998                        </list>
4999                    </t>
5000                    <t>Server will start sending the following notification messages:</t>
5001                    <t>
5002                        <list>
5003                            <t>"NOTIFY:MIDI_INSTRUMENT_COUNT:&lt;map-id&gt; &lt;instruments&gt;"</t>
5004                        </list>
5005                    </t>
5006                    <t>where &lt;map-id&gt; is the numerical ID of the MIDI instrument map, in which
5007                    the nuber of instruments has changed and &lt;instruments&gt; will be replaced by
5008                    the new number of MIDI instruments in the specified map.</t>
5009                </section>
5010    
5011                <section title="MIDI instrument information changed" anchor="SUBSCRIBE MIDI_INSTRUMENT_INFO">
5012                    <t>Client may want to be notified when changes were made to MIDI instruments on the
5013                    back-end by issuing the following command:</t>
5014                    <t>
5015                        <list>
5016                            <t>SUBSCRIBE MIDI_INSTRUMENT_INFO</t>
5017                        </list>
5018                    </t>
5019                    <t>Server will start sending the following notification messages:</t>
5020                    <t>
5021                        <list>
5022                            <t>"NOTIFY:MIDI_INSTRUMENT_INFO:&lt;map-id&gt; &lt;bank&gt; &lt;program&gt;"</t>
5023                        </list>
5024                    </t>
5025                    <t>where &lt;map-id&gt; will be replaced by the numerical ID of the MIDI instrument map,
5026                    in which a MIDI instrument is changed. &lt;bank&gt; and &lt;program&gt; specifies
5027                    the location of the changed MIDI instrument in the map. The front-end will have to send
5028                    the respective command to actually get the MIDI instrument info. Because these messages
5029                    will be triggered by LSCP commands issued by other clients rather than real
5030                    time events happening on the server, it is believed that an empty notification
5031                    message is sufficient here.</t>
5032                </section>
5033    
5034                <<section title="Miscellaneous and debugging events" anchor="SUBSCRIBE MISCELLANEOUS">
5035                  <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
5036                  the server by issuing the following command:</t>                  the server by issuing the following command:</t>
5037                  <t>                  <t>
Legend:
Removed from v.706  
changed lines
  Added in v.984
  ViewVC Help
Powered by ViewVC