Additional text for section 4.6 Clefs and transposition

As well as directives for transposing a tune (or file) and extracting a score in sounding concert pitch, detailed 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>] [abc=sounding-pitch | written-pitch] [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 used when writing abc code for transposing instruments. They describe how abc software must treat the abc code in order to produce the required typeset score or playback and specify the shift in the current voice as a number of semitones; 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. There are two shift modifiers (for more information see writing abc code for transposing instruments):
  • [shift-score=<semitones>[<enharmonic indicator>]] - for typesetting, shift the typeset score in the current voice. This setting does not affect playback.
  • [shift-sound=<semitones>[<enharmonic indicator>]] - for playback, shift the sound in the current voice. This setting does not affect the typeset score.
• [instrument=<key>[<octave>]] - when writing abc code for transposing instruments, the instrument modifier is used to indicate the transposing instrument that the abc code relates to. For more information see writing abc code for transposing instruments.
• [abc=sounding-pitch | written-pitch] - when writing abc code for transposing instruments, the pitch modifier is used to indicate whether the abc code has been transcribed at sounding pitch or written pitch. 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 transposing instruments and how the shift modifiers may be used see writing abc code for transposing instruments and enharmonic indicators. For more details about instrument and abc modifiers, 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 scoping and precedence of all of the modifiers needs some careful work as it hasn't been addressed properly yet (even in abc 2.0 where most of them were introduced). This issue also touches on multi-voice syntax, slated for abc 2.2. The scoping needs to address the interaction between global V: fields (in the tune header), the global K: field (signalling the end of the tune header and the start of the tune body), local V: fields (within the tune body) and local K: fields (also within the tune body).

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 and, optionally, an enharmonic indicator, 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 (7 semitones) from C into G.

I:transposition 7
K:C
CDEF|

Example: The following excerpt would be transposed up by 6 semitones. Because such a transposition is ambiguous, the # means that the resulting key will be F# rather than Gb. See enharmonic indicators for more details.

I:transposition 6#
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).

Comment for developers: The I:transposition <semitones>[<enharmonic indicator>] directive is equivalent to applying shift-score=<semitones>[<enharmonic indicator>] and shift-sound=<semitones>[<enharmonic indicator>] to every K: field in the tune (or file).

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

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 clarity the former terminology is used.)

To write abc code for a transposing instrument, each appropriate V:voice or K:key field has modifiers applied to it which indicate how the abc code should be interpreted.

The following modifiers are available:

• the instrument=<key> modifier describes the "key" of the instrument (e.g. Bb clarinet is indicated by instrument=Bb), followed optionally by an octave indicator (e.g. +1, -2) to specify if the transposition is "high" or "low"
• the abc modifier describes the pitch at which the abc code has been transcribed; use abc=sounding-pitch for sounding pitch and abc=written-pitch for written pitch
• the shift modifiers describe what the software must do to produce the required typeset score or to adjust the playback: if the abc code has been transcribed at sounding pitch, the typeset score will need transposing to written pitch and shift-score indicates how to produce this; conversely, if the abc code has been transcribed at written pitch, the playback will need adjusting and the shift-sound indicates how to achieve this

Example: Bb instruments sound a tone below what is written, so that if the abc code is transcribed at sounding pitch the typeset score must be shifted up by two semitones. This is fully specified as:

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

Example: Alternatively, for the same Bb instrument, if the abc code is transcribed at written pitch, then the playback must be shifted down by two semitones. This is fully specified as:

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

The instrument and abc modifiers jointly describe how the music has been transcribed and closely mimic typical language used by musicians who play transposing instruments. By contrast, the shift modifiers instruct the reader (human or software) how to produce the desired output. These mutually dependent constructs have been deliberately chosen to suit different ways of looking at the same issue and in fact each modifier can inferred from one, or both, of the others.

The following table lists the instrument "keys" that are supported together with their corresponding shift values (see Wikipedia for a full list of transposing instruments and their keys):

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:

• 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) for abc at sounding pitch and shift-sound=+3 (-9 + 12) for abc at written pitch.
• 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) for abc at sounding pitch and the shift-sound=-14 (-2 - 12) for abc at written pitch.

Because each modifier can inferred from one or both of the others it is possible to omit one (or sometimes even two) of the modifiers, according to taste, as follows:

