The notion "abc item" describes one of the following:

1. a field, disregarding any voice parameters (e.g. in "K:C clef=bass", the "clef=bass" part is considered a different item)
2. a voice parameter (each one individually, e.g. "clef=bass")
3. an ordinary note or grace note, decoration, annotation, bar line, chord symbol etc.

Each item belongs to a type (also called item type), which is one of the following:

1. an I: field, distinguished by its keyword after I:
2. a non-I: field, distinguished only by its field letter (left of the ":")
3. a voice parameter, distinguished by its keyword (left of the "=")
4. "note", "decoration", "annotation", "chord symbol", etc.

Each type has one of the following six scopes:

1. header-only
2. movement separator (currently only one type, T: field in the body)
3. movement property (currently only one type, W: field)
4. control
5. staff-related
6. voice-related

The last three are collectively called stream scope.

If for any item type no scope is specified in this document, voice-related applies.

Fields of type T:, if encountered in the tune body, have grave consequences beyond typesetting. They split the code of the tune body into disjoint parts, technically called movements here (which may or may not coincide with their musical meaning). Voices, as characterized by their voice IDs, can run through several movements, affected by the separator only in one respect: Their metric positions (see next paragraph) are considered "synchronized" there, i.e. set to an equal value.

Each movement can contain its own selection of voices.

The first movement of every tune starts behind the tune header.

The metric position of an abc item is defined within a movement as the sum of the note values of single notes, chords, or rests preceding it in the current voice and movement. Bar lines, fermatas, etc. are irrelevant. (If bar/beat numbers are needed, they can only be derived from the control voice, see below. If a position within the whole tune is required, the lengths of the longest voices of the preceding movement are added.)

Two abc items are called synchronous if they belong to the same movement, and their metric positions coincide. Software must display such items on the same vertical line, resp. play them simultaneously. Repeat signs of bar-line type, volta signs, and P: fields are disregarded for these definitions.

In fact, playback software is allowed to run out of synchronousness if non-synchronous repeats are decreed at the user's responsibility - see below -, but not for other reasons such as non-synchronous fermata signs. (Any inconsistendies of repeat signs and P: fields should of course be treated as syntax errors.)

Fields of (upper-case) W: type will be collected per movement in given order, but disregarding any voice context. The W: lines will be typeset at the end of each movement.

In a movement of a multi-voice tune, the items preceding its first V: field constitute the "movement header", which is considered outside any voice. It must not contain any notes or rests. All other items are permitted, and will have the same effect as if they were copied into each voice occurring in this movement. More precisely, it has the same effect as

[V:firstvoice]mvt.header[V:secondvoice]mvt.header …

Typical candidates for this header are K: and M: fields.

The ranges of ordinary repeat signs do not transcend their movements. Example:

T:First movement
abc |]
T:Second movement
def :| % player software must only repeat the last three notes.

The "name=" attribute of a voice can be changed per movement; display software will normally print it at the beginning of each movement:

T:First movement
V:clr name="Clarinet in Bb"
…
T:Second movement
V:clr name="Clarinet in A"
…

In principle, any stream-scoped item found in the body belongs to one well-defined voice (see below for a formal exception). If it has a meaning "from here on …" (e.g. an L: field), it ceases to apply at the next V: field, but resumes its validity at the next V: of its own voice, unless/until revoked in the same voice.

Revoking is done by an item of equal type and keyword/letter, but different value. The previous value is always overridden, never added to etc. Items of some types also override the values of different types, as mentioned in their definitions.

Stream-scoped fields can also be used in the tune (or file) header, some of them are even required there, M:, L:, and K:. They are considered as if they were added at the beginning of each voice of the tune, following its first V: field, but logically preceding any voice parameters in it (which simply means that these voice parameters may be able to override the header specifications).

Note that movement limits (T: fields) do not bar any of these mechanisms in any way. In particular, if a voice ID was already used in the previous movement, it would be a mistake to assume that anything was reset from the tune header.

In the following paragraphs, we use an ordering of the voices occuring in a movement, called "order of declaration". It is determined by the first occurrence in the movement of a V: field of the respecive voice.

