ABC Music Notation

by John Chambers

This is a tutorial for the ABC notation and some of its software. You are reading the experimental, "in-development" version. Please send me comments about suggestions, typos, ideas, etc. I also have two very brief introductions to ABC, a plain text intro and an HTML intro. If you are not familiar with ABC, you might find these a better starting place than this in-depth tutorial.

Intro
Tunes
Notes
Lengths
Repeats
Accidentals
Tuplets
Ties and Slurs
Chords
Grace Notes
_
_
Words
Voices
_
Readability
Headers
History
ABC Sites
Glossary
ABC Links

Intro

In 1993, Chris Walshaw introduced a simple plain-text music notation, together with the abc2mtex program that translated it to the input format that the MusicTeX and TeX programs use. The result was some very nice "sheet music". Soon after, Michael Methfessel started writing a standalone program, abc2ps, which converts ABC to PostScript without requiring a complex package like TeX. Then James Allwright followed with abcMIDI, which converted back and forth between ABC and MIDI notation. Other programs soon appeared for Macintosh and DOS/Windows users.

Chris and most of the early users were folk musicians, and ABC has so far been used mostly to transcribe folk melodies. Slowly features have been added to support new sorts of musical notation. But all along the primary benefits of ABC have been maintained: It is a notation that is easy to type on an ordinary keyboard. The files are small, and can be sent via email or downloaded from web sites very quickly. If properly formatted, ABC notation can be very readable. And it's easy to write code in most common programming languages to parse ABC and do things with it.

There is now a rather large and growing population of software that understands ABC. Some of the commercial music packages now accept ABC as input and will produce it as output. This is not without a lot of grumbling over ABC's missing features. But it's the same phenomenon as the debate about fancy word processors versus plain text. ABC has the typical advantages of plain text: It's easy to read and type on any computer. It can be sent anywhere via email. It is very compact, making for small files and fast downloads. But it lacks most of the fancy features of the more advanced notation systems.

Another dichotomy that is useful in appreciating ABC's role is the difference between "markup" and "formatting" notation. ABC is primarily a "markup" system. It identifies the parts of the music, and provides a way of giving information about the music. But it intentionally includes little information about formatting or other interpretation. This is left for other add-on notation to handle. This has helped in the spread of ABC, because with most other kinds of music software, it can be very difficult to write your own program to extract information like title, author, rhythm, and so on. But with ABC, it's easy, and a number of ABC indexing schemes have appeared.

For a current list of software and other ABC pointers, see Chris' abc home page.

For a simple example of what ABC looks like, here is Chris' transcription of a well-known Irigh jig:

X:1
T:Paddy O'Rafferty
C:Trad.
M:6/8
L:1/8
K:D
dff cee|def gfe|dff cee|dfe dBA|dff cee|def gfe|faf gfe|1 dfe dBA:|2 dfe dcB||
~A3 B3|gfe fdB|AFA B2c|dfe dcB|~A3 ~B3|efe efg|faf gfe|1 dfe dcB:|2 dfe dBA||
fAA eAA|def gfe|fAA eAA|dfe dBA|fAA eAA|def gfe|faf gfe|dfe dBA:|

Here is what it looks like after processing by abc2mtex and conversion to GIF:
PaddyORafferty

Here is what it looks like after processing by abc2ps and conversion to PNG:
PaddyORafferty

You can see that there are some stylistic differences, but both produce very nice-looking music. The PostScript output looks even nicer than GIF or PNG files ever can, and can also be input to many document preparation programs.

So now let's go on to how ABC notation works.

Tunes

ABC is written in chunks; each chunk is called a "tune". In its simplest form, a tune consists of two parts:

header lines: Information about the tune as a whole.
music lines: ABC notation for the notes and chords, and possibly lyrics.

A blank line indicates the end of the tune. In the above example, the headers are:

	X:1
	T:Paddy O'Rafferty
	C:Trad.
	M:6/8
	L:1/8
	K:D

Let's look at these one at a time.

X: 1

The first line must give an index number to the tune. This is like the track number on an album. It is used by assorted ABC software to select tunes from a file with more than one. Some people leave out the X: line in single-tune files, but this tends to confuse a lot of ABC software. So it's a good idea to always include one, even if there is only one tune in the file.

T: Paddy O'Rafferty

The second line gives a title, and may be repeated for tunes with several titles. Different programs may have limits to the number of accepted titles, but everything seems to accept at least four.

C: Trad. This gives a composer. If the composer isn't known, this line may be omitted. If the tune is definitely known to be traditional, it might a good idea to indicate this, so people don't think you forgot to give proper attribution.

