Clef and transposition information may be provided in the K: key and V: voice fields. The general syntax is:

[clef=]<clef name>[<line number>][+8 | -8] [transpose=<interval>] [octave=<number>] [stafflines=<lines>][shift=<interval>]

(where <…> denotes a value, […] denotes an optional parameter, and | separates alternative values)

The abc2.1 standard also included [middle=<pitch>] but this is now deprecated – see deprecated syntax.

The <interval> parameters will usually be just a number of semitones, but a number of steps may also be specified so that <interval> = <semitones>[:<steps>] See intervals.

• <clef name> - may be treble, alto, tenor, bass, perc or none. perc selects the drum clef. clef= may be omitted.
• [<line number>] - indicates on which staff line the base clef is written. Defaults are: treble: 2; alto: 3; tenor: 4; bass: 4; perc: 3.
• [stafflines=<lines>] - the number of lines in the staff. The default is 5.
• [+8 | -8] - draws '8' above or below the staff. The notes will sound one octave higher or lower than printed. See also transposing instruments.
• [transpose=<interval>] – for playback, transpose the current voice by the indicated interval; positive intervals transpose up, negative down. This setting does not affect the printed score. An ‘interval’ can be just a number of semitones; see the notes below for the general syntax. The default is 0. Note that 8, -8 above have the same effect as transpose=12,-12. If both transposition mechanisms are present, then they add to give the total transposition. See also transposing instruments.
• [octave=<number>] to raise (positive number) or lower (negative number) the music code in the current voice by one or more octaves. This usage can help to avoid the need to write lots of apostrophes or commas to raise or lower notes. Example: octave=-1 means that the abc-note c represents middle-C both for drawing and play-back.
• [shift=<interval>] - signifies that the music code in the current voice is to be shifted by the defined interval. Example: with shift=-3 the abc notes c d e in the voice become A B ^c . This applies in the same way as <octave> and shift=-12 is exactly equivalent to octave=-1. In particular both the written and sounding pitches are shifted, whereas transpose, +8, -8, define differences between the written and sounding pitches. The default for <shift> is 0, which means that the abc notes (with any octave modification) represent the notes which are to be printed for the instrument.

An ‘interval’ can be expressed in the format <semitones> or <semitones>:<steps>. Examples:

If the number of steps is omitted, it is taken by default according to the number of semitones as:

Defaults for compound and downward intervals are as obtained by adding perfect octaves.

Note that all perfect, major, and minor intervals can be defined without explicitly defining the number of steps, and so the need to specify a number of steps will be infrequent. Furthermore, for playback purposes only the number of semitones may be needed.

Note that addition and subtraction of intervals is straightforward: the semitones and steps components are just added or subtracted individually.

Desideratum 1: a note name n semitones from C could be allowed to provide an alternative syntax for an interval of n semitones with equivalents being carefully defined to include -2=Bb, -5=G, -7=F, -9=Eb, -21=Eb-, 3=Eb+, see 'transposing instruments' below. This is an optional 'extra' to the minimal proposal. It would not introduce any conflicts.

The keywords +8, -8, transpose, (and only those) introduce a difference between the written pitch of the music (the dots) and the pitch at which it sounds. By default (but see octave and shift) the abc is encoded at the pitch of the dots.

Example 4.6.2.1: a Bb clarinet might expect

K:C
[V:clt clef=treble transpose=-2][K:D]D E F G|

and the player will see a scale of D in the key of D, but it will sound a tone lower as a scale of C in the key of C.

Example 4.6.2.2: A descant recorder might expect

K:C
[V:descant clef=treble+8] C D E F |

or

K:C
[V:descant clef=treble transpose=12] C D E F

The effect of using either +8 or transpose=12 is the same, except that the 8-option causes a little 8 to be drawn above the treble clef. In both cases the scale is written upwards from middle C, and sounds an octave higher. See also writing at concert pitch.

Combining 8 with transpose: if both 8 and transpose are used, their effects add. But drawing software should omit the 8 from next to the clef if the resultant transposition is not exactly an octave.

Desideratum 1: the note-name option to define intervals would allow human readable syntax where transpose=Bb and transpose=Eb would define the transpositions of Bb clarinet and Eb alto sax. This is an optional 'extra' to the minimal proposal. It would not introduce any conflicts. It would allow an obvious syntax for standard orchestral instrument transpositions.

The keywords octave and shift change the meaning of abc notation in the voice where they appear. They change both the written pitch of the dots, and the sounding pitch, but do not change the relationship between written and sounding pitches.

octave provides an octave renormalisation.

By default the abc note C represents middle-C and A represents what is (these days) known as A440. This is changed by octave.

Example 4.6.3.1.1:

octave=-1

