Chords¶

This document defines the syntax and semantics of chords in neumaRk, including:

dictionary of admitted chord symbols
normalization of variants
bass handling
chord rhythm (implicit, explicit, mixed)
optional chords
polychords

Chords are contained in C) lines and can be used to determine both the harmony and its rhythmic aspect.

1. Chord event¶

A chord event is a harmonic unit that may have:

a chord symbol
an optional bass, or a bass only
a duration (implicit or explicit)
duration modifiers

A chord event may also represent:

a rest (r)
a re-attack (!)
a polychord (two symbols stacked vertically, see §6)

Every chord event in neumaRk is an autonomous rhythmic entity, with an implicit or explicit duration.

A chord may include an explicit bass in the form of a slash chord (e.g. A/B), or consist exclusively of a bass (e.g. /B).

In both cases, the event is subject to the same rhythmic rules as the other chords.

1.1 Harmony persistence (empty cell)¶

An empty chord measure — with no symbols, no % and no NC token (§1.2) — does not represent a harmonic void: the harmony of the previous measure persists. The prevailing harmonic content is re-realized on the downbeat of the empty measure (re-attack, with the same logic as %), not sustained like a tie.

Persistence:

propagates across multiple consecutive empty measures;
crosses datapack boundaries, consistently with the persistent musical context (neumaRk_specification.md);
is interrupted by an NC event (§1.2) and resumes only from the next explicit chord.

C) C |   |   F

Measures 1 and 2 carry the chord C; measure 3 carries F. No glyph is drawn above the persisting measures: the chord line stays clean.

Note-line rendering. If the N) line of a persisting measure is empty, the measure is rendered with slash notation (there is active harmony to comp): see neumaRk_notes_and_durations.md §10 → Slash notation.

Inside versions. Persisting harmony is context, so it crosses a %%NAME region by the same rule as the other contexts (neumaRk_versions.md §4.1.1): every alternative starts from the harmony in force when the region begins, and the measure after %%end inherits the one the canonical block ends on — not the selected block's. That way the rest of the song reads the same for everyone.

1.1.1 Partial continuation (leading `.`)¶

When a measure begins with a dot . (before any chord symbol), the dot is a continuation of the persisting harmony: it re-strikes the active harmony (§1.1) for its own slot only, leaving the rest of the measure to the chords that follow. It is the slot-level extension of empty-cell persistence. (Distinct from a . that follows a chord in the same measure, which prolongs that chord's duration: see §4.)

C) A7 DM |   | . GM

In measure 3 the first beat continues DM — the active harmony, inherited from measure 1 through the empty cell of measure 2 — and the second beat carries GM. The resulting harmony equals A7 DM | DM | DM GM.

Multiple leading dots (. .) extend the continuation over several slots. If no harmony is active (start of the piece, or after NC), a leading . continues no harmony. On the chord line the continuation dot draws no glyph.

1.2 No chord (`NC`)¶

The NC token (two uppercase letters, no dots) declares the absence of harmony: it interrupts persistence (§1.1) and indicates that no chord is active in that measure.

as the sole content of its cell it occupies the entire measure;
it realizes no chord (no active harmony);
it is rendered on the chord line with the dedicated N.C. glyph (reference rendering, informative: reserved codepoint U+EF62 of the BravuraLS/PetalumaLS fonts);
if the corresponding N) line is empty, the measure does not get slash notation but a rest (there is no harmony to comp).

C) C |  NC |  F

Measure 1 carries C; measure 2 has no chord (with N.C. drawn); measure 3 carries F. After an NC, an empty cell stays chord-less until a new explicit chord appears.

1.2.1 `NC` on a fraction of the measure¶

NC need not fill the measure: it can sit next to other symbols, and then it behaves like a chord — it takes its slot in rhythm deduction (§4.1), accepts an explicit duration (NC(4)), and prints N.C. at that position, not centred on the measure.

Like a chord, it persists: from there on no harmony is active until a new explicit symbol appears — through the following slots, the following measures and the empty cells.

C) C-7 NC |  | F

C-7 lasts the first two beats; from the third there is no harmony left, and measure 2 (an empty cell) stays chord-less instead of inheriting C-7. Measure 3 restarts from F.

It follows that the last harmonic event of the measure wins:

Source	After the measure
`C-7 NC \\| \\|`	no harmony in the two empty cells
`NC C-7 \\| \\|`	`C-7` persists through the two empty cells

