Voice parameters have the general syntax "keyword=value". The ones that concern us here, may occur interchangeably inside V: or K: fields (the latter only for practical reasons), separated from the other syntax elements by space characters. You can even use K: fields that do not specify a key signature, with the syntax [K:keyword=value] or [K:keyword1=value1 keyword2=value2 …].

The order in which voice parameters occur within a single field is strictly irrelevant; any conflict among them must result in a severe error message. Different voice parameters may have different scopes.

A fundamental voice parameter keyword is stafflines=, whose value is the number of lines in the staff. Legal values are 0 to 9, the default is 5. Obviously its scope is "staff-related". If the value changes at a position where no score line break is immanent, the display software may defer the change to the next such line break.

The staff lines are numbered from a (possibly "invisible") bottom line upwards. Depending on the stafflines value, the lines with the following numbering will be visible only:

The reason for this is to cater for legacy usage, identifying the "middle" line with line number 3.

Clef information is normally provided by the voice parameter keyword "clef=<clef value>". The syntax "<clef-value>" (without the "clef=" prefix) is also permitted, except for the case "clef=none". In some situations, mostly deprecated, the clef parameter can be supplemented by "middle=<middle note>"

Typical examples:

V:cello clef=bass
…[K:tenor]…
V:violin clef=treble1 % "French violin clef" sitting on the bottom line, thus the note d comes on the middle line.
V:violin clef=none middle=d % the same effect, but without displaying any clef
V:doublebass clef=bass-8i % meant one octave lower, but visually indistinguishable

A middle= parameter is only allowed in connection with an explicit <clef value> in the same field.

An alternate syntax, as a separate field, is

I:clef <clef value> [middle=<middle note>]

(where <…> denotes a value, […] denotes an optional part, and | separates alternative values).

Since there will be other clef keywords of this syntax, which are not allowed as voice parameters, the syntax will be explained in this alternate form. The voice parameters will be considered mapped in the obvious way, to an imaginary I: field following or preceding, respectively, the existing V: or K: field.

Example:

V:violin clef=none middle=d name="Vl."
… [K:G treble] …

is equivalently mapped to

V:violin name="Vl."
I:clef none middle=d
… [I:clef treble][K:G] … % actually the order should not be relevant here

The syntax of the I: fields concerned with clefs is:

I:<clef keyword> <clef name>[<line number>][+8|-8|+15|-15[s|n][i]] [middle=<middle note>]

(where <…> denotes a value, […] denotes an optional part, and | separates alternative values).

All these fields are (formally) of "staff-related scope".

<clef keyword>
is principally "clef". Other keywords, to be explained later, are "clef_concert", "clef_shared", and "clef_shared_concert".

<clef name>
may be treble, soprano, alto, tenor, bass, perc, none, or auto. "perc" selects the drum clef. The default value is "auto", which causes the display software to choose and switch between treble and bass clef freely, as it deems best.

[<line number>]
indicates on which staff line the base clef is anchored. Different values constitute different clefs, e.g. "bass2" is elsewhere known as the baritone clef, and "alto4" equals "tenor".

• Values (unsigned) 0 to 9 are formally allowed, even if referring to an "invisible" line, as inevitable in the case stafflines=0. *)
• Defaults are: treble: 2; soprano: 1; alto: 3; tenor: 4; bass: 4, perc: 3. These defaults make the clefs behave as their names indicate.
• Cannot be used in conjunction with middle= in a single field, except for the <clef name> "perc".
• Cannot be used with the <clef name> "none" (use middle= in that case) or "auto".

[middle=<middle note>]

• Cannot be used with the <clef name> "auto".
• Cannot be used in conjunction with <line number> in a single field, except for the <clef name> "perc".
• For <clef name> "none", an arbitrary <middle note> can be specified, to appear on line 3. Default is B.
• For <clef name> "perc", an arbitrary <middle note> can be specified, to appear on the line of given <line number>, or on line 3 by default. Default value is C. [The percussion topic is currently VOLATILE / TODO.]

Example:

I:clef perc4 middle=F, % F, will appear on line 4