M: 6/8 This is the meter. It defaults to 4/4. The usual fractional notation may be used. You can also use C for common (4/4) time, and C| for cut (2/2) time. (That's a vertical bar, not the letter l or the digit 1.) Many programs also accept M:none to indicate a free rhythm with no time signature.

L: 1/8 This is the unit note length. Notes may be followed by a length (a fraction), which is multiplied by this to get the actual note length. The default is a bit complicated: For meters that are numerically 3/4 or longer, the default note length is 1/8. For meters that are numerically less than 3/4, the default note length is 1/16. It's probably best to always include the L: line and not depend on defaults.

K: D This gives the key, and must be the last line of the header. The classical modes are recognized, and may be abbreviated to their first three letters. Minor can be indicated by just "m". Some examples:

ABC	key	signature
K:D	D major	2 sharps
K:Dm	D minor	1 flat
K:Dmin	D minor	1 flat
K:Dminor	D minor	1 flat
K:DDor	D Dorian	No sharps or flats
K:DDorian	D Dorian	No sharps or flats
K:DMix	D Mixolydian	1 sharp
K:DPhr	D Phrygian	2 flats

This isn't nearly the whole story for headers. There are a large number of other header lines defined. And most of the lines can also be used inside the music section of a tune to change the information. See the Headers section below for a full description.

Notes

The important part of the music is the notes, right? OK, here's a scale exercise in ABC:

X:2
T:
K:C
|| G,A,B,C DEFG | ABcd efga | bc'd'e' f'g'g'a' ||
w: G, A, B, C D E F G A B c d e f g a b c' d' e' f' g' a'

Here's how that comes out in standard music notation:
Scale from low G, to high a'

There are several things to notice here:

The letters CDEFGAB are the lower half of the staff; the letters cdefgab are the upper half. Musicians will understand why this funny order is used, though programmers don't always like it.

Comma (,) and apostrophe (') are used to mean "down an octave" and "up an octave" respectively. These are pictorial, since a comma is a low character and an apostrophe is high. You can repeat these characters to get more octaves.

I snuck in the notation for bar lines when you weren't looking. Sure enough, the vertical bar (|) is used for bar lines. You can use two of them to get a double bar. You can also use [| to get a thick+thin double bar, and you can use |] for a thin+thick double bar. We'll get to repeats later.

The M: and L: lines were omitted, so they defaulted to M:4/4 and L:1/8.

Notes without spaces are beamed together if possible. This is the main situation where spaces are significant in ABC.

There is a notation for including words aligned with the notes. We'll get to that later.

Lengths

In addition to saying what note to play, you need to say how long the note is. ABC does this by simply putting a number after the note. The number can be an integer or a fraction, and means to multiply the default length by that much. You can't combine an integer and a fraction, so 1-1/2 would be written as 3/2.

For example, A2 is an A played twice as long as just A. For example, A3/2 is an A played 50% longer than A.

In fractions, a numerator of 1 and a denominator of 2 can be ommitted. So A1/2, A/2 and A/ all mean the same thing, an A half as long as just A.

There is a useful length abbreviation: The characters < and > between two notes mean to take away half of one note's length and give it to the other, with < meaning "short+long" and > meaning "long+short". Thus c>d means the same as c3/2d1/2 (or c3/d/). You can also repeat these characters, using << and >> for double-dotted note pairs.

Here is a simple test case, which is not very musical, but illustrates various ways to indicate unit note lengths.

X: 5
T:
K: C
[| D D2 D3 D4 D6 | d d/ d3/ d3/4 d7/8 | EF/G//A// BA1/2G1/4F/4 \
| E>D C<D E>>F G>>A| B2>c2 d2>>c2 |]

This comes out on paper as:
note lengths

Some things to notice about ABC's note-length notation:

Once again, I was too lazy to type the M: and L: lines, so they defaulted to M:4/4 and L:1/8, and all the note lengths are multiples of 1/8. I've violated my own advice that it's always better to give these explicitly and not trust the software to guess right.

The first bars don't add up to 4/4. Most ABC software doesn't care. Some programs have an option for checking measure lengths. A few programs won't accept this at all, but they will probably be fixed in future releases, as the authors learn about free-rhythm music and understand that they have to support it.

ABC can represent "funny" note lengths, and G5/7 is a perfectly valid note in ABC, and programs that convert ABC to sound (such as playabc and abcMIDI) will accept it. But standard notation can't handle them, so it's not a good idea to do such things. In the above examples, D5 and D5/4 would get error messages from any program trying to show the music in standard notation.

I snuck in another bit of ABC: The final backslash (\), meaning "continued on next line". ABC normally treats each line as the start of a new staff, but if a line gets long, this is a simple way of breaking it into several short lines.

This example also illustrates why it's usually a very bad idea to try to embed ABC inside HTML. If you look behind the scenes at the source to this page, you will find that all the < and > characters are encoded as "HTML entities". They probably look fine your screen, but any ABC program that tries to read this file is likely to get very confused by the second line of music above.

Repeats

There are several ways of indicating repeats in standard music notation, and ABC has counterparts to the most common.

Repeat symbols

The most common way of indicating repeats is with colon-like symbols next to bar lines. ABC simply uses the colon (:) character for this in the obvious way:

    |: CDE FGA | Bcd efg :|

This is a two-bar repeated phrase. Sometimes you see multiple colons:

    |:: CDE FGA | Bcd efg ::|

This is not part of the official ABC notation standard yet, though some programs might understand it.

There is also an abbreviation: :: means the same as :|:, a bar line with repeat indicators on both sides. How it is drawn may be different for different programs.

Repeated phrases frequently have different endings on the repeats. There is a standard way of handling this in ABC:

    |: CDE FGA |1 Bcd efg :|2 Bcd eBc :|

The use of a number like this immediately after a bar line indicates an alternative ending in the obvious manner. However, this notation currently has a serious limitation. Many ABC programs only recognize |1 and |2, but won't accept any other numbers. This is a topic that has led to some discussion, and it may be fixed eventually. The final decision isn't in, but we can expect something like:

    |: CDE FGA |1,3 Bcd efg :|2 Bcd eBc :|4 Bcd c3 :|

Repeat lists

Another scheme used by some musicians (especially dance musicians) is to label all the parts of the tune, and then give a repeat pattern at the top of the tune, usually at the upper left. ABC can do this, a most ABC software understands it. For example:

X: 1
T: Country Garden(s)
P: A(A2B2C2B2)2
M: C|
L: 1/8
K: C
P: A
[| g2  g>f e2 e2 | d2  d>c B2 B>c |  d2 G2 A2 c2 | B3A G4 |]
P: B
[| g>a g>e f2 d2 | g>a g>e f4     | g2 g>f e2 a2 | f3e d2 B>c |
|  d2  g>f e2 e2 | d>e d>c B2 B>c | d2 G2  A2 c2 | B3A G4 |]
P: C
[| G2  c2 c2  e2 | d>e d>c B2 B>c | d2 G2  A2 c2 | B3A G4 |]

Here's how this comes out as a PNG file:
Country Gardens

In this example, the header lines include:

P: A(A2B2C2B2)2 This indicates the order in which the parts are to be played. The letters correspond to the later P:A, P:B and P:C lines, which identify the tune's three parts.

Note that the P: lines are being used in two different ways here. Within the header portion of a tune, P: gives the order of the parts. Within the music portion of a tune, P: is used to label each part.

There is an alternative way of labeling the parts that some software (such as abc2ps) now accepts. You can put the label in double quotes before a bar line. This lets you put the label anywhere, not just at the start of a line. Written this way, the above tune would be:

X: 4
T: Country Garden(s)
Z: 1997 by John Chambers <jc@trillian.mit.edu> http://trillian.mit.edu/~jc/music/abc/
P: A(A2B2C2B2)2
M: C|
L: 1/8
K: C
"A" | g2  g>f e2 e2 | d2  d>c B2 B>c | d2 G2  A2 c2 | B3A G4 |]
"B"[| g>a g>e f2 d2 | g>a g>e f4     | g2 g>f e2 a2 | f3e d2 B>c |
   |  d2  g>f e2 e2 | d>e d>c B2 B>c | d2 G2  A2 c2 | B3A G4 |]
"C"[| G2  c2  c2 e2 | d>e d>c B2 B>c | d2 G2  A2 c2 | B3A G4 |]

Here's what this looks like as a PNG file:
Country Gardens

One qualification about both of these schemes for labeling the parts: Many people have used this as a way of merely putting text ("Adagio") to the upper left of a staff. This works if your only intent is to produce printed music. It can confuse some programs that attempt to play the music. Eventually there might be ways of doing both with different notation.

Accidentals

Tuplets

Ties and Slurs

Chords

There are two fundamentally different way of dealing with chords:

Accompaniment chords written above or below the staff.

Multiple-note chords played by a single instrument. We will deal with these separately here, since they are written differently in ABC (and in most standard music notation).

Accompaniment or "guitar" chords.

Chords to accompany the melody, i.e., accompaniment chords (termed 'guitar chords' in the previous abc standard) can be included. Depending on the package, accompaniment chords will be displayed either above or below the melody line. Some playback packages can play accompaniment chords.

An accompaniment chord is enclosed in double-quotation marks. It is placed to the left of the note it is sounded with, without an intervening space, e.g., "Am7"A2D2.

The chord has the format <note><accidental><type>/<bass>, where <note> can be A-G, <accidental> can be b, #, or nothing, <type> is the type of chord, and /<bass> is an optional bass note.

Valid chord types are:

m or min	minor
maj	major
dim	diminished
aug or +	augmented
sus	sustained
7, 9 ...	7th, 9th, etc.

The chord type can be combined, e.g., Cdim7. And, obviously, maj can be (and usually is) omitted.

A slash after the chord type is used only if the optional bass note is also used, e.g., "C/E". If the bass note is a regular part of the chord, it indicates the inversion, i.e., which note of the chord is lowest in pitch. If the bass note is not a regular part of the chord, it indicates an additional note that should be sounded with the chord, below it in pitch. The bass note can be any letter (A-G or a-g), with or without a trailing accidental sign (b or #). The case of the letter used for the bass note does not affect the pitch.

Alternate chords can be indicated for printing purposes by enclosing them in parentheses inside the double-quotation marks after the regular chord, e.g., "G(Em)". But note that most ABC playback software will simply ignore such alternate chords. Music printing programs will just show the text as-is, of course. Whether transposing will effect alternate chords isn't predictable yet, and probably depends on just which program you are using.

Examples? How about our Country Garden friend, this time with chords:

X: 3
T: Country Garden(s)
Z: 1997 by John Chambers <jc@trillian.mit.edu> http://trillian.mit.edu/~jc/music/abc/
P: A(A2B2C2B2)2
M: C|
L: 1/8
K: C
P: A
 | "G7"g2 g>f "C"e2 e2 | "D7"d2 d>c "G"B2 B>c | "G"d2 G2 "C"A2 c2 | "D7"B3A "G"G4 |]
P: B
[| "A7"g>a g>e "D"f2 d2 | "A7"g>a g>e "D"f4 | "A7"g2g>f e2a2 | f3e "D7"d2B>c |
|  "G7"d2 g>f "C"e2 e2 | "D7"d>e d>c "G"B2 B>c | "G"d2 G2 "C"A2 c2 | "D7"B3A "G"G4 |]
P: C
[| "C"G2c2 c2e2 | "D7"d>e d>c "G"B2 B>c | "G"d2 G2 "C"A2 c2 | "D7"B3A "G"G4 |]

And here's what this looks like as a PNG file:
Country Gardens

The main thing to note about this is that some ABC programs will put the chords below the staff, and some programs may have an option to control this placement. Music publishers have been quite inconsistent about which position is "standard".

Multiple-note chords.

ABC's notation for multiple notes played simultaneously looks like:

[CEGc]

This is a written-out C chord, and will appear on a printed page with all the notes on one stem. Note lengths should go after each note in the chord:

[C2E2G2c2]

ABC can handle chords with different lengths for every note, but there are some qualifications about how well this notation works in practice:

Some playback programs are monophonic. They will typically treat the first note as the "melody" note, and only play that note.

Standard music notation can't handle different lengths very well, so you should use it sparingly. On the other hand, music-playing programs should be able to handle any lengths without difficulty.

Some programs will apply the length of the first note to all the others.

Putting a note in a chord twice, as in [ccA], will result in stems pointing both up and down with some programs (such as abc2ps); other programs will treat it as a single note.

Tieing or slurring notes in chords is not well defined, and probably shouldn't be used at present. However, ties or slurs applied to an entire chord should work without problems.

Here's an example of the use of chords to write out a simple harmony. Note that the lower note is consistently written as the first of each "chord", so that monophonic players will treat it as the melody. (Of course, anyone familiar with Balkan music will realize that either line can be considered the "melody" and the other the "harmony".)

X: 1
T: Sva Nok le, Nado
O: Makedonija
R: slow pravo
M: 4/4
L: 1/8
K: F
[| "C"[c3e3] [df] [ce][Bd] [Bd][Ac] | "F"[Ac][G2B2] [Ac] [GB][FA] [FA][FC] \
| [FA][GB] [GB][Ac] "C7"[GB][Ac] [GB][FA] | "F"[FA][GB] [FA][CG] [FA][GB] [Ac][Bd] |
| "C"[dB][ce] [ce][df] [ce][Bd] [Bd][Ac] | "C7"[Ac][B2G2] [Ac] "F"[GB][FA] [F2A2] \
| [FA][GB] [GB][Ac] "C7"[GB][Ac] [GB][FA] | "F"[F8A8] |]
[| "F"([F3A3] [GC]) [F2A2] ([FA][GB]) | ([A3c3] [GB]) ([GB][FA][F2A2]) \
| ([FA][GB]) [A2c2] "C7"([GB][Ac]) ([GB][FA]) | "F"([F3A3] [CG] [FA][GB] [A2c2]) |
| "F"[F2A2] ([FA][CG]) [F2A2] ([FA][GB]) | ([A3c3] [GB]) ([GB][FA] [F2A2]) \
| ([FA][GB]) [A2c2] "C7"([GB][Ac]) ([GB][FA]) | "F"[F8A8] |]
[| "C"[c4e4] ([ce][Bd]) ([Bd][Ac]) | "F"([A3c3] [GB]) ([GB][FA] [F2A2]) \
| ([FA][GB]) [A2c2] "C7"([GB][Ac]) ([GB][FA]) | "F"([F3A3] [CG] [FA][GB] [A2c2]) |
| "C"[c4e4] ([ce][Bd]) ([Bd][Ac]) | "C7"([Ac][B2G2]) [Ac] "F"([GB][FA]) [F2A2] \
| ([FA][GB]) [A2c2] "C7"([GB][Ac]) ([GB][FA]) | "F"[F8A8] |]

Grace Notes

ABC has a simple notation for grace notes:

{cd}e

This represents the note e with two grace notes, c and d, before it. Music formatting programs will represent these as tiny notes. Playback programs will play them somehow, but exactly how isn't defined by ABC itself. A good way to write out complicated ornaments is to write the main notes as regular notes with their full time, and fill in between them with little notes. Here's an example:

X:12
T:Gracenotes
L:1/8
M:C
K:D
| {E}FA{c}AF DF{^dc}A f{A}df f{AGA}df \
| {B}D2 {A}D2 {G}D2 {F}D2 {E}D2 \
| {E}c2 {F}c2 {G}c2 {A}c2 {B}c2 |
| {A}^c2 {gcd}c2 {gAGAG}A2{g}c<{GdG}e {Gdc}d>c {gBd}B<{e}G \
| {G}[G4e4] {FGAB}[^c4A4] {ef}[e4c4] {d'c'bagfedcB_AcBFGC}D4 |]

