FAQ (Frequently Anticipated Questions)

What is this for?
This is three separate tools to aid in the transcription of chant into GABC notation, and a fourth which only deals with chants that have already been transcribed. The first is called the "GABC Transcription Tool" and the second is called the "Psalm Tone Tool" and they will be dealt with separately below. The others are the "Readings Tool" and the "Propers Tool".
Who wrote it, and why?
My name is Benjamin Bloomfield, and the schola that I sing with in Cincinnati, Ohio began chanting Vespers every Sunday in Lent of 2010, but not all of us have a Liber Usualis to sing from, so we were making copies of the chant and pointed psalms from the Liber Usualis every week. I thought about retypesetting things with Gregorio and TeX, but one of the problems was that formatting the text of the psalms with certain syllables in bold and italic is both tedious and error-prone when done by hand. While chanting Vespers one Sunday in January 2011, I realized that it would be relatively simple to write a computer program to automatically break apart a Latin text into syllables, and (as long as the accents are already marked) apply a psalm tone to it or mark certain syllables as bold or italic. In the process of writing this Psalm Tone Tool, it became obvious that it would also be advantageous to split apart Latin into its syllables simply to prevent having to type so many parentheses, and thus the GABC Transcription Tool was born. I put together the Readings Tool after my dad (a permanent deacon) had asked about chanting a specific Gospel in English. The Propers Tool, I wrote more recently (in 2013) at the suggestion of one of my brothers.
What about the graphical representation of the chant?
I had begun a project in May 2010, thinking it would be simple to render GABC into a webpage, but abandoned it later in the year, half-finished. When I wrote these tools, it was a natural fit to use what I already had half-working in order to allow for a graphical preview of the chant, and actually using this code for something provided additional inspiration for getting it to work better, because it is annoying whenever it displays something incorrectly, and thus I have improved much in the rendering of the chant preview since writing the transcription tool. Some of the tools use the Exsurge library by Father Matthew Spencer.
Can I have a look at the source code?
Sure. It is hosted at Github, here.
Have any of these questions really been frequently asked?
One or two of them may have been asked by a real person, but certainly not frequently.
Is there any way of running this while not connected to the Internet?
Yes, as long as you use Chrome on the desktop, or an Android phone or iPhone/iPad. You can get the Chrome Web App version here and it will work whether you are connected to the Internet or not, and there is an Android App available here. The iPhone/iPad version is available here.
Would you like any of my money as a way of thanking you for putting these tools together?
Not really, but if you insist, you can send me a donation.
What about for the iPhone version? Doesn't Apple charge you to join their developer program?
Yes, they charge $99+tax every year for anyone to be in their developer program, which is required to list apps in their App Store. If you'd like to contribute to keeping the iPhone version available, please click here, and thank you for your support.

GABC Transcription Tool

What is the GABC Transcription Tool?
It is a tool to allow you to enter GABC notation without having to mark the syllable breaks, and without having to use so many parentheses. It is also useful for transcribing chants that have repetitive melodies over different texts, such as hymns.
What does it do exactly?

It does several different things. Its original use was simply to take a Latin text and intersperse it with parenthetic GABC notation after each syllable. That is, it takes the two separate texts, "c e g g" and "Adoro te", and produces: "A(c)do(e)ro(g) te(g)" thus saving the typing of many parentheses.

For hymns, it is useful to repeat the melody over each verse. It is also useful to have sections of melody and text, each of which repeats the melody for that section over all the text, for example with a hymn that has several verses followed by an "amen" of an entirely different melody. This can be done by separating the sections with a line that consists entirely of two dashes: "--", or

1. first verse text...
2. second verse text
for the text and
GABC for verses...
GABC for Amen
for the GABC.

It will not repeat the GABC for the last section, so if you have only one section and want it to repeat over all the text, you will have to enter the last line as --