[middle=<middle note>] for mainstream clefs (deprecated)
For clef values other than "auto", "perc", and "none", middle=<middle note> is an alternate way to define the line number of the clef, now strongly deprecated. It is mechanically mapped to <line number> according to the following scheme, regardless of the "stafflines" value *), regardless of any +8 etc. postfices, regardless of transposition:

Values differing from these by one or more octaves are permitted for legacy reasons, though strongly deprecated. The number of octaves, call it n, is then mapped to a separate directive [I:shift-score -12*n], see "Transposition" below. For example, deprecated [K:clef=bass middle=f] is equivalent to [I:clef bass3][I:shift-score -24].

If no middle= is specified, the <line number> defaults apply.

[+8 | -8 | +15 | -15] ("Octave clefs")
denotes the basic clef with a little '8' or '15' drawn above or below it, the result being viewed as a different clef. We call such a clef an octave clef, and the little number its affix.

• Can only be used with the <clef name>s "treble" or "bass".
• The postfix [s|n] determines whether the sound and meaning of the abc notes is shifted by an octave ("s", the default), or not ("n"). In the latter case, the clef behaves like any non-octave clef, affecting only the display.
• The default value "s" is an additional feature of these clefs, designed for persons who view the situation in analogy to octave-transposing instruments. In particular, it allows users to copy existing sheet music by typing the note names as if there were no affix. This feature only affects the notes of the current voice until the next clef change there, i.e. it constitutes a separate voice-related directive, whereas the clef itself is always of staff-related scope. With the "clef_…" keywords, the [s|n] postfix has no effect at all. (See the example below, and the paragraph "4.6.7 Further explanation …".)
• The postfix [i] makes the affix invisible in the display, with otherwise unchanged behaviour. This is intended for special cases, such as the "traditional French horn bass clef" bass+8i used passagewise. (Usage for double bass voices etc. is possible, but requires particular care; normally the treatment as octave-"transposing instruments" is to be preferred, see "Transposition" below.)
• If this clef is used together with the deprecated "middle=" voice attribute, the user must not specify the intended (sounding) note, but the one that would be apply to the treble or bass clef on the same line; see above.

*) Software unable to support some valid stafflines/clef/line-number/middle combination, should apply its best approximation that yields equal pitches, and issue a warning message.

Example for the [s|n] option: The lowest note of a soprano recorder has the sound c. Either of the following lines will produce it equivalently, with the typical clef:

[V:sop_rec clef=treble+8n] c8 |] % lower-case c as sounding
[V:sop_rec clef=treble+8n octave=+1] C8 |]
[V:sop_rec clef=treble+8n] [I:octave +1] C8 |] % best way to make clear that "octave" has nothing to do with "clef"
[V:sop_rec clef=treble+8] C8 |] % the "s" is usually omitted

In practice, an abc score will often be used for more than one type of printed score: Full score, single voice part, concert score, condensed score etc., switched frequently. (Readers who do not have such desires may skip this paragraph with its subparagraphs.)

Different clef settings may be required for these various use cases, including clef changes at different positions during the course of a voice. It would be tedious to change all clef directives whenever printing a type of score differing from the one printed previously.

It is much more convenient to switch between these use cases by simply editing the statements "I:score" or "I:concert_score", usually found in the header.

Therefore, new clef keywords are introduced to cater for the various use case in advance, to be used only when need arises. The principal the values of "I:clef" apply by default. Users who do not anticipate more than one type of printing, can use "I:clef" for it.

With each keyword we will associate

• a use case (such as concert score),
• another clef keyword as "default keyword"
• one or more clef keywords as possible "fallback keywords".

The general mechanism for a given keyword is the following:

1. If the use case is not effective, the fields of that keyword are ignored.
2. If the use case is effective, but the keyword has not been encountered yet in a particular voice, the values of the "default keyword" apply.
3. If the use case is effective, and the keyword is encountered specifying for value the name of one of the fallback keywords, the current value of that fallback keyword is used, until the given keyword occurs again; example: [I:clef_concert_shared clef_shared].
4. All other clef keywords are ignored.
5. If "auto" is the current value of a keyword serving as default or fallback, software must recalculate the effective clef.

