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:

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

Another example: A voice coded for clarinet in A "as written" (cde), can be changed to be printed for Bb clarinet (B^c^d) with unchanged sound, by just adding a shift-score:

V:clar
[I:shift-score _B to A] % added statement
[I:shift-sound c to A] cde

The following shorthands can be used for the typical cases of "instrument in X". The general syntax is

I:instrument <note> <coding mode> [prag]

or alternately as a voice parameter:

instrument=<note>;<coding mode>[;prag]

If <coding mode> is "sounding" or "s" or (less recommended) "concert", this is a shorthand for

I:shift-score <note> to c [prag]
I:shift-sound 0

If <coding mode> is "written" or "w", this is a shorthand for

I:shift-sound c to <note> [prag]
I:shift-score 0

For example, consider a tenor sax voice ("in low Bb") entered as sounding:

V:tenorsax instrument=_B,;s

or, equivalently:

V:tenorsax
[I:instrument _B, sounding]

The user must be aware that any "shift-…" occurring later in that voice is likely to render the "coding mode" invalid. For good readability, such mixed usage is discouraged. If your abc code is neither as sounding nor as written, only use the "shift-…" syntax for those voices.

It is perfectly legitimate to switch the coding mode, and of course the transposition as need arises:

V:altosax
[I:instrument _E sounding]…[I:instrument ^D sounding]…[I:instrument _E written]…

In the header of a tune or file, users can specify

I:abc-pitch sounding | concert | written

which will then be considered the ("default") <coding mode> for the shortened syntax

I:instrument <note>

or (as a voice parameter)

instrument=<note>

This syntax is not allowed if no "I:abc-pitch" statement currently applies.

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.

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.

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:

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" qualifiers, 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

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.

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.

My name is Alexander Scheutzow, I am a professional software architect and developer, also the author of the abc tool MidiZyx2abc and of the more widely known MIDI software MidiCond ( http://www.midicond.de/ ).

Suggestions for improvements are welcome in the forum http://tech.groups.yahoo.com/group/abcusers/ - 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:

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 "Instrument-oriented" syntax as a shorthand (not as a separate independent mechanism!) [NEW in version 2]
5. 13.2.6 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)
6. 13.2.7 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
7. 13.2.8 Invariant transposition - is it desired?
8. 13.3 Overall transposition - is it desired?
9. 13.4 Transposition of chord symbols - correct algorithm? Keyword? Do we need a new formal syntax for chord symbols?

New in this version:

1. 13.2.5 Instrument-oriented shorthand, including "instrument=" and "I:abc-pitch"

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" or "major/minor/diminished/augmented". In particular, the addition with any "overall transposition" is easiest to calculate.

There has been a desire to describe transposition as close to the usual instrument name (e.g. "clarinet in Bb") as possible. In abc syntax, names like "Bb" are used in key signatures and chord symbols, where the octave is disregarded. For our topic, we need the octave as well, for which systems have been suggested in which "Bb-1" stands for the (usual) tenor sax transposition; I believe that abc users prefer "_B," - always specifying the sounding note that corresponds to the displayed (lower-case!) c.

More importantly, there are proposals that this should define a separate mechanism, independent of the two "shift-…" statements. We already have other independent mechanisms that amount to code being transposed, such as "octave=" and the "+|-8" suffix for clefs and ottavas. But these are very clear-cut in their semantics, whereas the two layers discussed here are not really distinct in their meanings.

(Chris seems to imagine the "low level" statements rather in the vicinity of my "transpose_all". I do not see why they are needed there, but I do see a need for them that is closely related to transposing instruments, and interferes with their semantics. Bagpipe music is a good example.)

One of the grave problems is illustrated by the following example (using my above syntax):

I:concert-score
V:clar instrument=_B;sounding
cde [I:shift-sound -1 dia -1] cde

All of us agree that such usage, mixing layers, is generally ill-advised. In my opinion this means that the above mapping suffices, no two independent mechanisms are needed at all.

What is worse: in the "independent layers model", what would users expect to find in the concert score?

1. Some may say: "I said 'sounding', so I want to see exactly what I typed in, regardless of the 'shift-sound' coming from an independent mechanism." - cde cde
2. Others may say (with slightly better justification) "A concert score should always represent the final sound." - cde B^c^d

