PLAY) e FORM)¶

Questo documento definisce la sintassi e la semantica delle due sezioni di neumaRk dedicate alla forma del brano:

PLAY) — sub-programma di esecuzione, inline fra datapack, letto dal player nell'ordine del documento;
FORM) — descrizione panoramica della forma, una sola per documento, posizionata in fondo, per uso umano e di indicizzazione.

Le due sezioni condividono la stessa grammatica di box di sezione e lo stesso vocabolario di postfix, ma differiscono per posizione, molteplicità e ruolo semantico (imperativo vs descrittivo).

1. Definizione¶

1.1 PLAY)¶

Una sezione PLAY) contiene un sub-programma di esecuzione: una sequenza di box di sezione (con eventuali ripetizioni, dinamiche, fermate, prosa libera) che il player esegue al momento in cui la incontra nel documento.

Più sezioni PLAY) possono coesistere nello stesso documento; sono lette dall'alto in basso, nell'ordine in cui appaiono.

1.2 FORM)¶

Una sezione FORM) contiene una descrizione panoramica della forma del brano (es. "AABA con coda", oppure prosa estesa che dettaglia articolazione e dinamica delle sezioni). Esiste al massimo una FORM) per documento, posizionata in fondo.

FORM) non è eseguibile dal player: ha valore descrittivo, per il lettore umano e per l'indicizzazione/ricerca.

In una playlist, una voce può dichiarare un proprio form che sostituisce la FORM) del brano per quell'occorrenza ("la forma di stasera è questa"). È un overlay descrittivo a livello di scaletta, non eseguito; PLAY), essendo posizionale, non è esprimibile a quel livello. Vedi neumaRk_collections.md §8.

1.3 Distinzione semantica¶

Aspetto	`PLAY)`	`FORM)`
Ruolo	imperativo ("esegui questo")	descrittivo ("ecco la forma")
Molteplicità	multiple, inline	al massimo una, in fondo
Player	esegue	ignora
Uso	playback, sketch di esecuzione	summary, ricerca, didattica

La scelta fra "il player esegue PLAY" e "il player segue il flusso naturale dei datapack" non è una proprietà del documento: è una preference utente salvata nello user-index (toggle UI). Il documento contiene entrambe le forme di informazione; l'utente decide cosa visualizzare/eseguire.

2. Posizione strutturale¶

2.1 PLAY)¶

È una riga di sezione, marcata da PLAY) come primo token.
Compare fra datapack, mai dentro un datapack.
È non ricorsiva by design: una PLAY) non può apparire come riga interna di un'altra PLAY). Garanzia statica del parser.
Una PLAY) può estendersi su più righe del documento: il newline è whitespace dentro la sezione (vedi §6).

La sezione PLAY) termina al primo dei seguenti eventi:

inizio del datapack successivo (riga che apre con un marcatore musicale M), C), N), A), D), L), F));
inizio di un'altra sezione (PLAY), FORM));
fine del documento.

2.2 FORM)¶

È una riga di sezione, marcata da FORM) come primo token.
Compare alla fine del documento, dopo l'ultimo datapack.
È unica per documento. Più FORM) producono warning W140.
Una FORM) può estendersi su più righe (newline = whitespace).

FORM) termina solo a fine documento.

3. Grammatica del box di sezione¶

Sia in PLAY) sia in FORM), l'unità atomica è il box di sezione:

SECTION_BOX  := TOP_LABEL? '[' NAME ('|' BARS)? ']' POSTFIX*
TOP_LABEL    := '"text"'           // adiacente, no spazio
POSTFIX      := REPEAT | DYNAMIC | HAIRPIN | KEYWORD | BOTTOM_LABEL
                                    // tutti adiacenti al precedente

Tutti i token del box sono adiacenti: nessuno spazio fra top-label, parentesi quadre, postfix.

3.1 NAME¶

Il NAME dentro […] è il nome di una sezione definita da una riga M) del documento (neumaRk_markers.md §3). Il matching è per text-equality sul contenuto della sezione (dopo strip del markup, vedi §3.2 di neumaRk_text_markup.md §7.1).

Il binding è selettivo: vengono considerate solo le sezioni […] di M) (incluse le collassabili [? NAME], con il prefisso ? ignorato nel matching). Le annotazioni "…" di M) non sono referenziabili da PLAY) / FORM) (vedi neumaRk_markers.md §3.1).

Esempi:

[A]       riferisce una sezione [A] in M)
[Intro]   riferisce [Intro] o [? Intro] (prefisso ? ignorato)
[Solo 1]  multi-parola, riferisce [Solo 1] o [? Solo 1]

Una "freely" in M) non è target valido: [freely] in PLAY/FORM sarebbe reference broken (vedi §7.3).

