Skip to content

neumaRk — Formats

1. Purpose

This document defines the presentation formats of the neumaRk language. Formats do not modify the musical or temporal meaning of the data, but only the way content is organized, spaced, and made readable.

2. General principle

  • Musical content is identical across all formats.
  • Formats affect only:
  • line layout;
  • alignment;
  • spacing;
  • textual compactness.

A parser must be able to read all formats and produce the same internal representation.

3. Supported formats

3.1 Compact

A minimalist format designed for:

  • transmission;
  • storage;
  • URL embedding.

Characteristics:

  • minimal number of blank lines;
  • minimal spacing;
  • shorthand (implicit) notation where possible, within the limits of deterministic safety.

Example:

nrk:0.5
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

A readable format designed for:

  • manual editing;
  • review;
  • collaboration.

Characteristics:

  • explicit spacing;
  • logically separated lines;
  • comments allowed.

Example:

nrk:0.5

                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

An explicit and redundant format designed for:

  • debugging;
  • inspection;
  • tooling.

Characteristics:

  • every line is explicitly labeled;
  • no implicit deduction;
  • maximum level of detail.

Example:

nrk:0.5

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 Mixed verbosity levels

These formats are not strictly separated. Intermediate levels of verbosity, compactness, implicit/explicit notation, and human readability are allowed.

3.5 Semantic equivalence of formats

The Compact, Human, and Verbose formats are semantically equivalent.

Any valid neumaRk document may be expressed in any of these formats without loss of musical or structural information.

Differences between formats concern exclusively:

  • the level of explicitness;
  • human readability;
  • textual compactness.

Normalization between formats does not alter the semantics of the represented piece.

4. Alignment

4.1 Temporal alignment

  • alignment between musical lines is based on barlines;
  • the | separators define synchronization points.

4.2 Visual alignment

  • spaces may be used freely;
  • they have no semantic value;
  • they serve readability only.

5. Blank lines

Blank lines are used to delimit datapacks. Additional blank lines:

  • are allowed in Human and Verbose formats;
  • are semantically ignored;
  • are not allowed in Compact format.

6. Normalization

A formatter may:

  • convert any format into another;
  • remove superfluous spaces;
  • expand or compress datapacks.

Normalization must not modify:

  • rhythm;
  • flow;
  • musical semantics;
  • deterministic recognition in the case of shorthand (implicit) notation.

7. Compatibility

A neumaRk document is valid if:

  • it respects the base syntax;
  • it uses one of the supported formats.

The format may be automatically deduced or explicitly declared via the header.