ABC Music Notation
Syntax and Extensions
by John Chambers



Contents


1 Purpose

This description of abc notation has been created from Chris Walshaw's original ABC 1.6 document, and then modified to describe the various extensions and modifications that various people have implemented to make ABC work with more kinds of music.

2 The abc Notation System

2.0 Tune Layout

Each tune consists of a header and a body. The header, which is composed of information fields, should start with an X (reference number) field followed by a T (title) field and finish with a K (key) field. The body of the tune in abc notation should follow immediately after. Tunes are separated by blank lines. In summary:
    X:5
    T:Joe's Reel
    ... (more header fields)
    K: D
    ... (music)
    (blank line)

Many programs have now been written that allow omitting any or all of the header fields. The X field is often omitted when there is only a single tune present. The title is sometimes omitted for various reasons. This has turned out to be very useful for people working on such things as fragments of music embedded in text. It can be handy to be able to represent just a few notes or bars of music without such things as titles, signatures, and so on. But note that a complete piece of music should have at least the parts shown above.

2.1 Information Fields

2.1.1

The information fields are used to notate things such as composer, meter, etc. in fact anything that isn't music. Most of the information fields are for use within a tune header but in addition some may be used in the tune body, or elsewhere in the tune file. Those which are allowed elsewhere can be used to set up a default for the whole or part of a file. For example, in exactly the same way that tunebooks are organised, a file might start with M:6/8 and R:Jigs, followed by some jigs, followed by M:4/4 and R:Reels, followed by some reels. Tunes within each section then inherit the M: and R: fields automatically, although they can be overridden inside a tune header. Finally note that any line beginning with a letter in the range A-Z and immediately followed by a : is interpreted as a field (so that line like E:|, which could be regarded as an E followed by a right repeat symbol, will cause an error).

2.1.2

