Play directive¶

Questo documento definisce la sintassi e la semantica della play directive: un meccanismo per cambiare in modo locale lo style e il tempo del brano, agendo a partire da una misura specifica e restando in vigore fino a una nuova direttiva.

La play directive risolve l'esigenza di lead sheet con sezioni a tempo o groove diversi (es. "vamp till cue" rallentando, "double-time" su un solo, cambio da swing a latin a metà brano) senza ricorrere a brani distinti.

1. Definizione¶

Una play directive è un token della riga M) (Markers) che dichiara, in modo locale, uno o entrambi i seguenti elementi:

uno style (descrizione testuale del carattere musicale);
un tempo, espresso come BPM esplicito oppure come metric modulation (relazione metrica fra due figure NRK).

La play directive non è un decoratore di barline: non si attacca al segno | e non appartiene alla famiglia dei decoratori di misura ([1.] volta, (3/4,Dm) cambio metro/tonalità). È un token autonomo che convive con i marker testuali nella riga M).

2. Sintassi¶

2.1 Forma generale¶

Due forme alternative:

(=[Style][,Tempo])         con prefisso `=` (Style/BPM/combinato)
(<figura>=<figura>)        metric modulation pura (senza prefisso)

Dentro le parentesi tonde:

Il prefisso = apre una direttiva con slot Style e/o Tempo (BPM o metric modulation), distinguendola da un cambio metro o tonalità (3/4,Dm).
Una direttiva di sola metric modulation (es. (4=4.)) si scrive senza prefisso =: la = interna fra due figure NRK è già auto-disambiguante rispetto agli altri token in parentesi.

Quando il prefisso = è presente e Style/Tempo sono entrambi dichiarati, l'ordine è fisso: Style prima, Tempo dopo, separati da virgola.

2.2 Slot Style¶

Testo libero che descrive il carattere musicale (es. Rock, Fast swing, rock ballad, bossa, funk). Valgono le stesse regole testuali dello slot HS) Style dell'header (neumaRk_header.md §11.2):

testo libero multi-parola, spazi interni ammessi;
virgole interne ammesse (es. Fast, dirty swing): il parser ricostruisce lo Style usando la regola "parse from end" descritta sotto;
nessun vincolo di capitalization (il rendering preserva la grafia);
non deve collidere con pattern interpretabili come Tempo (vedi §2.3 e §3.2).

2.2.1 Disambiguazione Style/Tempo ("parse from end")¶

Quando la direttiva contiene una virgola, il parser cerca l'ultima virgola e prova a interpretare ciò che segue come Tempo (BPM o metric modulation). Se il match riesce → split lì (Style = tutto a sinistra, Tempo = tutto a destra). Se fallisce, il body intero è trattato come un unico slot (Style se l'utente non ha tentato un Tempo, oppure Tempo-only se non ci sono virgole e il body è un Tempo valido).

Conseguenze pratiche:

Body	Style	Tempo
`=Rock,120bpm`	`Rock`	120bpm
`=Fast, dirty swing, 180bpm`	`Fast, dirty swing`	180bpm
`=swing, 4=4.`	`swing`	4=4.
`=foo, bar` (no Tempo finale)	`foo, bar`	—
`=120bpm` (no virgola, è Tempo)	—	120bpm

2.3 Slot Tempo¶

Due forme alternative, mutuamente esclusive:

2.3.1 BPM esplicito¶

Nbpm

dove N è un intero a 2 o 3 cifre (range 10–999), seguito immediatamente dal suffisso bpm (case-insensitive: bpm, BPM, Bpm tutti ammessi). Esempi:

60bpm     120bpm     200bpm     90BPM

Range fuori bounds (5bpm, 1000bpm) produce warning W136. Decimali (120.5bpm) non sono ammessi (errore di parsing).

2.3.2 Metric modulation¶

<figura-precedente>=<figura-nuova>

dove ciascun lato è una figura NRK (1, 2, 4, 8, 16, 32, con dotted . e tuplet t ammessi). Convenzione standard (Grove, Carter): il valore a sinistra è una figura nel tempo precedente, il valore a destra è una figura nel tempo nuovo; le due figure hanno la stessa durata fisica. Esempi:

4=2     ♩ = 𝅗𝅥    (la semiminima del tempo precedente vale come minima nuova → double-time)
4=4.    ♩ = ♩.   (la semiminima precedente vale come semiminima puntata nuova → accelera)
2=4     𝅗𝅥 = ♩    (la minima precedente vale come semiminima nuova → half-time)
4.=4    ♩. = ♩   (la semiminima puntata precedente vale come semiminima nuova → rallenta)
8t=8    ♪₃ = ♪   (la croma di terzina precedente vale come croma nuova → accelera)

La metric modulation è executable: il player ricalcola il BPM effettivo dalla relazione metrica applicata al currentBPM corrente (formula in §5.2). Figure non valide (es. 5=4, 4=k) producono warning W137.

2.4 Esempi sintattici¶

