Skip to content

neumaRk — Overview

1. What is neumaRk

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

neumaRk is, at the same time:

  • a musical markup language;
  • a DSL (Domain Specific Language) for music notation;
  • a plain text format, usable as a standalone file.

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

2. Design goals

neumaRk is designed around the following core 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. Parsing reliability
    The syntax enables deterministic parsing, even in the presence of implicit information.

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

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

  6. Compatibility with modern workflows
    Text files that are diff-friendly and suitable for version control systems and URL-based sharing.

3. neumaRk as a musical DSL

neumaRk is a DSL: a specialized language with a clearly defined domain.

The neumaRk domain includes:

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

The language does not attempt to replicate every graphical detail of traditional staff notation, but instead provides a coherent and transformable textual representation.

4. Human-readable and machine-readable

neumaRk is designed to be:

  • readable by humans, without the need for dedicated tools;
  • interpretable by machines, without fragile heuristics.

This is achieved through:

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

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

5. Formal and informal syntax

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

  • Formal syntax
    Rigorous and 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.

These are not separate languages, but two expressive modes of the same language.

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

  • maximum semantic precision;
  • maximum writing speed and readability.

6. File formats and levels of detail

neumaRk supports different levels of explicitness, which affect how much information is present in the file:

  • Compact
    Information reduced to the essential. Maximum compactness.

  • Human
    A balance between compactness and clarity. Optimized for human reading.

  • Verbose
    All information is explicit. Zero semantic ambiguity.

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

7. Typical use cases

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

  • writing and sharing leadsheets;
  • 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:

  • prioritizes semantics over graphics;
  • allows implicit information that is difficult to express on paper;
  • separates musical description from visual rendering.

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

9. Non-goals

neumaRk does not aim to:

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

The language is intentionally focused and modular.

10. Specification organization

The neumaRk documentation is split into multiple files, each with a specific responsibility:

  • conceptual overview;
  • normative specification;
  • syntax;
  • file structure;
  • header and metadata;
  • music and rhythm;
  • harmony;
  • rendering and formatting;
  • validation and examples.

This organization enables progressive reading and long-term maintainability of the specification.