Flusso, Battute e Ripetizioni¶

Questo documento definisce la semantica temporale di neumaRk: battute, segni di battuta, decorator, ripetizioni e salti di flusso.

L’obiettivo è descrivere un sistema deterministico, testuale e leggibile, capace di rappresentare strutture musicali complesse senza ambiguità.

1. Battuta e segno di battuta (barline)¶

Le righe di note e accordi, così come quelle di altro tipo, contengono segni di battuta che delimitano le misure.

1.1 Segni di battuta ammessi¶

I segni di battuta riconosciuti sono:

|    ||    |.    .|    :|    |:

Regole:

il segno di battuta finale di misura deve essere preceduto da uno spazio
i segni composti (:|, |:) non ammettono spazi interni, eccetto la label compatta del ritornello di rimando (:xN|, :open|, vedi §6.1)

2. Decorator di misura¶

I decorator sono simboli o costrutti testuali adiacenti a una barline.

Essi modificano il flusso musicale, la struttura formale o il rendering.

Esistono due classi di decorator:

BEGIN decorator → agiscono all’inizio della misura
END decorator → agiscono alla fine della misura

La loro posizione è semanticamente rilevante.

Decorators e segni di battuta¶

Un decorator appartiene semanticamente a un segno di battuta.

I decorators qualificano il flusso musicale (ripetizioni, salti, coda, fine, ecc.) e sono sempre associati a una barline specifica, non a una misura in senso strutturale.

3. BEGIN decorator (a destra della barline)¶

3.1 Cambio di metro e tonalità¶

Fra parentesi tonde può essere indicato un nuovo metro e/o una nuova tonalità:

|(3/4,Dm)

Regole:

metro e tonalità possono apparire in ordine arbitrario
entrambi sono opzionali
il metro può usare la forma con clave al numeratore (es. [3+2]/8)

Se presenti, questi decorator devono essere i primi, immediatamente adiacenti alla barline.

3.2 Volta (alternative ending)¶

Una parentesi quadra indica una volta:

|[1.]

La volta:

si riferisce all’inizio della misura
può includere un testo arbitrario

3.2.1 Estensione della volta¶

La durata della volta può essere estesa aggiungendo +n:

|[1.]+4

In assenza di estensione, la volta si chiude automaticamente al primo segno di chiusura di ritornello (:|) incontrato entro 4 battute (caso tipico dei finali [1.]).

Se nelle 4 battute successive non compare un :|, la volta non si chiude automaticamente e indica un'uscita (estensione esplicita +n raccomandata in tutti i casi non standard).

3.3 Segni di struttura¶

Altri BEGIN decorator ammessi:

$ → segno
@ → coda

Possono seguire i decorator di cambio metro/tonalità.

4. END decorator (a sinistra della barline)¶

Gli END decorator modificano il flusso al termine della misura.

4.1 Salti di flusso¶

Sono ammessi i seguenti costrutti:

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 e Coda¶

FINE → termine del brano
al@ → salto alla coda

4.3 Decorator testuali¶

Un decorator testuale è espresso in due forme container, semanticamente equivalenti, che differiscono solo per la presenza del box grafico:

[<testo>] — forma con box;
"<testo>" — forma senza box.

[D.S.]:|            decorator testuale con box
"freely":|          decorator testuale senza box
[x4]                decorator testuale con box

Viene visualizzato in alto, al margine destro della misura.

Il decorator ammette il markup testuale definito in neumaRk_text_markup.md. Lo stile di default è plain, size body, in entrambe le forme.

Per il caso particolare di numero di esecuzioni di un ritornello ([xN]:|) o di ritornello aperto ([open]:|), è disponibile anche la forma compatta :xN| / :open| (vedi §6.1), che è interpretata dal player come istruzione di esecuzione.

5. Ordine e combinazione dei decorator¶

Regole di composizione:

i decorator BEGIN precedono sempre il contenuto della misura
i decorator END seguono sempre il contenuto della misura
all’interno di ciascuna classe, l’ordine è semanticamente rilevante
in caso di conflitto, prevale il decorator più vicino alla barline

6. Ripetizioni¶

Le ripetizioni sono indicate tramite i segni di battuta:

|: → inizio ripetizione
:| → fine ripetizione

La semantica delle ripetizioni interagisce con:

volte
segni ($)
DC / D$

La risoluzione del flusso deve essere deterministica.

6.1 Numero di esecuzioni e ritornello aperto¶