All clef changes induced by these mechanisms must leave the sounding pitches unchanged, notably if some octave clef is involved. Therefore, a postfix [s|n] does not make any difference for these keywords.

Although I:score and I:concert_score rarely occur outside of tune headers, they are "control types". If their value changes in the course of a tune, software must revaluate clefs and insert clef changes wherever necessary.

The value "true" of the field "I:concert_score" [NEW/TODO], see "Transposition" below, constitutes the use case for the keyword I:clef_concert.

Different clefs in the concert score are typically required for instruments with large transposition intervals such as used for tenor saxophones, piccolo flutes, double basses etc.

Typical examples:

V:bass_clarinet clef=treble transpose=-14
[I:clef_concert bass]

V:doublebass clef=bass transpose=-12
[I:clef_concert bass-8] % produces equal sheet music, except for a little '8' printed below the clef

The default keyword for clef_concert, and the only possible fallback keyword, is "clef". (Those who prefer "auto" as the default, even for viola voices etc., can simply write

I:clef_concert auto

into the tune header, which by convention applies for all voices.)

Often two or more voices are designed to be printed individually, but must share a staff in the score, as decreed by "I:score". This is the use case for the keywords I:clef_shared or I:clef_shared_concert, depending on whether "I:concert_score true" applies.

These keywords will only be effective in the master voice of a staff that is shared with at least one other voice.

The default keyword of "I:clef_shared" is "I:clef", which is also its only possible fallback keyword.

The default keyword of "I:clef_shared_concert" is "I:clef_concert"; its possible fallback keywords are "I:clef", "I:clef_concert", and "I:clef_shared". The fallback/default mechanism may apply in multiple steps, the last fallback being "auto".

Typical example, a choir piece; the tenor part transforms correctly by the "law of conservation of intended pitch":

I:score (soprano alto) | (tenor bass)
…
V:tenor clef=treble-8 % or treble-8n
[I:clef_shared bass]

As another example, consider two bassoon voices sharing a staff

I:score (bsn1 bsn2)
V:bsn1 clef=bass
… [I:clef tenor][I:clef_shared bass] … [I:clef bass][I:clef_shared clef] …

"I:suppress-subsequent-clefs true|false", if of value "true", causes clefs to be printed only at their installation, not at the beginning of every staff. It is a staff-related type. The default value is "false".

[TODO, somewhere else: "I:suppress-subsequent-key-signatures" does the same with key signatures, also staff-related.]

An important item of notation concerns passages written in a different octave, to save ledger lines. Such a passage is marked by a dashed line starting with something like "8va".

This is not just a decoration, but has much in common with octave clefs such as treble+8. Therefore, its standard abc syntax is a field, usually inline:

I:<ottava-keyword> <number of octaves>[s|n] ["<text>" ["<loco text>"]]

These are voice-related types, in contrast to clefs.

<ottava-keyword>
is principally "ottava". Additional keywords are "ottava_concert", "ottava_shared", and "ottava_shared_concert", working like "clef_concert" etc., but completely independently of these, and voice-related. This includes a fallback syntax [I:ottava_shared_concert ottava_shared] etc.

<number of octaves>
A signed number from -2 to +2. The value 0 ends the passage. A positive value causes a dashed line above the staff, a negative one below the staff. Of course, 0 is the default.

[s|n]
(postfix), entirely analogous to the same postfix of octave clefs: "s" (the default) changes the sound and meaning of the abc notes in the current voice to a different octave, "n" preserves the intended meaning and only causes the display of the notes to be shifted in opposite direction. Either effect is added independently to all other transposition mechanisms, and ends at the next ottava statement. Note that the postfix does not make any difference in cases of derived "ottava_…" keywords, since these must never change the sound of any notes. See "4.6.7 Further explanation" below.

["<text>"]
An arbitrary text, to be displayed at the beginning of the dashed line. Defaults are "8va" (for +/-1) and "15ma" (for +/-2). Display software should follow the typographic conventions, including superscripting "va" and "ma".

