Use of GregorioXML

The goal of the document is to describe a simple usage of GregorioXML to typeset monophonic gregorian chant in square notation. Future extensions are envisaged for ancient notation and polyphony.

The document starts with the most detailed element, the representation of the note, and then zooms out to the global representation of a score.

The note

First of all, we must describe our way of representing a note, before going on to the glyph. A note is represented within a pair of <note>...</note> tags.

The height

The height of a note, its position on a line or space, is represented between the <pitch>...</pitch> tags. We need two parameters to know the height of a note: its letter name and the octave it is in.

We indicate the name of the note we want to represent between the <step> tags, in english notation, with the lower-case letters a, b, c, d, e, f and g.

The octave is indicated between <octave> tags. For some clefs there are 3 possible octaves, so the octave is represented by a number between 1 and 3. The convention is to say that the note of the clef is in the second octave. For example if the C clef is on the third line, a C on the third line will be in the octave 2.

If we want to represent the C of the second octave we will write:

<pitch>
  <step>c</step>
  <octave>2</octave>
</pitch>

The shape

A note can have any of several possible shapes. For the sake of consistency, only specific names can be used. They are the following:

	punctum
	punctum-inclinatum
	stropha
	oriscus
	oriscus-reversus
	quilisma
	virga

In the beginning of some books, there are explanations on how to sing gregorian chant, and this instructional material is printed with a special notation, namely empty notes. There are three forms:

	punctum-cavum
	linea-punctum
	linea-punctum-cavum

A virga with the tail on the left theoretically never appears inside a glyph.

	left-virga

Another shape appears sometimes, the generic square note:

	quadratum

The shape is between <shape> tags, for example if we want to represent a note with the shape of a punctum it will be <shape>punctum</shape>.

The signs

Notes can have several signs above and below and to the right of the note. These signs are represented between <sign> tags. These tags contain up to three other tags that must appear in this order: <top>, <right> and <bottom>.

Signs above the note

There is mainly one sign above the note: the horizontal episema, whose name will be h-episemus.

	h-episemus

The horizontal episema often appears above several notes. In this case we do not put a horizontal episema above every note; rather we use the <multi-note-h-episemus> tag which is described later.

However, there are cases in which we may use two episemas: this is the case of small horizontal episemas beneath notes, above which is a long horizontal episema.

Other signs may appear, in particular at the beginning of books, explaining the interpretation:

• circulus is a circle
• semi-circulus is a semicircle
• accentus is an accent, which may be large

circulus, semi circulus and accentus

Signs to the right of the note

There are two possible signs to the right of the note: punctum mora is a dot after the note, and augmentum duplex is composed of two dots aligned vertically, after the notes.

Inside the <right> markup, they will be indicated by the names augmentum and augmentum-duplex.

punctum mora (augmentum) and augmentum duplex

The signs beneath the note

Two signs are possible beneath the note: the horizontal episema and the vertical episema. Sometimes a substitute for the episema is used. The names of these signs are h-episemus, v-episemus and circumflexus.

There can be only one sign between the top, right and bottom tags. I have never seen a case in which two would be necessary.

If we want to represent a note with a horizontal episema, a punctum mora and a vertical episema we will note inside the <note> markup, after <pitch>:

<sign>
  <top>h-episemus</top>
  <right>augmentum</right>
  <bottom>v-episemus</bottom>
</sign>

Horizontal episema on several notes

Horizontal episemas often appear above several notes. To represent these, we use the <multi-note-h-episemus> tag, which has one attribute: the position of the note in relation to the episema. The first note of an horizontal episema on several notes will have this attribute with the value beginning; a note inside it middle and the final note of the episemus end.

A difficulty here is the case of two notes one on another, for example in a podatus. We are not really imposing any restriction at that level; we can make the episema start on the first or the second note of the podatus, and the same flexibility applies for the end: we can make the episema end on the note of the podatus that we want.

For example, if the C clef is on the second line:

<note>
  <pitch>
    <step>b</step>
    <octave>2</octave>
  </pitch>
  <multi-h-episemus position="beginning"/>
</note>
<note>
  <pitch>
    <step>c</step>
    <octave>2</octave>
  </pitch>
  <multi-h-episemus position="middle"/>
</note>
<note>
  <pitch>
    <step>b</step>
    <octave>2</octave>
  </pitch>
  <multi-h-episemus position="end"/>
</note>

The flat and the natural

The problem of accidentals is the following: we need to represent them inside the <note> tags, in order for music analysis tools to be able to see that a note has been altered. But we also need to think about the score representation software that will represent the glyph, without representing the alteration on every altered note. That's why we chose to represent alterations in two different places.

