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 (composer, style, tempo, key, etc.);
supply global indications valid for 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.6

Characteristics:

it is mandatory in the exchanged .nrk file (exported, imported, shared) and in the song blocks of a collection, where it separates one song from the next (neumaRk_collections.md §9.2);
it must be the first line of the file;
it is not part of the header.

The rule applies at the file boundary. A song may also reach a parser without the nrk: line, when the version is known by other means (for instance from the container that stores it): in that case the song is valid and the absence produces no diagnostics. An nrk: line that is present but malformed (not in the form nrk:<major>.<minor>, e.g. nrk:abc) is ignored with W307.

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 Block recognition and invalid fields¶

The initial block is a header if none of its lines can be interpreted as a musical line (notes, chords, markers). If even one line can, the whole block is a musical datapack (§3.3).

Once recognized, the header holds field by field:

a field with an invalid value (key, meter, BPM, year) is discarded with a diagnostic (§14); the other fields stay valid and the block stays a header;
a repeated field (the same marker twice) takes its first valid occurrence; later ones are ignored with W305. HT) lines are the exception: after the first they declare alternative titles (§7.1);
in the implicit form, an unrecognized token on the metadata line is ignored with W306 (§9.3);
a line with an unknown H…) marker is ignored with W308 (§6.1).

An error in one field therefore does not lose the others: HK) H discards only the key (with E301), and the declared title, tempo and meter stay.

3.3 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;
make parsing reliable;
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 impose a complete 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, Meter, and BPM.

4. Formal and informal syntax¶

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

4.1 Formal (explicit) syntax¶

Characteristics:

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

This is the mode recommended for automated use.

4.2 Informal (implicit) syntax¶

Characteristics:

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

Informal syntax prioritizes readability and rapid writing.

4.3 Precedence rules¶

In case of ambiguity or conflict, the following prevails:

formal syntax;
positional rules;
semantic deduction;
header parsing failure.

5. Elements allowed in the header¶

The header recognizes only the following elements:

Title
Credits
Music by
Lyrics by
Arranger
Transcriber
Year
Style
Key
Meter
BPM
Versions (explicit form HV) only, see §10.6)

All elements are optional. An element with an invalid value is discarded with a diagnostic without invalidating the header (§3.2).

Title, credits and style are plain text: they do not accept the markup of neumaRk_text_markup.md and have no escapes. Double quotes " and backslashes \ are written as they are and stay in the text (HT) The "King" of Rome).

6. Header markers¶

6.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.

A marker that starts with H but is not in the list of §6.2 (HZ) foo) is ignored with W308: the line stays part of the header and does not become a title, a style or a musical line.

6.2 List of markers¶

Marker	Meaning
`HT)`	Title
`HSB)`	Subtitle
`HC)`	Generic credits
`HCM)`	Music by
`HCL)`	Lyrics by
`HCA)`	Arranger
`HCT)`	Transcriber
`HY)`	Year
`HS)`	Style
`HK)`	Key
`HM)`	Meter
`HB)`	BPM
`HV)`	Versions

7. Title¶

7.1 Explicit form¶

marker: HT);
the first HT) (or the implicit title, §7.2) is the primary title;
additional HT) lines declare alternative titles — search aliases: the piece is findable by the primary or any alternative title (e.g. Chega de Saudade / No More Blues);
a title (primary or alternative) may carry an optional trailing language tag [code] (e.g. HT) No More Blues [EN]), linking it to a lyrics language (neumaRk_lyrics.md §8.8) — the title↔language bridge: opening the piece by that title preselects that language. The tag is recognized by syntactic shape: a final bracketed token matching a language-code shape ([A-Za-z]{2,3} optionally followed by -region, normalized to lowercase). A trailing […] that is not a language-code shape is literal title text — titles rarely end in brackets (unlike parentheses), so the collision risk is negligible. The tag is stripped from the stored/searched title text;
alternative HT) lines may appear on any header line (order-independent); the serializer emits them at the end of the header block;
may contain any text.

7.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 any spaces);
must not be interpretable as a musical line (notes, chords, or markers).

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

