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 si scrive preceduto da uno spazio; la forma incollata (c d e f|) è tollerata e letta allo stesso modo
:|: è il giro di ritornello: chiusura e apertura nello stesso punto, un segno solo
||: e :||: sono grafie tollerate di |: e :|:: si accettano in lettura e la serializzazione le riscrive nella forma canonica. Quel || non è una doppia barra — è il segno di ritornello contato due volte (il heavy-light di MusicXML è già il glifo del ritornello), quindi non si disegna due volte
i segni composti (:|, |:) non ammettono spazi interni, eccetto la label compatta del ritornello di rimando (:xN|, :open|, vedi §6.1)
|. e .| sono la barra finale del brano (thin+thick): per convenzione vive sulla barra iniziale della misura seguente (beg_bar); si propaga fra i sistemi ma non si ripete a inizio rigo (a differenza della doppia ||)
un . da solo non è mai un segno di battuta, in nessuna riga: in N) è un prolungamento della nota precedente (| e f g a . | = a2), nelle altre righe una continuazione o un segnaposto

1.2 Quando esiste una misura¶

Una misura esiste se contiene almeno un token musicale, oppure se fra due segni di battuta c'è almeno uno spazio. La prima e l'ultima stanghetta di un rigo si possono omettere: le quattro scritture seguenti sono equivalenti e fanno due misure ciascuna.

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

N) | | | fa due misure vuote (fra le barre c'è uno spazio); N) ||| non ne fa nessuna.

1.3 Stanghette adiacenti: un punto solo¶

Due segni di battuta senza niente in mezzo non delimitano una misura: sono lo stesso punto di battuta scritto in due pezzi, e quello che portano vale tutto insieme. Serve per il giro di ritornello con cambio di metro (o di tonalità, o di chiave), dove la dichiarazione sta fra i due segni:

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

chiude il ritornello, cambia metro e lo riapre. La forma canonica è :|:(3/4), col giro scritto come segno unico (§1.1), ed è quella che la serializzazione riscrive.

Se entrambi i pezzi dichiarano (|(3/4)|(4/4)), vince quello accanto alla musica che lo userà e l'editor segnala W169, come per l'annuncio ripetuto a fine misura e a inizio della successiva.

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.

Autoraggio: riga note/accordi o riga dei markers `M)`¶

Un decoratore può essere scritto indifferentemente sulla barline della riga note (N))/accordi (C)) oppure sulla riga dei markers (M)): l'effetto su rendering ed esecuzione è identico, perché il decoratore viene comunque associato alla misura allineata. La riga M) è la collocazione consigliata (raccoglie la struttura formale in un unico punto, cfr. neumaRk_markers.md §2.1) ed è l'unica in cui un segno di flusso può stare da solo: è ammessa una barline di solo flusso a inizio sezione, es. M) |@ (coda senza altro testo).

Se lo stesso decoratore compare su entrambe le righe è lecito (serve solo all'allineamento visivo) e non produce warning. Se due righe portano decoratori divergenti sulla stessa misura, vince la riga scritta prima nel datapack — di norma la riga dei markers, che sta in testa — e il parser emette il warning W159 sulla riga che perde. Vale anche fra due righe N) dello stesso sistema (neumaRk_datapack.md §7.3).

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 parentesi quadra 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.2.1 `FINE` ancorato alla nota (riga `A)`)¶

Il FINE su barra (decorator di cui sopra) segna la fine del brano alla stanghetta della misura: è la forma normale e va bene quando il brano finisce a fine misura.

Quando invece il brano deve finire su una nota specifica, anche a metà misura, FINE si scrive come token sulla riga delle articolazioni A), allineato per conteggio alla nota (come ogni token A), i silenzi contano):

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

Qui FINE cade sulla 5ª posizione → nota a4: il brano finisce su quella nota, prima del silenzio e della stanghetta. È reso sopra la nota lo stesso glifo del FINE su barra (medesimo simbolo, dimensione e quota), semplicemente centrato sulla testa invece che appeso alla stanghetta.

Note:

FINE su A) non è un'articolazione di esecuzione: è una direttiva di flusso che usa la riga A) solo come superficie di ancoraggio alla nota. È l'unico segno di flusso ancorabile a una nota; tutti gli altri ($, @, DC, D$, al@, …) restano legati alla barra (riga M)).
Precedenza: il FINE su nota è il più fine. Se la stessa misura porta sia un FINE su barra sia un FINE su nota, il parser emette W167 (ridondanza/ambiguità); nessuno dei due viene scartato.
Il token esatto è FINE (tutto maiuscolo). Forme diverse (es. fine minuscolo) non sono riconosciute e ricadono nella validazione lessicale (W139).

4.3 Decorator testuali¶

Un decorator testuale segue il modello a cornice dei container di testo (neumaRk_text_markup.md §2.1): forme semanticamente equivalenti, che differiscono solo per la cornice grafica:

"<testo>" — nessuna cornice;
["<testo>"] — riquadro (forma di riferimento);
[<testo>] — riquadro, abbreviazione di ["<testo>"];
("<testo>") — cornice tonda.

