Flow, Measures, and Repeats¶

This document defines the temporal semantics of neumaRk: measures, barlines, decorators, repeats, and flow jumps.

The objective is to describe a deterministic, textual, and readable system, capable of representing complex musical structures without ambiguity.

1. Measure and barline¶

The notes and chords lines, as well as those of other types, contain barlines that delimit the measures.

1.1 Admitted barlines¶

The recognized barlines are:

|    ||    |.    .|    :|    |:

Rules:

the closing barline of a measure must be preceded by a space
the compound signs (:|, |:) do not admit internal spaces, except the compact label of the count-in repeat (:xN|, :open|, see §6.1)

2. Measure decorator¶

The decorators are symbols or textual constructs adjacent to a barline.

They modify the musical flow, the formal structure, or the rendering.

There are two classes of decorators:

BEGIN decorators → act at the start of the measure
END decorators → act at the end of the measure

Their position is semantically relevant.

Decorators and barlines¶

A decorator belongs semantically to a barline.

The decorators qualify the musical flow (repeats, jumps, coda, end, etc.) and are always associated with a specific barline, not with a measure in the structural sense.

3. BEGIN decorator (to the right of the barline)¶

3.1 Change of meter and key¶

A new meter and/or a new key may be indicated in parentheses:

|(3/4,Dm)

Rules:

meter and key may appear in arbitrary order
both are optional
the meter may use the form with bracket in the numerator (e.g. [3+2]/8)

If present, these decorators must come first, immediately adjacent to the barline.

3.2 Volta (alternative ending)¶

A square bracket indicates a volta:

|[1.]

The volta:

refers to the start of the measure
may include arbitrary text

3.2.1 Extension of the volta¶

The duration of the volta may be extended by adding +n:

|[1.]+4

In the absence of an extension, the volta closes automatically at the first repeat closing sign (:|) encountered within 4 measures (typical case of [1.] endings).

If no :| appears in the following 4 measures, the volta does not close automatically and indicates an exit (explicit extension +n recommended in all non-standard cases).

3.3 Structure signs¶

Other admitted BEGIN decorators:

$ → segno
@ → coda

They may follow the meter/key change decorators.

4. END decorator (to the left of the barline)¶

The END decorators modify the flow at the end of the measure.

4.1 Flow jumps¶

The following constructs are admitted:

DC → Da Capo
DCal@ → Da Capo al Coda
DCalFINE → Da Capo al Fine
D$ → Dal Segno
D$al@ → Dal Segno al Coda
D$alFINE → Dal Segno al Fine

4.2 Fine and Coda¶

FINE → end of the piece
al@ → jump to the coda

4.3 Textual decorators¶

A textual decorator is expressed in two container forms, semantically equivalent, that differ only in the presence of the graphic box:

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

[D.S.]:|            textual decorator with box
"freely":|          textual decorator without box
[x4]                textual decorator with box

It is displayed at the top, at the right margin of the measure.

The decorator admits the text markup defined in neumaRk_text_markup.md. The default style is plain, body size, in both forms.

For the particular case of the number of executions of a repeat ([xN]:|) or of an open repeat ([open]:|), the compact form :xN| / :open| is also available (see §6.1), which is interpreted by the player as an execution instruction.

5. Order and combination of decorators¶

Composition rules:

the BEGIN decorators always precede the content of the measure
the END decorators always follow the content of the measure
within each class, the order is semantically relevant
in case of conflict, the decorator closest to the barline prevails

6. Repeats¶

The repeats are indicated through the barlines:

|: → start of repeat
:| → end of repeat

The semantics of the repeats interacts with:

voltas
segni ($)
DC / D$

The resolution of the flow must be deterministic.

6.1 Number of executions and open repeat¶

To indicate how many times to execute a repeat, or to mark it as open (number not specified, typical of jazz/pop-style codas), the sign :| admits a compact label between the two characters:

