Second voice per staff¶

This document defines the syntax and semantics of the second musical voice on the same staff in neumaRk: marker, structural position, context rules, graphic rendering, and diagnostics.

The second voice is an independent musical stream that shares the same staff as the principal voice but evolves with its own rhythm and its own persistent musical context.

1. Definition¶

In neumaRk a staff can contain up to two independent voices:

voice 1 (or principal voice), introduced by the N) line (or N+, see neumaRk_datapack.md §4.5);
voice 2 (or secondary voice), introduced by the N2 line, optional.

The two voices:

share the staff, the clef, the key, the time signature, the measure barlines, and the chord line C);
maintain independent rhythmic and melodic streams;
have separate persistent musical contexts (last_pitch, durCtx).

A staff can have at most one voice 2. Voice 2 exists only if explicitly declared: in its absence the staff is monodic.

Staff ≠ voice. The concept of staff (N) / N+) describes the stave; the concept of voice (1st or 2nd) describes the musical stream within that stave. A piece with 4 staves may have up to 8 total voices (4 staves × 2 voices), with no further aggregate limits.

2. Marker syntax¶

2.1 Form¶

The voice 2 marker is the sequence of two characters:

N2

followed by a space, analogously to N) and N+. The token is 2 characters wide (the ) is absent), as required for the vertical alignment of the barlines across the datapack lines. Writing N2) (with the )) is a malformed form: error E130.

2.2 Relation to the general marking rules¶

The general rule (neumaRk_datapack.md §2.1) provides for markers formed by one, two, or three uppercase letters followed by ). The markers N+ and N2 are morphological variants of N) explicitly provided for by the specification and do not represent an arbitrary exception: the identifying letter N remains unchanged, and the second character distinguishes the role () continuation, + new staff, 2 second voice).

3. Structural position and binding¶

3.1 Voice group¶

Each voice is described by a voice group of the form:

[$)] [A)] N) [D)] [L)]      ← voice 1 group
[$)] [A)] N2 [D)] [L)]      ← voice 2 group (optional)

The $), A), D), L) lines bind by position:

$) (fingering, neumaRk_fingering.md) and A) (articulations) precede their N) / N2, in that order;
D) (dynamics) and L) (lyrics) follow their N) / N2, in that order.

Both voices can declare their own fingerings, articulations, dynamics, and lyrics independently.

3.2 Binding to the parent staff¶

An N2 line binds to the immediately preceding staff in the same datapack, identified by the most recent N) or N+ line. The recommended order between the parent N) / N+ and the N2 contains only:

the eventual D) / L) of the voice 1 group;
the eventual $) / A) of the voice 2 group.

Other interposed lines (M), C), F)) do not break the binding: the N2 stays voice 2 of the most recent staff. E123 fires only when, in the datapack, no N) or N+ comes before the N2 (§3.4).

3.3 Uniqueness per staff¶

Within the same datapack, each staff can have at most one N2 line. The presence of multiple consecutive N2 lines binding to the same staff produces error E124.

3.4 N2 as the first note line¶

An N2 not preceded by an N) or N+ in the same datapack has no valid parent and is invalid (E123).

4. Musical context of voice 2¶

4.1 Independent stream¶

The persistent musical context defined in neumaRk_specification.md §2.1 is per-stream: each (staff, voice) pair maintains its own last_pitch, its own durCtx, and the propagation state of the measure accidentals.

Context updates made by the events of voice 1 do not modify the context of voice 2, and vice versa.

4.2 Initialization at first appearance¶

When voice 2 of a staff appears for the first time in a datapack — that is, when in the preceding datapack the same staff did not contain a voice 2 — its initial reference (last_pitch and durCtx) is inherited from voice 1 of the same staff, in its state at the beginning of the current datapack.

Equivalently: voice 2 enters as if it were, at that precise musical instant, a continuation of voice 1 — and from that instant onward it maintains its own separate stream.

// DP1
N) a4

// DP2
N) c           // inherits a4 → c5 (minimum interval)
N2 a           // first appearance: inherits a4 (voice 1 at the start of DP2)
               // → a4. From here voice 2 continues with its own stream.

4.3 Subsequent appearances¶

When voice 2 was already present in the preceding datapack, it inherits normally from its own stream:

// DP3
N) c           // inherits from voice 1 of DP2
N2 a           // inherits from voice 2 of DP2

4.4 Suspended voices¶

If voice 2 of a staff is present in one datapack, absent in the next, and reappears in a still later datapack, upon reappearance rule §4.2 applies again: the context of voice 2 is reinitialized from voice 1 of the same staff at the beginning of the datapack of reappearance.

The historical context of voice 2 prior to the suspension is not recovered.

4.5 Voices in a staff introduced with `N+`¶

