Skip to content

Formal specification

1. Purpose of the document

This document defines the formal specification of the neumaRk language.

It establishes normatively:

  • which constructs are valid
  • how they must be interpreted
  • which rules must be respected by parsers, validators, and rendering tools

Everything described in this document is to be considered binding.

2. Levels of the specification

The neumaRk specification is organized into several levels, each with precise responsibilities:

  1. Syntactic level

  2. defines the textual grammar

  3. establishes which sequences of characters are valid

  4. Structural level

  5. defines the logical structure of the document

  6. establishes the relationships between the various sections

  7. Semantic level

  8. defines the musical meaning of the constructs

  9. clarifies ambiguities and edge cases

  10. Validation level

  11. defines the validity conditions
  12. establishes errors and invalid states

2.1 Persistent musical context

The parsing of a neumaRk document takes place within a persistent musical context.

The musical context retains the most recent relevant explicit information (pitches, durations, metric state) and persists across the entire document, crossing:

  • lines;
  • measures;
  • consecutive datapacks.

The musical context is not automatically reset at the beginning of a new datapack.

A datapack represents a structural and vertical-synchronization unit, but does not constitute a semantic boundary for musical deduction.

In the absence of explicit values, the deduction rules always refer to the current state of the musical context.

3. Normative terminology

In this document the following terms are used with normative meaning:

  • must / must not: mandatory requirement
  • may / may not: optional behavior
  • is invalid: the document must be rejected
  • is interpreted as: deterministic behavior

4. Contextual use of symbols

Some textual symbols of neumaRk have contextual semantics, determined by the type of musical line in which they appear. The normative algorithm by which the line type itself is deduced (in the absence of an explicit marker) is in neumaRk_datapack.md ยง3.bis.

In particular:

  • the symbol . (dot)
  • the symbol ! (exclamation mark)

take on different meanings depending on whether they appear in:

  • note lines (N));
  • chord lines (C)).

They take on different meanings, even within the same lines, depending on their position.

The line context and the position relative to the other elements of the line are always sufficient to resolve the meaning of the symbol deterministically.

There is no valid case in which a symbol can be ambiguous within the same line context.

5. Document identification and extension

A neumaRk document is a text file encoded in UTF-8.

The recommended file extension for neumaRk documents is:

.nrk

The use of the .nrk extension allows tools, editors, and operating systems to reliably recognize neumaRk documents.

The extension is recommended but not mandatory.
A document is considered valid as a neumaRk document based on its content, and not based on the file name or its extension.

Tools may assume the .nrk extension as the default when reading or writing neumaRk files.

6. General structure of a neumaRk document

A neumaRk document may contain, in order:

  1. Header (metadata)
  2. Musical content and formatting content

The order of the sections is significant and must be respected.

Structural delimitation

In neumaRk, a blank line has structural value.

Blank lines delimit logical blocks of the document, in particular:

  • the end of the header;
  • the separation between consecutive musical datapacks.

A structural block (header or datapack) always consists of one or more consecutive non-blank lines.

This specification refers to the following documents:

  • neumaRk_overview.md
  • neumaRk_formats.md
  • neumaRk_header.md
  • neumaRk_datapack.md
  • neumaRk_markers.md
  • neumaRk_chords.md
  • neumaRk_notes_and_durations.md
  • neumaRk_grace_notes.md
  • neumaRk_voices.md
  • neumaRk_articulations.md
  • neumaRk_lyrics.md
  • neumaRk_flow_and_repeats.md
  • neumaRk_dynamics.md
  • neumaRk_text_markup.md
  • neumaRk_play_and_form.md
  • neumaRk_play_directive.md
  • neumaRk_versions.md
  • neumaRk_collections.md

Each document elaborates normatively on a specific aspect of the language.

8. Compatibility and versioning

Every neumaRk document must explicitly declare the version of the language used. The first line of the document must report the sequence nrk: followed by the reference version in the form major.minor

example

nrk:0.6

The compatibility rules between versions and the evolution of the language are documented in neumaRk_changelog.md.

9. Extensions

The neumaRk language may be extended only within the limits explicitly allowed by the specification.

Undefined or unrecognized constructs make the document invalid, unless otherwise explicitly indicated.