On the N) line, implicit slash notation (§10 of neumaRk_notes_and_durations.md) remains a per-measure decision: a measure with an empty note line gets slashes if harmony is active at its start. A measure cannot be half slashed.

1.3 Harmonic rest (`R`)¶

The R token (a single uppercase letter) is the silent twin of NC: it declares the absence of harmony exactly like NC — interrupting persistence (§1.1) — but draws nothing on the chord line. Use it when a passage should carry no chord symbol at all (e.g. an instrumental section without changes), even when a line break would otherwise restate the persisting harmony.

as the sole content of its cell it occupies the entire measure;
it realizes no chord and stops persistence, exactly like NC;
if the corresponding N) line is empty, the measure does not get slash notation but a rest (there is no harmony to comp);
unlike NC, it draws no glyph (no N.C., no symbol) — the cell is blank.

When to choose which: use NC to visibly declare "N.C."; use R when you simply want no symbol printed.

C) C |  R |  F

Measure 1 carries C; measure 2 has no harmony and no printed symbol; measure 3 carries F. After an R, an empty cell stays chord-less until a new explicit chord appears.

1.3.1 `R` on a fraction of the measure¶

R need not fill the measure: it can sit next to other tokens, and then it covers a fraction of it. In that position it is a synonym of the chord rest r (§4.3): it takes part in rhythm deduction like any other event and carries no chord for its duration. It follows the same rendering rule too: bare R is implicit and draws nothing; R(…) is explicit and draws a visible rest in the chord rhythm, exactly like r(…).

C) > | R C-11(8^) | !(2.)

Measure 2 carries no symbol over the first three and a half beats; C-11 falls on the last eighth, tied into the next measure. It is the same alignment you would get with a real symbol in place of R, minus the printed symbol.

Canonical form. Fractional R and r are the same event: the round-trip re-emits r, as with the other chord-symbol normalizations (§3). The semantic difference only concerns the whole measure: R alone also stops harmony persistence (above), r does not.

2. Chord symbol¶

2.1 General structure¶

The general form of a symbol is:

<root><quality>[<extensions>][/<bass>]

Where:

root ∈ {A B C D E F G} with optional accidentals # or b (at most one accidental)
suffix identifies the chord suffix
bass optional, indicates a bass different from the root

Examples:

C   Dm  GM  F#7alt   BbM13   C7/E

3. Chord dictionary¶

The "Normalization" column is the canonical source form — what you type and what the round-trip reproduces. On the staff, three families are rendered with jazz glyphs: diminished °, half-diminished ø, major-seventh Δ (e.g. Co7→C°7, Ch→Cø, CM→CΔ). These glyphs are not valid input: typing them yields E102.

3.1 Triads¶

Admitted input	Normalization
C	C
Cm, C-	C-
Co, Cdim	Co
C+, C5+, Caug	Caug
Csus2	Csus2
Csus4	Csus4
Cadd2, Cadd9	Cadd2
Cadd4	Cadd4

3.2 Major chords (4 or more notes)¶

Admitted input	Normalization
C6	C6
C69	C69
CM, CM7, CMaj7, Cmaj7, C7M	CM
CM9, Cmaj9	CM9
CM13, Cmaj13	CM13
CM#11, CM7#11, Cmaj#11	CM#11
CM9#11	CM9#11
CM13#11	CM13#11
CM+, CM#5, CM7#5, C+M7	CM#5
CMadd4	CMadd4

3.3 Minor chords¶

Admitted input	Normalization
C-b6, Cmb6	C-b6
C-6, Cm6, C-69, Cm69	C-6
C-7, Cm7	C-7
C-9, Cm9	C-9
C-11, Cm11	C-11
C-13, Cm13	C-13
C-M, CmM, C-M7, CmM7	C-M
C-M9, CmM9	C-M9
C-M11, CmM11	C-M11
C-M13, CmM13	C-M13

3.4 Dominant chords¶

Admitted input	Normalization
C7	C7
C9	C9
C13	C13
C7#11, C7b5	C7#11
C9#11	C9#11
C13#11	C13#11
C7b9	C7b9
C7alt	C7alt
C7#5, C+7	C7#5
C7#9	C7#9
C13b9	C13b9
C7sus	C7sus
C9sus	C9sus
C13sus	C13sus
C7susb9	C7susb9
C7add4	C7add4

3.5 Diminished and half-diminished chords¶