(Note that a voice ID may have occured before its declaration, not only in other movements, but also e.g. in an "I:score" directive, where the ordering has a different significance and can therefore not be used for the purposes of this chapter.)

The following types are defined as control types (short for "metric-position-related types"); items of such a type, called control items, apply to all voices simultaneously at the given metric position:

1. fields P: and Q:
2. all types that induce line breaks in the typesetting:
3. the ordinary line break directive (e.g. $, depending on the value of I:linebreak)
4. I:text
   1. I:score and I:staves
   2. … [TODO]
5. annotations prefixed ~, to appear above the top staff of the system [NEW, please discuss]
6. the following I: fields:
   1. I:concert-score [TODO]
   2. … [TODO]

Other than some may expect, M:, K:, repeat signs (see below), bar lines, and fermatas are not control types; they are allowed to differ between staves resp. voices, though they rarely will.

Control items are not allowed everywhere in the code. The main reason for this is to detect mistyped or miscalculated code; a welcome side effect is that reading becomes slightly easier for humans and software. Therefore, a control item found at a disallowed point is considered a non-fatal error; software must not obey it and should issue a severe error message.

A text position in the abc code between two abc items is called an "in synch" point, if all voices that occur anywhere in the current movement have accumulated the same note lengths. In other words, if for each such voice a note were inserted here, their metric positions would be equal. Every movement header is "in synch", by definition.

Control items are always allowed at in-synch points. This is the preferred place for lengthy fields (non-inlined), or for items that mark a new section of the tune. This conforms to a tradition that treats P: and some I: fields as if they were outside all voices, like T:.

For example, the following usage, occasionally found in legacy, is still correct:

X:1
T:Short Symphony
M:4/4
L:1/4
K:C
%
P:1 % movement header
V:flute % the control voice
cdef |]
V:whistle
ABcd |]
%
P:2 % formally in the non-control voice "whistle", but in synch
% (if a K: field appeared here, it would only apply to "whistle", other than a movement header) I:score (flute whistle) % formally in the non-control voice "whistle", but in synch
V:flute
gabc' |]
V:whistle
efga |]

An example using a type which is normally inlined:

I:linebreak $
…
$
[V:1] abc
[V:2] ABC
$
…

1. A voice whose first V: in a movement carries the voice parameter "control", has the role of control voice in that movement; Example: [V:flute control clef=treble]. Other positions, or more than one such parameter in a movement, are illegal.
2. If there is no such voice parameter in a movement, the first voice in order of declaration is considered its control voice.
3. Control items are allowed outside the control voice only if they are either at an in-synch point (see above), or if there is an exactly equal item in the control voice at the same metric position.
4. For good legibility and check of consistency, users should insert control items (that are not at in-synch points) not only to the control voice, but to all voices, at the same metric position, unless they have good reasons to the contrary.
   • If they fail to do this, and in a non-control voice a control item is missing, whose position there is bridged by a single note or rest, software must issue an error message, even if it can repair the damage. (Users must split such a note or rest in two, at the desired position, tying the notes.)
5. If the control voice is currently excluded from the score, the control items in it must still be obeyed. In other words, to extract voices from a score, it does not suffice to collect the items belonging to the respective voice. Rather, software must collect the header, T:, and W: fields, plus all items with their correct metric positions that are
   • either control items in the control voice
   • or non-control items in the voice(s) being extracted (check for consistency of control items at equal metric positions)
   • or control items at in-synch points of the code.
6. Another role of the control voice is bar numbering, according to the bar lines found in it. If it is metrically shorter than the longest voice of the movement (- strongly discouraged -), the numbering for the remainder of the movement is undefined.

The following types of items are defined as staff-related types, an item of such a type is called a staff-related item:

