Soundfont, MIDI velocity and instruments.xml

Updated 1 week ago

    While MuseScore 4 is bringing VSTi support along with the ability to use commercial sound libraries which often sound great and expensive, SF2/SF3 soundfonts and SFZ soundfonts will continue to be compatible through use of VST wrappers

    Default dynamics MIDI velocity and MIDI velocity output dB conversion

    MuseScore has default velocity for each dynamics symbols. The default MuseScore_General.sf3 soundfont is edited with the following dB level aim in mind
    Based on this doc dB is calculated is as follows:
    L(dB) = 40 log (MIDIVelocity/127)

    Musescore 3.6.2 by default adds a 10% headroom to instrument, so that the default 100/127 as seen in the Mixer is 90% volume of soundfont sample. Full volume soundsample would be ~111/127 volume in Mixer. The 127 in Mixer is an arbitrary number, it is not related to MIDI velocity.

    Velocity full volume sample dB Musescore 3 Dynamics
    127 0.0dB ffff, fffff, ffffff
    126 fff
    112 -2,2dB ff
    96 - 4.8dB f
    80 - 8.0dB mf
    64 -11.9dB mp
    48 -16,9dB p
    32 -23.9dB pp
    16 -36.0dB ppp
    10 pppp
    8 -48,0dB
    5 ppppp
    4 -60,0dB
    2 -72,1dB
    1 -84.15dB pppppp
    0 -Infinity


    This page describes the syntax of the instruments.xml file, is aimed at MuseScore users familiar with XML and wishing to set up their own instrument definitions.

    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 here

    To change instrument in Musescore visit Change instrument set-up

    Copy and paste method

    You may not need to learn the xml definition
    Edit and finalize your custom soundfont, load soundfonts in synthesizer, keep default soundfont as 1st, order others as desired, click Set as default, then don't rearrange Banks and Presets in your soundfonts and don't rearrange the order of soundfonts in the synthesizer anymore , because these affects what your custom instruments.xml point to.
    New score, add instruments, choose sound you desire in Mixer, save as mscx.
    Open mscx as plaintext and see its instrument definition , copy and paste to create custom instruments.xml.

    Understanding two types of sound

    • Non-percussion
      • Musescore3's default use different Preset to represent different instruments , it may be from GM
      • Musescore use Bank in a way that seems different from other app and mainstream MIDI keyboards. Don't want to learn what MSB, LSB, BankSelect are? Use an editor that show Bank number directly.
      • Musescore3's default use Bank 0 as default normal sound for each instrument and Bank 17 for instruments' Expressive version = Single note dynamics = CC2 attenuation modulator instead of the default Note-On velocity modulator. To use SND, also set <singleNoteDynamics>1</singleNoteDynamics>, it is equal to ticking the Use Single Note Dynamics box in Staff properties
      • You are free to use any Bank and Preset number, just make sure <channel> points to the correct sound.

    Default soundfont's Bank 0 Preset 0 = Piano normal
    Default soundfont's Bank 0 Preset 12 = Marimba normal
    Default soundfont's Bank 0 Preset 24 = Guitar open
    Default soundfont's Bank 0 Preset 41 = Violin arco non expressive (no SND)
    Default soundfont's Bank 17 Preset 41 = Violin arco expressive (SND)

    • Percussion
      • To use the Drumset palette in Input mode, you must use a percussion sound.
      • <drumset>1</drumset> is equal to Ticking the Drumset checkbox in the Mixer
      • Percussion sound has a keyboard layout that's different from other instruments: each note represent a different sound sample. It may be from Percussion layout in GM
      • <Drum pitch=n> defines the sound sample to be represented by that pitch/note, its staff appearance eg position on staff, notehead etc, and its input keyboard shortcut.
      • Musescore default xml use default soundfont's Bank 128 for percussion and different Preset for different taste/style.
      • You are not restricted to use 128, any Bank and Preset number will work if <channel> points to the correct sound and <drumset>1</drumset>.

    Default soundfont's Bank128 Preset 0 = Standard Kit
    Default soundfont's Bank128 Preset 16 = Power Kit
    Default soundfont's Bank128 Preset 48 = Orchestra Kit
    Pitch 36=Bass Drum 1
    Pitch 38=Acoustic Snare

    file definition

    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)


    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">

    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.


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

          <Articulation name="marcatoStaccato">

    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.


    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">
            <Instrument id="flute">

    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)
    As of MuseScore 3.6.2, referencing and re-using / re-positioning of instrument is not working.
    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.
    As of MuseScore 3.6.2, referencing and re-using / re-positioning of instrument is not working.

    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.


    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.


    The definition for a piano, grand staff, would be

        <bracket>1</bracket> <!-- Grand staff brace -->
        <barlineSpan >2</barlineSpan>
        <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

    -- if the stafftype element content is standard;

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

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

    See Tablature for an explanation of Simple, Common, etc.

    For example, for a guitar

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

    Instrument element - singleNoteDynamics (optional)
    see also how to setup CC below
    Enables and disables single note dynamics (SND), varying the amplitude while a note is playing
    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).


    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) {#Channel}
    see also example below
    A Channel defines a set of playback parameters including sound.

    Channel attribute - name (optional)
    required if more than one Channel is defined in an Instrument.

    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 -->

    wiki bookmark

    Channel element - Controller (optional, multiple)
    controller attribute - ctrl the MIDI continuous controller number
    controller attribute - value the the value to be set.
    see also example below
    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.
    In Fluid synthesizer, Bank Select refers to selecting the bank (MSB and LSB), or the Bank number shown in Polyphone
    Expected behavior:
    ctrl_0_value and ctrl_32_value refers to MSB and LSB
    eg To will use Bank 17 of a soundfont

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

    As of MuseScore 3.6.2, when using multiple SF2/SF3 soundfonts, ctrl_0_value and ctrl_32_value will not work as simply as you may expect.
    Total number of banks are accumulated and use to calculate and affect what these two numbers refer, meaning what they refer to varies with

    • the number of soundfonts used in Fluid synthesizer
    • the ordering in Fluid synthesizer
    • the number of occupied banks in each soundfont (except the last)

    One way to handle the problem is to make sure all soundfonts have the number 128 bank occupied, then
    refer the 1st ordered soundfont with expected ctrl_0_value(=0) and expected ctrl_32_value,
    refer the 2nd ordered soundfont with expected ctrl_0_value(=1) and expected+1 ctrl_32_value,
    refer the 3rd ordered soundfont with expected ctrl_0_value(=2) and expected+2 ctrl_32_value.
    Bank 0 in 1st soundfont ,use ctrl_0_value=0 and ctrl_32_value=0
    Bank 0 in 2nd soundfont ,use ctrl_0_value=1 and ctrl_32_value=1
    Then instruments.xml will refer correctly each time if the ordering in Fluid synthesizer stay the same
    See example below

    Channel element - program (optional)
    program attribute - value
    see also example below
    This refers to selecting the MIDI program, counts from zero.
    In General MIDI definition it refers to a particular instrument.
    It is the Preset number shown in Polyphone
    Note the official General MIDI documentation table, preset is count from one.

    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.

    Instrument (definitions for tablatures)

    Instrument element - StringData (required for tablatures) {#StringData}
    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.

    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:


    Instrument (unpitched percussion)

    Instrument element - drumset (required) {#drum}
    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 ...

    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


    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.

    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.

    Single Note Dynamics (SND) and Set up MIDI CC

    Musescore use Single Note Dynamics (SND) if <singleNoteDynamics>1</singleNoteDynamics>, it is equal to ticking the "Use single note dynamics" checkbox in Staff/Part properties
    To support SND in sf2/sf3, edit Instrument modulator and/or Preset modulator and change from velocity to MIDI CC, screenshot below shows an example using Polyphone, more info visit Polyphone manual. Default SND use MIDI CC 2. Open and study the default MuseScore_General.sf3 soundfont to know more.
    Attenuation value in sf2 use a 1200 cents based value, for more info search for official soundfont definition document.

    Channel terminology

    Channel defined in instrument.xml falls under one instrument, multiple channels of the same instrument can be seen in a folder like manner in the Mixer. Use multiple channels to simulate different articulation or playing technique. Number of channel is unrelated to number of voices (four voices in one instrument). eg expand a default violin to see 3 channels: arco, tremolo and pizzicato.
    Do not get it confused with MIDI Output Port and Channel.

    Illustrated example with soundfont created using Polyphone

    This soundfond MuseScore_GumGum.sf3 is created using Polyphone, consider this Bank 6 Preset 41 sound
    When loaded as the 1st soundfont in Fluid Synthesizer. To refer to this sound use this channel setting

    <Channel name="cres1">  
      <controller ctrl="0" value="0"/><!-- 1st soundfont = 0 -->
      <controller ctrl="32" value="6"/><!-- 1st soundfont use bank = 6 -->
      <program value="41"/><!-- preset -->

    When loaded as the 2nd soundfont in Fluid Synthesizer, so that default soundfont MuseScore_General.sf3 can also be used. Since MuseScore_General.sf3's Bank 128 is occupied, to refer to the above sound use this channel setting

    <Channel name="cres1">  
      <controller ctrl="0" value="1"/><!-- 2nd soundfont = 1 -->
      <controller ctrl="32" value="7"/><!-- 2nd soundfont use bank+1 = 6+1 -->
      <program value="41"/><!-- preset -->

    Change sound/articulation sample of an instrument in the middle of your music

    Not to be confused with Mid-staff instrument changes.
    You can switch to another sound/articulation inside your multi-sound instrument defined using multiple <Channel name=xxx>.
    Each voice of the four voices in an instrument use its own sound. To change sound, add Staff text, in the property dialog box, select a sound for the selected voice, it is the Channel name in xml.
    set Channel name="pizzicato" in xml, see above inside Musescore
    This edited staff text can be reused, an example saved palette item extracted/unzipped and open as plaintext look like this

    <Cell name="SoftStart 1" custom="1">
      <channelSwitch voice="0" name="cres1"/> <!-- name=Channel name defined in xml-->
      <channelSwitch voice="1" name="cres1"/>
      <channelSwitch voice="2" name="cres1"/>
      <channelSwitch voice="3" name="cres1"/>
      <color r="0" g="170" b="0" a="255"/>

    Staff text: staff does not means one staff on a score paper in real world sense, it represents the whole instrument. ie. piano have two staffs, Staff text affect the whole piano.
    Staff text property's MIDI actions tab is probably, like many ancient UI in MuseScore, outdated and not working.