Skip to content

neumaRk — Header

1. Definition and role of the header

The header is an optional section of a neumaRk document, located at the beginning of the file, after the version declaration.

Its purpose is to contain all non-strictly musical information required to:

  • identify the piece;
  • provide contextual information (author, style, tempo, key, etc.);
  • define global indications that apply to the entire document.

In neumaRk, the header fully coincides with the file metadata.
There are no external, distributed, or separately declared metadata.

2. nrk:version and its relation to the header

Each neumaRk file must start with a version line in the form:

nrk:.

Example:

nrk:0.5

Characteristics:

  • it is mandatory;
  • it must be the first line of the file;
  • it is not part of the header.

After the nrk:version line, one or more blank lines may appear, followed by:

  • a header, or
  • directly by the first musical datapack.

3. Header block and recognition criteria

3.1 Initial block

If present, the header consists of a block of consecutive lines that:

  • follows the nrk:version line (after any blank lines);
  • precedes any musical datapack;
  • contains no blank lines.

The header ends at the first blank line. Any subsequent content is interpreted as musical datapack.

3.2 “All-or-nothing” criterion (conservative parsing)

The initial block is recognized as a header only if all its lines are valid according to the rules defined in this document.

If even a single line:

  • violates a syntactic rule;
  • contains an unsupported element;
  • or can be interpreted as a musical line,

the entire block is classified as not a header.

In this case:

  • header parsing fails;
  • the block is subsequently analyzed as musical datapack content.

Partial parsing of the header is not allowed.

4. Conservative deduction and anti-collision principle

Implicit deduction in the neumaRk header is governed by a fundamental principle:

A header element must never be confusable with a musical element.

In particular, a header line must not semantically collide with:

  • a note line;
  • a chord line;
  • a marker line;
  • any line valid as musical datapack content.

This principle aims to:

  • avoid structural ambiguities;
  • ensure reliable parsing;
  • guarantee that deduction does not produce incorrect interpretations.

Deduction is therefore conservative:

  • if a line can be interpreted both as a header element and as a musical line, the musical interpretation prevails;
  • in such cases, header parsing fails and the block is treated as musical datapack.

The specification does not require a fully formal grammar to absolutely distinguish header and musical content. Some aspects of deduction may rely on implementation heuristics, provided that they respect the non-collision principle and the conservative strategy described above.

Deduction of style

In implicit header deduction, weakly typed textual elements (such as style) must always avoid collisions with structurally stronger elements such as Key, Metrum, and BPM.

5. Formal and informal syntax

The header supports two syntactic modes: formal (explicit) and informal (implicit).

5.1 Formal (explicit) syntax

Characteristics:

  • use of explicit line markers;
  • no syntactic ambiguity;
  • arbitrary line order;
  • each element occupies a dedicated line.

This mode is recommended for automated use.

5.2 Informal (implicit) syntax

Characteristics:

  • minimal or absent use of markers;
  • deduction based on content and position;
  • constrained line order;
  • conservative deduction rules.

Informal syntax prioritizes readability and rapid writing.

5.3 Precedence rules

In case of ambiguity or conflict, the following precedence applies:

  1. formal syntax;
  2. positional rules;
  3. semantic deduction;
  4. header parsing failure.

6. Elements allowed in the header

The header recognizes only the following elements:

  • Title
  • Credits
  • Music by
  • Lyrics by
  • Arranger
  • Transcriber
  • Style
  • Key
  • Metrum
  • BPM

All elements are optional. Any other content invalidates the entire header.

7. Header markers

7.1 Definition

Header markers are uppercase alphabetic sequences followed by the character ) and a space.

  • the first character is always H;
  • the length ranges from two to three letters.

7.2 List of markers

Marker Meaning
H) Generic header
HT) Title
HC) Generic credits
HCM) Music by
HCL) Lyrics by
HCA) Arranger
HCT) Transcriber
HS) Style
HK) Key
HM) Metrum
HB) BPM

8. Title

8.1 Explicit form

  • marker: HT);
  • may appear only on the first header line;
  • may contain arbitrary text.

8.2 Implicit form

In the absence of a marker, the title:

  • must be the first header line;
  • must begin with an uppercase letter or a digit (after optional spaces);
  • must not be interpretable as a musical line (notes, chords, or markers).

Implicit title deduction is conservative: in case of doubt, header parsing fails.

8.3 Title and credits on the same line

Credits may appear on the same line as the title only in implicit form.

In this case:

  • credits must be enclosed in parentheses;
  • no explicit marker may appear on the line.

9. Credits

9.1 Role

Credits identify the contributors to the piece.

9.2 Credits with specific markers

Each element appears on its own line with a dedicated marker:

  • HCM) — Music by
  • HCL) — Lyrics by
  • HCA) — Arranger
  • HCT) — Transcriber

The order is arbitrary.

9.3 Credits with generic marker

  • marker: HC);
  • single line;
  • parentheses optional;
  • elements separated by /.

Assignment rules:

  • first unprefixed element → Music by;
  • second unprefixed element → Lyrics by;
  • arr: → Arranger;
  • trans: → Transcriber;
  • subsequent unprefixed elements are ignored.

9.4 Implicit credits

Without explicit markers, credits:

  • must be enclosed in parentheses;
  • must appear on a single line;
  • must be separated by /.

Allowed positions:

  • same line as the title;
  • or the immediately following line.

10. Style, Key, Metrum, BPM

10.1 Common rules

  • all optional;
  • may appear only after title and credits (if present);
  • in explicit form, order is arbitrary.

10.2 Explicit form

  • each element on a dedicated line;
  • use of the corresponding marker.

10.3 Implicit form

  • elements may be combined on the same line;
  • no markers;
  • recognition based on pattern matching.

11. Element-specific rules

11.1 Style

Style is a textual description of the musical character of the piece (e.g. swing, bossa, latin, rock ballad).

Implicit form

In implicit form, style:

  • must begin with a lowercase letter (after optional spaces);
  • must not collide with valid patterns for:
  • key (Key);
  • meter (Metrum);
  • tempo (BPM).

If a text fragment can be interpreted both as style and as another structured header element, the structured interpretation always prevails.

If ambiguity cannot be resolved, style deduction fails without invalidating the entire header.

11.2 Key

Form:

  • note A–G;
  • optional accidental b or #;
  • major mode implicit;
  • m or - for minor.

Special value:

X

indicating no key, polytonality, or atonality.

11.3 Metrum

Fractional form:

N/D

with N and D being one- or two-digit integers.

Examples:

4/4
3/8

An extended form with internal numerator subdivision (clave) is allowed:

Example:

[3+3+2]/8

11.4 BPM

  • integer value with two or three digits;
  • in implicit form, must be followed by BPM (case-insensitive);
  • in explicit form (HB)), the suffix is optional;
  • decimal values are not allowed.

12. Forbidden lines and header failure

The following invalidate the entire header:

  • blank lines;
  • unrecognized elements;
  • lines interpretable as musical datapack content;
  • unresolved conflicts.

13. Examples

My Song (John Doe / Jane Roe)
Swing 120BPM 4/4 Dm

is equivalent to:

HT) My Song
HC) John Doe / Jane Roe
HS) Swing
HB) 120
HM) 4/4
HK) Dm

14. Implementation notes

  • header parsing is conservative;
  • no automatic correction is performed;
  • no partial fallback is provided.