Se il NAME non corrisponde a nessun marker definito nel documento, il box è reference broken: viene renderizzato come testo non-cliccabile, non eseguito, e non genera errore o warning (vedi §7.3).

3.2 Durata in misure `[NAME|BARS]`¶

Opzionale: un | interno e un numero di battute.

[A|8]     A per 8 misure (informativo)
[B|4]     B per 4 misure
[A]       A senza durata dichiarata

BARS è un intero positivo (1–999). Decimali, zero o negativi producono warning W141.

La durata in [NAME|BARS] ha valore puramente informativo: è un hint grafico per il lettore. Non viene confrontata con l'estensione reale della sezione marcata M); è responsabilità di chi scrive mantenere coerenza. Nessun warning o errore in caso di discrepanza.

Le durate sono ammesse solo in PLAY) / FORM). Un marker in M) non ammette |N (vedi neumaRk_markers.md).

3.3 Top e bottom label¶

Top label: container "…" adiacente prima di [. Bottom label: container "…" adiacente dopo la parentesi quadra chiusa (può apparire come postfix in qualsiasi ordine, vedi §3.4).

"Tema"[A|8]                  solo top
[A|8]"Variazione"            solo bottom
"Tema"[A|8]"con feeling"     top + bottom

Le label ammettono solo il container "…" (senza box). La forma […] collide grammaticalmente con il box di sezione e non è ammessa come label.

Le label sono soggette al markup unificato di neumaRk_text_markup.md. Stile di default: plain, dimensione ridotta.

3.4 Postfix¶

Sono tutti adiacenti al token precedente (no spazi). L'ordine fra postfix è libero: il parser identifica ogni postfix per la sua forma. La pluralità è ammessa solo per la bottom label (una sola per box) e per le keyword (più keyword distinte possibili).

3.4.1 Repeat count¶

xN con N in 2–99 indica numero di esecuzioni:

[A|8]x2       esegui A due volte (×2)
[A|8]x4       esegui A quattro volte

x1 o x0 o xN con N > 99 produce warning W142.

3.4.2 Dynamic¶

Dynamic puntuale del vocabolario D) (vedi neumaRk_dynamics.md §3.1):

[A|8]ff       sezione A a fortissimo
[B|4]p        sezione B a piano

Vale per tutta la durata della sezione.

3.4.3 Hairpin¶

< o > adiacenti aprono un hairpin solo dentro il box di apertura: si chiude alla prossima dynamic adiacente, anch'essa dentro lo stesso postfix-stack.

[A|8]<ff      cresc. fino a ff alla fine della sezione
[B|4]>p       decresc. fino a p

Hairpin non cross-box: [A|8]< [B|4]ff apre un hairpin che non trova chiusura nel box A e viene chiuso implicitamente a fine box. Nessun errore, render decide la rappresentazione.

3.4.4 Keyword¶

Famiglia &keyword, case-insensitive, prefix per estensioni future.

Keyword	Effetto
`&fermata`	corona sul beat finale della sezione
`&caesura`	cesura dopo la sezione
`&breath`	respiro dopo la sezione
`&GP`	grand pause dopo la sezione
`&niente`	dinamica "al niente" (decresc. fino al silenzio)

Le keyword sono riservate: keyword sconosciute producono errore W143. La lista è estendibile in versioni future della spec.

3.4.5 Bottom label¶

Container "…" adiacente, vedi §3.3.

3.5 Esempi di box completi¶

[A]                            riferimento minimale
[A|8]                          A per 8 misure
"Tema"[A|8]                    A con top label
[A|8]x2&fermata                A ripetuto 2× con corona finale
"Tema"[A|8]ff<>p"crescendo"x2  combinazione complessa
[FREE IMPRO!]                  reference broken (no marker omonimo)

4. Token speciali ammessi in PLAY/FORM¶

Oltre ai box di sezione, sono ammessi:

Token	Effetto
`$`	segno (segno musicale, target di D.S.)
`@`	coda (target di D.C. al Coda)
`&fermata`	corona stand-alone (fuori da un box)

Questi token mantengono la stessa semantica dei decorator inline omonimi delle righe musicali (vedi neumaRk_flow_and_repeats.md).

5. Prosa libera¶

Tutto ciò che non è un token strutturale (box, &keyword, $, @) è prosa libera in modalità markup neumaRk_text_markup.md.

PLAY) [Intro] then go to [A|8] twice [A|8]x2 finally [Outro]

In questo esempio "then go to", "twice", "finally" sono prosa libera interpolata fra box. Vengono renderizzate come testo descrittivo nel display della PLAY (es. in una banda separata o accanto al box).