Admitted input	Normalization
Co7, Cdim7	Co7
CoM7, CdimM7, CoM	CoM
Cm7b5, Ch	Ch
Ch9, C-9b5	Ch9
Ch11, C-11b5	Ch11

3.6 Suffixes outside the dictionary¶

The dictionary (§3.1–§3.5) is the set of recognized suffixes. The major-seventh spellings maj/Maj (Cmaj7, Cmaj9, Cmaj#11, …) and the redundant M7/7M are canonicalized to the M-form (§3.2) — they are recognized, not warnings. The maj→M canonicalization applies only when the suffix begins with maj (the major family): minor-major and diminished-major must be written with the -M/mM (§3.3) and oM (§3.5) forms; spellings like C-maj7/Cmmaj7 are not in the dictionary and fall back to W103. A suffix genuinely outside the dictionary (e.g. dom7) does not make the document invalid: the symbol is preserved (root + optional bass) but the suffix has no significant rendering, and the parser emits the non-blocking warning W103 (unrecognized chord suffix). This is a best-effort degradation, not an error: the parsing flow continues.

The dictionary spellings are case-sensitive: Cmaj and CMaj are the form CM, but CMAJ7, all upper case, is not a chord symbol. The parser splits it into tokens it does not recognize (E102) and keeps what it can (CM followed by A).

4. Chord rhythm¶

N.B.¶

The meaning of the dot (.) is specific to the context of chord lines and does not coincide with the one used in notes lines. The dot character takes on different meanings depending on whether it is positioned spaced from the chord event or inserted in the context of a duration.

4.1 Implicit mode¶

In the absence of explicit durations, the chord rhythm is deduced.

Principle:

the chord events in a measure are counted
the measure duration is subdivided equally
the dot (.) prolongs the chord by its own duration

Examples in 4/4:

| C Dm |
| C . . Dm |
| r C . Dm . D#o . Em |

In implicit mode the rhythm is not displayed, but it serves for alignment.

4.1.1 Explicit prolongation with a slash (`/`)¶

The / token (a slash, as a standalone token) prolongs the preceding chord exactly like the dot (.) — same duration, same subdivision, same alignment — with one difference: it prints a slash on the prolonged beat, even in implicit mode (where the . stays invisible). It is the tool to make graphically explicit which chord is held, and for how many beats.

| C A B C . | and | C A B C / | are musically identical; the second draws a slash on beat 4. Several consecutive slashes are allowed (Eb7 / /) and they may be mixed with dots in the same tail (C . /), each counted as one subdivision unit.

Examples in 4/4:

C) | FM E7 Eb7 . |     // ambiguous: which chord lasts two beats?

C) | FM E7 Eb7 / |     // explicit: Eb7 is held, slash on beat 4

A / as the first useful token of the measure is a continuation placeholder inheriting the persistent harmony (§1.1), rendered as a slash.

Disambiguation. The prolongation / is a standalone token (whitespace or barline around it, no pitch after it). It is distinct from a / glued to a pitch, which denotes the bass of a slash chord (A/B, Eb7/Bb) or a bass on its own (/B, §1): there the / is attached to a pitch, here it is isolated. Disambiguation is purely positional, consistent with the rest of the spec.

The / does not alter pitch, duration, transposition, or harmony: it is only a difference in graphic rendering with respect to the . — a prolongation to all effects (round-trip preserves the written / form).

4.1.2 Explicit prolongation with a hold line (`-`)¶

The token - (dash, as an isolated token) prolongs the preceding chord exactly like the dot (.) and the slash (/) — same duration, same subdivision, same alignment — with one difference in rendering: it draws a continuous horizontal hold line spanning the prolonged beats. It is the idiomatic notation for "the chord holds through here".

| C A B C . |, | C A B C / |, and | C A B C - | are musically identical; the third draws a line over the 4th beat. A run of several consecutive - (A - -) renders as a single continuous stroke (not separate dashes) spanning all covered beats. Combining dots, slashes, and dashes in the same tail is allowed (C . / -), each counted as one subdivision unit and rendered per its own mark.

Examples in 4/4:

C) | FM E7 Eb7 . |     // ambiguous: which chord lasts two beats?

C) | FM E7 Eb7 - |     // explicit: Eb7 holds, line over the 4th beat

C) | A C - - |         // C holds 3 beats, continuous line over the last two

A - as the first useful token of a measure is a continuation placeholder inheriting the persistent harmony (§1.1), rendered with the hold line.

