Dinamiche e annotation testuali¶

Questo documento definisce la sintassi e la semantica della riga di dinamiche D) in neumaRk: vocabolario degli elementi, allineamento agli eventi musicali, sintassi delle annotation testuali, regole di estensione e diagnostica.

La riga D) è la fascia annotativa sotto il rigo: ospita le indicazioni dinamiche tradizionali (p, mf, ff, hairpin, cresc./dim.) e — coerentemente con la pratica jazz/lead-sheet — anche annotation testuali ancorate a eventi musicali (es. "drums fill", "freely", "w synth") o alle stanghette di misura (es. "Vamp till cue").

1. Definizione¶

La riga D) è una riga musicale opzionale del datapack (neumaRk_datapack.md §3, gruppo di note) che descrive eventi sotto-pentagramma allineati per posizione agli eventi della riga N) parent.

Esistono due classi ortogonali di elementi in D):

Elementi note-anchored — token in corrispondenza 1:1 con le note della riga N) parent (o N2). La classe principale.
Elementi barline-anchored — annotation testuali ancorate all'inizio o alla fine di una misura, indipendentemente dagli eventi note interni.

Le due classi convivono nella stessa riga: barline-anchored sono riconoscibili per adiacenza a un bordo barline composto; note-anchored sono tutti gli altri token.

2. Posizione strutturale e binding¶

La riga D) segue le regole generali del gruppo voce (neumaRk_datapack.md §3, gruppo di note, e neumaRk_voices.md §3.1):

[A)]  N)|N2|N+  [D)]  [L)]

è opzionale; può apparire al massimo una per gruppo voce;
è legata alla riga N) / N+ / N2 immediatamente precedente;
segue le stesse stanghette di misura (|, ||, :|, |:, ecc.) e gli stessi decoratori di misura della riga parent.

Una riga D) non legata a una N)/N+/N2 valida nello stesso datapack produce warning W130.

3. Vocabolario degli elementi¶

3.1 Dynamic puntuali¶

Marcatori dinamici tradizionali, ognuno puntuale (vale su una sola nota):

p   mp   mf   f   ff   fff   pp   ppp   pppp   ffff   sf   sfz   fp

Non si estendono nel tempo: il volume implicato dal mark vale per il beat dell'evento e — interpretativamente — fino al prossimo dynamic mark, ma graficamente compare una sola volta.

3.2 Hairpin grafici¶

Due token, ognuno renderizzato come segno grafico (crescendo/decrescendo "a forcina"):

Token	Effetto
`<`	crescendo
`>`	decrescendo

I hairpin si estendono per ripetizione: una sequenza < < < su tre note produce un singolo segno grafico che copre quelle tre note. Una singola occorrenza è ammessa (puntuale).

3.3 Hairpin testuali¶

Due token brevi che generano un'indicazione testuale con linea di estensione tratteggiata:

Token	Rendering
`c`	"cresc. - - - - "
`d`	"dim. - - - - "

Si estendono per ripetizione, esattamente come §3.2: una sequenza c c c c produce un'unica scritta "cresc." seguita da una linea tratteggiata che copre le quattro note.

Co-locazione con hairpin grafico (c< / d>): quando c e < (o d e >) compaiono sulla stessa nota come token co-located, vince la forcella grafica. Il token testuale è ignorato dal post-pass di estrazione hairpin. Per ottenere il testo "cresc."/"dim." senza forcella, usare c/d da soli. Per ottenere entrambi i segni contemporaneamente serve scriverli su note diverse (es. c < su due note adiacenti).

Compound testuali pc / fd: NON sono supportati. Un token co-located con dynamic puntuale seguito da hairpin testuale (es. pc, fd) produce solo il dynamic puntuale; l'hairpin testuale viene ignorato. Per esprimere "p e poi cresc." scrivere su due note: p c.

3.4 Annotation testuali¶

Container testuali con o senza box (vedi neumaRk_text_markup.md §2):

Forma	Effetto
`"text"`	annotation senza box
`[text]`	annotation con box

Il contenuto del container è soggetto al markup unificato definito in neumaRk_text_markup.md. Lo stile di default delle annotation D) è plain, dimensione ridotta: italic, bold e underline sono applicati solo se richiesti esplicitamente tramite il markup utente (*…*, **…**, __…__).

Le annotation testuali sono puntuali di default; diventano estese se seguite da - adiacente (vedi §5).

3.5 Placeholder `.`¶

