Rendering Music notation with ABC

ABC is a human readable ascii representation of music notation.  John Chambers posted a brief history of ABC notation and there is a newer history by Chris Walshaw.

Unlike MusicXML, which is designed for exchanging music between score editing and performance applications, ABC is designed to be directly edited by humans. I can type a score in ABC with vim much faster than by fiddling with a mouse in a GUI score editor. Unlike other formats ABC works well with version control such as git. As with Latex, what you see is not what you get. But the notation is intuitive, the learning curve is pretty short, and the benefits are awesome.

While often touted as the standard for folk music, it works perfectly for Jazz lead sheets and does full scores as well. Some GUI score editors can import/export ABC notation. I used noteedit for a GUI editor until it was abandoned upstream, but was able to export as ABC. The result is reasonably human readable – letting me continue to edit in ABC notation, and serving as an example of a more complete score. When you are done with this lesson, you’ll be able to turn it into a PDF!

Ancient 4th Century Hymn

For a folk tune example, we will do a simple arrangement of a 4th century hymn, with a medieval era tune. “O Lux Beata Trinitas” is one of the twelve hymns which the Benedictine editors regarded as undoubtedly the work of St. Ambrose. It is cited as by St. Ambrose by Hinemar of Rheims in his treatise De unâ et non trinâ Deitate, 857.

The hymn was still popular in the Gregorian Chant era. Here you can see the medieval notation and hear a performance as historically accurate as you will find today.

20th Century Interpretations

The medieval notation was updated in hymnals to more modern notation, This is our starting point. As reflected in those hymnals, there were no measures or bar lines in the medieval period.

Here are the basics of ABC:

  • Comments are lines beginning with ‘%’.
  • Notes beginning with “middle C” are entered as CDEFGABcdefgab.
  • Following a note with a number multiplies the timevalue by that number.
  • Notes that are next to each other are joined together whenever possible. This is the only way spaces are significant.
  • Parenthesis are used to tie or slur notes together.
  • The tune begins with X: 1, where 1 is the tune number. There can be multiple tunes in a file. Folk tunes are often collected into a file. For instance, we could collect all 12 known works of St. Ambrose into a single file named ‘’.
  • The title is given with T:
  • The composer or source is given with C:
  • The key (default is C major) is given with K:

Here is a simple transcription of our tune into ABC:

X: 1
T: O lux beata Trinitas
C: Plainsong, Mode VIII
K: D
% Fedora Magazine example
(AB) (AGFG) EFG (AB) (BA) A4 
(AB) (AGFG) EFG (AB) (BA) A4 
(AB) d (cd) B (AG) (AB)  (AGF) F4 
(GA) (AGFG) EFG (AB) (BA) A4

We are going to do our work in a terminal emulator. Enter the above with your favorite text editor (bonus points if that is cat) into a file named ‘’.
Or download with all the tunes for this lesson. To format and view this, we need ghostscript, xreader, and abcm2ps. You probably have ghostscript and xreader (or other PDF viewer) already installed on a desktop, but it doesn’t hurt to ask again.

$ sudo dnf install ghostscript xreader abcm2ps make

I had you install make so a simple makefile can simplify rendering:

.SUFFIXES:  .abc .ps .pdf .mid
    abcm2ps $*
    abcm2ps $*
    ps2pdf $*.pdf
    abc2midi $*.abc -o $*.mid 

Enter or download that as a file named ‘Makefile’. Now format and view our tune:

$ make lux.pdf
$ xreader lux.pdf &

I had you run xreader in the background, so you can switch back to your terminal. Xreader will update the view whenever lux.pdf is updated. If you are just reading this article, you can also view the output here.

Adding Lyrics

Lyrics are entered with ‘w:’ under the tune line they go with. Words are hyphenated to show how the syllables go with the notes. Use ’*’ to use additional notes for the last syllable.

Append tune 2 to the file, it is the same tune with lyrics:

