neumaRk — Flow, Measures, and Repeats¶

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

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

1. Measure and barline¶

Note and chord lines, as well as other musical lines, contain barlines that delimit measures.

1.1 Supported barlines¶

The recognized barline symbols are:

|    ||    |.    .|    :|    |:

Rules:

the final barline of a measure must be preceded by a space;
compound barlines (:|, |:) do not allow internal spaces.

2. Measure decorators¶

Decorators are symbols or textual constructs adjacent to a barline.

They modify musical flow, formal structure, or rendering.

There are two classes of decorators:

BEGIN decorators → act at the beginning of the measure;
END decorators → act at the end of the measure.

Their position is semantically relevant.

Decorators and barlines¶

A decorator semantically belongs to a barline.

Decorators qualify musical flow (repeats, jumps, coda, fine, etc.) and are always associated with a specific barline, not with a measure as an abstract unit.

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

3.1 Time signature and key changes¶

A new time signature and/or key may be specified inside parentheses:

|(3/4,Dm)

Rules:

time signature and key may appear in arbitrary order;
both are optional;
the time signature may use the extended form with internal subdivision (e.g. [3+2]/8).

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

3.2 Volta (alternative endings)¶

Square brackets indicate a volta:

|[1.]

A volta:

refers to the beginning of the measure;
may include arbitrary text.

3.2.1 Volta extension¶

The duration of a volta may be extended by appending +n:

|[1.]+4

If no extension is specified:

the volta ends at the repeat sign;
or represents an exit.

3.3 Structural symbols¶

Other supported BEGIN decorators:

$ → segno
@ → coda

They may follow time/key change decorators.

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

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

4.1 Flow jumps¶

The following constructs are supported:

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¶

Text enclosed in square brackets:

[x4]

is rendered above the staff, at the right margin of the measure, enclosed in a box.

5. Order and combination of decorators¶

Composition rules:

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

6. Repeats¶

Repeats are indicated using barline symbols:

|: → repeat start;
:| → repeat end.

Repeat semantics interact with:

voltas;
segni ($);
DC / DS instructions.

Flow resolution must be deterministic.

7. Markers lines and best practices¶

The | barline symbol may appear in all lines (markers, chords, articulations, notes, dynamics, lyrics).

Compound barlines (:|, |:, ||, .|, |.), as well as measure decorators, may appear only in markers, chords, and notes lines.

If present, the markers line is the most appropriate place to contain them.

Since markers are enclosed in square brackets and refer to the beginning of a measure, when preceded by a barline (with possible modifiers) they must be separated from it by a space, to distinguish them from volta decorators.

8. Flow resolution principles¶

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

This document defines the musical navigation logic of neumaRk.