Il player ignora la prosa libera in PLAY): esegue solo i box e i token strutturali. La prosa libera è valore esclusivamente informativo per il lettore.

In FORM), l'intero contenuto è prosa descrittiva con box di sezione interpolati: il player non esegue nulla di FORM) in ogni caso.

6. Whitespace e continuazione¶

6.1 Newline = whitespace, blank line = terminator¶

Dentro PLAY) e FORM), un singolo newline ha lo stesso valore di uno spazio: la sezione può estendersi su quante righe l'utente preferisce, semplicemente proseguendo (eventualmente con indentazione) sulla riga successiva.

PLAY) [Intro]
      [A|8]x4
      [B|8]
      [A|8]
      [Outro]&fermata

è equivalente a:

PLAY) [Intro] [A|8]x4 [B|8] [A|8] [Outro]&fermata

Una riga vuota (blank line) invece chiude la sezione, coerentemente con la convenzione del resto del linguaggio NRK dove una blank line separa i datapack. Quanto segue è quindi interpretato fuori dalla PLAY):

PLAY) [Intro]
      [A|8]

C7
a

Le tre righe C7 / a formano un nuovo datapack indipendente; la sezione PLAY) si è chiusa dopo [A|8].

6.2 Continuazione esplicita¶

Non è richiesto alcun carattere di continuazione. La sezione termina al primo dei seguenti eventi (vedi anche §2.1 / §2.2):

prossimo prefisso di datapack (M)/C)/N)/A)/D)/L)/F));
nuova sezione globale (PLAY), FORM), %%…);
riga vuota;
fine documento.

7. Semantica del player¶

7.1 Modello base¶

Senza alcun PLAY) nel documento, il player esegue i datapack nell'ordine del documento, applicando i decorator standard (volte, ripetizioni, D.S., D.C., coda) descritti in neumaRk_flow_and_repeats.md.

7.2 Con `PLAY)`¶

Quando il player incontra una sezione PLAY), esegue il sub-programma in essa contenuto al posto del flusso naturale dei datapack a quel punto. Dopo aver completato la PLAY), prosegue dal datapack immediatamente successivo nel documento.

Multiple PLAY) consecutive sono lette in ordine: il player esegue ciascuna a turno. Datapack interposti fra una PLAY) e l'altra sono ignorati dal flusso eseguito, se referenziati da box di sezione dentro le PLAY) (i datapack sono comunque tabellati per nome marker; servono come "definizione" delle sezioni, non come flusso lineare).

7.3 Reference broken¶

Un box [NAME] il cui NAME non corrisponde a nessun marker M) del documento è reference broken:

viene renderizzato come testo non-cliccabile (visibile, marcato come irrisolvibile);
non viene eseguito dal player;
non genera warning o errore.

Questo permette di scrivere PLAY/FORM come sketch o annotazione informale senza vincoli sulla coerenza con i marker del documento.

7.4 Esecuzione di un box¶

L'esecuzione di un box [A|8]ff<x2&fermata consiste in:

salto al primo datapack la cui riga M) contiene il marker A;
applicazione della dinamica ff come dynamic iniziale della sezione;
esecuzione di tutti i datapack della sezione A (fino al prossimo marker o fine documento), con hairpin < se presente;
ripetizione N volte (per xN);
corona finale (per &fermata).

La durata |8 non influisce sull'esecuzione: l'estensione effettiva è data dai datapack del documento.

8. Render¶

8.1 PLAY)¶

Le sezioni PLAY) sono renderizzate come banda compatta sopra o sotto lo score, con i box di sezione disegnati come rettangoli con NAME e durata (se presente). Le label, dinamiche, hairpin e keyword sono renderizzate accanto al box secondo le convenzioni tipografiche musicali.

I box reference broken sono renderizzati con stile distinto (es. testo italic in grigio chiaro) per segnalare l'irrisolvibilità senza ostacolare la lettura.

8.2 FORM)¶

Le sezioni FORM) sono renderizzate come blocco descrittivo in calce al documento, con prosa Markdown interpolata ai box di sezione. Lo stile è meno enfatico di PLAY): testo body, box con bordo sottile.

8.3 Markup¶

Tutti i testi (top/bottom label, prosa libera) supportano il markup unificato di neumaRk_text_markup.md §3. Lo stile di default è quello indicato in neumaRk_text_markup.md §5 (label: plain ridotto; prosa PLAY/FORM: plain body).

9. Diagnostica¶

9.1 Codici diagnostici¶

Codice	Descrizione
W140	Più di una sezione `FORM)` nel documento
W141	Durata `\|BARS` non valida (atteso intero 1–999)
W142	Repeat count `xN` fuori range (atteso 2–99)
W143	Keyword `&xxx` non riservata
W145	`FORM)` non in fondo al documento (datapack successivi a `FORM)`)