X: 2
T: O lux beata Trinitas
C: Words: St. Ambrose 4th century
C: Plainsong, Mode VIII
K: D
% Fedora Magazine example
(AB) (AGFG) EFG (AB) (BA) A4 
w: O*  lux***  be-a-ta trin-* ni-* tas, 
(AB) (AGFG) EFG (AB) (BA) A4 
w: et* prin-*** ci-pa-lis U-* ni-* tas,
(AB) d (cd) B (AG) (AB)  (AGF) F4 
w: i-* am sol* re-ce-* dit* i-*gne-us, 
(GA) (AGFG) EFG (AB) (BA) A4
w: in-* fun-***  de lu-men cor-*di-* bus.

Now ‘make lux.pdf’ and see the results in your xreader window. Both tunes are rendered to the PDF.

Adding Measures

So, historical authenticity is all very fine, but I want to make a modern version. The first step for modern ears is to divide the tune into equal sized measures. My ear says that 7/8 is an excellent time signature for this tune.

  • M: 7/8
    specifies a default meter of 7/8
  • L: 1/8
    specifies a default note length of 1/8 of a whole note. This was already the default, but now it is documented.
  • Q: 1/4=80
    specifies a suggested speed: 80 quarter notes per minute.
  • Measures are separated by bar lines represented by ‘|’.
  • There will be multiple verses, so ‘:|’ adds a repeat bar line.
  • A final bar line is ‘||’, but we don’t use it for this example.
  • It is good practice for debugging to divide the lyrics into measures as well, and not rely on automatic distribution.
  • Note that additional spaces can be added for readability.
  • Lining up the bar lines is not required, but can make it more readable.