The - is usable both in the base C) row and in the alternate C+ rows (where the line visually "holds" above the base).

Disambiguation. The prolongation - is an isolated token (spaces or barlines around it). It is distinct from the - attached to a root, which denotes a minor chord (C-, F-7, §3): there the - is glued to the letter, here it stands alone. C- is C minor; C - (with a space) is C major followed by a hold line. Disambiguation is purely positional.

The - does not alter pitch, duration, transposition, or harmony: it is only a difference in graphic rendering with respect to the . — a prolongation to all effects (round-trip preserves the written - form).

4.2 Explicit mode¶

The duration of a chord may be indicated in parentheses:

C(4)   Dm(8.)   G7(16)   F(8t) !(8t) !(8t)   Bb(4)

The duration may contain:

note value (mandatory)
dots (.), standard mode, add half of the value
t for triplet (tuplet 3:2)
multipliers (*n)

Special symbols:

r → rest
! → re-attack (repeats the duration, not the symbol)

The tie ^ is written inside the parentheses, after the value: C(2^) ties the chord to the next event, also across the barline. Written outside the parentheses (C(2)^, C^) it is not recognized (E102) and the tie is lost.

With this notation mode, the chord rhythm is notated above the staff.

4.3 Mixed mode¶

It is possible to combine implicit and explicit mode in the same measure.

only the explicit durations are displayed
the others are deduced

C   Dm(8^)

The rest r follows the same rules as a chord, both for rhythm deduction and for display:

r (without parentheses) is implicit: it contributes to the deduction like any other event (the measure duration, minus the explicit durations, is subdivided equally among the implicit events, also taking into account the dots .) and is not drawn in the rhythm-row;
r(...) (with parentheses) is explicit and is drawn as a visible rest above the staff.

Example — eighth-note anticipation on an otherwise empty measure:

r EbM(8^) | EbM

renders only the anticipating eighth note tied to the EbM of the next measure, without visible rests filling the first measure. It is equivalent, in placement and rhythm, to what is already obtained with an implicit chord in place of r (Gm EbM(8^)), with the difference that here there is no symbol at the beginning of the measure.

Reference rendering (informative). The reference rendering does not apply the suppression to an implicit event (chord or r) that falls inside an irregular group of the chord rhythm: there the event is drawn (the r as a rest, the chord as a rhythm head). This is a deviation of the rendering, not a notation rule: the event's duration and rhythm do not change.

Also in the reference rendering, on a line that carries chord rhythm a chord symbol without a duration of its own (neither (…) nor a member of a compact list, §4.4) drops to the level of the rhythm heads, into the free space of its column: symbols with their own rhythm stay up, those without sit closer to the staff. The exception is an implicit chord inside an irregular group, which has its rhythm head drawn (previous paragraph) and stays up with the other symbols of the group. Any chord symbol standing over the bracket or the number of an irregular group of the chord rhythm rises just enough not to touch them (C) | F(8t) Bb G(8t) C(2.) |: F, Bb and G above the "3", C keeps its height).

4.4 Compact duration list¶

When the same chord extends over multiple rhythmic figures, instead of repeating ! for each continuation one can use a comma-separated list of durations inside the parentheses:

D/Eb(16,8,8,16,16,r16,16,16)

is the compact form, equivalent to:

D/Eb(16) !(8) !(8) !(16) !(16) r(16) !(16) !(16)

Rules:

each segment admits value, value. (dotted), value.., value..., valuet (triplet);
a segment may begin with r to insert an internal rest (e.g. r16): the chord interrupts for that duration and then resumes with the next segment;
the first segment cannot be r (the list must open with the chord): D(r16,8) is an error;
*n (multiplier) and ^ (tie) are not admitted inside the segments, only in the single-rhythm form (value*n) or on the final segment of the group (see below);
spaces around the commas are tolerated: D(16, 8, 8) is valid.

Tie ^ on a compact list. The ^ on the last segment, inside the parenthesis, ties that segment to the next event, like a normal value tie on the last note of the measure:

D/Eb(16,8,8,16,16,r16,16,16^)   A
                           ↑
                           last `16` tied to `A`

Visual rendering. The symbol D/Eb appears only once above the staff (anchored to the first segment). The rhythm of the whole group is drawn above the staff: the first figure has the name of the chord, the following ones are continuations without a symbol (no symbol repeated), any internal r are visible rests.

