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 is written preceded by a space; the glued form (c d e f|) is tolerated and read the same way
:|: is the repeat turnaround: close and open at the same point, a single sign
||: and :||: are tolerated spellings of |: and :|:: they are accepted on input and serialization rewrites them into the canonical form. That || is not a double barline — it is the repeat sign counted twice (MusicXML's heavy-light is already the repeat glyph), so it is not drawn twice
the compound signs (:|, |:) do not admit internal spaces, except the compact label of the count-in repeat (:xN|, :open|, see §6.1)
|. and .| are the piece's final barline (thin+thick): by convention it lives on the starting barline of the following measure (beg_bar); it propagates across systems but is not repeated at the start of a staff (unlike the double ||)
a lone . is never a barline, on any row: in N) it prolongs the preceding note (| e f g a . | = a2), on the other rows it is a continuation or a placeholder

1.2 When a measure exists¶

A measure exists if it contains at least one musical token, or if there is at least one space between two barlines. The first and the last barline of a line may be omitted: the four writings below are equivalent, and each makes two measures.

N) a | b        N) | a | b        N) | a | b |        N) a | b |

N) | | | makes two empty measures (there is a space between the bars); N) ||| makes none.

1.3 Adjacent barlines: a single point¶

Two barlines with nothing between them do not delimit a measure: they are the same barline point written in two pieces, and what they carry applies together. This serves the repeat turnaround with a meter change (or a key, or a clef change), where the declaration sits between the two signs:

N) | c d e f :|(3/4)|: e f g |

closes the repeat, changes the meter and opens it again. The canonical form is :|:(3/4), with the turnaround written as a single sign (§1.1), and that is what serialization rewrites.

If both pieces declare (|(3/4)|(4/4)), the one next to the music that will use it wins and the editor reports W169, as for an announcement repeated at the end of one measure and the start of the next.

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.

Authoring: notes/chords line or markers line `M)`¶

A decorator may be written either on the barline of the notes (N))/chords (C)) line or on the markers (M)) line: the effect on rendering and execution is identical, because the decorator is associated with the aligned measure in both cases. The M) line is the recommended location (it gathers the formal structure in a single place, see neumaRk_markers.md §2.1) and is the only line where a flow sign may stand alone: a flow-only barline at the start of a section is allowed, e.g. M) |@ (coda with no other text).

If the same decorator appears on both lines it is legal (it only serves the visual alignment) and produces no warning. If two lines carry divergent decorators on the same measure, the line written first in the datapack wins — normally the markers line, which comes first — and the parser emits warning W159 on the losing line. This also holds between two N) rows of the same system (neumaRk_datapack.md §7.3).

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.2.1 Note-anchored `FINE` (row `A)`)¶

The barline FINE (the decorator above) ends the piece at the measure's barline: this is the normal form and is what you want when the piece ends at a measure boundary.

When instead the piece must end on a specific note, possibly mid-measure, FINE is written as a token on the articulations row A), count-aligned to the note (like every A) token — rests are counted):

A) .  . . . FINE
N) a8 b c d  a4 r |

Here FINE falls on the 5th slot → note a4: the piece ends on that note, before the rest and the barline. The same glyph as the barline FINE is drawn above the note (identical symbol, size and lane height), simply centered on the notehead instead of hung at the barline.

Notes:

FINE on A) is not a performance articulation: it is a flow directive that uses the A) row only as a note-anchoring surface. It is the only flow sign that can be anchored to a note; all others ($, @, DC, D$, al@, …) remain barline-bound (row M)).
Precedence: the note-anchored FINE is the finer-grained one. If the same measure carries both a barline FINE and a note FINE, the parser emits W167 (redundancy/ambiguity); neither is discarded.
The exact token is FINE (all caps). Other forms (e.g. lowercase fine) are not recognized and fall under lexical validation (W139).

4.3 Textual decorators¶

A textual decorator follows the frame model of textual containers (neumaRk_text_markup.md §2.1): semantically equivalent forms that differ only in the graphic frame:

"<text>" — no frame;
["<text>"] — box (reference form);
[<text>] — box, shorthand for ["<text>"];
("<text>") — round frame.

[D.S.]:|            textual decorator in a box (on repeat)
"freely":|          textual decorator without a frame (on repeat)
["x4"]:|            same as [x4]:| (§6.1.1)
[to Coda]|          decorator in a box on a plain barline
"let ring"|         decorator without a frame on a plain barline
("ad lib"):|        decorator in a round frame

