Instrument definitions

MusE loadable Midi Instrument Definitions

File Extension ".idf"
Searched in "instruments" in "share" installation subdirectory (global) and in "~/.config/MusE/MusE/instruments" (user-specific). You can copy your own valid .idf files into the user-specific folder (MusE restart is necessary to make them visible in the Instrument Editor).
Can be viewed, created or edited with menu 'Midi -> Edit Instrument...'
In the Instrument Editor, when an existing instrument is modified and saved, a COPY of that instrument is saved in the user's "~/.config/MusE/MusE/instruments" directory, and it is used instead. This preserves original instruments while allowing modifications.

All found instrument definitions are presented by MusE in Settings->Config->MidiPorts in Pulldown in column "Instrument". They can also be selected directly from within a midi mixer strip.

You choose an appropriate Instrument for the playback device being used. For example if playing back to a Yamaha S-90 keyboard, choose Yamaha S-90. If the Yamaha model is not listed, it may be a Yamaha XG compatible device so try the more general XG. Similarly there is a more general Roland SG. More specific Instrument models are defined as well. When in doubt, or if all else does not seem to work, try GM (General Midi), it is always a safe bet with most devices, and is the default Instrument.

As of MusE-2.1 or so, Drum Maps can be integrated into the .idf file. The Instrument Editor has a facility for editing them. See the GM2, GS, or XG instruments for examples.

TODO: Formal specs.

Example of Instrument Definition File:

<?xml version="1.0"?>
<muse version="1.0">
  <MidiInstrument name="GM">
  
    <!-- Supported sysex messages: -->
    <!-- Notice that the enclosing F0 ... F7 are not required: -->
    <SysEx name="GM on">
      <comment>Switch General Midi mode on</comment>
      <data>7e 7f 09 01</data>
      </SysEx>
      
    <!-- Sysex event list which initializes instrument: -->
    <Init>
        <event tick="0" type="2" datalen="4"> 
            7e 7f 09 01           
            </event>
      </Init>
      
    <PatchGroup name="Piano">
       <Patch name="Grand Piano" prog="0"/>
       <Patch name="Bright Piano" prog="1"/>
       ...
      </PatchGroup>
    <PatchGroup name="Bass">
      <Patch name="Acoustic Bass" prog="32"/>
      <Patch name="Fingered Bass" prog="33"/>
      </PatchGroup>
    ...
    <Controller name="Pan" l="10" min="-64" max="63" init="0" />
    <Controller name="PitchBendSensitivity" type="RPN" h="0" l="0" max="24" init="2" />
    
    ...
    </MidiInstrument>
  </muse>

Notes

PatchGroups are not mandatory; its valid to write:

      <MidiInstrument name="GM">
        <Patch name="Grand Piano" prog="0"/>
        <Patch name="Bright Piano" prog="1"/>
        <Patch name="Acoustic Bass" prog="32"/>
        <Patch name="Fingered Bass" prog="33"/>
        ...
     </MidiInstrument>

An "Instrument Definition File" can define more than one Instrument, but it is recommended to use one file for one instrument
the "prog" parameter in a "Patch" is mandatory. Missing "hbank" or "lbank" are treated as "don't care". Missing "drum" is treated as drum="0".

A XG-Patch looks like:

<Patch name="Electro" drum="1" hbank="127" lbank="0" prog="24"/>
Prior to version 2.1:

A patch can be associated with a "mode" with one of
```
     1  - GM
     2  - GS
     4  - XG
```
Example:

<Patch name="Electro" mode="4" drum="1" hbank="127" lbank="0" prog="24"/>

Mode id's can be ore'd together for patches which are valid for more than one mode:

<Patch name="Grand Piano" mode=7" hbank="0" lbank="0" prog="0"/>

From version 2.1:

There is no 'mode' parameter. The selection of GM, GS, or XG instruments or other instruments with a sysex 'Init' section, determines what 'mode' the device is in.
example for MusE event (Sysex "XG-On"):

      <!-- Notice that the enclosing F0 ... F7 are not required: -->
      <event tick="0" type="5" datalen="7">
        43 10 4c 00 00 7e 00
      </event>

<Init> ... </Init> part can be omitted

From version 2.1:

This section contains initialization events to be sent to the devices upon certain changes such as device selection, change of instrument etc. Usually it contains a brief series of sysex commands such as (4) to set the device to a 'mode'.
Controllers have the following properties:

      name: arbitrary unique (short) string describing the controller
      
      type:     Controller7       regular 7-bit controller
                Controller14      14-bit controller
                RPN               registered parameter 7-bit
                NRPN              non registered parameter 7-bit
                RPN14             registered parameter 14-bit
                NRPN14            non registered parameter 14-bit
                Pitch             pitch mod wheel
                Program           program 
              From version 2.1:
                PolyAftertouch    key pressure controller
                Aftertouch        channel pressure controller

            Default Controller7 if omitted.
            Pitch Program PolyAftertouch and Aftertouch are convenience controllers which
             wrap functionality in one controller. They translate to and from the real midi messages
             which are behind the scenes such as Pitch -> midi 0xE0. Their controller numbers are
             internal and cannot be changed. PolyAftertouch is really an internal per-pitch controller.

      h:  controller number MSB. Default 0 if omitted.
      l:  controller number LSB. Defaultcontroller 0 if omitted.
            For per-pitch controllers, 'l' can also be "pitch" indicating each 'note' or
             'drum sound' has its own controller. Some devices such as XG or GM2 support this.

      min:  minimum value for controller
      max:  maximum value for controller
      init: reset value for controller; when controller value is
            undefined after instrument reset, use the ''undefined''
            value 0x10000

           The min/max/init values can be omitted
           Auto-biasing feature: If min is less than zero, such as with 
            pan = -64 -> 63, MusE automatically displays this range, 
            yet uses the true range of 0-127 'behind the scenes'.

From version 2.1:

  showType: Combination of 1: Show controller in drum tracks.
                       and 2: Show controller in midi tracks.
            Default is to show in both drum and midi tracks if omitted (same as "3").

Here is a per-pitch drum controller example from the XG instrument definition file:

<Controller name="Drum Pan" type="NRPN" h="28" l="pitch" min="-64" max="63" showType="1" />