home tune search software learn abc discuss about blog Starbound/LOTRO contact  

  [abc standard: home | current | route-map | updating | proposals]


13 Transposition

13.1 Entering code in a different octave

The ordinary syntax of abc notes can be tedious and error-prone, if used outside the typical treble clef range and thus requiring many commas or apostrophes. To avoid this and make the code shorter, you can use the voice parameter

octave=<number of octaves>

or, equivalently, the separate field

I:octave <number of octaves>

- where <number of octaves> is the difference between the desired meaning and the coded notes, in octaves. For example,

[I:octave 0]…[I:octave -1]c[I:octave 0]

is completely equivalent to

[I:octave 0]…C

regardless of clef and transposition. The scope is voice-related. Such a statement (in either of the syntax variants) remains valid until the next such statement within its voice. In particular, it survives changes of clef, ottava, transposition etc. Only ordinary notes and grace notes are affected, not note names that appear as syntax elements for other items, such as clefs with "middle=".

Rule of thumb for all keywords related to transposition and having numbers for value, including "octave":

Starting from the typed code, add the numbers (in given units) to obtain the desired result. For example, to quickly decide the correct sign of an "octave", think "Typed c should mean c' - which is +1 octave higher". Sometimes more than one distinct keywords affect the same type of result, e.g. the sounding pitch; in this case the first one is applied to the typed code, the second one to the result of the first one, etc. The order is always irrelevant.

If you are still in doubt, use the alternate "note to note" syntax, specifying two notes differing by the desired multiples of a pure octave:

I:octave <note1> to <note2>


I:octave d to D, % typed d means D,

13.2 Transposing instruments

Some instruments, e.g. the clarinet, traditionally require sheet music that is transposed against the intended sound by a fixed number of semitones. The "shift" keywords are designed for that purpose.

13.2.1 The "shift" keywords

If your abc code reflects the intended sound, use

I:shift-score <transposition>

to get the desired sheet music. <transposition> can be the number of semitones by which you want the notes displayed above their abc representation, so it will be 2 in the case of the Bb clarinet. (See next chapter for another interpretation of <transposition>.)

If you prefer to enter the code as displayed (e.g. copying an existing clarinet sheet), use

I:shift-sound <transposition>

to have the desired sound. <transposition> is usually the number of semitones by which you want the notes to sound above their abc representation, so it will be -2 in the case of the Bb clarinet.

The two coding methods can be mixed passage-wise, by setting the currently unused parameter to 0.

For some special purposes, the two keywords can even be used non-zero in conjunction, so that code, display, and sound may be in three distinct keys. Acceptable use cases for this include the wish to type in C major, or copy-pasting snippets in a different key from elsewhere - even for non-transposing instruments! However, for the typical temporary overall transposition, the special mechanism described below is to be preferred.

Some instruments, including double bass, piccolo flute, various recorders, celesta, guitar, etc., can be treated either as transposing instruments - by an octave - or as endowed with special clefs, depending on the user's preferences about concert score representation, little '8's printed at the clef, etc.

Transposition (in the sense of this chapter) is never staff-related. When two voices share a staff, the clef will be unified, but not transposition. Normally it is insensible to have them differ in this respect. A tradition-honoured exception is a 'cello voice at original pitch sharing a staff with an octave-transposed double bass voice.

The value 0 means no change (see below), which is of course the default value.

13.2.2 Voice parameter "transpose="

A legacy syntax is the voice parameter

transpose=<number of semitones>

- now to be mapped to

I:shift-sound <number of semitones>

13.2.3 Enharmonically sensitive variants

The number of semitones is actually not sufficient to determine the displayed result. For example, if a piece is transposed by -6 semitones, the note c may result either in ^F or _G. If <transposition> is specified just by the number of semitones, the choice will be done "pragmatically", depending on the keys, as described below. This normally yields good results when no keys of more than five accidentals are involved.

For cases in which the user needs or wants more control, there is a different functionality expressed by the syntax

I:<keyword> <number of semitones> dia <number of diatonic steps>

for the <keyword>s shift-score, shift-sound, and transpose-all (see below). For shift-sound, it only makes a difference in a concert score (see below). A diatonic step is a step in the scale of pure note letters, including octave indicators but disregarding all accidentals. A pure octave has 7 diatonic steps.