If voice 2 appears in a staff introduced in that datapack via N+, voice 1 of the staff is itself "fresh" (orientation reference based on the clef, see neumaRk_notes_and_durations.md §2.2). Voice 2 consequently inherits the same clef-dependent reference at the beginning of its own stream.

5. Graphic rendering¶

5.1 Stem direction¶

The simultaneous presence of voice 1 and voice 2 on the same staff fixes the stem direction in a normative way:

voice 1 → stems always up;
voice 2 → stems always down.

This rule applies independently of the pitch of the notes: with two voices on the staff, voice 1 always has stems up and voice 2 always stems down. (On a monodic staff the stem direction instead follows the standard automatic conventions.)

The single exception is voice crossing (§7): an explicit X marker toggles the slot→stem assignment from its column onward. Outside a crossing region the rule above holds unchanged.

5.2 Rests¶

The rests of the two voices are independent. When the natural vertical position of a rest collides with that of the other voice, the renderer applies a clarity offset according to the standard conventions of musical notation; this does not alter the semantics.

Reference rendering (informative). The whole-bar rest is per voice: the voice that is silent for the whole bar is drawn as a centred whole rest (neumaRk_notes_and_durations.md §3.3.1) even when the other voice has notes, which stay as they are.

6. Alignment and validity¶

6.1 Number of measures¶

If voice 2 and the parent staff have a different number of measures, the shorter one is completed with measure rests, with no diagnostics: N2 c d e f | under N) c d e f | g a b c | has a rest in the second measure. It is the same rule that applies between staves of a multi-stave system (neumaRk_datapack.md §4.3).

6.2 Chord line¶

The C) line is system-wide and is shared by all the voices of all the staves of the datapack. There is no per-voice C).

6.3 Clef¶

The clef is a property of the staff, not of the voice. Any inline clef directive on an N2 line is not allowed and produces error E125, regardless of form: a standalone token as the first token (e.g. N2 (@F) …), mid-measure (N2 c (@F) d …), or a begin-barline decorator (N2 |(@F) …). Voice 2 inherits the parent staff's clef.

6.4 Anacrusis¶

The anacrusis sign > is per-line and may appear independently in N) and in N2.

6.5 Measure repeat¶

The % token (and the variants %!, %2, %!2, %4, %!4, see neumaRk_flow_and_repeats.md §7) applies per-line: its presence in N2 repeats voice 2 of the source measure, without involving voice 1. The eventual copies of A), D), L) follow the same layer rules already defined for single lines.

6.6 Grace notes¶

Grace notes ([ … ], see neumaRk_grace_notes.md) are allowed within N2 with the same rules as voice 1. Their local context of pitch and accidentals lives in the stream of voice 2.

7. Voice crossing (`X`)¶

When the two voices of a staff swap vertical position — the lower rising above the upper, or vice versa — an explicit marker X declares the crossing point. From there the stems follow position and two oblique "X" segments trace each voice through the swap, so the eye can follow each voice across the exchange.

Voice crossing is editorial and selective: it is declared by the author with X, never inferred from a comparison of pitches. Two voices that merely brush past each other, or touch a passing unison, often do not call for the crossing marks; the marker leaves that choice to the author.

7.1 The `X` token¶

X is a standalone token in an N) or N2 line, written at the column of the crossing, between the notes. It belongs to the same grammatical class as the padding tokens . and |: it is neither a note nor a suffix, and it consumes no beat.
It may appear in either of the two voices. It anchors to the note-boundary of the voice in which it is written, giving fine control over the exact instant of the crossing even when the two voices are not homorhythmic.
The glyph is the uppercase X, kept distinct from the cross notehead, which is always the parenthesized suffix (x) (e.g. a2(x)).

A single X is enough to derive both obliques: it is written once, in whichever voice best anchors the instant. The pivot of the other voice is taken from that voice's own notes that straddle the same column.

7.2 Semantics — `X` is a toggle¶

X inverts the current vertical relationship of the two voices from its column onward, with two effects:

Stem-slot flip. The notes of the voice that was "above" take stem-down, and those of the voice that was "below" take stem-up, from the column of the X until the next X (or the end of the passage). This is a per-column slot state driven by the marker — an explicit, local exception to the fixed stem rule of §5.1, not a pitch-based heuristic.
Two oblique segments. At the swap point, for each voice a segment joins its pivot note before the crossing with its pivot note after. The two segments cross: this is the visible "X".

Crossings alternate: once the voice that was above has passed below the other, the following X swaps them back. The marker therefore needs no direction argument — it is a plain toggle of the current state.