:xN| (or equivalently :Nx|) with N an integer in [2..99] → execute the repeat N times
:open| → open repeat (number of executions at the performer's discretion)

Examples:

|: a b c d | e f g a :x8|
|: a b c d | e f g a :8x|
|: a b c d | e f g a :open|

Rules:

the token is atomic: no space between :, the label, and |
N must have 1 or 2 digits; :x1| / :1x| and :x100| / :100x| (or beyond) are parsing errors
open is case-insensitive: :open|, :Open|, :OPEN| are all accepted
the label is rendered above the barline, right-aligned (same position as the textual decorator [xN] of §4.3), in the canonical form xN independently of the order used in the input

6.1.1 Relation with the textual form `[xN]:|`¶

The compact form :xN| / :open| and the form with textual decorator [xN]:| / [open]:| (§4.3) produce the same graphic rendering, but have different playback semantics:

Form	Render	Play
`:xN\|`	"xN" box above	executable — the player executes N times
`:open\|`	"open" box above	executable — open repeat (UX prompt)
`[xN]:\|`	"xN" box above	decorative — the player uses default (2x)
`[text]:\|`	"text" box above	decorative — arbitrary text

The compact form :xN| is a structured instruction that the player reads and executes; the form with textual decorator is informative text for the human, and the player ignores it for the purposes of counting the repeats (it follows the standard default, typically 2 executions).

Both remain valid. The compact form is recommended for the count-in repeats where the number of executions must be respected by playback; the form with textual decorator remains useful for arbitrary labels other than xN/open (e.g. [D.S.], [fade]) or when the number of executions is purely informative.

7. Measure repeat¶

The symbol % indicates the repeat of the content of the preceding measure(s). There are six forms, which distinguish the graphic rendering from the explicit realization of the content, for spans of 1, 2, or 4 measures:

Token	Render	Span
`%`	similar glyph (`repeat1Bar`)	1 measure
`%!`	visible copy of the content	1 measure
`%2`	similar-2 glyph (`repeat2Bars`)	2 measures
`%!2`	visible copy of the content	2 measures
`%4`	similar-4 glyph (`repeat4Bars`)	4 measures
`%!4`	visible copy of the content	4 measures

The forms with ! and without ! are musically equivalent: they differ only in the engraving.

7.1 Syntactic rules¶

the token is atomic: no whitespace between %, !, and the number
1 NRK cell = 1 measure: even the forms with span > 1 (%N/%!N for N>1) occupy a single measure per cell. The token appears in each of the N consecutive measures of the run.

Examples (4/4):

N) | a | b | %2  | %2  |
N) | a | b | %!2 | %!2 |
N) | a | b | c | d | %4 | %4 | %4 | %4 |
N) | a | b | c | d | %!4 | %!4 | %!4 | %!4 |

the token must be the only content of its measure (not mixable with notes/chords)
admitted N: {1, 2, 4} (correspond to the standard SMuFL glyphs repeat1Bar, repeat2Bars, repeat4Bars). Other values (%3, %5, …) are parsing errors
for the %N glyph tokens: the SMuFL glyph is drawn only once per run, anchored to the central barline of the run (N=2: barline between m1 and m2; N=4: barline between m2 and m3). The other measures of the run are musically part of the event but do not add graphic notation
do not confuse with the note event repeat ! of neumaRk_notes_and_durations.md §5: the lexer recognizes %! as a single token

7.2 Scope and resolution¶

The symbol applies to the chord-row and to the notes-row. The resolution is independent per row-type: a % in the chord-row inherits from the preceding chord-row; a % in the notes-row inherits from the preceding notes-row.

Classification of a line of only %. Without an explicit marker, a line composed only of % (plus barlines and spaces) is classified according to neumaRk_datapack.md §3.bis.5 TB1bis: at the head of the datapack and in the absence of a real chord-row it is a chord-row of repeats (it inherits the chords, also cross-datapack); after a real chord-row, or if it contains the rest-token r/!, it is a notes-row. To force the opposite reading use the marker (C) for chords, N+/N) for a notes staff).

