ABC Music Notation: Headers

by John Chambers
(Back to main text)

(Back to main text)
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:Chieftains 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.

E: elemskip

F: file name
Mostly used to give a URL for an file that contains the tune. This can be a recording, an image of printed music, an ABC file, etc.

G: group

H: history
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:DD major2 sharps
K:DmajD major2 sharps
K:DmajorD major2 sharps
K:DmD minor1 flat
K:DminD minor1 flat
K:DminorD minor1 flat
K:CC majorNo sharps or flats
K:AmA minorNo sharps or flats
K:DDorD DorianNo sharps or flats
K:DDorianD DorianNo sharps or flats
K:ELydE LydianNo sharps or flats
K:DMixD Mixolydian1 sharp
K:DPhrD Phrygian2 flats
K:DLydD Lydian3 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. Here are some examples. The first is often seen in Scottish bagpipe music, with an explicit G natural to make it clear that this isn't A major. The rest should be familiar to any Balkan, Klezmer, or Middle-Eastern musician.
K:Amix=gA mixolydiantwo sharps + advisory G natural
K:Dphr^FD hijaz/freygish2 flats and 1 sharp
K:Cdor^FC misheberach2 flats and 1 sharp
K:_B_e^Fsame, no tonic2 flats and 1 sharp
K:D_e_B^f^cD zengule2 flats and 2 sharps
K:GDor^cG misheberachBb 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
This is used by programs that convert ABC to standard music notation. It is the note length for an ABC note [A-Ga-g] not followed by a length. If omitted, the default is determined by the numeric value of the M: field. If the M: value is 3/4 or greater, the default is L:1/8. If the M: value is less than 3/4, the default is L:1/16. If you change the M: value, you should probably also specify the L: value, since some programs will change to the default if you don't.

M: meter
This is the musical meter, expressed as a fraction. There are also several special meters that may be used:
M:CCommon time, the same as M:4/4.
M:C|Cut time, the same as M:2/2.
M:noneFree 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 assumes 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
This means something different in the header and music portions. In the header, P: is used to give the order of the labelled parts of the music. In the music, P: is used to attach a label (name) to the music that follows. For example, consider the tune:
		X: 1
		T: Constant Billy
		O: England
		A: Bucknell
		P: A(A2B)3.A2
		M: 6/8
		L: 1/8
		K: G
		P: A
		|:G2d BGB | c2A AFD | BAG E2E | AGF G3 :|
		P: B
		| Gee e>de | ABc dBG | ABc dBG | ABc d3 \
		| G2d BGB | c2A AFD "S"|BAG E2E | DEF G3 ||
		P: S Last time - Caper out
		| ((2BA) G3 | ((2E>F) G3 | ((2D>E) F3 | G6 |]
	
In this tune, there are are two parts, plus a sort of coda. The first P: line says to play the parts in the order AAABAABAABAA, and then the last part will be played (until the dancers have gotten out of the dance area).

Note that the P: lines in the music may be single letters, in which case a lot of software that plays ABC will follow the order given by the P: line in the header. Or the P: lines may contain longer descriptions. Classical works may use lines like P:Adagio or P:Trio to label the sections. Probably not much software will be able to use this for playback.

In general, the contents of P: lines in the header are not very well defined, and they are really only useful for giving instructions to humans that understand the musical style. This may be improved in the future (or it may get more complex as ABC is used for more musical styles).

Q: tempo
The Q: line gives a "metronome" 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 Q: line:
Q:1/4=112Note and count (preferred)
Q:140Count only, L: used for note length
Q:C2=80C is the basic note length from the L: line
Q:AndanteWords are only printed, not used by software
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.

The Q: header is often used to place arbitrary text above the left end of the first staff. This isn't a good idea, since various ABC software will attempt to interpret the text as tempo instructions, with confusing results.

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
ABC has a way of representing multi-voice music, described in more detail in another page.

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.


(Back to main text)

Copyright 2001, 2002 by John Chambers