New Hampshire Country Dance Fiddle Tunes Website

About the abc Document


The abc Document I: Tune Header

This is the more technical portion of the section on abc notation. Here we look at abc notation and the abc document in more detail. This subsection covers the parts of the abc document, some of the basics of abc notation and introduces some of the methods for gaining further control over the formatting of an abc document. We start with the tune body.

I divided the abc section into two parts: an introductory series for people interested in making use of abc tunes and a more detailed and somewhat more technical series aimed more at people who might want to write out tunes in abc. Please use the abc Notation menu above to navigate the abc pages.

The Tune Header

The part of the abc code of greatest interest to most musicians is, of course, the part that produces the musical notation: the tune body. But knowing the notes of a tune doesn't help us or the software a whole lot unless we know what kind of tune it is, what key it's in and other useful information. This information is presented in the tune header as a series of information fields, each of which conveys specific information about the tune.

Suppose we want to write out the tune On the Road to Boston. A very basic tune header might look like this:

X:1                     % the tune number 
T:On the Road to Boston % title
T:Road to Boston        % a second title
M:2/4                   % meter
L:1/8                   % default note length
R:March                 % rhythm
K:D                     % key

Although basic this is enough description that any subsequent music would be interpretable to both the abc software and human readers. Here are a few notes to expand on the descriptions given above.

  • In abc notation a percent sign indicates a comment: everything after that is for the benefit of the humans, and is ignored by the computer.
  • The tune number is used to identify each tune, and can be used to order tunes in a document containing multiple abc tunes.
  • Each note is represented by a letter. The default note length gives the length a note will have if it has no number next to it to modify the length.
    • It's best to choose the shortest note that occurs more than occasionally as the default length.
  • The rhythm can be used to give the abc interpreter software (and the musicians) some hints about how the tune should be played.
  • The key may be specified in terms of the mode as well. For example, Amin for minor, Ddor for Dorian.
  • The abc standard requires that all tunes begin with the X: field, followed by the T: field. The K: field must be the last field of the tune header.

We may want to convey other information about the tune, so there are a number of other information fields that may be used. Here is a partial but more detailed header from the tune as presented on this website. It illustrates some of the ways in which a header might be made more informative. Note that some people write out notation for playing and don't care about documentation; others place more emphasis on documenting the tunes they write out.

Field explanations are at the end, including a few fields not needed for this tune.

T:On the Road to Boston
T:Road to Boston
S:$2Farm & Wilderness String Band Tunebook.$0 Compiled by Christy 
S:Keevil and Henry Darley Chapin. Plymouth, Vt., Farm & Wilderness, 1980.
H:A couple chords have been modified. The alternative chords are listed as
H:"special chords for the last time through", but these days they're played
H:at other times as well.
N:From the Lamprey River Band Tunebook, on NH Country Dance (URL below), 
N:along with many New England, Canadian & Swedish tunes, and 
N:resources for abc notation and New England traditional music and dance.
Z:abc-transcription Peter Yarensky. 
Z:abc-copyright Peter Yarensky. You may reproduce this tune freely but
Z:please include the entire abc file including all the notes.
F:Tunes Home Page -
G:Marches ~ LRB
N: Tune Tags ~ March, New England Repertoire, LRB

Notes on the Information Fields

X is a large number because I use it to classify tunes.
T can be used more than once to give an alternate title.
C is where the composer is listed, not relevant in this case.
S is for giving a source for the tune. See below concerning $2 and $0.
H is the history field, and can be used for historical background and stories about a tune.
N is for notes about the tune.
Z is used to give information about the transcription, copyright and other such information.
F is for the file's URL.
G is a grouping field. There are many ways of organizing a set of tunes.

One thing currently lacking in abc is a good way to organize and tag tunes. I use the X field to encode how a tune is categorized as well as its alphabetical order. I use the N: Tune Tags line to allow searching based on a variety of information in the Tune Index. These are both unofficial uses of those fields.

In the Source field the $2 and $0 start and end a predefined font change, in this case the use of italics. It's possible to define up to four font changes that can be used in the middle of a line of text. This is discussed further in the discussion of file headers.

Coming Next. On the next page we look at The Tune Body , where the actual melody is written out.