["<loco text>"]
An arbitrary text, to be displayed at the beginning of the dashed "loco" line (see below), if any. Default is "loco" (Italian for "place", or Latin for "in place"). An empty string "" (in contrast to an omitted <loco text>) will cause the dashed line to be suppressed as well.

Since these items are voice-related, different values are allowed in the same passage on the same staff, but in different voices. Software will print each voice as requested, but no more than one dashed line can be specified on either side of the staff. Therefore, it is preferable to synchronize the effective "ottava_shared" values in all voices that may share a staff. If this is found failing for some passage, software must react as follows:

• If all voices have ottavas in the same direction, the <text> for the first relevant voice (in order of declaration) is used with its dashed line; <loco text>s are ignored.
• If some, but not all, voices have ottavas, which all go in the same direction, the <text> for the first such voice (in order of declaration) is used with its dashed line. Now the <loco text> of the first voice (regardless of its ottava value) that currently specifies it will be considered; "loco" if no such voice is found. If that text is nonempty (i.e. not ""), on the opposite side another dashed line will appear, with that tag.
• If ottavas are found in both directions, at either side of the staff a dashed line will be displayed, using the <text> for the first relevant voice (in order of declaration); <loco text>s are ignored.

This rule is applied freshly whenever a new ottava directive is encountered, so that <text>s or <loco text>s may become effective at a later position. It is the user's responsibility to ensure that the reader can identify the octave of every note. The <text> and <loco text> values can be used to clarify possible ambiguities.

Examples:

[I:ottava_shared +1 "8va (1st only)" "loco (2nd and 3rd)"]
[I:ottava_shared +1 "8va (1st only)" ""] % no "loco" line found necessary
[I:ottava_shared 0 "" "3rd flute loco"]

Note: it is obviously pointless to write "loco" for a passage that contains no notes. Software may suppress the "loco" line in that case, but is not obliged to do so; users are advised to insert suitable ottava_shared directives.

For users who value brevity, alternate spellings for some ottava statements are being offered. These are mapped mechanically to I: fields as follows:

!8va(! is equivalent to [I:ottava +1s],
!8vb(! is equivalent to [I:ottava -1s] ("ottava bassa"),
!15ma(! is equivalent to [I:ottava +2s],
!15mb(! is equivalent to [I:ottava -2s],
the same with ")" instead of "(" are all equivalent to [I:ottava 0].

Users are recommended, but not obliged, to use matching couples.

This modifier occurs at octave clefs and at ottava statements, and is also the default if no "n" postfix is present there. To define the induced behaviour, we can imagine two additional variables "octaveC=" and "octaveO=", exactly equal to "octave=" in their scope (not staff-related!) and effect, but all three administered independently and adding their effects.

Then, such an octave clef delaration will be considered as split in two statements:
a) the corresponding "n" statement (staff-related)
b) plus octaveC=-|+1|2 (voice-related).

Analogously, such an ottava directive will be mapped to
a) the corresponding "n" statement
b) plus octaveO=-|+1|2 (both voice-related).

Any other clef change will be considered ornated with octaveC=0, any other ottava with octaveO=0.

The values of octaveC and octaveO represent the user's wish about the notes effective in the voice, so they must remain in force if a different clef or ottava is imposed on the voice by any of the above mechanisms. Conversely, if an octave clef or ottava causes such a change, its "s" capacity is ignored.

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.

The list items are numbered for better reference, the final version may use bullets or other forms of organization.

The demand for an I:concert_score is taken as a well-established hypothesis, regardless of the eventual transposition facilities beyond "transpose=".

A major premise of this proposal is that changing the value of "I:concert_score" and/or the parentheses in "I:score" will never change the perceived meaning of any note. Users will be enabled to prepare their code so that they only need to switch those two header lines to obtain

• individual voice parts
• a full score
• a "condensed" score, in which some voices share their staves
• a concert score
• a "condensed" concert score

with well-chosen clefs and ottava passages. (Users of formatting instructions, e.g. %%newpage, will not be served by these "one-off" mechanisms; they must continue to use tools like abcpp. Clefs and ottavas differ from those by the fact that their proper choice is indispensible for legible sheet music.)