Il token . indica nessun elemento sulla nota corrispondente. Serve a "saltare" una nota mantenendo l'allineamento posizionale.

Il . ha anche un ruolo chiusura: una . su una nota interrompe qualunque extension testuale in corso (vedi §5.4).

3.6 Continuation `-`¶

Il token - come token standalone (separato da spazi) significa "prosegue l'extension testuale aperta a sinistra". Si applica alle sole annotation testuali (vedi §5).

- ha anche un ruolo adiacente (senza spazi) come marcatore di apertura extension ("text"-) o di ancoraggio barline ([1.]-"text", "text"-:|). I tre ruoli sono distinguibili per posizione e adiacenza (vedi §4, §5, §6).

4. Elementi note-anchored¶

4.1 Corrispondenza 1:1 con la riga `N)` parent¶

Ogni token note-anchored della riga D) cade su una nota della riga parent, in ordine left-to-right. La corrispondenza è strettamente posizionale:

N) | a8 b c d e f g a |
D) | p  .  .  < < < f .  |
     ↑           ↑   ↑
   nota 1     note 4-6  nota 7

4.2 Co-locazione: più elementi sulla stessa nota¶

Più elementi sulla stessa nota si scrivono come token unico senza spazi interni:

N) | a4    b   c   d |
D) | f"piano fill"   .   c<   .  |
     ↑ 3 elementi sulla stessa nota: f + "piano fill" + (nessuno su b)

L'ordine degli elementi co-located è libero: f"text"c< e "text"<fc sono equivalenti dal punto di vista semantico (stessa nota, stessi elementi). Il renderer può applicare un ordine canonico in display.

4.3 Autofill di note residue¶

Se la riga D) contiene meno token note-anchored della riga N) parent, le note residue ricevono un . implicito:

N) | a a a a a a a a |
D) | f               |     ≡  D) | f . . . . . . . |

Se la riga D) contiene più token di quanti siano gli eventi nota nella riga parent (extra-token), produce warning W131.

4.4 Misure e barline¶

La suddivisione in misure è definita dalle stanghette | come per le altre righe musicali. Le stanghette di D) devono allinearsi a quelle della riga parent (regole generali di neumaRk_datapack.md §6).

5. Estensione testuale `-`¶

5.1 Solo i testi sono estendibili¶

Le annotation testuali ("text", [text]) sono gli unici elementi estendibili tramite trattino -. Dynamic puntuali (§3.1) non si estendono per loro natura; hairpin grafici e testuali (§3.2, §3.3) si estendono per ripetizione, non con -.

5.2 Apertura¶

Un trattino - adiacente (senza spazi) a destra di un'annotation testuale apre un'extension:

D) | "intro"-  -  -  -  mp |
       ↑ apre extension     ↑ chiude

In un gruppo co-located, il - adiacente vale per l'annotation testuale del gruppo, non per gli altri elementi:

D) | ff"drums fill"-  -  -  -  -  -  -  ppp  -  -  -  - |
       ↑ apre extension del testo (ff resta puntuale sulla nota 1)
                                   ↑ ppp puntuale, chiude "drums fill"

5.3 Continuazione¶

Un - standalone (token separato da spazi) prosegue l'extension aperta a sinistra. Funziona per qualunque numero di note successive, anche attraverso le stanghette di misura:

N) | a16 a a a a a a a    a a a a a a a a | a8 a a a a a a a |
D) | ff"drums fill"- - - - - - - ppp- - - - - - - - -   -  - - - pp
     ─────── extension 1 ───────┘ ───── extension 2 ────────┘   ── pp puntuale
                                                          (continua cross-bar)

5.4 Chiusura¶

Una extension testuale termina quando si incontra uno dei seguenti eventi:

un nuovo elemento note-anchored senza - adiacente sopra di sé (dynamic mark, hairpin, annotation, placeholder .);
la fine del system corrente (chiusura implicita);
una nuova annotation testuale aperta con - adiacente: chiude la precedente e ne apre una nuova;
un nuovo begin-bar anchor -"text" (vedi §6.2) come primo token di una misura: chiude l'extension precedente sulla nota immediatamente anteriore e apre un nuovo ancoraggio begin-bar allineato alla barline di apertura della misura corrente.

L'ultima regola si applica anche quando l'extension precedente è cross-bar barline-anchored (apertura -"prev"- … - continua sulle misure intermedie): un nuovo begin-bar -"new" la chiude implicitamente e ne apre uno nuovo, allineato al bordo barline di ingresso della misura corrente. Non occorre chiusura esplicita.