(=Rock,120bpm)                 style + tempo
(=swing,4=4.)                  style + metric modulation
(=fast swing)                  solo style (multi-parola)
(=Fast, dirty swing, 180bpm)   style con virgole interne + tempo
(=foo, bar)                    solo style con virgola (no Tempo finale)
(=120bpm)                      solo BPM
(8=4)                          solo metric modulation (NO prefisso `=`)

Forme non valide:

(=)                        W134 — direttiva vuota
(=120bpm,Rock)             W135 — ordine slot invertito
(=5bpm)                    W136 — BPM fuori range
(4=q)                      W137 — figura NRK non valida

3. Posizione strutturale¶

3.1 Solo nella riga `M)`¶

Una play directive può apparire esclusivamente in una riga di Markers (M), esplicita o dedotta secondo neumaRk_markers.md §2). La sua presenza in qualunque altra riga musicale (C), N), A), D), L), F)) produce warning W138.

3.2 Co-locazione con marker testuali¶

Una play directive convive liberamente con marker testuali ([Mark], "freely") nella stessa misura della riga M). La disambiguazione è per delimitatori:

Token	Tipo
`[…]` / `"…"`	marker testuale
`(=…)`	play directive (Style/BPM/combinato)
`(fig=fig)`	play directive (metric modulation pura)
`(…)` altro	decorator di barline (cambio metro/key) — non in `M)`

Esempio:

M) | [A] (=Rock,120bpm) |

Misura 1 contiene sia il marker [A] sia la play directive che imposta Rock 120 BPM dalla stessa misura in poi.

L'ordine fra marker testuali e play directive è libero nella stessa misura: il parser identifica i token per delimitatori.

3.3 Ancoraggio temporale¶

Una play directive si applica a partire dal beat 1 della misura di apparizione, e resta in vigore fino a una nuova play directive (vedi §4).

Non sono ammessi cambiamenti mid-bar: la posizione orizzontale del token nella riga M) non altera il punto di applicazione, che è sempre l'inizio della misura.

4. Persistenza e contesto¶

4.1 State machine `currentStyle` / `currentBPM`¶

Il contesto musicale persistente del brano (neumaRk_specification.md §2.1) include due variabili cross-datapack:

currentStyle — inizializzato da HS) Style dell'header;
currentBPM — inizializzato da HB) BPM dell'header.

Ogni play directive aggiorna una o entrambe le variabili, a partire dalla misura di apparizione. Le variabili restano poi in vigore fino a una nuova play directive, attraversando i confini fra datapack.

4.2 Direttive a slot singolo¶

Una direttiva che dichiara un solo slot aggiorna solo quella variabile, lasciando l'altra invariata:

M) | (=Rock,120bpm) | | (=fast swing) | (2=4) |

Misura 1: currentStyle ← Rock, currentBPM ← 120.
Misura 3: currentStyle ← fast swing, currentBPM resta 120.
Misura 4: currentBPM ← currentBPM × (2/4) = 60 (metric modulation), currentStyle resta "fast swing".

4.3 Niente reset esplicito¶

Non esiste un token speciale per "tornare ai valori dell'header". Per ripristinare lo style/BPM iniziale si ridichiara esplicitamente:

HS) swing
HB) 140

…
M) | (=Rock,80bpm) | … | (=swing,140bpm) |    ← ripristino esplicito

Questa scelta mantiene la spec ortogonale: ogni direttiva è un'azione positiva, non c'è semantica nascosta di "spegnimento".

5. Semantica del player¶

5.1 Executable¶

Le play directive sono istruzioni eseguibili dal player runtime:

un cambio di currentBPM (esplicito o via metric modulation) altera immediatamente la velocità di esecuzione;
un cambio di currentStyle segnala al motore di accompagnamento di cambiare groove (Rock → Bossa → Swing produce pattern diversi di batteria, basso, chitarra di accompagnamento).

L'effettiva mappatura style → groove è responsabilità del player e non è definita da questa specifica. Style sconosciuti al player sono trattati come fallback al groove di default, senza errore.

5.2 Metric modulation: calcolo del BPM¶

Convenzione (musicale standard, vedi Grove Music Online ed Elliott Carter): in una metric modulation S = D il valore a sinistra è una figura nel tempo precedente, il valore a destra è una figura nel tempo nuovo. Le due figure hanno la stessa durata fisica.

Da questa equivalenza si deriva:

dur(S) × (60 / oldBPM) = dur(D) × (60 / newBPM)
⟹ newBPM = oldBPM × dur(D) / dur(S)

dove dur(F) è la durata della figura NRK F in beat unitari (quarter = 1, whole = 4, half = 2, eighth = 0.5; dotted = 1.5×; tuplet t = 2/3×).

Esempi (assumendo currentBPM = 120):

Modulation	newBPM	Effetto musicale
`4=2`	240	double-time (old ♩ → new 𝅗𝅥)
`4=4.`	180	accelera (old ♩ → new ♩.)
`8t=8`	180	accelera (old ♪₃ → new ♪)
`2=4`	60	half-time (old 𝅗𝅥 → new ♩)
`4.=4`	80	rallenta (old ♩. → new ♩)

6. Render¶

6.1 Fascia marker¶

Tutte le play directive sono renderizzate nella stessa fascia dei marker (sopra il rigo), allineate orizzontalmente al beat 1 della misura di apparizione.