7.3 Title and credits on the same line¶

Credits may be indicated 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.

8. Credits¶

8.1 Role¶

Credits identify the contributors to the piece.

8.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.

Note (text editions). HCL) gives the author of the default text (the neutral edition). The author of a tagged edition is written with the <…> group on the LYRICS) block (neumaRk_lyrics.md §8.8), not here. An HCL) line always sets only the primary lyricsBy.

8.3 Credits with generic marker¶

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

Assignment:

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

8.4 Implicit credits¶

Without an explicit marker, 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.

9. Year, Style, Key, Meter, BPM¶

9.1 Common rules¶

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

9.2 Explicit form¶

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

9.3 Implicit form¶

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

A token that is not a year, key, meter, BPM or chr belongs to the style if it is in the first run of unrecognized words (§10.2); an unrecognized token after a structured element is ignored with W306 (e.g. Reb in Swing 120bpm 4/4 Reb: the Italian note name is not a key).

10. Element-specific rules¶

10.1 Year¶

Indicates the year of composition: a 4-digit number between 1000 and 2999.

HY) with a value that is not a number (HY) abc) or out of range (HY) 999, HY) 3000) is ignored with W304. In the implicit form, a number that does not have the shape of a year is not a year: it stays text (style, §10.2).

10.2 Style¶

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

The value declared in the header initializes currentStyle and may be overridden locally in any measure via a play directive (=Style,…) in the M) line (see neumaRk_play_directive.md).

Implicit form¶

In implicit form, style is the first run of words on the metadata line that are not a year, key, meter, BPM or chr, in upper or lower case (Swing, rock ballad). Style:

must not collide with valid patterns for:
key (Key);
meter (Meter);
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.

10.3 Key¶

Form:

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

Special value:

indicating no key, polytonality, or atonality.

A key that does not have this form (HK) H, HK) dm, HK) Reb) is discarded with E301: the default key applies.

Default. An undeclared key means C (C major), not X: a song in C may omit the key, and NRK generators omit it (compact export, fly link). An atonal song must be declared explicitly with X.

Authorial chromatic-display default (`chr`)¶

A song may have a real tonal center and yet be meant to be read without a key signature (inline accidentals). This is the case of music with a moving tonal center: the song does have a key (it makes sense to say "let's do it a tone lower"), but the author prefers it to be read chromatically.

To declare it, add the chr token next to the key:

HK) Db chr

or, in implicit form, as a token on the metadata line:

Db 120bpm chr

Semantics:

chr is an attribute orthogonal to the key: the key stays as declared (e.g. Db), but the default rendering is chromatic (no key signature).
It is emitted only when active; its absence means normal reading with a key signature.
It is an authorial declaration that travels with the song. A reader may invert it from the display settings (showing the key signature), but that does not change the .nrk source.

Do not confuse it with atonal X: use X only for songs with genuinely no tonal center. A tonal song meant to be read chromatically must be written with its key plus chr, not with X.

10.4 Meter¶

Fractional form:

N/D

with D equal to 2, 4, 8 or 16 and N a one- or two-digit integer, at least 1. 0/4, 5/3 or 3/32 are not meters.

Examples:

4/4
3/8

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

Example:

[3+3+2]/8

Each part of the sum is 2, 3, 4 or 5.

An invalid meter in the header (HM) 5/3) is discarded with E303: the starting meter (the default) stays. The same criterion applies to the meter written in the measure context object (neumaRk_datapack.md §7.1).

Default. An undeclared meter means 4/4.

10.5 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.

A value that breaks these rules (HB) 5, HB) 1000, HB) 120.5, 5bpm) is ignored entirely with W304: it is not truncated.

The value declared in the header initializes currentBPM and may be overridden locally in any measure via a play directive (=…,Nbpm) or metric modulation (=…,figure=figure) in the M) line (see neumaRk_play_directive.md).

10.6 Versions¶

Declares the alternative versions of a %%NAME block. Available only in explicit form (HV)), one line per NAME.

HV) INTRO: [standard, adams] default=standard
HV) BRIDGE: [default, miles, jarrett] default=default