Esempio:

D) | "intro"- - - - - - - - | -"new"  p . . ff |
       ↑ extension aperta      ↑ chiude "intro" sulla nota 8 della
                                misura precedente, apre "new"
                                begin-bar nella misura corrente

Per chiudere esplicitamente prima della fine del system senza aprire un nuovo ancoraggio, inserire . (placeholder) o un altro elemento note-anchored privo di - adiacente.

5.5 Cross-bar libero¶

La stanghetta di misura | (e le sue varianti composte) è trasparente all'extension testuale: un - continua attraverso | senza necessità di sintassi speciale. Per ancorare un'annotation alla barline anziché a una nota interna, si usa la forma barline-anchored (§6).

5.6 Extension parallele¶

Più extension parallele (es. testo + hairpin) si ottengono per combinazione delle regole: il testo si estende con -, il hairpin si ripete per nota. Non esiste un meccanismo - per estendere hairpin:

N) | a a a a a a a a |
D) | "cresc."- - - - < < < < |
     ↑ testo esteso            ↑ hairpin grafico per 4 note

Il rendering presenta entrambi i segni nella fascia D), con regole di posizionamento verticale a cura del renderer.

6. Elementi barline-anchored¶

6.1 Contesto: bordo barline e contenuto di D)¶

In neumaRk un "bordo barline" è il gruppo composto formato dalla stanghetta | e dai suoi decoratori adiacenti: ripetizione (:), cambio metro/tonalità ((3/4), (@F)), volta ([1.], [2.]), conteggio ripetizioni (:x3), ecc. Il bordo barline è proprietà della riga (vedi neumaRk_datapack.md §6) ed è comune a tutte le righe musicali del datapack: D) non lo replica nel proprio contenuto.

Di conseguenza, il contenuto di D) per ciascuna misura è il testo fra una barline e la successiva, escluso ogni decoratore del bordo barline. È su questo contenuto pulito che si applicano le regole di ancoraggio di §6.2-§6.4.

6.2 Begin-bar¶

Un trattino - come carattere iniziale del primo token della misura, seguito (senza spazi) da un'annotation testuale, ancora l'annotation all'inizio della misura:

D) | -"my text 1"  p . . ff |
       ↑ "my text 1" begin-bar anchored

Il - iniziale non rappresenta extension qui: rappresenta ancoraggio barline. L'annotation resta puntuale di default; per estenderla attraverso le misure successive si applica la regola di §6.4.

Interazione con extension precedente (§5.4): se la misura precedente aveva una extension testuale aperta (note-anchored o barline-anchored cross-bar), il nuovo begin-bar -"text" la chiude implicitamente sulla nota immediatamente anteriore e apre il nuovo ancoraggio allineato al bordo barline. Per chiudere esplicitamente l'extension prima del begin-bar, inserire . o altro closing element sull'ultima nota della misura precedente.

6.3 End-bar¶

Simmetricamente: un'annotation testuale seguita (senza spazi) da - come ultimo token della misura ancora l'annotation alla fine della misura:

D) | ff "my text 2"- |
            ↑ "my text 2" end-bar anchored

6.4 Extension barline-anchored cross-bar¶

Un'annotation barline-anchored può estendersi attraverso più misure combinando due trattini sul primo token (ancora + apre) e uno sull'ultimo (ancora + chiude):

D) | -"Vamp till cue"-  -  -  - | -  -  -  -  - | -  -  - "end"- |
       ↑ begin-bar + apre ext      ↑ continua ext (cross-bar)        ↑ end-bar (chiude)

Il primo - ancora l'annotation a begin-bar.
Il secondo - adiacente al testo apre l'extension testuale (come per le note-anchored).
Nelle misure successive, - standalone continua l'extension.
La chiusura segue le stesse regole di §5.4; in più, una forma end-bar "end"- come ultimo token può chiudere esplicitamente un'extension aperta (anche con "end" qui usato simbolicamente — un nuovo elemento barline-anchored chiude quello in corso).

6.5 Convivenza begin + end nella stessa misura¶

Una misura può contenere sia un'annotation begin-bar sia una end-bar:

D) | -"text 1"   p . . ff   "text 2"- |
       ↑ begin                ↑ end

Eventuali elementi note-anchored della misura (p . . ff) si intercalano normalmente fra l'annotation begin e quella end.