6.2 Style¶

Lo style è renderizzato come testo italic, dimensione body. Quando co-localizzato con un marker testuale nella stessa misura, il renderer applica un offset verticale per evitare sovrapposizione, mantenendo entrambi visibili.

6.3 Tempo BPM esplicito¶

Nbpm è renderizzato in notazione tradizionale:

♩ = N

dove la figura della pulsazione è derivata dal denominatore del metro corrente (4/4 → ♩, 6/8 → ♪., 3/2 → 𝅗𝅥, ecc.). In assenza di un metro identificabile, default ♩.

6.4 Metric modulation¶

figura₁=figura₂ è renderizzato in notazione tradizionale come:

glyph(figura₁) = glyph(figura₂)

dove glyph(F) è la testa di nota nera/bianca/aperta della figura F, con dot se dotted, con ³ (o equivalente) se tuplet.

Esempi:

4=4.    →   ♩ = ♩.
8=4     →   ♪ = ♩
8t=8    →   ♪³ = ♪

6.5 Style + Tempo combinati¶

Quando una direttiva contiene entrambi gli slot, il render presenta style sopra il tempo in due righe verticali, oppure sulla stessa riga separati da spazio. La scelta è del renderer.

7. Diagnostica¶

7.1 Codici diagnostici¶

Codice	Descrizione
W134	Direttiva vuota `(=)`: nessuno slot dichiarato
W135	Ordine slot invertito: tempo prima di style
W136	BPM fuori range (atteso intero 10–999)
W137	Figura NRK non valida in metric modulation
W138	Play directive in riga diversa da `M)`

7.2 Style sconosciuto¶

Uno style non riconosciuto dal player (es. (=mood music)) non è un errore: viene rispettato come testo descrittivo e ignorato dal motore di accompagnamento (fallback al groove di default).

7.3 BPM = 0 o negativo¶

Esclusi dal range; produce W136.

7.4 Direttive ridondanti¶

Una direttiva che riasserisce esattamente i valori correnti (es. (=Rock,120bpm) quando currentStyle="Rock" e currentBPM=120) è ammessa, non genera warning. Il player la applica come no-op.

8. Esempi¶

8.1 Cambio tempo a metà brano¶

HS) swing
HB) 140

…
M) | [Solo] | | | (=200bpm) | | | | |

Solo che parte a 140 BPM; dalla misura 4 in poi accelera a 200 BPM.

8.2 Cambio style + tempo combinato¶

M) | [Intro] (=Rock,120bpm) | | | [A] | | (=swing,160bpm) | |

Misura 1: marker [Intro] + setup Rock 120 BPM.
Misura 4: marker [A] (style e tempo invariati).
Misura 6: switch a swing 160 BPM.

8.3 Metric modulation¶

M) | (=swing,120bpm) | | | (2=4) | | | | (4=2) | | |

Misura 1: swing a 120 BPM.
Misura 4: half-time (currentBPM = 60).
Misura 8: double-time rispetto al precedente (currentBPM = 120, torna al valore iniziale).

8.4 Style multi-parola¶

M) | (=Fast swing,200bpm) |

Style "Fast swing" (due parole, spazio interno ammesso), 200 BPM.

8.5 Vamp till cue con cambio style¶

M) | [A] | | | | [? Vamp] (=funk,90bpm) | | | (=swing,140bpm) [B] |

Misure 1–4: sezione A (style/tempo dall'header).
Misure 5–7: vamp in funk a 90 BPM (la sezione collassabile [? Vamp] è definita in neumaRk_markers.md §4).
Misura 8: ritorno a swing 140 BPM, sezione B.

8.6 Solo metric modulation¶

HS) jazz
HB) 120

…
M) | [Theme] | | (4=4.) | | | (4.=4) | |

Tema a 120 BPM; dalla misura 3 accelera a 180 BPM (la semiminima precedente diventa una semiminima puntata nel nuovo tempo, quindi le nuove semiminime sono più corte); dalla misura 6 si torna a 120 BPM (4.=4: la semiminima puntata precedente diventa la nuova semiminima).

9. Riassunto¶

Concetto	Sintassi	Sezione
Direttiva Style/BPM	`(=[Style][,Tempo])`	§2.1
Metric modulation pura	`(figura=figura)` (senza prefisso `=`)	§2.1
Style	testo libero multi-parola	§2.2
Tempo BPM	`Nbpm` (intero 10–999)	§2.3.1
Metric modulation	`figura=figura` (NRK valide)	§2.3.2
Posizione	solo riga `M)`, beat 1 misura	§3
Persistenza	cross-datapack, fino a nuova direttiva	§4
Semantica	executable (player applica)	§5
Render	notazione tradizionale (♩ = N, ♩ = ♩.)	§6

Le play directive estendono le indicazioni globali dell'header (HS), HB)) con la possibilità di cambi locali durante il brano, preservando la natura testuale e parsabile del linguaggio.

Questo documento definisce la play directive come meccanismo locale di controllo style e tempo in neumaRk, completando il sistema di indicazioni performative del linguaggio.