The glyph

We represent the glyph of an accidental on the same level as the glyphs of notes (see glyph section):

<flat>
  <step>d</step>
  <octave>1</octave>
</flat>

The natural is represented the same way, with the tags <natural> instead of <flat>

Inside the <note> tags

The notes that are flatted have an additional <flated /> markup inside their <pitch> tags:

<pitch>
  <step>b</step>
  <octave>2</octave>
  <flated />
</pitch>

The naturals are, of course, never represented inside the note.

The neumatic glyph

Basic neumatic glyphs

By neumatic glyph we understand the position of the notes, the link between them and the position of the queues. We do not take the shape of the notes into consideration inside the glyph. When several shapes are possible for a note, we will need to look inside the <shape> markup of this note.

liquescentia may also change the shape of a neumatic glyph, we will see that later.

The type of the glyph is given inside <type> tags. To ease the interpretation of GregorioXML, there is a restriction on the type that we can give to a glyph. The basic glyph that contains only one note (of any shape) is called punctum. Here is a list of the other glyph types possible:

	pes
	pes-quadratum
	clivis
	torculus
	porrectus
	torculus-resupinus
	porrectus-flexus
	torculus-resupinus-flexus

The pes quadratum is a new shape invented by a monk of the abbey Sainte-Madeleine du Barroux to determine precisely the translation of the podatus from ancient notation to square notation. This is also the type used when the first note of a podatus is an oriscus. This shape can also be encountered with a quilisma as the first note, but it is a very rare case.

There are other shapes that never exist alone, that is to say that they are always followed by a particular glyph, often a subbipunctis deminutus, but they are very rare:

	right-pes
	right-porrectus

To finish with, a last glyph must be taken into consideration. Theoretically it must not be used, but we prefer to give it a name, for our representation to be truly complete.

	torculus-et-pes

Puncta inclinata

There are glyphs that make an exception to the definition that we gave earlier. They are the puncta inclinata. They are a sequence of puncta inclinata that (???), and very often composed of only ascending or descending notes. We call them x-puncta-inclinata-ascendens or x-puncta-inclinata-descendens, where x is their number. The other possibility is the trigonus: three puncta incliata in which the central one is the highest. Other sequences of puncta inclinata will be simply called puncta-inclinata.

3-puncta-inclinata-descendens

The climacus is a one-note (with the shape virga) followed by a 2-puncta-inclinata-descendens.

Indication of the notes

We represent the glyphs inside <glyph> tags. Inside those tags, the first markup is <type>, in which we indicate the type of the glyph (it has to be a name that we already talked about).

After <type>, <note> markup are present, as many as notes in the glyph.

Here is an example if the C clef is on the second line:

<glyph>
  <type>porrectus</type>
  <note>
    <pitch>
      <step>d</step>
      <octave>2</octave>
    </pitch>
  </note>
  <note>
    <pitch>
      <step>c</step>
      <octave>2</octave>
    </pitch>
  </note>
  <note>
    <pitch>
      <step>d</step>
      <octave>2</octave>
    </pitch>
  </note>
</glyph>

liquescentia and initio debilis

The liquecences are indicated by the <figura> tags, that can contain four different words:

• deminutus for diminutive liquescentia
• descendens for auctae increasing liquescentia
• ascendens for descendae increasing liquescentia

The initio debilis are represented in another markup: <initio-debilis />. This markup is situated between <type> and <note>tags.

The puncta inclinata can also have liquescentia (but not initio-debilis).

In some cases there is a lot of difference between a glyph and the glyph with liquescentia. There are even sometimes different ways to represent the same glyph with the same liquescentia.

Another important thing is that the pes quadratum, pes and right-pes have the same ??? liquescentia. It is not advised to give the glyph the type right-pes in this case. The most logical is pes.

Auctae increasing liquescentia of the pes

The name markup

Sometimes a glyph can have a special name, it may be interesting to indicate it, even if it is not mandatory for the interpretation, for example if we type this:

The name pes quassus won't appear anywhere, this is the kind of things that may appear in the <name> markup:

<glyph>
  <type>pes</type>
  <name>pes quassus</name>
  <note>
    <pitch>
      <step>c</step>
      <octave>2</octave>
    </pitch>
    <shape>oriscus</shape>
  </note>
  <note>
    <pitch>
      <step>c</step>
      <octave>2</octave>
    </pitch>
  </note>
</glyph>

You can notice that here we could have set the type to pes-quadratum.

The neumatic elements

