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 sound C; measure 3 sounds 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.

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 sounds GM. In playback this 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 . stays silent. 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 sounds in that measure.

it occupies the entire measure and is the sole content of its cell; it cannot be mixed with symbols or durations (C NC → error E128);
in playback it is silent (no chord realized);
it is rendered on the chord line with the dedicated N.C. glyph (reserved codepoint U+EFB2 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 sounds C; measure 2 is silent (with N.C. drawn); measure 3 sounds F. After an NC, an empty cell stays silent until a new explicit chord appears.

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¶

3.1 Triads¶

Admitted input	Normalization
C	C
Cm, C-	C-
Co, Cdim	C°
C+, C5+, Caug	Caug
Csus2	Csus2
Csus4	Csus4

3.2 Major chords (4 or more notes)¶

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

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

3.4 Dominant chords¶

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

3.5 Diminished and half-diminished chords¶

Admitted input	Normalization
Co7, Cdim7	C°7
CoM7, CdimM7, CoM	C°M
Cm7b5, Ch	Cø

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

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.2 Explicit mode¶

The duration of a chord may be indicated in parentheses:

C(4)   Dm(8.)   G7(8t)

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)

For the last chord of the measure, ^ creates a tie to the next measure.

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.

Current limitation. When an implicit event (chord or r) falls inside a tuplet the visual suppression is not active and the rest is drawn again. This is not a semantic choice: it is a constraint of the renderer that may be removed in the future without changes to the syntax.

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 trailing ^ ties the last segment of the group 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 silent continuations (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 (§7) attached to the closing parenthesis, without intermediate whitespace:

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

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 played together

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

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

| [D|EbM] . . [F|G7] |     polychord repeated three times, then change
| [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. Comment-label¶

A comment-label is a free string in square brackets, attached as a postfix to a chord event to annotate it with arbitrary text.

7.1 Syntax¶

A comment-label is expressed in two container forms, semantically equivalent, that differ only in the presence of the graphic box:

"<text>" — primary form, without box;
[<text>] — variant form, with box.

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 \].

The default style of the comment-label is italic, reduced size, in both forms. The graphic box is applied only in the […] variant.

Three admitted scopes, distinguished by attachment point:

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

Eb7alt"tritone"            no box (primary)
Eb7alt[tritone]            with box (variant)
[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]

row-level — as the first useful token of the chord-row, preceded only by the line marker C) / C+. Two semantically equivalent forms:
without barlines — label as the only content of the line (the chord-row contains no musical events):
```
C+ "solos changes"
C+ [solos changes]
```
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 |
```
It is equivalent to the form without barlines for the label segment, and allows coexistence with later events of the same row.

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

7.3 Visual rendering¶

chord-level — reduced italic above the chord (above the eventual rhythmic notation); graphic box only in the […] variant.
group-level — reduced italic above the group, left-aligned; graphic box only in the […] variant. The optional parentheses remain unchanged in both forms.
row-level — reduced italic at the start of the line, aligned with the first musical event; graphic box only in the […] variant.

The default style (italic, reduced size) is a property of the construct and applies in both forms. The container ("…" vs […]) decides only the presence of the box (see neumaRk_text_markup.md).

7.4 Limits¶

at most one comment-label per event (error E126 if duplicated on the same event), regardless of the container form used ([…] or "…")
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 […] and "…" are single-line: the closing delimiter must appear by end of line

8. General duration rules¶

in case of conflict the explicit syntax prevails
normalization does not alter the semantics
the implicit rhythm is deterministic

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