<NAME>: the block name, followed by :.
List of labels in square brackets, separated by commas; default stands for the canonical block.
default=<label> optional: specifies the variant shown on the first opening of the piece (default=default = the canonical block).
The old form HV) versions: […] is rejected with W150.

See neumaRk_versions.md for the full spec of the %%NAME … %%end blocks and the substitution semantics.

HV) is optional: in its absence, versions are deduced directly from the %%NAME "label" blocks present in the document.

10bis. `INFO)` next to the header¶

An INFO) line adjacent to the H…) lines, with no blank line in between, is information about the whole song (neumaRk_datapack.md §11.1): its label is engraved as part of the header, its body stays available on request. It is not a header element: it takes no part in deducing title, credits or key, it does not invalidate the header, and it may sit before, after or among the H…) lines. One per header (W170 on the second).

HT) Blue Info
INFO) "Transcriber's note" Transcribed from the 1961 record.
HCM) Anon

11. Forbidden lines and header failure¶

The following turn the whole block into a musical datapack (there is no header):

lines interpretable as musical datapack content (§3.3).

A blank line invalidates nothing: it closes the header (§3.1). An invalid, repeated or unrecognized field is discarded with a diagnostic and the rest of the header holds (§3.2).

12. Examples¶

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

is equivalent to:

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

13. Implementation notes¶

header parsing is conservative;
no automatic correction is provided: an invalid value is discarded, not corrected or truncated;
the header holds field by field (§3.2).

14. Diagnostics¶

Code	Condition	Effect
E301	Key cannot be parsed (`HK) H`, `HK) Reb`)	Key discarded, the default applies (§10.3)
E303	Invalid header meter (`HM) 5/3`, `HM) 0/4`)	Meter discarded, the starting meter stays (§10.4)
W150	Malformed `HV)` or old form `HV) versions: […]`	Line ignored (§10.6)
W170	Second `INFO)` next to the header	The first one holds (§10bis)
W301	First line of the implicit header yields neither title nor credits	Line read as style (§7.2)
W304	Malformed or out-of-range BPM or year (`HB) 1000`, `HY) 999`, `HY) abc`)	Field ignored (§10.1, §10.5)
W305	Repeated field (`HK)` twice)	The first valid one holds (§3.2)
W306	Unrecognized token on the implicit metadata line	Token ignored (§9.3)
W307	Malformed `nrk:` line (`nrk:abc`)	Line ignored (§2)
W308	Unknown header marker (`HZ) foo`)	Line ignored, stays header (§6.1)

Header¶

1. Definition and role of the header¶

2. nrk:version and its relation to the header¶

3. Header block and recognition criteria¶

3.1 Initial block¶

3.2 Block recognition and invalid fields¶

3.3 Conservative deduction and anti-collision principle¶

Deduction of style¶

4. Formal and informal syntax¶

4.1 Formal (explicit) syntax¶

4.2 Informal (implicit) syntax¶

4.3 Precedence rules¶

5. Elements allowed in the header¶

6. Header markers¶

6.1 Definition¶

6.2 List of markers¶

7. Title¶

7.1 Explicit form¶

7.2 Implicit form¶

7.3 Title and credits on the same line¶

8. Credits¶

8.1 Role¶

8.2 Credits with specific markers¶

8.3 Credits with generic marker¶

8.4 Implicit credits¶

9. Year, Style, Key, Meter, BPM¶

9.1 Common rules¶

9.2 Explicit form¶

9.3 Implicit form¶

10. Element-specific rules¶

10.1 Year¶

10.2 Style¶

Implicit form¶

10.3 Key¶

Authorial chromatic-display default (chr)¶

10.4 Meter¶

10.5 BPM¶

10.6 Versions¶

10bis. INFO) next to the header¶

11. Forbidden lines and header failure¶

12. Examples¶

13. Implementation notes¶

14. Diagnostics¶

2. `nrk:version` and its relation to the header¶

Authorial chromatic-display default (`chr`)¶

10bis. `INFO)` next to the header¶