In my model there can be no doubt, since "shift-sound" is defined to override the sound part from the "shift=". (Bad usage in any case, as I said.)

An unambiguous correct usage (in case the meaning was "switch to the A clarinet") would be:

I:concert-score
V:clar instrument=_B;sounding
cde [I:instrument A sounding] B^c^d

or, if the user insists on coding the second part neither at concert nor at written pitch:

I:concert-score
V:clar
[I:shift-score _B to c] cde [I:shift-sound c to B] cde

For the general case (neither "concert" nor "written" coding), I cannot think of an "instrument-oriented" syntax that is equally safe and more intuitive than the note-to-note syntax in the last example. It would have to be a single statement saying something like "this is for clarinet in Bb, but coded a minor third higher than sounding, resp a minor second higher than written" (since it was formerly meant for clarinet in A). It must be a single complete I:instrument directive that overrides both "shift_…" parameters. If such a syntax finds a majority, it can be incorporated.

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.

It is a tempting idea to let "instrument=" operate on a basic parameter (dots↔sound) instead of being derived. The other independent parameter can be

• code↔dots (Dave) or
• depending on whether "written" or "sounding" is specified, viewed as a code transposition similar to octave= (Hudson).

Both models have their charms, for users who are comfortable with the dots↔sound way of thinking, particularly the "instrument=" syntax. But the others will miss out, particularly with Hudson's model. Dave's model has the drawback that two commands are needed if the user wants to code as sounding; defining a "shorthand" for it (or, much worse, a global "mode") would again blur the concept considerably.

In Chris's v9 proposal, there is one mechanism based on code→dots and code→sound, and another independent one for "instrument=". Both mechanisms are voice-related and thus to be used in the "transposing instrument" context. The problem is that if both are used in conjunction, the assertions of "instrument=" (such as "this is coded as sounding" or "this will sound a minor third below the dots") can become untrue. If however we say they must not be used in conjunction at all, the above single mechanism behaves exactly the same.

A special aspect of the same problem is the concert score: it must react to both mechanisms, which may look pretty intransparent.

Some have asked for an additional voice-related command like "I:rewrite_for Eb-1", to change the existing instrumentation. It would amount to yet another transposition layer, effective on the dots but starting with the sounding notes (similar to the transformation used for the concert score, which would in principle correspond to "I:rewrite_for C".) This is possible, but my arguments against it are the following:

1. It adds complexity and reduces readability.
2. Like the concert score, it may involve clef issues, so that people may want yet another directive "I:clef_rewrite …", e.g. "I:clef_rewrite treble" when reassigning a bassoon voice (that uses the tenor clef passage-wise) to a baritone saxophone. Or even "[I:clef_rewrite Eb-1 treble][I:clef_rewrite C tenor]"… to cater for various anticipated re-instrumentations - not exactly simple.
3. Changing the instrumentation of a tune coded "as written" can be viewed as creating a different arrangement, for which simultaneous administration is not required. Software may offer such functions in abc2abc style, allowing for manual post-editing such as fixing the clefs and ottavas. And of course, if we have an "ifdef mechanism", people can prepare their scores for as many use cases as they want - they may not always be happy with it, though. In contrast, the concert score and shared staves are felt to leave the piece essentially unchanged, therefore they deserve that special support.

(As for "overall transposition", it is somewhere in between. The points in favour of its support are:
a) the use case is very common, much more so than re-instrumentation,
b) if it were absent, as in Chris's proposals until v9, people would be tempted to abuse our voice-related transposition directives, creating chaos if these are simultaneously used for their proper purposes,
c) we need not offer modifications of clefs and ottavas here, since the intended usage is "one-off" transposition by a small interval, unknown in advance, to suit a particular singer. See my "Clefs" proposal text.)

Some users would like to have the "instrument=" syntax available even if coding neither as written nor as sounding. This is why Chris introduced an independent voice-related mechanism, which unfortunately has the serious drawbacks mentioned above. The most severe drawback is that he allows "transpose-score" to differ from "transpose-sound", on top of an "instrument=". If only "transpose-both" were allowed in the independent mechanism, at least the dots↔sound relation would be preserved (i.e. reserved to a single mechanism/level).