means that the abc note c now represents middle-C, and the abc note a is A440. In this case the abc-note c should both be drawn on the staff in the position of middle-C, and sound as middle C.

Example 4.6.3.1.2:

…clef=bass octave=-2 …

means that the abc note corresponding with the middle line of the bass clef is now d. This facilitates bass clef writing without the need for lots of commas in the note names. On play-back, d will now sound as written, a 7th below middle C.

shift provides a renormalisation by other intervals but also including octaves: If either shift or octave is used, then shift=-12 is entirely equivalent to octave=-1. The use of shift means in general that written (and sounded) notes differ from the default definition of abc notes by the supplied interval.

Example 4.6.3.2.1:

[V:<id> clef=treble shift=-2][K:D] D E F G |

represents music to be written (the dots) in the key of C, appearing and sounding as the notes C D E F would do by default.

Example 4.6.3.2.2:

It is pertinent, perhaps, to ask why anyone would want to do that. Well, suppose you have a large score which includes a Bb clarinet part starting

[V:clt clef=treble transpose=-2][K:C] C D E F |

and you wish to insert an Eb alto sax part in unison with it. The shift keyword enables you to do this by copying and pasting the voice with minimal changes. The syntax

[V:asx clef=treble transpose=-9 shift=7][K:C] C D E F |

will do it. The notes and key signatures can be copied and pasted into the new voice, which only needs the transpose parameter changing (the sax sounds 9 semitones lower than its music is written) and the shift by a perfect 5th, saying that when I write C in this voice of the abc, I really mean G.

Important: employing octave or shift does not affect the relationship between the written pitch of the notes and the pitch at which they sound: that is still as given by transpose and/or +8, -8.

If both octave and shift are used, their effects add. For example "shift=21" is equivalenet to "shift=9 octave=1".

The abc notes (in the absence of octave or shift) represents the instrument's notes as the player conventionally sees them – ie at the instrument’s ‘written pitch’. Experienced conductors can look at a score with multiple parts written for different transposing instruments, and ‘see’ the harmonies even though each has a different transposition. However, it is undoubtedly easier if all the parts are written at the same sounding pitch (possibly give or take an octave) in the same key. This can be achieved in abc notation by

[V:xxx clef=treble transpose=-n shift=n][K:C] C D E F |

where the shift and transpose parameters are the same but with opposite signs. The shift=n means the abc-notes C D E F actually represent written notes (the dots) which are n semitones higher, but transpose=-n means that they will sound n semitones lower than the dots – ie as would normally be meant by C D E F. Thus the sounding pitch matches the abc notation.

Example 4.6.3.1 Bb clarinet

[V:clt clef=treble transpose=-2 shift=2][K:C] C D E F |

produces music (dots), because of the shift, showing a key signature of 2-sharps the notes D E F# G, which sound on the clarinet, because of the transpose, as C D E F.

Example 4.6.3.2 descant recorder

[V:descant clef=treble+8 octave=-1][K:C] c d e f |

achieves the same effect (abc-notes at written pitch). The dots will be shown (because of the octave parameter) starting 1 leger line below the treble clef, but sound (because of the +8) starting an octave higher than middle-C. An 8 will be drawn above the treble clef.

Important: even though this mechanism allows the music to be encoded into abc at sounding pitch, the print-out is still, thus far, designed to produce a score (dots) at written pitch. See concert scores for the alternative.

Desideratum 2: "shift=concert" could be a special value of shift, meaning 'set the shift value equal and opposite to the transposition', or equivalently 'encode the abc at concert pitch'. As long as this is done with the shift parameter, no conflict would be introduced, though adding an octave parameter in this case would encode the abc a number of octaves from concert pitch.

The key signature at the start of the piece is given by the K: field which terminates the header. Changes of key withing the piece are given bt in-line K: fields within the voices. These will usually align in the music in all voices. [Exceptions include French Horn (and/or other) parts written with no key signatures, and rhythm voices (see below).]

Transposing instruments must include a K: field at the start of the voice, indicating the key which applies to the following abc-code. Example:

...
V:flute clef=treble
V:clarinet clef=treble transpose=-2
I:score [ flute clarinet ]
K:C
[V:flute] C D E F |
[V:clarinet][K:D] D E F G |

The clarinet reads the music in D, but the parts sound in unison in C.

Clefs, and clef changes must be the same, and coincide, in all voices which share a staff.

Values of transpose must be the same at the start of every voice which shares a staff, and changes in the value must be the same, and coincide, in all voices which share a staff. There is one very specific exception to this rule - a rhythm voice - which is given below.

A change of transposition in the middle of a piece is occasioned by a change of instrument. The new key signature must also be supplied. For example a change from Bb clarinet to Eb Alto sax would be given by