Round-trip. When saving and reloading, the compact form is preserved: the .nrk file becomes identical to what was written.

5. Optional chords¶

An open parenthesis starts a group of optional chords:

(C Dm G7)

The group may extend over multiple measures, including internal barlines:

(FM F#-7 | B7 EM)

The parentheses are rendered visually around the group. The chords inside them maintain normal rhythmic semantics and alignment with the other lines of the datapack.

An optional group may carry a comment-label (§8) attached to the closing parenthesis, without intermediate whitespace:

(FM F#-7 | B7 EM)[Bill Evans changes]

Optional chord or key. A bare chord symbol in parentheses has the same shape as a key ((Bb), (Dm), (F)). The position decides (neumaRk_datapack.md §7.3): glued to the barline or written before the first barline it is the context object, i.e. the key of the measure; detached after the barline or inside the measure it is an optional chord.

C) (Bb) | Eb7 F |      // key of B-flat (before the first barline)

C) |(Bb) Eb7 F |       // key of B-flat (glued to the barline)

C) | (Bb) Eb7 F |      // optional chord Bb, then Eb7 and F

6. Polychords¶

A polychord is a chord event made of two stacked symbols, read simultaneously: an upper symbol and a lower symbol, separated visually by a horizontal line.

The polychord is a harmonic event distinct from the slash chord (§1):

slash chord (A/B) → a single chord A with bass B
polychord ([A|B]) → two independent chords A and B stacked

6.1 Syntax¶

A polychord is enclosed in square brackets, with the | character as the internal separator:

[<top>|<bottom>]

Where:

top and bottom are valid chord symbols according to §2 (root, quality, extensions, optional bass)
the square brackets [ ] are mandatory
the separator | is mandatory and appears exactly once
internal whitespace is not admitted

Valid examples:

[D|EbM]            polychord: D major over EbM7
[CM7|F#-7]         polychord with extended symbols
[D/F#|EbM]         top with explicit bass (slash chord) over a simple chord
[Am|G](8.)         polychord with explicit duration

Invalid examples:

[D|EbM|F]          three levels not admitted
[|EbM]             upper symbol missing
[D|]               lower symbol missing
[D | EbM]          internal whitespace not admitted

A malformed polychord gives E102 and degrades to the recognizable chord symbols it contains, written one after the other ([D|EbM|F] → D EbM F).

6.2 Visual rendering¶

The polychord is displayed as two vertically stacked symbols, separated by a horizontal line:

 D
───
EbM

The horizontal width reserved for the polychord equals the greater of the two symbols.

6.3 Duration and rhythm¶

The polychord is a single chord event for rhythmic purposes. All the rules of §4 apply to the polychord as to any other event:

implicit duration: the polychord counts as a single event in the subdivision of the measure
explicit duration: the parentheses follow the square brackets, e.g. [D|EbM](4)
re-attack (!) and repetition (.) operate on the whole polychord

C) | [D|EbM] . . [F|G7] |     // polychord repeated three times, then change

C) | [D|EbM](2) [F|G7](2) |   // two polychords, explicit duration

6.4 Transposition¶

In transposition, both symbols of the polychord are transposed independently according to the rules of the single chord.

6.5 Limits¶

number of levels: exactly 2 in neumaRk 0.6; extensions to N levels are outside the specification
nesting: a polychord cannot itself contain another polychord
optional group: a polychord may appear inside an optional chord group ( … ) (§5)

7. Alternate chords (`C+`)¶

The C+ line marker introduces an alternate chord line to the base line C): harmonies the reader may use instead of the base ones at given positions — typically the changes for solos.

7.1 Model and placement¶

The C+ is an additional line, not a substitution: it coexists with the C) in the datapack, which remains the principal line.
In the source the C+ lines are placed above the base; the C) is the last chord-row of the datapack. At most two C+ lines are admitted, stacked above the base.
Each C+ shares the base's grid and barlines and aligns to its columns: each alternate event reads above the aligned base event.

7.2 Overlay per position (not per measure nor per song)¶

The alternative acts position by position:

where the C+ has a chord, that is the alternative for that column;
where the C+ has an empty cell (| |), or does not cover a measure at all, it proposes no alternative: the base applies.

C+ |     | Ab7 | D-7          |
C) | C   | A-  | D-7  Bb7  A7 |

→ M1 no alternative (C applies); M2 Ab7 replaces A-; M3 D-7 replaces only the first event, Bb7 and A7 remain.

