
    Tones and Keymaps File Structure
    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~


    All keywords must start a new line
 
    <----> : name
    [    ] : optional
    {    } : repeated as required
  


    Tones File
    ----------
 
    GENERATION <1,2,3>   (Defines how the MSB and LSB values are interpreted)

    {
    SECTION <section name>

    WITHGROUPS=<TRUE,FALSE>
    WITHSTYLES=<TRUE,FALSE>
    WITHKEYMAP=<TRUE,FALSE>
    [MSB=<msb value (0-127)>]
    [LSB=<lsb value (0-127)>]
    
    Then Either:
    
       {
       GROUP <Group name>
 
          {
          #<program no> <Tone name> [: {<style no>,<style name>;}]
          }
      
       }
    
    Or:
      
       {
       #<program no> <Tone name> [: {<style no>,<style name>;}]
       }
    
    END
 
 
    Generation 1 instruments only have one SECTION and no MSB and LSB numbers.
    WITHGROUPS=FALSE and WITHSTYLES=FALSE

    Generation 2 instruments only use the MSB number

    Generation 3 instruments use both MSB and LSB numbers

    Sections with grouped instruments have WITHGROUPS=TRUE
    Sections with listed instruments have WITHGROUPS=FALSE

    Sections with styles have WITHSTYLES=TRUE and no LSB number
    Sections without styles have WITHSTYLES=FALSE and an LSB number
 
 
    Keymaps File
    ------------
    
 
    GENERATION <1,2,3>
 
    {
    SECTION [<section name>]
    [MSB= <msb value (0-127)>]
    [LSB= <lsb value (0-127)>]
    
       {
       K<key number (middle C = 60)>  [<global name>:] [{#<program change number>,<specific name>;}]
       }

    }
    
    END
 
 
    The keymaps file has a similar structure to the tones file and the
 same comments about generation instruments apply.
 
    Where named notes are applied to one program change number only (eg
 a GM instrument with a drumkit on voice 99) a typical line will look
 like this:
 
    K34  #99,Open Rim Shot
 
    Where named notes are applied to a whole section with minor changes
 between program change numbers a typical line would look like this:
   
    K34  Open Rim Shot    :#2,Open Rim Shot 2
 
    This will name key 34 as 'Open Rim Shot' for all program change numbers
 except for #2 which it will name as 'Open Rim Shot 2'
 

    Technical note on Bank Change messages
    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    
    The normal way to allocate a voice to a channel is with a Program
 Change message. This method is limited to 128 voices. Modern
 instruments greatly extend the range of available voices by using Bank
 Change messages of which there are two - called MSB and LSB. To
 specify a particular voice, therefore, three numbers are required: the
 MSB, the LSB and the Program change number. With lamentable
 predictability however, different manufacturers have interpreted the
 meaning of the MSB and LSB bank change messages differently. For this
 reason, Rhapsody4 has adopted the following convention.
 
    The highest level number is called the SECTION number. This
 typically switches from instruments to drumkit or sound effects mode.
 
    The middle level number is the TONE number. In instrument mode,
 this typically selects the voice. In drumkit mode, it may switch
 between sets of drumkits etc.
 
    The lowest level is the STYLE number. This typically changes the
 basic voice in some way or other, eg by detuning it or adding
 brightness etc.
 
    First generation instruments only respond to program change message
 - ie the TONES number.
 
    Second generation instruments interpreted the MSB of the bank
 change message as the STYLE number. The LSB was assumed to be zero.
 
    Third generation instruments use the MSB as the SECTION number and
 the LSB as the STYLE number.
 
    In order to tell Rhapsody what kind of instrument is present, every
 Tones file should have a GENERATION directive at the beginning.
 
    For each SECTION, there should be a directive informing Rhapsody
 what MSB and/or LSB to use.


    GROUPS and LISTS
    ~~~~~~~~~~~~~~~~

    For convenience, Rhapsody can be directed to divide the list of TONES
 (which can be 128 items long) into GROUPs containing individual tones.

    Where only a few program change numbers are used, eg in a collection of
 drumkits, a single LIST can be used instead.
  
 
  