The neumatic elements are the most simple tags: they are only a sequence of neumatic glyphs. Before this sequence there may be a <name> markup, as a lot of elements do have names.

Here is a very simple example:

<element>
  <name>salicus auctus descendens</name>
  <glyph>
    <type>one-note</type>
    <name>punctum quadratum</name>
    <note>
      <pitch>
        <step>e</step>
        <octave>2</octave>
      </pitch>
      <shape>punctum-quadratum</shape>
    </note>
  </glyph>
  <glyph>
    <type>pes-quadratus</type>
    <name>pes quassus</name>
    <figura>auctum-descendens</figura>
    <note>
      <pitch>
        <step>d</step>
        <octave>2</octave>
      </pitch>
      <shape>oriscus</shape>
    </note>
    <note>
      <pitch>
        <step>e</step>
        <octave>2</octave>
      </pitch>
    </note>
  </glyph>
</element>

The entire neume

The neume is basically a succession of neumatic elements. So inside the <neume> tags we can find a sequence of <element> tags. However, sometimes other things may appear between two <elements>.

Longer spaces

Spaces are specially important in gregorian chant. This importance comes from the fact that when monks translated the ancient neumes in square notation, the equivalence was not perfect, and some ancient figures have been translated with a larger space between two notes. It is necessary to take that phenomenon into consideration for the conservation of all the data in digital format.

By default there is no need to put spaces between elements, but sometimes larger spaces are present. When it is the case, we must put the <larger-neumatic-space/> markup between two elements.

Notes with non space, then normal space between two elements and finally a larger neumatic space

Separation bars

Inside a neume, there may be separation bars. Even if all of them cannot appear, we will present them all now.

To represent a bar between two neumatic elements, we write <bar>. Inside these tags, we only find the <type> tags, in which there can only be five words:

• minima: a small bar on the top line
• minor: a bar on the two middle lines
• maior: a bar on all lines
• finalis: a double bar on all lines
• virgula: an apostrophe on the top line (or the bottom line, according to the style)

virgula, minima, minor, maior et finalis

The spaces before and after the bar must be set automatically by the software that will interpret GregorioXML.

End of line

Logically software can handle automatically the end of lines, but it may be useful to indicate them in XML files, for example for conversions to OpusTeX.

End of line may appear between neumes, or even inside them, between two neumatic elements (but not between two glyphs).

The two cases are identical: the end of a line is indicated by the markup <end-of-line />. The software that will interpret GregorioXML must determine the custos automatically.

Conclusion on the software interpretation of a neume

If a software wants to interpret GregorioXML to print a result on the screen, it must start by interpreting the glyph, looking at the type (<type>) and the liquescentia (<figura>), to determine the position of the notes and the bars linking them. It must then look at the shapes of the notes (<shape>) for the notes that can be of several different shapes.

It must do the same for each glyph of the neumatic element, without space between them, and then handle the spaces(<larger-neumatic-space/>), bars (<bar>) and eventually the end of lines (<end-of-line>) between elements to form the complete neume.

The simple score

Let's look at a simple score, that is to say a monodic score.

The text

To each syllable corresponds a neume, we have consequently thought to a <syllable> markup containing a markup <text> and then a <neume> markup.

The <text> markup has an attribute position which is the position of the syllable inside the word: if the syllable is the first of the word it will be beginning, if it is inside the word, middle and if it is the last, end. If the word has only one syllable, the attribute will be set to one-syllable.

