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>]] [instrument=<key>] [pitch=sounding | written] [octave=<number>] [stafflines=<lines>]

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

… unchanged …

• [shift-<type>=<semitones>[<enharmonic indicator>]] - the shift modifiers 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>]].
• [instrument=<key>[<octave>]] [pitch=sounding | written] - the instrument and pitch modifiers aid with writing abc code for transposing instruments by mimicking typical verbal usage for such instruments and act as aliases for shift-sound and shift-score. For more information see writing abc code for transposing instruments.

… unchanged …

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

For more details about transposition and how the shift modifiers may be used see transposition of a tune / file, enharmonic indicators and writing abc code for transposing instruments. For more details about instrument and pitch see writing abc code for transposing instruments.

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

… unchanged …

TODO: The exact syntax here has yet to be discussed. However, it may not be possible to use I:transpose because of an existing %%transpose directive.

When included in the tune header (or even the file header) the I:transposition directive, followed by the number of semitones, can be used to transpose a complete tune (or even all the tunes in a file).

Example: The following excerpt would be transposed up a fifth from C into G.

I:transposition 7
K:C
CDEF|

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

The I:transposition <semitones> directive is equivalent to applying shift-score=<semitones> and shift-sound=<semitones> to every K: field in the tune (file) and therefore the rest of this section is written in terms of the shift modifiers.

For details of how the I:transposition <semitones> directive combines with existing shift modifiers in the tune (i.e. in a tune that has one or more voices written for transposing instruments), see transposition for transposing instruments.

Generally, when a shift-score or shift-sound modifier 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 modifier.

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 modifiers 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).

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 sounding pitch, with a shift-score modifier to change the typeset score to written pitch
• at written pitch, with a shift-sound modifier to change the sound output to sounding 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.

As an alternative syntax, more familiar to musicians who play transposing instruments, the abc music code can also be transcribed:

• at sounding pitch, with a pitch=sounding modifier to indicate this and a instrument modifier to indicate what the software must do to change the typeset score to written pitch
• at written pitch, with a pitch=written modifier to indicate this and a instrument modifier to indicate what the software must do to change the playback to sounding pitch

The instrument modifier specifies the "key" of the instrument (e.g. Bb), followed optionally by an octave indicator (e.g. +1, -2) to specify if the transposition is "high" or "low".

Example 1: Bb instruments sound a tone below what is written, so for sounding pitch the following two fields are equivalent:

V:clarinet shift-score=+2
V:clarinet instrument=Bb pitch=sounding

Example 2: Similarly, for written pitch the following two fields are equivalent:

V:clarinet shift-sound=-2
V:clarinet instrument=Bb pitch=written

Note that an instrument modifier must always be accompanied by a pitch modifier and vice-versa. If either one appears (in a K: or V:) field on its own, it will be ignored.

The following instrument aliases are supported (see Wikipedia for a full list of transposing instruments):

For high and low transposing instruments, the instrument key can be followed by a + or - together with the number of octaves.

In these cases the shift-score equivalent has 12 subtracted from it for each octave the instrument is raised and 12 added for each octave it lowered. Similarly the shift-sound has 12 added for each octave it is raised and 12 subtracted for each it is lowered.

Examples:

1. The sopranino saxophone is in high Eb and so would be written ''instrument=Eb+1''. The ''shift'' equivalents are therefore ''shift-score=-3'' (9 - 12) and the ''shift-sound=+3'' (-9 + 12). 
2. The tenor saxophone is in low Bb and so would be written ''instrument=Bb-1''. The ''shift'' equivalents are therefore ''shift-score=+14'' (2 + 12) and the ''shift-sound=-14'' (-2 - 12). 

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, 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:clarinet shift-score=2
K:C
CDEF|

Alternatively, using the instrument modifier it could be written:

V:clarinet instrument=Bb score=sounding
K:C
CDEF|

Either will be rendered by abc playback software as the notes CDEF and by abc typesetting software as follows:

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

If, however, 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:clarinet shift-sound=-2
K:D
DEFG|

Or, using the instrument modifier:

V:clarinet instrument=Bb pitch=written
K:D
DEFG|

Either 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.

Enharmonic distinctions can be determined using the shift variant and the semitone shift table.

Example: The following two fields are identical and therefore the resulting score would be typeset as if the key signature were K:F# rather than K:Gb.

K:E instrument=Bb pitch=sounding
K:E shift-score=+2

To access other enharmonic choices, the shift-score (or shift-sound) modifier should be used directly, although it can be used alongside the instrument and pitch modifiers (which are effectively ignored).

Example: In the following, the shift-score=+2b indicates that the resulting score should be typeset as if the key signature were K:Gb rather than K:F# (although this would be an unusual way to write for a Bb instrument):

K:E instrument=Bb pitch=sounding shift-score=+2b

If the I:transpose directive is used for a tune which has one or more voices written for transposing instruments, then the transposition is combined with the transposing instrument by adding together the equivalent shift-score and shift-sound modifiers.

Example: Consider the following excerpt:

I:transposition 7
V:clarinet instrument=Bb score=sounding
K:C
CDEF|

The I:transposition 7 directive is equivalent to applying shift-score=7 and shift-sound=7 to every key signature. Meanwhile the instrument=Bb score=sounding is equivalent to shift-sound=2. The excerpt above is therefore equivalent to:

V:clarinet shift-score=9 shift-sound=2
K:C
CDEF|

TODO: Decide a sensible rule for combining enharmonic indicators - e.g. what happens if you combine shift-score=6# with shift-score=11b?

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 modifiers and treats all of the shift-sound modifiers 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|