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

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.

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 is the mode 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;
deduction based on conservative rules.

Informal syntax prioritizes readability and rapid writing.

5.3 Precedence rules¶

In case of ambiguity or conflict, the following prevails:

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

6. 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 §11.6)

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
`HT)`	Title
`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

8. Title¶

8.1 Explicit form¶

marker: HT);
the first HT) (or the implicit title, §8.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, case-insensitive, 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.

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

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

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.

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. The old per-language credit HCL) … [language] is removed: an HCL) line always sets only the primary lyricsBy.

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

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

10. Year, Style, Key, Meter, 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 Year¶

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

11.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:

must begin with a lowercase letter (after any spaces);
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.

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

11.4 Meter¶

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

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

11.6 Versions¶

Declares the alternative versions of the piece. Available only in explicit form (HV)).

HV) versions: [original, miles, jarrett] default=original

versions: mandatory keyword.
List of labels in square brackets, separated by commas.
default=<label> optional: specifies the variant shown on the first opening of the piece.

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.

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)
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

14. Implementation notes¶

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

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 “All-or-nothing” criterion (conservative parsing)¶

3.3 Conservative deduction and anti-collision principle¶

Deduction of style¶

5. Formal and informal syntax¶

5.1 Formal (explicit) syntax¶

5.2 Informal (implicit) syntax¶

5.3 Precedence rules¶

6. Elements allowed in the header¶

7. Header markers¶

7.1 Definition¶

7.2 List of markers¶

8. Title¶

8.1 Explicit form¶

8.2 Implicit form¶

8.3 Title and credits on the same line¶

9. Credits¶

9.1 Role¶

9.2 Credits with specific markers¶

9.3 Credits with generic marker¶

9.4 Implicit credits¶

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

10.1 Common rules¶

10.2 Explicit form¶

10.3 Implicit form¶

11. Element-specific rules¶

11.1 Year¶

11.2 Style¶

Implicit form¶

11.3 Key¶

11.4 Meter¶

11.5 BPM¶

11.6 Versions¶

12. Forbidden lines and header failure¶

13. Examples¶

14. Implementation notes¶

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