7. Regole di parsing¶

7.1 Tokenizzazione¶

La riga D) è tokenizzata su spazi bianchi. All'interno di un token possono comparire più elementi co-located (§4.2). I container testuali "…" e […] ammettono spazi interni (sono delimitati dalle loro virgolette/parentesi quadre).

7.2 Disambiguazione del `-`¶

Il carattere - ha tre ruoli, distinguibili per posizione e adiacenza rispetto al contenuto della misura D):

Forma	Ruolo
`"text"-` (adiacente a annot, non ultimo token della misura)	apre extension testuale (§5.2)
`-` (token standalone)	continua extension (§5.3)
`-"text"` come PRIMO token della misura	ancoraggio begin-bar (§6.2)
`"text"-` come ULTIMO token della misura	ancoraggio end-bar (§6.3)
`-"text"-` come primo token	begin-bar + apre extension cross-bar (§6.4)

Un - non riconducibile a nessuno di questi tre pattern produce warning W132.

7.3 Disambiguazione `[…]`¶

Il container […] in D) è sempre un'annotation testuale con box. Non collide con il volta begin ([1.]) perché quest'ultimo compare nella riga di Markers, non in D). Non collide con polychord ([top|bottom]) per lo stesso motivo.

7.4 Single-line e container vuoti¶

I container testuali sono single-line (vedi neumaRk_text_markup.md §6.2). Container vuoti "" e [] sono letterali e non interpretati come annotation (sono token testuali vuoti).

7.5 Markup interno¶

Il contenuto di "…" e […] in D) è soggetto al markup unificato di neumaRk_text_markup.md §3. Lo stile di default applicato è plain, size ridotta: italic, bold e underline si attivano solo tramite markup esplicito (*…*, **…**, __…__).

8. Resa grafica¶

8.1 Fascia D)¶

Tutti gli elementi della riga D) sono renderizzati sotto il pentagramma del rigo parent, in una fascia dedicata. Quando il rigo parent è una voce 2 (N2), la fascia D) della voce 2 può essere sovrapposta o adiacente a quella della voce 1: il posizionamento verticale è scelta del renderer.

8.2 Dynamic puntuali¶

I dynamic mark (§3.1) sono renderizzati come testo bold-italic tradizionale (convenzione tipografica musicale), allineati orizzontalmente al beat della nota corrispondente.

8.3 Hairpin grafici¶

I hairpin (</>) sono renderizzati come singolo segno "a forcina" che copre l'intervallo da prima all'ultima ripetizione, con estremi allineati ai beat delle note di apertura e chiusura.

8.4 Hairpin testuali¶

c e d producono rispettivamente "cresc." e "dim." come testo italic, seguiti da una linea tratteggiata che si estende fino al beat dell'ultima ripetizione. Lo stile è coerente con la convenzione tipografica musicale.

8.5 Annotation testuali¶

Stile default: italic ridotto. Le annotation con […] (con box) mostrano un rettangolo grafico attorno al testo; le annotation con "…" (senza box) sono solo testo.

Le extension testuali sono renderizzate come linea continua o tratteggiata (a discrezione del renderer) che parte dalla fine del testo e si estende fino al beat di chiusura.

8.6 Annotation barline-anchored¶

Le annotation begin-bar sono allineate verticalmente al bordo sinistro della misura; quelle end-bar al bordo destro. Le extension cross-bar attraversano graficamente le stanghette di misura.

9. Diagnostica¶

9.1 Codici diagnostici¶

Codice	Descrizione
W130	`D)` senza una riga `N)`/`N+`/`N2` parent valida nel datapack
W131	Numero di token note-anchored in `D)` superiore agli eventi di `N)`
W132	Token `-` in posizione non riconducibile a extension o ancoraggio barline
W133	Container testuale non chiuso entro fine riga (`"…` o `[…` senza chiusura)

9.2 Extension non chiuse¶

Una extension testuale che arriva alla fine del system è chiusa implicitamente a fine system (§5.4). Non è un errore: la spec considera questo un comportamento valido e robusto. Per chiudere esplicitamente prima della fine del system, basta inserire . o un altro elemento note-anchored senza - adiacente.

9.3 Hairpin con singola occorrenza¶

Un hairpin (<, >, c, d) che compare una sola volta su una nota non è errore: produce un segno grafico/testuale puntuale (di estensione minima). Non viene emesso warning.

10. Esempi¶

10.1 Dinamiche essenziali¶

