instruments.xml documentation

Mis à jour il y a 5 jours

    Based on (https://docs.google.com/document/d/1aqL7PL90Ui45EjtxiBTYa4smhBb5zGNNCpk…)

    The goal of the document is to describe the syntax of the instruments.xml file. The document is not really aimed at developers but at MuseScore users familiar with XML and wishing to set up their own instrument definitions.

    instruments.xml files

    MuseScore uses one or two files, referred to as “instruments.xml” even if the filename is different, to define the instrument list displayed in the new score wizard, in the EditInstruments dialog box and in the the Staff propertiesChange Instrument... dialog box. An instrument is defined by its name, notation (brackets, barlines, staves, clefs, and noteheads, depending on the type of instrument), behaviors (transposition, playable range), sound (instrument(s) in the soundfont, articulations, midi controller settings).

    By default, MuseScore will use a single instruments.xml file. This "file 1" is embedded in the MuseScore binary for performance reasons. However users can change the instruments.xml file 1 in the Score tab in the EditPreferences dialog box. They can also define a second instruments.xml. The instruments.xml file 2 can define new Genres, new instrument groups, append new instruments to instrument groups, etc.
    The instruments subdirectory of the MuseScore installation directory has a model instruments.xml file and an up-to-date version can be found at (https://github.com/musescore/MuseScore/blob/master/share/instruments/in…)

    Translation

    TODO

    instruments.xml file definition

    museScore

    The museScore element is the container for all of the definitions for all of the instruments.

    museScore element - Genre (optional, multiple)
    museScore element - Articulation (optional, multiple)
    museScore element - InstrumentGroup (optional, multiple)

    Genre

    The Genre defines a type of music (e.g. orchestra, jazz) for which an Instrument is used. A given Instrument may be used in more than one Genre.

          <Genre id="klezmer">
                    <name>Klezmer</name>
          </Genre>

    Genre attribute - id (required)
    The id should be unique. Each instrument element defines the Genre or Genres in which the instrument is used.

    Genre element - name (required)
    The content is the name of the Genre. This is used in the instrument selection menu to list all the Instruments used in the Genre.

    Articulation

    An articulation modifies the velocity (loudness) and or gateTime (length) of a note.

          <Articulation name="marcatoStaccato">
                    <velocity>120</velocity>
                    <gateTime>50</gateTime>
          </Articulation>

    Articulation attribute - name (required)
    The name of the Articulation (e.g. staccato). Articulations defined for an Instrument take precedence over Articulations defined in the museScore element for all Instruments*.
    The name should correspond to an entry in the articulations palette:

    staccato, staccatissimo, portato, tenuto, marcato, sforzato (accent), sforzatoStaccato, marcatoStaccato, marcatoTenuto

    Articulation element - velocity (optional)
    The content is the velocity (loudness) multiplier in percent: 100% leaves the velocity unchanged. The % is optional.

    Articulation element - gateTime (optional)
    The content is the gate time (note length) multiplier in percent: 100% leaves the note length unchanged. The % is optional.

    Articulation element - descr (inactive)
    Currently not used. The description may be helpful for people editing the instruments.xml file in the future.

    InstrumentGroup

    Defines a type of instrument, e.g, Woodwinds, Brass, etc. An Instrument can only be defined in one InstrumentGroup, but it can be included in several InstrumentGroups by cross referencing using the ref element.

        <InstrumentGroup id="woodwinds">
            <name>Woodwinds</name>
            <Instrument id="flute">
                ....
            </Instrument>
            ....
       </InstrumentGroup>

    InstrumentGroup attribute - id (required)
    The InstrumentGroup id need not be unique within the instruments.xml files. If the id has already been used, then a new InstrumentGroup is not created but the Instruments defined in this element will be added to the previously defined InstrumentGroup.

    InstrumentGroup element - name (required)
    The content is the name used in the instrument selection menu to list all the Instruments in the InstrumentGroup.

    InstrumentGroup element - Instrument (optional, multiple)
    An Instrument as defined below

    InstrumentGroup element - ref (optional, multiple)
    The content is the id of an Instrument previously defined. The Instrument will be added to this InstrumentGroup and will appear in both groups. ref can be used in an InstrumentGroup in the instruments.xml file 2 to refer to an instrument in file 1.

    Instrument (common definitions)

    MuseScore handles three types of notation (with many variants): standard vocal and instrumental staves, tablatures and unpitched percussion staves. Much of the definition for an instrument is common to all these.

    Instrument attribute - id (required)
    The Instrument id must be unique. It is not only used internally but also for identifying the Instrument for the init element in another Instrument and for the ref element in another InstrumentGroup.

    Instrument element - init (optional)
    The content is the id of an Instrument previously defined. init copies most elements from the referenced Instrument into this Instrument.

    New elements can be added to the instrument and most existing elements can be redefined.

    init does not copy the genres: these should be redefined.

    Redefining staves, bracket, bracketSpans and barlineSpans can have unfortunate effects.

    Instrument element - longName (1 or more)
    Instrument element - shortName (1 or more)
    Used to define staff labels.

    longName / shortName attribute - pos (optional)
    Where where an Instrument has multiple staves pos is used to position the label. The value is 1 for the first staff, 2 between staff 1 and staff 2 etc. Even numbers are always between staves.

    The content is the label identifying the staves on the score. Usually there is only one longName and one shortName. The longName is used on the first system in the score and the shortName for all other systems. The longName is also used to display the Instrument in the instrument list if the trackName is not defined.

    Instrument element - trackName (optional)
    The content is the trackName used to display the Instrument in the instrument list and as the part name. If trackName is not defined, the first longName is used.

    Instrument element - description (inactive)
    Currently not used. The description may be helpful for people editing the instruments.xml file in the future. It should describe the instruments and give helpful information that cannot be found in the other elements.

    Instrument element - genre (optional, multiple)
    The content is a Genre id defined in the main museScore element. One or more genre (not Genre!!) elements are used to assign the Instrument to Genres. If an Instrument doesn’t have any genre elements, it will only appear in the Instrument list if the “All instruments” category is selected.

          <genre">
                    Klezmer
          </genre>

    Instrument element - musicXMLid (optional)
    The content is the MusicXML sound id for this Instrument. Not yet implemented, but MuseScore will use this id to import and export MusicXML files with the MusicXML id.

    Instrument element - staves (optional)
    The content is the number of staves for this Instrument, defaults to one.

    Instrument element - bracket (optional - only for multiple staves)
    The content is the type of bracket to use for joining staves. The value should be 0 for a normal bracket, 1 for a grand staff brace, 2 for a thin square bracket and 3 for a simple line.

    Instrument element - bracketSpan (optional - only for multiple staves)

    bracketSpan attribute - staff (optional)
    The first staff to bracket, numbered from 1, defaulting to 1.

    The content is the number of staves that are spanned by the bracket.

    The staff number plus the span should be no more that the number of staves + 1, otherwise the bracket will span to the next instrument.

    Instrument element - barlineSpan (optional - only for multiple staves)

    barlineSpan attribute - staff (optional)
    The first staff to for the spanning barline, numbered from 1, defaulting to 1.

    The content is the number of staves that are spanned by the barline.

    The staff number plus the span should be no more that the number of staves + 1, otherwise the barline will span to the next instrument.

    Instrument element - clef (optional)
    Instrument element - concertClef (optional)
    Instrument element - transposingClef (optional)
    Sets the clef to be used for a given staff for the Instrument. The clef element sets the clef for both concert pitch and transposed scores and parts; the concertClef element sets the clef for concert pitch only and the transposingClef element sets the clef for transposed scores and parts only.

    ...Clef attribute - staff
    The target staff for the Clef, numbered from 1, defaulting to 1.

    The content must be one of the following clef IDs.

    Clefs.png

    The definition for a piano, grand staff, would be

        <staves>2</staves>
        <bracket>1</bracket> <!-- Grand staff brace -->
        <bracketSpan>2</bracketSpan>
        <barlineSpan >2</barlineSpan>
        <clef>G</clef>
        <clef staff="2">F</clef>

    Instrument element - stafftype (optional)
    stafftype presets the number of lines in the staff, the type of notation and the clef. If the clef is also defined by a clef element, then the clef element takes precedence.

    stafftype attribute - staffTypePreset (required)
    This should be one of

    stdNormal,
    -- if the stafftype element content is standard;

    perc1Line, perc3Line, perc5Line,
    -- if the stafftype element content is percussion;

    tabBalajka,
    tab4StrSimple, tab4StrCommon, tab4StrFull, tabUkulele,
    tab5StrSimple, tab5StrCommon, tab5StrFull
    tab6StrSimple, tab6StrCommon, tab6StrFull, tab6StrItalian, tab6StrFrench,
    tab7StrCommon,
    tab8StrCommon
    -- if the stafftype element content is tablature.

    See (https://musescore.org/en/handbook/tablature#from_instruments) for an explanation of Simple, Common, etc.

    For example, for a guitar

        <stafftype staffTypePreset="tab6StrCommon">tablature</stafftype>    

    Instrument element - singleNoteDynamics (optional)
    Enables and disables single note dynamics (SND), varying the amplitude while a note is playing, see (https://musescore.com/marcsabatella/single-note-dynamics-demo).
    The default content is true (>0), enabling SND unless specifically disabled, for example for percussion and plucked instruments. To disable SND for plucked and percussion instruments the content should be false (0).

              <singleNoteDynamics>0</singleNoteDynamics>

    Instrument element - aPitchRange (optional)
    Instrument element - pPitchRange (optional)
    The amateur and professional ranges of the instrument.

    The content is a range of MIDI note numbers eg 50-89 for a clarinet.

    Amateur ranges are probably narrower than professional ranges, especially for woodwinds and voices. Notes outside the instrument's amateur range are greyed and notes outside professional range are highlighted in red.

    Instrument element - transposeChromatic (optional)
    Instrument element - transposeDiatonic (required if transposeChromatic is defined)
    transposeChromatic is used for transposing instruments to define the transposition interval between a transposed part and concert pitch.

    The content is the transpotition. If negative, the part sounds lower than written.

    transposeDiatonic should be set to the diatonic equivalent of transposeChromatic. For instruments (Bb and Eb) where there is no direct equivalent, a near equivalent should be used, -15, -8, -1, 6 ... for Bb and -12, -5, 2, 9 ... for Eb.

    Instrument element - Articulation (optional, multiple)
    An articulation defined for an Instrument takes precedence over the same articulation in the museScore element, see above.

    Instrument element - Channel (required, multiple)
    Instruments can have several channels defining the playback parameters. The first channel defined is used at the start of the score. The channel can be changed by adding stave text at the point in the score where the change is required and selecting the channel used for each voice in the stave text properties dialog box.

    Instrument (definitions for tablatures)

    Instrument element - StringData (required for tablatures)
    Defines the number of frets and the tuning for each string.
    Althrough the string data is required for a tabulature, it can also be defined for a standard notation Instrument. This Instrument can then be displayed on a standard staff or displayed as a tablature by setting the appropriate tablature style in the edit instruments menu.

    Instrument (definitions for unpitched percussion)

    Instrument element - drumset (required)
    The value should be true (>0) for an unpitched percussion instrument. Note that a "drumset" may include non-percussive, unpitched instruments such a whistle.

    Instrument element - Drum (multiple)
    Defines the sound, the staff line and the noteheads for each sound in the drumset such as snare, snare crossstick, snare rimshot ...

    ******************* End of Instrument definition ******************

    Channel and MidiAction

    A Channel defines a set of playback parameters, principally MIDI controls. A MidiAction is a mini Channel embedded within a Channel to allow a choice of multiple actions on activating a channel.

    The first Channel defined is activated at the start of playback.

    Channel attribute - name (optional for Channel, required for MidiAction)
    A Channel name is required if more than one Channel is defined in an Instrument. The Channel name and MidAction name are used in the Staff text property dialog box to select a channel for a voice and to select which of the MidiActions for a channel will be activated when the channel is activated.

    Channel element - mute (deprecated)
    Channel element - solo (deprecated)

    Channel element - synti (optional, Channel only)
    Selects the synthesizer.
    The default MuseScore synthesizer is Fluid which uses SF2/SF3 soundfonts. MuseScore also includes the Zerberus synthesizer which uses SFZ. The Aeolus synthesizer is not currently supported.

          <synti>Zerberus</synti> <!-- Select zerberus synthesizer -->

    Channel element - Controller (optional, multiple)

    Controller attribute - ctrl the MIDI continuous controller number
    Controller attribute - value the the value to be set.

    The most of the continuous controllers available and their functions are either defined in the soundfont or are specific to a synthesizer, but Bank Select is generally available.

    To set bank 17

            <controller ctrl="0" value="0" /> <!-- set sound bank number to 0 x 128 (MSB) -->
            <controller ctrl="32" value="17" /> <!-- add 17 (LSB) to sound bank number -->

    Channel element - program (optional)

    program attribute - value (optional)
    Sets a new MIDI program (instrument).
    Note that the value is the real value of the program in the soundfont (counting from zero) and not the value defined in the General MIDI tables (counting from one). If a soundfont is not documented, you can find all the program and soundbank numbers in the soundfont using a soundfont editor, for example Polyphone (http://www.polyphone-soundfonts.com).

    Channel element - descr (inactive)
    Currently not used. The description may be helpful for people editing the instruments.xml file in the future.

    Channel element - MidiAction (optional, multiple)
    An optional action (set midi controller and/or set program) that can be selected for the channel when the channel is activated in the stave text properties dialog box.

    StringData

    StringData element - frets (required)
    Number of frets for the instrument.

    StringData element - string (required, multiple)
    Tuning of a string as a MIDI pitch number. Uppermost string first.

    For a 5 string banjo:

          <StringData>
            <frets>19</frets>
            <string>67</string>
            <string>50</string>
            <string>55</string>
            <string>59</string>
            <string>62</string>
          </StringData>

    Drum

    Defines a sound for an unpitched Instrument

    Drum attribute - pitch (required)
    The content is the MIDI note number (pitch) for the sound.

    Drum element - head (recommended unless noteheads is specified)
    The content is the notehead group to use for this sound. Specifying the notehead group number is deprecated: the notehead group name is required. The default and the fallback if the name is not recognized is normal.

    Each notehead group defines a set of four noteheads for "black" notes (quarter notes / crotchets and shorter), half notes (minims), whole notes (semibreves) and double whole notes (breves).

    The notehead group may be one of the standard groups for percussion
    normal, cross, plus, xcircle | withx, triangle-up, triangle-down, slash perc 0-7s.png
    slashed1, slashed2, diamond, diamond-old | circled, circled-large perc 8-13s.png

    or one of the oddities
    large-arrow, do, re, mi | fa, (no so), la, ti perc 14-20s.png

    Drum element - noteheads (optional)
    Sets the the noteheads for "black" notes (quarter notes / crotchets and shorter), half notes (minims), whole notes (semibreves) and double whole notes (breves) individually using internationally recognized names. noteheads takes precedence over head.

    noteheads has four, optional, elements defining the noteheads for each length note: quarter for "black" notes, half for half notes /minims, whole for whole notes / semibreves and breve for double whole notes / breves.

    The noteheads equivalent of the notehead group slashed2 is

        <noteheads>
            <quarter>noteheadSlashedBlack2</quarter>
            <half>noteheadSlashedHalf2</half>
            <whole>noteheadSlashedWhole2</whole>
            <breve>noteheadSlashedDoubleWhole2</breve>
        </noteheads>

    Any noteheads from the SMuFL ranges Noteheads, Slash noteheads, Round and square noteheads and Shape note noteheads can be used.

    For unpitched percussion instruments, you may only ever need black noteheads. If the notehead definition for any note length is omitted, the notehead defaults to normal.

    Drum element - line (recommended)
    The content is the staff line to use for this sound. 0 is the top line, 1 the top interline and so on. The default is -1. This is not guaranteed.

    Drum element - voice (recommended)
    The content is the preset voice to use for this sound: a number between 0 and 3, corresponding to staff voices 1 to 4. The default is 0 (staff voice 1). This is not guaranteed.

    Drum element - name (required)
    The content is the name of the sound. This is the tip text for the sound in the drum palette and name of the sound in the Edit drumset dialog box.

    Drum element - stem (recommended)
    The content is the preset stem direction: 0 for automatic. 1 for up and 2 for down. Defaults to up for voice 0 or 3 (staff voice 1 or 4) and defaults to down for voice 1 or 2 (staff voice 2 or 3).

    Drum element - shortcut (optional)
    The content is the shortcut for this sound which should be a letter between A and G.

    Tip
    Rather than typing in a large set of drum definitions, in particular the noteheads, use the Edit Drumset dialog box to set up the the definitions of all the sounds and save it as .drm file. This file has all the drum elements for the instrument in the same format as in instruments.xml and you can simply copy them across.