Here is tune 3 with bar lines (appended to

X: 3
T: O lux beata Trinitas (3)
C: Words: St. Ambrose 4th century
C: Plainsong, Mode VIII
M: 7/8
L: 1/8
Q: 1/4=80
K: D
% Fedora Magazine example
z(AB) (AGFG) | EFG     (AB) (BA) | A3-A4 |
w: O*  lux***|be-a-ta trin-* ni-*| tas,  |
z(AB) (AGFG)   |  EFG    (AB) (BA)| A3-A4 |
w: et* prin-***|ci-pa-lis U-* ni-*| tas,  |
 (AB) d (cd)   B (A |G) (AB) (AGF)   F-| F7|
w:i-* am sol* re-ce-|* dit*  i-*gne-us,| * |
z(GA)  (AGFG) | EFG      (AB) (BA) | A3-A4 :|
w:in-* fun-***| de lu-men cor-*di-*|bus. |

Bass Line, Chords, and Verses

Now we begin the real departure in our interpretation. First, chords are added to assist in improvising from a “lead sheet”. Then we add a suggested bass line.

  • V:1
    switch between voices.
  • Chords are entered in double quotes in the tune line, and are rendered above the following note.
  • Each comma after a note lowers it by an octave.
  • C:
    can also be used to document arranger and license.
  • Addition verses are added as additional lyric lines under a tune line.
  • Verse numbers can be added by using ‘~’ to join them to the next word with a non-break space. Otherwise they would be counted as words.
  • %%MIDI
    these are magic comments that are used in the next section!

Here is our final tune for this lesson:

X: 4
T: O lux beata Trinitas (4)
C: Words: St. Ambrose 4th century
C: Plainsong, Mode VIII
C: Arranged: Stuart D. Gathman
C: Copyright 2012: Creative Commons Attribution-ShareAlike 2.0
M: 7/8
L: 1/8
Q: 1/4=80
K: D
%%MIDI gchord c3c4
%%MIDI program 75
"D"z(AB) (AGFG) | "A7"EFG (AB) (BA) | "Dsus"A3-"D"A4 |
w:i.~O*  lux*** |be-a-ta trin-* ni-*| tas,  |
w:ii.~Te* ma-***|ne lau-dum car-*mi-*| ne, |
w:iii.~De-* o***|Pa-tri sit glo-*ri-*| a, |
   D,3  A,2 A,2 |   E,3  A,2 A,2    | D,3  A,2 A,2 |
"D"z(AB) (AGFG) | "A7"EFG (AB) (BA) | "Dsus"A3-"D"A4 |
w:  et* prin-***|ci-pa-lis U-*  ni-*| tas,  |
w:  te* de-***  |pre-ce-mur ves-*pe-*|re: |
w:  ei-* us-*** |que so-li   Fi-*li-*| o, |
   D,3  A,2 A,2 |   E,3  A,2 A,2    | D,3  A,2 A,2 |
"G"(AB) d (cd) B (A  |"Em"G) (AB)  (AGF)  F-|"D"F7 |
w: i-* am sol* re-ce-|*     dit*  i-*gne-us,| * |
w: te* nos-tra* sup-plex|* glo-*ri-**a | * |
w: cum* Spi-ri-*tu Pa-|* ra-*cli-**to, | * |
   G,3  B,2 B,2 |   D,3  B,2 B,2    | D,3  A,2 A,2 |
"A7"z(GA) (AGFG) | "A7"EFG (AB) (BA) | "Dsus"A3-"D"A4 :|
w: in-* fun-***  |  de lu-men cor-*di-*| bus. |
w: per* cunc-*** | ta lau-det sae-*cu-*| la. |
w: et*  nunc,*** |  et in per-pe-*tu-* | um |
   E,3  A,2 A,2 |   C,3  A,2 A,2    | D,3  A,2 A,2 :|

Rendering to MIDI

Rendering that makes a nice lead sheet! What does it sound like? You will need the abc to MIDI translator and a MIDI renderer. Fedora comes with a number of MIDI synthesizer and rendering options, but we will use timidity – a simple command line utility that can render to audio files or play on your speakers.

Install abcMIDI and timidity:

$ sudo dnf install abcMIDI timidity++

If you have been following the examples, you have 4 tunes in Render them to midi with the abc2midi utility:

$ abc2midi

This creates four midi files, one for each tune: lux1.mid .. lux4.mid. Use timidity to play each file to your speakers:

$ timidity lux1.mid

When you play ‘lux4.mid’, you will hear what the ‘%%MIDI’ directives did. You can read more about abc2midi and its directives here. You can also hear me singing and playing piano from the lead sheet and totally butchering the Latin.

There is a lot more to ABC, but this has hopefully been a fun introduction!  There are more examples in /usr/share/doc/abcm2ps/examples, and check out folk tunes from many cultures.

Fedora Project community


  1. Silvia

    Nice to see some multimedia-oriented articles. Thanks! Very interesting.

  2. Nice article! I love ABC and Timidity. It’s so easy once you learn a few things, especially if you’re a programmer because it’s so much like that. Thanks for sharing this!

  3. Mehdi

    Very interesting article. Thanks for posting

  4. Mehdi

    Btw, your piano piece and your voice performance is amazing.

  5. Daniel

    Another option to render it on-line is Example: or the self hosted version

    If you want to convert abc notation to commandline beep script (pcspkr music), try my script

  6. Christopher Augustus

    Fascinating article. I used to play around with MIDI on my old Apple IIGS and wished for a way to enter MIDI with a text editor. Fast forward to today and here is a way to do just that. The PDF output of the score is amazing. I now have several more command line tools in my toolbox to help complete some small things I have been wanting to do.

  7. Bruno

    Interesting, I cannot help to mention MuseScore
    You can install the AppImage for the latest and greatest Open Source “world’s most popular notation software”.
    (It features ABC import, plugin included out of the box)

Comments are Closed

The opinions expressed on this website are those of each author, not of the author's employer or of Red Hat. Fedora Magazine aspires to publish all content under a Creative Commons license but may not be able to do so in all cases. You are responsible for ensuring that you have the necessary permission to reuse any work on this site. The Fedora logo is a trademark of Red Hat, Inc. Terms and Conditions