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

1. a field, disregarding any voice parameters (!)
2. a voice parameter (each one individually)
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 (only one type, T: field in the body)
3. movement footer (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 "synchronized", i.e. set to an equal value.

Each movement can contain its own selection of voices.

A tune without any T: in its body will be considered to consist of a single movement.

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 respective voice and movement. Bar lines 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 in each 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.

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 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, or of a stream-scoped item belonging to the voice that had been current prior to the T: field. (Users are recommended to redeclare the voice in such a case, unless ther is only one voice.)

Example: … V:melody abc|] % T:Second movement % it is preferable, but not strictly necessary, to redeclare "V:melody" here def|] % this belongs to "melody", which thus becomes the first ("master") voice of this movement V:harmony % "harmony" becomes the second voice of this movement in order of declaration Bcd|]

(Note that a voice ID may have occured before, 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; items of such a type, called control items, apply to all voices simultaneously at the given metric position:

1. all types referring to the flow of music:
   1. all sorts of repeat sign
   2. all volta signs [1 etc.
   3. the "decorations" !segno! !coda! !D.S.! !D.C.! !dacoda! !dacapo! !fine!
   4. fields Q: and P:
   5. … [TODO]
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:, non-repeat bar lines, and fermatas are not control types; they may differ between staves.

1. The first voice of a movement, in order of declaration there, has the role of control voice.
2. Any control item of a piece must be present in its control voice, so that software and human readers can see them in their intended succession.
3. A control item found in a non-control voice that does not match an equal item in the control voice at the same metric position (i.e. to be "played" simultaneously), is considered a non-fatal error; software must not obey it and should issue a severe error message. An important exception is described in the following subparagraph.
4. For good legibility and check of consistency, users should copy control items to all other voices at the same metric position (unless they have good reasons such as excessive length).
   • 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.
6. Global bar numbering always refers to the control voice. This voice is allowed (but strongly discouraged) to be metrically shorter than the longest voice of the movement, in which case the rest of the bars is undefined.

There is an important exception from the above rules about the control voice. Let us first define the notion "in synch":

A text position in the abc code between two abc items is called "in synch", 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. The beginning of the body or of a movement (after the T: item) is always "in synch", by definition.

Now for the important exception: Any control item occurring at a point "in synch" will be accepted as if it were in the control voice. Thus we legalize 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 % no voice, but in synch V:flute % the control voice cdef |] V:whistle ABcd |] % P:2 % formally in the non-control voice "whistle", but in synch I:score (flute whistle) % formally in the non-control voice "whistle", but in synch V:flute gabc' |] V:whistle efga |]

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 that are not control types
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]

1. If several voices share a staff, the first of these, in order of declaration, is called the master voice. This role can be reassigned at the start of a new movement. Also, a new "I:score" directive may redistribute the voices to staves, but cannot change the order of declaration.
2. Staff-related items in a non-master voice are perfectly legal (since the user may plan to change the staff assignment later, for different printings), but must be ignored by the software.
3. Clef keywords are formally strictly staff-related, but allow an alternative administration for shared staves. See 4.6 for details.

If two voices sharing a staff do not match in staff-related matters, fully compliant display software must execute the following adjustments to the representation of the non-master voice.

1. The guiding principle 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.
2. If a clef is imposed, software must adjust the displayed notes to represent the original intended sound. See 4.6 for details.
3. If a staff-related item is to be imposed, but its position is bridged by a single note or rest, software must normally split that note or rest in two, notes being tied. Some types do not require this, e.g. annotations and decorations. (Note the contrast to control items, which are assumed to be "more permanent".)
4. If a key signature for display (i.e. possibly after transpositions) must be imposed, software must 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.
5. Similarly, the effects of imposed bar lines on (non-signature) accidentals must be adjusted.
6. Overlay measures must be adjusted as if they were separate voices.

If some (not fully compliant) display software encounters such adjustment needs but cannot fulfill them (yet), it must issue a well-worded fatal error message, never display incorrect sheets. Of course, publishers of abc code should avert such calamities whenever possible.

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.

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.

In this version, the special role of T: as a movement separator is newly introduced, adopting the functionality of existing software.

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 in this version]
• MFT - W: printed below each movement (as done in abcm2ps) [NEW in this version]
• OV - ordering by V: (etc.) in the movement [NEW in this version]
• CT list - still to be completed. [NEW additions and grouping in this version]
• CT3 - new prefix for annotations, additional to ^ and _
• CT4 - I:concert-score
• CV - control voice movement-dependent [NEW in this version]
• SRT6, 7 - new prefices for annotations, additional to ^ and _
• SRT8 - New mechanism to exclude non-master annotations, lyrics etc.
• ANM - adjustments [NEW additions in this version - see below]

Note that I have dropped the "I:synch" of previous versions completely, for simplicity.

• Define "I:text" not as a control type (like $), but as a "movement separator" (like T:)? (Jef believes this to be "sensible"; I am not yet convinced, given the fact that the ordinary control item "$" can cause line breaks in the typesetting as well, without anyone expecting all voices to be synchronized.)
• ANM must probably become rebalanced in favour of programmers, at the expense of users: Compliant software has to offer only the function about unifying clefs, it is allowed to replace any of the other functions by that well-worded fatal error message. This means that publishers of abc code have to match bar lines and effective (displayed) key signatures between voices that share a staff. (Note that this makes some legitimate use cases miss out, e.g. involving traditional French horn voices.) We may proclaim several "degrees of super-compliance", named something like "fully compliant plus ANM4".
• We probably need more regulations for the notion "movement". For example, ordinary repeat signs should not transcend their movements:

T:First movement abc |] T:Second movement def :| % should only repeat the last three notes. % (Needless to say that abc2midi currently repeats all six.)

We might also regulate whether the instrument name can be changed, and should be printed, at the beginning of each movement, which abcm2ps already allows resp. does.

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 master role.

That is in fact the idea. When this document describes what software must do, the purpose is only 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 to do 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 way of coding. Users will be glad if we describe a style of coding as "orthodox", so that new features are most likely to work properly on otherwise unchanged code. A typical example is the concert score.

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