[D.S.]:|            decorator testuale con riquadro (su ritornello)
"freely":|          decorator testuale senza cornice (su ritornello)
["x4"]:|            identico a [x4]:| (§6.1.1)
[to Coda]|          decorator con riquadro su barline semplice
"let ring"|         decorator senza cornice su barline semplice
("ad lib"):|        decorator con cornice tonda

["xN"] e ["open"] valgono esattamente come [xN] e [open]: indicano il numero di ripetizioni del ritornello (§6.1.1).

Viene visualizzato in alto, al margine destro della misura. Entrambe le forme sono ammesse su qualunque riga musicale (il decorator è proprietà del bordo barline, condiviso dal datapack) e con qualunque barline (semplice |, ritornello :|, ecc.).

Disambiguazione per adiacenza (con la comment-label di C)). Un container ("…", ["…"]/[…], ("…")) incollato alla barline finale (…|, senza spazio) è un decorator di misura; se è spaziato o attaccato a un accordo resta una comment-label (neumaRk_chords.md §8). Es. su C): Cmaj7"voicing" "coda"| → "voicing" è comment-label su Cmaj7, "coda" è decorator sulla barline.

Il decorator ammette il markup testuale definito in neumaRk_text_markup.md. Lo stile di default è plain, size body, con qualunque cornice, nel font dei testi del renderer.

Un ; va a capo (neumaRk_text_markup.md §3bis): la pila cresce verso l'alto dal rigo, le righe sono allineate a destra (a filo della barra finale) e una sola cornice avvolge la pila.

[x2;poi Fine]:|     due righe, un riquadro
"D.S. al Coda;poi Coda"|

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

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|

Regole:

il token è atomico: nessuno spazio fra :, la label e |
N deve avere 1 o 2 cifre; :x1| / :1x| e :x100| / :100x| (o oltre) producono W142 (repeat count fuori range, atteso [2..99] — stesso codice di […]xN in neumaRk_play_and_form.md §3.4.1); il conteggio fuori range è clampato/ignorato
eccezione — lo zero: :x0| / :0x| («esegui 0 volte») sono contraddittori — il materiale non suonerebbe mai — e producono l'errore E302, non un semplice fuori-range come x1/x100
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 Forma testuale `[xN]:|`¶

Il numero di ripetizioni si può scrivere anche come decorator testuale (§4.3) sul segno :|: nella sintassi [xN]:| (e ["xN"]:|, che le è identica) N identifica il numero di ripetizioni del ritornello, come nella forma compatta. Allo stesso modo [open]:| marca il ritornello come aperto.

Forma	Significato
`:xN\|` / `:Nx\|`	ritornello ripetuto `N` volte
`[xN]:\|` / `["xN"]:\|`	ritornello ripetuto `N` volte
`:open\|` / `[open]:\|`	ritornello aperto
`[text]:\|` (altro testo)	testo libero sul ritornello

Le due forme hanno la stessa resa (label xN sopra la barline, allineata a destra) e gli stessi vincoli su N: [2..99], con W142 fuori range ed E302 per lo zero (§6.1). Un testo diverso da xN/open (es. [D.S.], [fade]) è solo testo e non indica ripetizioni.

La forma compatta :xN| è la più breve; quella testuale ammette la cornice (§4.3) e resta la forma per le label diverse da xN/open.

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, …) non sono token validi: E001, e la misura resta vuota (pausa)
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. Sulla voce 2 (N2) il % ripete la misura precedente della stessa voce.

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

10. Codici diagnostici (flusso e ripetizioni)¶

Codice	Significato	Rif.
W139	Validazione lessicale: sequenza fuori-vocabolario (es. `FINE` malformato)	§4.2.1
W142	Repeat count `xN` fuori range (atteso `[2..99]`)	§6.1
E001	`%N` con `N` non ammesso (`%3`, `%5`)	§7.1
W159	Flow-decorator conflict (decorator divergenti sulla stessa barra: vince la riga scritta prima)	§2
W167	`FINE` su barra e `FINE` su nota in conflitto	§4.2.1
E300	Measure-repeat `%` senza misura-sorgente valida	§7.1
E302	Repeat count `x0` (contraddittorio: «esegui 0 volte»), su `:x0\\|` e su `[x0]:\\|`; nei box `PLAY)`/`FORM)` vedi `neumaRk_play_and_form.md`	§6.1

Flusso, Battute e Ripetizioni¶

1. Battuta e segno di battuta (barline)¶

1.1 Segni di battuta ammessi¶

1.2 Quando esiste una misura¶

1.3 Stanghette adiacenti: un punto solo¶

2. Decorator di misura¶

Decorators e segni di battuta¶

Autoraggio: riga note/accordi o riga dei markers M)¶

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.2.1 FINE ancorato alla nota (riga A))¶

4.3 Decorator testuali¶

5. Ordine e combinazione dei decorator¶

6. Ripetizioni¶

6.1 Numero di esecuzioni e ritornello aperto¶

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

10. Codici diagnostici (flusso e ripetizioni)¶

Autoraggio: riga note/accordi o riga dei markers `M)`¶

4.2.1 `FINE` ancorato alla nota (riga `A)`)¶

6.1.1 Forma testuale `[xN]:|`¶