Vai al contenuto

Header

1. Definizione e ruolo dell’header

L’header è una sezione opzionale di un documento neumaRk, collocata all’inizio del file dopo la dichiarazione di versione.

Il suo scopo è contenere tutte le informazioni non strettamente musicali necessarie a:

  • identificare il brano;
  • contestualizzarlo (autore, stile, tempo, tonalità, ecc.);
  • fornire indicazioni globali valide per l’intero documento.

In neumaRk l’header coincide integralmente con i metadati del file.
Non esistono metadati esterni, distribuiti o dichiarati altrove.

2. nrk:version e relazione con l’header

Ogni file neumaRk deve iniziare con una riga di versione nella forma:

nrk:.

Esempio:

nrk:0.6

Caratteristiche:

  • è obbligatoria nel file .nrk scambiato (esportato, importato, condiviso) e nei blocchi-brano di una collezione, dove separa un brano dal successivo (neumaRk_collections.md §9.2);
  • deve essere la prima riga del file;
  • non fa parte dell’header.

La regola vale al confine del file. Un brano può arrivare a un parser anche senza la riga nrk:, quando la versione gli è nota per altra via (per esempio dal contenitore che lo conserva): in quel caso il brano è valido e l'assenza non produce diagnostici. Una riga nrk: presente ma malformata (non nella forma nrk:<major>.<minor>, es. nrk:abc) è ignorata con W307.

Dopo la riga nrk:version possono comparire uno o più righi vuoti, seguiti da:

  • un header, oppure
  • direttamente dal primo datapack musicale.

3. Blocco di header e criterio di riconoscimento

3.1 Blocco iniziale

L’header, se presente, è costituito da un blocco di righe consecutive che:

  • segue la riga nrk:version (dopo eventuali righi vuoti);
  • precede qualsiasi datapack musicale;
  • non contiene righe vuote.

L’header termina al primo rigo vuoto.
Il contenuto successivo è interpretato come datapack musicale.

3.2 Riconoscimento del blocco e campi non validi

Il blocco iniziale è un header se nessuna delle sue righe è interpretabile come riga musicale (note, accordi, markers). Se anche una sola riga lo è, l’intero blocco è un datapack musicale (§3.3).

Una volta riconosciuto, l’header vale campo per campo:

  • un campo con un valore non valido (tonalità, metro, BPM, anno) si scarta con un diagnostico (§14); gli altri campi restano validi e il blocco resta header;
  • un campo ripetuto (stesso marcatore due volte) vale per la prima occorrenza valida; le successive si ignorano con W305. Fanno eccezione le righe HT), che dopo la prima dichiarano titoli alternativi (§7.1);
  • nella forma implicita un token della riga di metadati che non è riconosciuto si ignora con W306 (§9.3);
  • una riga con un marcatore H…) sconosciuto si ignora con W308 (§6.1).

Un errore in un campo non fa quindi perdere gli altri: HK) H scarta la sola tonalità (con E301) e titolo, tempo e metro dichiarati restano.

3.3 Principio di deduzione conservativa e anti-collisione

La deduzione implicita nell’header di neumaRk è governata da un principio fondamentale:

un elemento dell’header non deve mai poter essere confuso con un elemento musicale.

In particolare, una riga dell’header non deve collidere semanticamente con:

  • una riga di note;
  • una riga di accordi;
  • una riga di markers;
  • qualunque riga valida come datapack musicale.

Questo principio ha lo scopo di:

  • evitare ambiguità strutturali;
  • rendere il parsing affidabile;
  • garantire che la deduzione non produca interpretazioni errate.

La deduzione è quindi conservativa:

  • se una riga può essere interpretata sia come elemento di header sia come riga musicale, prevale l’interpretazione musicale;
  • in tal caso, il parsing dell’header fallisce e il blocco viene trattato come datapack musicale.

La specifica non impone una grammatica formale completa per distinguere in modo assoluto header e contenuto musicale. Alcuni aspetti della deduzione possono dipendere da euristiche implementative, purché rispettino il principio di non-collisione e la strategia conservativa descritta.

Deduzione di style

Nella deduzione implicita dell’header, gli elementi testuali debolmente tipizzati (come lo style) devono sempre evitare collisioni con elementi strutturalmente più forti, quali Key, Meter e BPM.

4. Sintassi formale e sintassi informale

L’header supporta due modalità sintattiche: formale (esplicita) e informale (implicita).

4.1 Sintassi formale (esplicita)

Caratteristiche:

  • uso di marcatori di riga espliciti;
  • nessuna ambiguità sintattica;
  • ordine delle righe arbitrario;
  • ogni elemento occupa una riga dedicata.

