The mScore.js XML file format
There are several ways to feed a musical score into mScore.js for display:
- It can be constructed on-the-fly in the browser by some sort of JavaScript-powered editor — this is how the interactive examples on the pages of this manual are produced. (The page you are now reading is the only page of the manual which is not interactive.)
- A complete piece can be loaded from an mScore.js XML file.
- A complete piece can also be loaded from a JSON (JavaScript Object Notation) file.
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.
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.
- XML files mostly consist of elements and content. An element is a pair of tags with content between them. They look like this:
<name> ... stuff inside ... </name>
Each element has a name (from a predefined list of elements for that type of XML file, in our case mScore.js XML), and the start and the end tag have the same name. - XML is case sensitive, voice ≠ Voice.
- XML elements often have attributes, which are pairs in the form of attributeName="attributeValue" and go into the start tag of the element. There can be several attributes in a tag and their ordering does not matter.
- The content of an XML element can be any combination of text and other XML elements. They need to be properly nested, though (if an element starts inside another, it must end inside it too.)
- If an XML element has no content (i.e. is empty), it can be written in a shorter form (and usually is): <name></name> = <name/>. Note the position of the “/”!
- You can put spaces or line breaks almost anywhere without changing the meaning of the file, e.g. around element tags, inside the tags around attributes etc. But it is still recommended to stick to some kind of regular line indentation or your file can become hard to read.
- mScore.js will ignore any text content which is not placed inside the proper XML element; therefore you can write comments that way, although it better style to use the XML comment syntax, i.e. <!-- this is an XML comment -->.
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:
- Content: There’s three types of content, voice content, rhythm patterns, and macro definitions. Rhythm patterns and macros
are valuable tools for writing concise and readable mScore.js code, but you never have to use them. They are dealt with
on this page.
Voice content is the heart of mScore.js and most manual pages are devoted to it, starting here. However, it’s useful to first get an idea how to pack voice content into an XML file, as this page describes. - Parts definitions: A part definition contains information about the instrument, stave structure, number of voices and similar data of a single instrument or player appearing in the piece. Many pieces will have only one part.
- General information: The piece’s title, composer, tempo, initial key, etc. as well as typesetting parameters like display styles of various elements (tuplets, time signatures, etc.) and color definitions.
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
| element | used for | default value |
|---|---|---|
| title | displaying error messages | “Untitled” |
| key | key which the piece begins with | C major (i.e. no accidentals) |
| tempo | metronomic tempo for audio playback | 120 bpm |
| style | see 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”.
Parts
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.
Staves
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.
Voices
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.
| attribute | meaning | possible values | default value |
|---|---|---|---|
| (idx) | voice index | between 1 and number in voices (if specified) | idx of prev. voice + 1 |
| color | which color to use for the voice | between 0 and the number of defined colors | 0 (= default-black) |
| restPos | vertical position of rests | a signed integer | 0 |
| stave | which stave the voice lies in | between 1 and the number of staves | 1 |
| stem | Orientation of note stems | auto, up, down, or inbetween | auto |
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:
| attribute | meaning |
|---|---|
| voices | A comma-separated list of the following types of items:
|
| pickup | If 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:
| attribute | meaning |
|---|---|
| name | Used 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. |
| args | The 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>
