Skip to content

Formats

1. Purpose

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

2. General principle

  • The musical content is identical in all formats
  • The formats only affect:
  • line layout
  • alignment
  • use of spaces
  • text compactness

A parser must be able to read all formats, producing the same internal structure.

3. Supported formats

3.1 Compact

Minimalist format, intended for:

  • transmission
  • storage
  • URL/embedding

Characteristics:

  • number of blank lines reduced to the minimum
  • spaces reduced to the minimum
  • shorthand (implicit) writing where possible, within the limits of deterministic safety

Example:

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

Readable format, intended for:

  • manual editing
  • review
  • collaboration

Characteristics:

  • explicit spacing
  • lines logically separated
  • comments allowed

Example:

nrk:0.6

                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

Explicit and redundant format, intended for:

  • debugging
  • inspection
  • tooling

Characteristics:

  • every line is labeled
  • no implicit deduction
  • maximum detail

Example:

nrk:0.6

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 types

These modes are not sharply separated; intermediate degrees of verbosity, compactness, implicit/explicit notation, and human readability are possible.

3.5 Semantic equivalence of the formats

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

Every valid neumaRk document can be expressed in any one of these formats without loss of musical or structural information.

The differences between the formats concern exclusively:

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

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

4. Alignment

4.1 Temporal alignment

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

4.2 Visual alignment

Whitespace has two distinct roles:

  • Alignment/padding whitespace — not significant: the length of a run of spaces/tabs, and the spaces added to vertically align lines or for leading/trailing, serve only readability and may be normalized freely.
  • Significant spaces — not normalizable, because they carry meaning:
  • token/event separators: a space separates two events (c d = two notes; c4 d ≠ c4d), and on A)/D) lines it separates the tokens aligned by count;
  • literal content inside delimited spans: the spaces inside a chord-stack <c e g> separate the pitches; inside an annotation "…" (and […]) they are literal text.

A formatter may compress/expand only whitespace of the first type; removing a space of the second type alters the semantics (see §6).

5. Blank lines

Blank lines serve to delineate the various datapacks. Additional blank lines:

  • are allowed in Human and Verbose
  • are semantically ignored
  • are not allowed in Compact

6. Normalization

A formatter may:

  • convert any format into another
  • remove superfluous spaces
  • expand or compress the datapack

Normalization must not modify:

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

7. Compatibility

A neumaRk document is valid if:

  • it respects the basic syntax
  • it uses one of the supported formats

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

8. Collections

A .nrk file may represent a single song (first line nrk:<v>) or a collection — a book or a playlist — wrapping an ordered sequence of songs. In that case the first line is nrk-book:<v> or nrk-playlist:<v>. The Compact / Human / Verbose formats of this document apply to each individual song block of the collection. See neumaRk_collections.md.