Skip to content

Overview

1. What neumaRk is

neumaRk is a formal system for the textual representation of music. It is designed to be simultaneously human-readable and machine-readable, with defined syntax and semantics that allow musical events, temporal structures, harmony, dynamics, lyrics, and formal sections to be described.

neumaRk is, at the same time:

  • a musical markup language;
  • a DSL (Domain Specific Language) oriented toward musical notation;
  • a pure textual format, usable as a standalone file.

The language was created to bridge the gap between traditional music writing and the needs of modern software systems: versioning, reliable parsing, compactness, sharing, and automatic transformation.

2. Design goals

neumaRk is designed around the following main goals:

  1. Semantic clarity
    Every construct has a precise and unambiguous meaning.

  2. Human readability
    A neumaRk file can be read and understood directly by a musician or an author.

  3. Efficiency and speed of writing

neumaRk is designed to favor fast and efficient musical writing, based on textual input and contextual deduction, minimizing redundant information.

  1. Parsing reliability
    The syntax allows deterministic parsing, even in the presence of implicit information.

  2. Expressive flexibility
    The same musical content can be expressed in more compact or more verbose forms.

  3. Rendering neutrality
    The language describes what the music is, not how it must be drawn.

  4. Compatibility with modern workflows
    Text files, diff-friendly, suited to versioning systems and exchange via URL.

3. neumaRk as a musical DSL

neumaRk is a DSL: a specialized language, with a well-defined domain.

The domain of neumaRk includes:

  • tempo and meter;
  • pitches and durations;
  • articulations and dynamics;
  • harmony and chord symbols;
  • lyrics;
  • formal structure (markers, sections, repeats);
  • layout and formatting hints.

The language does not attempt to replicate every graphical aspect of traditional music notation, but rather to provide a coherent and transformable textual representation.

4. Human-readable and Machine-readable

neumaRk is designed to be:

  • human-readable, without the need for dedicated tools;
  • machine-interpretable, without fragile heuristics.

This result is achieved through:

  • a line-based syntax;
  • a reduced set of symbols with stable meaning;
  • explicit rules for the deduction of implicit information.

A neumaRk file can be written quickly by hand, but also generated, validated, and transformed automatically.

5. Formal syntax and informal syntax

One of the central elements of neumaRk is the coexistence of two levels of syntax:

  • Formal syntax
    Rigorous, fully disambiguated, designed to guarantee reliable parsing in any situation.

  • Informal syntax
    More compact and natural to write, based on common conventions and contextual deduction.

The two syntaxes are not separate languages: they are two expressive modes of the same language.

The author can decide, case by case, whether to favor:

  • maximum semantic precision;
  • maximum speed and readability.

6. File formats and levels of detail

neumaRk supports several levels of explicitness, which influence the amount of information present in the file:

  • Compact
    Information reduced to the essential. Maximum compactness.

  • Human
    A compromise between compactness and clarity. Oriented toward human reading.

  • Verbose
    All information is explicit. No semantic ambiguity.

These levels do not define different languages, but modes of using the same language.

7. Typical use cases

neumaRk is intended to support, among others, the following scenarios:

  • writing and sharing lead sheets;
  • textual representation of scores;
  • embedding music in URLs or messages;
  • automatic parsing and rendering;
  • collaborative editing and versioning;
  • conversion to graphical or audio formats.

8. Relationship with traditional music notation

neumaRk is not a direct transcription of staff notation.

Many concepts are shared (durations, measures, ties, chords), but the language:

  • favors semantics over graphics;
  • allows implicit information that cannot easily be made explicit on paper;
  • separates the musical description from the visual rendering.

Traditional notation is one possible output representation, not the internal model.

9. Non-goals

neumaRk does not aim to:

  • replace traditional music notation in the editorial domain;
  • define a single graphical standard;
  • represent calligraphic micro-details;
  • cover every possible existing musical practice.

The language is intentionally focused and modular.

10. Organization of the specification

The neumaRk documentation is divided into several files, each with a specific responsibility: this conceptual overview, the normative specification, and the detail documents (header, datapack, notes and durations, chords, flow, dynamics, markup, voices, grace notes, etc.).

The complete and up-to-date list of normative documents is in neumaRk_specification.md ยง7. For the entry page and navigation, see index.md.

This division allows a progressive reading and an evolutionary maintenance of the specification.