Here is an example (we don't write the neume to save some space):

<syllable>
  <neume> ... </neume>
  <text position="beginning">ec</text>
</syllable>
<syllable>
  <neume>
  ...
  </neume>
  <text position="end">ce</text>
</syllable> 

The special characters

Sometimes the text contains characters that are not in the Unicode table. The special characters used in gregorian chant are the y accentuated, the æ accentuated, the œ accentuated, the barred R (for Response), the barred V (for Versicle) and the barred A (for Antiphon). In these signs, the œ accentuated and the barred A are not in the unicode table. There are also other accentuated characters, and sometimes letters with tilde.

The insertion of special characters in the text, in the cases where it is not possible with the keyboard, will be done thanks to the <special-character> tags, containing a code identifying the character:

• 'o for o accentuated
• oe for œ
• 'oe for œ accentuated
• /R for barred R
• ~n for n with tilde

These codes are of course adaptable to all other letters.

barred A, V and R

Separation bars

Separation bars are often between neumes. We can consequently put some <bar> tags in a separate <syllable> markup, containing a <type> markup with the same name as in the previous section on bars. The text under the bar is the one of the syllable.

Clefs and clef changes

The clefs are defined inside the meta-data of a score, but there can be clef changes inside a score, which are represented the same way.

The clef changes are represented with a <clef-change> markup, that contains the <sign>, <line> and optionally <flated/> tags. The <sign> markup contains the sign of the clef: c for a c clef and f for a f clef.

The <line> tags contain the number (between 1 and 4) of the line on which is the clef, when 1 is the top line. If there is a flat on the clef, it is indicated with the <flated/> markup.

Here is an example of clef change:

<clef-change>
  <type>f</type>
  <line>3</line>
</clef-change>

Possible clefs in gregorian chant

Metadata of a partition

The metadata of a partition are indicated inside the <score-attributes> tags, the first markup inside the <score> markup. They contain a lot of elements in any order. Most are optional, but some are important:

Mandatory elements

The clef is indicated between <clef> tags, that behave exactly the same way as <clef-change> tags.

The name of the piece is indicated inside the <name> tags. Most of the time the name of the piece is the first words of the text, for example Pópulus Sion, as here.

The <type> tags contain the type of the partition: mono-voice, simple-polyphony or polyphony. mono-voice corresponds to the score that we are describing, simple-polyphony allows to have several neumes in one syllable, and polyphony allows to make real polyphony.

Optional elements

The <author> and <date> tags contain the name of the author and the date of the writing. For most of the pieces this data is unknown; these tags are not mandatory.

The <manuscript> tags contain the name of the manuscript the piece is transcribed from; and the <manuscript-storage-place> tags contain the name of the place where the manuscript is kept.

The <manuscript-reference> tags contain a reference of the piece. Each ancient piece may have a unique reference, for example, that used in the Cantus database.

<transcriber> and <transcription-date> contain respectively the name of whoever entered the gabc, and the date of entry.

The initial

Initials are indicated between <initial> tags, that contain the <letter> markup (indicating the letter represented by the initial), <type> (representing the width of the initial) and <style> representing the style.

Three widths are often encountered in manuscripts: the very large initial at the beginning of some books (type huge), the initials at the beginning of chapters (type large) and the normal initials (type normal).

You can notice that the first letter after an initial is upper-cased. We consider that the word starts with the first letter under the score lines, so we will note <text position="beginning"> but not <text position="middle"> for the first syllable after the initial.

The annotations

What we call annotation is what is represented at the left of the first score line, above the initial (cf. example). It is often just the mode and then an abbreviation for the part of the office, so it can generally be determined without any precision. However there are exceptions, we need to be able to precise these annotations.

The representations of these annotations is made inside <annotation> tags. There is one of these tags per line. The number of these lines is by the way an attribute of the <annotation> markup. There is never more than two lines of annotation, but there may be an annotation at the level of the initial, we consider that the initial is on the line 3.

Inside these <annotation> tags we put text, including special characters. To format the text we can put some <style> tags that have a format attribute. There is no restriction for this attribute, but the commonly used are italic, bold and small-capitals.

Here is an example:

...
<annotation line="1">
  1. <style format="italic">P
  <special-character>'o </special-character>
  pu</style>
</annotation>
<annotation line="2">
  <style format="small-capitals">Offert.</style>
</annotation>
... 

style and precise-style

The style determines the graphys that will be used for the different glyphs, the type of font that will be used we could say. In general there are only few variations between the different styles, that's why the <style> is not mandatory.

However there may be really different graphys, like in the line from a book the 18th century:

Describing the small changes that may appear between the styles is possible with the <precise-style> that can contain any markup, to describe all possible styles.

An example of markup that we can put inside it is <virgula-position>, that can be bottom or top. Indeed in some books the virgula is on the bottom line and in others on the top line.

Another example would be <v-episemus-style>, that determines if we use classical vertical episemus or episemus substitutes (circumflexus).

We can also indicate some shapes, for example the shape of the toruclus resupinus deminutus or of the subpunctis deminutus that may vary.

Example

Here is an example on what we have seen on the metadata of a score:

<score>
  <score-attributes>
    <name>Populus Sion</name>
    <office-part>introitus</office-part>
    <annotation>
      <style format="small-capitals">Offert.</style>
    </annotation>
    <type>mono-voice</type>
    <author>Elie Roux</author>
    <date>2006</date>
    <initial>
      <letter>P</letter>
      <type>normal</type>
    </dropped-initial>
    <clef>
      <sign>c</sign>
      <line>3</line>
    </clef>
  </score-attributes>
  <syllable>
    <neume>
      ...
    </neume>
    <text="beginning">Ó</text>
  </syllable>
      ...
</score>