The final example here is a bit extreme, but shows what can be done. One limit to ABC's current grace-note notation: You can't use lengths, so you can't break up such long strings of grace notes to improve readability. Maybe some day this will be addressed (and maybe not).

_

Words

A lot of music has words, otherwise known as lyrics, and there are two ways of showing them. You can put them below the music staff, aligned with the notes. Or you can show all the words below the music, in poetry format. The original ABC only did the latter; now it does both.

Putting words below the music is easy: Put W: at the start of each line. Such lines are collected by the music formatting programs, and produced after the last music staff is finished.

Putting words below the notes is more complicated, and is handled by lines that start with w: (note the lower-case w). W: lines can occur anywhere, though they are conventionally in the header. You must put w: lines immediately below their staff of music, of course.

Before explaining more, here is an example of a well-known Greek folk song, with the words included in both forms:

This was produced by abc2ps from the following ABC:

X: 1
T: Misirlou
C: N.Roubanis 1934
O: Greece
W: 1. Misirlou mou i glikia sou matia
W:    Floga m'ehi inapsi mes tin kardia
W:    Ah! Yahabibi Ah! Yaleleli Ah!
W:    Apto diko sou to sto mataki ime
W: Chorus:
W:    A Misirlou
W:    Trella tha m'erthi den ipofero pia
W:    Ah! tha si klepso mes ap tin Arapia.
W:    Ah Misirlou.
W:
W: 2. Mavro mata Misirlou mou trelli
W:    Ti zoi m'allazo mena fili
W:    Ah! yahabibi M'ena filaki Ah!
W:    ta dio sou hili stazoune meli ime
M: 4/4
L: 1/8
K: Gm
|: "D"D3 E ^F2 G2 | A3B ^c2BA | A8- | A8 |
w: 1.~Mi-sir-lou mou i gli-kia sou ma-tia
w: 2.~Mav-ro ma-ta Mi-sir-lou mou tre-lli
| D3E ^F2G2 | A3B ^c2BA | A8- | A8 |
w: Flo-ga m'e-hi~i-na-psi mes tin kar-dia
w: Ti zo-i m'al-la-zo me-na fi-li
| "Gm"BA2B A2G2 | AG2A G2^F2 | "D"^F8- | ^F8 |
w: Ah! Ya-ha-bi-bi Ah! Ya-le-le-li Ah!
w: Ah! ya-ha-bi-bi M'e-na fi-la-ki Ah!
| "Cm"AG2A G2^F2 | ^FE2F E2DD | "D"D8- | D8 :|
w: ta dio sou hi-li sta-zou-ne me-li i-me
w: Ap-to di-ko sou to sto ma-ta-ki i-me
|: "Gm"G8- | G6 ^FG | "F"A8- | A6 GA | "Bm"B6 AB | "A"^c6 Bc | "D"d8- | d8 |
w: A___________ Mi-sir-lou
| "Cm"e d2 e d2 c2 | d c2 d c2 B2 | "D"A8- | A8 |
w: Tre-lla tha m'er-thi den i-po-fe-ro pia
| "Cm"c B2 c B2 A2 | A G2 A ^F2 E2 | "D"D8- | D8 :|
w: Ah! tha si kle-pso mes ap tin A-ra-pia.
P: Coda
|| "Gm"B6 AB | "A"^c6 Bc | "D"d8- | d8- | d8- | d z7 |]
w: Ah___ Mi-sir-lou.

