An ABC primer
by John Chambers

This is a brief intro to the ABC music notation system. This notation was originally invented by Chris Walshaw, who produced the first abc2mtex program that converts ABC notation to mtex (Musix Tex). Other people have since produced a variety of other software for ABC, most of which is free.

The main advantages of ABC are:

  • It's simple ASCII, easy to type and read, and easy to email.
  • There's a lot of good software that understands it.
  • ABC files are small, so downloading is fast.

    The main disadvantages of ABC are:

  • It's not a full music notation yet. It's best for single-line instruments.
  • The software isn't from a single source, and there are inconsistencies.

    OK, enough of that. On to the notation...


    Headers

    Each tune starts with some header lines. A header lines starts with a letter and a colon (:), plus some info. There are lots of different header lines. The most useful are:

    
       X: 1
       T: Tune Title
       C: Composer
       N: Notes about the tune
       M: 3/4
       L: 1/8
       K: G
    

    The X: line gives a sequence number, useful for selecting one tune out of a file full of tunes.

    The T: line gives the title, and may be repeated if you want to give several titles.

    The C: line gives the composer's name. Use C:Trad for traditional tunes.

    The N: line is any kind of comment, ignored by the software.

    The M: line is the meter. M:2/4 is two/four time; M:6/8 is jig time, etc. M:C and M:C| have the obvious meanings.

    The L: line is the default note length; here it's an eighth note (quaver).

    The K: gives the key. K:Em would mean E minor. Most ABC software also recognizes the classical "modal" keys, using 3 (or more) letters of the mode, so K:EDor means E Dorian (two sharps) and K:AMix means A Mixolydian (two sharps).

    The X: and T: lines should be the first two lines, and the K: line should be the last header line. Some software is liberal about these, but some is fairly picky, so its best to always use these three main header lines in this order. The K: line is followed by music, with a blank line to separate the tune from whatever follows.


    Notes

    The bottom half of the staff, from C below the staff to B in the middle, are represented by the capital letters CDEFGAB. The top half of the staff, from the C in the middle to the B above, are represented by lower-case letters cdefgab. So the notes on the treble staff are EFGABcdef. The lines are EGBdf, and the spaces are FAce.

    You can represent the octaves below and above these by putting a comma (,) after the capital letters, or an apostrophe (') after the lower-case letters. This is sort of a pictorial mark: The "lower comma" means go down an octave, while the "upper comma" means to go up an octave.

    Here's a summary of notes:

                                                                ...
                                                             d'
                                                       -c'- ----
                                                    b
                                               -a- --- ---- ----
                                              g
        ------------------------------------f-------------------
                                          e
        --------------------------------d-----------------------
                                      c
        ----------------------------B---------------------------
                                  A
        ------------------------G-------------------------------
                              F
        --------------------E-----------------------------------
                          D
        ---- ---- ---- -C-
                   B,
        ---- -A,-
         G,
     ...
    

    Bar lines

    Here's how you do bar lines:
    |simple bar line
    ||double bar line
    [|thick+thin double bar line
    |]thin+thick double bar line
    |:start of repeat
    :|end of repeat
    |1start of first ending
    :|2start of second ending
    There's also a :: symbol that's merely shorthand for :||:, the end of one repeated section and the start of another.

    It's a good idea to include spaces around bar lines, for human readability, but ABC syntax doesn't require this.


    Timing

    A note by itself stands for whatever length note is in the L: header line. You can add a multiplier after the note. A simple fraction is the basic notation. So A3/2 means a note 1.5 times as long as the basic length (a dotted eighth note in the above example).

    You can omit /1, of course, so d4 means a note four times as long as the basic length (a half note here).

    You can also omit a numerator of 1 or a denominator of 2. So F1/2, F/2 and F/ all mean the same thing, an F note half as long as the L: length in the header.

    Since all notes are in terms of the L: length, you can quickly change the meter of a tune by merely modifying the M: and L: lines in the header.

    There is a shorthand notation for dotting: The characters < and > transfer half the value of the note on one side to the other side. The < is a "snap", with a short first note, so A<B is shorthand for A1/2B3/2. The > is a long-short, so A>B is shorthand for A3/2B1/2. You can double these symbols to get a double dot.


    Beaming

    Within a measure, spaces are used to separate groups of notes that are to be beamed together (if possible). So |DFA dAF| is a bar with two groups of three notes (probably a jig), while |DF Ad AF| is a bar with three groups of two notes (possibly a waltz).


    Staffs

    Normally, ABC uses one staff per line, and end-of-line represents the end of a staff. This can lead to very long lines, so the backslash (\) is used to mean "continued on next line". This is similar to its use in a lot of programming languages, and lets you break up a long line into several short lines. The main use for this is in sending tunes via email. A lot of email software inserts line feeds in long lines, and this has an unfortunate effect on ABC. This can be prevented by using \ to split a long staff line into two or more shorter lines.


    "Accompaniment" chords

    This refers to the names of chords, to be placed above or below the staff (there's no standard here). They go in double quotes, just before the note. So "G"dBAG would be a G chord above/below the d note. You can actually put any text inside the double quotes, so long chord names are possible. People also use this for other musical directions, but that isn't really correct.


    Example

    One new thing first: I've used the letter 'z' in this example, which represents a rest. Rests take lengths just like notes, so the two uses of z2 represent 1/4-length rests.

    You have enough knowledge now to understand the following tune:

    X: 1
    T: Balance the Straw
    R: jig
    N: This tune goes with one of the best-known Morris dances. It is also a good jig
    N: for other dances, usually in AABB form. The B phrase bears a strong resemblance
    N: to a certain Christmas carol, and at Morris dances you will hear words like:
    N: __ Hark! the herald angels sing, __
    N: __ Glory to the Morris Ring. __
    N: Sometimes assorted other things are praised by the angels.
    N:
    M: 6/8
    L: 1/8
    K: G
    D \
    |: "G"G2B B>AB | "C"c2A A>ce | "D7"d>ed cAc | "G"G2B B2D \
    |  "G"G2B B>AB | "C"c2A A>ce | "D7"d>ed cEF | "G"G4 z2 :|
    B/c/ \
    |: "G"dz d dz G | "(D7)"c2B "D7"B2A |  "G"dz d dz G | "D7"B2A A2D \
    |  "G"G2B B>AB | "C"c2A A>ce | "D7"d>ed cEF | "G"G4 z2 :|
    

    Here's what this looks like as standard music notation:

    Balance the Straw

    This was produced using the a abc2ps program, plus some tools to convert the result to the PNG graphics format. Something else you might notice is that the ABC version contains some N: lines, which are "notes" about the tune. The graphics file doesn't show these notes. The abc2ps program, like many ABC tools, has options that control whether such information is produced. This means that you can include as much documentation about a tune as you like, and people can print just the tune or print it with full documentation. So don't be afraid to use N: lines liberally.
    Repeats and endings

    Well, I lied a bit just there; I used something new without warning you.. Did you notice the |: and :| symbols in that tune? You probably understood them. They mean exactly what you think they mean: Repeat the phrase. There's also a shorthand :: notation for a bar in the middle of a line with repeat symbols on both sides.

    There is a simple multi-ending notation:

    |: ... |1 ... :|2 ... |]
    This represents a phrase with two different endings. You can use :| at the end to indicate four times through. But this notation is still not well developed in ABC. You'd think that you could also say something like
    |::: ... |1,3 ... :|2 ... |4 ... |]
    But this isn't recognized by all ABC software yet, and isn't part of the official standard. It may be eventually. Some ABC software also lets you use the obvious multi-colon notation for repeats:
    |:: ... ::|
    This would mean two repeats; i.e., play the phrase three times. Again, this isn't yet understood by all ABC software.
    Accidentals
    The ASCII character set has the # symbol, but lacks the natural and flat symbols. So some other, somewhat pictorial, characters were chosen. The notation for accidentals is:
    _Bmeans B flat
    =Ameans A natural
    ^Gmeans G sharp
    The usual rule should be followed: An accidental applies to that note for the rest of the measure, unless changed by another accidental. However, it is common to use occasional unnecessary accidentals for emphasis. And if you're hanging out with the Early Music crowd, or with modern atonal musicians, you should probably treat accidentals as only for that one note.

    In accompaniment ("guitar") chords, the characters # and b are used for sharps and flats, so "Bb" means a B-flat chord, and "F#m7" means an F-sharp minor 7th chord. The same thing is done in key signatures, so K:Bb means the key of B flat, and K:F#m means F sharp minor. This is inconsistent with accidentals on notes, but printed music is often inconsistent in similar ways.


    Chords

    You can produces chords, that is, multiple notes on a single stem, by putting them within square brackets [...]. So [GBdg] is a 4-note G chord. The order doesn't much matter, so [gdBG] comes out the same on paper. But there is some music-playing software that will treat the first note as the "melody" note, so if this is important, you should put the main note first.

    ABC notation allows each note in the chord to have its own length. You can say things like [D4F3A2d3/2]. Music-playing software can honor such things with ease. But standard music notation can't represent all of this, and on paper you'll get something much simpler. Much music-printing software will just use the length of the first note for the entire chord, and the above example and [D4FAd] will both come out the same as [D4F4A4d4].


    Slurs and ties
    Parentheses are used for slurs. AB(cd) means to draw a slur from the c to the d. Slurs can be drawn between arbitrary notes (though there may be problems with slurs that go from one staff to another).

    A tie is indicated by a hyphen (-) after the first note. So A4- A is two A's tied together.

    Most music notation doesn't really distinguish slurs and ties, and ABC is no exception. You'll see A-B, which should really be (AB). This probably isn't a big deal, except to the rare people who get excited about such things. Also, some ABC software will complain if you tie two different notes together. But the software should usually do the right thing, and treat it to a slur.


    Ornaments

    ABC has a several notations for ornaments. If you put notes in curly braces {} they will be treated as grace notes. When printed, they will be tiny notes just before the note that follows. You can use this to write out rather complex ornaments. {gded^c}d will give a d with all five little notes before it.

    There are also some special symbols that can be put before a note. A dot produces the usual staccato: .d means a d with a dot below or above it. You can use ~ to indicate a turn, so ~D means a turned D. Some software has options to say how to draw such ornaments. There are also some ornaments that some programs recognize and others don't. Thus T is recognized by some to produce the usual italic tr symbol above the next note. M (for "emphasis") is recognized by some to produce a little horizontal line above or below the note. Most software recognizes H as a "hold" (fermata). And so on.

    This is an area for future development.


    Clefs

    The treble clef is the default. But you can specify the clef in the K: header line.

    K:Gm bass
    means the key is G minor, and the clef is bass. Unless you say otherwise, K:C treble is assumed. (Some software will give a warning if there is no K: line, and will then use this default.)

    One quandary with ABC was how letters map to staff notes in alto and bass clefs. The abc2ps program originally used a mapping like the treble clef: a was the top line, d was the middle line, and G the bottom line.. But then some other people wrote software that did it differently, with A, the top bass line and G,, the bottom line. After extensive discussion, it was decided that there was no "best" way to do this, so another idea was accepted: You can state what note goes on the middle line. So you might write:

    K:Gm bass middle=d
    This puts the letters GABcdefga on the staff, and makes for easy typing. If you prefer the other scheme, you can say:
    K:Gm bass middle=D,
    It's a good idea to always include the middle= item for bass clef, so that the software knows where you want the notes on the staff. If you don't, some software will draw the notes in different octaves than you intended.

    You could also use middle= to change the mapping for the treble clef. This could be useful, for exmple, to convert an alto vocal line to an instrumental line with the notes drawn an octave higher. Another example is with alto recorder music, which historically has been printed in two different octaves. In ABC terms, printers treat the instrument's range as F,, ... g or F, ... g'. Such music, when transcribed to ABC, can easily be printed in staff notation in either octave by merely adding a middle=B or middle=b term to the K: header line.


    More header lines

    C: Composer (who wrote the tune)
    O: Origin (where it's from)
    S: Source (who you got it from)
    R: Rhythm (reel, jig, polka, tango, ...)
    B: Books where you can find the tune
    D: Discography (recordings of the tune)
    H: History (anything you know about the tune's origins)
    Q: Tempo (1/4=120 means 120 quarter notes per minute)
    Z: Transcription notes (who wrote it down or converted it to ABC, and when)


    For more details, here are a couple of documents about ABC notation:
    abc.txt
    Chris Walshaw's introduction to abc notation.
    abc-15.txt
    Chris Walshaw's detailed document for ABC notation.
    ReadMe.abc2ps
    Description of abc2ps (version 1.2)
    abc2mtex_1.5.html
    Chris Walshaw's description of abc2mtex.
    abcguide.txt
    James Allwright description of his programs that translate between ABC and MIDI.
    See also the ABC home page for a lot more information and pointers to software.
    Web warning

    It turns out to be a bad idea to include ABC notation inside HTML web pages. I've done it here, true, but it's really tricky. I don't recommend it. The problem is that ABC uses < and >. Inside .html files, most software will interpret these as HTML tags. The result is often disastrous. It's best to put your tunes in files with .abc on the end of their names, and put links to them into your HTML file.

    If you must include ABC inside HTML, probably the best way is with a <PRE> tag. You still need to encode < as &lt; and > as &gt;. But this will preserve your whitespace and line ends, so it doesn't all get run together as one long line.

    The HTML5 encoding is now accepted by most browsers, and if you use it, you can surround ABC with the new <CODE> tag. But it still has problems due to incomplete or inconsistent implementation in some browsers.

    Also, there is an official MIME type for ABC. Your webmaster should tell the server that .abc files are to be sent as "Content-Type: text/vnd.abc". Then browser helpers and extensions will be able to recognize your ABC files as music and treat them appropriately. Some web servers, including the common apache server, come configured to understand ABC, but older web servers might not.

    If your webmaster won't accept the idea of sending the official MIME type for .abc files, suggest that "text/plain" be used. This will allow browsers and other software to display the ABC correctly, though it will defeat browser setups for handling ABC music automatically.


    Visit the ABC home page for a lot more information.