1. all types of bar line, including repeat signs
2. M: fields
3. the key signature part of a K: field (whereas voice parameters have scopes of their own)
4. the voice parameter "staffline="
5. all clef keywords, including the voice parameter "middle="
6. annotations prefixed +, to appear above the staff [NEW, please discuss]
7. annotations prefixed -, to appear below the staff [NEW, please discuss]
8. all annotations, decorations, or lyrics found in passages where [I:annotations_staffwise true], [I: decorations_staffwise true], resp. [I:lyrics_staffwise true] is in force. [I:…_staffwise false] returns to the default treatment. [NEW]
9. the following I: fields:
   • I:…_staffwise
   • [TODO]

(Note that 8va (ottava) fields are voice-related, see 4.6.)

The regulations about staff-related items are designed for the following goal: Users should be enabled to prepare a score for various printouts of distinct dispositions of voices onto staves, within reasonable limits. Ideally, for each of these printouts, it suffices to adapt the I:score/staves directives, including any parentheses for staff-sharing.

1. If several voices share a staff, one of them has the role of master voice.
2. The first V: field of any voice in a movement may carry the "master" voice parameter. Example: [V:cl master clef=treble].
3. For each movement, an ordering of its voices is considered that first has those carrying the "master" voice parameter, in order of declaration, then the other ones, also in order of declaration.
4. At the beginning of the movement, and at each I:score/staves directive inside it, the role of master voice per shered staff is assigned according to that ordering.

Of course, the idea of the master voice is that its staff-related items are respected.

1. Staff-related items in a non-master voice are perfectly legal (for the above reason), but must be ignored by all software.
2. Clef keywords are formally strictly staff-related, but allow alternative administrations for shared staves. See 4.6 for details.

The guiding principle for voices sharing staves is: If the user changes parentheses in an I:score statement, and nothing else in a tune, this must not change the intended sound of any note, as perceived by the viewer of the sheet music.

Voices that share a staff should have matching key signatures and bar lines. Clefs need not match; if a clef is imposed on a non-master voice, software must adjust the displayed notes to represent the original intended sound. See 4.6 for details.

If display software encounters two voices sharing a staff that do not match in staff-related matters other than clefs, it may perform the following adjustments (accompanied by a warning message saying that other software may not):

1. If a staff-related item is to be imposed, but its position is bridged by a single note or rest, normally split that note or rest in two, notes being tied. Some types do not require this, e.g. annotations and decorations.
2. If a key signature for display (i.e. possibly after transpositions) must be imposed, reproduce the effective accidentals at the notes, following the current rules, so that the intended sound remains unchanged. It must also reproduce any redundant ("courtesy") accidentals encountered. Example: if the master voice has "[K:C]", but the sharing voice has "[K:D]|CDC=F|=C", it will normally be displayed as if it were "[K:C]|^CDCF|C". Note that the last note does not get a "courtesy accidental", since the original accidental was not redundant.
3. Similarly, adjust the effects of imposed bar lines on (non-signature) accidentals.
4. Adjust overlay measures as if they were separate voices.

Whenever software it is unable to fulfill any of these rules in a particular case, it must issue a well-worded fatal error message, never display incorrect sheets. Differing key signatures must not be considered an error if there is no actual note to adjust, e.g. for the typical voice consisting only of chord symbols and invisible rests.

In contrast, software must not try to unify transposition when a staff is shared. Transposition is never staff-related; discrepancies in this respect are not necessarily errors. For example, in classical scores a double bass voice may share its staff with a 'cello voice at different octaves. As with "clefs with invisible 8 markings", it is always the user's responsibility to clarify the meaning to the viewer of the sheet music.

Items of the following types are formally staff-related, but normally required to be precisely synchronized in all voices:

1. repeat signs :|, |:, ::, :|:, and :||:
2. all volta signs, i.e. [1 etc.
3. the "decorations" !segno! !coda! !D.S.! !D.C.! !dacoda! !dacapo! !fine!

The header-only instruction "I:repeats_synchronized" causes software to check whether this is true, and to issue a helpful fatal error message otherwise. Software is also encouraged to offer a user-triggered mode or function to perform these checks on any abc code.

Volta signs and the decoarations mentioned will normally be displayed not on each staff of a score, but only once above the score, as with genuine control items, if they are synchronous in all voices. [TODO: in large scores, anything "above the score" is sometimes repeated above each group of staves.] Otherwise, display software may represent them either on each staff or summarize those that are equal. (Playback software must of course act per voice, whatever sense that may make to the user.)

Fermata signs are not pseudo control items, since they may appear slightly asynchronously in a polyphonic context.

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.

I have not included any chapter numbering yet, please refer to any of the above chapters by the abbreviation given in brackets. The list items should be bullets, but for better reference, I used numbers.

The whole scope concept is new for standard abc. Here a list of new items that my be discussed individually:

• MS - T: as movement separator [NEW since v4]
• MPT - W: printed below each movement (as done in abcm2ps) [NEW since v4; originally "movement footer type"; renamed in v7 to accomodate any future I: types concerned with subtitles, layout, or whatever, analogous to the "header-only" scope]
• MH - [NEW since v8]
• OC - voice names may change per movement (as done in abcm2ps) [NEW in v5]
• OV - ordering by V: (etc.) in the movement [NEW since v4, simplified in v8 due to the new "MH" concept]
• CT list - still to be completed. [NEW in v6: repeat signs no longer included]
• CT3 - new prefix for annotations, additional to ^ and _
• CT4 - I:concert-score
• CV - control voice movement-dependent [NEW since v4]
• CV - the control voice can also be specified explicitly by a voice parameter [NEW since v8]
• SRT6, 7 - new prefices for annotations, additional to ^ and _
• SRT8 - New mechanism to exclude non-master annotations, lyrics etc.
• MV - the master voices can also be specified explicitly by a voice parameter [NEW since v8]
• ANM - adjustments for shared staves, now optional except for clefs [NEW in v5, slight rewording in v7]
• PCT - a new category, formally staff-related [NEW in v6]

It would be possible, and compatible to abc 2.1., to make T: an ordinary control type, like P:. This document would be somewhat shorter, as were its previous versions.

The charm of movements is the new selection of voices, without worrying about formally filling them with rests for the preceding movements. A special synchronizing directive is not needed any more.

The idea of using T: fields for movement separators is somewhat arbitrary, in particular since Jef often uses it without an actual "title" string. But it can be accepted as de-facto legacy.

Because

1. the order in which the voices appear in it has a significance in it own, which would limit the user in selecting the most adequate control/master voices,
2. I:score is considered somewhat volatile, whereas the control and master voice roles are often assumed fixed by the author.

Because each movement can have its own set of voices, so there may not exist a single voice that occurs in all movements, let alone one that qualifies for the role everywhere.

That is in fact the idea. When this document describes what software must do, it is just a rhetorical device to explain what an abc item means, and what usage is safe (even if it may not be mainstream usage).

Well, we could, as does the abc standard document 2.1, but it is much better if the document

1. tells programmers exactly and completely what effect is expected to become compliant, so that they need not experiment with other software or study existing abc code (often amounting to guesswork),
2. tells users which usage is safe, so that their abc code is properly understood not only by the software they happen to possess, but also by all other compliant software as may be used by recipients of their code, or in the future by themselves.

Most standards written by humans, including MusicXML, actually fail this goal, and so will this one, but the closer we get, the more will our work be useful and respected, and the more effort will be invested by programmers.

We may want to add features in the future, which may rely on a particular style of abc coding. Users will be glad if we describe such a style as "orthodox", so that new features are most likely to work properly on otherwise unchanged code. A typical example is the concert score. Also, conversion tools from and to formats of slightly differing philosophies may have difficulties if our notions are unnecessarily vague.

An equally important reason is the logical consistency of the standard. Present and future regulations should be as self-evident as possible, or at least easy to understand and memorize correctly and completely. Thus, it is much better to say "T: starts a new movement" than just "At a T: field, software must resynchronize all voices". The notion "movement" is defined technically, so that users are free to map their own needs to it. (Actually, a more neutral wording such as "part of code" would be preferable, if it could not be confused with the P: mechanism.)

Because of legacy usage. In future versions, we may have more flexible mechanisms for tempi and everything related to repeating. These will probably use fresh keywords in I: syntax, since a natural extension of the current Q: and P: syntax is hard to imagine.