[V:ClarinetAndAltoSax clef=treble transpose=-2][K:D]DEFG|"^to Alto"[K:A transpose=-9]A B C D |

In this case the change of key K:A does not corespond with a change of key of the overall piece, just a change of transposition in this voice. Therefore no key change need be present in parallel voices on other staves.

A rhythm voice is one which contains no notes at all, but is designed to show chord names. By this means a part, eg for rhythm guitar or banjo, can be put in a separate voice. The voice may contain hidden rests to position the changes within the music. Uniquely, a rhythm voice need not have the same transposition as voices with which it shares a staff. Example:

...
T:clarinet and guitar
...
V:gtr clef=treble
V:clt clef=treble transpose=-2
I:score (clt gtr)
K:C
[V:gtr] "C"x2 "C"x2 "C"x2 "C"x2 |"G7"x2 "G9"x2 "Gmaj7"x2 "Gsus4"x2 |
[V:clt][K:D] D2 E2 F2 G2 | D2 E2 F2 G2 |

In this case the chord symbols are drawn above the single staff. [The clarinet voice is mentioned first in the I:score as this makes it the controlling voice from which the key signature on the staff is obtained; the chords are always drawn above the staff, and the music lines are ordered in this example to reflect this.]

A rhythm voice may contain a transpose. For example transpose=2 would indicate a capo at the 2nd fret. The chord names would be printed as supplied, but play-back would sound a tone higher.

The abc2.1 standard and earlier allowed a clef definition to be accompanied by

middle=<note>

where <note> is a note in the abc syntax.

This is now deprecated for a number of reasons. New abc files should not use it.

One of its main purposes was to avoid commas in bass clef writing (which is now achieved with octave – see above). The abc2.1 standard suggests clef=bass middle=d is a good way to achieve it. The play-back pitch of the note d on the middle line of the bass clef, is not explicitly discussed, and one might assume either (a) that the relationship between played pitch and abc-notation is unaffected, or (b) that the relationship between the played pitch and the drawn music (the dot) is unaffected. Much (popular) software assumes (a); the abc2.1 standard resolves the ambiguity in the example ‘Zocharti Loch’ making it clear that it means (b). [This is musically more elegant than (a) in that it does not produce by default a bass clef part sounding two octaves higher than written.] The discrepant interpretations have been around since well before the abc2.1 standard, and there is no real hope of a resolution.

The syntax middle=<note> might also be used to put a clef on a different line – eg clef=treble middle=d might be used to produce a French Violin clef. (This is now achieved by clef=treble1.) But this gives two degrees of freedom – where to put the clef, and which octave to draw the notes – for one parameter.

Some values for the keyword must be nonsense – eg clef=treble middle=c.

And when it comes to the use of transposing instruments, and indeed to the new shift keyword, the existence of (now unneeded) middle just makes things impossibly difficult. Therefore it is now deprecated.

The keywords +8/-8 transpose octave shift (and not others) are defined as they are, for very specific reasons. Importantly:

• apart from the new shift, all are from abc2.1;
• all requirements of transposed parts are met by combining them;
• different combinations do not readily yield nonsensical abc.

In general there are three pitches of interest:

• The pitch at which the abc is represented (abc) ;
• The pitch at which the music is written (the dots) ;
• The pitch at which the music sounds (sound) .

and therefore three relationships connecting them, of which any two imply the other.

• abc → dots is controlled by the octave and shift parameters, which leave the dots→sound relationship unchanged.
• dots → sound is controlled by the +8,-8 and transpose parameters, whch leave the abc→dots relationship unchanged.

The abc→sound relationship is implied in both cases, and importantly there are no parameters which define this explicitly. Why not?

• The relationship abc→dots is the essence of abc; as a notation format it is different from MIDI which encodes only sounding pitches.
• The relationship dots→sound is a fundamental property of the score on which you're working: it defines the instrumentation (albeit incompletely).

If you know which written notes the abc represents, and you know your instrumentation, then you know where they sound. Suppose you wanted to change the abc→sound relationship directly. Then at least one of the other two relationships must change: if it keeps the instrumentation, then it redefines the meaning of the abc in terms of written notes; if it keeps the meaning of the abc notes, then it changes the instrumentation (and instrument transpositions will no longer be gven by the transpose parameter). Both of these must be considered 'side effects' of such an operation, and such are undesirable. Therefore the abc→dots and dots→sound relationships are considered as the two fundamentally important ones and abc→sound is implied.

Because of the addition properties of intervals this does not mean it is difficult to write play-back software. The interval from the written abc to the playback sound is just transpose-sound if those two parameters are used, (with +/-8 and/or octave adding octaves appropriately).