Originally, information fields were required to start in column 1 of a new line, with the colon in column 2. Most abc software now accepts "inline" fields that are surrounded by [] brackets. These may occur almost anywhere. There must be no spaces between the [ and the : two columns later. Thus, one might change the key signature in the middle of a line of music by writing [K:Bb]. Exactly how this is displayed is up to the program, but it should at least end with the signature for the new key.

2.1.3


Table of fields
Field name header tune elsewhere Used by Examples and notes
A:area yes       A:Donegal, A:Bampton
B:book yes yes   archive B:O'Neills
C:composer yes       C:Trad.
D:discography yes     archive D:Chieftans IV
E:elemskip yes yes     see Line Breaking
F:file name yes       see index.tex
G:group yes yes     archive G:flute
H:history yes yes     archive H:This tune said to ...
I:information yes yes   playabc  
K:key last yes     K:G, K:Dm, K:AMix
L:default note length yes yes     L:1/4, L:1/8
M:meter yes yes yes   M:3/4, M:4/4
N:notes yes       N:see also O'Neills - 234
O:origin yes yes   index O:I, O:Irish, O:English
P:parts yes yes     P:ABAC, P:A, P:B
Q:tempo yes yes     Q:200, Q:C2=200
R:rhythm yes yes index   R:R, R:reel
S:source yes       S:collected in Brittany
T:title second yes     T:Paddy O'Rafferty
V:voice no? yes     V:3 nm="vla" clef=alto
W:words (lyrics) yes       W:Hey, the dusty miller
w:words aligned with music yes       w:Hey, the dus-ty mil-ler
X:reference number first       X:1, X:2
Z:transcription note yes       Z:from photocopy


2.1.4 Header Fields

Some additional notes on certain of the fields:

2.1.5 Title

T - tune title. Some tunes have more than one title and so this field can be used more than once per tune - the first time will generate the title whilst subsequent usage will generate the alternatives in small print. The T: field can also be used within a tune to name parts of a tune - in this case it should come before any key or meter changes.

2.1.6 Key Signatures

K - key; the key signature should be specified with a capital letter which may be followed by a # or b for sharp or flat respectively. In addition, different scales or modes can be specified and, for example, K:F lydian, K:C, K:C major, K:C ionian, K:G mixolydian, K:D dorian, K:A minor, K:Am, K:A aeolian, K:E phrygian and K:B locrian would all produce a staff with no sharps or flats. The spaces can be left out, capitalisation is ignored for the modes and in fact only the first three letters of each mode are parsed so that, for example, K:F# mixolydian is the same as K:F#Mix or even K:F#MIX. There are two additional 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.

2.1.6.1 Extended Key Signatures

The original ABC 1.6 document included the text:
Finally, global accidentals can also be set in this field so that, for example, K:D =c would write the key signature as two sharps (key of D) but then mark every c as natural (which is conceptually the same as D mixolydian). Note that the there can be several global accidentals, separated by spaces and each specified with an accidental, _, _ _, =, ^

This turns out to have been somewhat of a mistake, and nobody has actually implemented it. But a revision called "Explicit Key Signatures" has been proposed, discussed a lot, and occasionally implemented. It looks similar to the above, but it's a true key signature, suitable for music that uses scales other than the classical scales of western Europe. Here's a description of the proposed key signature standard:

2.1.6.1.1 Extended Key Signatures (proposed)

The K field specifies a key signature, and has the syntax:
K: <tonic><mode><accidentals>
where any or all of the three portions may be omitted. For the <tonic> and <mode> portions, case is not significant. Spaces may be used around the three portions, for readability.

The <tonic> portion is a letter in the range [A-G], optionally followed by a # or b for sharp or flat.

The <mode> portion is any of the following:

 majmajor
m minminor
 aeoAeolian
 dorDorian
 ionIonian
 locLocrian
 lydLydian
 mixMixolydian
 phrPhrygian
A mode may be spelled out, or may be abbreviated to its first three letters. Most programs only check the first three letters.

The letter m alone stands for "minor", and is the only mode that may be abbreviated to one character. Note that M alone means "Minor", not "Major".

The <accidentals> portion may be used to explicitly list accidentals. The notation is simply a list of notes preceded by accidentals. The accidentals are drawn after the clef on the line or space indicated by the note.

The case is significant in <accidentals>. Thus, "K:^G" and "K:^g" put the sharp on different lines (or spaces depending on the clef).

There are several important uses for this:

  1. Some musical styles use scales that don't match the classical European modes. Publishers often force these into a classical mode and use accidentals to get the right notes. But people who play such styles often object to this and want the "right" key signatures for their music. ABC doesn't take sides in this debate; it allows you to do key signatures either way.
  2. Some musical transcription projects have had problems with musical novices who get the tonic and mode wrong, writing K:G for K:Em or K:Adorian for example. And sometimes a piece of music is sufficiently ambiguous as to tonality that you can't really say what is the correct tonic and mode.
  3. You sometimes see naturals in key signatures to emphasize to novice musicians that the scale is not major or minor. Thus, Scottish and Irish music will sometimes use K:Amix=g with an "advisory" natural on the g to make it clear to readers that, although the tonic note is A, the scale is not A major, and the g's are not sharp.

2.1.6.1.1 Key Signature Defaults (proposed)

If none of the <tonic><mode><accidentals> portions is included, there is no key signature. This appears on paper the same as K:C, K:Am, K:Ddor, etc. But the interpretation is different, since K: by itself means "no key specified".

If <mode> and <accidentals> are both omitted, the mode defaults to major.

If the <tonic> is omitted, the <mode> must also be omitted, since a mode without a tonic node isn't very useful.

If both <mode> and <accidentals> are used, then the key signature for the <mode> is drawn first, followed by the <accidentals>.

If K:<tonic><accidentals> is used without a <mode>, only the <accidentals> are drawn. In this case, the <tonic> doesn't actually correspond to anything in printed music. But the <tonic> is still useful, since it can be used in computerized lookups.

2.1.6.1.2 Key signature examples (proposed)
K:
No key signature. C major, A minor, etc.
K:G
G major. One sharp (^f).
K:Gm
G minor. Two flats (_B_e).
K:Bbm
B flat minor. Five flats (_B_e_A_d_G).
K: Amix
A mixolydian. Two sharps (^f^c). Common in traditional Scottish and Irish music.
K: Amix=g
A mixolydian with an advisory natural on the g. For the benefit of musicians who might think the g sharp was accidentally omitted.
K: DPhr
D Phrygian. Two flats (_B_e).
K:Dphr^F
D Hejaz (or freygish for klezmer musicians). The signature is _B_e^F, with the sharp on the lower space.
K: Dmix_B_e
D Hejaz again, but this time with a signature of ^f_B_e.
K: ^c
Unspecified key, with just a c sharp in the signature. Some traditional Scandinavian books use this for D Dorian, and Swedish bagpipes are often tuned to a scale like this.
K: G^f=F
G with the lower F low and the upper f high. This is the scale of some northern European bagpipes. Musicians from the India will also be familiar with scales that have different accidentals in different octaves.

2.1.8

L - default note length; i.e. L:1/4 - quarter note, L:1/8 - eighth note, L:1/16 - sixteenth, L:1/32 - thirty-second. The default note length is also set automatically by the meter field M: (see below).

2.1.9

M - meter; apart from the normal meters, e.g. M:6/8 or M:4/4, the symbols M:C and M:C| give common time and cut time respectively.

2.1.10

P - parts; can be used in the header to state the order in which the tune parts are played, i.e. P:ABABCDCD, and then inside the tune to mark each part, i.e. P:A or P:B.

2.1.11

Q - tempo; can be used to specify the notes per minute, e.g. if the default note length is an eighth note then Q:120 or Q:C=120 is 120 eighth notes per minute. Similarly Q:C3=40 would be 40 dotted quarter notes per minute. An absolute tempo may also be set, e.g. Q:1/8=120 is also 120 eighth notes per minute, irrespective of the default note length.

2.1.12

G - group; to group together tunes for indexing purposes.

2.1.13

H - history; can be used for multi-line stories/anecdotes, all of which will be ignored until the next field occurs.


3 abc tune notation

3.0 Notes

The following letters are used to represent notes on the treble staff:
                                                      d'
                                                -c'- ----
                                             b
                                        -a- --- ---- ----
                                       g
 ------------------------------------f-------------------
                                   e
 --------------------------------d-----------------------
                               c
 ----------------------------B---------------------------
                           A
 ------------------------G-------------------------------
                       F
 --------------------E-----------------------------------
                   D
 ---- ---- ---- -C-
            B,
 ---- -A,-
  G,
and by extension, the notes C, D, E, F, a' and b' are available.

The comma and apostrophe may be used more than once, to get more octaves. A comma means "one octave lower"; an apostrophe means "one octave higher". In fact, c, is the same as C and C' is the same as c.

3.1 Rests

Rests are generated with a z and can be modified in length in exactly the same way as notes can.

Extension: Some programs now accept x to represent a rest that is not drawn on the staff. This may be used in multi-voice music to make the page less cluttered.

A few programs also use y to represent a "rest" that is neither displayed nor played. This is essentially a spacer to force a bit more separation between notes on the page.

3.2 Note lengths

NB: Throughout this document note lengths are referred as sixteenth, eighth, etc. The commonly used equivalents are sixteenth note = semi-quaver, eighth = quaver, quarter = crotchet and half = minim.

3.2.0.1

A letter [A-Ga-g] by itself represents a note of some duration. You can represent notes of other durations by following the note with a multiplier. The multiplier may a (positive) integer or a fraction. Thus A3 is an A three times as long as just A, and F3/2 is an F 50% longer than F.

A numerator of 1 and a denominator of 2 may be omitted, so G1/2, G/2 and G/ all mean the same thing, a G half as long as G.

3.2.0.2

Each meter automatically sets a default note length and a single letter in the range [A-Ga-g] will generate a note of this length. For example, in 3/4 time the default note length is an eighth note and so the input DEF represents 3 eighth notes.

The default note length can be calculated by computing the meter as a decimal; if it is less than 0.75 the default is a sixteenth note, otherwise it is an eighth note. For example, 2/4 = 0.5, so the default note length is a sixteenth note, while 4/4 = 1.0 or 6/8 = 0.75, so the default is an eighth note. Common time and cut time (M:C and M:C|) have an eighth note as default.

3.2.0.3

Notes of differing lengths can be obtained by simply putting a multiplier after the letter. Thus in 2/4, A or A1 is a sixteenth note, A2 an eighth note, A3 a dotted eighth note, A4 a quarter note, A6 a dotted quarter note, A7 a double dotted quarter note, A8 a half note, A12 a dotted half note, A14 a double dotted half note, A15 a triple dotted half note and so on, whilst in 3/4, A is an eighth note, A2 a quarter note, A3 a dotted quarter note, A4 a half note, ...

3.2.0.4

To get shorter notes, either divide them - e.g. in 3/4, A/2 is a sixteenth note, A/4 is a thirty-second note - or change the default note length with the L: field. Alternatively, if the music has a broken rhythm, e.g. dotted eighth note/sixteenth note pairs, use broken rhythm markers (see below). Note that A/ is shorthand for A/2.

3.3 Broken rhythms

3.3.0.1

A common occurrence in traditional music is the use of a dotted or broken rhythm. For example, hornpipes, strathspeys and certain morris jigs all have dotted eighth notes followed by sixteenth notes as well as vice-versa in the case of strathspeys. To support this abc notation uses a > to mean `the previous note is dotted, the next note halved' and < to mean `the previous note is halved, the next dotted'. Thus the following lines all mean the same thing (the third version is recommended):

3.3.0.2

  L:1/16
  a3b cd3 a2b2c2d2

  L:1/8
  a3/2b/2 c/2d3/2 abcd

  L:1/8
  a>b c<d abcd

3.3.0.3

As a logical extension, >> means that the first note is double dotted and the second quartered and >>> means that the first note is triple dotted and the length of the second divided by eight. Similarly for << and <<<.

3.3.0.4

This broken-rhythm notation is only valid if the two notes are of equal length. If they aren't, the results are not well defined.

3.4 Duplets, triplets, quadruplets, etc.

3.4.0.1

These can be simply coded with the notation (2ab for a duplet, (3abc for a triplet or (4abcd for a quadruplet, etc., up to (9. The musical meanings are:

3.4.0.2

 (2 2 notes in the time of 3
 (3 3 notes in the time of 2
 (4 4 notes in the time of 3
 (5 5 notes in the time of n
 (6 6 notes in the time of 2
 (7 7 notes in the time of n
 (8 8 notes in the time of 3
 (9 9 notes in the time of n

3.4.0.3

If the time signature is compound (3/8, 6/8, 9/8, 3/4, etc.) then n is three, otherwise n is two.

3.4.0.4

More general tuplets can be specified using the syntax (p:q:r which means `put p notes into the time of q for the next r notes'. If q is not given, it defaults as above. If r is not given, it defaults to p. For example, (3:2:2 is equivalent to (3::2 and (3:2:3 is equivalent to (3:2 , (3 or even (3:: . This can be useful to include notes of different lengths within a tuplet, for example (3:2:2G4c2 or (3:2:4G2A2Bc and also describes more precisely how the simple syntax works in cases like (3D2E2F2 or even (3D3EF2. The number written over the tuplet is p.

3.5 Beams

3.5.0.1

To group notes together under one beam they should be grouped together without spaces. Thus in 2/4, A2BC will produce an eighth note followed by two sixteenth notes under one beam whilst A2 B C will produce the same notes separated. The beam slopes and the choice of upper or lower staffs are generated automatically.

3.6 Repeat/bar symbols

3.6.0.1

Bar line symbols are generated as follows:

3.6.0.2

 | bar line
 |] thin-thick double bar line
 || thin-thin double bar line
 [| thick-thin double bar line
 :| left repeat
 |: right repeat
 :: left-right repeat

3.7 First and second repeats

3.7.0.1

First and second repeats can be generated with the symbols [1 and [2, e.g. faf gfe|[1 dfe dBA:|[2 d2e dcB|]. When adjacent to bar lines, these can be shortened to |1 and :|2, but with regard to spaces | [1 is legal, | 1 is not.

3.8 Accidentals

3.8.0.1

The symbols ^, = and _ are used (before a note) to generate respectively a sharp, natural or flat. Double sharps and flats are available with ^^ and __ respectively.

3.9 Changing key, meter, and default note length mid-tune

3.9.0.1

To change key, meter, or default note length, simply put in a new line with a K: M: or L: field, e.g.
  ed|cecA B2ed|cAcA E2ed|cecA B2ed|c2A2 A2:|
  K:G
  AB|cdec BcdB|ABAF GFE2|cdec BcdB|c2A2 A2:|

3.9.0.2

To do this without generating a new line of music, put a \ at the end of the first line, i.e.

  E2E EFE|E2E EFG|\
  M:9/8
  A2G F2E D2|]

3.10 Ties and slurs

3.10.0.1

You can tie two notes together either across or within a bar with a - symbol, e.g. abc-|cba or abc-cba. More general slurs can be put in with () symbols. Thus (DEFG) puts a slur over the four notes. Spaces within a slur are OK, e.g. (D E F G), but the open bracket should come immediately before a note (and its accents/accidentals, etc.) and the close bracket should come immediately after a note (and its octave marker or length). Thus (=b c'2) is OK but ( =b c'2 ) is not.

3.11 Gracings

3.11.0.1

Grace notes can be written by enclosing them in curly braces, . For example, a taorluath on the Highland pipes would be written GdGe. The tune `Athol Brose' (in the file Strspys.abc) has an example of complex Highland pipe gracing in all its glory. Grace notes have no time value and so expressions such as a2 or ${a>b}$ are not legal.

3.11.0.2

Alternatively, the tilde symbol   represents the general gracing of a note which, in the context of traditional music, can mean different things for different instruments, for example a roll, cran or staccato triplet

3.12 Accents

3.12.0.1

Staccato marks (a small dot above or below the note head) can be generated by a dot before the note, i.e. a staccato triplet is written as (3.a.b.c

3.12.0.2

For fiddlers, the letters u and v can be used to denote up-bow and down-bow, e.g. vAuBvA

3.13 Chords and unisons

3.13.0.1

Chords (i.e. more than one note head on a single stem) can be coded with [] symbols around the notes, e.g. [CEGc] produces the chord of C major. They can be grouped in beams, e.g. [d2f2][ce][df] but there should be no spaces within a chord. See the tune `Kitchen Girl' in the file Reels.abc for a simple example.

3.13.0.2

If the chord contains two notes both of the same length and pitch, such as [DD], then it is a unison (e.g. a note played on two strings of a violin simultaneously) and is shown as note-head with both upward and downward stems.

3.14 Guitar chords

3.14.0.1

Guitar chords can be put in under the melody line by enclosing the chord in inverted commas, e.g. "Am7"A2D2 . See the tune `William and Nancy' in English.abc for an example.

3.15 Order of symbols

3.15.0.1

The order of symbols for one note is $<$guitar chords

\begin{displaymath}>\end{displaymath}

, $<$accents

\begin{displaymath}>\end{displaymath}

(e.g. roll, staccato marker or up/downbow), $<$accidental$>$, $<$note$>$, $<$octave$>$, $<$note length$>$, i.e.  ^ c'3 or even "Gm7"v.=G,2

3.15.0.2

Tie symbols, -, should come immediately after a note group but may be followed by a space, i.e. =G,2- . Open and close chord symbols, [], should enclose entire note sequences (except for guitar chords), i.e. "C"[CEGc] or "Gm7"[.=G,^c'] and open and close slur symbols, (), should do likewise, i.e. "Gm7"(v.=G,2~^ c'2)

3.16 Comments

3.16.0.1

A % symbol will cause the remainder of any input line to be ignored. The file English.abc contains plenty of examples.

3.17 New notation

3.17.0.1

The letters H-Z can be used to define your own new notation within a tune. Currently the way they are implemented (if at all) is extremely package dependent and so users are advised not to rely too heavily on them to include new features. Instead, if there is a feature or symbol that you need and which is not available it is better to press for it to be included as a part of the language.

3.18 Line breaking and justification

3.18.0.1

Generally one line of abc notation will produce one line of music, although if the music is too long it will overflow onto the next line. This can look very effective, but it can also completely ruin ties across bar lines, for example. You can counteract this by changing either the note spacing with the E: field (although currently this is package dependent) or break the line of abc notation. If, however, you wish to use two lines of input to generate one line of music then simply put a backslash (\) at the end of the first line. This is also useful for changing meter or key in the middle of a line of music.

3.18.0.2

With most packages lines of music are right-justified. However, where this is not the case (e.g. when using MusicTeX), a * at the end of each line of abc notation will force a right-justified line-break.


About this document ...

The ABC Standard

This document started off as Chris Walshaw's plain-text intro to ABC, and was converted to HTML by Laura Conrad. It was edited to include ideas and extensions by John Chambers at MIT.