• if either or both of the instrument and abc modifiers are omitted they can each be inferred from the shift modifier: the instrument modifier can be inferred by calculating the semitone shift (e.g. see the table above); the abc modifier can be inferred direclty - a shift-score modifier implies abc=sounding-pitch and shift-sound implies abc=written-pitch
• if the shift modifier is omitted, it can be inferred from the instrument and abc modifiers (e.g. see the table above)
• the default for the abc modifier is sounding pitch, so that if both abc and shift modifiers are missing, the default abc=sounding-pitch is assumed and the shift modifier can then be inferred (e.g. see the table above)
• however, omitting both instrument and shift modifiers is an error and should generate a warning message from the software

Examples: The following are all equivalent ways of specifying a Bb instrument at sounding pitch:

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

Examples: The following are all equivalent ways of specifying a Bb instrument at written pitch:

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

Recommendation: These differing possibilities have been deliberately included because of a wide-range of views whilst this syntax was being discussed. The user is recommended to decide on the set of modifiers that they find most suggestive and stick with them.

Since there are more ways to specify abc code for a transposing instrument than is absolutely necessary, it is possible for the modifiers within a field to contain conflicting information. If this happens the shift modifiers always override instrument and abc. However, software encountering such conflicts should issue a warning to the user.

Example: The combination of instrument=Bb abc=written-pitch shift-score=+3 is meaningless musically. However, since the shift modifier overrides the other two, this would be treated exactly the same as instrument=A abc=sounding-pitch shift-score=+3, although the software should issue a warning that the modifiers did not make sense.

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 modifiers to indicate that the score should be typeset two semitones up from where it is sounded:

V:clarinet instrument=Bb abc=sounding-pitch shift-score=+2
K:C
CDEF|

This 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

However, if 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 modifiers to indicate that the score should be typeset as transcribed, but that playback should be transposed two semitones down:

V:clarinet instrument=Bb abc=written-pitch shift-sound=-2
K:D
DEFG|

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.

Enharmonic distinctions can be assessed by conisdering the shift modifiers and the semitone shift table (even if the shift modifier has to be inferred).

Example: In the following, the instrument=Bb and abc=sounding-pitch modifiers imply shift-score=+2. Therefore, as can be seen from the semitone shift table, the resulting score would be typeset as if the key signature were K:F# rather than K:Gb. See enharmonic indicators for details.

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

To access other enharmonic choices, the shift-score (or shift-sound) modifier must be used directly.

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 a very unusual way to write for a Bb instrument). See enharmonic indicators for details.

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

If the I:transposition 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 the transposition's shift-score and shift-sound modifier equivalents into the existing shift modifiers that have been used to specify transposing instrument (even if they have to be inferred).

Example: Consider the following excerpt:

I:transposition 7
V:clarinet instrument=Bb abc=sounding-pitch
K:C
CDEF|

The I:transposition 7 directive is equivalent to applying shift-score=7 and shift-sound=7 to every key signature (see transposition of a tune / file. Meanwhile the instrument=Bb abc=sounding-pitch implies shift-sound=2. The excerpt above is therefore equivalent to the following, where the two shift-score modifiers are added together to give 9 and the instrument and abc modifiers are omitted since they no longer make sense:

V:clarinet shift-score=9 shift-sound=7
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?

If one or more voices in a tune are transcribed for transposing instruments it is sometimes useful to produce a sounding (concert) pitch score (e.g. for the conductor).

The I:shift to-sounding directive can be used in the tune header (or even the file header) to typeset a complete score (or even all the scores in a file) at sounding pitch. To achieve this, in effect, I:shift to-sounding ignores all of the shift-score modifiers and treats all of the shift-sound=<semitones> modifiers as if they were shift-sound=<semitones> and shift-score=<semitones>.

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

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

V:clarinet 1
K:D shift-sound=-2 shift-score=-2
DEFG|
V:clarinet 2
K:C
CDEF|

Generally, when an I:transposition directive is used for a tune, or a shift-score or shift-sound modifier applied to a field, each affected 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.

The following examples illustrate this. Mostly they are expressed in terms of shift-score, but the same rules govern an I:transposition directive when applied to a K: field.

Example 1: The transposition K:C shift-score=10 indicates that the score will be typeset in 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#). The same would be true for an I:transposition 10 directive applied to a K:C field.

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 18 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: To 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 I:transposition 7 is used. Transposing down from K:C to K:G is (7 - 12) = -5 semitones and hence I:transposition -5 is used.

The shift can also go beyond an octave.

Example: K:C shift-score=19 would shift the typeset score up an octave and a fifth from K:C to K:G (i.e. the note C is transposed to the note g).

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: To transpose 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 do also make sense for the shift-sound modifier 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).