È la modalità raccomandata per l’uso automatico.

4.2 Sintassi informale (implicita)

Caratteristiche:

  • uso minimo o assente di marcatori;
  • deduzione basata su contenuto e posizione;
  • ordine delle righe vincolato;
  • deduzione basata su regole conservative.

La sintassi informale privilegia la leggibilità e la scrittura rapida.

4.3 Precedenze

In caso di ambiguità o conflitto, prevale:

  1. la sintassi formale;
  2. le regole di posizione;
  3. la deduzione semantica;
  4. il fallimento del parsing dell’header.

5. Elementi ammessi nell’header

L’header riconosce esclusivamente i seguenti elementi:

  • Titolo
  • Credits
  • Music by
  • Lyrics by
  • Arranger
  • Transcriber
  • Year
  • Style
  • Key
  • Meter
  • BPM
  • Versions (solo forma esplicita HV), vedi §10.6)

Tutti gli elementi sono opzionali. Un elemento con valore non valido si scarta con un diagnostico senza invalidare l’header (§3.2).

Titolo, credits e style sono testo semplice: non ammettono il markup di neumaRk_text_markup.md e non hanno escape. Virgolette " e backslash \ si scrivono così come sono e restano nel testo (HT) Il "Re" di Roma).

6. Marcatori di header

6.1 Definizione

I marcatori di header sono sequenze alfabetiche maiuscole seguite dal carattere ) e da uno spazio.

  • il primo carattere è sempre H;
  • la lunghezza varia da due a tre lettere.

Un marcatore che comincia con H ma non è nell'elenco di §6.2 (HZ) foo) si ignora con W308: la riga resta parte dell'header e non diventa titolo, style o riga musicale.

6.2 Elenco dei marcatori

Marcatore Significato
HT) Titolo
HSB) Sottotitolo
HC) Credits generici
HCM) Music by
HCL) Lyrics by
HCA) Arranger
HCT) Transcriber
HY) Year
HS) Style
HK) Key
HM) Meter
HB) BPM
HV) Versions

7. Titolo

7.1 Forma esplicita

  • marcatore: HT);
  • la prima riga HT) (o il titolo implicito, §7.2) è il titolo principale; le righe HT) successive dichiarano titoli alternativi — alias di ricerca: il brano è trovabile con il titolo principale o con uno qualsiasi degli alternativi (es. Chega de Saudade / No More Blues);
  • le righe HT) alternative possono comparire su qualsiasi riga dell'header (ordine indifferente); il serializer le riemette in coda al blocco header;
  • può contenere qualsiasi testo;
  • può portare un tag lingua finale [lingua] (es. HT) No More Blues [EN]), che associa quel titolo a una lingua dei lyrics (neumaRk_lyrics.md §8.8) — è il ponte titolo↔lingua: aprire il brano da quel titolo preseleziona la lingua. Il tag è riconosciuto per forma sintattica: un token finale fra parentesi quadre con forma di codice lingua ([A-Za-z]{2,3} con -regione opzionale, normalizzato a minuscolo). Un […] finale che non ha forma di codice lingua è testo letterale del titolo — i titoli finiscono raramente per parentesi quadre (a differenza delle tonde), quindi il rischio di collisione è trascurabile. Il tag è strippato dal testo memorizzato/di ricerca.

7.2 Forma implicita

In assenza di marcatore, il titolo:

  • deve essere la prima riga dell’header;
  • deve iniziare con una lettera maiuscola o un numero (dopo eventuali spazi);
  • non deve essere interpretabile come riga musicale (note, accordi o markers).

La deduzione del titolo implicito è conservativa:
in caso di dubbio, l’header fallisce.

7.3 Titolo e credits sulla stessa riga

È ammesso indicare i credits sulla stessa riga del titolo solo in forma implicita.

In tal caso:

  • i credits devono essere racchiusi tra parentesi tonde;
  • non deve essere presente alcun marcatore esplicito sulla riga.

8. Credits

8.1 Ruolo

I credits identificano i contributori del brano.

8.2 Credits con marcatori specifici

Ogni elemento appare su una riga autonoma con marcatore dedicato:

  • HCM) — Music by
  • HCL) — Lyrics by
  • HCA) — Arranger
  • HCT) — Transcriber

L’ordine è arbitrario.

Nota (edizioni del testo). HCL) indica l'autore del testo di default (edizione neutra). L'autore di un'edizione taggata si scrive col gruppo <…> sul blocco LYRICS) (neumaRk_lyrics.md §8.8), non qui. Una riga HCL) setta sempre e solo il lyricsBy primario.

