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;
  • deve essere la prima riga del file;
  • non fa parte dell’header.

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 Criterio “tutto o niente” (parsing conservativo)

Il blocco iniziale viene riconosciuto come header solo se tutte le sue righe sono valide secondo le regole di questo documento.

Se anche una sola riga:

  • viola una regola sintattica;
  • contiene un elemento non ammesso;
  • oppure è interpretabile come riga musicale,

l’intero blocco viene classificato come non header.

In tal caso:

  • il parsing dell’header fallisce;
  • il blocco viene successivamente analizzato come datapack musicale.

Non è ammesso parsing parziale dell’header.

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.

5. Sintassi formale e sintassi informale

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

5.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.

5.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.

5.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.

6. 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 §11.6)

Tutti gli elementi sono opzionali.
Qualunque altro contenuto invalida l’intero header.

7. Marcatori di header

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

7.2 Elenco dei marcatori

Marcatore Significato
HT) Titolo
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

8. Titolo

8.1 Forma esplicita

  • marcatore: HT);
  • la prima riga HT) è il titolo principale; sono ammesse righe HT) successive come titoli alternativi (alias di ricerca / per-lingua);
  • può contenere qualsiasi testo;
  • può portare un tag lingua finale [lingua] (es. HT) No More Blues [EN]): forma sintattica [a-z]{2,3}(-regione)?, case-insensitive, strippato dal testo memorizzato. Associa quel titolo a una lingua — è il titolo tradotto per le edizioni di quella lingua (neumaRk_lyrics.md §8.8).

8.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.

8.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.

9. Credits

9.1 Ruolo

I credits identificano i contributori del brano.

9.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. Il vecchio credit per-lingua HCL) … [lingua] è rimosso: una riga HCL) setta sempre e solo il lyricsBy primario.

9.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.

9.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.

10. Year, Style, Key, Meter, BPM

10.1 Regole comuni

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

10.2 Forma esplicita

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

10.3 Forma implicita

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

11. Regole specifiche per elemento

11.1 Year

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

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

  • deve iniziare con una lettera minuscola (dopo eventuali spazi);
  • 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.

11.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à.

11.4 Meter

Forma frazionaria:

N/D

con N e D numeri interi di una o due cifre.

Esempi:

4/4
3/8

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

Esempio:

[3+3+2]/8

11.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.

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).

11.6 Versions

Dichiara le versioni alternative del brano. Disponibile solo in forma esplicita (HV)).

HV) versions: [original, miles, jarrett] default=original
  • versions: parola chiave obbligatoria.
  • Lista di label fra parentesi quadre, separate da virgole.
  • default=<label> opzionale: specifica la variante mostrata alla prima apertura del brano.

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.

12. Righe vietate e fallimento dell’header

Invalidano l’intero header:

  • righe vuote;
  • elementi non riconosciuti;
  • righe interpretabili come datapack musicale;
  • conflitti non risolvibili.

13. 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

14. Note di implementazione

  • il parsing dell’header è conservativo;
  • non è prevista alcuna correzione automatica;
  • non è previsto fallback parziale.