The condensed score is at least as important as the concert score. Note that the "…_shared" syntax is usually designed with a particular way of sharing/condensing in mind; users who change the parentheses of their "I:score" may have to reconsider their "…_shared" items.

The third "one-off mechanism" is "one-off transposition" of the whole piece. The above proposal does not offer a separate administration of clefs and ottavas for this operation, since

• typically only small intervals are involved, adding no more than one ledger line;
• the exact interval can normally not be planned in advance (depending on singers' health etc.).

The problem with stafflines=0 is how to establish "line numbers" for clef, middle, etc. abc2ps has a solution for the stafflines problem that I would not exactly call beautiful, but which works and is probably being used. The point is that the line numbering does not count the visible lines from 1, but includes "invisible lines".

This current version reflects the behaviour of abc2ps in the question of line numbering. If anyone knows conflicting software or usages, please shout.

The following items and features are newly introduced here as hypotheses, with respect to the current standard 2.1.

1. 4.6.2: alternate syntax I:clef
2. 4.6.3: value "clef=auto" (following Jef)
3. 4.6.3: value "clef=soprano" (NEW in version 9)
4. 4.6.3: middle= limited to reasonable usage, the octave component mapped differently, here with a "shift-score" hypotbesis, to be adjusted with the final transposition mechanism
5. 4.6.3: clef affix "15" added, following most modern notation software (NEW in version 8)
6. 4.6.3: postfix n for "well-behaved" octave clefs (the default is introduced as "s" for better reference)
7. 4.6.3: postfix i for octave clefs with invisible affix (the former postfix v for "visible" has been dropped in version 8)
8. 4.6.4: "I:concert_score" tentatively imagined to be defined elsewhere in the standard document; symbolizing the principal facility of a (temporary) concert score
9. 4.6.4: "I:clef_concert"
10. 4.6.4: "I:clef_shared" and "I:clef_shared_concert"
11. 4.6.5: "I:suppress-subsequent-clefs"
12. 4.6.6: "I:ottava" and ottava_shared etc.
13. 4.6.6.2: alternate spellings !8va(! etc. (NEW in version 8)

Feel free to criticize each point, preferably specifying your preferred solution, or your challenge of a particular one of my assumptions and diagnoses.

from one of my messages to the abcusers forum, to my best knowledge representing a general consensus:

1. The abc standard defines a way to communicate music in its essence, not in typesetting details.
2. Clefs and ottava settings are considered parts of that essence in a wider sense, which means that the author must be able, but not forced, to control them completely - see remark below.
3. Concert scores and shared staves should be supported "one-off", which implies an administration of deviating clef and ottava settings.
4. The third "one-off" operation is overall transposition, typically by small intervals; deviating clef and ottava settings will not be administered.
5. abc is about standard ("western") music notation, which deals with *notes* and some symbols. Notes are abstract objects like "sounding _A,," plus a note value such as "eighth". Their mapping to actual sound is culture and context dependent, guided by conventions, "stylistic feeling", improvisation, and the composer's comments. Some genres tend to ignore some aspects of notation and add other distinctions. In the standard, playback software is only viewed as a tool to control acoustically those "notes intended to sound". (Actual playback software may try to be more "intelligent".)

Most of this is a logical consequence of existing abc, the rest follows from the consensual parts of our discussions about transposition.

All programmes *must* have the same understanding of the "essence", unless defined to the contrary (e.g. "clef=auto"). Proprietory language elements should ideally be syntactically distinguishable, and safe to ignore. (Remember those chaotic web pages saying "Optimized for Internet Explorer 3.0"? That is the opposite of a standard.)

Remark about item 2.: This is particularly necessary because abc does not know about conventions typical for various instruments. But in fact these items often convey an "essential" message from the composer, beyond those conventions. The simplest example is striving to avoid clef or ottava changes in the midst of a musical phrase. Of course, there is also an aspect of the printer's or player's personal taste. Softwere automatisms in the sense of "clef=auto" are welcome as *options*. The respective commands might become more sophisticated later, e.g. "clef=auto:bass;tenor" or even "clef=auto:bass:3;tenor:2".

If anybody challenges those premises, please specify which one, and what other principle you would prefer to apply.