The W: lines are self-explanatory, but there are a number of special symbols inside the w: lines that deal with the alignment with the notes. The basic rule is that each "word" is aligned with one note, where a "word" is whatever comes between chunks of white space. But the following can be used to modify this:

~ (tilde): This is turned into a space, but doesn't count as a "word". It lets you put two words on a single note. In this example, it also separates the 1. and 2. from the first word of the text. The abc2ps formatter has a special kludge to spot this and outdent the number, so the second "word" lines up with the note.
- (hyphen): This is used as a syllable separator, and each syllable is lined up with one note.
* (asterisk): This means that the syllable takes up an extra note. Use as many as you need to cover all the the notes. You can also use * at the start of the line, to skip over notes.
_ (underscore): This is like *, but draws a long horizontal after the syllable. Some music publishers like to show long words this way; others don't. It is appropriate in this example, for the long melismas on the word "Ah!"
| (bar line): This wasn't used in the above example. If you use it, each | lines up with one bar line in the music. This can be used if you want the words to start several bars in, and don't want to bother counting notes.

You might think that the W: and w: would be used only by the music formatting programs such as abc2mtex and abc2ps, but you'd be wrong. Some of the music-playing programs now have a "karaoke" option that displays or highlights the words as the music plays. Perhaps some day a program will include voice synthesis, so you can select a "Frank Sinatra" or "Ella Fitzgerald" or "Bob Dylan" voice, and hear how that singer would have done the song.