N) | a4 b c d | e f g a |
D) | p  .  .  f  | .  <  <  ff |

p su nota 1 di misura 1, f su nota 4; crescendo grafico su note 2-3 di misura 2 che culmina in ff su nota 4.

10.2 Annotation puntuale e estesa¶

N) | a8 a a a a a a a | a a a a a a a a |
D) | "intro"- - - mp< < < f | "verse"- - - - - - - - |

Misura 1: "intro" esteso per 4 note, poi mp chiude e parte hairpin grafico fino a f. Misura 2: "verse" esteso per tutta la misura; chiusura implicita a end-of-system.

10.3 Hairpin testuale `c` / `d`¶

N) | a8 a a a a a a a | a a a a a a a a |
D) | p c c c c c c c | c f . . d d d d |

Misura 1: p puntuale su nota 1, "cresc." si estende per 7 note. La prima ripetizione c cade sulla stessa nota di p (co-located). Misura 2: ulteriore c continua il "cresc." fino alla nota 1, poi f chiude. Da nota 5: "dim." si estende per 4 note.

10.4 Co-locazione complessa¶

N) | a4 b c d |
D) | ff"drum fill"c<  .  .  ppp |

Sulla nota 1: 4 elementi co-located (ff puntuale + testo "drum fill" + hairpin testuale c + hairpin grafico <). Le note 2-3 sono vuote; ppp puntuale su nota 4.

10.5 Barline-anchored begin¶

M) |[V.]                                          …
D) | -"Vamp till cue"- p . . . . . . . . |

"Vamp till cue" ancorato all'inizio della misura [V.] (volta), esteso per tutta la misura (i - continuano sulle note successive perché il trattino adiacente alla destra del testo apre l'extension).

Il decoratore [V.] di M) non è replicato nel contenuto di D): il parser lavora sul contenuto pulito della misura (vedi §6.1).

10.6 Barline-anchored cross-bar¶

D) | -"Vamp till cue"- p . . . . . . . . | - - - - - - - - | - - - - mp - - - |

"Vamp till cue" copre 3 misure; chiude su mp in misura 3.

10.7 Begin + end nella stessa misura¶

M) |:(3/4)[1.]                              :x3|
D) | -"intro"   p . . ff   "outro"- |

Annotation "intro" begin-bar + annotation "outro" end-bar nella stessa misura. Dinamiche p e ff sulle note interne. Il bordo barline di M) (:(3/4)[1.] / :x3|) non compare nel contenuto di D).

10.8 Voce 2 con dinamiche indipendenti¶

N)  | a4 b c d |
D)  | f . . ff |
N2  | e4 d e2  |
D)  | p . pp   |

La voce 1 ha f su nota 1 e ff su nota 4; la voce 2 ha p su nota 1 e pp su nota 3. Le due D) sono entrambe legate alle rispettive N)/N2 per posizione (vedi neumaRk_voices.md §3.1).

11. Riassunto¶

Concetto	Sintassi	Sezione
Dynamic puntuale	`p mp mf f ff fff pp ppp pppp ffff sf sfz fp`	§3.1
Hairpin grafico	`<` `>` (per ripetizione)	§3.2
Hairpin testuale	`c` (→ cresc.) `d` (→ dim.)	§3.3
Annotation testuale	`"text"` / `[text]`	§3.4
Placeholder	`.`	§3.5
Continuation	`-` standalone	§3.6
Co-locazione	adiacenza senza spazi	§4.2
Autofill	note residue → `.` implicito	§4.3
Extension testuale	`"text"-` apre, `-` continua, `.` chiude	§5
Begin-bar	`-"text"` come PRIMO token della misura	§6.2
End-bar	`"text"-` come ULTIMO token della misura	§6.3
Cross-bar barline-anch	`-"text"-` … `"end"-` (cross-bar)	§6.4
Cross-bar note-anch	`-` attraversa `\|` trasparente	§5.5

Il sistema è ortogonale: i tre meccanismi (dynamic puntuali, hairpin per ripetizione, testi con extension -) coesistono senza interferenze e si combinano per co-locazione.

Questo documento definisce la riga D) di neumaRk come fascia annotativa sotto-pentagramma unificata, in grado di esprimere dinamiche tradizionali, indicazioni di crescendo/decrescendo, annotation testuali puntuali ed estese e ancoraggi alle stanghette di misura, attraverso un vocabolario compatto e regole ortogonali.