To make the attribute "written/sound" seem correct as well, we can use "Hudson's trick": we define it to refer to the the result after that "transpose-both", as with the existing modifications "octave=", and +-8 from clefs and ottavas. Since these are all considered code modifiers, we may christen the new parameter "code-shift".

Those of us who do not think "instrument-oriented" (in Chris's coinage) will still want their "shift-score" etc.

Thus, the following model may be very attractive:

1. All the above stays as it is (including the definition of the concert score and the separate overall transposition).
2. An additional independent voice-oriented mechanism is introduced, with a single parameter "code-shift", which takes the role of Chris's "transpose-both" when used in conjunction with "instrument=".

The fans of all models can be reasonably happy with this one.

Currently I have the feeling that the "pragmatism" is a) required, including the bias, and b) too restricted if it relies on printed key signatures only. Here is a tentative replacement for the above paragraph 13.2.7. Its voice-related flexibility allows users to avoid unwanted orthography efficiently without cluttering the sheet music with signature changes.

The exact syntax is not important here, I used a "prag" modifier for added clarity - a matter of taste.

Comments are welcome.

For tunes that basically stay within one key, it often suffices to specify a transposition by its <number of semitones>, because there is a single reasonable "dia" value. In other cases users may want the "dia" value to change in mid-tune, in other words an enharmonic switch, to avoid remote keys and accidentals.

A "pragmetic" transposition directive is given either by the bare <number of semitones> syntax, or by an arbitrary transposition directive (e.g. note-to-note) with appended "prag" modifyer.

13.2.7.1 What is the T-key?

These transposition directives will find the appropriate "dia" value at the beginning of each voice, and recalculate it at every change of key. The key by which this is done may or may not be the key defined by the key signature. Users are allowed to specify this key separately, voice-related or of control scope. We call it the (current) T-key; it is determined by

1. the voice-related voice parameter "tkey=<key>",
2. or, if its value is "tkey=ckey" (as by default), the control-scoped voice parameter "ckey=<key>",
3. or, if the value of the latter is "ckey=key" (as by default), the staff-related ordinary key signature, disregarding any explicit accidentals in it; in case of "K:none", C major is used.

These are three independent parameters; for example, a change of key signature only affects the key internally used if both "tkey=ckey" and "ckey=key" are currently active (which is usually advisable to ensure.) Like genuine key signatures, the tkey and ckey values must be specified in relation to the code of the voice in which they are encountered, i.e. equally transposed. In the case of "ckey=", the state of the control voice applies.

Note that "tkey=" or "ckey=" never induce a printed key signature change - an enharmonic switch may well affect the accidentals at the individual notes.

Of the T-key only the basic signature accidentals are relevant.

13.2.7.2 Bias

The straightforward idea is to determine the "dia" value so that the key to which the T-key is mapped is most comfortable to play among its enharmonically equivalent partners. Usually this means the least number of signature accidentals, but some players prefer e.g. C# major to Db major. To signal such a bias, append a number of sharps or flats to the "prag" modifyer: "prag^2", "prag^1" = "prag^", "prag_" = "prag_1", "prag_2".

The "effective T-key" is calculated from the current T-key by subtracting the bias accidentals (where each flat counts -1 sharps and vice versa).

13.2.7.3 Comfortable target key

The "dia" value is now chosen so that the key to which it maps the "effective T-key"

1. has less than six accidentals if possible;
2. if six are needed, and thus two candidates exist, the one is chosen that has the same type - flat or sharp - as the T-key (not the "effective" one!);
3. if the latter had no accidentals at all, sharp is assumed.

Important exception: for <number of semitones> values 0 or multiples of 12, a pragmatic algorithm must not touch any accidentals, i.e. is always equivalent to "x*12 dia x*7", even if the T-key is, say, C# major. This ensures that "the default is 0" makes sense.

13.2.7.4 Example

My T-key is C major (or A minor etc.) and my transposition is "+1 prag^". The effective T-key is thus F major, "subtracting one sharp from C major". One semitone up from F major is either F# major ("dia" value 0) or Gb major ("dia" value 1), each having six accidentals. If F major were the genuine T-key, Gb major would be of the same sharp/flat type, so that "dia 1" would apply, taking C major to Db major.

But the sharp/flat type is in fact taken from the original T-key, which has no accidental at all, thus sharp is assumed, resulting in "dia" 0, our desired key of C# major.