7.3 Rhythm and prolongations¶

The C+ accepts the same rhythmic vocabulary as the base: durations (…), restruck !, tie ^, and the prolongations . (invisible), / slash (§4.1.1) and - hold line (§4.1.2).

7.4 Label¶

A C+ line may carry a comment-label (§8) as its first token, with any frame: C+ "solos changes", C+ ["solos changes"] (or C+ [solos changes]), C+ ("solos changes").

7.5 Transposition and realization¶

Transposition: the C+ chords follow the song's transposition exactly like the base ones.
Realization: the piece's effective harmony is defined by the base line C) alone; the C+ is a reading alternative and does not contribute to the harmonic realization.

8. Comment-label¶

A comment-label is a free text attached as a postfix to a chord event to annotate it.

8.1 Syntax¶

The comment-label follows the frame model of textual containers (neumaRk_text_markup.md §2.1): the text sits between quotes, the frame around it is optional. The forms are semantically equivalent and differ only in their graphics:

"<text>" — no frame;
["<text>"] — box (reference form);
[<text>] — box, shorthand for ["<text>"] (same result: the quotes never appear);
("<text>") — round frame.

The text is a string of printable characters (spaces included) and admits the text markup defined in neumaRk_text_markup.md. The closing character of the container (" or ]) cannot appear literally in the text: use the escape \" or \] (C7[a\]b]), or the quoted form ["a]b"], where the ] is already text. Inside quotes a | is text too: Eb7alt["a|b"] is a label, not a polychord (§6).

When the document is rewritten, on the chord row the box is written in the abbreviation [text] when the text allows it, and in the form ["text"] when it contains ] or |: the two forms are equivalent (Eb7alt["tritone"] is rewritten Eb7alt[tritone]).

The default style of the comment-label is plain (roman), medium size (role reduced; ### makes it small), with any frame. The text markup *…* turns on italic above this default.

Three admitted scopes, distinguished by attachment point:

chord-level — attached to a chord event (also polychord), without intermediate whitespace:

Eb7alt"tritone"            no frame
Eb7alt["tritone"]          box (reference form)
Eb7alt[tritone]            box (shorthand)
Eb7alt("tritone")          round frame
[A|EbM]"polychord exp."

group-level — attached to the closing parenthesis ) of a group of optional chords (§5):

(FM F#-7 | B7 EM)"Bill Evans changes"
(FM F#-7 | B7 EM)["Bill Evans changes"]
(FM F#-7 | B7 EM)("Bill Evans changes")

row-level — as the first useful token of the chord-row, preceded only by the line marker C) / C+, with any frame. Two positions:
without barlines — label as the only content of the line (the chord-row contains no musical events):
```
C+ "solos changes"
C+ ["solos changes"]
```
The label stays even when the row has nothing else: when the document is rewritten, C) [Intro] | and C) "solos" become C) | [Intro] | and C) | "solos" |, the same row with the same label.
with barlines — label as the first token inside the bars of the line, before any chord-event:
```
C+ | "solos changes" | Cm7 | F7 |
C+ | ("solos changes") | Cm7 | F7 |
```
The label segment is a measure: the row above has three, the first with the label alone. As on every row the opening barline is optional (neumaRk_datapack.md §6), but only in front of context: a label makes it real, and C+ "solos changes" | Cm7 | F7 | is the same three-measure row. To put the label on the measure of the first chord, write it in that measure: C+ | "solos changes" Cm7 | F7 |.

A label written at the head of a measure after the first is not a row label: it belongs to that measure and attaches to the chord that follows it (C) | Eb7 F | [xy] G | is equivalent to | Eb7 F | G[xy] |). If no chord follows in that measure (C) | Eb7 F | [xy] |), the label stays in its measure, on the empty cell, at beat 1, while the previous harmony persists; the same holds on C+ rows. Two labels at the head of the same measure are a duplicate (E126, §8.4): the first one holds.

```
C) | Eb7 F | [xy] | G |
N) | c4 d e f | g1 | c1 |
```

8.2 Disambiguation¶

The delimiter […] is shared with other constructs already defined in the spec. The disambiguation is positional:

Construct	Recognized form
Polychord (§6)	`[<top>\\|<bottom>]` — contains internal `\\|`, no whitespace
Volta (`flow §3.2`)	attached to the barline at the start of the measure: `\\|[1.]`
End-decorator (`flow §4.3`)	attached to `:\\|` or to a closing barline: `[xN]:\\|`, `[D.S.]`
Comment-label (box)	attached to a chord / `)` of an optional group, or first token of the row, in the form `["…"]` / `[…]`