Voices

ABC is somewhat biased towards a "voice", that is, a sequence of notes for an instrument that produces one note at a time. There is work underway to design a multi-voice facility for ABC, so that choral, orchestra and band scores can be represented easily. This is currently under active development, and is rather preliminary. Different ABC software currently implements different portions of this.

The most general syntax so far defines a voice with a header line of the form:

V: label par1=value1 par2=value2 ...

Such lines should appear within the header of the tune. Within the music portion, you would use only:

V:label

You may also use

[V:label] music ...

This is convenient because it lets you put the music on the same line.

Currently, there is disagreement on what the label may be. Some programs only allow numbers (and may insist that they be consecutive). Other programs allow any single word, such as V:Soprano or V:Cello. Most of the examples so far use only numbers.

There are a number of parameters that may be used in the definition of a voice. Here are some of the parameters defined so far:

param short example description

name nm nm="Violin I" This sets the long version of the voice name, to be written before the staves at the start of a piece. If the string contains \\, this is interpreted as a line break and the pieces are writen above each other.

sname snm snm="Vl. I" Short version of the name, written before subsequent staves.

clef cl clef=bass Chooses the clef (treble, alto, or bass). It can also be bass+8 and so on.

staves stv stv=2 This is the number of staves (starting from the current one) to connect by tall vertical bar lines.

