and more

The mScore.js XML file format

There are several ways to feed a musical score into mScore.js for display:

When you write a score file yourself, or get one from an archive or database, it will typically be in the XML format, so this is what you need to know about. This page explains how an mScore.js XML file works and what elements it contains.

  1. An mScore.js XML file
    1. XML essentials
    2. The structure of an mScore.js piece
  2. General information
    1. The style element and colors
  3. Parts
    1. Staves
    2. Voices
  4. Musical content
    1. The voice content element
    2. Rhythm patterns and macros
  5. Full file examples

An mScore.js XML file

XML essentials

All mScore.js XML files look like this:

<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE mScore> <mScore> ... everything goes in here ... </mScore>

XML has lots of features and syntax rules which do not have to concern you, and which mScore.js does not use in any case. Below is the essential minimum which you should know. Skip this part if you are already acquainted with XML.

You will notice that the first two lines in example File are no proper XML elements; they are called the XML declaration and the document type declaration. They are not strictly necessary, but we strongly recomment you include them. The attribute encoding must match the format in which your text editor is saving the file; it only matters for special characters (diacritics, umlauts, and worse).

<mScore> ... </mScore> is the file’s root element and all data goes into it.

The structure of an mScore.js piece

An mScore.js musical piece consists of three types of data:

This basic structure of mScore.js pieces applies not only to XML files but to all methods of data input.

General information

The first lines inside an mScore.js XML file’s root mScore element are usually various kinds of additional information about the piece. mScore.js will use the following elements

elementused fordefault value
titledisplaying error messages“Untitled”
keykey which the piece begins withC major (i.e. no accidentals)
tempometronomic tempo for audio playback120 bpm
stylesee section below

If you omit any of them, its default value is used. Note that this list includes no composer element: This element and many others like it can be added to the XML file, and usually are; but they are not used by mScore.js for anything. The job of mScore.js is to draw the actual musical material on a screen canvas. Putting title, composer, tempo, opus number and similar around it on the HTML page is the responsibility of the JavaScript code using the mScore.js package. One example of this is the mScore.js showcase page. Below is a list of XML elements which mScore.js will recognize in its current version and put into the piece for later retrieval by JavaScript:

composer, composerExtra, opus, subtitle

The style element and colors

The element <style> ... </style> contains all kinds of settings which specify how to display the score, such as how to align staves (left, right, justified etc.), or how to display tuplets (under what circumstance to display an angled bracked under the number).

— There are no style settings defined as yet, but they will be added in an upcoming version! —

One important element which can appear inside style is colors. It contains a list of color elements, each of which defines a color to use in the piece. In the content element(s) of the piece there can appear color switches which will make that voice’s content following the switch be displayed in the specified color. For example

<style> <colors> <color/> <!-- no color value → use default = black --> <color>#cd4c77</color> <!-- hexadecimal RGB value --> <color>SeaGreen</color> <!-- you can also use predefined web colors --> </colors> </style>

These colors get numbered consecutively — 1, 2, 3 in example Colors above. There is usually no need to define a black color, because default-black always stays available in content as “color zero”.


A part represents a single instrument or player or voice in a choir. A score can have one or many parts. They are written into the XML file as

<part> ... instrument, staves and voice definitions etc. go here ... </part>

If your score contains only a single part, you can omit the enclosing <part> ... </part> tags, but you absolutely need them if there’s several parts.

The most important element that goes in a part description is <instrument>instrumentName</instrument>, where “instrumentName” is the instrument or singing voice of the part. It is recommended to put nothing more fancy than just the name, or the name followed by a number (e.g. “Violin 2”) there, so that mScore.js can identify the instrument to select the correct playback sound and and stave preset. But you are always free to specify any instrument you want and set the playback instrument manually as an attribute:

<part> <instrument playback="piano">Steinway D-274</instrument> <staveset preset="piano"/> ... voice definitions etc. go here ... </part>