The parser recognizes the polychord first (constraining the form to internal |), the others are distinguished by attachment position.

The "…" form of the comment-label does not collide with any of these constructs, because the delimiter " is not shared. The disambiguation of the comment-label "…" remains positional (attached to a chord, ) of an optional group, or first token of the row).

The round frame ("…") is told apart from the optional chord group (§5) and from the duration C(4) by the " that immediately follows the (: (C7 F7) opens a group, ("alt") is a label. A round frame glued to the closing barline (("ad lib"):|) is an end-decorator, like the other forms (flow §4.3).

8.3 Visual rendering¶

chord-level — reduced plain above the chord (above the eventual rhythmic notation), with the written frame.
group-level — reduced plain above the group, left-aligned, with the written frame. The optional parentheses remain unchanged with any frame.
row-level — reduced plain at the start of the line, left-aligned with the first musical event; if the first chord has a comment-label, the row label takes its left edge (frames included).

The frame hugs the text (it does not reach down onto the chord symbol below). The default style (plain, medium size) is a property of the construct and applies with any frame; the frame decides only the graphics around the text (see neumaRk_text_markup.md).

Reference rendering (informative). The comment-label above the chord symbol (chord, group and row level) and its frame are in the ink color, like the rest of the score, smaller than the symbol: the size is what sets them apart from the symbol and from note annotations.

On several lines. A ; in a comment-label is a line break, at every level (neumaRk_text_markup.md §3bis): the stack grows upward, the last line stays where the single line would be, and a single frame wraps the stack. A group or row label stacked above the first chord's comment-label clears the whole stack; C+ rows above move up as needed. In the side label of §8.5 the dashed line starts from the last line.

C) | (C7"alt;b9" F7 | Bb A7)"Bill;Evans" | D-7"voicing;drop 2" |

8.4 Limits¶

at most one comment-label per event (error E126 if duplicated on the same event), regardless of the frame used; this holds for the group too: in (C7 F7)"a""b" the second label is a duplicate of the group (E126) and is discarded, it does not move to F7; the same for two labels at the head of a measure (§8.1, | [xy] [zz] G |)
the label is purely annotative: it does not affect pitch, duration, rhythm, musical flow or transposition
admitted both on the base line C) and on the alternate lines C+
the containers fit on one source line: the closing delimiter must appear by end of line (to break lines in the rendering use ;, §8.3)

8.5 Line extension (`label-`)¶

A chord-level comment-label may carry a hyphen - glued to its closing delimiter ("…"-, ["…"]-/[…]- or ("…")-). This suffix changes the rendering of the label from above the chord symbol to a horizontal extension to the side:

the text is drawn to the right of the chord symbol (no longer centered above it);
from the end of the text a dashed line extends up to the first terminator in the row, namely:
the next printed chord symbol (empty cells / invisible continuations are skipped); or
an NC measure → the line stops before the N.C. glyph; or
an R measure (harmonic rest, muted and glyph-less, §1.3) → the line stops at the start of the measure;
(a fractional NC, §1.2.1, is a printed symbol like any other: it stops the line by the first rule, not by this one);
if none follows, to end of line / end of piece;
the line ends with a downward vertical hook.

It is the idiom for annotating an event that extends over time — typically a break, a drum fill, a solo:

C)  | C-7"break"-  |  |  | Bb6 |

C-7 carries the break label to its right; the dashed line spans the three measures up to Bb6. The boxed form is equivalent:

C)  | C-7[break]-  |  |  | Bb6 |

If the arrival cell is an NC or R instead of a chord symbol, the line stops there (before the N.C. glyph, or at the start of the muted R measure):

C)  | C-7"break"-  | NC |     // the line stops at the N.C. glyph

C)  | C-7"break"-  | R  |     // the line stops at the start of the R measure

Disambiguation. The extension - is glued to the label's closing delimiter ("break"-, no space). It is distinct from the sustain-line extension - (§4.1.2), which is an isolated token and extends the harmony: C-7"break" - (with a space) is the symbol with the label above followed by a sustain extension; C-7"break"- (glued) is the symbol with the label to the side + an annotation line. Disambiguation is purely positional (adjacency to the delimiter).

