Migration to GitHub

This project has migrated to GitHub. All releases, starting with 3.0.0-rc1, and documentation updates will be made available there. This website will be allowed to remain for those looking for documentation for older releases.


The gabc notation


gabc is a simple notation based exclusively on ASCII characters that enables the user to describe Gregorian chant scores. The name gabc was given in reference to the ABC notation for modern music.

The gabc notation was developed by a monk of the Abbey of Sainte Madeleine du Barroux and has been improved by Élie Roux and by other monks of the same abbey to produce the best possible notation.


A small summary has been created, you can download it here. You must have basics of gabc to understand it, but it can help you remember some notations. It is made to be printed on A5 paper.

Files written in gabc have the extension .gabc and have the following structure:

name: incipit;
gabc-copyright: copyright on this gabc file;
score-copyright: copyright on the source score;
office-part: introitus/...;
occasion: in church calendar;
meter: for metrical hymns;
commentary: source of words;
arranger: name of arranger;
gabc-version: 0.9.3;
author: if known;
date: xi c;
manuscript: ms name;
manuscript-reference: e.g. CAO reference;
manuscript-storage-place: library/monastery;
book: from which score taken;
transcriber: writer of gabc;
transcription-date: 2009;
gregoriotex-font: greciliae;
mode: 6;
initial-style: 1;
centering-scheme: english;
user-notes: whatever other comments you wish to make;
annotation: IN.;
annotation: 6;
(clef) text(notes)

In each case, replace whatever is between the colon and semi-colon (:...;) with the appropriate character string. Of these attributes, only name is mandatory. Descriptions of how these header fields are intended to be used are below. If you wish to write a value over several lines, omit the semicolon at the end of the first line, and end the attribute value with ;; (two semicolons).

This is the name of the piece, in almost all cases the incipit, the first few words. In the case of the mass ordinary, the form as Kyrie X Alme Pater or Sanctus XI is recommended where appropriate.
This license is the copyright notice (in english) of the gabc file, as chosen by the person named in the transcriber field. As well as the notice itself, it may include a brief description of the license, such as public domain, CC-by-sa; a separate text file will be necessary for the complete legal license. For the legal issues about gregorian chant scores, please see the dedicated page. An example of this field would be:
(C) Elie Roux, 2009, public domain
This license is the copyright notice (in english) of the score itself from which the gabc was transcribed. Like the gabc-license, there may be a brief description of the license too. In unclear or complex cases it may be omitted; it is most suitable for use when the transcriber is the copyright holder and licensor of the score as well. One again, reading the page on legal issues is recommended. An example of this field would be:
(C) Abbaye de Solesmes, 1934
The office-part is the category of chant (in latin), according to its liturgical rôle. Examples are: antiphona, hymnus, responsorium brevium, responsorium prolixum, introitus, graduale, tractus, offertorium, communio, kyrie, gloria, credo, sanctus, benedictus, agnus dei.
The occasion is the liturgical occasion, in latin. For example, Dominica II Adventus, Commune doctorum, Feria secunda.
For hymns and anything else with repetitive stanzas, the meter, the numbers of syllables in each line of a stanza. For example, for typical Ambrosian-style hymns: 4 lines each of 8 syllables.
This is intended for notes about the source of the text, such as references to the Bible.
The name of a modern arranger, when a traditional chant melody has been adapted for new words, or when a manuscript is transcribed into square notation. This may be a corporate name, like Solesmes.
The version of gabc notation used. At present the version should be the same as the version of gregorio used.
The author of the piece, if known; of course, the author of most traditional chant is not known.
The date of composition, or the date of earliest attestation. With most traditional chant, this will only be approximate; e.g. XI. s. for eleventh century. The convention is to put it with the latin style, like the previous examples (capital letters, roman numerals, s for seculum and the dots).
For transcriptions direct from a manuscript, the text normally used to identify the manuscript, for example Montpellier H.159.
A unique reference for the piece, according to some well-known system. For example, the reference beginning cao in the Cantus database of office chants. If the reference is unclear as to which system it uses, it should be prefixed by the name of the system. Note that this should be a reference identifying the piece, not the manuscript as a whole; anything identifying the manuscript as a whole should be put in the manuscript field.
For transcriptions direct from a manuscript, where the manuscript is held; e.g. Bibliothèque Nationale, Paris.
For transcriptions from a modern book (such as Solesmes editions; modern goes back at least to the 19th century revival), the name of the book; e.g. Liber Usualis.
The name of the transcriber into gabc.
The date the gabc was written, with the following convention yyyymmdd, like 20090129 for january the 29th 2009.
The font used by gregoriotex. At present gregoriotex can use three fonts: greciliae, gregorio, and parmesan.
The mode of the piece. This should normally be an arabic number between 1 and 8, but may be any text required for unusual cases. Note that this is not used for the text above the initial, for which see the annotation field.
The style of the initial letter. 0 means no initial letter, 1 a normal one, and 2 a large one, on two lines. Note that if you want to use the initial on two lines, you have to specify at least the two first line breaks.
To change the type of centering behavior gregorio uses. In the default scheme (latin), neumes are centered over the vowel in each syllable, as is typical in Latin chant books. Using the centering-scheme: english option will instead center notes over the entire syllable, rather than just the vowel. (note: this feature is currently only useable with a recent svn version of gregorio)
This may contain any text in addition to the other headers -- any notes the transcriber may wish. However, it is recommended to use the specific header fields where they are suitable, so that it is easier to find particular information.
The annotation is the text to appear above the initial letter. Usually this is an abbreviation of the office-part in the upper line, and an indication of the mode (and differentia for antiphons) in the lower. Either one or two annotation fields may be used; if two are used, the first is the upper line, the second the lower. Example:
annotation:Ad Magnif.;
annotation:VIII G;
The name of the software used to generate the gabc file. If you write gabc by hand, this field should not appear.
The typographical style of the music. This is not yet supported, in that it has no effect. Example: editio vaticana, editio medicea.
The position to be used for the virgula. This is not yet supported, in that it has no effect. Example: top, bottom.
The number-of-voices is the number of voices for a polyphonic piece.