In the above example, "-6 dia -4" produces ^F (it takes four diatonic steps from c down to F), whereas "-6 dia -3" results in _G.

Note that a constant <number of diatonic steps> largely ensures the preservation of melodic contexts in our notation system. This system does have its limits, so that in rare "chromatic" cases some further editing - enharmonic switching - may be necessary to make a transposition look absolutely fine. Users with such demands will probably prefer to use software tools.

If you encounter an error message of the type "maximal multiplicity of accidentals exceeded!", you may have used an erroneous combination of semitone and "dia" values. However, there may be passages for which no uniform "dia" value works at all without producing that error. In such passages, you should try to insert additional shift statements of varying "dia" values, amounting to enharmonic switches. (Sometimes a change of key signature helps; however, inserting this into existing abc code normally requires a software tool that adjusts the accidentals at the notes.)

13.2.4 "Note to note" syntax

An alternate syntax for that "enharmonically sensitive" functionality and the "pragmatic" one is

I:<keyword> <note1> to <note2> [prag]

specifying two abc notes:

  • <note1> is an arbitrary abc note to start from, e.g. imagined in your abc code,
  • <note2> is the abc note you wish to result from it, e.g. to sound or to be displayed.

Software will calculate the semitone and "dia" values from that. Example: the following commands are equivalent:

I:shift-score E to _d I:shift-score ^F to _e I:shift-score 9 dia 6

(as sometimes needed for alto saxophone voices, whereas "9 dia 5" would be the normal "_E to c").

The modifyer "prag" disregards the "dia" value, producing the "pragmatic" variant described below. For example, the following three are equivalent

I:shift-score 9 I:shift-score _E to c prag I:shift-score ^D to c prag

Rule of thumb: symbolically, to write for instruments named "… in X", such as "clarinet in A", use either of the following:

I:shift-score X to c [prag] % abc code as sounding; mnemonics: "X between the two c's" I:shift-sound c to X [prag] % abc code as displayed

- of course in the suitable octave and accidental syntax. See the list of common instruments in the appendix [TODO]. Note that a "tenor saxophone in Bb" will normally take "_B," for X, but sometimes "^A," is desired instead.

13.2.5 Transposition of key signatures

A transposition is primarily a mapping from notes (with their accidentals, no matter whether written directly or coming from a key signature) to other such notes. But it is also sensible to make it reinterpret all key signatures, except for "K:none". There is a single natural way to do this:

  1. Transpose the fundamental note, disregarding its octave,
  2. keep the mode unchanged.
  3. For any explicitly added accidental, consider the corresponding note, and use the accidental of its transposed note (which may be a natural sign). Normally the octave of these accidentals is irrelevant; software should position them to suit the clef.
  4. In the very irregular case of differing accidentals in octave distance, e.g. "K:C ^f =F", the octave does matter. If this causes problems with accidentals on ledger lines, software should issue an warning message and add those accidentals at individual notes.)

(Note that if of some transposition you only know its effect on a key signature, you still do not know its octave. If the signature happens to be K:none, you know nothing.)

A command that transposes the score (shift-score, transpose-all, and shift-sound with the concert score, see below) will automatically cause the current key signature to be displayed in the new transposition, unless K:none applied before and still applies. Example from a typical clarinet voice, switching between the Bb and the A instrument:

K:C % ending the header V:clar [I:shift-score +2] % displays Bb major CDEF| [K:B] CDEF "^Muta in A" | Z20 | "^in A" [I:shift-score +3] % now displays a signature change to C major! …

This ensures that the following two lines have the same effect, to display a D major key signature:

[I:shift-score +2]…[I:shift-score +3][K:F]… [I:shift-score +2]…[K:F][I:shift-score +3]…

- the first one by operating on the K: field, the second one by the mechanism just described.

Note that for shift-sound (outside the concert score), there is no corresponding automatism, since there is no interaction with K: fields.

13.2.6 "Pragmatic" algorithm

For the simple <number of semitones> syntax, the "dia" value is deduced from the current key signature (K:), recalculated at every change of it. The idea is to have as few signature accidentals as possible, pragmatically accepting enharmonic switches in rare cases. Therefore we speak of a "pragmatic" transposition directive, as opposed to (enharmonically) "sensitive".

