Formati¶

1. Scopo¶

Questo documento definisce i formati di presentazione del linguaggio neumaRk. I formati non modificano il significato musicale o temporale dei dati, ma solo il modo in cui il contenuto è organizzato, spaziato e reso leggibile.

2. Principio generale¶

Il contenuto musicale è identico in tutti i formati
I formati influenzano solo:
disposizione delle righe
allineamento
uso degli spazi
compattezza del testo

Un parser deve poter leggere tutti i formati producendo la stessa struttura interna.

3. Formati supportati¶

3.1 Compact¶

Formato minimalista, pensato per:

trasmissione
storage
URL/embedding

Caratteristiche:

numero di righe vuote ridotto al minimo
spazi ridotti al minimo
scrittura stenografica (implicita) dove possibile, nei limiti dell sicurezza deterministica

Esempio:

nrk:0.6
My Tune (John Dowe)
Waltz Ballad 3/4 Bb 135bpm

Bb6| |Cm7|F7|Bb6|
d|c bb c|d4 8 d eb d|c|bb|^.|

3.2 Human¶

Formato leggibile, pensato per:

editing manuale
revisione
collaborazione

Caratteristiche:

spaziatura esplicita
righe separate logicamente
commenti ammessi

Esempio:

nrk:0.6

                My Tune (John Dowe)
              3/4 Waltz Ballad 135bpm
Bb

| Bb6 |         | Cm7          | F7  | Bb6   |      .|
| d2. | c4 bb c | d4 d8 d eb d | c2. | bb2.^ | bb2. .|

3.3 Verbose¶

Formato esplicito e ridondante, pensato per:

debug
ispezione
tooling

Caratteristiche:

ogni riga è etichettata
nessuna deduzione implicita
massimo dettaglio

Esempio:

nrk:0.6

HT)                       My Tune
HCM) John Dowe
HCA) gino bart
HM) 3/4
HS) Waltz Ballad
HB) 135
HK) Bb

C) | Bb6 |           | Cm7             | F7  | Bb6   |      .|
N) | d2. | c4 bb4 c4 | d4 d8 d8 eb8 d8 | c2. | bb2.^ | bb2. .|

3.4 Tipologi miste¶

Queste modalità non sono nettamente separate, è possibile avere gradi intermedi di verbosità, compattezza, notazione implicita/esplicita, leggibilità per l'umano.

3.5 Equivalenza semantica dei formati¶

I formati Compact, Human e Verbose sono semanticamente equivalenti.

Ogni documento neumaRk valido può essere espresso in uno qualunque di questi formati senza perdita di informazione musicale o strutturale.

Le differenze tra i formati riguardano esclusivamente:

il grado di esplicitazione;
la leggibilità per l’essere umano;
la compattezza testuale.

La normalizzazione tra i formati non altera la semantica del brano rappresentato.

4. Allineamento¶

4.1 Allineamento temporale¶

l'allineamento tra righe musicali è basato sulle barline
i separatori | definiscono i punti di sincronizzazione

4.2 Allineamento visivo¶

Il whitespace ha due ruoli distinti:

Whitespace di allineamento/padding — non significativo: la lunghezza di un run di spazi/tab, e gli spazi aggiunti per incolonnare verticalmente le righe o per leading/trailing, servono solo alla leggibilità e possono essere normalizzati liberamente.
Spazi significativi — non normalizzabili, perché portano significato:
separatori di token/evento: uno spazio separa due eventi (c d = due note; c4 d ≠ c4d), e su righe A)/D) separa i token allineati per conteggio;
contenuto letterale dentro span delimitati: gli spazi dentro un chord-stack <c e g> separano le pitch; dentro un'annotation "…" (e […]) sono testo letterale.

Un formatter può comprimere/espandere solo il whitespace del primo tipo; rimuovere uno spazio del secondo tipo altera la semantica (vedi §6).

5. Righe vuote¶

Le righe vuote servono per delineare i vari datapack. Righe vuote supplementari:

sono consentite in Human e Verbose
ignorate semanticamente
non consentite in Compact

6. Normalizzazione¶

Un formatter può:

convertire qualsiasi formato in un altro
rimuovere spazi superflui
espandere o comprimere il datapack

La normalizzazione non deve modificare:

ritmo
flusso
semantica musicale
riconoscimento deterministico in caso di notazione stenografica (implicita)

7. Compatibilità¶

Un documento neumaRk è valido se:

rispetta la sintassi di base
utilizza uno dei formati supportati

Il formato può essere dedotto automaticamente o dichiarato esplicitamente tramite header.

8. Collezioni¶

Un file .nrk può rappresentare un brano singolo (prima riga nrk:<v>) oppure una collezione — un book o una playlist — che incapsula una sequenza ordinata di brani. In quel caso la prima riga è nrk-book:<v> o nrk-playlist:<v>. I formati Compact / Human / Verbose di questo documento si applicano a ogni singolo blocco-brano della collezione. Vedi neumaRk_collections.md.