After the %% separator, (clef) text(notes) represents the description of the score. In the following sections, we will only talk about this section, which is the heart of the notation.

Notation fundamentals


We have chosen to represent pitch using a single character. One character corresponds to one written pitch: whatever the clef may be, a position on the staff will still be represented by the same character. With this system, anyone will be able to type scores, even people who are unfamiliar with solfege or do not know much about music theory.

There are 13 possible pitches in Gregorian chant scores, which are represented by letters from a to m that is, 13 characters. For the rare pieces with a broader range, the clef changes.

The inconvenience of this choice is that it only corresponds to English notation (notes A through G) when the do-clef is on the top line of the staff, and even then only for the low notes on the staff.

Correspondence between letter and staff position

One-note neumes

In the notation adopted, a lower-case letter from a to m, represents a punctum quadratum, a square note, and an upper-case letter (A through M), a punctum inclinatum, a diamond-shaped note, which are less frequently used.

For the virga, add a v after the letter. For the oriscus, add a v, for the oriscus an o, a s for the stropha, etc.

The different shapes

Complex neumes

To compose a neume with more than one note, you simply type the letters corresponding to the notes, without worrying about the connections between them. These will be calculated automatically. In the following examples, the caption to each image shows the letters in gabc notation which correspond to the image.

Example of complex neume: gfge

When there is a quilisma within a neume, you type a w after the corresponding pitch.

Of course there are cases in which a sequence of notes can be written in more than one way. These cases are described in the section Determination of the neume according to the sequence of notes.

Separation bars

Separation bars indicate a pause in the chant, so punctuation signs have been chosen to represent them.

The separation bars:  ` , ; : :: 

When a bar is located between two syllables, you must put it in as a separate syllable, as for example,  jus(g) (::) Di(g) .

When a colon ( : ) in the text is immediately followed by a bar, you must type the colon with the preceding word, and not after the note: for example,  jus :(g) (:)  instead of  jus(g) :(:) .

The clef

The way to notate the clef is using two or three characters:

Clefs used in Gregorian chant:  c2 c3 c4 f3 f4


It is very simple to write text and neumes: the letters corresponding to the notes are typed in brackets after the syllable to which they correspond.

To delineate words, you simply put a space between them. We can now give an example of the final notation:

Po(eh/hi)pu(h)lus(h) Si(hi)on(hgh)

The text here is Populus Sion and each syllable is followed by the corresponding neume between brackets.

Here we have to consider the case of text characters located under a separation bar. These characters are principally asterisks indicating repeated sections and other signs indicating the structure of the piece. In those cases, we choose to treat such a character as if it were a syllable: for example,

Si(hi)on,(hgh) *(;) ec(hihi)ce(e).

When there is no character under a separation bar, we proceed the same way, but with a space instead of text:

su(iji)\ae,(i) (;) in(e)

Text centering

In Gregorian chant, aligning the neumes with the text is important, and can be automated (cf. the page about the writing of chant). However, in many software programs, it is necessary to specify the part of the text over which the neume will be centered. Usually you do not have to indicate this with gregorio, but if it is necessary, put the part of the text to be aligned between braces.

Initial determination

The initial is automatically recognized by gregorio as the first letter. If this behaviour is not the one you want, you can force the text centering of the first syllable. Thus Gregorio will consider that the letters preceding the centered text are the initial (it can be empty), and the centered letter as well as the following ones will be under the first note. You can also use the gabc attribute initial-style:0; in the header.

Note that in the case of a syllable composed of one letter only, gregorio does not automatically add an hyphen under the first notes. This is due to the fact that it's easy to add it in gabc, and it would be difficult to remove it if it was automatically added.

Special characters

It can happen that the texts of Gregorian chants contain non-unicode characters, so we must consider how to notate them. Special characters used in Gregorian notation are ý, ǽ, œ́, the crossed R (for Response), the crossed V (for Versicle) and the crossed A (for Antiphon). Of these characters, only the crossed A is not to be found in the Unicode table.

In the case where it is not possible to insert special characters using the keyboard, this can be done using sp markup tags, for example <sp>R/</sp> for the crossed R, <sp>'ae</sp> for accented æ.

Text style

Even though text is rarely styled in a chant score, we have made some markups to apply styles to the text: they are <i> for italic, <b> for bold and <sc> for small capitals.

For example: <i>Ps.</i>(::)

You have now read the basics of the gabc notation, you can go on the details page if you want to know more!

Last modification: 6 February 2011.


This document and the design of this site (by Patrick Roux) are under GPL.