Besides the instrument, as of version ?? only stave and voice definitions go inside parts, but more elements may get added in later versions.


The staveset element describes how the part is layed out into staves, in particular how many to use (usually one or two), and what clefs to start with. You can specify the staves manually or use default stave structures for chosen instruments. In example Staves below both variants do the same thing: Two staves, both starting with a G clef (as is used e.g. in Debussy’s Clair de Lune).

<staveset> <stave clef="G"/> <stave clef="G"/> </staveset><staveset preset="piano"> <stave idx="2" clef="G"/> </staveset>

If you do not specify a stave preset, mScore.js attempts to identify one from the part’s instrument element. Failing that, the fall-back default is a single stave with a G clef.

The purpose of manual stave descriptions is to modify the values coming from the preset; you can also use them to add more staves to the staveset. By default, the stave elements in the staveset pertain to the staves 1, 2, etc., but you can also skip some of them (if they are fine with their default values) by specifying the next one’s idx attribute (as example Staves.2 above shows).

Note: As of version ?? the only available stave attribute besides idx is clef, which accepts the values F and G. Expect more in upcoming versions.


Musical scores traditionally consist of one or several voices; using several ones in one part (instrument) allows you among other things to have concurrent notes of different durations (note values). Some musical typesetting programs limit you to a maximum of four voices per instrument, in mScore.js you can use any number you want. The simplest way to define voices for a part is <voices number="n"/>, where “n” is the number you want. If you omit the attribute (or the whole voices element), a single voice is created.

You can also manually define/modify voices by putting voice/ elements inside <voices> ... </voices>. As with staves, voices are listed ordered by index and you can skip some by specifying the following one’s idx attribute. Additionally, if all or most voices share an attribute value, you can specify it once in the enclosing voices element — see examples Voices.2–4 below, where stem="up" gets used as default for all three voices, except the 2nd, which has it manually set to down.

<voices> <voice stem="up"/> <voice stem="down"/> <voice stem="up"/> </voices><voices stem="up"> <voice/> <voice stem="down"/> <voice/> </voices>
<voices stem="up"> <voice idx="2" stem="down"/> <voice/> </voices><voices number="3" stem="up"> <voice idx="2" stem="down"/> </voices>

As of version ?? the following attributes are available for voices. Most of them can also be set inside the content elements that use this voice (using appropriate switch commands), but it’s usually more tidy to write the voice attributes instead.

attributemeaningpossible valuesdefault value
(idx)voice indexbetween 1 and number in voices (if specified)idx of prev. voice + 1
colorwhich color to use for the voicebetween 0 and the number of defined colors 0 (= default-black)
restPosvertical position of restsa signed integer 0
stavewhich stave the voice lies inbetween 1 and the number of staves 1
stemOrientation of note stemsauto, up, down, or inbetweenauto

Musical content

The voice content element

After you have defined the parts (instruments) of your piece, it is time to put some music in it. You do this by adding one or more <content> ... </content> elements inside <mScore> ... </mScore>. Inside them go the piece’s notes, chords, rests, bar lines, ties, everything. Because writing that sort of content in a strictly XML style would be extremely cumbersome, mScore.js uses its own language for it. The voice content language is the central element of learning and using mScore.js and it is the same whichever method is used to create an mScore.js piece (remember that XML files are just one of the methods). The rest of this manual (i.e. the following pages) mostly deal with explaining the numerous features of the voice content language. You may start here.

A content element can also accept a number of attributes:

voicesA comma-separated list of the following types of items:
  • A number: Taken to be a voice index of the first part of the piece — the best thing to use when there is only one part.
  • A number prefixed with #: Taken to be the index of a part; all voices of the part are added to the list.
  • A number prefixed with #, followed by a comma-separated list of voice indices enclosed in square brackets: Certain voices from that part (see example Contents).