Will it work in reverse?
Yes, to some extent, although it isn't always working quite right at the moment. If you click 'Show integrated GABC' and type into the single textbox that shows up, it will separate the text from the GABC notation if you type or paste regular GABC with the text and GABC interleaved with parentheses, and display it as chant below.
How can elisions be marked in the text?
If you need to mark an elision in the text of the hymn, you can enclose the elided part of the syllable in parentheses. You can change the behavior of elisions by checking or unchecking the "Use puncta for elisions" checkbox. If this checkbox is checked, the elided syllable will get a punctum associated with it. If it is unchecked, the syllable will simply be skipped when assigning GABC to each syllable.
What can I do if it doesn't break up my word into syllables properly?
Right now, there is an inconsistency in the way this is handled depending on whether English is checked. If English is checked, then you can separate syllables with an equals sign (=), but if you use one equals sign in a word, you must you it between every syllable, as it won't look that word up in the dictionary at all. If English is not checked, you may use a hyphen (-) and if you use one hyphen, you must use it on all syllables to the left as well. If you want to mark a word as a monosyllable, you may end the word with a hyphen (e.g., quo-)
Are there any other features I should know about?
There is at least one feature that may be classified as such. When typing into the text field, you may enter accented vowels by typing an apostrophe immediately after a vowel (e.g., e' will be converted to é) This also works with quotation marks and diphthong ligatures, such that e" will be converted to ë and ae and oe will be converted to æ and œ. These conversions will not be made when English is checked above the textbox, and they can be undone by pressing Backspace. (e.g., pressing Backspace while the text cursor is immediately to the right of æ will change the æ to ae, but will not move the cursor.)
Apropos of the aforementioned "English" checkbox, what is it, and what does it do?
It signifies whether the text is English, so that the syllabification can be done differently. English syllabification is done by checking each word against a dictionary (actually by feeding them into the lyric hyphenator at this site) and it only updates the local dictionary every 5 seconds, so you will sometimes have to wait for it to properly syllabify the text.
Is there any way to hear what the chant might sound like?
Oh, yes. If you click on the large initial or the first note of the chant, it will give you some options to set the starting pitch and play the chant. If you click on a punctum, it will turn blue and give you some options. Use the controls that display at the bottom of the screen to pause, step through, change the tempo, or stop the chant.
Is there anything else it does that you still forgot to mention?
Yes, I nearly forgot. If you click on lyrics or notes within the chant while holding down a modifier key (Ctrl, Alt, Shift, etc.), it will highlight the GABC code that maps to it. There is also a link to generate a PDF of the chant using the web front-end to Gregorio here. This link is in the upper right corner and is labeled, "(PDF)". The link next to it (Further PDF Options) links to the same site, but gives you an opportunity to change settings, such as the font used, before generating the PDF.
Is there a way to move whole groups of notes up or down?
Yes. You can do this by holding down <Alt> while pressing up or down. Also, this will only happen if the GABC or Integrated GABC text field is active at the time. If you select part of the GABC, only that part will be moved.
What about the 'Download Integrated GABC' link?
Yes, I should have mentioned that. You can click that to download the GABC file, which will be a text file containing the text in the Integrated GABC text box, which will show up if you click the "Show integrated GABC" link at the top. From Chrome, you can drag this link onto an explorer window, and it will name the .gabc file with the value of the name field in the header, if you have edited the GABC header.
And the other 'Download' links?
Oh yes, these are rather recent additions. These allow you to download an SVG (unlimited resolution) or PNG (limited resolution) versions of the chant. These versions will be identical to the preview displayed on the page, and use the Exsurge library rather than Gregorio to render the chant, which means that some GABC code is not supported (e.g., translations). If you hold down <Ctrl> (<command> on Mac) while clicking the "Download PNG" link, it will download a separate PNG for each system. Also, you can set the width of the PNG/SVG by adding a line to the GABC header such as %width: 5in; or %width: 16cm;. You can also set the DPI for the PNG file by adding a line to the header such as %dpi: 600;. Note that the default DPI is 300.
Are there any other header settings that will affect these SVG and PNG exports?
Yes. You can change the font used with %lyric.font: Helvetica; or %drop-cap.font: Times New Roman;. In addition to drop-cap and lyric, you can also set annotation styles individually. The color of these texts can also be set, e.g., %drop-cap.color: red; will make the large initial red. %staff-line-color: red; will set the staff lines red.

Psalm Tone Tool

What is the Psalm Tone Tool?
It is a tool to aid in the transcription of psalms into GABC notation, as well as formatting the verses into HTML, TeX, or some other format.
What Psalm edition are you using?
The psalms (as well as the Magnificat and Benedictus) are according to a 1961 Liber Usualis (although there may be some mistakes), with all the mediants and flexa as marked in there.
What about the "Use Nova Vulgata psalms" checkbox?
Good point. If this is checked, it will use the Nova Vulgata edition of the psalms.
There are a lot more options in this tool than in the Transcription Tool, aren't there?
Yes, there are.
Shall we go over them one by one?
Yes, I think that's probably the best way.
OK. Let's start with the upper-left quadrant of the grid at the top. The one with the Tone dropdown.
Certainly. From here, you can select the tone to use, first by selecting the tone and then the termination. You can check the "Solemn Tone" box if you want the solemn tone.
What about the other things in the upper-left quadrant?
The clef box can be used to set the position of the clef. It will shift the chant along with the clef, so if you want to change the clef without shifting the chant, you will have to change it in the GABC box just above the preview of the chant.
What are the rules for the Psalm GABC box just below the clef box?
This is just the GABC for each verse of the psalm. The first line is the mediant, and the second line is the termination. The neumes that belong over accented syllables are prefixed by an apostrophe and the dominant is marked as a punctum cavum, with an r. You can store custom tones by using the "Create new tone" button, and they will be stored locally, and thus persist across sessions, but will only be available on your current computer.
How does the format verses part work?

This is where certain aspects of the textual part of the output can be adjusted. If the name of the selected format has GABC in it, all verses will be output in GABC notation. Otherwise, all but the first and sometimes second verse will be formatted text with no GABC. Also, you can adjust the settings for the first verse by selecting GABC and changing the settings on the right side, and then selecting the format that you actually want to use for the subsequent verses.

The parameters of the currently selected verse format show up on the right, "Begin Preparatory Syllable", etc. and it should be fairly obvious what they refer to. The default format is to italicize the preparatory syllables and to bold the accented syllables. The verse prefix is just text that gets put before each verse ($c will be replaced by the current verse number) and the verse suffix is simply put at the end of each verse. The non-breaking space is used between a word and a flex or mediant to prevent a line break from occurring.

The "Verses Filename" is used when dragging the 'Download Verses' link from Chrome (no other browsers support this) into an Explorer window as the name of the file. It is also used by the "Download ZIP of all psalms in each tone" for the name of the verses files. It is also applied to the name field in the header, but for this it will cut off everything after the last period as well as the period itself (e.g., $psalm-$tone.tex becomes $psalm-$tone). Also, $psalm will be replaced with the psalm number (or Magnificat, etc.) and $tone will be replaced with the tone and termination, e.g., 8gstar or solemn8g.

You didn't mention the checkboxes beneath the Format verses dropdown. What are they all about?

"Only format vowels" will cause only the vowels of the preparatory and accented syllables to be affected rather than the entire syllable.

"Use puncta cava" will cause puncta cava to be used in the chant parts of the output.

"Repeat intonation" will cause the intonation to be repeated on each verse, and is automatically checked if the Magnificat or Benedictus is selected or "Solemn Tone" is checked at the top, and is automatically unchecked if a psalm is selected.

Is there anything else I should know about the formats?
Yes, and it is simply this: if the format name has html in it, the verses will be rendered as html on the page, otherwise they will be rendered as text.

Readings Tool

I wrote this just before Advent 2011, and made some slight modifications through January 2012. This is not a tool that I myself need to use very often, so I am not as sure whether there are many problems with it. The special characters (used in the Text that the tone is applied to) to control the output are as follows:

+: Causes the flex tone to be used (or a dotted punctum on the previous syllable, with a quarter bar immediately after, if no flex tone is given).
^: Causes a dotted punctum on the previous syllable, with a quarter bar immediately after.
`: Causes a quarter bar immediately after, without dotting the punctum on that syllable.
~ (or : or ,, or , followed by a new line): Causes the Mediant tone to be used
. or ! or :: will cause the full stop tone to be used
? will cause the Question tone to be used.
Where do the tones come from?
The English tones come from the PDFs linked to here and the Latin tones are from the Liber Usualis.
What else do I need to know in order to set English texts to these tones?
First, know that the English readings are available on the USCCB website here.

Also, the thing that's probably most tedious and important about applying tones to English texts is that accents are not marked in English and indeed are often a bit more nebulous than in Latin. The Readings Tool assumes that the accent falls on the last word of a phrase if that word has only a single syllable, and otherwise it assumes that it falls on the penultimate syllable, but if you need to mark where the accent falls, you can put an asterisk after the syllable that should be accented, as in the example text.

To aid in this process, you can hit <tab> and it will select the last three syllables of the next phrase. Once these are selected, you can press 1, 2, or 3 to mark the first, second, or third of these as the accented syllable, and then press <tab> to go on to the next phrase.

Propers Tool

What does the Propers Tool do?
The Propers Tool will allow you to find the propers for a Sunday or certain feast days and votive Masses from the Liber Usualis. It will also give you the option of applying a psalm tone to some or all of these chants and make a PDF.
Does it support the Novus Ordo calendar as well as the traditional calendar?
Yes, you can click on the big button near the top to switch between the traditional calendar and the Novus Ordo. When using the Novus Ordo calendar, it should make an educated guess about whether the current year is A, B, or C, but there is also a dropdown from which you can change which year it is using.
Why are there extra options for the Alleluia verse?
For all the other propers, the only choice is full tone or psalm toned, but for an alleluia verse, there is an option for psalm toning just the psalm verse, and leaving the full tone for the alleluia antiphon. There is another option for “à la Chants Abrégés,” which replaces the Alleluia antiphon with a simpler one from Chants Abrégés but uses the same psalm toned verse, and the last option is for psalm toning even the alleluia antiphon.
Did you transcribe all of these chants?
No, I didn't. They are all from GregoBase and were originally transcribed by Andrew Hinkley. They are not guaranteed to be free of error, and if you do notice a mistake, you can click on the name of the Mass part (Introitus, etc.) and see the chant at its page on GregoBase and make corrections (if you understand GABC) or simply click the "Report a problem" link (if you don't know how to fix it yourself). To do either, you would first need to register with the GregoBase site.

Supposing I have a question that isn't answered here?
You may contact me via e-mail and I will probably respond: bhb123+jgabc [at]