brace brc brace=2 This is the number of staves (starting from the current one) to be grouped together with a brace. When this option is used, the name defined in the same V: line is written at the center of the brace.

bracket brk brk=4 The number of staves to be grouped together by a bracket. This option does not change the way in which the names are written.

space spc spc=40 This defines or modifies the vertical space between this staff and the one below it. The space can be given in pt (default) or with a unit in the form 1cm or 0.4in. Furthermore: if a + or - sign comes after the start of the number, the value is an increment to be added to or subtracted from the default setting.

gchords gch gch=0 This controls whether any guitar chords embedded in the current voice are actually written. True/false are specified as for the %% formats.

stems stm stems=up This says that stems for this voice's notes should all go in the same direction, which may be "up" or "down". The default is to let the program draw stems as it wishes, including the possibility that notes will be joined on a single stem.

param	short	example	description
name	nm	nm="Violin I"	This sets the long version of the voice name, to be written before the staves at the start of a piece. If the string contains \\, this is interpreted as a line break and the pieces are writen above each other.
sname	snm	snm="Vl. I"	Short version of the name, written before subsequent staves.
clef	cl	clef=bass	Chooses the clef (treble, alto, or bass). It can also be bass+8 and so on.
staves	stv	stv=2	This is the number of staves (starting from the current one) to connect by tall vertical bar lines.
brace	brc	brace=2	This is the number of staves (starting from the current one) to be grouped together with a brace. When this option is used, the name defined in the same V: line is written at the center of the brace.
bracket	brk	brk=4	The number of staves to be grouped together by a bracket. This option does not change the way in which the names are written.
space	spc	spc=40	This defines or modifies the vertical space between this staff and the one below it. The space can be given in pt (default) or with a unit in the form 1cm or 0.4in. Furthermore: if a + or - sign comes after the start of the number, the value is an increment to be added to or subtracted from the default setting.
gchords	gch	gch=0	This controls whether any guitar chords embedded in the current voice are actually written. True/false are specified as for the %% formats.
stems	stm	stems=up	This says that stems for this voice's notes should all go in the same direction, which may be "up" or "down". The default is to let the program draw stems as it wishes, including the possibility that notes will be joined on a single stem.

Comments

ABC uses the percent (%) character to mean "Ignore the rest of this line." You can use this to add any text you want to an ABC tune, and it will be ignored by ABC software.

One simple use of this is to put a line with just a % into a tune as a separator. You may have noticed that, since an ABC tune ends with the first blank line, you can't have a blank line inside a tune. But sometimes you want one to make things more readable. A line with just a % will do the job.

Another way in which % is used is as a sort of "escape" to pass non-ABC information to particular ABC programs. There are several ABC tools that use this, mostly in the form of lines that start with %%.

abc2ps: You can give formatting information to abc2ps with %% lines. The same information can be given in the command-line arguments, or in a file whose name ends in .fmt, but these can only set global formatting options. If you want to make changes, it may be more convenient to embed the commands in the ABC itself.
abc2midi: You can specify such things as instruments and loudness in %%MIDI lines.