The row in which X is written serves to (a) anchor the column (the rhythmic position) and (b) fix the pivot of that voice (its two flanking notes). The pivot of the other voice is derived from the notes of that voice which straddle the same rhythmic position. When the two voices are not homorhythmic the two pivots fall on different columns, so the two obliques take different slopes — the characteristic "skewed X".

7.3 Rests and the endpoints of the obliques¶

The endpoints of an oblique are always real noteheads: a rest is silence and offers no head to anchor to.
When a voice has a rest adjacent to the X, the oblique anchors to the nearest real note, skipping the rests. The stem-slot flip still fires at the column of the X, whether that column holds a note or a rest.
When a voice has no real note on one side of the crossing within the measure, that oblique is omitted (see §7.4).

7.4 Edge cases¶

Measure boundary. If a voice has no note after the crossing within the measure, its oblique is omitted. (Extending it into the next measure is out of scope.)
First or last event of the staff. Treated as the measure-boundary case above: the oblique on the missing side is omitted.
X without a pivot in its own row. If, even after skipping rests, the row that carries the X has no real note before or no real note after it within the measure, there is no pivot to anchor and the marker is invalid (error E132).

7.5 Validation¶

Code	Description
E131	Two `X` markers on the same column of the staff (one per voice, at the same rhythmic position): a double toggle at the same instant is ambiguous
E132	`X` without a pivot: no real note before or after it within its own row (even after skipping rests)

E131 is not a request to synchronize the two voices; it states that two crossings may not be declared at the same instant. A single X already derives both obliques, so one X per voice at the same column is redundant as well as ambiguous.

8. Diagnostics¶

8.1 Error codes¶

Code	Description
E123	`N2` without a valid parent staff (`N)` or `N+`) in the datapack
E124	More than one `N2` bound to the same staff in the same datapack
E125	Inline clef directive on an `N2` line
E130	Malformed voice/stave marker `N2)` / `N+)` (use `N2` / `N+`)
E131	Two `X` crossing markers on the same column of the staff (§7.5)
E132	`X` crossing marker without a pivot note (§7.5)

8.2 Misaligned measures¶

A misalignment of the number of measures between N2 and the parent staff falls under the same validity rules as multi-stave (neumaRk_datapack.md §4.3).

9. Examples¶

9.1 Minimal voice 2¶

C) A7
N) a1
N2 e4 d e2

Single staff in treble clef. Voice 1: one whole note a for the measure. Voice 2: two quarter notes and one half note.

9.2 Both voices with independent A/D/L¶

C) A7
A) .
N) a1
D) f
L) ah
A) ! !
N2 e4 d e2
D) p
L) la la la

The A) . line binds to N) a1; the A) ! ! line binds to N2. The dynamics and lyrics of each voice are independent.

9.3 Multi-stave with voice 2 on the upper staff¶

C) G7
N) | <d b>2 <e c>4 |
N2 | g8 a b a g a b a |
N) (@F) | g,4. d'8 e d |

Two-staff system. The upper staff (treble) contains two voices; the lower staff (bass) is monodic.

9.4 Multi-stave with voice 2 on the lower staff¶

C) G7
N) | <d b>2 <e c>4 |
N+ (@F) | g,4. d'8 e d |
N2 | r4 c8 d e d c b, |

Two-staff system introduced in this datapack. The N2 binds to the staff introduced by N+ (bass), which therefore remains two-voiced, while the upper staff (treble) is monodic.

9.5 Voice 2 at first appearance¶

N) a4

N) c
N2 a

N) c
N2 a

DP1: voice 1 ends with a4.
DP2: voice 1 c inherits a4 → c5; voice 2 a is at its first appearance, inherits a4 from voice 1 at the start of the datapack → a4.
DP3: voice 1 c inherits from voice 1 of DP2 → c5; voice 2 a inherits from its own stream (voice 2 of DP2) → a4.

9.6 Suspended and reappearing voice¶

N) c4
N2 a

N) e

N) c
N2 a

DP1: voice 1 c4, voice 2 a4 (first appearance, inherits from voice 1 → a4, minimum interval).
DP2: only voice 1 → voice 2 is suspended.
DP3: voice 2 reappears → rule §4.2 applies again; voice 2 inherits from voice 1 of DP3 at the start of the datapack, not from its own historical stream.

9.7 Voice crossing¶

C) Dm7
N)  b4 a  f  e
N2  d4 e  X  g  a

Single staff, two voices. Voice 1 descends b–a–f–e; voice 2 ascends d–e–g–a. The X in voice 2, written at the boundary before its third note, toggles the vertical relationship: up to that column voice 1 is above (stems up) and voice 2 below (stems down); from there voice 2 rises above voice 1, so the stems flip and two oblique segments join each voice's notes flanking the crossing — voice 1 a→f and voice 2 e→g — drawing the "X" (§7).