The extension - is purely annotative: it does not affect duration, rhythm, harmony or flow; it does not count as a subdivision slot (unlike the sustain -). Round-trip lossless: the serializer re-emits the glued -. Without the - the label stays above the chord symbol (§8.3, unchanged).

Reference rendering (informative). The side label, the dashed line and the hook are in the ink color, like the rest of the score. The side label has the size of the A) text annotations (A) "vamp"-), larger than the label above the chord symbol (§8.3).

Note. The extension is defined only at the chord-level scope. At group-level / row-level a glued - is ignored: it opens no line, takes no slot, and the rewritten document does not keep it.

A)-row twin. This inline extension (label to the right of the symbol) has a twin above the chord band: an A) row written over the C) that anchors text annotations, dashed lines and { } analysis staves to the printed chords. See neumaRk_articulations.md §2.1.

9. General duration rules¶

in case of conflict the explicit syntax prevails
normalization unifies enharmonic/equivalent spellings into a single canonical rendering (e.g. 7b5→7#11, dim7→o7, m7b5→ø): it unifies the spelling, not the harmonic meaning
the implicit rhythm is deterministic

10. Diagnostics¶

Code	Condition
E101	Invalid compact rhythm list or one that starts with a rest (`D(16*2,8)`, `D(r16,8)`), chord or polychord expression that cannot be parsed (§4.4, §6)
E102	Unrecognized token on the chord row: invalid chord symbol (`CMAJ7`), typed rendering glyph (`CΔ`), malformed polychord, `^` outside the parentheses (§3, §4.2, §6)
E126	More than one comment-label on the same chord, group or row (§8.4)
E127	More than 2 `C+` rows per datapack (§7.1)
E129	More than one base `C)` row in the datapack (`neumaRk_datapack.md` §3.bis.1)
E135	Clef on the chord row (`E135.clef_on_chord_row`) or pitch reference on `C)`/`C+` (`E135.pitch_ref_on_secondary_row`): component discarded (`neumaRk_datapack.md` §7.3)
E300	Measure repeat `%` without a source (`neumaRk_flow_and_repeats.md` §7)
W103	Suffix outside the dictionary: symbol kept without the suffix (§3.6)
W131	`A)` row above `C)` with more texts than printed chord columns (`neumaRk_articulations.md` §2.1)
W400	Chord-rhythm note with non-positive duration: omitted (§4)

This document defines the harmonic and rhythmic semantics of chord lines in neumaRk.

Chords¶

1. Chord event¶

1.1 Harmony persistence (empty cell)¶

1.1.1 Partial continuation (leading .)¶

1.2 No chord (NC)¶

1.2.1 NC on a fraction of the measure¶

1.3 Harmonic rest (R)¶

1.3.1 R on a fraction of the measure¶

2. Chord symbol¶

2.1 General structure¶

3. Chord dictionary¶

3.1 Triads¶

3.2 Major chords (4 or more notes)¶

3.3 Minor chords¶

3.4 Dominant chords¶

3.5 Diminished and half-diminished chords¶

3.6 Suffixes outside the dictionary¶

4. Chord rhythm¶

N.B.¶

4.1 Implicit mode¶

4.1.1 Explicit prolongation with a slash (/)¶

4.1.2 Explicit prolongation with a hold line (-)¶

4.2 Explicit mode¶

4.3 Mixed mode¶

4.4 Compact duration list¶

5. Optional chords¶

6. Polychords¶

6.1 Syntax¶

6.2 Visual rendering¶

6.3 Duration and rhythm¶

6.4 Transposition¶

6.5 Limits¶

7. Alternate chords (C+)¶

7.1 Model and placement¶

7.2 Overlay per position (not per measure nor per song)¶

7.3 Rhythm and prolongations¶

7.4 Label¶

7.5 Transposition and realization¶

8. Comment-label¶

8.1 Syntax¶

8.2 Disambiguation¶

8.3 Visual rendering¶

8.4 Limits¶

8.5 Line extension (label-)¶

9. General duration rules¶

10. Diagnostics¶

1.1.1 Partial continuation (leading `.`)¶

1.2 No chord (`NC`)¶

1.2.1 `NC` on a fraction of the measure¶

1.3 Harmonic rest (`R`)¶

1.3.1 `R` on a fraction of the measure¶

4.1.1 Explicit prolongation with a slash (`/`)¶

4.1.2 Explicit prolongation with a hold line (`-`)¶

7. Alternate chords (`C+`)¶

8.5 Line extension (`label-`)¶