Basics of mScore.js musical content
The previous page has shown you how to produce an mScore.js XML file for a musical piece and in it put content elements for the actual musical content. This page will teach you the basics of writing this content using mScore.js’s voice content language. There are of course many more features to mScore.js on the other pages of this manual.
Note that the information on this page does not only apply to mScore.js XML files. Voice content is the same, no matter which method is used to put it into a musical piece. For instance, in the interactive examples below each input box represents a content element from which, when you click the button, a piece is constructed and displayed without an XML file inbetween.
The explanations of the various features of mScore.js contained in this page are not always totally exhaustive in covering all eventualities, but you can use the interactive examples to experiment with the language to answer most questions. In case of errors mScore.js strives to always return detailed error messages to help you see what went wrong.
The basics
Hello, Ludwig van
To write a melody simply put the notes one after another with any number of spaces between them. A note is a capital letter A to G (you can also use the German-style H as an alias for B). To put notes an octave higher or lower prefix them with “+” or “-” (without space), or several of those to shift by more than one octave. If your melody moves to a higher octave (e.g.) and stays there for a while it can be annoying having to put “+” or even “++” in front of every note. In that case you can simply use an octave shift to change which octave notes naturally lie in. The shift operators are <ocU/> (octave up) and <ocD/> (octave down).
Example OcUD above shows how after shifting the octave up with <ocU/> the following B♭, which lies in the original lower octave, now needs to be prefixed by “-”.
The example also already shows how accidentals are written in mScore.js. They are suffixed to the notes (no space); As of version ?? mScore.js supports five types of accidentals:
The usual rules of musical notation apply: Ab Ab is equivalent to Ab A, unless there’s a bar line between the notes; of course you will need to type the first form if you want the redundant flat to be displayed visually as a reminder.
Note value switches
You may also have noticed the expression 2: in front of the last note of example OcUD. This is a note value switch. In mScore.js you don’t need to specify each note’s value separately, you just switch to a note value and all following notes of this voice will get that value. By default a voice starts with quarter notes. A note value is specified by its reciprocal value. The following values are currently available in mScore.js:
| reciprocalValue | 1 | 2 | 4 | 8 | 16 | 32 | 64 |
|---|---|---|---|---|---|---|---|
| note | full | half | quarter | eighth | … | ||
| code | 1: | 2: | 4: | 8: | 16: | 32: | 64: |
A note value switch can appear almost anywhere in an mScore.js voice; space to the left and right of it is optional.
Beamed groups
Sequences of fast notes (value ≥ eighths) in a bar will usually be grouped together by beams. mScore.js calls such a sequence a beamed group. It is written by putting an underscore _ between each two notes (space optional).
In some cases you might want to visually split a beamed group in several sub-groups by cutting one or several beams at specific places (e.g. splitting a group of 8 notes into 4+4.) In that case replace the underscore by _^_, _^^_ etc. where the number of “^” is the number of beams to cut at this place. Note: mScore.js does not prevent you from using this feature to produce layouts which look bad or wrong. It’s your own responsibility.
Chords
The previous page has shown how an mScore.js piece can have an unlimited number of simultaneous voices. But the content of one voice does not have to be a sequence of single notes, there can also be chords — in fact internally in mScore.js all notes are part of chords, even when those chords only have one note. Visually (as you know) notes of a chord are connected together by a common note stem. You write chords by putting their notes together without spaces. Their order does not matter, but for ease of reading it is recommended to write them in ascending order by pitch. See example Chords, where there are two (differently-colored) voices, of which the first contains chords.
Rests
Rests in mScore.js are written by putting *, which draws a rest with the currently set note value. It will happen frequently that the separation of your score into voices is not totally strict and that voices vanish for a while (or only come up for a single chord for example). In that case you will want to not clutter your score with lots of rests. For this purpose mScore.js offers invisible rests, which are written by . (put a space before it when it follows a note to distinguish it from a dotted note). Advice: There shouldn’t be an invisible rest in all voices at the same time — mScore.js does not prevent you from misleading your readers.
Additionally there are commands ** resp. .., which create visible/invisible rests which fill the whole bar. They will be displayed as full-note or half-note rests, whichever is more appropriate for the current time signature.
All about rhythms
Note values and dots
A note can be dotted (and multiple dotted) by simply putting periods after it (without space), coming after accidentals but before any layout modifiers. The note following a dotted note is automatically made shorter by half (or 3/4 etc. for multiple dots) to save you switching the note value back and forth, unless it is dotted itself, has its note value explicitely set by a note value switch, or there’s a bar line between them.
Tuplets
A tuplet is governed by three numbers: the base beat, the tuplet’s length (number of base beats) and its split number. For example (8, 2, 3) means a duration of two eights split into a triplet of three (visual) eights.
The syntax for a tuplet is either tsplit: or tlength/split:. The base beat is always the currently set note value. If you need a different one, put a note value switch before the tuplet. If you use the first (shorter) form of the tuplet switch, the default value for the tuplet length is used, which are:
| Split | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 |
|---|---|---|---|---|---|---|---|---|
| Default length | 3 | 2 | 4 | 4 | 4 | 4 | 8 | 8 |
mScore.js currently supports 2-tuplets (duplets) to 9-tuplets!
8:F_F_F_F F_F_F_F F_F_F_F
8:B_B t3u:A_G_+E# t4/3:B_B_16:B._B 16: t3:B_B_B 8: t3/2:B B
A tuplet is applied once, then the voice continues with regular note values. If you have many tuplets of the same type following each other, you might want to use a persistent tuplet switch (tssplit: resp. tslength/split:). This will produce tuplets of that type until it is stopped by starting a rhythm pattern or by t0:.
Comments
Every markup or programming language needs a way to put comments into the source code, i.e. stuff that will be ignored when processing the material. This is useful for mainly two reasons:
- Adding explanatory text to the source to help people reading/modifying it. Example in mScore.js: Add bar numbers to some or all bars to make it easier to find them in the piece.
- Comment out material, i.e. mark it as a comment when you want to remove it from your score but don’t want to delete it because you might want to put it back later.
mScore.js has two ways of writing comments. mScore.js stores its score files in an XML format and thus needs to be able to use XML-style comments. These take the form <-- text in an XML comment -->. We suggest you don’t use XML comments, because they are a bit clumsy. Use mScore.js’s own comment style instead:
mScore.js comments are simply enclosed in round brackets (like this). Unlike XML comments, mScore.js comments can be nested, i.e. C_D_Eb(this ((is) perfectly) OK)_F_G. Comments do not break up items, e.g. a comment can appear in the middle of a chord.
mScore.js comments are available inside mScore.js’s content elements, i.e. voice content, rhythm pattern and macro elements. In an XML file outside those elements you must use XML comments.
Bars and bar lines
Musical pieces are usually split into bars of equal length, seperated by different types of bar lines. You write them in mScore.js by simply putting a vertical bar (pipe) character where you want a bar line to be. In addition to the normal bar line mScore.js as of version ?? supports the following types:
| bar line type | code | appearance |
|---|---|---|
| Normal bar line | | | |
| Double bar line | || | |
| End of piece | ||| | |
| Begin repeat | ||: | |
| End repeat | :|| | |
| End & begin repeat | :||: |
The length of a bar, displayed as a time signature at the start of the bar, or lack thereof, is calculated automatically from the bar’s content. For this reason you don’t need to set a musical piece’s time signature. If the piece starts with an anacrusis, i.e. its first content element has the attribute pickup="yes", this bar is ignored for measuring time, as it should be. Likewise, if a piece ends without a bar line, the last bar is considered unfinished and does not have a time signature, even if its length is unlike that of the preceding bar.
Multi-voice content
If a piece or part has multiple voices you will not always wish to put each one of them in its own content element. The previous page has shown how to specify multiple voices for a content element. Inside the content you can cycle through these voices by writing \. Each bar (i.e. after each bar line) starts with the first of the content element’s voices. You don’t have to write content for each voice in a bar: You can put multiple voice switches to skip voices, e.g. \ \ \ = \\\.
As illustration, the following examples MultiVoice1 and MultiVoice2 produce the same score with the voices in seperate content elements, and together, respectively. In example MultiVoice1, the first content element has pickup="yes", the second doesn’t.