8.3 Credits con marcatore generico

  • marcatore: HC);
  • una sola riga;
  • parentesi opzionali;
  • elementi separati da /.

Assegnazione:

  • primo elemento senza prefisso → Music by;
  • secondo elemento senza prefisso → Lyrics by;
  • arr: → Arranger;
  • trans: → Transcriber;
  • elementi successivi senza prefisso vengono ignorati.

8.4 Credits impliciti

Senza marcatore esplicito, i credits:

  • devono essere racchiusi tra parentesi tonde;
  • devono comparire su una sola riga;
  • devono essere separati da /.

Posizione ammessa:

  • stessa riga del titolo;
  • oppure riga immediatamente successiva.

9. Year, Style, Key, Meter, BPM

9.1 Regole comuni

  • tutti opzionali;
  • possono comparire solo dopo titolo e credits (se presenti);
  • in forma esplicita l’ordine è arbitrario.

9.2 Forma esplicita

  • ogni elemento su riga dedicata;
  • uso del marcatore corrispondente.

9.3 Forma implicita

  • possono essere combinati sulla stessa riga;
  • nessun marcatore;
  • riconoscimento basato su pattern.

Un token che non è anno, tonalità, metro, BPM o chr fa parte dello style se sta nella prima sequenza di parole non riconosciute (§10.2); un token non riconosciuto dopo un elemento strutturato si ignora con W306 (es. Reb in Swing 120bpm 4/4 Reb: il nome italiano della nota non è una tonalità).

10. Regole specifiche per elemento

10.1 Year

Indica l'anno di composizione: numero a 4 cifre compreso fra 1000 e 2999.

HY) con un valore che non è un numero (HY) abc) o fuori intervallo (HY) 999, HY) 3000) si ignora con W304. Nella forma implicita un numero che non ha la forma dell’anno non è un anno: resta testo (dello style, §10.2).

10.2 Style

Lo style è una descrizione testuale del carattere musicale del brano (es. swing, bossa, latin, rock ballad).

Il valore dichiarato nell'header inizializza currentStyle e può essere sovrascritto localmente in una qualsiasi misura tramite una play directive (=Style,…) nella riga M) (vedi neumaRk_play_directive.md).

Forma implicita

In forma implicita lo style è la prima sequenza di parole della riga di metadati che non sono anno, tonalità, metro, BPM o chr, maiuscole o minuscole (Swing, rock ballad). Lo style:

  • non deve collidere con pattern validi di:
  • tonalità (Key);
  • metro (Meter);
  • tempo (BPM).

Se una porzione di testo può essere interpretata sia come style sia come altro elemento strutturato dell’header, prevale sempre l’interpretazione strutturata.

In caso di ambiguità non risolvibile, la deduzione dello style fallisce senza invalidare l’intero header.

10.3 Key

Forma:

  • nota A–G;
  • alterazione b o # opzionale;
  • maggiore implicita;
  • m o - per il minore.

Valore speciale:

X

che indica assenza di tonalità, politonalità o atonalità.

Una tonalità che non ha questa forma (HK) H, HK) dm, HK) Reb) si scarta con E301: vale la tonalità di default.

Default. Una tonalità non dichiarata vale C (Do maggiore), non X: un brano in C può omettere la tonalità, e chi genera NRK la omette (l'export compatto, il fly link). Un brano atonale va dichiarato esplicitamente con X.

Default cromatico autoriale (chr)

Un brano può avere un centro tonale reale e tuttavia essere pensato per la lettura senza armatura (alterazioni in linea). È il caso della musica a centro tonale mobile: il brano ha una tonalità (ha senso dire «facciamolo un tono sotto»), ma l’autore preferisce che si legga cromaticamente.

Per dichiararlo si aggiunge il token chr accanto alla tonalità:

HK) Db chr

oppure, in forma implicita, come token della riga di metadati:

Db 120bpm chr

Semantica:

  • chr è un attributo ortogonale alla tonalità: la tonalità resta quella dichiarata (es. Db), ma la resa predefinita è cromatica (nessuna armatura).
  • Si emette solo quando attivo; la sua assenza equivale a lettura normale con armatura.
  • È una dichiarazione autoriale che viaggia col brano. Il lettore può invertirla dalle impostazioni di visualizzazione (mostrando l’armatura), ma ciò non modifica il sorgente .nrk.

Da distinguere dall’atonale X: usare X solo per brani realmente privi di centro tonale. Un brano tonale che si vuole leggere cromaticamente va scritto con la sua tonalità più chr, non con X.

10.4 Meter

Forma frazionaria:

N/D