Omitting the attribute will select all voices of all parts.
pickupIf this is set to yes (default no) this content will start with „bar zero“, i.e. an anacrusis or pickup.

A content element will always contain full bars (i.e. end at a barline). If you have more than one content containing the same parts/voices (you can put the voices of one part into seperate content elements if you want) each new content will start after the latest bar reached by any of its voices. For example

<content voices="#1[1,3], #2"> (assume we put 8 bars here) </content> <content voices="#1"> (more content) </content>

In example Contents the first content adds eight bars of material to the first and third voices of the first part and to all voices of the second part. The second content thus starts in the ninth bar in all voices of the first part. It does not matter that its second voice has no content yet; since all voices in a content must start in the same bar, those voices that are not there yet will skip some bars (i.e. be tacet).

If you specify pickup="yes", and any one of the voices contained in the content has already appeared in another content (i.e. is now beyond bar zero), it will result in an error message.

Rhythm patterns and macros

Rhythm patterns and macro definitions are content types/elements of mScore.js which serve to speed up your writing and keep your scores concise and sometimes more readable. You don’t have to use them, however, since anything they do can also be written directly in the content element themselves. They contain their own languages — the rhythm pattern language is quite simple, and the macro definition language is essentially idential to the voice content language. You can learn all about them here.

All rhythm pattern definitions (pattern elements) are enclosed in a single <rhythmPatterns> ... </rhythmPatterns> element; neither of them accept any particular attributes. Rhythm patterns get numbered 1, 2, etc. and it is by number that you call them up in your content. As an example (deferring the explanation of the patterns’ contents to the appropriate place):

<rhythmPatterns> <pattern>8._16 16 16_16_16</pattern> <!-- rhythm pattern 1 --> <pattern>16_8_16 16_8_16</pattern> <!-- rhythm pattern 2 --> </rhythmPatterns>

A macro is a snippet of voice content with or without arguments, which can be inserted in content (or in other macros) anywhere you wish. They serve to e.g. repeatedly put in the same formatting commands, like a voice frequently jumping between staves. Macros are defined by macro elements, all enclosed in a single <macros> ... </macros> element. They accept two attributes:

nameUsed with macros instead of idx. You can give a macro a name consisting of any characters except spaces, square and round brackets, or inequality signs (“<”, “>”). Those macros that are not given a name get named by consecutive numbers 1, 2 etc., skipping numbers already used as explicit names.
argsThe number of arguments of the macro. If omitted, the number will be determined from the number of arguments which appear in the macro definition’s content (not part of this page).
<macros> <macro name="example"> (content here; number of args automatic) </macro> <macro args="3"> (content here; macro has 3 arguements) </macro> <!-- automatic name of macro above will be “1” --> </macros>

Full file examples

First a minimal example (with a snippet of Beethoven), to show how small an mScore.js XML file can be. The two prolog lines of XML are omitted, which is allowed, but not advisable.

<mScore> <content>E E F G|G F E D|C C D E|E. D 2:D</content> <mScore>

Then a piece for classical guitar with very ordinary settings:

<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE mScore> <mScore> <title>Chôros № 1</title> <key>E minor</key> <instrument>guitar</instrument> <voices number="3"/> <content pickup="yes"> (all music goes here) </content> <mScore>

Finally a duet, with the content of both parts together in one content element.

<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE mScore> <mScore> <title>Ave Maria</title> <composer>J.S. Bach / Charles Gounod</composer> <key>C major</key> <part> <instrument>cello</instrument> </part> <part> <instrument playback="piano">Piano or Bobby McFerrin<instrument> <staveset preset="piano"/> <!-- line is redundant: the playback instrument is the same --> <voices> <voice idx="3" stave="2"/> </voices> <!-- automatically creates 3 voices --> </part> <content voices="#2, #1"> (All music goes here. In each bar the piano notes are written before the cello notes because part 2 comes first in the “voices” attribute.) </content> <mScore>