Readability

One of the nice things about ABC notation is that it is fairly readable. Many people are already claiming that they can read ABC nearly as easily as standard music notation. However, as with anything, there is good and bad ABC notation. Here are some suggestions for making your ABC easy to read.

The main suggestion is to use spaces. Consider these lines of music:

|"C"EDC|GF"C7"E|"F"ccA/B/|c3|"C"GEC|CB,C|"D7"EDD|"G7"D2G|
|"C"GGE/F/|GG"C7"c|"F"ccA/B/|c2A|"C"GEC|"G7"DED|"C"C3-|C3||

Not very nice to read, is it? Now compare it with:

| "C"EDC    | GF "C7"E | "F"ccA/B/ | c3  | "C"GEC |    CB,C | "D7"EDD | "G7"D2G |
| "C"GGE/F/ | GG "C7"c | "F"ccA/B/ | c2A | "C"GEC | "G7"DED |  "C"C3- | C3     ||

You probably find this much easier to read. There are two ways that the spacing makes the second easier to read:

Putting spaces around the bar lines isn't required by ABC, but it really improves readability.

We also aligned the notes and chords vertically in these two parallel lines of music. This makes the chords stand out somewhat from the notes, and makes it easier for a reader to associate the notes with the rhythm.

A third, more subly thing that was done in both of the above examples was to make each phrase start a new line. This isn't always possible, just as it isn't with standard music notation, but when you can do it easily, you should.

Headers

Here's a table of the current ABC header information lines:

	Field name	header	tune	elsewhere	Used by	Examples and notes
A:	area	optional				A:Donegal, A:Bampton
B:	book	optional		yes	archive	B:O'Neills
C:	composer	optional				C:Trad.
D:	discography	optional			archive	D:Chieftans IV
E:	elemskip	optional	yes			see Line Breaking
F:	file name			yes		see index.tex
G:	group	optional		yes	archive	G:flute
H:	history	optional		yes	archive	H:This tune said to ...
I:	information	optional		yes	playabc
K:	key	last	yes			K:G, K:Dm, K:AMix
L:	note length	optional	yes			L:1/4, L:1/8
M:	meter	optional	yes	yes		M:3/4, M:4/4
N:	notes	optional				N:see also O'Neills - 234
O:	origin	optional		yes	index	O:I, O:Irish, O:English
P:	parts	optional	yes			P:ABAC, P:A, P:B
Q:	tempo	optional	yes			Q:200, Q:1/4=120, Q:C2=200
R:	rhythm	optional		yes	index	R:R, R:reel
V:	voice	optional	yes			V: 2=2nd violin, V:3
S:	source	optional				S:collected in Brittany
T:	title	second	yes			T:Paddy O'Rafferty
W:	words	yes	yes			Words placed below the last staff
w:	words	no	yes			Words placed below the notes
X:	index number	first				X:1, X:2
Z:	transcription	optional				Z:Joe Smith <js@fu.bar.com> from handwritten copy

Some of these make sense only in the header portion of a tune, while others may be used inside the music portion to change the information.

Some programs (such as abc2ps) now accept notation such as: [K:...] to change information inside a line of music. But this notation might be ignored by some ABC software.

Now for detailed descriptions:

A: area

The A: header line is not seen much. Its intent is to list geographic areas where particular versions of tunes are found. This function overlaps somewhat with the S: line.

B: book

The B: header line is used to give a list of publications where the tune may be found.

C: composer

The composer's name will be shown at the upper-right of the first staff by ABC formatting programs. For tunes known to be traditional, C:Trad is probably a good idea so that people don't think the composer has just been ignored.

D: discography

The D: header line is used to list recordings of the tune.

The H: line is used for historical information about the tune. Dates, names of variants, uses in performances are all appropriate here.

I: information

K: key

The K: line is the last line of a tune's header. It may be repeated inside the tune to get a change of key signature. The classical modes are recognized, and may be abbreviated to their first three letters. Minor can be indicated by just "m". Some examples:

K:D	D major	2 sharps
K:Dmaj	D major	2 sharps
K:Dmajor	D major	2 sharps
K:Dm	D minor	1 flat
K:Dmin	D minor	1 flat
K:Dminor	D minor	1 flat
K:C	C major	No sharps or flats
K:Am	A minor	No sharps or flats
K:DDor	D Dorian	No sharps or flats
K:DDorian	D Dorian	No sharps or flats
K:ELyd	E Lydian	No sharps or flats
K:DMix	D Mixolydian	1 sharp
K:DPhr	D Phrygian	2 flats
K:DLyd	D Lydian	3 sharps

There is also a mechanism for giving arbitrary key signatures, for music that uses non-classical scales. As of this writing (early 1999) only a few programs implement it. It is simple: Give explicit notes with accidentals. They may be combined with a key signature. Some examples:

