This is a wikified version of the draft revised abc standard. The original file can be found at http://abcnotation.com/standard/abc_v1.7.6-draft.txt
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.
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).
By far the best way to find out how to use the fields is to look at the example files (in particular English.abc) and try out some examples. Thus rather than describing them in detail, they are summarised in the following table. The second, third and fourth columns specify respectively how the field should be used in the header and whether it may used in tune body or elsewhere in the file. Certain fields do not affect the typeset music but are there for other reasons, and the fifth column reflects this; index fields only affect the index (see index.tex) while archive fields do not affect the output at all, but are just provided to put in information that one might find in, say, a conventional tunebook.
| 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 | ||
| F:file name | yes | F:http://a.b.c/file.abc | |||
| 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:unit 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 | ||
| U:user defined | yes | yes | yes | U: T = !trill! | |
| W:words | yes | lyrics after tune | |||
| w:words | yes | lyrics aligned with tune | |||
| X:reference number | first | X:1, X:2 | |||
| Z:transcription note | yes | Z:from photocopy |
Some additional notes on certain of the fields:
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.
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.
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, __, _, =, ^ or ^^, (see below) followed by a letter in lower case. Global accidentals are overridden by accidentals attached to notes within the body of the abc tune and are reset by each change of signature.
Finally, the key field can also be used to specify a clef, by adding the name of the clef, separated by a space from the key information, e.g K:Am bass. Some programs currently require this to be written as K:Am clef=bass, but either format should be acceptable. Where no clef is specified the default is treble.
i.e. L:1/4 - quarter note, L:1/8 - eighth note, L:1/16 - sixteenth, L:1/32 - thirty-second. If there is no L: field in the header, a unit note length is set by default, based on the meter field M: (see below).
Apart from the normal meters, e.g. M:6/8 or M:4/4, the symbols M:C and M:C| give common time (4/4) and cut time (2/2) respectively. The symbol M:none omits the meter entirely (free meter).
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. Within the header, a part can be repeated by following it with a number e.g. P:A3 is equivalent to P:AAA and a sequence can be repeated by using parentheses e.g. P:(AB)3 is equivalent to P:ABABAB. Nested parentheses are permitted and dots may be placed anywhere within the header P: field, e.g. P:((AB)3.(CD)3)2, to increase legibility and are ignored.
Defines the beat unit (and beats per minute) for setting tempo, e.g. Q:1/2 means that a half note counts as one beat. The number of beats per minute can be specified, e.g. Q:1/2=120 means 120 half-note beats per minute. If no beat unit is given, one is set by default (see below).
To group together tunes for indexing purposes.
Can be used for multi-line stories/anecdotes, all of which will be ignored until the next field occurs.
Supplies a line of lyrics to be aligned syllable by syllable below the previous line of notes. Syllables are not aligned on grace notes and tied notes are treated as two separate notes. Because lyrics tend to take up more space than notes, one w: field and all continuations match one line of notes, whether or not the line of notes ends with a continuation character. If a line of notes is followed by several w: fields, each one supplies alternate words for the notes (this is typically used for writing the verses of a song). Within the lyrics, the following words should be separated by one or more blank spaces and to correctly align them the following symbols may be used:
Some examples:
The following letters are used to represent notes:-
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. Notes can be modified in length (see below). Lower octaves are reached by using 2 commas, 3 commas and so on. Higher octaves are written using 2 apostrophes, 3 apostrophes and so on.
Rests are generated with a z and can be modified in length in exactly the same way as notes can.
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.
The unit note length for the transcription is set in the L: field, e.g. L:1/8 sets an eighth note as the unit note length. A single letter in the range A-G, a-g represents a note of this length. For example, if the unit note length is an eighth note, DEF represents 3 eighth notes.
Notes of differing lengths can be obtained by simply putting a multiplier after the letter. Thus if the unit note length is 1/16, 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. If the unit note length is 1/8,
To get shorter notes, either divide them - e.g. if A is an eighth note, A/2 is a sixteenth note, and A/4 is a thirty-second note - or change the unit 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 and similarly A// = A/4, etc.
If no unit note length is given explicitly in the L: field, a unit note length is set by default, based on the meter. This default is calculated by computing the meter as a decimal: if it is less than 0.75 the default unit note length is a sixteenth note; if it is 0.75 or greater, it is an eighth note. For example, 2/4 = 0.5, so, the default unit note length is a sixteenth note, while for 4/4 = 1.0, or 6/8 = 0.75, or 3/4= 0.75, it is an eighth note. For M:C (4/4), M:C| (2/2) and M:none (free meter), the default unit note length is 1/8.
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):
L:1/16 a3b cd3 a2b2c2d2 L:1/8 a3/2b/2 c/2d3/2 abcd L:1/8 a>b c<d abcd
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 <<<.
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:
If the time signature is compound (6/8, 9/8, 12/8) then n is three, otherwise n is two.
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.
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.
Bar line symbols are generated as follows:
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.
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.
To change key, meter, or unit 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:|
Key changes within the tune may be accompanied by a clef change, and a change of clef without a key change may be specified by means of a K: field without key information, e.g.
K:tenor
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|]
Alternately, any field which can be legally used within the tune can also be specified as an inline field, by placing it within square brackets in a line of music, e.g.
E2E EFE|E2E EFG|[M:9/8] A2G F2E D2|]
The first bracket, field identifier and colon must be written without intervening spaces. Only one field may be placed within a pair of brackets and where appropriate, inline fields (especially clef changes) can be used in the middle of a beam without breaking it.
A meter change within the body of the tune will not change the unit note length (unlike one in the header where no L: field is present).
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.
It should be noted that although the tie "-" and slur "()" produce similar symbols in staff notation they have completely different meanings to player programs and should not be interchanged. Ties connect two successive notes of the same pitch, causing them to be played as a single note, while slurs connect the first and last note of any series of notes, and may be used to indicate phrasing, or that the group should be played legato. Both ties and slurs may be used into, out of and between chords, and in this case the distinction between them is particularly important.
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. Although nominally grace notes have no melodic time value, expressions such as {a2} and {a>b} can be useful and are legal although some packages may ignore them. The unit duration to use for gracenotes is not specified by the abc file, but by the package, and might be a specific amount of time (for playback purposes) or a note length (e.g. 1/32 for Highland pipe music, which would allow {ge4d} to code a piobaireachd 'cadence').
The presence of gracenotes is transparent to the broken rhythm construct. Thus the forms A<{g}A and A{g}<A are legal and equivalent to A/2{g}A3/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.
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.
For fiddlers, the letters u and v can be used to denote up-bow and down-bow, e.g. vAuBvA.
Other common symbols are available such as
However these symbols (.uvTHLMPSO and the roll ~) are just short cuts for commonly used accents and can even be redefined (see Redefinable symbols). More generally accents can be entered using the syntax !symbol!, e.g.
!trill!A4
for a trill symbol (tr). The currently defined symbols (and this list may grow with time) are:
As a short cut to writing accents or other symbols which avoids the !symbol! syntax (see Accent above), the letters H-Z and h-w and the symbol ~ can be assigned with the U: and u: fields (the U: defines how the symbols are printed and the u: defines how they are played). For example, to assign the letter T to represent the trill, you can write:
U: T = !trill!
You can also use "^text" etc (see Annotations below) in definitions, e.g.
U: X = "^+"
to print a plus sign over notes with X before them.
Symbol definitions can be written in the file header, in which case they apply to all the tunes in that file, or in a tune header, when they apply only to that tune, and override any previous definitions. Programs may also make use of a set of global default definitions, which apply everywhere unless overridden by local definitions. You can assign the same symbol to two or more letters e.g.
U: T = !trill! U: U = !trill!
in which case the same visible symbol will be produced by both letters (but they may be played differently), and you can de-assign a symbol by writing:
U: T = !nil!
or
U: T = !none!
The standard set of definitions (if you do not redefine them) is:
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.
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.
Accompaniment chords (e.g. chords/bass notes) can be put in under the melody line (or above, depending on the package) using double-quotation marks placed to the left of the note it is sounded with, e.g. "Am7"A2D2.
The chord has the format <note><accidental><type>/<bass>, where <note> can be A-G, the optional <accidental> can be b, #, the optional <type> is one or more of
and /<bass> is an optional bass note.
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 (but not for playback) by enclosing them in parentheses inside the double-quotation marks after the regular chord, e.g., "G(Em)".
General text annotations can be added above, below or on the staff in a similar way to accompaniment. In this case, the string within double quotes is preceded by one of five symbols ^, _, <, >or @ which controls where the annotation is to be placed; above, below, to the left or right respectively of the following note, rest or bar line. Using the @ symbol leaves the exact placing of the string to the discretion of the interpreting program. Where two or more such annotations are placed consecutively, e.g. for fingerings, the notation program should draw them on separate lines, with the first listed at the top. These symbols also distinguish annotations from guitar chords, and should prevent programs from attempting to play or transpose them.
The order of symbols for one note is <guitar chords>, <accents> (e.g. roll, staccato marker or up/downbow), <accidental>, <note>, <octave>, <note length>, i.e. ~^c'3 or even "Gm7"v.=G,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)
The standard form of the Q: field is, for example, Q:1/2=120 which means 120 half-note beats per minute, however, if a beat unit is given without a speed (e.g. Q:3/8), then the speed is usually intended to be set in a playback program and this field will then be ignored by typesetting programs.
The beat unit can also be given as a multiple of the unit note length using the letter L, e.g. if L:1/8, then Q:L3=120 is equivalent to Q:3/8=120. However, it is usually better to specify an absolute note length. (Note that giving a tempo in relative to the unit note length may result in unexpected behaviour if the unit note length is changed, either explicitly or by default mechanisms.) Older versions of the abc standard used the letter C instead of L, and this is still a permitted form although not recommended.
If no beat unit is set in the Q: field or if the Q: field is missing, a default beat unit is assumed. The default beat unit is the demoninator of the meter, except for compound meters (6/8, 9/8 and higher multiples of 3/8), for which the default beat unit is 3/8. For example, if M:2/4, the default beat unit is 1/4. For M:C| (=M:2/2) it is 1/2; for M:12/8 it is 3/8.
When giving a tempo, it is preferable to specify a beat unit rather than to rely on default mechanisms.
A % symbol will cause the remainder of any input line to be ignored. The file English.abc contains plenty of examples.
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 (using some package specific command) or break the line of abc notation. If, however, you wish to use two lines of input to generate one line of music (see, for example, the 'Untitled Reel' in Reels.abc) then simply put a \ at the end of the first line. This is also useful for changing meter or key in the middle of a line of music.