Panoramica¶

1. Cos'è neumaRk¶

neumaRk è un sistema formale di rappresentazione testuale della musica. È progettato per essere contemporaneamente human‑readable e machine‑readable, con una sintassi e una semantica definite che consentono di descrivere eventi musicali, strutture temporali, armonia, dinamiche, testi e sezioni formali.

neumaRk è, allo stesso tempo:

un linguaggio di markup musicale;
una DSL (Domain Specific Language) orientata alla notazione musicale;
un formato testuale puro, utilizzabile come file standalone.

Il linguaggio nasce per colmare lo spazio tra la scrittura musicale tradizionale e le esigenze dei sistemi software moderni: versionamento, parsing affidabile, compattezza, condivisione e trasformazione automatica.

2. Obiettivi di progettazione¶

neumaRk è progettato attorno ai seguenti obiettivi principali:

Chiarezza semantica
Ogni costrutto ha un significato preciso e non ambiguo.
Leggibilità umana
Un file neumaRk può essere letto e compreso direttamente da un musicista o da un autore.
Efficienza e rapidità di scrittura

neumaRk è progettato per favorire una scrittura musicale rapida ed efficiente, basata su input testuale e deduzione contestuale, riducendo al minimo le informazioni ridondanti.

Affidabilità del parsing
La sintassi consente un parsing deterministico, anche in presenza di informazioni implicite.
Flessibilità espressiva
Lo stesso contenuto musicale può essere espresso in forme più compatte o più verbose.
Neutralità rispetto al rendering
Il linguaggio descrive cosa è la musica, non come deve essere disegnata.
Compatibilità con workflow moderni
File testuali, diff‑friendly, adatti a sistemi di versionamento e a scambi via URL.

3. neumaRk come DSL musicale¶

neumaRk è una DSL: un linguaggio specializzato, con un dominio ben definito.

Il dominio di neumaRk comprende:

tempo e metrica;
altezze e durate;
articolazioni e dinamiche;
armonia e sigle di accordo;
testo (lyrics);
struttura formale (marker, sezioni, ripetizioni);
suggerimenti di layout e formattazione.

Il linguaggio non tenta di replicare ogni aspetto grafico della notazione musicale tradizionale, ma di fornire una rappresentazione testuale coerente e trasformabile.

4. Human‑readable e Machine‑readable¶

neumaRk è progettato per essere:

leggibile dall'uomo, senza necessità di strumenti dedicati;
interpretabile dalla macchina, senza euristiche fragili.

Questo risultato è ottenuto tramite:

una sintassi line‑based;
un insieme ridotto di simboli con significato stabile;
regole esplicite per la deduzione delle informazioni implicite.

Un file neumaRk può essere scritto rapidamente a mano, ma anche generato, validato e trasformato automaticamente.

5. Sintassi formale e sintassi informale¶

Uno degli elementi centrali di neumaRk è la coesistenza di due livelli di sintassi:

Sintassi formale
Rigorosa, completamente disambiguata, pensata per garantire un parsing affidabile in qualsiasi situazione.
Sintassi informale
Più compatta e naturale da scrivere, basata su convenzioni comuni e deduzione contestuale.

Le due sintassi non sono linguaggi separati: sono due modalità espressive dello stesso linguaggio.

L'autore può decidere, caso per caso, se privilegiare:

la massima precisione semantica;
la massima velocità e leggibilità.

6. Formati di file e livelli di dettaglio¶

neumaRk supporta diversi livelli di esplicitazione, che influenzano la quantità di informazione presente nel file:

Compact
Informazioni ridotte all'essenziale. Massima compattezza.
Human
Compromesso tra compattezza e chiarezza. Orientato alla lettura umana.
Verbose
Tutte le informazioni sono esplicite. Nessuna ambiguità semantica.

Questi livelli non definiscono linguaggi diversi, ma modalità di utilizzo dello stesso linguaggio.

7. Casi d'uso tipici¶

neumaRk è pensato per supportare, tra gli altri, i seguenti scenari:

scrittura e condivisione di leadsheet;
rappresentazione testuale di partiture;
embedding di musica in URL o messaggi;
parsing e rendering automatico;
editing collaborativo e versionamento;
conversione verso formati grafici o audio.

8. Relazione con la notazione musicale tradizionale¶

neumaRk non è una trascrizione diretta della notazione su pentagramma.

Molti concetti sono condivisi (durate, battute, legature, accordi), ma il linguaggio:

privilegia la semantica rispetto alla grafica;
consente informazioni implicite non esplicitabili facilmente su carta;
separa la descrizione musicale dalla resa visiva.

La notazione tradizionale è una possibile rappresentazione di output, non il modello interno.

9. Non‑obiettivi¶

neumaRk non ha come obiettivo:

sostituire la notazione musicale tradizionale in ambito editoriale;
definire uno standard grafico unico;
rappresentare micro‑dettagli calligrafici;
coprire ogni possibile pratica musicale esistente.

Il linguaggio è intenzionalmente focalizzato e modulare.

10. Organizzazione della specifica¶

La documentazione di neumaRk è suddivisa in più file, ciascuno con una responsabilità specifica: questa panoramica concettuale, la specifica normativa, e i documenti di dettaglio (header, datapack, note e durate, accordi, flusso, dinamiche, markup, voci, grace notes, ecc.).

L'elenco completo e aggiornato dei documenti normativi è in neumaRk_specification.md §7. Per la pagina d'ingresso e la navigazione, vedi index.md.

Questa suddivisione consente una lettura progressiva e una manutenzione evolutiva della specifica.