Additional text for section 4.6 Clefs and transposition

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] [middle=<pitch>] [shift-<type>=<semitones>[<enharmonic indicator>]] [octave=<number>] [stafflines=<lines>]

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

… unchanged …

• [shift-<type>=<semitones>[<enharmonic indicator>]] - the shift parameters are provided for transposition and transposing instruments. They shift either the sound or the typeset score in the current voice by the number of semitones indicated; positive numbers shift up, negative down. The <enharmonic indicator> can optionally be used to clarify which key is meant - for more details see enharmonic indicators.
  • [shift-sound=<semitones>[<enharmonic indicator>]] - for playback, shift the sound in the current voice. This setting does not affect the typeset score.
  • [shift-score=<semitones>[<enharmonic indicator>]] - for typesetting, shift the typeset score in the current voice. This setting does not affect playback.
  • [shift-both=<semitones>[<enharmonic indicator>]] - for typesetting and playback, combines both and is equivalent to [shift-sound=<semitones>[<enharmonic indicator>]] [shift-score=<semitones>[<enharmonic indicator>]].

… unchanged …

The shift-sound parameter is equivalent to the transpose parameter of abc 2.1 and either may be used.

For more details of how the shift parameters may be used see enharmonic indicators, one-off transposition and writing abc code for transposing instruments.

TODO: Here or elsewhere, clarify how the shift parameters affect the clef - see messages 6316 and 6324.

… unchanged …

Generally, when a shift-score directive is applied, each key signature will be changed to the key signature which is closest in the cycle (helix) of fifths. However, if the key shifts through 6 or more steps in the cycle, it is ambiguous which key is required.

Example 1: The transposition K:C shift-score=10 indicates a change to K:Bb rather than K:A#, since Bb is only two steps away from C in the cycle of fifths (C - F - Bb), whereas A# is ten steps away (C - G - D - A - E - B - F# - C# - G# - D# - A#).

Example 2: The transposition K:C shift-score=6 is ambiguous as to whether K:Gb or K:F# is intended since both are six steps away from C in the cycle of fifths.

In ambiguous cases, enharmonic indicators b or # can be used (immediately after the number of semitones) to state which is required.

Example: The transposition K:C shift-score=6b would shift the typeset score to K:Gb whereas K:C shift-score=6# would shift it to K:F#.

By extension, enharmonic indicators bb or ## could be used when the key shifts through 13 or more steps in the cycle (although this is unlikely to ever occur in practice).

TODO: Include some sensible limits (here and elsewhere in the document) on what keys and accidentals should be supported by compliant software; e.g. double sharps and flats should be, but triples are entirely optional.

The following semitone shift table shows all the upward shifts (i.e. transposing up from the original key to the required key) between every key from K:Cb (seven flats) through to K:C# (seven sharps).

To calculate downward shifts, look up the number in the table and subtract 12 from it (leaving the enharmonic indicator unchanged).

Example: Transposing up from K:C to K:G (the row headed K:C and the column headed G) is a positive shift of 7 semitones and hence K:C shift-both=7 is used. Transposing down from K:C to K:G is (7 - 12) = -5 semitones.

The shift can even go beyond an octave although in this case it may be clearer to use an additional octave parameter.

Example: K:C shift-both=19 transposes up an octave and a fifth from K:C to K:G (i.e. the note C is transposed to the note g). However, it might be clearer to write K:C shift-both=7 octave=1.

Note that even though they are not specifically mentioned in the table, the semitone shifts also work for minor and modal keys, provided that both original and required key signatures are both minor or both in the same mode.

Example: Transposing up from K:Cmin to K:Gmin is a positive shift of 7 semitones (the same semitone shift as for K:C to K:G).

