home | tune search | software | learn abc | discuss | about | blog | Starbound/LOTRO | contact |
[abc standard: home | current | route-map | updating | proposals]
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>
e.g.
I:octave d to D, % typed d means D,
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.
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.
A legacy syntax is the voice parameter
transpose=<number of semitones>
- now to be mapped to
I:shift-sound <number of semitones>
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.)
An alternate syntax for that "enharmonically sensitive" functionality and the "pragmatic" one is
I:<keyword> <note1> to <note2> [prag]
specifying two abc notes:
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.
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:
(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.
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".)
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.
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"
or
[I:shift-score 0 dia +1][I:shift-sound 0 dia +1]
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:
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.)
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
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.
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:
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.
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.
Here a list of items that my be discussed and possibly polled individually:
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".
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.