|home||tune search||software||learn abc||discuss||about||blog||Starbound/LOTRO||contact|
[abc standard: home | current | route-map | updating | proposals]
Transposition proposal: summary
abc-pitchis specified in the tune (or file) header, rather than in each voice - see message 6977 and that each tune should be transcribed entirely at sounding pitch or entirely at written pitch
transpose=(as indicated below) or not;
sounding(as used below), or
written, or no default (meaning that an
instrumentmodifier would generate an error message if there is no
I:abc-pitchdirective with an
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
V:voice fields. The general syntax is:
[clef=]<clef name>[<line number>][+8|-8] [middle=<pitch>] [shift-<type>=<semitones>[<enharmonic indicator>]] [instrument=<key>] [octave=<number>] [stafflines=<lines>]
<…> denotes a value,
[…] denotes an optional modifier, and
| separates alternative values).
… unchanged …
[shift-<type>=<semitones>[<enharmonic indicator>]]- the
shiftmodifiers 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
shiftmodifiers (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.
… unchanged …
Recommendation: In multi-voice tunes it is recommended that these modifiers only applied to
V:voice fields (an additional
V:voice field can even be introduced if one of the modifiers needs to change at a
K:key change). In single-voice tunes they will normally be applied to the
K:key field. However, if a single-voice tune contains
V:voice fields (for example, if it is a part extracted from a multi-voice score), then it is recommended that modifiers are applied to the
The modifiers may be arranged in any order but there must be no more than one of each modifier in the same field. In this context,
shift-score count as two different modifiers and so it is possible for them to appear together.
Within a given voice, the modifiers of each
V: field are generally inherited from the previous
V: (unless overridden) - see scope and inheritance of modifiers.
transpose modifier of abc 2.1 is equivalent to the
shift-sound modifier. However, the use of
transpose is now deprecated.
TODO: Update deprecated list.
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
abc-pitch modifiers, see writing abc code for transposing instruments.
… 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
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, the tune (or file) should indicate whether the abc code is transcribed at sounding pitch or written pitch (using an
I:abc-pitch directive). Subsequently each transposing instrument's voice has transposition modifiers (
instrument and / or
shift) which indicate how the abc code should be interpreted. Typically these appear in the
V: field although they may also be used in the
K: field (for example, in a tune transcribed for a single voice).
instrument modifier, together with the
abc-pitch setting, describes how the music has been transcribed for a transposing instrument and closely mimics typical language used by musicians who play such 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 the other.
abc-pitch, which indicates how the abc code has been transcribed (and thus how the
instrument modifiers are to be interpreted), is set using either of the following directives in the tune (or file) header:
abc-pitch only indicates how the
instrument modifiers are to be interpreted; it has no effect on any voice that does not contain an
instrument modifier, so voices written for non-transposing instruments are completely unchanged by it. Furthermore,
abc-pitch has no effect on the
shift modifiers (although, for clarity, the use of the
I:abc-pitch directive is recommended in all tunes transcribed for transposing instruments, even if they only use
I:abc-pitch directive is omitted and an
instrument modifier is encountered, the default
abc-pitch is assumed to be
The two transposition modifiers, specified in the
K:key fields, are used as follows:
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";
shiftmodifiers 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-scoreindicates how to produce this; conversely, if the abc code has been transcribed at written pitch, the playback will need adjusting and the
shift-soundindicates 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:
I:abc-pitch=sounding V:clarinet instrument=Bb 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:
I:abc-pitch=written V:clarinet instrument=Bb shift-sound=-2
As noted above, the
shift modifiers are mutually dependent and it is straightforward to calculate one from the other. 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):
| || || ||example|
| || || |
| || || ||Bb clarinet|
| || || ||A clarinet|
| || || |
| || || ||alto flute|
| || || ||cor anglais|
| || || |
| || || ||alto sax|
| || || |
| || || |
For high and low transposing instruments, the instrument key can be followed by a
- 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.
shiftequivalents are therefore
shift-score=-3(9 - 12) for abc at sounding pitch and
shift-sound=+3(-9 + 12) for abc at written pitch.
shiftequivalents 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 transposing instrument modifier can inferred from the other it is possible to omit one of them, according to taste, as follows:
instrumentmodifier is omitted it can be inferred from the
shiftmodifier and the
abc-pitchsetting (e.g. see the table above);
shiftmodifier is omitted, it can be inferred from the
instrumentmodifier and the
abc-pitchsetting (e.g. see the table above).
Examples: The following
V: fields contain equivalent ways of specifying a Bb instrument at sounding pitch:
I:abc-pitch=sounding V:clarinet instrument=Bb shift-score=+2 V:clarinet instrument=Bb V:clarinet shift-score=+2
Examples: The following
V: fields contain equivalent ways of specifying a Bb instrument at written pitch:
I:abc-pitch=written V:clarinet instrument=Bb shift-sound=-2 V:clarinet instrument=Bb 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 modifier(s) that they find most suggestive and stick with it as far as possible.
For all non-standard cases, the
shift modifiers can be used, since they merely describe how the abc code is to be treated. Indeed they provide a self-contained transposition system, which is both complete and very flexible (more so than using standard notation), in particular since both
shift-sound can appear in the same field.
Examples: None of these usages are recommended, but they are available.
K:C shift-sound=-2 shift-score=+7indicates a tune transcribed in C, played back in Bb and typeset in G;
K:C shift-score=+7 shift-sound=+7indicates a tune transposed from C to G;
shift-soundto include a written-pitch voice in a sounding-pitch tune.
shift modifiers are mutually dependent, it is possible for a field to contain conflicting information. In this context, a conflict is said to occur when the "shift" modifier(s) specifies a different number of semitones to that implied by the
If a conflict arises the
shift modifiers override
instrument (since the
shift modifiers are self-contained). However, software encountering such conflicts should issue a warning to the user.
Example: If the abc is transcribed at sounding pitch (
I:abc-pitch=sounding), a Bb instrument requires the typeset score to be shifted up by 2 semitones. Therefore the combination of
shift-score=+3 instrument=Bb is meaningless, musically. However, since the
shift modifier overrides the
instrument, this combination would be treated exactly the same as
shift-score=+3 instrument=A, 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:
I:abc-pitch=sounding V:clarinet instrument=Bb % or shift-score=+2 or both 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
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:
I:abc-pitch=written V:clarinet instrument=Bb % or shift-sound=-2 or both 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 considering the
shift modifiers and the semitone shift table (even if the
shift modifier has to be inferred).
Example: In the following, the
instrument=Bb modifier (together with the
I:abc-pitch=sounding directive) 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.
I:abc-pitch=sounding K:E instrument=Bb
To access other enharmonic choices, the
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.
I:abc-pitch=sounding K:E instrument=Bb shift-score=+2b
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 the transposition's
shift-sound equivalents into the transposing instrument's
shift modifiers (even if those modifiers have to be inferred).
Example: Consider the following excerpt:
I:transposition 7 V:clarinet instrument=Bb K:C CDEF|
I:transposition 7 directive is equivalent to applying
shift-sound=7 to every key signature (see transposition of a tune / file). Meanwhile the
instrument=Bb assumes the default of
I:abc-pitch=sounding and hence 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 modifier is omitted since it no longer makes 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
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).
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.
It has no effect on tunes where
I:abc-pitch=sounding (the default) is already in use.
To achieve this, for tunes where
I:abc-pitch=written is in use, in effect
I:shift to-sounding infers any missing
shift-sound modifiers and treats all of the
shift-sound=<semitones> modifiers as if they were
shift-score=<semitones>. There shouldn't be any
shift-score modifiers in the tune (since they are only used for sounding-pitch tunes), but if they are there to handle some kind of non-standard transposition, they are ignored.
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:C instrument=Bb % the default abc-pitch=sounding implies shift-score=+2 CDEF| V:clarinet 2 K:D instrument=Bb abc-pitch=written % implies shift-sound=-2 DEFG|
V:clarinet 1 K:C CDEF| V:clarinet 2 K:D shift-sound=-2 shift-score=-2 DEFG|
Generally, when an
I:transposition directive is used for a tune, or a
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
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
Example 2: The transposition
K:C shift-score=6 is ambiguous as to whether
K:F# is intended since both are six steps away from C in the cycle of fifths.
In ambiguous cases, enharmonic indicators
# 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:C shift-score=6# would shift it to
By extension, enharmonic indicators
## 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 sharp and double flat accidentals should be supported, 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:G (the row headed
K:C and the column headed
G) is a positive shift of 7 semitones and hence
I:transpose 7 is used. Transposing down from
K:G is (7 - 12) = -5 semitones and hence
I:transpose -5 is used.
The shift can also go beyond an octave.
K:C shift-score=19 would shift the typeset score up an octave and a fifth from
K:G (i.e. the note
C is transposed to the note
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:Gmin is a positive shift of 7 semitones (the same semitone shift as for
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).
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).