For each key signature, the algorithm considers the accidentals from the basic key part, disregarding any explicit accidentals in it. (For this purpose "K:none", though actually remaining unchanged, is treated like "K:C".)

  1. If possible, the (unique) "dia" value is used that produces less than six such accidentals.
  2. If six are needed, those are chosen that have the same type - b resp. # - as the original signature.
  3. If the latter had no accidentals at all, the "dia" is used that produces six sharps.

This will always produce decent key signatures, but users must be aware that it may still result in some notes of unwanted or even illegal multiplicities of accidentals. In such cases you may try to insert "sensitive" directives to induce enharmonic shifts.

Important exception: for <number of semitones> values 0 or multiples of 12, the pragmatic algorithm does not touch any accidentals, i.e. is always equivalent to "x*12 dia x*7", even in keys such as C# major. This ensures that "the default is 0" makes sense.

13.2.7 Invariant transposition

For all purposes where the colloquial notion "transposing instrument" is relevant, e.g. for concert scores, the transposition interval assumed is the difference between the current shift-score and shift-sound values.

Sometimes transposition, usually by whole octaves, is used for slightly different semantics, in particular meant to be unchanged in the concert score. To cater for this, the marker "inv" for "invariant" can be added at the end:

I:shift-sound|shift-score <transposition> inv

The most prominent use case is a bass staff shared by a 'cello and a double bass voice, as often found in classical music (now considered obsolete):

I:score … (vcl db) I:concert-score true … V:vcl clef=bass … V:db clef=bass [I:shift-sound -12 inv] % ensures appearance in the concert score equal to the players' sheet

Note that this effect cannot be obtained by an (otherwise useful) "double bass clef".

Another example: to cause an enharmonic switch from F# major to Gb major in a keyboard part in all scores, use either

I:shift-score 0 dia +1 inv % equivalent to "I:shift-score ^F to _G"


[I:shift-score 0 dia +1][I:shift-sound 0 dia +1]

13.2.8 Concert score

Traditional full scores have exactly the same notes as the players. If readers, such as conductors, want to know the interval between notes from parts transposing differently, they must do some calculation. Some want to avoid this effort, and ask for a so-called "concert score", in principle reflecting the sounding pitches.

An abc user whose code is designed for the players, can produce a concert score from it by simply putting

I:concert-score true

in the header. (Like "I:score", this is formally a control type, so that it can be set to "true" or "false" in mid-tune; rarely used.)

The effect is the following, absolutely mechanically:

  1. All shift-score is ignored, unless postfixed "inv"
  2. Any shift-sound (resp. transpose=), unless postfixed "inv", is considered as if followed by a shift-score field of equal value(s).
  3. Clefs and ottava declaration may change according to the mechanisms described in the respective paragraphs.
  4. All other items are untouched.

By the first two properties, the changes to the score, in terms of semitones, amount exactly to the difference between the current shift-score and shift-sound values, reflecting the netto "transposing instrument" value mentioned above. (Note however that this rule does not extend to the "enharmonic" qualifyers, see below, since shift-score is ignored in this respect as well.)

13.3 Overall transposition

Sometimes an existing score must be transposed completely, e.g. to suit the singers. Again, a single command

I:transpose-all <number of semitones>

does the trick. It is of control type, and works in addition to all other transposing mechanisms (see below for enharmonic issues). Clefs are unchanged (except that "auto" values are recalculated), which means that large intervals may not be practical.

An "I:transpose-all" transposition adds to the effect of shift-score and shift-sound. Adding two transpositions means that

  1. if both are "sensitive", their sum is defined as the transposition whose <number of semitones> and <number of diatonic steps> values are simply the sums of the respective values (you may be surprised that this actually works, in a natural way);
  2. if either of them is "pragmatic", the "pragmatic" transposition with added <number of semitones> values applies. In other words, the pragmatism is applied at the end.

In rare cases, no variant of "I:transpose-all" for a given number of semitones (typically 1) can be added to a given score without producing illegal multiplicities of accidentals. Further editing is unavoidable.

13.4 Transposition of chord symbols

The keyword

I:chord-symbols-transpose true|false

regulates whether chord symbols like "Bbdim-9/Eb" must follow the transposition regulations in their voice. It is of voice-related scope, true being the default.