For each measure of the run, the source is the measure i - N in the same row-type (simple offset). For %2 repeated in a run (m_a m_b → %2 %2), the 1st measure %2 has source m_a, the 2nd has source m_b. Same logic for N=4: each measure of the run of 4 copies from the corresponding offset-4 back.

The resolution walks up the chain: if the source i - N is itself a %/%!, it continues backwards using the N of the source measure encountered, until a "real" measure (non-repeat) is reached. This makes correct the idiomatic case of the run of % (N=1), in which each % repeats the preceding measure:

N) | a | % | % |     → a a a

The 1st % has source a; the 2nd % has as source the 1st %, so it walks back again by 1 up to a. In mixed cases the walk-up uses the offset of the source each time (e.g. | a | b | %2 | %2 | % |: the last % walks up to the 2nd %2, which has source b → the measure equals b). The walk-up limit is 32 steps; beyond that, or if no valid source measure exists, the measure is flagged with E300 (see §7.1 and the rule below).

%/%! are not admitted as the first measure of the piece (and in general if there are no N preceding measures in the same row-type).

7.3 Behavior per layer¶

When the source content is inherited:

notes, chords, rhythm, durations → copied
articulations (staccato, accent, tenuto, …) → copied (they are attributes of the note)
point dynamics (p, f, mf, …) → not re-emitted: the dynamic in force before the source measure continues to apply by standard notational inheritance
spanning dynamics (cresc., decresc., hairpin) → truncated at the boundary of the source measure
lyrics → not copied

The user may add new lyrics or new dynamics aligned to a %/%! measure without conflicting with the symbol (they are parallel layers).

7.4 Edge cases¶

Tie out from the source: in the %! case the copy keeps the initial value tie if the %! measure is not the last of the chain; the tie propagates to the successor. For % the rule is the same, applied to the realized content.
Change of key or meter in the source: it is structural and is not re-applied in the %/%! measure.
Autofill source: if the source measure is a rest-only autofill, the % produces a measure of rests (intentional behavior, not a warning).

8. Markers lines and best practice¶

The barlines (simple and compound — |, ||, |., .|, :|, |:) and the measure decorators can be found in all the musical lines (markers, chords, articulations, notes, dynamics, lyrics).

The only exception is the Format line, which admits neither barlines nor decorators.

The markers line, if present, is the most suitable for containing the flow decorators (DC, D$, coda, etc.).

Since the markers are indicated in square brackets and refer to the start of the measure, if they are preceded by a barline (with eventual modifiers) they must be separated from it by a space to differentiate them from a volta-decorator.

9. Principles of flow resolution¶

the flow is resolved as a linear sequence of measures
the jumps do not introduce temporal ambiguities
each measure has a unique temporal position

This document defines the musical navigation logic of neumaRk.

Flow, Measures, and Repeats¶

1. Measure and barline¶

1.1 Admitted barlines¶

2. Measure decorator¶

Decorators and barlines¶

3. BEGIN decorator (to the right of the barline)¶

3.1 Change of meter and key¶

3.2 Volta (alternative ending)¶

3.2.1 Extension of the volta¶

3.3 Structure signs¶

4. END decorator (to the left of the barline)¶

4.1 Flow jumps¶

4.2 Fine and Coda¶

4.3 Textual decorators¶

5. Order and combination of decorators¶

6. Repeats¶

6.1 Number of executions and open repeat¶

6.1.1 Relation with the textual form [xN]:|¶

7. Measure repeat¶

7.1 Syntactic rules¶

7.2 Scope and resolution¶

7.3 Behavior per layer¶

7.4 Edge cases¶

8. Markers lines and best practice¶

9. Principles of flow resolution¶

6.1.1 Relation with the textual form `[xN]:|`¶