Frequently Asked Questions about ABC Music Notation
Last updated 10 Oct 2001

This FAQ was collected by John Chambers from questions that have been asked on the mailing list. Nothing here is at all authoritative; it's my current best guess at an answer based on the mailing-list discussions. If you have a correction or addition, please send me email, and maybe we can make it authoritative.
What's this abc notation all about?

There have been many music software packages marketed in recent years. Some of them can do marvelous things. But all have had some major problems: They are proprietary products that typically run on only on one machine. You can't email the files to friends unless they have the same kind of computer with the same software. If there's something wrong, you just have to wait for them to fix it.

The abc software, in contrast, uses ASCII source files that can be emailed with no known problems. The files are small, making for fast network access. The software runs on every common computer, and is mostly free, or nearly so. If you have ideas for improvements, and you have a C compiler, you can get the source and make improvements (and then share them with the rest of us).


Where can I get abc software?

The abc home page is at http://abcnotation.com/. You'll find pointers to the source, as well as binaries for your Mac or W95 machine. You'll also find pointers to a growing list of abc musical archives.


How about a mailing list?

Yep, there's a mailing list for abc users: https://groups.yahoo.com/neo/groups/abcusers/info.


What is the correct order for header lines?

The only fixed rule is the following order:

  • X:
  • T:
  • ... other header lines
  • K:
  • ... music ...
  • blank line
    Other header lines may be in any order between the T: and K: lines. Some software will accept either X: or T: as the start of a tune, and not require both. But it's a good idea to include both, so that your abc will work everywhere.

    The P: lines are a semi-exception: You often see P: after the K: line. Such a P: line is technically outside the header, in the body of the music. The conventional use of P: inside the headers is to state the order of parts, as in P:AABBACCA. You would then use P:A before the first line of music (after K:) to label the A part. A later P:B would label the B part, and so on.


    What "header" lines may also occur inside the tune?

    The E: K: L: M: P: Q: T: V: W: w: lines may also occur within the tune, as well as in the header. Some recent software encourages using [...] around such commands, and they can then be placed anywhere within the tune, not just at the start of a new line. Thus [K:Gm] may be used to change the key signature to G minor in the middle of a line. Some abc software might not recognize this syntax yet.


    How is the default note length determined?

    By the L: header line. L:1/8 means that a note without a length is an eighth note (semiquaver).

    If you want to omit the L: line, the rules are: The time signature is converted to its decimal value. If the value is 0.75 or higher, the default is L:1/8. If the value is less than 0.75, the default is L:1/16.

    You might consider not asking this question at all, and including a L: line in every tune. That way, there will be no surprises.


    Is "free rhythm" without a time signature possible?

    Yes, though some programs may not handle it correctly. The notation is a time signature line of M:none, which should suppress the time signature and any checking.


    What are ABC's rules for accidentals? Do they apply to the rest of the measure?

    Yes, they do. The rule is the same as for standard music notation: An accidental applies to that note (in any octave) for the rest of the measure, unless cancelled by another accidental. However, there are two qualifications:

    Emphasis
    It is common practice to repeat accidentals if there are more than a few notes in between, in case the reader forgot. Also, it's common to use accidentals if the repeated notes are in different octaves or in different vocal lines. These accidentals are redundant and not strictly necessary, but they can help make your music more readble.
    K:none
    To nobody's surprise, modern electronic musicians have discovered ABC, and as a result, there is a suggestion that this be used for the sort of music that doesn't have a true tonal center. This key signature would cancel the usual rule for accidentals, and require that accidentals be used on every note that needs one. This is not officially part of the standard yet, but it is highly likely to be adopted soon, and there is some software that already implements it.

    How do I put words (lyrics) in my abc files?

    Proper support for words is new as of early 1997, and may not work yet with all programs. (It may be a while before abcMIDI supports them. ;-) There is also some experimenting going on with variants on the notation, so some of this may change in the future (but probably not by much).

    There are two different sorts of word lines: w: and W: lines.

    w: 1.~This ill-us-trates a line* of lyr-*ics.
    Such lines are printed where they appear, with the syllables aligned with notes. There is provision for putting multiple notes with a single syllable, and putting multiple syllables with a single note. In counting notes, ties and slurs are ignored.

    Here are the special characters:

    -
    The hyphen (-) and spaces are used to delimit what goes with a single note. Use hyphens between syllables to get them aligned with notes. Some programs have problems with spaces around hyphens, so you probably shouldn't use them yet (though this does detract from readability).
    * _
    The asterisk (*) and underscore (_) are both used to say that the preceding syllable takes up one more note. Use two asterisks for three notes, and so on. The difference between the two is: The underscore will be drawn as an extended underscore after the syllable, as is done in a lot of volcal music to indicate that the syllable is to be held. The asterisk just produces spaces in the output, with no explicit indication of how long to hold the note. Which you use is a matter of taste.
    ~
    The tilde (~) is a space that is treated as a letter, so you can put more than one syllable under a single note. Initial non-alpha characters (the "1." in the above example) are printed to the left of the note's position, for the purpose of labelling verses. A tilde may also be used after a syllable to force wider spacing.
    \-
    appears as a hyphen in the output.
    \
    is the ABC continuation character, and in this case means that the next w: line is part of the same line.

    W: This illustrates a line of lyrics at the bottom.
    Such lines are produced at the bottom of the music, as block text. You may put them anywhere in the header or within the tune. This allows for the practice of putting one verse with the music, and the rest of the verses down below. You can also use this to attach arbitrary text to the music that will always appear at the bottom. (unlike N: lines that default to being ignored).

    Here's an example with lyrics below the notes, and an English translation below the music. And here's what it looks like as a gif file.


    How is the end of a tune determined?

    By a blank line. This means that you shouldn't put blank lines within a tune, as they will truncate the tune. You can use "nearly blank" lines that consists of just a '%' or '\'.


    How do I put chord symbols above (below) the music?

    Currently, abc2ps puts chord symbols above the music, and abc2mtex puts them below. The music publishing industry is evenly divided as to which is "correct". Eventually, there may be options telling the abc programs which you prefer.


    How do I write things like "ff" or "Crescendo" or ">" or "da Capo al fine".

    This is an area of future development. ABC currently has no standard way of including such directions. Many people have (mis)used the quoted "guitar chord" notation for this purpose. The problem with this is that when ABC is tranposed, "da Capo al fine" becomes "eb Dbpo bl gind" for Bb instruments. Stay tuned ...


    How do I convert abc to GIF, TIFF, JPEG, etc.?

    This is an area of future development. Many unix-like systems, including recent linux or freebsd systems, have ghostview and the GNU graphics tools. Look around for things with "pbm" or "png" in their names. If you have these, you probably have everything you need, though they might not be easy to use at first. Here are a few perl scripts that use them:

    ps2gif
    converts PostScript to GIF.
    ps2png
    converts PostScript to PNG.

    With ghostview, you can use abc2ps to get a postscript file, and then convert it to gif with the command:

    	gs -q -DNOPAUSE -sDEVICE=ppmraw -r${resolution} -sOutputFile="|pnmcrop|ppmtogif -interlace >xx.gif" -- xx.eps
    
    A value 100 for ${resolution} seems to give a reasonable result on at least some screens; you may want to experiment a bit. Here's a perl script that can do it for you.

    We can thank Richard Robinson <richard@beulah.demon.co.uk> for this one.

    Macintosh users can get ghostscript for the Mac, and you might also check out the Acrobat Reader.


    What are abc's rules for spacing and/or newlines?

    Sometimes spaces and newlines are significant; sometimes not. Here are some guidelines:

    Note groups.
    Spaces within groups of notes are significant: They determine what is beamed together with notes of length 1/8 or shorter. Thus with L:1/8, |DEFG| will be four notes beamed together as a single group, while |DE FG| will be two pairs of notes.
    Bar lines.
    Spaces around bar lines are generally not significant. However, double bars and repeat bars (|| |: :| [| |]) should not have any internal spaces.
    Newlines (line feeds).
    Newlines at the end of lines of music are significant; the basic idea is that one line of abc produces one staff of music. However, if the line ends with a backslash (\), the newline is ignored, and the line is combined with the next line. Some abc programs have options that effect this: "abc2ps -c" ignores all the newlines, and decides for itself when to go to a new staff. You may use ! to force a new staff, even with "abc2ps -c". And newlines don't mean much to programs like abcplay and abcMIDI, for obvious reasons.
    Chords.
    Spaces around "guitar chords" in quotes are not significant. But if the chord is within a note group, spaces are significant because of the note group. Thus |"Gm"GBd2| and |"Gm" GBd2| mean the same thing. But in |"Gm"GB"D7"d2|, you shouldn't put spaces around "D7", because that will change the way the notes are beamed.

    (This reminds me: The statement above that there are no known email problems with abc was actually a small lie. There is one known problem. Some email packages like to truncate text to 72 or 80 columns by inserting newlines. This can cause very strange effects in abc files, especially when the newline is in the middle of an ornament. It's hard to believe that the punch-card mind is still with us, when there no longer seem to be any 80-column devices on the market. We should probably just hunt down the programmers who write things like this, and shoot them on the spot. It'd probably qualify as justifiable homicide. Unfortunately, we can't afford the time, since we are too busy hunting down the turkeys who brought us the year 2000 problems, and shooting them. ;-)


    How do I write out ornaments?

    The first answer, which you will hear from many experience musicians, is "Don't." The more experienced musicians usuallly want just the tune, thank you, with maybe a few subtle clues as to what to ornament. For them, ~D suffices to say "ornament a D however you feel like at the moment."

    But you may want to write out suggestions for those who aren't as intimitely familiar with the style. The main technique that abc provides is the {x} notation. Thus you could write out an ornamented G in several ways:

    G{A}G{F}G
    G>{B}G{F}G
    G>{A}G{B}G
    G>{A}G{B}G/G/
    {eGdGBG}G2

    How do I control margin alignment?

    This doesn't seem to be well standardized right now.

    With abc2ps, the default is that all music lines but the last are aligned on the right; the last is its "natural" width. The "-g shrink" suppresses this alignment, and gives a jagged right margin. However, a final '*' on a line causes that one line to be stretched to the right margin. Got all that?

    abc2win offers a way to do this in the Page Layout Settings. Select "Tune Space and Layout" and then turn on the checkbox labelled "Justify Last Line." (quote from Jim Vint)


    How do I get Balkan/Klezmer key signatures?

    This is a recent addition to the standard, as of early 1996, and not many programs handle it properly yet. The notation now allows for explicit accidentals in a K: signature line, in addition to the tonic and mode. Thus [K:Dm_e^f] would represent D hijaz/freygish, with a key signature of _B_e^f. (You might also use [K:D_B^f] for the rarer form with ^c throughout.)

    Programs known (not) to handle explicit key signatures:

    ???
    abc2mtex
    No
    abc2ps (June 97)
    No
    abc2win (June 97)
    ???
    abc4Mac
    Yes
    abcMIDI (June 97)
    Yes
    abcmus (June 97)
    ???
    AbcPlay
    Yes
    BarFly (July 97)
    ???
    Muse

    How do I get my favorite browser to handle abc files? This is another question for which further research is needed ...

    If you are using Netscape, and have perl, abc2ps and ghostview (that is, you are probably a Unix user ;-), then you might be interested in my Helper and abc2gv scripts, which team up to implement a browser "helper" app that can be used to automate display of abc files. If installed correctly, with a .helpers file in your home directory, you can click on a link to a .abc file and a couple of seconds later a window will pop up with the music displayed. This works well with single-tune files; it becomes rather slow and unweildy when you try to access some of the huge single-file abc collections on the net.

    Also, this scheme doesn't seem to work with Mosaic or lynx (though their docs say it should), and MSIE is a complete unknown to me. Maybe someone else can send me further information about other browsers.

    Ultimately, what is needed to do this correctly is to establish an official abc MIME type, and pressure all suppliers of web software to include it. This is in the works; the type will probably be "text/vnd.abc".


    What suffix should abc files have?

    For "pure" abc files, it should be ".abc". Some software makes this difficult, and wants you to use things like ".txt". Try not to let this happen, as abc software might not recognize it.

    Some people put abc files on the web with ".html" as a suffix. This is a very bad idea. There are things in abc that look like html, and the result is lost notes. Consider the measure

    The <B c> portion looks like a bold tag (with a nonsensical c qualifier that is ignored). Any browser will display this as This can't be avoided. It's not a bug; it's what browsers should do if told that the data is html. So abc files on the web should be in separate files, not in html files.
    Are there any searchable indexes of online ABC tunes?

    Yes. Here are some. If you decide to tackle the job, let me know.


    How can I find a tune based on ...?

    This is definitely an area for further development. Some partial answers:

    The abc2mtex package has the ability to find tunes in arbitrary keys and do "approximate" matches. You don't have to install the full mtex package to use the search features.

    See JC's tune finder for a way to locate ABC files based on (partial) title matches.


    How about tempos?

    This is handled by the Q: header line, which has several formats:

    Q: 120
    This means 120 beats per minute, but it's not always clear what a "beat" is. Most software interprets this as whatever the L: line says. However, there seems to be some software that only does this if the L: line precedes the Q: line, and does something different if the Q: line comes first. Stay tuned ...
    Q: 1/4=120
    This says that there are 120 quarter notes per minute. This should be shown by printing programs in the usual notation, with the "1/4" replaced by a quarter-note symbol.
    There are ongoing discussions about the limitations of this notation, and how to further extend ABC to handle them.