Finally note that enharmonic indicators can also be used for the shift-sound and shift-both parameters although they will only make a difference to the sound if the playback software can handle non-equal temperaments (since, for example, a Gb will sound exactly the same as an F# in equal temperament).

In general, users may prefer to do a one-off transposition of a tune, from one key to another, using abc transposition software. Typically such software would read in the source abc file and then export the resulting transposed abc transcription to a separate file (or alternatively reads and display the source and transposed abc transcriptions via forms on web pages).

Recommendation to software developers: The abc standard does not prescribe how the transposition is to be specified and, for example, it can be done via sliders and/or text fields on a GUI or by command line parameters. Furthermore, the transposition change can be described by a change of key (e.g. C to G), an interval (e.g. up a fifth), a shift in semitones (e.g. up 7 semitones), or even the number of steps through the cycle of fifths (e.g. up one step). Choose the method(s) and description(s) that suit your users best.

However, it is also possible to specify one-off transpositions from within an abc file using the shift-both parameter which shifts both the sound output and the typeset score by a given number of semitones.

Examples:

K:C shift-both=2 % transpose up one tone from the key of C to the key of D
K:G shift-both=-5 % transpose down a fourth from the key of G to the key of D

The semitone shift table shows the number of semitones required to achieve any shift between every key from K:Cb (seven flats) through to K:C# (seven sharps).

Comment: The shift-both parameter is probably more useful in the context of folk music where it is common to have tunes that may have been transcribed in one key but are played in another. Using transposition software can result in a multiplicity of files and as an alternative the shift-both parameter allows each tune to have two different keys that can be easily accessed (the I:shift none directive can be used to toggle between the two).

Transposing instruments sound notes at a different pitch to which they are written. For example, a C written on a Bb clarinet score would be sounded as a Bb (and similarly a written D would be sounded as a C).

This section uses written pitch (i.e. the pitch that is written on a transposing instrument's score) and sounding pitch (i.e. the pitch is actually sounded) to distinguish between the two.

(Note: "sounding pitch" is also often referred to as "concert pitch"; however, confusingly, this term is also sometimes used to indicate "play A above middle C at 440Hz", so for in this section, the former terminology is preferred.)

When writing for transposing instruments, the abc music code can be transcribed either:

• at written pitch, with a shift-sound indicator to change the sound output to sounding pitch
• at sounding pitch, with a shift-score indicator to change the typeset score to written pitch

In either case, it is recommended that the abc code indicates which system is in use via a comment, although in general, shift-sound indicators would only ever be used for written pitch transcriptions and shift-score indicators would only be used for sounding pitch transcriptions.

Extended example: Suppose a Bb clarinet player and a violinist wish to play the same piece which simply consists of the notes CDEF in the key of C.

Since the violin is not a transposing instrument, the violinist's part is written (and sounded):

V:violin
K:C
CDEF|

For the clarinet part, there is a choice. If, for example, the clarinet player wants the abc music code to reflect what appears on the typeset score, the abc code can be transcribed at written pitch (i.e. the notes DEFG) with a shift-sound indicator:

V:Bb clarinet
K:D shift-sound=-2 % transcribed at written pitch, will be shifted to sound correctly
DEFG|

This will be rendered by abc playback software as the notes CDEF (i.e. shifted down two semitones) and by abc typesetting software as follows:

TODO: include typeset score image showing [K:D] DEFG

Alternatively, if, say, the composer of the piece prefers to work at sounding pitch, the clarinet part can be transcribed as sounded with a shift-score indicator to indicate that the typeset score is typeset at written pitch, two semitones up from where it is sounded:

V:Bb clarinet
K:C shift-score=2 % transcribed at sounding pitch, will be shifted to written pitch when typeset
CDEF|

This will also be rendered by abc playback software as the notes CDEF (i.e. shifted down two semitones) and by abc typesetting software as above.

When included in the tune header (or even the file header) the I:shift to-sounding directive can be used to typeset a complete score (or even all the scores in a file) at sounding pitch. To accomplish this it effectively ignores all of the shift-score parameters and treats all of the shift-sound parameters as if they were shift-both.

Example: The following excerpts will be treated identically by both playback and typesetting software and will produce a typeset score at sounding pitch (the sound output is already at sounding pitch and so is unaffected).

I:shift to-sounding
...
V:Bb clarinet 1
K:D shift-sound=-2 % transcribed at written pitch
DEFG|
V:Bb clarinet 2
K:C shift-score=2  % transcribed at sounding pitch
CDEF|

V:Bb clarinet 1
K:D shift-both=-2
DEFG|
V:Bb clarinet 2
K:C
CDEF|

When the I:shift none directive is included in the file header (or tune header), all the shift parameters in the file (or tune) will be ignored.

Comment: The I:shift none directive is most useful to cancel shift-both parameters - see one-off transposition.