Instruments.xml documentation

Updated 3 years ago

Taken from (https://docs.google.com/document/d/1aqL7PL90Ui45EjtxiBTYa4smhBb5zGNNCpk…)

The goal of the document is to describe the syntax of instruments.xml. The document is not really aimed at a developer audience but more an average savvy MuseScore user.

MuseScore uses one or 2 files, often designed as “instruments.xml”, to define the instrument list displayed in the new score wizard, in EditInstruments and in the Change Instrument dialog (Staff propertiesChange Instrument). An instrument in this list is not just a name, but also defines several behaviors (transposition, range), sounds (articulations, which synthesizer to use, which sound to use in the soundfont).

Cascading

By default, MuseScore will load a single instruments.xml file. This file is not accessible and embedded in the MuseScore binary for performance reason. However users can change the primary instruments list file in Edit &arr; Preferences. They can also define a secondary instruments list file. The secondary file can define new instrument groups, append new instruments to instrument groups, change properties of instruments etc...

Translation

TODO

Attributes and elements

Attributes and elements are used only once or noted as follow

* → 0 or more
+ → 1 or more

Attributes and elements are optional or noted as required

museScore

Top element.

Attributes

no attributes

Elements

Genre

Attributes

•id (required)
The id should be unique and is used in each Instrument declaration to indicate that an instrument is part of a genre.

Elements

•name (required)
The name of the genre. The string will be used in the user interface to describe the genre.

Articulation

Attributes

•name
The name of the articulation. It’s used as an id to store the articulations for a given instrument. Articulation can be defined globally in museScore for all instruments, in each Channel for an Instrument and in an Instrument. They are overridden in this order.
Name is also used internally to match a symbol with the desired effect defined by this element in instruments.xml. The possible values are “fermata”, “shortfermata”, “longfermata”, “verylongfermata”, “thumb”, “sforzato”, “espressivo”, “staccato”, “staccatissimo”, “tenuto”, “portato”, “marcato”, “ouvert”, “plusstop”, “upbow”, “downbow”, “reverseturn”, “turn”, “trill”, “prall”, “mordent”, “prallprall”, “prallmordent”, “upprall”, “downprall”, “upmordent”, “downmordent”, “pralldown”, “prallup”, “lineprall”, “schleifer”, “snappizzicato”, “tapping”, “slapping”, “popping".

Elements

•velocity
velocity change: -X00% - +X00%. The velocity of a note with this articulation will be multiplied by this percentage. The % is optional.

•gateTime
gate time change: -X00% - +X00%. The duration of the note with this articulation will be multiplied by this percentage. The % is optional.

•descr
A string description of the Articulation. Currently not used.

InstrumentGroup

Attributes

•id (required)
The Instrument group id is used by the cascading mechanism. If the secondary instruments.xml file uses a previously defined id, the instruments are added to the same group.

Elements

•name
The name of the group as it will appear in the user interface.

Instrument
An instrument as defined below

•ref
The id of an Instrument previously defined. The Instrument will be added to this InstrumentGroup on addition to the group it belongs. Of course, the InstrumentGroup can be defined in the secondary instruments.xml file and the instrument in the primary one.

Instrument

Attributes

•id (required)
The unique id of the instrument is used to refer to it in the secondary instrument list file, or in the init tag of an instrument to initialize an instrument with the value of another one. The id can also be used with the ref element of a InstrumentGroup to add an instrument to several groups without writing its full definition again.

Elements

  • longName* +
  • shortName* +
    ◦pos attribute: For certain instrument (like organ) it might be necessary to have long and short names for each staff or between staff. It’s the purpose of the the “pos” attribute. 1 is in front of the first staff, 2 is between staff 1 and 2 etc… Even number are always between staves

Usually there is only one long name and short name. The long name is used on the first system in the score and the shortname for all other systems. The long name is also used to display the instrument in the list if trackName is not defined.

•description
Currently not used. The description is helpful for people editing the instruments.xml file in the future. It should describe the instruments and give information that can’t be found in the other parameters but could be helpful.

•trackName
The trackName is used to display the instrument in the list. If trackName is not present, the first longName is used

•musicXMLid
The MusicXML sound id for this instrument. Not yet implemented MuseScore will use this id to import and export MusicXML file with the right MusicXML id

•staves
The number of staves for this instrument

clef
◦staff: the staff index, 1 based. If not present, 1 is assumed.
The clef for a given staff, the first one by default. This will set both concert and transposing clef. Possible values are "G", "G8va", "G15ma", "G8vb", "F", "F8vb", "F15mb", "F3", "F5", "C1", "C2", "C3", "C4", "TAB", "PERC", "C5", "G1", "F8va", "F15ma", "TAB2"

•concertClef
•transposingClef
The clef to be used in concert or transposing mode. Possible values are the same than for the clef element.

•stafflines
Number of staff lines.

•drumset
>0 if the instrument should use a drumset

•[Drum}(#drum)
Drumset definition.

•bracket
◦staff the starting staff for the bracket. First staff if not present.
The type of bracket to use. 0 normal bracket, 1 grand staff brace, 2 square brace, 3 line brace

•bracketSpan
◦staff the starting staff for the bracket. First staff if not present.
The bracket span in number of staves.

•barlineSpan
◦staff the starting staff for the barline. First staff if not present.
The barline span in number of staves.

•aPitchRange
•pPitchRange
The amateur and professional ranges of the instrument in MIDI pitches. Amateur ranges are probably smaller than professional one, especially for woodwinds, or voices. Notes out of the instrument's range are marked in yellow for amateur and red for professional.

•transposeChromatic
•transposeDiatonic
Used for transposing instruments and define the diatonic and chromatic intervals that will be used on playback and while switching to concert pitch.

Channel
Instruments can have several channels switchable with staff text. See how violin or trumpet are described. Channel will describe the sound used to play the instrument.

•Articulation
Override the articulations defined in Channel if it has the same name.

•[genre](#genre}
One or more genre elements with genre id defined at the start of the file. If an instrument doesn’t have any genre element, it will only appear if the “All instruments” category is selected.

•StringData
Define the number of frets and strings tuning for a tablature instrument.

•init
An instrument id to initialize the current instrument from.

•stafftype

◦staffTypePreset A staff type preset among "stdNormal", "perc1Line", "perc3Line", "perc5Line", "tab6StrSimple", "tab6StrCommon", "tab6StrFull", "tab4StrSimple", "tab4StrCommon", "tab4StrFull", "tabUkulele", "tabBalajka", "tab6StrItalian”, "tab6StrFrench". Default to “stdNormal”.

The content of the element can be “standard” (the default), “tablature” or “percussion” and should match the staffTypePreset. This will override the stafflines element.

StringData

Attributes

no attributes

Elements

•frets
Number of frets for the instruments

strings
Tuning of the string as a MIDI pitch number. Top string first.

Channel

Attributes

•name (optional)
A name should be present if more than one Channel is defined in an Instrument. The Channel name is used in the Staff text property dialog to switch the program number at this position in the staff.

Elements

•program
◦value
A program change event and the General MIDI program number that will be used to select the sound in the soundfont at the start if the song. It is 0 indexed: Acoustic Grand Piano. See General MIDI for others.

Controller
◦ctrl
◦value
A controller change event with ctrl the controller number and value the controller value that will be sent at the start of the song. It can be used to select a bank before sending the program change event for example.

Articulation
Define new articulations or override the global ones.

•descr
Used in the user interface in Staff Text properties dialog

•synti
The default synthesizer is the SF2/SF3 based one. This element can be used to override the default. It’s notably used for the Pipe Organ definition to use the Aeolus synthesizer instead of SF2/SF3.

•mute
•solo
Mute or solo this channel by default.

MidiAction
MIDI actions associated with the channel. These actions will be appended to the program and controller definition and be added to the Staff Text property.

MidiAction

Attributes

•name

Elements

•program
◦value

Controller
◦ctrl
◦value
see Controller and program in Channel

•descr
Used in the user interface in Staff Text properties dialog

Drum

Defines a drum note

Attributes

•pitch (required) A MIDI pitch number

Elements
•head
The notehead to use for this note

•line
The staff line to use for this note. 0 the top line, 1 the top interline and so on. One line staff uses the top line of a normal 5 line staff.

•voice
The voice to use for this drum note, a number between 0 and 3

•name
The name of the drum in the Edit drumset dialog

•stem
Stem direction 0 Automatic. 1, Up. 2 Down.

•shortcut
A shortcut for this drum note. A letter between A and G.