PLAY) nidificata (dentro un'altra PLAY) o dentro un datapack) è impedita strutturalmente (§3, non-ricorsiva by design): il parser non la produce mai e non emette alcuna diagnostica. Il codice W144 è usato dal parser per la legatura A) malformata (vedi neumaRk_articulations.md).

9.2 Non-errori¶

I seguenti non sono errori (vedi §3.1, §3.2):

box [NAME] con NAME non riconducibile a nessun marker (reference broken);
discrepanza fra durata |N dichiarata e numero reale di misure della sezione;
hairpin aperto senza chiusura entro fine box;
prosa libera con caratteri arbitrari (purché non coincida con pattern strutturali).

10. Esempi¶

10.1 PLAY minimale¶

M) [Intro]
… datapack Intro …

M) [A]
… datapack A …

M) [B]
… datapack B …

PLAY) [Intro] [A|8]x2 [B|8] [A|8]

Il player esegue: Intro → A → A → B → A.

10.2 PLAY con dinamiche e keyword¶

PLAY) [Intro]p [A|8]<ff [B|4]x2 [A|8]>pp&fermata

Intro a piano.
A con crescendo fino a ff su 8 misure.
B ripetuto 2 volte (mantiene ff).
A con decresc. fino a pp, corona finale.

10.3 PLAY con prosa libera¶

PLAY) Start with [Intro] freely.
      Then [A|8] twice, then [B|8].
      Optional [C|4] if vibe is right.
      End on [Outro] &fermata.

Prosa interpolata serve il lettore; il player esegue solo i box: Intro → A → A → B → C → Outro+fermata.

10.4 FORM descrittiva¶

M) [Intro]
…

M) [A]
…

M) [B]
…

FORM) Standard AABA jazz: [Intro|4] sets the mood, then
      [A|8] is the main theme, [A|8] repeats with melodic
      variation, [B|8] is the bridge (modulating to IV), and
      a final [A|8] resolves to a [Coda|4] tag.

FORM) descrive la forma; il player la ignora (esecuzione segue il flusso documento o eventuali PLAY) separate).

10.5 Reference broken (sketch informale)¶

PLAY) [Intro] [FREE IMPRO! whatever feels right] [A|8] [Outro]

[FREE IMPRO! whatever feels right] non è un marker definito: viene renderizzato come testo descrittivo (irrisolvibile) e saltato dal player. Esecuzione: Intro → A → Outro.

10.6 Multiple PLAY in sequenza¶

M) [A]
…

M) [B]
…

PLAY) [A|8] [B|8]

M) [C]
…

PLAY) [C|8]x3 &fermata

Il player esegue: A → B (prima PLAY), poi C → C → C con corona (seconda PLAY). Il datapack [C] definisce la sezione referenziata dalla seconda PLAY ma non viene eseguito linearmente dal flusso documento (è già coperto dalla seconda PLAY).

10.7 Toggle player vs flow naturale¶

Lo stesso documento può essere:

letto come PLAY: il player segue la/le PLAY) e ignora il flusso lineare dei datapack;
letto come flow: il player ignora le PLAY) e segue i datapack in ordine documento.

La scelta è preference utente (user-index), non proprietà del documento.

11. Riassunto¶

Concetto	Sintassi	Sezione
Sezione PLAY	`PLAY) …`	§1.1
Sezione FORM	`FORM) …`	§1.2
Box di sezione	`"top"?[NAME(\|BARS)?]POSTFIX*`	§3
Top label	`"text"` adiacente prima di `[`	§3.3
Bottom label	`"text"` adiacente come postfix	§3.3
Repeat count	`xN` (N 2–99)	§3.4.1
Dynamic	`p`/`mp`/`mf`/`f`/`ff`/`sf`/`sfz` postfix	§3.4.2
Hairpin	`<` / `>` postfix (no cross-box)	§3.4.3
Keyword	`&fermata`/`&caesura`/`&breath`/`&GP`/`&niente`	§3.4.4
Segno / coda	`$` / `@`	§4
Prosa libera	tutto ciò che non è token strutturale	§5
Whitespace	newline = spazio	§6
Reference broken	`[NAME]` senza marker omonimo, non eseguito	§7.3
Durata informativa	`\|BARS` solo grafica, no controllo	§3.2
Toggle player/flow	preference utente	§1.3

Questo documento definisce PLAY) e FORM) come le due sezioni di neumaRk dedicate alla forma del brano, completando il vocabolario strutturale del linguaggio insieme a M) marker, D) annotation e play directive.