["xN"] and ["open"] behave exactly like [xN] and [open]: they give the number of repeats of the section (§6.1.1).

It is displayed at the top, at the right margin of the measure. Both forms are allowed on any music row (the decorator is a property of the barline border, shared by the datapack) and with any barline (plain |, repeat :|, etc.).

Adjacency disambiguation (vs the comment-label of C)). A container ("…", ["…"]/[…], ("…")) glued to the closing barline (…|, no space) is a measure decorator; when spaced or attached to a chord it stays a comment-label (neumaRk_chords.md §8). E.g. on C): Cmaj7"voicing" "coda"| → "voicing" is a comment-label on Cmaj7, "coda" is a decorator on the barline.

The decorator admits the text markup defined in neumaRk_text_markup.md. The default style is plain, body size, with any frame, in the renderer's text font.

A ; breaks the line (neumaRk_text_markup.md §3bis): the stack grows upward from the staff, lines are right-aligned (flush with the closing barline) and a single frame wraps the stack.

[x2;then Fine]:|    two lines, one box
"D.S. al Coda;then Coda"|

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

N) |: a b c d | e f g a :x8|

N) |: a b c d | e f g a :8x|

N) |: 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) produce W142 (repeat count out of range, expected [2..99] — same code as […]xN in neumaRk_play_and_form.md §3.4.1); the out-of-range count is clamped/ignored
exception — zero: :x0| / :0x| ("execute 0 times") are contradictory — the material would never be performed — and produce the error E302, not a mere out-of-range like x1/x100
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 Textual form `[xN]:|`¶

The number of repeats can also be written as a textual decorator (§4.3) on the :| sign: in the syntax [xN]:| (and ["xN"]:|, which is identical) N identifies the number of repeats of the repeated section, as in the compact form. Likewise [open]:| marks the repeat as open.

Form	Meaning
`:xN\|` / `:Nx\|`	section repeated `N` times
`[xN]:\|` / `["xN"]:\|`	section repeated `N` times
`:open\|` / `[open]:\|`	open repeat
`[text]:\|` (other text)	free text on the repeat

The two forms have the same rendering (an xN label above the barline, right-aligned) and the same constraints on N: [2..99], with W142 out of range and E302 for zero (§6.1). Text other than xN/open (e.g. [D.S.], [fade]) is just text and does not indicate repeats.

The compact form :xN| is the shortest; the textual one accepts a frame (§4.3) and remains the form for labels other than xN/open.

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 not valid tokens: E001, and the measure stays empty (a rest)
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. On voice 2 (N2) the % repeats the previous measure of the same voice.

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

10. Diagnostic codes (flow and repeats)¶

Code	Meaning	Ref.
W139	Lexical validation: out-of-vocabulary sequence (e.g. malformed `FINE`)	§4.2.1
W142	Repeat count `xN` out of range (expected `[2..99]`)	§6.1
E001	`%N` with a non-admitted `N` (`%3`, `%5`)	§7.1
W159	Flow-decorator conflict (divergent decorators on the same barline: the line written first wins)	§2
W167	`FINE` on a barline and `FINE` on a note in conflict	§4.2.1
E300	Measure-repeat `%` with no valid source measure	§7.1
E302	Repeat count `x0` (contradictory: "execute 0 times"), on `:x0\\|` and on `[x0]:\\|`; for `PLAY)`/`FORM)` boxes see `neumaRk_play_and_form.md`	§6.1

Flow, Measures, and Repeats¶

1. Measure and barline¶

1.1 Admitted barlines¶

1.2 When a measure exists¶

1.3 Adjacent barlines: a single point¶

2. Measure decorator¶

Decorators and barlines¶

Authoring: notes/chords line or markers line M)¶

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.2.1 Note-anchored FINE (row A))¶

4.3 Textual decorators¶

5. Order and combination of decorators¶

6. Repeats¶

6.1 Number of executions and open repeat¶

6.1.1 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¶

10. Diagnostic codes (flow and repeats)¶

Authoring: notes/chords line or markers line `M)`¶

4.2.1 Note-anchored `FINE` (row `A)`)¶

6.1.1 Textual form `[xN]:|`¶