K:Gm^f	D hijaz	2 flats and 1 sharp
K:_B_e^f	D hijaz	2 flats and 1 sharp
K:GDor^c	D misheberach	Bb plus C#
K:Bb^c	D misheberach	Bb plus C#

It is conventional to use upper-case letters for the key, though there have been enough examples of lower-case keys to encourage the software to ignore the case. The mode names may be upper or lower case, and are usually abbreviated. The "maj" and "major" mode indicators are almost never used, and some software might not recognize it. For explicit key signatures, the case is significant to formatting programs, since this says where to put the accidental on the staff.

In addition, there are two keys specifically for notating highland bagpipe tunes: K:HP doesn't put a key signature on the music, as is common with many tune books of this music, while K:Hp marks the stave with F sharp, C sharp and G natural. Both force all the beams and staffs to go downwards. These correspond to the two conventional ways of notating bagpipe music.

L: note length

M: meter

This is the musical meter, expressed as a fraction. There are also several special meters that may be used:

M:C	Common time, the same as M:4/4.
M:C\|	Cut time, the same as M:2/2.
M:none	Free meter, no time signature and no checking.

Some ABC software has the ability to add up the lengths of measures and warn you if there is an error. This should always be an option, of course, because so many musical styles include occasional measures with extra beats. M:none should turn off any such error checking. Some ABC software assumed M:4/4 as the default, while other programs may assume M:none.

N: notes

The N: header lines are used to include arbitrary notes about a tune. Many ABC programs have options to either display or suppress these notes. Try not to use N: lines for information that is best done with a more specific header line, because very little software will know how to use information in N: lines.

O: origin

The O: line is used rather inconsistently, to indicate either a place or a person that the music came from. For a person, S: is probably better.

P: parts

Q: tempo

The Q: line gives a tempo, in beats per minute, and is mused by programs such as playabc and abc2midi to determine the speed. Formatting programs will put a tempo indication at the upper-left of the staff. There are several recognized formats for a T: line:

Q:1/4=112	Note and count (preferred)
Q:140	Count only, L: used for note length
Q:C2=80	C is the basic note length from the L: line
Q:Andante	Words are only printed, not used

If no Q: line is used, or only a word is given, play programs such as abc2midi and playabc usually assume a tempo of 100 for the L: note length. You can also expect programs that play ABC will have options to override the tempo, so Q: lines are really just suggestions.

R: rhythm

The R: header line gives a name for the tune's rhythm. This is mostly used for lookup purposes. This use is somewhat limited by due to the spelling variants that people use. Only a few ABC programs use this information. For example, abc2midi will interpret R:hornpipe by playing the small notes unequally.

V: voice

S: source

T: title

The T: title line should be the second of a tune's header lines. It may be repeated if there are several titles. ABC formatters will typically show the first such title as the main title, and the others as subtitles in a different font. The T: field can also be used within a tune to name parts of a tune, though you often see P: used for this purpose.

W: words (below the music)

The upper-case W: line is used to supply lyrics that should be separated from the music. Formatting programs like abc2mtex and abc2ps will show these lines below the music. See the Words section for details.

w: words (below the notes)

The lower-case w: line is used to supply lyrics that should be placed below the most recent staff, with the words aligned with notes. See the Words section for details.

X: index number

A tune's index number is used like the track number in a recording, and must be the first line in an ABC tune's header. Some ABC software uses this to select a single tune from a file. It is sometimes omitted in single-tune files, but this is not a good idea, because some programs won't recognize a tune without its X: line.

The value on an X: line should be a (non-negative) integer. Some people have suggested using arbitrary strings as indentifiers, but this will confuse a some software. X:0 seems to work with all ABC software, and it is sometimes used for introductory musical information in a file with multiple tunes - often with no actual music, just headers.

Every tune in a file should have a different X: number, because if two have the same number, you may not be able to use the second. It's probably a good idea to make sure that the numbers are in increasing order. They don't need to be consecutive.

A: transcription notes

The Z: line is used to hold information about who did the ABC transcription, and sometimes includes simply information about the source (though this really belongs in the S: line). Email addresses and URLs are appropriate here, and other contact information such as phone numbers or postal addresses may be included.

ABC Sites

Sites with large ABC music collections

http://trillian.mit.edu/~jc/music/abc/doc/: John Chambers' ABC documents.
http://perun.hscs.wmin.ac.uk/~jra/NMD/: James Allwright's ABC version of the Nottingham Music Database.
http://www.ceolas.org/tunes/: The Ceolas tune archive. This is mostly Irish and other British-Isles music.
http://trillian.mit.edu/~jc/music/abc/: John Chambers' tune collection.
http://home1.swipnet.se/~w-11382/abc/index/: Henrik Norbeck's tune collection.
http://www.musicaviva.com/: Frank Nordberg's Musica Viva site.

Glossary

ABC Music Notation

Contents

Repeat symbols

Repeat lists

Accompaniment or "guitar" chords.

Multiple-note chords.