Brian Kernighan and Dennis Ritchie popularized the practice of writing a program that prints the words “hello, world” as the first program to write when learning a new programming language. It is the minimal program that tests how to build a program and display its results.
In MusicXML, a song with the lyrics “hello, world” is actually more complicated than we need for a simple MusicXML file. Let us keep things even simpler: a one-measure piece of music that contains a whole note on middle C, based in 4/4 time:
Here it is in MusicXML:
<?xml version="1.0" encoding="UTF-8" standalone="no"?> <!DOCTYPE score-partwise PUBLIC "-//Recordare//DTD MusicXML 3.1 Partwise//EN" "http://www.musicxml.org/dtds/partwise.dtd"> <score-partwise version="3.1"> <part-list> <score-part id="P1"> <part-name>Music</part-name> </score-part> </part-list> <part id="P1"> <measure number="1"> <attributes> <divisions>1</divisions> <key> <fifths>0</fifths> </key> <time> <beats>4</beats> <beat-type>4</beat-type> </time> <clef> <sign>G</sign> <line>2</line> </clef> </attributes> <note> <pitch> <step>C</step> <octave>4</octave> </pitch> <duration>4</duration> <type>whole</type> </note> </measure> </part> </score-partwise>
Let’s look at each part in turn:
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
This is the XML declaration required of all XML documents. We have specified that the characters are written in the Unicode encoding “UTF-8”. This is the version of Unicode that has ASCII as a subset. Setting the value of standalone to “no” means that we are defining the document with an external definition in another file.
<!DOCTYPE score-partwise PUBLIC
"-//Recordare//DTD MusicXML 3.1 Partwise//EN" "http://www.musicxml.org/dtds/partwise.dtd">
This is where we say that we are using MusicXML, specifically a partwise score where measures are contained within parts. We use a PUBLIC declaration including an Internet location for the DTD. The URL in this declaration is just for reference. Most applications that read MusicXML files will want to install a local copy of the MusicXML DTDs on the user’s machine. Use the entity resolver in your XML parser to validate against the local copy, rather than reading the DTDs slowly over the network. If your application wants to validate against the MusicXML XSD rather than a DTD, you can use an entity resolver in your XML parser to do this. When writing MusicXML files, writing the DOCTYPE makes it easier for all applications – DTD or XSD based – to validate MusicXML files.
This is the root document type. The <score-partwise> element is made up of parts, where each part is made up of measures. There is also a <score-timewise> option which is made up of measures, where each measure is made up of parts. The version attribute lets programs distinguish what version of MusicXML is being used more easily. Leave it out if you are writing MusicXML 1.0 files.
<part-list> <score-part id="P1"> <part-name>Part 1</part-name> </score-part> </part-list>
Whether you have a partwise or timewise score, a MusicXML file starts off with a header that lists the different musical parts in the score. The above example is the minimal part-list possible: it contains one score-part, the required id attribute for the score-part, and the required part-name element.
We are now beginning the first (and only, in this case) part within the document. The id attribute here must refer to an id attribute for a score-part in the header.
We are starting the first measure in the first part.
The attributes element contains key information needed to interpret the notes and musical data that follow in this part
Each note in MusicXML has a duration element. The divisions element provided the unit of measure for the duration element in terms of divisions per quarter note. Since all we have in this file is one whole note, we never have to divide a quarter note, so we set the divisions value to 1. Musical durations are typically expressed as fractions, such as “quarter” and “eighth” notes. MusicXML durations are fractions, too. Since the denominator rarely needs to change, it is represented separately in the divisions element, so that only the numerator needs to be associated with each individual note. This is similar to the scheme used in MIDI to represent note durations.
<key> <fifths>0</fifths> </key>
The key element is used to represent a key signature. Here we are in the key of C major, with no flats or sharps, so the fifths element is 0. If we were in the key of D major with 2 sharps, fifths would be set to 2. If we were in the key of F major with 1 flat, fifths would be set to -1. The name “fifths” comes from the representation of a key signature along the circle of fifths. It lets us represent standard key signatures with one element, instead of separate elements for sharps and flats.
<time> <beats>4</beats> <beat-type>4</beat-type> </time>
The time element represents a time signature. Its two component elements, beat and beat-type, are the numerator and denominator of the time signature, respectively.
<clef> <sign>G</sign> <line>2</line> </clef>
MusicXML allows for many different clefs, including many no longer used today. Here, the standard treble clef is represented by a G clef on the second line of the staff (e.g., the second line from the bottom of the staff is a G).
We are done with the attributes, and are ready to begin the first note.
<pitch> <step>C</step> <octave>4</octave> </pitch>
The pitch element must have a step and an octave element. Optionally it can have an alter element, if there is a flat or sharp involved. These elements represent sound, so the alter element must always be included if used, even if the alteration is in the key signature. In this case, we have no alteration. The pitch step is C. The octave of 4 indicates the octave the starts with middle C. Thus this note is a middle C.
Our divisions value is 1 division per quarter note, so the duration of 4 is the length of 4 quarter notes.
The <type> element tells us that this is notated as a whole note. You could probably derive this from the duration in this case, but it is much easier to work with both notation and performance applications if the notation and performance data is represented separately. In any event, the performance and notation data do not always match in practice. For example, if you want to better approximate a swing feel than the equal eighth notes notated in a jazz chart, you might use different duration values while the type remains an eighth note. Bach’s music contains examples of shorthand notation where the actual note durations do not match the standard interpretation of the notes on the page, due to his use of a notational shorthand for certain rhythms. The duration element should reflect the intended duration, not a longer or shorter duration specific to a certain performance. The note element has attack and release attributes that suggest ways to alter a note’s start and stop times from the nominal duration indicated directly or indirectly by the score.
We are done with the note.
We are done with the measure.
We are done with the part.
And we are done with the score.
One limitation of XML’s document type definitions is that if you want to limit the number of elements within another element, you generally must also restrict how they are ordered as well. In the attributes, for instance, we want no more than one divisions element; for the note’s pitch, we want one and only one step element and octave element. In order to do this, the order in which these elements appear must be constrained as well.
Thus the order in which elements appear in these examples does matter. The DTD definitions should make it clear what ordering is required; we will not spell that out in detail during the tutorial.