By default scores are shown, quite generally, at ‘written pitch’ (the pitch at which the instrumentalists read them) and the definitions of sect 4.6 are designed to that end. Sometimes, however, it is desirable, to present a concert pitch score (in which all parts are shown either at concert pitch or one or two octaves from it). This section deals with that situation.

The instruction

I:concert_pitch [8]

in the header tells software that a concert pitch score is wanted. The parameter 8 is optional.

If no further information (see below) is included about how such a score is to be constructed, software should

• reproduce all parts in C (those with transpose set to zero or a multiple of 12) exactly as they are at written pitch, complete with clefs.
• produce all other parts choosing bass or treble clef as it finds most convenient for minimising leger lines. Parts on treble and bass clef may be shown an octave lower or higher (respectively) than sounding, if that reduces the occurence of leger lines. [Examples: a Db piccolo part may be shown an octave lower than sounding; an Eb contrabass saxophone part may be shown on bass clef, an octave higher than sounding.]

If the optional parameter 8 is specified, then any part shown an octave from concert pitch will be marked with an 8 by the clef (and correspondingly 15 or 22 for parts two or three octaves from sounding pitch).

All of the instructions in this section are ignored when a written pitch score is being constructed. They apply only to concert pitch scores, generated by the presennce of I:concert_pitch.

It is standard practice to leave parts in C on a concert pitch score exactly as they are on a normal, written pitch score. But further control of the production of concert pitch scores, especially with other transposing instruments, is available in the form of the following instructions.

I:score_concert ….

assigns parts to staves for a concert score, with exactly the same syntax as I:score. This enables a compressed concert score to be produced. If this instruction is absent then I:score defines the assignment.

I:clef_concert <clef-name>[+8|-8]

defines clefs and clef changes on the concert score. These must be synchronised in voices on the same stave (according to I:score_concert or if that is absent according to I:score ).

An score for vocal quartet can be defined including

I:score [soprano alto tenor bass]
I:score_concert [(soprano alto) (tenor bass)]
[V:tenor clef=treble-8][I:clef_concert bass]…

and an open or closed score will be produced according to the absence of presence of I:concert_pitch.

My name is David Webber. I am the author of the music software 'Mozart' and am currently working hard to make it import and export abc - sticking rigorously, at the moment, to the published abc2.1 standard. As I do this, I am gradually acquiring (perforce) a deepening understanding of abc and what it can and can't do, so I thought it would be worthwhile to contribute here.

This proposal contrasts in some ways with that of Alex Scheutzow. (But in some areas I am stealing his ideas wholesale: I hope he accepts the latter as 'Schmeichelei' - nothing to do with goalkeepers!).

I play saxophones, clarinets, ukulele, and recorders (in that order of frequency) and so I am passionate about the inclusion of 'transposing instruments' in abc.

1) Conciseness, legacy, and sustainability. In fulfilling the objectives below I am tryuing to do it by introducing the minimum number of new keywords and with minimal changes to the old ones.

2) abc2.1 knows about transposition intervals only as a number of semitones. If abc is to be able to handle transposing instruments better, it needs to be able to handle transpositions better. This proposal deatails a method of defining detailed transpositions in such a way that anything other than the semitone count will never be needed for transpositions through major, minor and perfect intervals.

The result is a very simple extension of the transpose= syntax, which will almost never be needed. [MusicXML fans will see that it owes much to the definitions of transpositions in that format.]

3) abc2.1 only allows you to write abc code at the instrument's written pitch. This means you can't copy and paste a flute part, and make it a Bb clarinet part. Being able to do that would be useful. It also means you can't type in your abc at concert pitch for transposing instruments and see the harmonies in a nice simple fashion. It would be nice to be able to do that too.

Actually you can do it in abc2.1 for the special case of octave transposing instruments - eg with a +8 and then octave=-1.

The objectives here are achieved by the introduction of a single new keyword 'shift' which is precisely analogous to the octave keyword but allows an 'abc-shift' through any interval, not just a numvber of octaves.

4)abc2.1 can only represent 'written pitch' scores. A method is needed to write concert pitch scores. My instruction to write a concert pitch score "I:concert_pitch" is identical to Alex's "I:concert_score" but renamed for a reason. I have also taken on board Alex's "I:clef_concert" with the same meaning (having grilled him mercilessly about it), and I wanted to use the …_concert keyword suffix in the same way for I:score_concert which allows a different assignment of voices to staves when producing a concert pitch score. I renamed I:concert_score to try to avoid confusion.

Importantly, everything in (2) and (3) here is aimed at producing the dots at the instrument's written pitch (even though the abc-code can be at other pitches). (4) is extra stuff which is unneeded (unused) in that case but allows production of concert pitch dots. I think this was ALex's motivation too.