Per indicare quante volte eseguire un ritornello, o per marcarlo come aperto (numero non specificato, tipico delle code in stile jazz/pop), il segno :| ammette una label compatta fra i due caratteri:

:xN| (o equivalentemente :Nx|) con N intero in [2..99] → eseguire il ritornello N volte
:open| → ritornello aperto (numero di esecuzioni a discrezione dell'esecutore)

Esempi:

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

Regole:

il token è atomico: nessuno spazio fra :, la label e |
N deve avere 1 o 2 cifre; :x1| / :1x| e :x100| / :100x| (o oltre) sono errore di parsing
open è case-insensitive: :open|, :Open|, :OPEN| sono tutti accettati
la label è renderizzata sopra la barline, allineata a destra (stessa posizione del decorator testuale [xN] di §4.3), nella forma canonica xN indipendentemente dall'ordine usato in input

6.1.1 Relazione con la forma testuale `[xN]:|`¶

La forma compatta :xN| / :open| e la forma con decorator testuale [xN]:| / [open]:| (§4.3) producono la stessa resa grafica, ma hanno semantiche di playback differenti:

Forma	Render	Play
`:xN\|`	box "xN" sopra	executable — il player esegue N volte
`:open\|`	box "open" sopra	executable — repeat aperto (prompt UX)
`[xN]:\|`	box "xN" sopra	decorative — il player usa default (2x)
`[text]:\|`	box "text" sopra	decorative — testo arbitrario

La forma compatta :xN| è una istruzione strutturata che il player legge ed esegue; la forma con decorator testuale è testo informativo per l'umano, e il player la ignora ai fini del conteggio delle ripetizioni (segue il default standard, tipicamente 2 esecuzioni).

Entrambe restano valide. La forma compatta è raccomandata per i ritornelli di rimando dove il numero di esecuzioni deve essere rispettato dal playback; la forma con decorator testuale resta utile per label arbitrarie diverse da xN/open (es. [D.S.], [fade]) oppure quando il numero di esecuzioni è puramente informativo.

7. Ripetizione di misura¶

Il simbolo % indica la ripetizione del contenuto della/e misura/e precedente/i. Esistono sei forme, che distinguono la resa grafica dalla realizzazione esplicita del contenuto, per span di 1, 2 o 4 misure:

Token	Resa	Span
`%`	glifo simile (`repeat1Bar`)	1 misura
`%!`	copia visibile del contenuto	1 misura
`%2`	glifo simile-2 (`repeat2Bars`)	2 misure
`%!2`	copia visibile del contenuto	2 misure
`%4`	glifo simile-4 (`repeat4Bars`)	4 misure
`%!4`	copia visibile del contenuto	4 misure

Le forme con ! e senza ! sono musicalmente equivalenti: differiscono solo nell'engraving.

7.1 Regole sintattiche¶

il token è atomico: nessun whitespace fra %, !, e il numero
1 cell NRK = 1 misura: anche le forme con span > 1 (%N/%!N per N>1) occupano una sola misura per cell. Il token compare in ognuna delle N misure consecutive del run.

Esempi (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 |

il token deve essere l'unico contenuto della sua misura (non miscelabile con note/accordi)
N ammessi: {1, 2, 4} (corrispondono ai glifi SMuFL standard repeat1Bar, repeat2Bars, repeat4Bars). Altri valori (%3, %5, …) sono errore di parsing
per i token %N glyph: il glifo SMuFL è disegnato una sola volta per run, ancorato alla barline centrale del run (N=2: barline fra m1 e m2; N=4: barline fra m2 e m3). Le altre misure del run sono musicalmente parte dell'evento ma non aggiungono notazione grafica
non confondere con la ripetizione di evento nota ! di neumaRk_notes_and_durations.md §5: il lexer riconosce %! come token unico

7.2 Scope e risoluzione¶

Il simbolo si applica alla chord-row e alla notes-row. La risoluzione è indipendente per row-type: un % nella chord-row eredita dalla chord-row precedente; un % nella notes-row eredita dalla notes-row precedente.

Classificazione di una riga di soli %. Senza marker esplicito, una riga composta solo da % (più barline e spazi) è classificata secondo neumaRk_datapack.md §3.bis.5 TB1bis: in testa al datapack e in assenza di una chord-row reale è una chord-row di ripetizioni (eredita gli accordi, anche cross-datapack); dopo una chord-row reale, o se contiene rest-token r/!, è una notes-row. Per forzare la lettura opposta usa il marker (C) per gli accordi, N+/N) per un rigo di note).