con D uguale a 2, 4, 8 o 16 e N intero di una o due cifre, almeno 1. 0/4, 5/3 o 3/32 non sono metri.

Esempi:

4/4
3/8

È consentita la forma estesa con suddivisione interna del numeratore (clave):

Esempio:

[3+3+2]/8

Ogni parte della somma vale 2, 3, 4 o 5.

Un metro non valido nell’header (HM) 5/3) si scarta con E303: resta il metro di partenza (il default). Lo stesso criterio vale per il metro scritto nell’oggetto di contesto di misura (neumaRk_datapack.md §7.1).

Default. Un metro non dichiarato vale 4/4.

10.5 BPM

  • numero intero di due o tre cifre;
  • in forma implicita deve essere seguito da BPM (case-insensitive);
  • in forma esplicita (HB)) il suffisso è opzionale;
  • non sono ammessi numeri decimali.

Un valore che non rispetta queste regole (HB) 5, HB) 1000, HB) 120.5, 5bpm) si ignora per intero con W304: non viene troncato.

Il valore dichiarato nell'header inizializza currentBPM e può essere sovrascritto localmente in una qualsiasi misura tramite una play directive (=…,Nbpm) o metric modulation (=…,figura=figura) nella riga M) (vedi neumaRk_play_directive.md).

10.6 Versions

Dichiara le versioni alternative di un blocco %%NAME. Disponibile solo in forma esplicita (HV)), una riga per NAME.

HV) INTRO: [standard, adams] default=standard
HV) BRIDGE: [default, miles, jarrett] default=default
  • <NAME>: il nome del blocco, seguito da :.
  • Lista di label fra parentesi quadre, separate da virgole; default indica il blocco canonico.
  • default=<label> opzionale: specifica la variante mostrata alla prima apertura del brano (default=default = il blocco canonico).
  • La forma vecchia HV) versions: […] è rifiutata con W150.

Vedi neumaRk_versions.md per la spec completa dei blocchi %%NAME … %%end e la semantica di sostituzione.

HV) è opzionale: in sua assenza le versioni sono dedotte direttamente dai blocchi %%NAME "label" presenti nel documento.

10bis. INFO) accanto all’header

Una riga INFO) contigua alle righe H…), senza riga vuota in mezzo, è un’informazione sull’intero brano (neumaRk_datapack.md §11.1): la sua etichetta è incisa come parte dell’intestazione, il corpo resta disponibile su richiesta. Non è un elemento d’header: non entra nella deduzione di titolo, credits o tonalità, non invalida l’header e può stare prima, dopo o fra le righe H…). Una sola per intestazione (W170 sulla seconda).

HT) Blue Info
INFO) "Nota del trascrittore" Trascritto dal disco del 1961.
HCM) Anon

11. Righe vietate e fallimento dell’header

Fanno di tutto il blocco un datapack musicale (l’header non c’è):

  • righe interpretabili come datapack musicale (§3.3).

Una riga vuota non invalida nulla: chiude l’header (§3.1). Un campo non valido, ripetuto o non riconosciuto si scarta con un diagnostico e il resto dell’header vale (§3.2).

12. Esempi

My Song (John Doe / Jane Roe)
1998 Swing 120BPM 4/4 Dm

equivale a

HT) My Song
HC) John Doe / Jane Roe
HY) 1998
HS) Swing
HB) 120
HM) 4/4
HK) Dm

13. Note di implementazione

  • il parsing dell’header è conservativo;
  • non è prevista alcuna correzione automatica: un valore non valido si scarta, non si corregge né si tronca;
  • l’header vale campo per campo (§3.2).

14. Diagnostici

Codice Condizione Effetto
E301 Tonalità non interpretabile (HK) H, HK) Reb) Tonalità scartata, vale il default (§10.3)
E303 Metro dell’header non valido (HM) 5/3, HM) 0/4) Metro scartato, resta il metro di partenza (§10.4)
W150 HV) malformato o forma vecchia HV) versions: […] Riga ignorata (§10.6)
W170 Secondo INFO) accanto all’header Vale il primo (§10bis)
W301 Prima riga dell’header implicito da cui non si deducono titolo né credits Riga letta come style (§7.2)
W304 BPM o anno malformato o fuori intervallo (HB) 1000, HY) 999, HY) abc) Campo ignorato (§10.1, §10.5)
W305 Campo ripetuto (HK) due volte) Vale il primo valido (§3.2)
W306 Token non riconosciuto nella riga di metadati implicita Token ignorato (§9.3)
W307 Riga nrk: malformata (nrk:abc) Riga ignorata (§2)
W308 Marcatore d'header sconosciuto (HZ) foo) Riga ignorata, resta header (§6.1)