In practice, chord symbols are used for two distinct purposes:

  1. to indicate the harmony to the player, for improvisation: use "I:chord-symbols-transpose true"
  2. as instructions to a different player such as a guitarist: use "I:chord-symbols-transpose false".

If false, chord symbols will only be transposed following overall transposition (I:transpose-all). Users who want yet another behaviour, can collect the chord symbols in a separate voice, usually sharing the staff.

For transposing, the following algorithm is used: The chord symbol string is considered split in parts separated by any characters that are neither ASCII letters nor digits, nor evaluate to the Unicode character 9837 ("flat") or 9839 ("sharp"). Each such part that starts with a letter from A to G or a to g will be changed. If the letter is directly followed by #, b, or one of those Unicode representations, the corresponding accidental is assumed. The resulting note is replaced by its transposed value in the corresponding representation, disregarding octaves. If some note without accidentals results in one with an accidental, software will normally use the elaborate Unicode characters; however, if it catches the author using simple # and b, it is allowed to do the same.

This mechanism does not only apply to display, but also to sound, if the chords are actually played by software.

Proposer's comments

My name is Alexander Scheutzow. Suggestions for improvements are welcome in the thread http://tech.groups.yahoo.com/group/abcusers/message/8246 - my user name there is scheutzow4cond. Thank you.

In this appendix, I would like to collect my own comments, errata, answers to questions, and announcements for the next version. It will be the only part of the text that will be edited, if possible by appending only. Any comments by readers, or separate proposals, are welcome, but will be particularly valuable if they take account of the various problems I try to solve with my proposal. So please take your time to study it/them thoroughly. Thanks.

New items

Here a list of items that my be discussed and possibly polled individually:

  1. 13.1 "I:octave" syntax, including "note-to-note" (designed for those who are nostalgic of "middle=")
  2. 13.2.2 Choice of parameters "shift-sound" and "shift-score" (basically similar to "transpose=" resp. Jef's "%%transpose")
  3. 13.2.3-4 Choice of the syntax variants "dia" and "note-to-note" for enharmonically sensitive transpositions (possible alternatives include Dave's interval syntax)
  4. 13.2.5 Forcing a change of key signature (very useful, but in some cases of enharmonic switch, people may want to keep the signature and apply the changed accidentals to the notes directly)
  5. 13.2.6 The pragmatic algorithm is required (though less trivial than some may have imagined), but some people want an "enharmonically biased" variant, following Jef and one of Chris's proposals. Is it demanded, as an add-on? It should not replace the "sensitive" syntax, see below
  6. 13.2.7 Invariant transposition - is it desired?
  7. 13.3 Overall transposition - is it desired?
  8. 13.4 Transposition of chord symbols - correct algorithm? Keyword? Do we need a new formal syntax for chord symbols?
Considerations about transposition syntax

Recent mourners for the "middle=" octave transposition have convinced me that note names are very intuitive to some of us. They should be served by the note-to-note syntax, for "octave=" and for transposition. It generally makes things easiest for the author, but perhaps slightly more difficult for the reader.

The "dia" notation is borrowed from MusicXML. I think it is much easier to understand correctly than any system of the kind "prefer flats to sharps".

Why do we need both "enharmonically sensitive" and "pragmatic" algorithms?

The former is the more elementary notion, so users and programmers have to understand it by all means. Also, in cases of "K:none", it is the only way of influencing the enharmonic interpretation.

The "pragmatic" version is not absolutely necessary, but highly demanded for various reasons, including the legacy "transpose=" syntax, and the use case of a quick overall transposition for saxophones.

"Biased pragmatic" variants, e.g. "I:transpose-all -3#", are arguable as additional options, particularly for quick overall transposition. When the "pragmatic" version of "shift-score" fails the user's wishes, an individual analysis of each K: statement is necessary, where the "enharmonically sensitive" variant is more at home, and offers the comfortable "note-to-note" syntax.

abc/standard/v2.1/proposals/transposition/alexmidicond/v1.txt · Last modified: 2012/08/15 17:45 by alexmidicond
Except where otherwise noted, content on this wiki is licensed under the following license: CC Attribution-Noncommercial-Share Alike 3.0 Unported
Recent changes RSS feed Donate Powered by PHP Valid XHTML 1.0 Valid CSS Driven by DokuWiki