Per ogni misura del run, la sorgente è la misura i - N nella stessa row-type (offset semplice). Per %2 ripetuto in run (m_a m_b → %2 %2), la 1ª misura %2 ha sorgente m_a, la 2ª ha sorgente m_b. Stessa logica per N=4: ogni misura del run di 4 copia dalla corrispondente offset-4 indietro.

La risoluzione risale la catena: se la sorgente i - N è essa stessa un %/%!, si prosegue all'indietro usando l'N della misura sorgente incontrata, finché si raggiunge una misura "vera" (non-repeat). Questo rende corretto il caso idiomatico del run di % (N=1), in cui ogni % ripete la misura precedente:

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

La 1ª % ha sorgente a; la 2ª % ha come sorgente la 1ª %, quindi risale ancora di 1 fino ad a. Nei misti la risalita usa l'offset della sorgente di volta in volta (es. | a | b | %2 | %2 | % |: l'ultima % risale alla 2ª %2, che ha sorgente b → la misura vale b). Il limite di risalita è 32 passi; oltre, o se non esiste alcuna misura sorgente valida, la misura è segnalata con E300 (vedi §7.1 e la regola sotto).

%/%! non sono ammessi come prima misura del brano (e in generale se non esistono N misure precedenti nella stessa row-type).

7.3 Comportamento per layer¶

Quando il contenuto sorgente viene ereditato:

note, accordi, ritmo, durate → copiati
articolazioni (staccato, accento, tenuto, …) → copiate (sono attributi della nota)
dinamiche point (p, f, mf, …) → non ri-emesse: la dinamica vigente prima della misura sorgente continua a valere per ereditarietà notazionale standard
dinamiche spanning (cresc., decresc., hairpin) → troncate al confine della misura sorgente
lyrics → non copiate

L'utente può aggiungere nuove lyrics o nuove dinamiche allineate a una misura %/%! senza confliggere col simbolo (sono layer paralleli).

7.4 Casi limite¶

Tie out dalla sorgente: nel caso %! la copia mantiene la legatura di valore iniziale se la misura %! non è l'ultima della catena; la legatura propaga al successore. Per % la regola è la stessa, applicata al contenuto realizzato.
Cambio di chiave o di metro nella sorgente: è strutturale e non viene ri-applicato nella misura %/%!.
Sorgente autofill: se la misura sorgente è una rest-only di autofill, il % produce una misura di pause (comportamento intenzionale, non warning).

8. Righe di markers e best practice¶

I segni di battuta (semplici e composti — |, ||, |., .|, :|, |:) e i decoratori di misura si possono trovare in tutte le righe musicali (markers, accordi, articolazioni, note, dinamiche, lyrics).

L'unica eccezione è la riga di Format, che non ammette né segni di battuta né decoratori.

La riga dei markers, se presente, è quella più indicata per contenere i decoratori di flusso (DC, D$, coda, ecc.).

Dato che i markers sono indicati fra parentesi quadre e si riferiscono all'inizio della battuta, se sono preceduti da segno di battuta (con eventuali modificatori) devono essere da essa distanziati da uno spazio per differenziarsi da un volta-decorator.

9. Principi di risoluzione del flusso¶

il flusso è risolto come una sequenza lineare di misure
i salti non introducono ambiguità temporali
ogni misura ha una posizione temporale unica

Flusso, Battute e Ripetizioni¶

1. Battuta e segno di battuta (barline)¶

1.1 Segni di battuta ammessi¶

2. Decorator di misura¶

Decorators e segni di battuta¶

3. BEGIN decorator (a destra della barline)¶

3.1 Cambio di metro e tonalità¶

3.2 Volta (alternative ending)¶

3.2.1 Estensione della volta¶

3.3 Segni di struttura¶

4. END decorator (a sinistra della barline)¶

4.1 Salti di flusso¶

4.2 Fine e Coda¶

4.3 Decorator testuali¶

5. Ordine e combinazione dei decorator¶

6. Ripetizioni¶

6.1 Numero di esecuzioni e ritornello aperto¶

6.1.1 Relazione con la forma testuale [xN]:|¶

7. Ripetizione di misura¶

7.1 Regole sintattiche¶

7.2 Scope e risoluzione¶

7.3 Comportamento per layer¶

7.4 Casi limite¶

8. Righe di markers e best practice¶

9. Principi di risoluzione del flusso¶

6.1.1 Relazione con la forma testuale `[xN]:|`¶