# neumaRk — Full specification (v0.6.0)

> Complete specification of the neumaRk language (version 0.6.0), concatenated into a single AI-readable file.

Source: https://neumark.dev/

## Contents

- neumaRk
- Overview
- Formal specification
- Header
- Datapack
- Notes and Durations
- Chords
- Second voice per staff
- Grace notes (appoggiaturas and acciaccaturas)
- Articulations (`A)` line)
- Dynamics and text annotations
- Lyrics (`L)` line)
- Text markup
- Markers
- Flow, Measures, and Repeats
- PLAY) and FORM)
- Play directive
- Song versions
- Collections (book / playlist)
- Formats
- Official Changelog

# neumaRk

**A textual language for music, human-readable and machine-interpretable.**

neumaRk is a textual way of writing music — clear for people and precise
for computers. It sits between traditional music notation and modern
digital workflows, making music easy to write, share, analyze, transform,
and version.

It is designed to be written **directly from the keyboard**, with no mouse and
no graphical palettes, and is optimized for **lead sheets**, musical sketches,
and harmonic structures — content with one or a few voices, chords, and
structure. It is not intended for large orchestral scores, nor to replace
traditional notation: it is a complementary foundation, focused on musical
**meaning** rather than graphical rendering.

If you can read chord symbols and rhythmic patterns, you can already read neumaRk.

---

## Where to start

- **What it is, goals, and use cases** → **Overview** (`neumaRk_overview.md`)
- **The language, in normative detail** → **Specification**
  (`neumaRk_specification.md`) and the related documents (notes and durations,
  chords, flow and repeats, dynamics, text markup, voices, book/playlist
  collections, …)
- **The language's evolution** → **Changelog** (`neumaRk_changelog.md`)

> The underlying concepts — levels of detail (Compact / Human / Verbose),
> formal and informal syntax, relationship with traditional notation,
> design goals — are covered in the **Overview**.


---

# Overview

## 1. What neumaRk is

**neumaRk** is a formal system for the textual representation of music. It is designed to be simultaneously **human-readable** and **machine-readable**, with defined syntax and semantics that allow musical events, temporal structures, harmony, dynamics, lyrics, and formal sections to be described.

neumaRk is, at the same time:

- a **musical markup language**;
- a **DSL (Domain Specific Language)** oriented toward musical notation;
- a **pure textual format**, usable as a standalone file.

The language was created to bridge the gap between traditional music writing and the needs of modern software systems: versioning, reliable parsing, compactness, sharing, and automatic transformation.

---

## 2. Design goals

neumaRk is designed around the following main goals:

1. **Semantic clarity**  
   Every construct has a precise and unambiguous meaning.

2. **Human readability**  
   A neumaRk file can be read and understood directly by a musician or an author.

3. **Efficiency and speed of writing**

   neumaRk is designed to favor fast and efficient musical writing,
   based on textual input and contextual deduction,
   minimizing redundant information.

4. **Parsing reliability**  
   The syntax allows deterministic parsing, even in the presence of implicit information.

5. **Expressive flexibility**  
   The same musical content can be expressed in more compact or more verbose forms.

6. **Rendering neutrality**  
   The language describes _what_ the music is, not _how_ it must be drawn.

7. **Compatibility with modern workflows**  
   Text files, diff-friendly, suited to versioning systems and exchange via URL.

---

## 3. neumaRk as a musical DSL

neumaRk is a DSL: a specialized language, with a well-defined domain.

The domain of neumaRk includes:

- tempo and meter;
- pitches and durations;
- articulations and dynamics;
- harmony and chord symbols;
- lyrics;
- formal structure (markers, sections, repeats);
- layout and formatting hints.

The language does not attempt to replicate every graphical aspect of traditional music notation, but rather to provide a coherent and transformable textual representation.

---

## 4. Human-readable and Machine-readable

neumaRk is designed to be:

- **human-readable**, without the need for dedicated tools;
- **machine-interpretable**, without fragile heuristics.

This result is achieved through:

- a line-based syntax;
- a reduced set of symbols with stable meaning;
- explicit rules for the deduction of implicit information.

A neumaRk file can be written quickly by hand, but also generated, validated, and transformed automatically.

---

## 5. Formal syntax and informal syntax

One of the central elements of neumaRk is the coexistence of **two levels of syntax**:

- **Formal syntax**  
  Rigorous, fully disambiguated, designed to guarantee reliable parsing in any situation.

- **Informal syntax**  
  More compact and natural to write, based on common conventions and contextual deduction.

The two syntaxes are not separate languages: they are two expressive modes of the same language.

The author can decide, case by case, whether to favor:

- maximum semantic precision;
- maximum speed and readability.

---

## 6. File formats and levels of detail

neumaRk supports several **levels of explicitness**, which influence the amount of information present in the file:

- **Compact**  
  Information reduced to the essential. Maximum compactness.

- **Human**  
  A compromise between compactness and clarity. Oriented toward human reading.

- **Verbose**  
  All information is explicit. No semantic ambiguity.

These levels do not define different languages, but modes of using the same language.

---

## 7. Typical use cases

neumaRk is intended to support, among others, the following scenarios:

- writing and sharing lead sheets;
- textual representation of scores;
- embedding music in URLs or messages;
- automatic parsing and rendering;
- collaborative editing and versioning;
- conversion to graphical or audio formats.

---

## 8. Relationship with traditional music notation

neumaRk is not a direct transcription of staff notation.

Many concepts are shared (durations, measures, ties, chords), but the language:

- favors **semantics** over graphics;
- allows implicit information that cannot easily be made explicit on paper;
- separates the musical description from the visual rendering.

Traditional notation is one possible _output representation_, not the internal model.

---

## 9. Non-goals

neumaRk does **not** aim to:

- replace traditional music notation in the editorial domain;
- define a single graphical standard;
- represent calligraphic micro-details;
- cover every possible existing musical practice.

The language is intentionally focused and modular.

---

## 10. Organization of the specification

The neumaRk documentation is divided into several files, each with a
specific responsibility: this conceptual overview, the normative
specification, and the detail documents (header, datapack, notes and durations,
chords, flow, dynamics, markup, voices, grace notes, etc.).

The complete and up-to-date list of normative documents is in
`neumaRk_specification.md` §7. For the entry page and navigation,
see `index.md`.

This division allows a progressive reading and an evolutionary maintenance of the specification.


---

# Formal specification

## 1. Purpose of the document

This document defines the **formal specification** of the neumaRk language.

It establishes normatively:

- which constructs are valid
- how they must be interpreted
- which rules must be respected by parsers, validators, and rendering tools

Everything described in this document is to be considered **binding**.

---

## 2. Levels of the specification

The neumaRk specification is organized into several levels, each with precise responsibilities:

1. **Syntactic level**

   - defines the textual grammar
   - establishes which sequences of characters are valid

2. **Structural level**

   - defines the logical structure of the document
   - establishes the relationships between the various sections

3. **Semantic level**

   - defines the musical meaning of the constructs
   - clarifies ambiguities and edge cases

4. **Validation level**
   - defines the validity conditions
   - establishes errors and invalid states

## 2.1 Persistent musical context

The parsing of a neumaRk document takes place within a **persistent musical context**.

The musical context retains the most recent relevant explicit information
(pitches, durations, metric state) and **persists across the entire document**,
crossing:

- lines;
- measures;
- consecutive datapacks.

The musical context is **not automatically reset** at the beginning of a
new datapack.

A datapack represents a structural and vertical-synchronization unit,
but **does not constitute a semantic boundary for musical deduction**.

In the absence of explicit values, the deduction rules always refer
to the current state of the musical context.

---

## 3. Normative terminology

In this document the following terms are used with normative meaning:

- **must** / **must not**: mandatory requirement
- **may** / **may not**: optional behavior
- **is invalid**: the document must be rejected
- **is interpreted as**: deterministic behavior

---

## 4. Contextual use of symbols

Some textual symbols of neumaRk have **contextual** semantics,
determined by the type of musical line in which they appear. The
normative algorithm by which the **line type** itself is deduced (in the
absence of an explicit marker) is in `neumaRk_datapack.md §3.bis`.

In particular:

- the symbol `.` (dot)
- the symbol `!` (exclamation mark)

take on different meanings depending on whether they appear in:

- note lines (`N) `);
- chord lines (`C) `).

They take on different meanings, even within the same lines, depending on their position.

The line context and the position relative to the other elements of the line are always sufficient to resolve the meaning of the symbol deterministically.

There is no valid case in which a symbol can be ambiguous
within the same line context.

## 5. Document identification and extension

A neumaRk document is a text file encoded in UTF-8.

The recommended file extension for neumaRk documents is:

```
.nrk
```

The use of the `.nrk` extension allows tools, editors, and operating systems
to reliably recognize neumaRk documents.

The extension is **recommended but not mandatory**.  
A document is considered valid as a neumaRk document based on its
content, and not based on the file name or its extension.

Tools **may** assume the `.nrk` extension as the default
when reading or writing neumaRk files.

## 6. General structure of a neumaRk document

A neumaRk document may contain, in order:

1. Header (metadata)
2. Musical content and formatting content

The order of the sections is significant and must be respected.

### Structural delimitation

In neumaRk, a **blank line has structural value**.

Blank lines delimit logical blocks of the document, in particular:

- the end of the header;
- the separation between consecutive musical datapacks.

A structural block (header or datapack) always consists of one or more
consecutive non-blank lines.

---

## 7. References to related documents

This specification refers to the following documents:

- `neumaRk_overview.md`
- `neumaRk_formats.md`
- `neumaRk_header.md`
- `neumaRk_datapack.md`
- `neumaRk_markers.md`
- `neumaRk_chords.md`
- `neumaRk_notes_and_durations.md`
- `neumaRk_grace_notes.md`
- `neumaRk_voices.md`
- `neumaRk_articulations.md`
- `neumaRk_lyrics.md`
- `neumaRk_flow_and_repeats.md`
- `neumaRk_dynamics.md`
- `neumaRk_text_markup.md`
- `neumaRk_play_and_form.md`
- `neumaRk_play_directive.md`
- `neumaRk_versions.md`
- `neumaRk_collections.md`

Each document elaborates normatively on a specific aspect of the language.

---

## 8. Compatibility and versioning

Every neumaRk document must explicitly declare the version of the language used.
The first line of the document must report the sequence `nrk:` followed by the reference version in the form major.minor

example

```
nrk:0.6
```

The compatibility rules between versions and the evolution of the language are documented in `neumaRk_changelog.md`.

---

## 9. Extensions

The neumaRk language may be extended only within the limits explicitly allowed by the specification.

Undefined or unrecognized constructs make the document **invalid**, unless otherwise explicitly indicated.


---

# 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:<major>.<minor>

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:

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
- **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:

```
X
```

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.


---

# Datapack

## 1. The datapack concept

A **datapack** is the fundamental structural unit of musical content in neumaRk.

It represents a **vertical block of musical information synchronized in time**, typically corresponding to one or more aligned staves:

- markers
- chords
- notes
- articulations
- dynamics
- lyrics
- formatting

Each datapack describes a coherent temporal sequence (one or more consecutive measures).
Musical datapacks are separated from one another by one or more blank lines,
which act as structural delimiters. The presence of a blank line implies the conclusion of the preceding datapack.

---

## 2. Line types

Each line of the datapack has a **semantic type**.

The type may be:

- **explicit**, via a marker
- **implicit**, deduced from the content and position

### 2.1 Explicit line markers

Explicit markers are:

- one, two, or three uppercase letters
- followed by `)`
- followed by a space

| Marker | Type          |
| ------ | ------------- |
| `M)`   | Markers       |
| `C)`   | Chords        |
| `A)`   | Articulations |
| `N)`   | Notes         |
| `D)`   | Dynamics      |
| `L)`   | Lyrics        |
| `F)`   | Format        |

The markers are optional.

The `N)` marker admits two morphological 2-character variants,
explicitly provided for by the specification:

- `N+` — new staff introduced in this datapack (§4.5);
- `N2` — second voice on the same staff (see `neumaRk_voices.md`).

The digit `2` and the sign `+` replace the `)`, preserving
the 2-character width invariant required for vertical
alignment.

Likewise, the `C)` marker admits a variant:

- `C+` — line of **alternate** chords above the base line (comment-label
  and line scope in `neumaRk_chords.md` §7).

The `+` sign replaces the `)` as in `N+`, preserving the same
width invariant.

---

## 3. Logical order of lines (implicit deduction)

In the absence of explicit markers, the type of the lines is deduced following the logical order:

1. **Markers** (at most one line, optional)
2. **Chords**
   - zero or more lines
   - the last is considered the main line
3. **Note groups**, each composed of:
   - one **Articulations** line (optional, first)
   - one **Notes** line (mandatory in the absence of chords)
   - one **Dynamics** line (optional, after — see `neumaRk_dynamics.md`)
   - one **Lyrics** line (optional, last)

   A datapack may contain **from 1 to 4 note groups**: each group
   corresponds to a staff of the system (see §4).
4. **Format** (at most one line, optional, always final)

---

## 3.bis Line-type deduction (normative algorithm)

§3 gives the **logical order** of the types; this section formalizes
its **deduction algorithm**: how, in the absence of an explicit marker, the
type of a line is determined from content + position. The rule written here is
**normative** — it is the language, not an implementation detail. An explicit
marker (§2.1) always wins: the algorithm that follows applies only to lines
**without a marker**.

### 3.bis.1 Datapack structure

Only **Markers** and **Chords** are unique per datapack (they are shared
by the whole system, §4.1); everything else is a **repeated note group**,
once per (staff × voice):

```
datapack ::= [Markers]?  Head  Group{1..8}  [Format]?

Head     ::= ( [A]? Chord )*        // 0+ chord-row, each possibly
                                    //   decorated by an A) above
Group    ::= [A]? N [D]? [L]?       // one (staff × voice)
```

- **Head** (Markers + Chords): unique, shared. The articulations line
  may precede a chord-row to decorate it (a chord-row may carry its own
  rhythm, `neumaRk_chords.md §4`); for this reason `A)` is admitted **before**
  `C)`.
- **Group**: repeats up to **8 times** = max **4 staves** (§4) × **2 voices**
  per staff (§4.6). Voice 2 **is not implicitly deducible** — there is no
  way to distinguish, from content alone, "voice 2 of the same staff" from "new
  staff": it must always be declared with the explicit marker `N2`. Thus
  *implicit* deduction alone produces up to 4 groups (the staves); the 8 are
  reached only with `N2`.
- **Format**: unique, always final (§9).

### 3.bis.2 Computation model

Deduction is a **single-pass, per-datapack automaton** that scans the
lines in source order while maintaining two pieces of state:

- `lastType` — the type of the last line (init `Empty`);
- `headClosed` — `false` until the first **Notes** line of the
  datapack appears, then `true` forever. It marks the boundary between Head and Groups.

The `lastType` guards **are the transition function** of the automaton: they encode
both the order *within* a group, and the **loop-back** that opens the
next group (re-entry on `A` or on `N`). `headClosed` prevents Chords from
reappearing once the staves have been entered.

### 3.bis.3 Pre-filter: decorative lines

Before the cascade, a **purely decorative** line — composed only of
simple barlines, `:`, compact repeat forms (`neumaRk_flow_and_repeats.md §6.1`),
dots, spaces, and tabs — is **skipped** and does not receive a musical type (it remains
structural; its barline decorations belong semantically to the
other lines). Exception: the **`>`/`^` rescue** in §3.bis.6.

### 3.bis.4 Classification cascade (normative precedence)

On non-decorative lines without a marker, a **first-match-wins** cascade
is applied. The **order is binding**: the content predicates are
deliberately permissive and do not over-match *only* thanks to (a) this order and
(b) the position guard. The triad that defines each type is
**predicate + guard + exclusions**.

| # | Type | Predicate (content) | Guard (position) | Exclusions |
|---|------|---------------------|------------------|------------|
| 1 | **Markers** | only `[…]` / barline / spaces | is the **first line** of the datapack | — |
| 2 | **Chords** | ≥1 valid chord (`neumaRk_chords.md §3`) + barline / `.` / `%` / comment-label / spaces — **or** only `%` (TB1bis) | **head open** (`!headClosed`) | not slash-only (TB2); not rest-only `r`/`!` (TB1) |
| 3 | **Articulations** | charset of the `A)` vocabulary (`neumaRk_articulations.md`) | `lastType ≠ Articulations` | not `^`-only (TB3); not a valid notes-line (TB4) |
| 4 | **Dynamics** | dynamics charset (`< > c d f m p s z - . \| :`) | `lastType == Notes` | — |
| 5 | **Lyrics** | word-char + `. - _ ' \| :` (**the most permissive**) | `lastType ∈ {Notes, Dynamics, Lyrics}` | — |
| 6 | **Notes** | *default / sink* | any | — |

Notes on the guards:

- **Markers** (line 1): the *implicit* deduction of Markers occurs **only
  on the first line** of the datapack. A markers-shaped line further down is not
  Markers (an explicit `M)` remains possible wherever the spec allows it).
- **Chords** (line 2): the normative condition is **head open**. This is equivalent to
  saying that chords live only before the first notes line: chords
  are unique and shared (§4.1), and no valid datapack has a chord-row after
  a notes-row. The parser realizes the constraint with the positional flag `headClosed`
  (closed at the first Notes line of the datapack) — aligned to §3.bis since 2026-05-25
  (FU.3a).
- **Lyrics** (line 5): the predicate is the most permissive (it matches almost any
  text). This is **intentional**: the permissiveness is contained by the position
  guard, and in any case the default type is Notes. It is not narrowed (that would be
  non-monotonic and would risk changing the classification of existing songs).
- **Notes default**: line 6 is the *sink* — every line that reaches the bottom of the
  cascade is a notes line. It is also the loop-back mechanism: two consecutive `N)`
  (both sink) are two distinct staves.

### 3.bis.5 Tiebreakers

Three disambiguations resolve cases in which a permissive predicate
would match the wrong type:

- **TB1 — rest-only → Notes.** A line composed **only** of rest-tokens
  (`r` / `!`), barline, `.`, `%`, and spaces belongs to the **stave** (it is a notes
  line of rests only), not to an empty chord-row. It applies after Chords/Alt
  **and after Articulations**:

  ```
  A7        ← Chords          | > .       ← Articulations
  r         ← Notes (TB1)     r           ← Notes (TB1)
  ```

  > Implemented since 2026-05-25 as a single rule **"rest-only forces Notes"**: the
  > line is intercepted *before* Chords and Articulations, regardless of
  > `lastType` (FU.3b after Articulations + FU.3c after Chords — both produced
  > the wrong type, respectively empty chord-row and Articulations). A
  > guard requires a real rest-token `r`/`!` or `%`, so `| > |` (anacrusis)
  > remains handled by the rescue (§3.bis.6).

- **TB1bis — `%`-only without a chord-row → Chords.** A line composed **only** of
  `%` (plus barline, `.`, spaces — **no** rest-token `r`/`!`) **with head
  open** (`!headClosed`) and **in the absence of a real chord-row** in the datapack
  is a **chord-row of measure repeats only**: each `%` repeats the last
  chord-measure (even from the preceding datapack — the measure-repeat lookback
  is cross-datapack). It is the exception to TB1: `%` *without* a rest-token is not
  forced to Notes, but falls into the Chords branch (whose `isChordLine` already
  accepts `%`).

  ```
  | C7 | F7 |     ← Chords
  | a b c | …     ← Notes (closes the head)

  | % | % |       ← Chords (TB1bis): repeats C7, F7 from the datapack above
  | d e f | …     ← Notes
  ```

  > Decision **2026-05-26**, *supersedes* the previous principle "if you want a
  > chord-row of only `%` you must declare it with `C)`". Rationale: "chords that
  > repeat while the melody changes" is the most common lead-sheet pattern;
  > forcing `C)` on every continuation was gratuitous friction. Two guards keep
  > the case narrow:
  >
  > 1. **no rest-token** — a line with `r`/`!` always remains Notes (TB1):
  >    rests are unambiguously notes;
  > 2. **`!sawRealChordRow`** — if the head *already* has a chord-row with a real
  >    chord, a subsequent `%`-only line remains Notes (it is a notes-row of
  >    repeats), because the datapack's chord-row is already defined.
  >
  > Escape-hatch for the opposite reading (a *second notes staff* of only `%`):
  > the explicit marker `N+` / `N)`. Known limitation: a datapack of **only** `%`
  > (without any notes-row) is read as a chord-row and violates the grammar
  > `(A?ND?L?)+` (≥1 `N` is required); declare it with `N)` if the intent is a
  > standalone notes-row of repeats.

- **TB2 — slash-only → Notes.** A line of standalone `/` only (plus barline,
  `.`, spaces) is **slash rhythm** (`neumaRk_notes_and_durations.md §10`), never
  a chord-row: `/` on its own is syntactically a quasi-chord but semantically
  a note event.

  ```
  | / / | / / |     ← Notes (TB2)
  ```

- **TB3 — `^`-only → Notes.** A line of `^` only (plus `|` and spaces) is a
  notes line with **ties** only (`neumaRk_notes_and_durations.md §6`),
  not Articulations.

  ```
  | ^ |     ← Notes (TB3)
  ```

- **TB4 — valid notes-line → Notes.** A line that is a **valid notes-line**
  has priority over Articulations, even if it falls entirely within the charset
  of the `A)` vocabulary. Necessary because some letters of the vocabulary are also
  note-names/durations: in particular **`g`** (composes `gl` glissando, §9) is also
  the note G, and the durations `1`–`4` are in the charset → `g`, `g4`, `g g g`
  matched `articulations_line` and were stolen from A).

  ```
  A7        ← Chords
  g         ← Notes (TB4), not Articulations
  ```

  > Predicate: every token (split on spaces; the barlines `|`/`:` at the edges are
  > stripped) is a valid note-token according to the **canonical** grammar
  > `parse_notes` (single source → no divergence), and at least one token carries a
  > real pitch `[a-g]`/`r`. Articulation-only tokens (`>`, `tr`, `-`, `o`,
  > `gl`, `~`…) **do not** match `parse_notes` → the line remains Articulations;
  > a line of only `.`/`,`/`^` (placeholder, no real pitch) → remains
  > Articulations. Implemented 2026-05-26 (`isNotesLineForTiebreak` in
  > `map_functions.cpp`), gated also on the `>`/`^`/`~` rescue (§3.bis.6). Principle:
  > *in case of A)↔N) ambiguity, the note wins.*

### 3.bis.6 `>` / `^` rescue

A line that the pre-filter (§3.bis.3) would have discarded as decorative — because
`>` is readable as an anacrusis attached to a barline — but which contains `>`
or `^` and is **entirely** articulations-charset, is recovered as
**Articulations** (here `>` is an accent, not an anacrusis):

```
| > |     ← Articulations (rescue): accent on the first event of the measure
```

The rescue is a branch **outside the cascade** and always produces Articulations (
articulations may open a group in any position); it is subject to the
same constraint `lastType ≠ Articulations` and the `^`-only exclusion (TB3).

> **First line of the datapack.** The rescue presupposes a context above it. In
> first position (`line_id == 0`) a line `| > |` is read as
> **Markers/anacrusis**, not as an accent: the Markers pre-filter (cascade line 1)
> takes precedence, and `>` is ambiguous between accent and upbeat when there is no notes
> line below it to disambiguate. It is a deliberate choice (decision 2026-05-25):
> in the absence of context, the anacrusis reading prevails.

### 3.bis.7 Post-pass: AlternateChords promotion

The base classification assigns **Chords** to all implicit chord-rows.
A subsequent pass relabels as **AlternateChords** (`C+`, alternate chords
above the base) the consecutive chord-rows that precede the last,
**only** if no chord-row of the datapack carries an explicit marker (if
the user has chosen the markers, their choice is respected). Limit: max 2 alternate
lines per datapack (**E127**). Full spec in
`docs/feature-alternate-chords.md` and `neumaRk_chords.md §7`.

### 3.bis.8 Derivations and invariant

- The **`articulations_line` charset** (line 3) **derives** from the closed
  vocabulary of `neumaRk_articulations.md` (single source): deduction and the
  renderer semantics must not diverge.
- **Invariant**: the algorithm may only be **extended** toward what is written
  here, never silently change an existing line→type mapping. The
  parser↔spec divergences on classification (FU.3a *head closed*, FU.3b
  *rest-only after `A)`*, FU.3c *rest-only after Chords*) were **closed on
  2026-05-25**, verified by difference on the "classification golden" battery
  (`wasm/tests/fixtures/classify_*`). **FU.1** remains open (articulations charset
  from the closed vocabulary), which does not change the line→type mapping.
- **Mapping change 2026-05-26 (TB1bis)**: the `%`-only line without a rest-token,
  with head open and without a real chord-row, moves from **Notes** to **Chords**
  (§3.bis.5 TB1bis). It is a *deliberate and documented* change of the mapping, not
  a silent one — admitted because the language is not yet widespread (no version
  bump). Covered by the goldens `classify_pct_only_chords` (promotion) and
  `classify_pct_after_real_chords` (`sawRealChordRow` guard).
- **Correction 2026-05-26 (TB4)**: the line that is a valid notes-line but falls
  within the `A)` charset (typically the note-only lines **`g`**: `g`, `g4`,
  `g g g`) moves from **Articulations** to **Notes** (§3.bis.5 TB4). It is a bug-fix
  toward the correct behavior ("the note wins"), not a controversial
  extension. Covered by the goldens `classify_note_g_after_chords` and
  `classify_note_g_vs_artic` (with the negative `> . . .` → remains Articulations).

---

## 4. Multiple staves per datapack (multi-stave)

A datapack may represent a **system with multiple aligned staves**
(e.g. melody + bass). The number of staves is given by the **number of note
groups** (`A?ND?L?`) present, up to a maximum of **4**.

The number of staves may **vary from one datapack to another** in the same
song: one datapack may contain a single staff and the next two or
more, without prior declarations.

### 4.1 Elements shared by the system

The following elements are **common to all staves** of the datapack:

- the **Markers** line
- the **Chords** line(s)
- **barlines** and **measure decorators** (voltas, change of
  meter/key, `$`, `@`, `DC`, `FINE`, etc.)
- the key and meter of the system

The measure barlines cross all staves vertically.

### 4.2 Elements independent per staff

Each group `(A?ND?L?)` defines an independent staff with its own:

- **Notes** (mandatory)
- **Articulations**, **Dynamics**, **Lyrics** (optional)
- **clef** declared via the inline directive `(@…)` as the first token
  of the Notes line — see `neumaRk_notes_and_durations.md` §9. In
  the absence of a directive, the last clef defined in the context applies
  (default: treble clef).
- ties, beams, and tuplets (all contained within the staff)

### 4.3 Horizontal alignment

All staves of the system must contain the **same number of
measures**: the vertical alignment between staves is temporal.

### 4.4 Example

```
C) | Gm6 |
N) | g | a | bb | a |
N) | (@F) g,4 bb8 d e4 d | g,4 bb8 d e4 d | g,4 bb8 d e4 d | g,4 bb8 d e4 d |
```

A 2-staff system: the first in treble clef (default), the second
in bass clef. The chord `Gm6` is common to the system.

---

### 4.5 Staff continuity between datapacks (`N+`)

When a song has multiple datapacks, each staff (stave) has a **persistent
identity**: the "first staff" of a datapack is the same "first staff"
of the previous one — it inherits pitch context, the clef in effect, durCtx, and
is rendered in the same vertical position.

The base identity is **positional**: the first `N)` of the datapack
corresponds to the first `N)` of the previous datapack, the second to the
second, and so on.

To **add a new staff** in a datapack without breaking its
identity with the previous ones, the `N+` marker is used in place of `N)`.

```
N+   <content of the new staff>
```

The `+` replaces the `)` (it does not add to it): the prefix remains 2
characters as with `N)`, so the vertical alignment of measures remains
identical between adjacent staves.

#### Rules

- `N)` = **continuation** of the next staff of the previous datapack
  (FIFO, in source order). It inherits its context (pitch, clef,
  duration).
- `N+` = **new staff** introduced in this datapack. It starts with
  fresh context (the orientation reference depends on the initial
  clef, see `neumaRk_notes_and_durations.md` §2.2).
- **Source order = visual order** top→bottom. The `N+` marker
  determines only the identity (new vs. continuation), not the
  position.
- `N+` in the **first datapack** of the song is admitted but redundant (in
  the absence of preceding datapacks all staves are necessarily new); it is
  treated as a normal `N)`.
- **Unchanged limit:** max 4 total staves per datapack (sum of `N)`
  + `N+`).

#### Errors

- **E122** — `N) without match`: the datapack has more `N)` than the
  number of staves the previous one had. `N+` is missing (or there is one `N)`
  too many).

#### Example

Datapack 1 (intro with 2 staves, treble + bass):

```
M) [intro]
C) G7
N) |: <d b>2 <e c>4 | <f d>2 <e c>4 :|
N) (@F) g,4. d'8 e d | f4. d8 e d
```

Datapack 2 (Theme): adds a third staff **at the top** (vocal
melody), keeping the intro's treble and bass in the middle and at the bottom.

```
M) [Theme]
C) > | G7
N+ >  d8 | b'^ | b2 r8 d,
A) >    | . ! | . !
N) > |: <d b>2 <e c>4 | <f d>2 <e c>4 :|
N) > | g,4. d'8 e d   | f4. d8 e d
```

Resulting mapping (for the engine, not visible in source):

| source row | type  | identity                         |
|------------|-------|----------------------------------|
| 1 (`N+`)   | new   | new stave (top)                  |
| 2 (`N)`)   | cont. | = first intro staff (treble)     |
| 3 (`N)`)   | cont. | = second intro staff (bass)      |

The context (last_pitch, clef, durCtx) of staves 2 and 3 of the Theme
comes from staves 1 and 2 of the intro; staff 1 of the Theme starts fresh.

#### Cases not covered

The `N)`/`N+` syntax expresses the common situation *"I add a
staff at the top/in the middle/at the bottom"*, but it does not cover:

- **selective drop** (a datapack that keeps the 2nd staff of the previous one
  but drops the 1st);
- **reorder** (swapping the visual order of existing staves while keeping
  their identity).

For these cases a future extension could introduce an explicit
reference to the staff's internal ID (e.g. `N<n>)`). Not spec'd in this
version.

---

### 4.6 Second voice per staff (`N2`)

Each staff may host an independent **second voice**, introduced
by the `N2` line. Stave and voice are distinct concepts: the staff is the
pentagram, the voice is a musical stream within the staff.

Voice 2 shares the clef, key, meter, barlines, and chord line
with voice 1, but maintains an independent persistent musical context.
Voice 1 has stems up, voice 2 stems down.

The complete specification of syntax, context, binding, and diagnostics
is in **`neumaRk_voices.md`**.

---

## 5. Datapack validity rules

A datapack is valid if:

- it contains **at least one Notes line or one Chords line**
- it respects the logical order of the lines
- all musical lines are **temporally alignable**

It is invalid:

- a datapack with only text lines
- a datapack with a non-final Format line

---

## 6. Barlines and measures

All musical lines (Markers, Chords, Articulations, Notes, Dynamics, Lyrics):

- contain barlines — simple and compound — and any measure decorators (in the absence of barlines all content belongs to the first measure of the staff)
- implicitly define the division into measures

The **Format** line is the only exception: it does not admit barlines (neither simple nor compound) and no measure decorators.

### 6.1 Supported barlines

The admitted barlines are:

- `|` simple barline
- `||` double barline
- `|.` or `.|` end
- `|:` repeat start
- `:|` repeat end

The **final barline** must be preceded by a space.

---

## 7. Measure decorators

Measure decorators are elements **adjacent to a barline** and are divided into:

- **BEGIN decorators** (to the right of the barline)
- **END decorators** (to the left of the barline)

### 7.1 BEGIN decorators

Positioned immediately to the right of the barline.

Possible decorators:

- **Change of meter and/or key**

  - within parentheses
  - separated by a comma
  - arbitrary order

  Examples:

  ```
  |(3/4,Dm)
  |([3+3+2]/8)
  ```

- **Volta endings**

  - text within square brackets
  - optional `+n` for the duration in measures

  Example:

  ```
  |[1.]+4
  ```

  In the absence of `+n`, the volta closes **automatically** at the first `:|`
  encountered within **4 measures** (the typical case of `[1.]` endings).
  If no `:|` appears within the following 4 measures, the volta indicates
  an **exit** — use `+n` for non-standard cases.

- `$` segno
- `@` coda

If present, **meter and key must precede** every other BEGIN decorator.

---

### 7.2 END decorators

Positioned immediately to the left of the barline.

Supported decorators:

- `DC`
- `DCal@`
- `DCalFINE`
- `D$`
- `D$al@`
- `D$alFINE`
- `FINE`
- `al@`
- free text within square brackets (graphic annotation)

The `$` and `@` signs are **BEGIN decorators** (see §7.1): they identify the point where the segno or coda is located, not a jump toward them.

---

## 8. Markers line

The **Markers** line:

- contains markers enclosed within square brackets
- the markers refer **to the start of the measure**

If a marker is preceded by a barline:

- there must be **a space** between the barline and the marker
- to avoid ambiguity with the volta decorators

It is **best practice** to place the flow decorators (DC, D$, coda, etc.) on this line.

---

## 9. Format line

The **Format** line may be declared:

- in explicit form, via the marker `F)`;
- in implicit form, if the content of the line is uniquely
  recognizable as a format line.

The Format line, if present, must be:

- unique per datapack;
- always the last line of the datapack.

In case of ambiguity with a musical line, the musical
interpretation always prevails and the line is not considered Format.

It contains alignment indications:

| Symbol  | Alignment           |
| ------- | ------------------- |
| `\|*`   | LEFT                |
| `*\|`   | RIGHT               |
| `\|*\|` | CENTER              |
| `\|**\|` | JUSTIFIED (default) |

---

## 10. Margins between datapacks

A line:

- that follows a blank line
- that begins with `-`
- that contains only `-`, spaces, tabs, or `%`

indicates a **vertical margin** between datapacks.

The depth of the margin is given by the maximum number of consecutive `-`:

- `- - -` → margin 1
- `- -- -` → margin 2
- `--- -` → margin 3

The `%` symbol indicates a **possible page break**.

## 11. Comments

Single-line comments are permitted in the form `// comment`. The scope is the line: everything that follows `//` up to the newline is ignored by the parser. Comments may stand on their own line (above/below a datapack, or between the lines of a datapack) or trailing a line of code.

The discriminant between the two forms is **positional**: if there is at least one non-whitespace character before `//`, the comment is **trailing** (the part of code before `//` remains valid); otherwise the **entire line** is a comment.

Multi-line comments (`/* … */`) are not supported: NRK is a column-sensitive language (the barline `|` align the lines of the datapack vertically) and block comments would break the alignment.

The sequence `%%` at the start of a line **is not a comment**: it is reserved for the song version blocks (see `neumaRk_versions.md`).

---

## 12. Version blocks

Between one datapack and another, **version blocks** may appear, marked `%%NAME … %%end`, which enclose one or more alternate datapacks of the song. The blocks live standalone between datapacks, not inside them. See `neumaRk_versions.md` for the full spec.


---

# Notes and Durations

This document defines the syntax and semantics of **musical notes** in neumaRk: pitches, accidentals, durations, prolongations, and implicit deduction mechanisms.

The goal is to provide a **deterministic** specification that is nonetheless compatible with rapid writing in informal mode.

---

## 1. Note event

A **note event** is the atomic musical unit in the `N)` line of neumaRk.

Each note event represents a single musical occurrence in time
and contributes to building the rhythmic and melodic sequence of the piece.

A note event may specify, in explicit or implicit form:

- a pitch;
- a duration;
- duration modifiers;
- octave modifiers;
- annotations;
- ties.

Some of these elements may be omitted, provided they can be
deduced deterministically from the **persistent musical context**,
according to the rules defined in this document.

### Continuity of deduction

The deduction of pitches and durations in neumaRk is based on the last
explicit value encountered **across the entire document**, and is not limited to a single
note line or a single datapack.

At the start of a new musical datapack, the reference for deducing
pitches and durations is the last note event of the previous datapack,
if present.

In the absence of any prior reference (for example at the start of the
piece), deduction uses the default values defined by the specification,
or fails in cases where deterministic deduction is not possible.

---

### 1.1 Syntactic structure of the note event

A note event consists of an **ordered sequence of adjacent elements**,
with no intervening spaces.

The order of the elements is **fixed** and must be the following:

1. **Tie to the preceding note** (`^`), optional
2. **Pitch**, optional because deducible
3. **Forced accidental** (`!`), optional  
   (allowed only if the pitch is explicitly indicated)
4. **Octave modifiers**, optional  
   (relative octaves via `'` or `,`, or absolute octave)
5. **Duration**, optional
   - explicit duration (power-of-2 number, with optional dots or multipliers);
   - tuplet indicators;
   - or `?` for unknown duration
6. **Annotations**, optional, between double quotes
7. **Tie to the following note** (`^`), optional

All elements composing a note event **must be adjacent**.
The presence of a space separates distinct note events.

> **Groups in parentheses `(…)`.** Beyond explicit duration as a list
> (`r(…)`, suffix) and clef change (`(@…)`, prefix), a note event may
> carry additional `(…)` groups that specify its **notehead** or an **ornamental
> glissando**. Their meaning is determined by content and position: see
> the single rule in §11. At most per note: one clef (prefix), one
> glissando-in (prefix), one notehead (suffix), one glissando-out (suffix).

A note event may omit one or more elements according to the deduction rules
defined in this document, but **the relative order of the elements may
never be altered**.

---

#### Note events consisting of a single symbol

A note event consisting exclusively of a single symbol is allowed,
without explicit indication of pitch or duration, provided a valid
prior musical context exists.

The following symbols may by themselves constitute a valid note event:

- **Octave modifiers** (`'` or `,`)
- **Tie** (`^`)

In such cases, the note event:

- inherits the **pitch** from the preceding note event;
- inherits the **duration** from the preceding note event;
- applies exclusively the semantics of the indicated symbol.

In particular:

- an event consisting of `'` or `,` modifies the octave of the inherited pitch;
- an event consisting of `^` prolongs the preceding note **by the same value**.

A note event consisting of a single symbol is valid **only if**
pitch and duration can be deduced deterministically from the context.
In the absence of such context (for example at the start of the piece),
the event is invalid.

---

## 2. Pitch

### 2.1 Basic syntax

A pitch is expressed as:

```
<note>[accidental][octave]
```

Where:

- `note` ∈ `{a b c d e f g}`
- `accidental` ∈ `{#, b}` (optional, also double)
- `octave change` (optional, see the next paragraph)

Examples:

```
c   d#   fb   g##
```

---

### 2.2 Relative octaves

The octave is computed based on the pitch of the preceding note, considering the smallest interval from it.

Examples:

```
f4 bb f c
```

The character `'` immediately after the note's pitch shifts its octave upward.
The character `,` immediately after the note's pitch shifts its octave downward.

Examples:

```
f4 bb, f' c'
```

Multiple consecutive signs are permitted for octave change.

Examples:

```
a,4 g''' a,,,
```

At the start of the piece (or at the start of a staff, in a multi-staff
datapack) the orientation pitch is the **note marked by the
starting clef**: clefs in G use a `g` reference, clefs
in F an `f` reference, clefs in C a `c` reference.

In detail, for the clefs provided by neumaRk:

| Clef                            | Notation                | Reference   |
|---------------------------------|-------------------------|-------------|
| treble                          | `(@G)`                  | **g4**      |
| treble 8va alta                 | `(@G8va)`               | **g5**      |
| treble 8va bassa                | `(@G8vb)`               | **g3**      |
| soprano                         | `(@C1)`                 | **c4**      |
| mezzo-soprano                   | `(@C2)`                 | **c4**      |
| alto                            | `(@C3)`                 | **c4**      |
| tenor                           | `(@C4)`                 | **c4**      |
| baritone (C variant)            | `(@C5)`                 | **c4**      |
| baritone (F variant)            | `(@F3)`                 | **f3**      |
| bass                            | `(@F)` or `(@F4)`       | **f3**      |
| bass 8va bassa                  | `(@F8)` or `(@F8vb)`    | **f2**      |

> **Only the clef declared at the start** (of the piece or of the staff)
> determines the orientation reference. Any subsequent clef change
> (see §9) modifies the graphical clef and the visual
> rendering of the notes, but does **not** alter the reference used
> for computing relative octaves.

---

### 2.3 Absolute octaves

It is nonetheless possible to assert the absolute octave of a note by adding
the character `@` followed by the octave number (4 for middle C)
and the character `_`. The numbering is scientific: C-1 is
MIDI 0, C9 is MIDI 120; the practical useful range is roughly `-1`..`9`.

Examples:

```
c@4_8. g@3_2
```

> **The duration is mandatory** when using `@<n>_`: the `_` acts as a
> separator between the octave number and the duration value, and is meaningless
> without a value following it. A spelling such as
> `c@4_` (without duration) produces error **E008**.

`'`/`,` remain allowed as a "nudge" on top of the absolute octave — `c@4_'`
is equivalent to C5, `c@4_,8` is equivalent to C3 as an eighth note. They are discouraged
because redundant: use directly `c@5_` / `c@3_8`.

After a note with an absolute octave, the inference for subsequent events
restarts from that note as the standard `last_pitch` (smallest interval
via DIATONIC_MATRIX, as in §2.2).

**Absolute octave in chord-stack `<…>`**

Inside a chord-stack, the absolute octave is allowed **only on the
first pitch**, in the form:

```
<a@4_ c>4
```

Mandatory constraints:

1. the `_` that closes `@<n>_` on the first pitch is **mandatory** (it is
   the separator required by the notation);
2. the **duration of the chord after `>` is mandatory** (e.g. `>4`).
   The duration lives outside the braces and refers to the whole chord;
   omitting it falls into the same error **E008** as the
   monophonic case, because internally the token is reformulated as
   `a@4_4` (first pitch + duration) and that `_` remains without a numeric
   value following it.

The subsequent pitches of the chord-stack (the "extras") currently accept
only relative notation: their octave is inferred by smallest
interval starting from the primary pitch (see §2.2). A spelling
such as `<a@4_ c@5_>4` is not supported; see the backlog for a future
extension to the extras.

---

### 2.4 Implicit pitch

If a note **does not specify a pitch**, it inherits the last
pitch encountered during parsing; if no pitch has yet been
seen, the **initial orientation reference** defined
in §2.2 is used (`g4` for treble clef, `f3` for bass clef,
`c4` for C clefs, etc.).

Example:

```
f4 8 8 g 4 8
```

---

### 2.5 Forced accidentals

The character `!` immediately after the pitch **forces the display of the accidental**, even if it would be implicitly deducible from the key.

Example:

```
f#!8
```

This indicates that the accidental `#` must be displayed graphically.

#### 2.5.1 Propagation of accidentals within the measure

An accidental, once shown, **propagates** according to the standard convention
until the end of the measure. The rule is modeled by a **matrix
`[letter][octave]`** that stores the active inflection for each pair
letter+octave; the matrix is **initialized from the key** at the start of every
measure (and every staff).

- A note shows its own accidental symbol **only if** its inflection
  **differs** from the current value in the matrix for that letter+octave (or
  if forced with `!`, §2.5); otherwise **no symbol**. When the symbol is
  shown, the matrix is **updated**.
- Propagation is **per-octave**: an accidental on `c` (octave 4) does **not**
  affect `c` of another octave (`c5`). Each letter+octave pair is
  independent.
- **Chord-stack** (§2.6): each pitch of the stack is evaluated individually against the
  matrix.
- **Voice 2** (`N2`): has a propagation matrix independent of voice 1.
- **Grace notes** (preceding the main): are evaluated against the matrix but do **not
  update** it; if a grace deviates from the matrix, it **breaks propagation** for
  that letter+octave → subsequent mains in the same measure show an
  explicit accidental even if they coincide with the matrix (so the reader is not
  misled by the inflection introduced by the grace). See
  `neumaRk_grace_notes.md §8`.

---

### 2.6 Stacked chords (chord-stack) `<…>`

Multiple pitches sounded together are written between angle brackets as **a single
event**: `<p1 p2 …>` followed by a duration.

```
N) <c e g>4 .          C major held for two quarter notes
N) <f c'> f            dyad + f on top
```

**Internal syntax.** The pitches inside `<…>` are separated by spaces; each uses
the note syntax (letter + accidental + `'`/`,` for octaves). The octaves
are inferred in a **cascade**: the first pitch from the preceding note *outside* the
stack, each subsequent one from the previous one *inside* the stack (smallest interval,
§2.2). The absolute octave is allowed only on the first pitch (§2.3).

**Duration.** Lives **outside** the angle brackets, after `>` (`<c e g>4`), and applies to
the entire chord. If omitted, the event inherits the duration from the context like a
normal note (`<c e g> .`).

**A single event.** The chord-stack counts as **one** event in the
count-based alignment with the `A)`/`D)`/`L)` lines.

**Tie `^`.** Applies to the entire event; in rendering it ties the corresponding
keys by index (`<c e>4^ <c e>4` → two ties).

**Primary anchoring (normative rule).** The event **following** the stack
infers pitch and octave from the **first** pitch of the stack, **not** from the last.
Internally the stack maintains the cascade; toward the outside only the primary counts.

```
N) <c e g>^ <c e g>     two identical chords (without the rule the 2nd would rise an octave)
N) <f c'> f             the 2nd f stays at the octave of the first f of the triad
N) <f bb, d> f          Bb triad with f on top; following f = first of the stack
```

**Errors and limits.**

- empty `<>` or unclosed `<…` → **E001** (malformed token).
- Stack attached to the following note without a space (`<c e g>e4`) → **E001**;
  remedy: add the space.
- `r` (rest) and `s` (spacer, §14) are **not valid** inside a stack;
  currently they are silently ignored (candidate for a future diagnostic).

> The `>` that **closes** a stack belongs to the token: it is never a barline
> nor an anacrusis (§7), even when followed by a pitch (`<c e g> e4`).
> Likewise the `|` internal to a polychord `[top|bottom]` is the separator of the
> polychord, not a barline (`neumaRk_chords.md §7.2`).

---

## 3. Duration

### 3.1 Explicit duration

The duration may be indicated immediately after the pitch:

```
c4   d8   e16
```

The allowed values are the standard ones of musical notation (units with denominator based on powers of 2):
1 => whole note
2 => half note
4 => quarter note
8 => eighth note
16 => sixteenth note
32 => thirty-second note

---

### 3.2 Tuplets

A duration may be followed by the letter `t` indicating a tuplet value.
If there are no other completing characters, it will be understood as a tuplet with ratio 3:2 (triplet).
If the letter `t` is followed by n:n the tuplet will be based on that ratio (e.g. 5:3, 7:8).
The second part of the ratio may be omitted in the most frequent cases:
t4 is equivalent to t4:3
t5 is equivalent to t5:4
t7 is equivalent to t7:4

#### 3.2.1 Inheritance of the ratio within the group

A note **without a tuplet marker** that follows a tuplet note, while the
group is **still open** (it has not reached a complete cycle of the ratio),
**inherits** the ratio of the current group (`t_num:t_den`). Only the **first** note
of the group must carry the marker; the subsequent ones inherit it until closure.

```
N) c8t d e | …      # d, e inherit the 3:2 triplet opened by c8t
```

#### 3.2.2 Incomplete tuplet at the end of the measure

If at the end of the measure a tuplet remains **open** (the sum of its units
does not reach a complete cycle of the ratio), autofill **completes it with
rests** of the same tuplet unit (the same `base_dur` as the last note of the
group), until the group closes or the measure is full.

- If closure succeeds, **no diagnostic** (this is the typical case of the round-trip
  of a complete triplet whose final rest had been omitted).
- If autofill **cannot** close the group, **W002** is emitted
  («Tuplet not closed before measure end; auto-filled with 1/64 rests»).

---

### 3.3 Implicit duration

If a note **does not specify a duration**, the following rules apply, in order of priority:

1. if it is the only note of the measure, it occupies the entire duration of the measure;
2. the last explicit duration encountered in the musical context is used;
3. if it is at the start of the piece and no prior reference exists,
   the duration is considered unknown (`?`).

The rule of the single note occupying the entire measure
has **higher priority than all other forms of deduction**,
including those based on the persistent musical context.

#### 3.3.1 Reconciliation with the measure duration (normative algorithm)

Once a duration (explicit or inherited) has been assigned to each event, the sum
of the measure may not coincide with the time-signature duration. Reconciliation follows
a deterministic algorithm. Each event is first **classified**:

- **explicit** — duration written in the event. *In an anacrusis* (§7) with more than one
  note, **all** events are treated as explicit (the anacrusis does not fill
  the measure, so it is not redistributed);
- **unknown** — duration `?` (§3.4);
- **implicit** — duration inherited from the context. Only the trailing implicits
  (the sequence of implicits after the last explicit) participate in
  redistribution.

> **Invariant**: explicit durations are **never modified** by
> reconciliation. Only the trailing implicits, the `?`s, are touched, or
> a final rest is added.

**Case A — no `?` (all durations known).** Let `S` be the sum of the measure and
`M` the time-signature duration:

1. `S ≈ M` (within tolerance) → the measure is valid, no action.
2. `S > M` (**excess**):
   - if trailing implicits exist and the recomputed duration
     `(M − S + sum_of_trailing_implicits) / number_of_trailing_implicits` falls on a **representable
     rhythmic value** (power of 2 with 0 to 3 dots) → **silent redistribution**
     over those implicits. Typical idiom: `c2 d e` in 4/4 → `d`/`e`
     inherit the half note (total 1½ whole notes), are compressed to quarter notes;
   - otherwise it is a **real excess** → error **E005** (duration beyond the time signature),
     measure marked invalid, truncation of the final notes until the measure
     fits, plus a possible final filling rest. Covers both the purely explicit excess
     (`4 4 4 4 4` in 4/4) and the non-representable implicit excess.
3. `S < M` (**deficit**):
   - if a tuplet has remained open, it is first completed (§3.2.2);
   - then the residual duration is filled with a **final rest**. This is **standard
     NRK autofill**: **no diagnostic** (the old W001 has been retired).

**Case B — mixed (`?` together with known durations).** The residual duration `M − S` is
distributed **equally** among only the `?` events (see §3.4); no final rest
is added (the `?`s absorb the residual).

---

### 3.4 Unknown duration (`?`)

By indicating `?` as the duration, the value is considered **indeterminate**.

The value missing to complete the measure is distributed equally among all notes with duration `?`.

Example:

```
c? d? e?
```

in a 4/4 measure will identify a triplet of half notes.

---

## 4. Duration prolongations

#### N.B.

The meaning of the dot (`.`) is specific to the context of note lines
and does not coincide with the one used in chord lines.
The dot character takes on different meanings depending on its position **adjacent** to or **spaced** from the note event.

### 4.1 Adjacent dot

A dot immediately adjacent to the value prolongs the duration by **half of the preceding value**, as in standard notation:

```
g4.
```

---

### 4.2 Spaced dot

A dot separated by a space prolongs the duration **by the same value**, and may be repeated:

```
g8 . .
g8 ..
```

will identify a duration of three eighth notes.

Only the space after the note matters, not the one between the dots: both forms are equivalent.

---

### 4.3 Multipliers

An explicit multiplier may be indicated as:

```
g16*5
g16x5
```

will identify a duration equal to 5/16.
Both forms are equivalent.

---

## 5. Repetition (`!`)

The exclamation mark (spaced from the note event) repeats the **same note and the same duration**:

```
g8 !!!
```

Is equivalent to:

```
g8 g8 g8 g8
```

It is possible to combine `.` and `!`.

---

## 6. Tie (`^`)

The symbol `^` indicates a tie.

- if adjacent to a note event, immediately after it, it ties with the following note
- if adjacent to a note event, preceding it, it ties with the preceding note
- if isolated, it is equivalent to a dot (`.`)
- if it is the only sign in the measure, it ties with a note that fills the measure

**Accidentals across the tie.** A note tied to the preceding one follows two
regimes with respect to propagation (§2.5.1):

- **natural continuation** — same spelling (e.g. `eb ^eb`): **no accidental
  symbol** (the graphical tie expresses the continuation), but the note
  still **seeds** the matrix, so that subsequent notes with the same
  letter+octave but a different inflection show the explicit accidental;
- **enharmonic respelling** — different letter/inflection across the tie
  (e.g. `eb ^d#`): the second note is treated as a new note and **shows**
  the accidental, because it is the first time that letter appears in the measure.

---

## 7. Anacrusis

The anacrusis (upbeat measure) is introduced by the sign `>` as a **marker of
the initial barline** of the first measure:

```
N) > c8 d | e4 e e e | …      # upbeat of two eighth notes before measure 1
```

Rules:

- **Where it applies.** `>` is an anacrusis **only** in a note or chord line (C/N). In
  `A)` it is an accent, in `D)` a decrescendo, in `M)`/`L)` text (see
  `neumaRk_datapack.md §3.bis` for the classification filter). The `>` is
  recognized as an anacrusis only if **followed by content** (pitch / `<` /
  barline), so a final accent `>` is not confused.
- **Uncounted measure.** The anacrusis measure does **not** enter the numbering
  of measures.
- **Explicit durations.** In an anacrusis measure with more than one note, all
  events are treated as **explicit**: the anacrusis is partial by definition,
  so it is not redistributed to fill it (§3.3.1). Implicit durations are
  computed only based on the last explicit value received.
- **Completion rest at the start.** If the anacrusis measure is shorter than the
  full measure, the completion rest is added **at the head** (not at the tail),
  so the events align to the strong beat that follows.

### 7.1 Section anacrusis (mid-song)

The anacrusis is not confined to the start of the song: an internal section
(typically a **Refrain** after a Verse) may open *on an upbeat*. In that case
the last measure of the previous section shows its values **up to the upbeat
notes excluded**, and the new section starts with the anacrusis.

The case is expressed with **two distinct markers**, one per side:

| Marker  | Position | Row it sits on | Meaning |
|---------|----------|----------------|---------|
| **`>>>`** | **trailing** the measure | no content after | **open measure**: the measure is not completed with a tail rest, because an upbeat completes it later |
| **`>`**   | **leading** the measure | followed by content | **incoming upbeat**: as §7, but allowed as the initial barline of the **first datapack of a section**, not only the first datapack of the song |

```
[Verse]
a b | c d | a2 r8 >>>          # last measure of the verse, left OPEN

>       || [Refrain]           # Markers: `>` keeps the upbeat column empty
> g a b || c1 ...              # Notes:   `>` opens the upbeat g a b, then downbeat c1
```

Rules:

- **`>` leading vs `>` trailing.** The same sign is disambiguated by
  **position**, exactly as §7 distinguishes the anacrusis from the accent: `>`
  **followed by content** (pitch / `<` / `|`) is the *incoming* upbeat; `>>>`
  **followed by nothing** is the *open* (outgoing) measure. The trailing sigil
  is **fixed-form** (`>>>`): the number of `>` carries no meaning.

- **`>>>` explicit, mandatory.** The open measure requires the `>>>` marker:
  without it, a short measure receives the normal tail completion rest (standard
  autofill). NRK does **not** infer the openness from the following datapack —
  every datapack stays **self-describing**, and the marker survives reordering /
  moving of sections.

- **`>>>` is structural (propagates to the system).** The open measure `>>>` is
  on a par with a **measure sign / barline**: it is a property of the **system**,
  not of an individual voice. It is therefore **sufficient on one stave** of the
  datapack to **propagate to all the others**, exactly like shared barlines (§4.1
  of `neumaRk_datapack.md`). It must not be replicated voice by voice.

- **`>` incoming is per-row.** The incoming upbeat `>` is instead **per-row**
  (as §6.4 of `neumaRk_voices.md`): each voice carries its own. On rows
  **without notes** (Markers, Chords) the `>` **reserves the upbeat column,
  leaving it empty**, so the section label (`[Refrain]`) and the downbeat barline
  align to the **first real measure** and not above the anacrusis. The grammar
  already allows it because `|` counts as valid content after `>`
  (`>  || [Refrain]`).

- **Numbering.** The section upbeat is **not** counted (as §7). The open measure
  preceding it **is** counted normally: it is a real measure of the previous
  section, only shorter.

- **No double rest.** Unlike the initial anacrusis (§7), the section upbeat does
  **not** receive the head completion rest: it is the open measure preceding it
  that supplies the lead-in. The pair *(open measure + upbeat)* is temporally
  contiguous in playback. Symmetrically, the open measure does **not** receive
  the tail completion rest.

- **No metric validation.** *(Open measure + upbeat)* are taken as written, even
  if they do not sum to a full measure: no warning. It remains the author's
  responsibility.

- **Without an open measure.** If the previous section ends on a **full** measure
  (no `>>>`) but the new one opens with `>`, the `>` behaves as a standalone §7
  anacrusis (partial upbeat with head completion rest). `>>>` is what links the
  two sides; in its absence there is no link.

- **Section barlines.** NRK does not impose the typographic convention of a
  "double barline *before* the upbeat": barlines (including `||`) are placed
  where the author writes them. The form `… || c1` with the double barline **on
  the downbeat** is legitimate.

> **Composition with lyrics.** The *pickup* group `<…>` of the `LYRICS)` block
> (`neumaRk_lyrics.md §8.4.1`) is the textual counterpart of this upbeat: the
> pickup syllables attach to the notes of the section upbeat defined here.

---

## 8. Annotations

After a note it is possible to add, adjacent to it,
a textual annotation in two container forms, **semantically
equivalent**, which differ only by the presence of the graphical box:

- **`"<text>"`** — primary form, without box;
- **`[<text>]`** — variant form, with box.

```
c4"text"          annotation without box
c4[text]          annotation with box
c4"$F1"           fingering (reserved prefix, see §8.1)
```

The annotation allows the **text markup** defined in
`neumaRk_text_markup.md`. The default style is **plain, reduced size**,
in both forms.

### 8.1 Reserved prefixes

If the first character after the container opening is `$` followed by
a reserved uppercase letter, markup is **disabled**
on the entire annotation: the content is interpreted as a **structural
directive**.

| Prefix   | Meaning          |
|----------|------------------|
| `$F`     | fingering        |
| `$S`     | string number    |

Other prefixes may be defined in future extensions.

### 8.2 Disambiguation with grace notes

In a note-row the delimiter `[…]` is shared with the grace block
(see `neumaRk_grace_notes.md`). The disambiguation is **positional**
relative to the adjacent pitch:

| Pattern                                       | Interpretation          |
|-----------------------------------------------|-------------------------|
| `[…]MAIN` (no space after `]`)                | grace block             |
| `PITCH[…]` with whitespace or EOT after `]`   | annotation with box     |
| `PITCH[…]MAIN` (no space before or after)     | grace block (priority)  |
| orphan `[…]` (no adjacent pitch)              | W004 grace without main |

Examples:

```
c4[text] d4         annotation with box on c4 (space after `]`)
c4 [d8/^]e4         grace block anchored to e4
c4[d8/^]e4          grace block anchored to e4 (grace priority)
c4 [text] d4        orphan brackets → W004 (grace ignored)
```

To avoid ambiguity in edge cases, it is recommended to use the primary
form `c4"text"` for annotations: the delimiter `"…"` does not
collide with the grace block.

---

## 9. Clef change

The default clef is the treble clef.
A clef change can be defined with the notations:

- `(@G)` for the treble clef
- `(@C1)` for the soprano clef
- `(@C2)` for the mezzo-soprano clef
- `(@C3)` for the alto clef
- `(@C4)` for the tenor clef
- `(@F3)` or `(@C5)` for the baritone clef
- `(@F)` or `(@F4)` for the bass clef
- `(@G8va)` for the treble clef at the upper octave
- `(@G8vb)` for the treble clef at the lower octave
- `(@F8)` or `(@F8vb)` for the bass clef at the lower octave

The clef change is maintained in the piece until a new definition.

> **Disambiguation with the key.** In a measure decorator `(…)` (see
> `neumaRk_datapack.md §7.1`) both a clef change (`(@F)`)
> and a key change (`(F)`, `(Dm)`) may appear. The prefix **`@`** identifies the
> clef: the clef directive is recognized **before** the key, so
> `(@F)` is not read as the key of F.

In a multi-staff datapack (see `neumaRk_datapack.md` §4), the clef
declared as the first token of an `N)` line applies to the corresponding
staff. In the absence of a directive, each staff inherits the last
clef defined in its own context.

## 10. Non-standard notations

### Slash notation

On the staff, in place of the notes, **slashes** (oblique bars) are drawn in number equal to the beats of the measure. There are two ways to generate it:

**1. Implicit (default).** In a measure with **active harmony**, if the note line is empty (without even rests), the measure is rendered with slash notation. Active harmony means: an explicit chord, a `%`, **or** a chord persisting from a previous measure (empty chord cell, see `neumaRk_chords.md §1.1`). A measure marked `NC` (`neumaRk_chords.md §1.2`) is **not** active harmony: with an empty note line it gets a **rest**, not slashes.

**2. Explicit, with the construct `/`.** The symbol `/` in the `N)` line is a language event that generates slash notation. It can be used by itself to fill the entire measure, or mixed with notes: its duration is implicit (autofill) and occupies **all the space not covered by the other notes** of the measure.

Examples (in 4/4):

```
N) a b c d  |   /        |  a b c d
```
Three measures: the first and third with notes, the central one entirely in slash notation.

```
N)   a4  /
```
A quarter note + slashes on the remaining three beats.

```
N)   /   a8  b
```
Slashes on the first three beats + two final eighth notes.

**Rules.**

- At most **one `/` per measure** (more than one produces error E006).
- The slash does not accept a duration: its duration is always the residual one of the measure.
- When the slash region starts or ends in the middle of a beat (e.g. `| a8 / |`), an internal rest is added to close the partial beat, and the drawn slashes cover the remaining whole beats (in `| a8 / |` in 4/4: 1 eighth note + 1 eighth rest + 3 quarter-note slashes).
- If after alignment to the beats no space remains for at least one slash, the `/` is downgraded to a rest (error E007).
- A line composed **only of `/`** (plus barlines/dots/spaces) does not require the `N)` prefix: it is automatically recognized as a note line. E.g. `| / | / | / | / |` is already a valid note line.

---

---

# Note-event extensions (sealed 2026-05-24)

> Sections §11-§13 are **normative and implemented** end-to-end (Phases 3.2-3.3).
> Status/details: `neumaRk_changelog.md §0.6`. Impact on classification
> **low**: `N)` is the *default sink* of the cascade (`neumaRk_datapack.md §3.bis`),
> so a line with `(x)`, `(u-)…`, `{…}` or `R4` falls into Notes without touching the
> other predicates (`{` `}` `R` are in no charset; uppercase `R` is free,
> pitches are lowercase).

## 11. Noteheads and note glissando (the parentheses rule `(…)`)

In `N)` the parentheses are overloaded. The meaning of `(…)` attached to a
note is determined by **content** (and prefix/suffix position):

| Parenthesis content | Meaning | Position |
|---------------------------|-------------|-----------|
| `@…` (e.g. `@G`) | clef change (§9) | prefix/inline |
| digits / list (e.g. `4`, `16,8,8`) | explicit rhythm (§3, also `r(…)`) | suffix |
| notehead-token `x` `d` `t` `s` `/`, or **empty** | notehead / parenthesized note (§11.2) | suffix |
| direction+dash `u-` `d-` `u--` `d--` | **note glissando** (§11.3) | prefix = *in*, suffix = *out* |

**Operational discriminator: first character + presence of the trailing dash.** Key
case: `(d)` = diamond (notehead); `(d-)` = glissando down (the dash marks the
glissando). Without the dash the two collide.

A note may combine **distinct** parenthesis groups (one per concept):
`(u-)a2(x)` = short glissando-in up + `a2` + cross notehead; `a2(x)(d-)` = `a2` cross
notehead + glissando-out down.

### 11.1 The three "slash" things not to confuse

- **standalone `/`**: rhythmic slash-region (1 slash = 1 beat, beat-aligned),
  see §10.
- **`(/)`**: slash notehead on a note, **at the real pitch** of the note (§11.2).
- **`{…}`**: rhythmic notation, slash **centered** without pitch (§12).

### 11.2 Noteheads

> **Implemented** end-to-end (Phase 3.2). Status/details: `neumaRk_changelog.md §0.6`.

Suffix `(…)` on a note, **closed set**:

| Form | Notehead |
|------|-------|
| `(x)` | cross |
| `(d)` | diamond |
| `(t)` | triangle (single orientation; up/down variants deferred) |
| `(s)` | square |
| `(/)` | slash (rhythm notehead **at the pitch height**) |
| `()` *(empty)* | **parenthesized** note (editorial / ghost) |

```
N) a2(x) b2(/) c2() d2(d)
```

- **Chord-stack**: `<c e g>(x)` applies the notehead to **all** the pitches of the stack.
- A single notehead per note.

> **Positional overload**: inside `()` the letter `t` is a triangle; outside, `t` is the
> **tuplet** marker (`8t`, §3.2); in `A)` it is the turn. Disambiguate by position
> inside/outside parentheses (rule §11). Likewise `d` (outside `()` it is not a notehead).
> For `s`: inside `()` it is the **square** notehead; outside, as a standalone token-pitch, it is the
> **spacer** (§14).

### 11.3 Single-note glissando (scoop / fall / doit / plop)

> **Implemented** end-to-end (Phase 3.2b). Status/details: `neumaRk_changelog.md §0.6`.
> Co-locatable with the noteheads (`a(x)(d-)`).

Ornamental glissando **into or out of** a note (different from the glissando *between
two notes*, which lives in `A)` as `gl` — `neumaRk_articulations.md §9`).

- direction: `u` (up) / `d` (down); length: `-` short, `--` long;
- in/out from **position**: prefix = in, suffix = out;
- the **dash marks the glissando** (distinguishes it from the notehead, §11).

| Spelling | Meaning | Jazz name |
|-----------|-------------|-----------|
| `(u-)a` | gliss IN up, short | scoop |
| `(d-)a` / `(d--)a` | gliss IN down | plop / drop |
| `a(u-)` | gliss OUT up, short | doit / lift |
| `a(d-)` / `a(d--)` | gliss OUT down | fall (short / long) |

```
N) (u-)a2 a8 a(d--) | (d-)a a(u-)
```

## 12. Rhythmic notation `{…}`

> **Implemented** end-to-end (Phase 3.2c). Status/details: `neumaRk_changelog.md §0.6`.

A group `{…}` is rendered as **rhythmic notation**: slash noteheads **centered** on the
staff, without pitch. `{` and `}` are **new** delimiters in NRK.

```
N) a4 r | b4 {8 8 16 16 8 4}
```

- Content: **only durations** (no pitch); **rests allowed** (`{8 8 r8}` → rest
  glyphs) and **spacers allowed** (`{8 8 s8}` → rhythmic position skipped, no
  notehead, §14). The pitch is always centered.
- Default notehead = slash. **Override** with the notehead suffix of §11.2:
  `{8 8 16}(x)` = cross noteheads.
- Only the notes **inside** the braces are rendered as rhythm notation; the rest of the
  measure is normal.
- **Tuplets allowed** inside `{…}` (e.g. `{8t 8t 8t}`); invalid tuplet marker →
  warning **W007**.

## 13. Multi-measure rest (MMR) `RN`

> **Implemented** end-to-end (Phase 3.3): parse, empty-span validation (**W008**),
> ×N playback, dedicated MMR glyph and +N renumbering. Status/details:
> `neumaRk_changelog.md §0.6`.

`RN` (e.g. `R4`) renders a **multi-measure rest** of **N measures**: a single cell
worth N measures, with the measure count advancing by N. Rendering: standard MMR glyph
(thick bar) with the **number N** above. `R` is uppercase (free in `N)`, where
pitches are lowercase). Requires **N ≥ 2** (`R1` = single-measure rest,
redundant → normal rest). *(Form `Rx4` discarded: `RN` is used, consistent with
`%N`.)*

### 13.1 When it is used (empty-span condition)

The barlines are **shared by the system**: a staff is not collapsed while another is
shown. Therefore an MMR is rendered **only if the entire span is empty at the system
level** — all voices/staves at rest **and chords empty**. It is useful
in exactly two cases: (a) a single staff/voice with an empty span; (b) multiple
staves/voices all `RN` aligned on the same span (including the piano grand staff at rest).

```
C) A |    | B          # empty chords on the central span
N) a | R4 | b          # → 4-measure MMR; measure count +4
```

If there is **any content** on the span (chords, notes of another voice, markers),
`RN` is not the right tool: **warning** and degradation to N per-measure rests (one writes
normal rests directly).

> Corollary: since `RN` lives only in uniformly empty spans, there **never exists**
> another part with content to align in that span → no "expand-to-align"
> machinery.

### 13.2 `RN` ≠ collapse in extraction

These must be kept separate:

- **`RN`** = "I want an MMR **here**, in **this** view" (explicit notation, empty
  span).
- **Collapse in extraction** = **automatic**: when extracting a single part from a
  multi-part score, the empty measures of that part collapse into MMR **without
  special notation** (one writes normal rests). It is a **future** feature (arrives with
  part extraction); `RN` on an empty span, by contrast, is implementable right away. The
  choice "in the part the chords are omitted" is an **extraction setting**,
  not an MMR marker.

### 13.3 Boundary rules (rendering)

- **Whole measures only**: if the part enters mid-measure, the whole measures go
  into MMR and the half-beat at the edges remains a normal rest.
- **The span breaks** at: system change (line break), double barline,
  repeat `:|`/`|:`, key/time-signature/tempo change, rehearsal mark. E.g. `R8`
  with a key change in the middle → two MMRs.

---

## 14. Spacer — invisible rest (`s`)

> **Implemented** end-to-end (2026-05-27): parser, classification, serializer,
> render (GhostNote) and playback. See `neumaRk_changelog.md §0.6`. Impact on
> classification **low**: as for `r`, a line of only `s` falls into the
> default sink `N)` (`neumaRk_datapack.md §3.bis`, TB1 extended to `s`).

The **spacer** is an event that **occupies duration** exactly like a rest
(`r`), but **renders no glyph**: it advances the metric time without drawing
anything on the staff. It is borrowed from the eponymous construct in LilyPond. It serves to reserve
metric space without a graphical sign: aligning a second voice or
syllables (`L)`) by column, leaving driven "gaps" in a measure, positioning a single
annotation at a point in time without a visible rest.

### 14.1 Syntax

`s` is a **special token-pitch** (like `r`): it replaces the pitch and accepts
the entire duration grammar of a rest.

| Form | Meaning |
|-------|-------------|
| `s` | spacer of **implicit** duration (inherits from the context, §3.3) |
| `s4` `s8` `s16` | explicit duration (§3.1) |
| `s4.` `s2..` | adjacent dot (§4.1) |
| `s8 . .` | spaced dot (§4.2) |
| `s4t` `s8t5` | inside a tuplet (§3.2) |
| `s16*5` `s16x5` | multiplier (§4.3) |
| `s !!!` | repetition (§5) |

```
N) c4 s4 e4 s4        # two real events alternated with two quarter-note spacers
N) s2 g2              # first "empty" beat (invisible), then g as a half note
```

### 14.2 Semantics

The spacer is **indistinguishable from `r`** for: duration, measure count,
autofill (§3.3.1) and playback (silence — inaudible event). The **only**
difference is the graphical rendering.

| | `r` (rest) | `s` (spacer) |
|---|---|---|
| Rendering | rest glyph | **no glyph** |
| Duration / time signature | counts | counts (identical) |
| Playback | silence | silence (identical) |
| Line classification | Notes | Notes |

**Measure entirely of spacers.** The measure appears optically empty but the time
advances normally. The filling measure-rest (whole rest) does **not** apply,
nor the slash notation reserved for empty harmonic measures (§10): the spacer
is an explicit choice of "no sign".

### 14.3 Restrictions

The spacer has no pitch nor graphical presence, so it does **not accept** the modifiers
that presuppose a note or a visual anchor. In all the following cases the
modifier is **ignored** with warning **W009**:

| Spelling | Outcome |
|-----------|-------|
| `^s` / `s^` | no tie: the spacer does not tie (§6). To prolong, use the real note or `r` |
| `s"…"` / `s[…]` | no annotation (§8): the visual anchor is missing |
| `s(x)` `(u-)s` | no notehead/glissando (§11): reserved for real notes |

In addition, by symmetry with `r`:

- **Chord-stack `<…>`**: `s` inside it is **not valid**, silently ignored
  (§2.6).
- **Grace block**: `s` **not allowed** as a grace event → **E013** (like `r`,
  `neumaRk_grace_notes.md`).

### 14.4 No multi-measure form

There is no multi-measure spacer (`SN` is **not** defined): the uppercase `S` is
the *Style* header marker (`neumaRk_header.md`), and an MMR (§13) is by
definition a **visible** rest. To skip N measures invisibly one repeats
`s` measure by measure.

---

## 15. Deduction rules (summary)

- omitted pitch or duration are deduced from the context
- deduction must never produce semantic ambiguity
- in case of conflict, the explicit syntax always prevails

---

This document defines the **atomic level** of musical notation in neumaRk.


---

# Chords

This document defines the syntax and semantics of **chords** in neumaRk, including:

- dictionary of admitted chord symbols
- normalization of variants
- bass handling
- chord rhythm (implicit, explicit, mixed)
- optional chords
- polychords

Chords are contained in `C)` lines and can be used to determine both the harmony and its rhythmic aspect.

---

## 1. Chord event

A **chord event** is a harmonic unit that may have:

- a chord symbol
- an optional bass, or a bass only
- a duration (implicit or explicit)
- duration modifiers

A chord event may also represent:

- a rest (`r`)
- a re-attack (`!`)
- a **polychord** (two symbols stacked vertically, see §6)

Every chord event in neumaRk is an autonomous rhythmic entity, with an
implicit or explicit duration.

A chord may include an **explicit bass** in the form of a _slash chord_
(e.g. `A/B`), or consist exclusively of a bass (e.g. `/B`).

In both cases, the event is subject to the same rhythmic rules as the
other chords.

### 1.1 Harmony persistence (empty cell)

An **empty chord measure** — with no symbols, no `%` and no `NC` token
(§1.2) — does **not** represent a harmonic void: the **harmony of the
previous measure persists**. The prevailing harmonic content is
**re-realized on the downbeat** of the empty measure (re-attack, with the
same logic as `%`), not sustained like a tie.

Persistence:

- propagates across multiple consecutive empty measures;
- crosses datapack boundaries, consistently with the **persistent musical
  context** (`neumaRk_specification.md`);
- is **interrupted** by an `NC` event (§1.2) and resumes only from the next
  explicit chord.

```
C) C |   |   F
```

Measures 1 and 2 sound `C`; measure 3 sounds `F`. **No glyph is drawn**
above the persisting measures: the chord line stays clean.

> **Note-line rendering.** If the `N)` line of a persisting measure is
> empty, the measure is rendered with **slash notation** (there is active
> harmony to comp): see `neumaRk_notes_and_durations.md §10 → Slash
> notation`.

#### 1.1.1 Partial continuation (leading `.`)

When a measure **begins** with a dot `.` (before any chord symbol), the dot
is a **continuation of the persisting harmony**: it re-strikes the active
harmony (§1.1) **for its own slot only**, leaving the rest of the measure to
the chords that follow. It is the slot-level extension of empty-cell
persistence. (Distinct from a `.` that **follows** a chord in the same
measure, which prolongs that chord's duration: see §4.)

```
C) A7 DM |   | . GM
```

In measure 3 the first beat continues `DM` — the active harmony, inherited
from measure 1 through the empty cell of measure 2 — and the second beat
sounds `GM`. In playback this equals `A7 DM | DM | DM GM`.

Multiple leading dots (`. .`) extend the continuation over several slots. If
no harmony is active (start of the piece, or after `NC`), a leading `.` stays
silent. On the chord line the continuation dot **draws no glyph**.

### 1.2 No chord (`NC`)

The **`NC`** token (two uppercase letters, no dots) declares the **absence
of harmony**: it interrupts persistence (§1.1) and indicates that **no chord
sounds** in that measure.

- it occupies the **entire measure** and is the **sole content** of its
  cell; it cannot be mixed with symbols or durations (`C NC` → error
  **E128**);
- in playback it is **silent** (no chord realized);
- it is **rendered** on the chord line with the dedicated `N.C.` glyph
  (reserved codepoint `U+EFB2` of the BravuraLS/PetalumaLS fonts);
- if the corresponding `N)` line is empty, the measure does **not** get
  slash notation but a **rest** (there is no harmony to comp).

```
C) C |  NC |  F
```

Measure 1 sounds `C`; measure 2 is silent (with `N.C.` drawn); measure 3
sounds `F`. After an `NC`, an empty cell **stays silent** until a new
explicit chord appears.

---

## 2. Chord symbol

### 2.1 General structure

The general form of a symbol is:

```
<root><quality>[<extensions>][/<bass>]
```

Where:

- `root` ∈ `{A B C D E F G}` with optional accidentals `#` or `b` (at most one accidental)
- `suffix` identifies the chord suffix
- `bass` optional, indicates a bass different from the root

Examples:

```
C   Dm  GM  F#7alt   BbM13   C7/E
```

---

## 3. Chord dictionary

### 3.1 Triads

| Admitted input | Normalization |
| -------------- | ------------- |
| C              | C             |
| Cm, C-         | C-            |
| Co, Cdim       | C°            |
| C+, C5+, Caug  | Caug          |
| Csus2          | Csus2         |
| Csus4          | Csus4         |

---

### 3.2 Major chords (4 or more notes)

| Admitted input         | Normalization |
| ---------------------- | ------------- |
| C6                     | C6            |
| C69                    | C69           |
| CM, CM7, CMaj7, Cmaj7, C7M | CΔ        |
| CM9, Cmaj9             | CΔ9           |
| CM13, Cmaj13           | CΔ13          |
| CM#11, CM7#11, Cmaj#11 | CΔ#11         |
| CM9#11                 | CΔ9#11        |
| CM13#11                | CΔ13#11       |
| CM+, CM#5, CM7#5, C+M7 | CΔ#5          |

---

### 3.3 Minor chords

| Admitted input       | Normalization |
| -------------------- | ------------- |
| C-b6, Cmb6           | C-b6          |
| C-6, Cm6, C-69, Cm69 | C-6           |
| C-7, Cm7             | C-7           |
| C-9, Cm9             | C-9           |
| C-11, Cm11           | C-11          |
| C-13, Cm13           | C-13          |
| C-M, CmM, C-M7, CmM7 | C-M           |

---

### 3.4 Dominant chords

| Admitted input             | Normalization |
| -------------------------- | ------------- |
| C7                         | C7            |
| C9                         | C9            |
| C13                        | C13           |
| C7#11, C9#11, C13#11, C7b5 | C7#11         |
| C7b9                       | C7b9          |
| C7alt                      | C7alt         |
| C7#5, C+7                  | C7#5          |
| C7#9                       | C7#9          |
| C13b9                      | C13b9         |
| C7sus, C9sus, C13sus       | C7sus         |
| C7susb9                    | C7susb9       |

---

### 3.5 Diminished and half-diminished chords

| Admitted input    | Normalization |
| ----------------- | ------------- |
| Co7, Cdim7        | C°7           |
| CoM7, CdimM7, CoM | C°M           |
| Cm7b5, Ch         | Cø            |

### 3.6 Suffixes outside the dictionary

The dictionary (§3.1–§3.5) is the set of **recognized** suffixes. The major-seventh
spellings `maj`/`Maj` (`Cmaj7`, `Cmaj9`, `Cmaj#11`, …) and the redundant `M7`/`7M`
are **canonicalized to the `M`-form** (§3.2) — they are recognized, not warnings.
A suffix genuinely outside the dictionary (e.g. `dom7`) **does not
make the document invalid**: the symbol is **preserved** (root + optional bass) but the
suffix has no significant rendering, and the parser emits the non-blocking warning
**W103** (*unrecognized chord suffix*). This is a **best-effort degradation**, not an
error: the parsing flow continues.

---

## 4. Chord rhythm

#### N.B.

The meaning of the dot (`.`) is specific to the context of chord lines
and does not coincide with the one used in notes lines.
The dot character takes on different meanings depending on whether it is positioned **spaced** from the chord event or inserted in the context of a **duration**.

### 4.1 Implicit mode

In the absence of explicit durations, the chord rhythm is **deduced**.

Principle:

- the chord events in a measure are counted
- the measure duration is subdivided equally
- the dot (`.`) prolongs the chord **by its own duration**

Examples in 4/4:

```
| C Dm |
| C . . Dm |
| r C . Dm . D#o . Em |
```

In implicit mode the rhythm is **not displayed**, but it serves for alignment.

---

### 4.2 Explicit mode

The duration of a chord may be indicated in parentheses:

```
C(4)   Dm(8.)   G7(8t)
```

The duration may contain:

- note value (mandatory)
- dots (`.`), standard mode, add half of the value
- `t` for triplet (tuplet 3:2)
- multipliers (`*n`)

Special symbols:

- `r` → rest
- `!` → re-attack (repeats the duration, not the symbol)

For the last chord of the measure, `^` creates a tie to the next measure.

With this notation mode, the chord rhythm **is notated above the staff**.

---

### 4.3 Mixed mode

It is possible to combine implicit and explicit mode in the same measure.

- only the explicit durations are displayed
- the others are deduced

```
C   Dm(8^)
```

**The rest `r` follows the same rules as a chord**, both for rhythm
deduction and for display:

- `r` (without parentheses) is **implicit**: it contributes to the deduction like
  any other event (the measure duration, minus the explicit durations,
  is subdivided equally among the implicit events, also taking into account
  the dots `.`) and **is not drawn** in the rhythm-row;
- `r(...)` (with parentheses) is **explicit** and **is drawn** as
  a visible rest above the staff.

Example — eighth-note anticipation on an otherwise empty measure:

```
r EbM(8^) | EbM
```

renders only the anticipating eighth note tied to the `EbM` of the next measure,
without visible rests filling the first measure. It is equivalent, in
placement and rhythm, to what is already obtained with an implicit
chord in place of `r` (`Gm EbM(8^)`), with the difference that here there
is no symbol at the beginning of the measure.

> *Current limitation.* When an implicit event (chord or `r`) falls
> **inside a tuplet** the visual suppression is not active and the rest
> is drawn again. This is not a semantic choice: it is a constraint
> of the renderer that may be removed in the future without changes to the
> syntax.

---

### 4.4 Compact duration list

When the same chord extends over multiple rhythmic figures, instead of
repeating `!` for each continuation one can use a **comma-separated list
of durations** inside the parentheses:

```
D/Eb(16,8,8,16,16,r16,16,16)
```

is the compact form, **equivalent** to:

```
D/Eb(16) !(8) !(8) !(16) !(16) r(16) !(16) !(16)
```

Rules:

- each segment admits `value`, `value.` (dotted), `value..`,
  `value...`, `valuet` (triplet);
- a segment may begin with `r` to insert an **internal rest**
  (e.g. `r16`): the chord interrupts for that duration and then resumes
  with the next segment;
- the **first segment cannot be `r`** (the list must open with
  the chord): `D(r16,8)` is an error;
- `*n` (multiplier) and `^` (tie) **are not admitted inside**
  the segments, only in the single-rhythm form `(value*n)` or on the
  final segment of the group (see below);
- spaces around the commas are tolerated: `D(16, 8, 8)` is valid.

**Tie `^` on a compact list.** The trailing `^` ties the **last
segment** of the group to the next event, like a normal value tie
on the last note of the measure:

```
D/Eb(16,8,8,16,16,r16,16,16)^   A
                              ↑
                              last `16` tied to `A`
```

**Visual rendering.** The symbol `D/Eb` appears only once above the
staff (anchored to the first segment). The rhythm of the whole group is
drawn above the staff: the first figure has the name
of the chord, the following ones are silent continuations (no symbol
repeated), any internal `r` are visible rests.

**Round-trip.** When saving and reloading, the compact form is
**preserved**: the `.nrk` file becomes identical to what was written.

---

## 5. Optional chords

An open parenthesis starts a group of **optional chords**:

```
(C Dm G7)
```

The group may extend over **multiple measures**, including internal
barlines:

```
(FM F#-7 | B7 EM)
```

The parentheses are **rendered visually** around the
group. The chords inside them maintain normal rhythmic
semantics and alignment with the other lines of the datapack.

An optional group may carry a **comment-label** (§7) attached
to the closing parenthesis, without intermediate whitespace:

```
(FM F#-7 | B7 EM)[Bill Evans changes]
```

---

## 6. Polychords

A **polychord** is a chord event made of **two stacked symbols**, read simultaneously: an _upper_ symbol and a _lower_ symbol, separated visually by a horizontal line.

The polychord is a harmonic event distinct from the _slash chord_ (§1):

- _slash chord_ (`A/B`) → a single chord `A` with bass `B`
- polychord (`[A|B]`) → two independent chords `A` and `B` played together

### 6.1 Syntax

A polychord is enclosed in square brackets, with the `|` character as the internal separator:

```
[<top>|<bottom>]
```

Where:

- `top` and `bottom` are **valid chord symbols** according to §2 (root, quality, extensions, optional bass)
- the square brackets `[ ]` are **mandatory**
- the separator `|` is **mandatory** and appears **exactly once**
- internal whitespace is not admitted

Valid examples:

```
[D|EbM]            polychord: D major over EbM7
[CM7|F#-7]         polychord with extended symbols
[D/F#|EbM]         top with explicit bass (slash chord) over a simple chord
[Am|G](8.)         polychord with explicit duration
```

Invalid examples:

```
[D|EbM|F]          three levels not admitted
[|EbM]             upper symbol missing
[D|]               lower symbol missing
[D | EbM]          internal whitespace not admitted
```

### 6.2 Visual rendering

The polychord is displayed as two vertically stacked symbols, separated by a horizontal line:

```
 D
───
EbM
```

The horizontal width reserved for the polychord equals the greater of the two symbols.

### 6.3 Duration and rhythm

The polychord is a **single chord event** for rhythmic purposes. All the rules of §4 apply to the polychord as to any other event:

- implicit duration: the polychord counts as **a single event** in the subdivision of the measure
- explicit duration: the parentheses follow the square brackets, e.g. `[D|EbM](4)`
- re-attack (`!`) and repetition (`.`) operate on the whole polychord

```
| [D|EbM] . . [F|G7] |     polychord repeated three times, then change
| [D|EbM](2) [F|G7](2) |   two polychords, explicit duration
```

### 6.4 Transposition

In transposition, **both symbols** of the polychord are transposed independently according to the rules of the single chord.

### 6.5 Limits

- number of levels: **exactly 2** in neumaRk 0.6; extensions to N levels are outside the specification
- nesting: a polychord cannot itself contain another polychord
- optional group: a polychord **may** appear inside an optional chord group `( … )` (§5)

---

## 7. Comment-label

A **comment-label** is a free string in square brackets,
attached as a postfix to a chord event to annotate it with arbitrary
text.

### 7.1 Syntax

A comment-label is expressed in two container forms, **semantically
equivalent**, that differ only in the presence of the graphic box:

- **`"<text>"`** — primary form, without box;
- **`[<text>]`** — variant form, with box.

The text is a string of printable characters (spaces included) and
admits the **text markup** defined in `neumaRk_text_markup.md`.
The closing character of the container (`"` or `]`) cannot appear
literally in the text: use the escape `\"` or `\]`.

The default style of the comment-label is **italic, reduced size**, in
both forms. The graphic box is applied only in the `[…]`
variant.

Three admitted scopes, distinguished by **attachment point**:

- **chord-level** — attached to a chord event (also polychord),
  without intermediate whitespace:

  ```
  Eb7alt"tritone"            no box (primary)
  Eb7alt[tritone]            with box (variant)
  [A|EbM]"polychord exp."
  ```

- **group-level** — attached to the closing parenthesis `)` of a
  group of optional chords (§5):

  ```
  (FM F#-7 | B7 EM)"Bill Evans changes"
  (FM F#-7 | B7 EM)[Bill Evans changes]
  ```

- **row-level** — as the **first useful token** of the chord-row,
  preceded only by the line marker `C)` / `C+`. Two semantically
  equivalent forms:

  - **without barlines** — label as the only content of the line (the
    chord-row contains no musical events):

    ```
    C+ "solos changes"
    C+ [solos changes]
    ```

  - **with barlines** — label as the first token inside the bars of the
    line, before any chord-event:

    ```
    C+ | "solos changes" | Cm7 | F7 |
    C+ | [solos changes] | Cm7 | F7 |
    ```

    It is equivalent to the form without barlines for the label segment, and
    allows coexistence with later events of the same row.

### 7.2 Disambiguation

The delimiter `[…]` is shared with other constructs already defined
in the spec. The disambiguation is **positional**:

| Construct | Recognized form |
|-----------|--------------------|
| Polychord (§6) | `[<top>\|<bottom>]` — contains internal `\|`, no whitespace |
| Volta (`flow §3.2`) | attached to the barline at the start of the measure: `\|[1.]` |
| End-decorator (`flow §4.3`) | attached to `:\|` or to a closing barline: `[xN]:\|`, `[D.S.]` |
| Comment-label (with box) | attached to a chord / `)` of an optional group, or first token of the row, in the form `[…]` |

The parser recognizes the polychord first (constraining the form to internal
`|`), the others are distinguished by attachment position.

The `"…"` form of the comment-label does not collide with any of these
constructs, because the delimiter `"` is not shared. The
disambiguation of the comment-label `"…"` remains positional (attached to a
chord, `)` of an optional group, or first token of the row).

### 7.3 Visual rendering

- **chord-level** — reduced italic above the chord (above the eventual
  rhythmic notation); graphic box only in the `[…]` variant.
- **group-level** — reduced italic above the group, left-aligned;
  graphic box only in the `[…]` variant. The optional parentheses
  remain unchanged in both forms.
- **row-level** — reduced italic at the start of the line, aligned with the first
  musical event; graphic box only in the `[…]` variant.

The default style (italic, reduced size) is a property of the **construct**
and applies in both forms. The container (`"…"` vs `[…]`) decides
only the presence of the box (see `neumaRk_text_markup.md`).

### 7.4 Limits

- at most **one** comment-label per event (error `E126` if
  duplicated on the same event), regardless of the container form
  used (`[…]` or `"…"`)
- the label is purely annotative: it does not affect pitch, duration,
  rhythm, musical flow or transposition
- admitted both on the base line `C)` and on the alternate lines `C+`
- the containers `[…]` and `"…"` are **single-line**: the closing
  delimiter must appear by end of line

---

## 8. General duration rules

- in case of conflict the explicit syntax prevails
- normalization does not alter the semantics
- the implicit rhythm is deterministic

---

This document defines the **harmonic and rhythmic semantics** of chord lines in neumaRk.


---

# Second voice per staff

This document defines the syntax and semantics of the **second musical voice** on the same staff in neumaRk: marker, structural position, context rules, graphic rendering, and diagnostics.

The second voice is an **independent musical stream** that shares the same staff as the principal voice but evolves with its own rhythm and its own persistent musical context.

---

## 1. Definition

In neumaRk a **staff** can contain up to **two** independent voices:

- **voice 1** (or *principal voice*), introduced by the `N)` line (or `N+`,
  see `neumaRk_datapack.md` §4.5);
- **voice 2** (or *secondary voice*), introduced by the `N2` line,
  optional.

The two voices:

- share the staff, the clef, the key, the time signature, the measure barlines,
  and the chord line `C)`;
- maintain **independent rhythmic and melodic streams**;
- have **separate persistent musical contexts** (`last_pitch`,
  `durCtx`).

A staff can have **at most one voice 2**. Voice 2 exists only if explicitly declared: in its absence the staff is monodic.

> **Staff ≠ voice.** The concept of *staff* (`N)` / `N+`) describes the
> stave; the concept of *voice* (1st or 2nd) describes the musical
> stream within that stave. A piece with 4 staves may have
> up to 8 total voices (4 staves × 2 voices), with no further
> aggregate limits.

---

## 2. Marker syntax

### 2.1 Form

The voice 2 marker is the sequence of **two characters**:

```
N2
```

followed by a space, analogously to `N)` and `N+`. The digit `2` replaces the `)`, preserving the 2-character width invariant required for the vertical alignment of the barlines across the datapack lines.

### 2.2 Relation to the general marking rules

The general rule (`neumaRk_datapack.md` §2.1) provides for markers formed by one, two, or three uppercase letters followed by `)`. The markers `N+` and `N2` are **morphological variants of `N)`** explicitly provided for by the specification and do not represent an arbitrary exception: the identifying letter `N` remains unchanged, and the second character distinguishes the role (`)` continuation, `+` new staff, `2` second voice).

---

## 3. Structural position and binding

### 3.1 Voice group

Each voice is described by a **voice group** of the form:

```
[A)] N) [D)] [L)]      ← voice 1 group
[A)] N2 [D)] [L)]      ← voice 2 group (optional)
```

The `A)`, `D)`, `L)` lines bind by **position**:

- `A)` (articulations) precedes its `N)` / `N2`;
- `D)` (dynamics) and `L)` (lyrics) follow their `N)` / `N2`, in
  that order.

Both voices can declare their own articulations, dynamics, and lyrics independently.

### 3.2 Binding to the parent staff

An `N2` line binds to the **immediately preceding staff** in the same datapack, identified by the most recent `N)` or `N+` line. Between the parent `N)` / `N+` and the `N2`, only the following are allowed:

- the eventual `D)` / `L)` of the voice 1 group;
- the eventual `A)` of the voice 2 group.

Any other interposed line interrupts the binding and makes the `N2` not recognized as voice 2 of the preceding staff (error **E123**).

### 3.3 Uniqueness per staff

Within the same datapack, each staff can have **at most one** `N2` line. The presence of multiple consecutive `N2` lines binding to the same staff produces error **E124**.

### 3.4 N2 as the first note line

An `N2` not preceded by an `N)` or `N+` in the same datapack has no valid parent and is invalid (**E123**).

---

## 4. Musical context of voice 2

### 4.1 Independent stream

The persistent musical context defined in `neumaRk_specification.md` §2.1 is **per-stream**: each *(staff, voice)* pair maintains its own `last_pitch`, its own `durCtx`, and the propagation state of the measure accidentals.

Context updates made by the events of voice 1 do **not** modify the context of voice 2, and vice versa.

### 4.2 Initialization at first appearance

When voice 2 of a staff appears for the **first time** in a datapack — that is, when in the preceding datapack the same staff did not contain a voice 2 — its initial reference (`last_pitch` and `durCtx`) is inherited from **voice 1 of the same staff**, in its state *at the beginning of the current datapack*.

Equivalently: voice 2 enters as if it were, at that precise musical instant, a continuation of voice 1 — and from that instant onward it maintains its own separate stream.

```
DP1:
N) a4

DP2:
N) c           ← inherits a4 → c5 (minimum interval)
N2 a           ← first appearance: inherits a4 (voice 1 at the start of DP2)
               → a4. From here voice 2 continues with its own stream.
```

### 4.3 Subsequent appearances

When voice 2 was already present in the preceding datapack, it inherits normally from its own stream:

```
DP3:
N) c           ← inherits from voice 1 of DP2
N2 a           ← inherits from voice 2 of DP2
```

### 4.4 Suspended voices

If voice 2 of a staff is present in one datapack, **absent** in the next, and reappears in a still later datapack, upon reappearance rule §4.2 applies again: the context of voice 2 is reinitialized from voice 1 of the same staff at the beginning of the datapack of reappearance.

The historical context of voice 2 prior to the suspension is not recovered.

### 4.5 Voices in a staff introduced with `N+`

If voice 2 appears in a staff introduced in that datapack via `N+`, voice 1 of the staff is itself "fresh" (orientation reference based on the clef, see `neumaRk_notes_and_durations.md` §2.2). Voice 2 consequently inherits the same clef-dependent reference at the beginning of its own stream.

---

## 5. Graphic rendering

### 5.1 Stem direction

The simultaneous presence of voice 1 and voice 2 on the same staff fixes the stem direction in a **normative** way:

- voice 1 → stems always **up**;
- voice 2 → stems always **down**.

This rule applies independently of the pitch of the notes and overrides any automatic rendering heuristic in effect when the staff is monodic.

### 5.2 Rests

The rests of the two voices are independent. When the natural vertical position of a rest collides with that of the other voice, the renderer applies a clarity offset according to the standard conventions of musical notation; this does not alter the semantics.

---

## 6. Alignment and validity

### 6.1 Number of measures

Voice 2 must contain **the same number of measures** as the parent staff. It is the same rule that applies between staves of a multi-stave system (`neumaRk_datapack.md` §4.3).

### 6.2 Chord line

The `C)` line is system-wide and is shared by all the voices of all the staves of the datapack. There is no per-voice `C)`.

### 6.3 Clef

The clef is a property of the staff, not of the voice. An inline clef directive as the first token of an `N2` line (e.g. `N2 (@F) …`) is not allowed and produces error **E125**.

### 6.4 Anacrusis

The anacrusis sign `>` is per-line and may appear independently in `N)` and in `N2`.

### 6.5 Measure repeat

The `%` token (and the variants `%!`, `%2`, `%!2`, `%4`, `%!4`, see `neumaRk_flow_and_repeats.md` §7) applies **per-line**: its presence in `N2` repeats voice 2 of the source measure, without involving voice 1. The eventual copies of `A)`, `D)`, `L)` follow the same layer rules already defined for single lines.

### 6.6 Grace notes

Grace notes (`[ … ]`, see `neumaRk_grace_notes.md`) are allowed within `N2` with the same rules as voice 1. Their local context of pitch and accidentals lives in the stream of voice 2.

---

## 7. Diagnostics

### 7.1 Error codes

| Code | Description                                                    |
| ------ | -------------------------------------------------------------- |
| E123   | `N2` without a valid parent staff (`N)` or `N+`) in the datapack |
| E124   | More than one `N2` bound to the same staff in the same datapack |
| E125   | Inline clef directive on an `N2` line                          |

### 7.2 Misaligned measures

A misalignment of the number of measures between `N2` and the parent staff falls under the same validity rules as multi-stave (`neumaRk_datapack.md` §4.3).

---

## 8. Examples

### 8.1 Minimal voice 2

```
C) A7
N) a1
N2 e4 d e2
```

Single staff in treble clef. Voice 1: one whole note `a` for the measure. Voice 2: two quarter notes and one half note.

### 8.2 Both voices with independent A/D/L

```
C) A7
A) .
N) a1
D) f
L) ah
A) ! !
N2 e4 d e2
D) p
L) la la la
```

The `A) .` line binds to `N) a1`; the `A) ! !` line binds to `N2`. The dynamics and lyrics of each voice are independent.

### 8.3 Multi-stave with voice 2 on the upper staff

```
C) G7
N) | <d b>2 <e c>4 |
N2 | g8 a b a g a b a |
N) (@F) | g,4. d'8 e d |
```

Two-staff system. The upper staff (treble) contains two voices; the lower staff (bass) is monodic.

### 8.4 Multi-stave with voice 2 on the lower staff

```
C) G7
N) | <d b>2 <e c>4 |
N+ (@F) | g,4. d'8 e d |
N2 | r4 c8 d e d c b, |
```

Two-staff system introduced in this datapack. The `N2` binds to the staff introduced by `N+` (bass), which therefore remains two-voiced, while the upper staff (treble) is monodic.

### 8.5 Voice 2 at first appearance

```
N) a4

N) c
N2 a

N) c
N2 a
```

- DP1: voice 1 ends with `a4`.
- DP2: voice 1 `c` inherits `a4` → `c5`; voice 2 `a` is at its first
  appearance, inherits `a4` from voice 1 at the start of the datapack → `a4`.
- DP3: voice 1 `c` inherits from voice 1 of DP2 → `c5`; voice 2 `a` inherits
  from its own stream (voice 2 of DP2) → `a4`.

### 8.6 Suspended and reappearing voice

```
N) c4
N2 a

N) e

N) c
N2 a
```

- DP1: voice 1 `c4`, voice 2 `a4` (first appearance, inherits from voice 1
  → `a4`, minimum interval).
- DP2: only voice 1 → voice 2 is suspended.
- DP3: voice 2 reappears → rule §4.2 applies again; voice 2
  inherits from voice 1 of DP3 at the start of the datapack, not from its own
  historical stream.


---

# Grace notes (appoggiaturas and acciaccaturas)

This document defines the syntax and semantics of **grace notes** in neumaRk: appoggiaturas and acciaccaturas, with their graphic modifiers and rules of interaction with the musical context.

Grace notes are **ornamental musical events**: they are performed close to a real note (the *main*) but do not contribute to the rhythmic computation of the measure.

---

## 1. Definition

A **grace note** is an ornamental note enclosed in square brackets `[ … ]` and anchored, in the adjacent left position, to a **real note** called the *main*.

A grace note:

- **does not occupy time**: its duration is graphic, not rhythmic, and does not
  contribute to filling the measure;
- **must have an explicit duration** inside the square brackets;
- **does not update the persistent musical context**: neither the pitch nor the
  duration of a grace note is stored as a reference for the deduction of
  subsequent events (see `neumaRk_specification.md` §2.1).

---

## 2. Syntax

A grace block consists of an **opening square bracket**, a sequence of **grace events** separated by spaces, and a **closing square bracket**, immediately followed — with no spaces — by the main note.

```
[ <grace> [<grace> …] ] <main>
```

### 2.1 Grace event

A grace event is formed by:

1. **Pitch** — mandatory, with the same syntax as ordinary notes
   (see `neumaRk_notes_and_durations.md` §2). The **chord-stack** form `<…>`
   is also allowed. **Octave inference** takes as its reference the pitch of the
   **main** to which the block is anchored (the real note that follows `]`),
   not the musical context preceding the block — see §7.1.
2. **Duration** — mandatory **on the first grace event of the block**; on
   subsequent events it is optional and, if omitted, **inherits** the value
   previously made explicit within the block (see §3).
3. **Modifiers** `/` and/or `^` — optional, allowed **only on the last grace
   event of the block** (see §4).

Examples of valid grace events:

```
f#8        g16        <c e g>8       a16/^       g           f#/^
```

In the last two examples the duration is omitted: it is inherited from the explicit value of the previous grace in the block. The first event of a block without a duration produces **E009**.

The following are not allowed within a grace event:

- rests;
- annotations `"…"`;
- accidental-forcing modifiers `!`;
- tuplets (`t`);
- spaced prolongations (separate `.`, spaced `^`, repetition `!`).

### 2.2 Adjacency with the main

The closing square bracket `]` must be **immediately adjacent** to the main note, with no intervening spaces.

```
[f#8/^]c4        ✓
[f#8/^] c4       ✗  (space between grace block and main)
```

In the absence of adjacency, the grace block is not recognized as such and produces **W003** (see §8).

---

## 3. Allowed durations and inheritance

The duration values allowed for a grace note are exclusively:

```
4    8    16
```

**The following are not allowed**:

- adjacent prolongations (`.`);
- multipliers (`*` or `x`);
- tuplets (`t`);
- indeterminate duration (`?`).

A grace note with a non-conforming duration produces **E009**.

### 3.1 Block-local inheritance

The duration of the **first** grace event of the block is mandatory. Subsequent grace events, if they omit the duration figure, inherit the value last made explicit within the same block.

```
[f#8 g a]c4         ≡  [f#8 g8 a8]c4
[f#16 g8 a]c4       ≡  [f#16 g8 a8]c4       (a inherits 8, not 16)
[f# g8]c4           → E009 (first event without duration)
```

Inheritance is **strictly local to the block**: it does not interact with the persistent musical context (see §7) nor does it cross the `]`. Two consecutive grace blocks do not share the value: each must have its own explicit duration on the first event.

The inherited value is preserved by the serializer in compact form (no figure) for lossless round-trip of the source.

---

## 4. Graphic modifiers

Within the square brackets, two modifiers are allowed, placed at the end of the **last grace event of the block**, in any order:

- `/` — **slashed**: the grace is rendered graphically with an oblique slash
  on the flag (acciaccatura);
- `^` — **slurred**: the grace is connected to the main by a graphic slur.
  It reuses the `^` symbol of the tie (see
  `neumaRk_notes_and_durations.md` §6), in a grace context.

The two modifiers are combinable: `/^` or `^/` indicate a grace **slashed and slurred** to the main, the typical form of the classical acciaccatura.

### 4.1 Modifier position constraint

The modifiers `/` and `^` are allowed **only on the last grace event of the block**. Their presence on a non-final grace event produces **E010**.

```
[f#8 g8 a16/^]c        ✓
[f#8/]c                ✓
[f#8/ g8]c             ✗  (modifier on non-final grace → E010)
[f#8/ g8/^]c           ✗  (idem)
```

---

## 5. Block cardinality

A grace block **must contain at least one grace event** and **at most four**.

- Empty block `[]` → **E011**.
- Block with more than four grace events → **E012**.

```
[f#8]c                       ✓  (1 grace)
[f#8 g8 a16 b16/^]c          ✓  (4 grace, last one with modifiers)
[f#8 g8 a16 b16 c16/^]c      ✗  (5 grace → E012)
```

---

## 6. Anchoring to the main note

The grace block **must be followed**, in adjacent position, by a **real note** (pitch or chord-stack), which constitutes its main.

The main note:

- is an ordinary note in every respect, subject to the normal pitch and duration
  deduction rules (see `neumaRk_notes_and_durations.md`);
- is the rhythmically relevant event to which the grace is graphically and
  musically subordinate.

### 6.1 Grace block without a main

A grace block not followed by a valid main note (e.g. last event of the measure or of the datapack, or followed by a rest, barline, structural marker) is **ignored** by the parser and produces **W004**.

```
| c4 d4 e4 [f#8/^] |       → grace ignored, W004
| c4 d4 e4 [f#8/^] r |     → grace ignored, W004 (main cannot be a rest)
```

---

## 7. Effect on the musical context

A grace note **does not alter the persistent musical context**:

- the **pitch** of a grace is not stored as the last explicit pitch for the
  purpose of deducing subsequent pitches;
- the **duration** of a grace is not stored as the last explicit duration for
  the purpose of deducing subsequent durations.

Example (in 4/4):

```
c4 [f#8/^]c [f#8/^]c8 c4.
```

- `c4` — explicit main, context: pitch=c, duration=4.
- `[f#8/^]c` — grace `f#8` ignored for context purposes; main `c`
  inherits duration `4` (the last explicit duration remaining in the context).
- `[f#8/^]c8` — main `c8` updates the context to duration=8.
- `c4.` — main updates duration=4 (dotted).

The context at the end of the sequence is consistent as if the grace notes had never been written.

### 7.1 Octave inference of grace notes

The pitch of a grace **deduces its octave** relative to the pitch of the **main** to which the block is anchored (the real note that follows `]`), not relative to the musical context preceding the block. Grace notes are ornamentations of the main, and the nearest octave is the one that makes them adjacent to their visual target.

Example (treble, 4/4):

```
N) a [f8/^]g'
```

- `a` — main, pitch **a4**.
- `g'` — main of the grace, pitch **g5** (the minimum interval from `a4`
  would lead to `g4`; the `'` modifier adds +1 octave).
- `[f8/^]` — grace `f` with reference `g5`: the `f` nearest to `g5`
  is **f5** (a tone below), not `f4` (which would be a ninth away). Result:
  grace **f5** → main **g5**, a descending major second interval.

Within the grace block, the octaves of the individual grace events are computed in a **chain**: the **first** grace event has its octave inferred from the main; the **subsequent** ones have their octave inferred from the preceding grace event in the same block (standard monodic intra-block inference). The line context chain, by contrast, **does not cross** the block: the event immediately after the main inherits the context of the main, not of the grace notes (see §7).

---

## 8. Rendering of accidentals

For the graphic rendering of accidentals, a grace note **does not update** the measure's propagation state, but it **does influence it**. Three rules.

### 8.1 Accidental on the grace

The accidental is **drawn on the grace** if and only if the pitch of the grace deviates from the **current matrix** of the measure (i.e. from the key signature as updated by the accidentals already occurring in the measure before the grace block).

In other words, the criterion is the same as the one applied to mains: the grace shows an accidental when it sounds "unexpected" relative to the current visual state.

Examples (key signature: G major, F# in the signature; 4/4):

| Context on the left | Grace input | Graphic rendering of the grace             |
|---------------------|-------------|--------------------------------------------|
| (new measure)       | `[f#8/^]c`  | no accidental (F# matches the signature)   |
| `f4` (F♮)           | `[f#8/^]g`  | `#` (matrix=’f’→♮, the grace deviates)     |
| (new measure)       | `[f8/^]c`   | `♮` (F♮ deviates from F# in the signature) |
| (new measure)       | `[g8/^]c`   | no accidental (G♮ matches the signature)   |
| `g#4`               | `[g#8/^]c`  | no accidental (matrix=’g’→# after `g#4`)   |

### 8.2 Breaking propagation after the grace

A grace that **deviates from the current matrix** (i.e. a grace that has caused an accidental to be drawn per §8.1) **breaks** the accidental propagation for the subsequent mains of the measure having the same pitch-letter and octave.

Concretely, after a grace of this type, every subsequent main with the same (letter, octave) must display an explicit accidental on screen (`#`, `b`, or `♮`), even if the current matrix matches the pitch.

Example (key signature: G major; measure in 4/4):

```
f4 [f#8/^]g4 f4
```

Graphic rendering:

| Event        | matrix[‘f’][4] before | Accidental on screen                       |
|--------------|-----------------------|--------------------------------------------|
| `f4` (F♮)    | 1 (F# from key sig)   | `♮` (deviates from the matrix). matrix → 0 |
| `[f#8/^]g4`  | 0 (after `f4`)        | `#` on the grace (deviates, §8.1). matrix → 0 |
| `f4` (F♮)    | 0                     | `♮` (cautionary, propagation broken)       |

Note: the grace **does not update** the matrix. The final main `f4` still reads `matrix[‘f’][4] = 0` (the state left by the first `f4`); without §8.2 it would show no accidental. The cautionary `♮` is imposed by the "broken propagation" registered by the grace.

### 8.3 Internal independence within the block

Within a grace block, each grace event is isolated from the others for rendering purposes: since no grace updates the matrix (§8.1 / implicit rule), all the grace notes of the block see the same starting matrix, evaluated independently of one another.

> **Note.** The rules in §8 concern exclusively the **graphic rendering**.
> neumaRk input always uses absolute pitches: `f` denotes F♮, `f#` denotes
> F#, independently of context and key signature.

---

## 9. Summary examples

Classical acciaccatura (slashed, slurred):

```
N) c4 [f#8/^]c [f#8/^]c8 c4.
```

Simple appoggiatura (not slashed, not slurred):

```
N) c4 [f#8]c4
```

Slurred, non-slashed appoggiatura:

```
N) c4 [f#8^]c4
```

Cluster of grace notes (slur on the last one):

```
N) c4 [d8 e8 f8/^]g4
```

Grace with a chord:

```
N) c4 [<c e g>8/^]c4
```

---

## 10. Errors and warnings

| Code | Type    | Condition                                                                                                |
|--------|---------|------------------------------------------------------------------------------------------------------------|
| E009   | error   | Grace duration missing on the first event of the block, or non-conforming duration (only `4`, `8`, `16` allowed) |
| E010   | error   | Modifier `/` or `^` on a non-final grace event of the block                  |
| E011   | error   | Empty grace block `[]`                                                        |
| E012   | error   | Grace block with more than four grace events                                  |
| E013   | error   | Rests not allowed as a grace event (e.g. `[r8]c`)                             |
| W003   | warning | Grace block not adjacent to a main note (space between `]` and main)         |
| W004   | warning | Grace block without a main note to its right; the block is ignored            |

Further general error conditions (invalid pitch, malformed duration, unbalanced square brackets, etc.) fall under the diagnostics already defined for ordinary notes.

---

## 11. Known limitations

In this version of the specification, grace notes:

- do not allow articulations, dynamics, or annotations;
- do not allow rests as grace events;
- are not valid in chord lines (`C)`), nor in chord-rhythm lines: the `[ … ]`
  construct is reserved for `N)` lines.

Extensions to these constraints will be the subject of subsequent versions.


---

# Articulations (`A)` line)

> **STATUS: SPEC.** §1-§7 sealed 2026-05-23 (current `A)` deduction, already in
> the parser); §8-§12 sealed 2026-05-24 (extensions: token model, glissando `gl`,
> slur/wave spans). **Implemented** end-to-end (parser Phase 3.1 + rendering
> 3.1b); status/details in `neumaRk_changelog.md §0.6`. Known limitation: the
> vertical wave↔slur collision is a layout follow-up. Binding and order are not
> redefined here: see `neumaRk_datapack.md §2.1` and §3. Sealing decisions in §7
> (base) and §12 (extensions).

## 1. Definition

The `A)` (Articulations) line carries the **articulations and ornaments** to
apply, position by position, to the events of the music line it is bound to. It
is a parallel layer: it does not alter rhythm, durations or flow, only the
notational attributes of the events.

## 2. Structural position and binding

Marker, optionality and logical order are defined in `neumaRk_datapack.md`
§2.1 (marker table) and §3 (implicit order: `A)` is **optional and precedes**
the `N)` line of its own note group). In operational summary:

- `A)` **binds to the line below** ("model §4.A.5"): its tokens are held
  *pending* and drained onto the first subsequent music target in the same
  group/staff.
- Drain target, in priority order:
  1. the **chord-rhythm** of the `C)` line immediately below — **only for
     stave 0** (the chord-rhythm lives in `MeasureShared`), if the `C)` has
     rhythm;
  2. otherwise the `N)` line of the **same stave**.
- In multi-stave each staff has its own pending bucket; **voice 2** (`N2`)
  has an independent `A)` bucket (see `neumaRk_voices.md §3.1`).

## 3. Vocabulary

Each token is a symbol (or combination) that maps to an articulation or
ornament. Tokens are separated by spaces; multiple articulations on the **same**
note are written as a single token without spaces (e.g. `>!`).

| Token | Meaning                | Type          |
| ----- | ---------------------- | ------------- |
| `-`   | tenuto                 | articulation  |
| `>`   | accent                 | articulation  |
| `!`   | staccato               | articulation  |
| `^`   | marcato                | articulation  |
| `+`   | pizzicato (left hand)  | articulation  |
| `o`   | fermata (above)        | articulation  |
| `os`  | short fermata          | articulation  |
| `ol`  | long fermata           | articulation  |
| `-!`  | portato (tenuto+staccato) | combination |
| `>!`  | staccato accent        | combination   |
| `tr`  | trill                  | ornament      |
| `m`   | mordent                | ornament      |
| `M`   | inverted mordent       | ornament      |
| `t`   | turn                   | ornament      |
| `T`   | inverted turn          | ornament      |
| `,`   | breath mark            | ornament      |
| `h`   | harmonic               | articulation *(extension §8+)* |
| `v`   | up bow                 | articulation *(extension §8+)* |
| `n`   | down bow               | articulation *(extension §8+)* |
| `.`   | **placeholder**: no articulation on that position | — |

> `h` for the harmonic (the symbol `°` is not ASCII and `o` is already
> fermata); `v`/`n` for the bows (`n` recalls the ⊓). Added to these are a
> **per-pair** token (glissando `gl`, §9) and two **spans** (slur `( )`, wave
> `~`, §10), introduced by the decomposable token model in §8.

The vocabulary is the **closed set** of the table above (plus the placeholder
`.`, the per-pair/spans of the §8+ extensions). Only these tokens are valid
articulations; the **parser classification charset derives from this set**
(see §6 and §11). A token outside the vocabulary is not a valid articulation.

The markers `>` and `^` make a line **uniquely** articulations during
classification (`articulations_specific_marker`): no other music line uses
them in isolation.

## 4. Count-based alignment

The correspondence with the events of the target line is **strictly positional
by count** (as in `neumaRk_dynamics.md §4.1`), left-to-right:

```
N) | a8 b  c  d |
A) | >  .  !  ^ |
     ↑      ↑  ↑
   accent staccato marcato (b: none)
```

- The token `.` or an empty token = **no** articulation on that note.
- If there are **fewer** tokens than notes, the remaining notes stay without
  articulation (no-op).
- If there are **more** tokens than events, the extras are **silently
  dropped** (auto-fix philosophy; note: unlike `D)` no warning is emitted —
  see Open decisions).
- The alignment **counts rests too** (unlike `L)`, which skips them):
  a position above a rest is an event in every respect. This is what allows
  a span (§10) to **cover a rest** (you write `~` over it and the span
  continues).

## 5. Examples

```
A) | >    !  |
N) | c4 d e f |     accent on c, staccato on e

A) | >!         |
C) | C7  F7     |     staccato accent on the first chord-rhythm event (stave 0)
```

## 6. The vocabulary is part of deduction (single source)

The parser is **not agnostic** with respect to this vocabulary: to deduce that
a prefix-less line is `A)` it must recognize its tokens. Historically the
vocabulary was **split and duplicated** — half syntactic in the parser (charset
of `articulations_line` / `articulations_specific_marker`, used for
classification) and half semantic in the renderer (`nrkArticToModifiers`,
NRK-token → VexFlow code) — and the two halves diverged (the charset admitted
`_` and unmapped isolated letters).

**Normative model (decided 2026-05-23): this document is the single source.**
The spec defines `NRK-token → musical meaning` (e.g. `!`→staccato); the
*meaning* is normative, the VexFlow codes are not (another renderer would use
others). From this table **derive**: the parser's classification charset and
tokenization; the renderer's `meaning → glyph` map.

## 7. Decisions (closed 2026-05-23)

1. **Single source** ✓ — the spec is normative; parser-charset and
   renderer-map derive from it. Eliminates the drift.
2. **Vocabulary = closed set** ✓ — symbols outside the table (e.g. `_`,
   isolated letters) are **not** valid articulations; the charset must be
   restricted to the vocabulary.
3. **Token excess** ✓ — `A)` emits **W131** like `D)` (was a silent drop).
4. **Normative meaning, VexFlow implementational** ✓ — the "meaning" column
   is binding; the codes `a-`/`a>`/… are an implementation note.

> **Code-side follow-up** (D(L)→D(P), tracked in
> `docs/feature-deduction-spec-audit.md`), all ✅ done (Phase 3.1):
> classification charset derived from the closed vocabulary; **W131** on
> token excess; **W139** (lexical validation) on any token with an
> out-of-vocabulary sequence, including the isolated letter-fragment (`s`
> of `os`, `r` of `tr`).

---

# `A)` Extensions (sealed 2026-05-24)

> Sections §8-§12 are **normative and implemented** (parser Phase 3.1 + render
> 3.1b). They extend the per-position vocabulary of §3 with: a decomposable
> token model (§8), a per-pair token (glissando `gl`, §9) and two spans (§10).

## 8. Token model: decomposition and co-locations

The base vocabulary (§3) uses, in the current parser, a `switch` over whole
tokens (`nrkArticToModifiers`, with `case ">!"`). The extensions require a true
**per-position decomposer**, analogous to `parseDynamicsToken` of `D)`.

Each **position** (space-separated token) is an **order-free concatenation**
of **elements**, decomposed with **greedy longest-match** over the multi-char
atoms (first `os`/`ol` before `o`, first `tr` before `t`):

```
element :=
  | wave            ~[1-4]? ("…")?      # §10.2 (digit/label only at opening)
  | slur-open       (                    # §10.1
  | slur-close      )                    # §10.1
  | bracket-open    [ ("…")?             # §10.3 (label only at opening)
  | bracket-close   ]                    # §10.3
  | octave-open     8u | 8d              # §10.4 (up / down)
  | octave-close    8.                   # §10.4 (8 + dot)
  | glissando       gl                   # §9 (towards the next note)
  | fermata         o | os | ol          # greedy: os/ol before o
  | trill           tr                   # greedy: tr before t
  | turn            t | T
  | mordent         m | M
  | per-note 1ch    - > ! ^ + , h v n
  | placeholder     .                    # no element on that position
```

Consequence: **`-!` and `>!` are no longer special tokens** but **co-locations**
(`-`+`!` = portato; `>`+`!` = staccato accent). All combinations emerge from
concatenation: `(!` = slur-open + staccato; `>gl` = accent + glissando. The
"combination" entry of the §3 table remains valid as a *meaning*, not as an
atomic token.

> The **decomposition** (tokenize) is separate from the **span resolution**
> (post-pass), just as `D)` separates `parseDynamicsToken` from
> `extract_hairpins` (§10).

## 9. Note-to-note glissando (`gl`)

`gl` on the position of a note = that note **glides towards the next**. The
direction (up/down) is implicit from the two pitches. It is **per-pair**, not
a span.

```
A) .  gl .  .
N) r4 a  b  r       # a glides towards b
```

Distinct from the **single-note glissando** (scoop/fall, entry/exit from *one*
note), which lives in `N)` as a modifier between parentheses — see
`neumaRk_notes_and_durations.md` (N extensions).

## 10. Spans

Two spans, borrowed from the `D)` model (open/close resolved in a post-pass).

### 10.1 Slur `( )` (delimited span)

LilyPond style: `(` opens on the note of its position, `)` closes on the note
of its position; the curve covers from opening to closing.

```
A) . ( . . )
N) c d e f g      # slur from d to g
```

- **Cross-barline**: yes.
- **Confined to the staff**: a slur left open at the end of the staff
  **closes there with a warning**; an orphan `)` → **warning**, ignored.
- **No overlap/nesting (v1)**: at most one slur open at a time; a second `(`
  while one is open → **warning**. (Nesting deferred.)
- **Open+close on the same note** (`()`): degenerate → ignored/warning.
- **Co-locatable** with the per-note ones: `(!` = slur-open + staccato.

### 10.2 Wave `~[1-4]` (span by repetition)

A wavy line **always above** the staff. It unifies **vibrato / shake /
long-vibrato / laid-back**: the **amplitude** is the visual width, the
**label** gives its name.

**Amplitude** — optional digit `1`–`4` (default `~` = level 1):

- `~N` (with digit) **opens a new span** of amplitude N, **closing** the
  current one;
- `~` (bare) **extends** the current span; if none is open, opens one of
  level 1.

```
A) ~3 ~ ~ ~1 ~ ~      # large wave over 3 notes, then small wave over 3
```

**Extension and rests**: consecutive `~` (even **cross-barline**) = a single
wave; a position **without `~`** (including an empty measure) closes the span.
**Rests do not interrupt** (the alignment counts rests, §4).

```
A) ~2 ~ ~ ~ |   | ~3 ~ ~ ~
N) a4 b r c | d | a4 b r c
#  └─ amplitude-2 over a b r(rest) c ─┘  (meas.2 empty → no wave)  └─ amplitude-3 ─┘
```

**Label** (optional, only on the **opening** token): `"…"` immediately after
the wave, rendered above its start. The label is a **text markup container**
(`neumaRk_text_markup.md` §2.2): it accepts the `#`/`##`/`###`, `*`/`**`,
`__` markers; the **default is upright** (italic/bold/underline/size only via
the markers). Amplitude and label are independent.

```
A) ~3"shake" ~ ~ ~
A) ~"vibrato" ~ ~
A) ~4"laid back" ~ ~ ~ ~
```

The label gives the **semantics** (vibrato vs shake vs laid-back); the glyph
`~` alone is only "wave of amplitude N". For a transcription tool the page is
the truth; an eventual playback will infer from label/amplitude.

### 10.3 Analysis bracket `[ ]` (delimited span)

A **grouping bracket** above the staff, like the analytical brackets of formal
analysis. `[` opens on the note of its position, `]` closes on the note of its
position (LilyPond style, exactly like the slur §10.1).

```
A) . . ["DO triad" . . ] |
N) a a c        e | g e c a
```

- **Label** (optional): a string `"…"` **immediately after** `[` (reuses the
  same opaque token as the wave). Rendered **left-aligned** above the opening
  and is a **text markup container** (`neumaRk_text_markup.md` §2.2: `#`/`*`/`__`),
  **upright by default**. A bracket **without** label (`[ … ]`) is allowed.
- **Rendering**: square bracket **always above** the staff, with the two ends
  turned **downward** (toward the notes).
- **Cross-barline / cross-system**: yes.
- **No overlap/nesting (v1)**: at most one bracket open at a time; a second `[`
  while one is open → **warning** (`W144.bracket_open_overlap`); an orphan `]` →
  **warning** (`W144.bracket_close_unmatched`); a degenerate `[]` (open+close on
  the same note) → **warning** (`W144.bracket_degenerate`); a bracket left open
  at the end of the row → **implicit close + warning** (`W144.bracket_unclosed_eol`).
- **Purely graphic**: no effect on playback (it is an analytical annotation).
- **Syntax note**: in `A)` rows `[ … | … ]` is a bracket spanning a barline, so
  the inner `|` is a **real barline** — NOT a polychord `[X|Y]` (§chords) nor a
  volta `[1.`. The map suppresses polychord detection on Articulations rows.

### 10.4 Octave `8u` / `8d` … `8` (delimited span)

An **ottava** line. `8u` opens an **8va alta** (octave up), `8d` opens an
**8vb bassa** (octave down); `8.` **closes** the span (inclusive on the last
covered note). **Delimited** like the slur (§10.1) — deliberately NOT the
extension model of the wave (§10.2): the ottava line is sparse, so repeating a
token on every note would be cumbersome. A bare `8` (without `u`/`d`/`.`) is
**out of vocabulary** (likely a typo for `8.`) → `W139`.

```
A) . . . . . . . 8u . . . | . . . 8. |
N) c d e f g a b c  d e f | a g f e d c b a g
#                  └─ 8va from the 8th note, across the barline, to the close ─┘
```

- **Rendering**: the standard SMuFL ottava sign — **`8va`** (alta, glyph
  `U+E511`) / **`8ba`** (bassa, glyph `U+E513`) — followed by a **dashed**
  horizontal line and an **end hook** toward the staff; **above** for `8u`,
  **below** for `8d`. (Both glyphs are in the BravuraLS/PetalumaLS subset.)
- **Playback**: the covered notes are **transposed ±12 semitones** (`8u` = +12,
  `8d` = −12). The **written pitch is unchanged** — the noteheads stay where
  they are; only the playback shifts.
- **Cross-barline / cross-system**: yes.
- **No overlap/nesting (v1)**: a second open while one is open → **warning**
  (`W144.octave_open_overlap`); an orphan `8.` close → **warning**
  (`W144.octave_close_unmatched`); a degenerate `8u8.` → **warning**
  (`W144.octave_degenerate`); open at end of row → **implicit close + warning**
  (`W144.octave_unclosed_eol`).

> **Span convention** (decided for `A)`, to be reused by the `D)` hairpins/
> `cresc.`): every long span is **delimited** — a (possibly parametrized)
> opening token + a closing token; intermediate positions are placeholders `.`.
> Slur `( )`, bracket `[ ]` and octave `8u…8` follow it. The **wave `~`** keeps
> the **extension** model as the single documented exception, because its glyph
> is a *continuous* wavy line drawn over every covered note.

## 11. Impact on deduction (extended charset)

The extensions broaden the line classification surface
(`neumaRk_datapack.md §3.bis`):

- **Charset `A)`**: includes the new symbols `( ) ~ h v n g` and the digits
  `1-4`, plus `[ ] 8 u d` (§10.3 bracket, §10.4 octave), in addition to the
  base vocabulary §6 (from which the charset is derived — single source).
- **`~` is a specific marker**: a line that contains `~` is classified
  **uniquely** as `A)`, despite the digits that would otherwise bring it
  closer to chords/notes.
- **`[` `]` `8` `d` are NOT specific markers**: they are heavily overloaded
  (`[` = section `[NAME]`, alternate-chord label, grace/annotation in `N)`;
  `8`/`d` = duration/note). They only widen the `A)` charset; the notes-line
  priority (TB4) protects `N)` rows, and an implicit bracket/octave row needs
  the explicit `A)` prefix to be classified as articulations.
- **`g`/`gl` vs note G — TB4**: `g` (head of the `gl` glissando token, §9) is
  also the note G, and with the durations `1`–`4` it makes lines like `g`,
  `g4`, `g g g` ambiguous. The **TB4** rule
  (`neumaRk_datapack.md §3.bis.5`) gives priority to notes: a line that is a
  **valid notes-line** (every token matches the `parse_notes` grammar + at
  least one real pitch) is `N)`, not `A)`. The token `gl` is not a valid note,
  so an articulations line with `gl` stays `A)`.
- **Quote-aware**: the content of a label `"…"` (e.g. `shake`) is excluded
  from the classification match — out-of-charset letters or a `~` *inside the
  text* neither break nor falsely mark the line.

## 12. Decisions (extensions, closed 2026-05-24)

1. **Note-to-note glissando (`gl`, §9) ≠ single-note glissando** (scoop/fall,
   in `N)`). ✓
2. **Extended vocabulary = closed set**; normative meaning, implementational
   VexFlow codes (inherits §6/§7). ✓
3. **Unified token model** (decomposer + co-locations, §8). ✓
4. **Slur `( )`** delimited, no overlap v1 (§10.1). ✓
5. **Up bow `v`, down bow `n`; harmonic `h`** (§3). ✓
6. **Wave `~`**: levels 1–4; digit = new span, bare = extends; always above;
   covers rests; label `"…"` at opening, italic (§10.2). ✓
7. **Shake / long-vibrato / laid-back unified** in the wave `~N` + label. ✓
8. **Analysis bracket `[ ]`** delimited, label `"…"` optional, always above,
   purely graphic; no overlap v1 (§10.3). ✓ *(added 2026-05-31)*
9. **Octave `8u`/`8d` … `8.`** delimited (`8.` closes), dashed line above/
   below, **transposes playback ±12**; no overlap v1 (§10.4). ✓ *(2026-05-31)*
10. **Span convention**: long spans are delimited (open + close); the wave is
    the single exception (extension), its glyph being a continuous line. ✓


---

# Dynamics and text annotations

This document defines the syntax and semantics of the **dynamics line**
`D)` in neumaRk: element vocabulary, alignment to musical events, syntax
of text annotations, extension rules and diagnostics.

The `D)` line is the **annotation band below the staff**: it hosts the
traditional dynamic markings (`p`, `mf`, `ff`, hairpins, cresc./dim.)
and — consistently with jazz/lead-sheet practice — also **text
annotations** anchored to musical events (e.g. "drums fill", "freely",
"w synth") or to measure barlines (e.g. "Vamp till cue").

---

## 1. Definition

The `D)` line is an **optional music line** of the datapack
(`neumaRk_datapack.md` §3, note group) that describes below-staff events
aligned by position to the events of the parent `N)` line.

There are **two orthogonal classes** of elements in `D)`:

1. **Note-anchored elements** — tokens in 1:1 correspondence with the
   notes of the parent `N)` line (or `N2`). The principal class.
2. **Barline-anchored elements** — text annotations anchored to the
   beginning or the end of a measure, independently of the internal
   note events.

The two classes coexist on the same line: barline-anchored ones are
recognizable by **adjacency to a composite barline border**;
note-anchored ones are all the other tokens.

---

## 2. Structural position and binding

The `D)` line follows the general rules of the voice group
(`neumaRk_datapack.md` §3, note group, and `neumaRk_voices.md` §3.1):

```
[A)]  N)|N2|N+  [D)]  [L)]
```

- it is optional; it may appear at most **once** per voice group;
- it is bound to the **`N)` / `N+` / `N2` line immediately preceding**;
- it follows the same measure barlines (`|`, `||`, `:|`, `|:`, etc.) and
  the same measure decorators as the parent line.

A `D)` line not bound to a valid `N)`/`N+`/`N2` in the same datapack
produces warning **W130**.

---

## 3. Element vocabulary

### 3.1 Punctual dynamics

Traditional dynamic markers, each **punctual** (valid on a single note):

```
p   mp   mf   f   ff   fff   pp   ppp   pppp   ffff   sf   sfz   fp
```

They do not extend over time: the volume implied by the mark holds for
the beat of the event and — interpretatively — until the next dynamic
mark, but graphically it appears only once.

### 3.2 Graphic hairpins

Two tokens, each rendered as a graphic sign (crescendo/decrescendo
"hairpin"):

| Token | Effect        |
|-------|---------------|
| `<`   | crescendo     |
| `>`   | decrescendo   |

Hairpins extend **by repetition**: a sequence `< < <` over three notes
produces a single graphic sign that covers those three notes. A single
occurrence is allowed (punctual).

### 3.3 Text hairpins

Two short tokens that generate a **textual** indication with a dashed
extension line:

| Token | Rendering         |
|-------|-------------------|
| `c`   | "cresc. - - - - " |
| `d`   | "dim. - - - - "   |

They extend by repetition, exactly as §3.2: a sequence `c c c c`
produces a single "cresc." writing followed by a dashed line that
covers the four notes.

**Co-location with graphic hairpin (`c<` / `d>`)**: when `c` and `<`
(or `d` and `>`) appear on the same note as co-located tokens, the
**graphic** hairpin wins. The text token is ignored by the hairpin
extraction post-pass. To obtain the "cresc."/"dim." text without a
hairpin, use `c`/`d` alone. To obtain both signs simultaneously you
must write them on different notes (e.g. `c <` on two adjacent notes).

**Text compounds `pc` / `fd`**: they are NOT supported. A token
co-located with a punctual dynamic followed by a text hairpin (e.g.
`pc`, `fd`) produces only the punctual dynamic; the text hairpin is
ignored. To express "p and then cresc." write on two notes: `p c`.

### 3.4 Text annotations

Text containers with or without a box (see `neumaRk_text_markup.md` §2):

| Form      | Effect                                           |
|-----------|--------------------------------------------------|
| `"text"`  | annotation without a box                         |
| `[text]`  | annotation with a box                            |

The content of the container is subject to the **unified markup** defined
in `neumaRk_text_markup.md`. The **default style** of `D)` annotations
is *plain, reduced size*: italic, bold and underline are applied only if
explicitly requested through the user markup (`*…*`, `**…**`, `__…__`).

Text annotations are **punctual** by default; they become **extended**
if followed by an adjacent `-` (see §5).

### 3.5 Placeholder `.`

The token `.` indicates **no element** on the corresponding note. It
serves to "skip" a note while preserving the positional alignment.

The `.` also has a **closing** role: a `.` on a note interrupts any
text extension in progress (see §5.4).

### 3.6 Continuation `-`

The token `-` as a **standalone token** (separated by spaces) means
"continues the text extension opened to the left". It applies only to
text annotations (see §5).

`-` also has an **adjacent** role (without spaces) as an extension
opening marker (`"text"-`) or as a barline anchor (`[1.]-"text"`,
`"text"-:|`). The three roles are distinguishable by position and
adjacency (see §4, §5, §6).

---

## 4. Note-anchored elements

### 4.1 1:1 correspondence with the parent `N)` line

Each note-anchored token of the `D)` line falls on a note of the parent
line, in left-to-right order. The correspondence is strictly
positional:

```
N) | a8 b c d e f g a |
D) | p  .  .  < < < f .  |
     ↑           ↑   ↑
   note 1     notes 4-6  note 7
```

### 4.2 Co-location: multiple elements on the same note

Multiple elements on the same note are written as a **single token**
without internal spaces:

```
N) | a4    b   c   d |
D) | f"piano fill"   .   c<   .  |
     ↑ 3 elements on the same note: f + "piano fill" + (none on b)
```

The order of co-located elements is **free**: `f"text"c<` and
`"text"<fc` are equivalent from the semantic point of view (same note,
same elements). The renderer may apply a canonical order in display.

### 4.3 Autofill of residual notes

If the `D)` line contains **fewer** note-anchored tokens than the parent
`N)` line, the residual notes receive an **implicit** `.`:

```
N) | a a a a a a a a |
D) | f               |     ≡  D) | f . . . . . . . |
```

If the `D)` line contains **more** tokens than there are note events in
the parent line (extra-tokens), it produces warning **W131**.

### 4.4 Measures and barlines

The subdivision into measures is defined by the barlines `|` as for the
other music lines. The barlines of `D)` must align with those of the
parent line (general rules of `neumaRk_datapack.md` §6).

---

## 5. Text extension `-`

### 5.1 Only texts are extendable

Text annotations (`"text"`, `[text]`) are **the only elements extendable
through the hyphen `-`**. Punctual dynamics (§3.1) do not extend by their
nature; graphic and text hairpins (§3.2, §3.3) extend by **repetition**,
not with `-`.

### 5.2 Opening

A hyphen `-` **adjacent** (without spaces) to the right of a text
annotation opens an extension:

```
D) | "intro"-  -  -  -  mp |
       ↑ opens extension     ↑ closes
```

In a co-located group, the adjacent `-` applies to the text annotation
of the group, not to the other elements:

```
D) | ff"drums fill"-  -  -  -  -  -  -  ppp  -  -  -  - |
       ↑ opens extension of the text (ff stays punctual on note 1)
                                   ↑ ppp punctual, closes "drums fill"
```

### 5.3 Continuation

A **standalone** `-` (token separated by spaces) continues the extension
opened to the left. It works for any number of subsequent notes,
**even across measure barlines**:

```
N) | a16 a a a a a a a    a a a a a a a a | a8 a a a a a a a |
D) | ff"drums fill"- - - - - - - ppp- - - - - - - - -   -  - - - pp
     ─────── extension 1 ───────┘ ───── extension 2 ────────┘   ── pp punctual
                                                          (continues cross-bar)
```

### 5.4 Closing

A text extension terminates when **one of the following events** is
encountered:

- a **new** note-anchored element *without* an adjacent `-` above it
  (dynamic mark, hairpin, annotation, placeholder `.`);
- the **end of the current system** (implicit closing);
- a new text annotation opened with an adjacent `-`: closes the
  previous one and opens a new one;
- a **new begin-bar anchor** `-"text"` (see §6.2) as the first token
  of a measure: closes the previous extension on the immediately
  preceding note and opens a new begin-bar anchor aligned to the
  opening barline of the current measure.

The last rule also applies when the previous extension is cross-bar
barline-anchored (opening `-"prev"- … -` continues over the
intermediate measures): a new begin-bar `-"new"` **implicitly closes**
it and opens a new one, aligned to the entry barline border of the
current measure. No explicit closing is required.

Example:

```
D) | "intro"- - - - - - - - | -"new"  p . . ff |
       ↑ extension opened      ↑ closes "intro" on note 8 of the
                                previous measure, opens "new"
                                begin-bar in the current measure
```

To close explicitly before the end of the system without opening a new
anchor, insert `.` (placeholder) or another note-anchored element
without an adjacent `-`.

### 5.5 Free cross-bar

The measure barline `|` (and its composite variants) is **transparent**
to the text extension: a `-` continues through `|` without need of
special syntax. To anchor an annotation to the barline rather than to an
internal note, use the barline-anchored form (§6).

### 5.6 Parallel extensions

Multiple parallel extensions (e.g. text + hairpin) are obtained by
**combining the rules**: the text extends with `-`, the hairpin repeats
per note. There is no `-` mechanism to extend a hairpin:

```
N) | a a a a a a a a |
D) | "cresc."- - - - < < < < |
     ↑ extended text          ↑ graphic hairpin over 4 notes
```

The rendering presents both signs in the D) band, with vertical
positioning rules at the renderer's discretion.

---

## 6. Barline-anchored elements

### 6.1 Context: barline border and D) content

In neumaRk a "barline border" is the **composite group** formed by the
barline `|` and its adjacent decorators: repetition (`:`), meter/key
change (`(3/4)`, `(@F)`), volta (`[1.]`, `[2.]`), repetition count
(`:x3`), etc. The barline border is a property of the **line** (see
`neumaRk_datapack.md` §6) and is **common to all the music lines** of
the datapack: D) does not replicate it in its own content.

Consequently, the **content of D) for each measure** is the text
between one barline and the next, **excluding** any barline border
decorator. It is on this clean content that the anchoring rules of
§6.2-§6.4 apply.

### 6.2 Begin-bar

A hyphen `-` as the **initial character** of the first token of the
measure, followed (without spaces) by a text annotation, anchors the
annotation to the **beginning of the measure**:

```
D) | -"my text 1"  p . . ff |
       ↑ "my text 1" begin-bar anchored
```

The initial `-` does not represent an extension here: it represents a
**barline anchor**. The annotation stays punctual by default; to extend
it across the subsequent measures the rule of §6.4 applies.

> **Interaction with a previous extension** (§5.4): if the previous
> measure had a text extension open (note-anchored or barline-anchored
> cross-bar), the new begin-bar `-"text"` **implicitly closes** it on
> the immediately preceding note and opens the new anchor aligned to
> the barline border. To close the extension explicitly before the
> begin-bar, insert `.` or another closing element on the last note of
> the previous measure.

### 6.3 End-bar

Symmetrically: a text annotation followed (without spaces) by `-` as
the **last token** of the measure anchors the annotation to the **end
of the measure**:

```
D) | ff "my text 2"- |
            ↑ "my text 2" end-bar anchored
```

### 6.4 Cross-bar barline-anchored extension

A barline-anchored annotation may extend across multiple measures by
combining **two hyphens** on the first token (anchor + open) and one on
the last (anchor + close):

```
D) | -"Vamp till cue"-  -  -  - | -  -  -  -  - | -  -  - "end"- |
       ↑ begin-bar + opens ext      ↑ continues ext (cross-bar)        ↑ end-bar (closes)
```

- The **first `-`** anchors the annotation to begin-bar.
- The **second `-`** adjacent to the text opens the text extension
  (as for the note-anchored ones).
- In the subsequent measures, standalone `-` continues the extension.
- The closing follows the same rules as §5.4; in addition, an end-bar
  form `"end"-` as the last token can explicitly close an open
  extension (with `"end"` here used symbolically too — a new
  barline-anchored element closes the one in progress).

### 6.5 Coexistence of begin + end in the same measure

A measure may contain both a begin-bar annotation and an end-bar one:

```
D) | -"text 1"   p . . ff   "text 2"- |
       ↑ begin                ↑ end
```

Any note-anchored elements of the measure (`p . . ff`) are interleaved
normally between the begin annotation and the end one.

---

## 7. Parsing rules

### 7.1 Tokenization

The `D)` line is tokenized on **whitespace**. Within a token multiple
co-located elements may appear (§4.2). The text containers `"…"` and
`[…]` admit internal spaces (they are delimited by their
quotes/square brackets).

### 7.2 Disambiguation of `-`

The character `-` has three roles, distinguishable by **position and
adjacency** with respect to the content of the D) measure:

| Form                           | Role                               |
|--------------------------------|------------------------------------|
| `"text"-` (adjacent to annot, not last token of the measure) | opens text extension (§5.2)        |
| `-` (standalone token)         | continues extension (§5.3)         |
| `-"text"` as FIRST token of the measure | begin-bar anchor (§6.2)    |
| `"text"-` as LAST token of the measure | end-bar anchor (§6.3)    |
| `-"text"-` as first token      | begin-bar + opens cross-bar extension (§6.4) |

A `-` not reducible to any of these three patterns produces warning
**W132**.

### 7.3 Disambiguation of `[…]`

The container `[…]` in `D)` is always a text annotation with a box. It
does not collide with the volta begin (`[1.]`) because the latter
appears in the Markers line, not in `D)`. It does not collide with
polychord (`[top|bottom]`) for the same reason.

### 7.4 Single-line and empty containers

Text containers are single-line (see `neumaRk_text_markup.md`
§6.2). Empty containers `""` and `[]` are literals and not interpreted
as annotations (they are empty text tokens).

### 7.5 Internal markup

The content of `"…"` and `[…]` in `D)` is subject to the unified markup
of `neumaRk_text_markup.md` §3. The default style applied is *plain,
reduced size*: italic, bold and underline are activated only through
explicit markup (`*…*`, `**…**`, `__…__`).

---

## 8. Graphic rendering

### 8.1 D) band

All the elements of the `D)` line are rendered **below the staff** of
the parent staff, in a dedicated band. When the parent staff is a voice
2 (`N2`), the `D)` band of voice 2 may be superimposed on or adjacent to
that of voice 1: the vertical positioning is a renderer's choice.

### 8.2 Punctual dynamics

The dynamic marks (§3.1) are rendered as traditional bold-italic text
(musical typographic convention), aligned horizontally to the beat of
the corresponding note.

### 8.3 Graphic hairpins

The hairpins (`<`/`>`) are rendered as a single "hairpin" sign that
covers the interval from the first to the last repetition, with the
ends aligned to the beats of the opening and closing notes.

### 8.4 Text hairpins

`c` and `d` produce respectively "cresc." and "dim." as italic text,
followed by a **dashed line** that extends up to the beat of the last
repetition. The style is consistent with the musical typographic
convention.

### 8.5 Text annotations

Default style: *reduced italic*. Annotations with `[…]` (with a box)
show a graphic rectangle around the text; annotations with `"…"`
(without a box) are text only.

The text **extensions** are rendered as a continuous or dashed line
(at the renderer's discretion) that starts at the end of the text and
extends up to the closing beat.

### 8.6 Barline-anchored annotations

Begin-bar annotations are aligned vertically to the left border of the
measure; end-bar ones to the right border. Cross-bar extensions
graphically cross the measure barlines.

---

## 9. Diagnostics

### 9.1 Diagnostic codes

| Code   | Description                                                              |
|--------|--------------------------------------------------------------------------|
| W130   | `D)` without a valid parent `N)`/`N+`/`N2` line in the datapack          |
| W131   | Number of note-anchored tokens in `D)` greater than the events of `N)`   |
| W132   | Token `-` in a position not reducible to extension or barline anchor     |
| W133   | Text container not closed by end of line (`"…` or `[…` without closing)  |

### 9.2 Unclosed extensions

A text extension that reaches the end of the system is closed
**implicitly** at end of system (§5.4). It is not an error: the spec
considers this a valid and robust behavior. To close explicitly before
the end of the system, simply insert `.` or another note-anchored
element without an adjacent `-`.

### 9.3 Hairpin with a single occurrence

A hairpin (`<`, `>`, `c`, `d`) that appears only once on a note is not
an error: it produces a punctual graphic/text sign (of minimal
extension). No warning is emitted.

---

## 10. Examples

### 10.1 Essential dynamics

```
N) | a4 b c d | e f g a |
D) | p  .  .  f  | .  <  <  ff |
```

`p` on note 1 of measure 1, `f` on note 4; graphic crescendo on notes
2-3 of measure 2 culminating in `ff` on note 4.

### 10.2 Punctual and extended annotation

```
N) | a8 a a a a a a a | a a a a a a a a |
D) | "intro"- - - mp< < < f | "verse"- - - - - - - - |
```

Measure 1: "intro" extended over 4 notes, then `mp` closes and a
graphic hairpin starts up to `f`. Measure 2: "verse" extended over the
entire measure; implicit closing at end-of-system.

### 10.3 Text hairpin `c` / `d`

```
N) | a8 a a a a a a a | a a a a a a a a |
D) | p c c c c c c c | c f . . d d d d |
```

Measure 1: `p` punctual on note 1, "cresc." extends over 7 notes. The
first repetition `c` falls on the same note as `p` (co-located).
Measure 2: a further `c` continues the "cresc." up to note 1, then `f`
closes. From note 5: "dim." extends over 4 notes.

### 10.4 Complex co-location

```
N) | a4 b c d |
D) | ff"drum fill"c<  .  .  ppp |
```

On note 1: 4 co-located elements (`ff` punctual + text "drum fill"
+ text hairpin `c` + graphic hairpin `<`). Notes 2-3 are empty;
`ppp` punctual on note 4.

### 10.5 Barline-anchored begin

```
M) |[V.]                                          …
D) | -"Vamp till cue"- p . . . . . . . . |
```

"Vamp till cue" anchored to the beginning of the measure `[V.]`
(volta), extended over the entire measure (the `-` continue on the
subsequent notes because the hyphen adjacent to the right of the text
opens the extension).

The `[V.]` decorator of M) is **not replicated** in the content of D):
the parser works on the clean content of the measure (see §6.1).

### 10.6 Barline-anchored cross-bar

```
D) | -"Vamp till cue"- p . . . . . . . . | - - - - - - - - | - - - - mp - - - |
```

"Vamp till cue" covers 3 measures; closes on `mp` in measure 3.

### 10.7 Begin + end in the same measure

```
M) |:(3/4)[1.]                              :x3|
D) | -"intro"   p . . ff   "outro"- |
```

Annotation "intro" begin-bar + annotation "outro" end-bar in the same
measure. Dynamics `p` and `ff` on the internal notes. The barline
border of M) (`:(3/4)[1.]` / `:x3|`) does not appear in the content of
D).

### 10.8 Voice 2 with independent dynamics

```
N)  | a4 b c d |
D)  | f . . ff |
N2  | e4 d e2  |
D)  | p . pp   |
```

Voice 1 has `f` on note 1 and `ff` on note 4; voice 2 has `p` on note
1 and `pp` on note 3. The two `D)` are both bound to their respective
`N)`/`N2` by position (see `neumaRk_voices.md` §3.1).

---

## 11. Summary

| Concept               | Syntax                                    | Section |
|-----------------------|-------------------------------------------|---------|
| Punctual dynamic      | `p mp mf f ff fff pp ppp pppp ffff sf sfz fp` | §3.1 |
| Graphic hairpin       | `<` `>` (by repetition)                    | §3.2    |
| Text hairpin          | `c` (→ cresc.) `d` (→ dim.)                | §3.3    |
| Text annotation       | `"text"` / `[text]`                        | §3.4    |
| Placeholder           | `.`                                        | §3.5    |
| Continuation          | `-` standalone                             | §3.6    |
| Co-location           | adjacency without spaces                   | §4.2    |
| Autofill              | residual notes → implicit `.`              | §4.3    |
| Text extension        | `"text"-` opens, `-` continues, `.` closes | §5      |
| Begin-bar             | `-"text"` as FIRST token of the measure     | §6.2    |
| End-bar               | `"text"-` as LAST token of the measure      | §6.3    |
| Cross-bar barline-anch| `-"text"-` … `"end"-` (cross-bar)           | §6.4    |
| Cross-bar note-anch   | `-` crosses `|` transparently              | §5.5    |

The system is **orthogonal**: the three mechanisms (punctual dynamics,
hairpins by repetition, texts with extension `-`) coexist without
interference and combine by co-location.

---

This document defines the `D)` line of neumaRk as a unified
**below-staff annotation band**, able to express traditional dynamics,
crescendo/decrescendo indications, punctual and extended text
annotations and anchors to the measure barlines, through a compact
vocabulary and orthogonal rules.


---

# Lyrics (`L)` line)

> **STATUS: SPEC.** §1–§7 sealed 2026-05-23 (deduction semantics of the
> inline `L)` line). §8 (section lyrics block `LYRICS)`) is **DESIGN
> 2026-05-27**, sealed decisions, implementation in progress (§8.4.1
> pickup syllables sealed 2026-05-28) — see
> `docs/feature-lyrics-sections-and-editions.md`. Binding and order of `L)`
> are not redefined here: see `neumaRk_datapack.md §2.1` and §3. Sealing
> decisions and residual notes in §7; code-side follow-up in
> `docs/feature-deduction-spec-audit.md`.
>
> **The Italian version (`../it/neumaRk_lyrics.md`) is the source of
> truth**; this English version mirrors it.

## 1. Definition

The `L)` (Lyrics) line carries the **lyrics**, syllable by syllable, aligned
to the events of the `N)` line it is bound to. It is a parallel layer: it does
not alter rhythm or flow. Multiple consecutive `L)` lines of the same staff
form distinct **verses** (multi-verse).

## 2. Structural position and binding

Marker, optionality and logical order are defined in `neumaRk_datapack.md`
§2.1 and §3 (implicit order: `L)` is **optional and last** of the note group).
The line binds to the `N)` of its own group/staff; **voice 2** (`N2`) has its
own `L)` lines (see `neumaRk_voices.md`).

## 3. Count-based alignment (notes only, not rests)

The correspondence is **positional by count**, left-to-right, but computed
**only on note-events**: **rests do not receive syllables**.

```
N) | c4 d  r  e  |
L) | la la    sol |
     ↑  ↑  ↑   ↑
     la la (rest: none) sol
```

- The syllable counter advances **only** on actual notes (`isNote()`); on a
  rest an empty padding is emitted (preserving positional alignment).
- Token `.` = **placeholder**: no syllable on that note (the note stays
  without text, but the position is consumed).
- Tokens in excess beyond the number of notes: emits **W131** (like `D)`;
  aligned 2026-05-23, parser follow-up).

## 4. Multiple verses (multi-verse)

Each **consecutive** `L)` line of the same staff is a successive **verse**:

```
N) | c  d  e  f |
L) | first verse syllables… |     ← verse 1
L) | second verse…          |     ← verse 2
```

- Limit: **10 verses** per measure/staff; lines beyond the tenth are silently
  dropped.
- Padding between verses: for each verse, the notes without a token receive an
  empty syllable, so all notes have the same number of verses (vertical
  alignment between verses).

## 5. Syllable mechanics

Each text token is a **word**, optionally hyphenated with `-`:

| Form           | Effect |
| -------------- | ------- |
| `parola`       | one syllable (whole word) on the current note |
| `pa-ro-la`     | three syllables on three consecutive notes; the non-final syllables are marked **`word_continues`** (hyphenation dash in render) |
| `_`            | **melisma**: extends the previous syllable onto the current note (no new syllable) |
| `.`            | placeholder: no syllable (see §3) |
| `-coda`        | token with **leading** `-`: **continuation** of the previous word — back-marks the last emitted syllable as `word_continues` and adds `coda` as the next syllable (per-syllable form produced by the serializer) |

Robustness details (as per parser):

- the **empty** syllables generated by spurious hyphens (`-mar`, `mar--ti`,
  isolated `-`) are **discarded**;
- a syllable is `word_continues` if there exists a **non-empty** syllable after
  it within the same token (or if a continuation token `-X` follows).

## 6. Examples

```
N) | c4   d    e   f    |
L) | Ave-       _    ma- ri-a  |
```
`Ave` (with hyphenation dash) → `_` extends `Ave` onto the 2nd note →
`ma`/`ri` continue; `a` closes the word.

## 7. Decisions (closed 2026-05-23) and residual notes

Closed:

1. **Syllable excess** ✓ — emits **W131** like `D)` (was a silent drop;
   parser follow-up in `docs/feature-deduction-spec-audit.md`).
2. **§5 mechanics normative** ✓ — hyphenation, melisma `_`, continuation `-`
   as described.

Residual notes (current behavior documented as normative pending revision,
non-blocking):

- **Cap of 10 verses**: beyond the tenth, silent drop. Limit confirmed; the
  behavior on overflow (silent vs warning) remains revisable.
- **Rests**: they always interrupt the syllable count — the rest receives no
  text and the melisma `_` does not "skip over" it. Normative.
- **Canonical hyphenation form of the serializer**: the parser accepts both
  `pa-ro-la` and the per-syllable form `pa- -ro- -la`; which form the
  serializer *emits* is a separate output choice (it does not affect parsing),
  to be fixed when working on the serializer round-trip.

---

## 8. Section lyrics block (`LYRICS)` line)

> **DESIGN 2026-05-27, sealed decisions.** Roadmap and rationale in
> `docs/feature-lyrics-sections-and-editions.md`.

### 8.1 Purpose and relationship to `L)`

The `LYRICS)` block is an **alternative way to write the same verses** that
`L)` writes inline. Instead of aligning syllables to the notes of a single
datapack, it carries the text **per section** and lets the engine
distribute the syllables onto the notes of that section automatically.

`LYRICS)` does **not** introduce a different lyrics model: it feeds the very
same per-note `Lyric` slots that `L)` feeds (§3, §5). The inline `L)` line
remains fully valid; the two compose (§8.5).

The equivalence with `L)` holds **only for rendering**, though: the block
carries information the inline cannot express — the **text edition**
(language + author, §8.8). For this reason the **round-trip serializer
preserves the form the user chose**: a `LYRICS)` block re-emits `LYRICS)`
(verbatim, language included), an `L)` line re-emits `L)`. The serializer does
NOT automatically convert one into the other; the explicit conversion is a
separate user action (WRITE context menu, not yet implemented).
Implementation: `Music::lyrics_blocks` (raw block + position) +
`Lyric::from_section` (suppresses the inline re-emission of verses that
round-trip as a block).

### 8.2 Syntax

```
LYRICS)
[A] sillabe del verso…
[B] sillabe del verso…
[A] (a second [A] line = a second verse on A)
```

- The block opens with a line whose first non-blank token is the marker
  `LYRICS)` (optionally followed by an **edition** tag
  `[language] [<author>]`, §8.8).
- Each **entry** starts with a section reference `[NAME]` (§8.3). The text
  after the `]` on the same line, and/or the following non-blank lines that
  do **not** start with `[`, are the **syllables** of that entry.
- The entry text may optionally begin with a **pickup group** `<…>` —
  syllables that bind to the notes *preceding* the section (anacrusi).
  See §8.4.1.
- **Blank lines inside the block are allowed** (visual separators): they do
  not close the block.
- The block extends until the first **top-level marker** (`LYRICS)`,
  `PLAY)`, `FORM)`, `%%…`) or **datapack prefix** (`M) N) C) A) D) L) F)`).

Both compact and expanded forms are accepted and equivalent:

```
LYRICS)                          LYRICS)
[A] this is a text       ≡       [A]
                                 this is a text
```

The syllable grammar is **identical to `L)`** (§5): `pa-ro-la`,
melisma `_`, placeholder `.`, leading-`-` continuation.

### 8.3 Section reference and structural position

`[NAME]` is the same **reference-by-name** used by `PLAY)` / `FORM)`
(`neumaRk_play_and_form.md` §3.1): matching is by **text-equality on NAME**
with markup stripped (`neumaRk_text_markup.md` §7.1). A `LYRICS)` block may
appear **anywhere between datapacks**; position in the file does not affect
which section an entry binds to (binding is by name, like `%%versions`).

A reference to a non-existent section is **reference-broken**: warning
**W157** (non-blocking, §8.9).

### 8.4 Cross-datapack section aggregation

This is the defining behaviour: the syllables of `[A]` are spread over
**all the notes of section `[A]`**, concatenated in flow order, **crossing
datapack / system / measure boundaries**. (Inline `L)` is by contrast local
to one datapack.)

A measure belongs to the section whose marker is the **most recent**
`[…]` section marker at or before that measure (annotations `"…"` do **not**
open a section, `neumaRk_markers.md` §3.1, §4.1). A maximal run of
consecutive measures with the same current section is an **occurrence** of
that section.

```
M) [A]
N) a b c d

N) e f g a          ← same [A], next datapack, no marker

LYRICS)
[a] mol-te sil-la be su_un ri-go
     └─ distributed over a b c d  e f g a (8 notes, one occurrence, cross-datapack) ─┘
```

Within an occurrence, the notes (first staff, voice 1 — §8.7) are collected
in flow order and the syllables are bound exactly as `L)` (§3): **positional
by count, rests receive no syllable**, `.` placeholder, `_` melisma.

**Multiple occurrences (template).** If `[A]` occurs more than once
(e.g. AABA), the entry is a **template** applied to **each** occurrence: the
same syllables are bound, independently, to every occurrence. The syllables
are **not** spread across occurrences. (Per-occurrence different text — e.g.
verse 1 / verse 2 across repeats — is out of scope; use distinct names
`[A1]`/`[A2]`, §8.10.)

### 8.4.1 Pickup syllables (anacrusi) — `<…>`

> **DESIGN 2026-05-28, sealed decisions.** Closes the gap where lyrics
> need to start *before* a section boundary (anacrusi / pickup).
> Roadmap in `docs/feature-lyrics-sections-and-editions.md` §2.5.

An entry may begin with a **pickup group** delimited by `<…>`. The
syllables inside the group bind to the **last N notes that precede** the
section's occurrence in flow order, where **N is the syllable count** of
the group (after grammar expansion: `pa-ro-la` counts 3, `_` and `.` count
1 each). Syllables *after* `>` continue normally on the first note of the
section's occurrence (§8.4).

```
M) [intro]      | a4 a a a |
M) [intro]      | h2 r4 c,8 d |
M) [A]          | e         |

LYRICS)
[A] <do re> mi
     │      └─ first note of [A] occurrence
     └──────── last 2 notes of the previous section ([intro]: c,8 d)
```

**Where the pickup lands.** For each occurrence of `[NAME]`, the pickup
scans **backward** from the first note of that occurrence over the
contiguous run of notes whose current section is **not** `[NAME]`. The N
last notes of that run receive the pickup syllables (rests are skipped,
exactly as in §3 / §8.6). The scan stops at:

- the first note belonging to `[NAME]` (i.e. it never crosses into the
  occurrence itself or into an earlier occurrence of `[NAME]`);
- the start of the piece (no notes before `[NAME]`'s first occurrence).

**Voltas.** When the preceding run contains voltas
(`|[1.]` … `|[2.]` …, `neumaRk_flow_and_repeats.md` §6), only the
**last** volta contributes notes to the pickup; measures inside earlier
voltas are **skipped** by the backward scan. The intuition is that the
anacrusi is the run-up *into* `[NAME]` along the path the music actually
takes the last time, i.e. the path that ends in `[NAME]`. Non-volta
measures contribute normally.

**Multiple occurrences (template).** As with the post-`>` syllables, the
pickup group is a **template**: it is applied **independently to each
occurrence** of `[NAME]`, each looking back into its own preceding run of
non-`[NAME]` notes. In AABA, every `[A]` gets its own pickup from the
notes just before it.

**Overflow / no preceding notes.**

- If the preceding run has **zero** notes (e.g. the occurrence is at the
  very start of the piece), the pickup is **silently dropped for that
  occurrence** — no warning. The post-`>` syllables are bound normally.
- If `0 < available < N` (partial overflow: a run exists but is shorter
  than the pickup), the available notes receive the trailing pickup
  syllables, the leading excess is dropped, and **W158** is emitted
  **once per affected occurrence** (non-blocking, §8.9). The post-`>`
  syllables are bound normally regardless.

**Verse accumulation (same slot, OVERRIDE).** A pickup occupies the
**same verse slot as its own body** on the pre-notes, **replacing** any
syllables already present on that slot (**sealed 2026-05-28, after
testing on a real piece**):

- The **body** occupies the section's **natural slot**,
  `verseCount[NAME]` — the first free row of the section, like an entry
  without a pickup (§8.5).
- The **pickup** occupies the **same slot as its own body** on the
  pre-notes: `pickupSlot = bodySlot`. If the pre-notes already carry
  syllables on that slot (e.g. the preceding section's body singing
  those notes), the pickup **overwrites** them. Otherwise the pickup
  writes directly (with implicit padding).

The musical effect matches traditional notation convention: the verse
of `[NAME]` literally "steals" the last N notes of its predecessor from
the predecessor's same-position verse (same language / same slot), and
sings the anacrusis there.

Multilingual example (Portuguese = slot 0, English = slot 1): the last
2 notes of `[B]` carry **two** pickup syllables — `<E vol>` of `[A2]`
Portuguese replaces the last 2 syllables of `[B]` Portuguese body
(slot 0); `<So I>` of `[A2]` English replaces the last 2 of `[B]`
English body (slot 1). The body of `[A2]` (both languages) stays on its
natural slots (0 and 1), in continuity with `[A1]` and `[B]`. To
achieve this replacement, the engine processes **all bodies first**,
**then all pickups** (so each pickup sees and overwrites the body
already written on the pre-notes).

**Constraints.**

- Only **one** pickup group per entry, and it must come **immediately**
  after `[NAME]` (and optional whitespace), before any post-`>` syllable.
- **Empty `<>`** is a silent **no-op**: it is consumed without effect, no
  warning. The post-`>` syllables bind as if the group were absent.
- `<` and `>` are reserved **inside `LYRICS)` entries** only; they are not
  syllable-grammar tokens elsewhere (`L)`, `D)`).
- Inside `<…>` the syllable grammar is identical to `L)` (§5):
  `pa-ro-la`, `_`, `.`, leading-`-` continuation. A leading-`-` continuation
  as the *first* token of the pickup group is **dropped** (there is no
  prior syllable in the same entry to continue).
- Staff/voice binding is the same as the entry body: **first staff,
  voice 1** (§8.7).

### 8.5 Verse accumulation (`L)` inline ++ `LYRICS)` blocks)

For each section, the verses stack top-to-bottom in this order
(**sealed 2026-05-27**):

```
verses(section) = [ inline L) verses, in order ] ++ [ [NAME] entries from LYRICS) blocks, in file order ]
```

Each `[NAME]` entry (one line) adds **one** verse. Two `[A]` entries (same
block or different blocks) add two verses, in order of appearance.

To keep verses **vertically aligned** across a section that spans several
datapacks (whose inline verse counts may differ), the engine first pads
every note of the section to `n_inline = max(note.lyrics.size())` over the
whole section, then appends each block verse at a uniform index across all
occurrences.

The three fragments below produce the **same** two-verse result on `[A]`:

```
// (a) all inline               // (b) mixed                  // (c) all block
N) ...                          N) ...                        N) ...
L) tes-to u-no                  L) tes-to u-no                LYRICS)
L) tes-to du-e                  LYRICS)                       [A] tes-to u-no
                                [A] tes-to du-e               [A] tes-to du-e
```

### 8.6 Alignment rules (reused from `L)`)

Identical to §3 and §5: positional-by-count on notes, **rests receive no
syllable**, `pa-ro-la` hyphenation (`word_continues`), `_` melisma,
`.` placeholder, leading-`-` continuation. Syllables in excess of the notes
of an occurrence emit **W131** (as `L)` / `D)`); notes in excess of the
syllables receive an empty `Lyric{}` (padding).

### 8.7 Staff / voice binding

A `LYRICS)` entry always binds to the **first staff, voice 1** (the main
vocal line) — **sealed 2026-05-27**. Lyrics for other staves or for voice 2
(`N2`) use the inline `L)` line, which already has that granularity
(`neumaRk_voices.md`). The block trades per-voice granularity for
per-section convenience.

### 8.8 Text editions (`LYRICS) [language] [<author>]`)

> DESIGN 2026-05-30, sealed (Phase B). Generalizes multilingual lyrics
> (Phase 3): "language" is now a special case of a text **edition**. Roadmap
> and decisions in `docs/feature-lyrics-sections-and-editions.md` §9-§11.

An **edition** is a version of the sung text; a song may have more than one.
The `LYRICS)` header may carry two optional elements, on **distinct axes that
are also syntactically separate**:

- a **language token** (`LYRICS) pt-br`): a code (`it`, `en`, `pt-br`, …;
  form `[a-z]{2,3}(-region)?`, case-insensitive, lowercased) — a translation;
- an **author** in `<…>` (`LYRICS) en <Frank Sinatra>`): who wrote *that*
  text. Free text, may contain spaces (the brackets delimit it: no
  disambiguation heuristics).

| Form | Nature |
|---|---|
| bare `LYRICS)` / inline `L)` | **neutral** (default, no language/author) |
| `LYRICS) pt-br` | **language** |
| `LYRICS) en <Frank Sinatra>` | **language + author** |
| `LYRICS) <Al Jarreau>` | **author-only** (no language) |

An edition is identified by the pair **(language, author)**. **Multiple
editions in the same language** with different authors are allowed (vocalese /
competing translations: `en <Jon Hendricks>` + `en <Eddie Jefferson>`).

#### Default — Rule A

- **neutral** (no language, no author) → default text;
- **language** (has language, ± author) → *intrinsic*, contributes to the
  default;
- **author-only** (author without language) → **opt-in**, never the default.

The **default text** is the neutral one (inline `L)` or bare `LYRICS)`) if
present, otherwise the **first language edition in file order**. If no
intrinsic edition exists (only `<author>`-only) the song opens
**instrumental**: no default text, editions are activated from the selector.

#### Selection

The **active edition** is a scalar **user preference** (one per song,
key = the language+author pair), selectable from a menu — same pattern as
`%%versions` but scalar. It selects **which** edition feeds the per-note
`Lyric` slots; entries of the other editions are not bound. If the active
pair does not exist among the editions, the **default** is used (Rule A); if
there is no default (instrumental), no block lyric is bound.

The **inline `L)`** line is the **neutral default** edition: it accumulates
per §8.5 when the neutral edition is the shown text.

#### Metadata (title / author)

- **Title per language**: one title per language (shared by *all* editions of
  that language — it is the translation of the song's name, it does not change
  with the lyricist), declared with the `[language]` tag on `HT)` titles
  (`neumaRk_header.md` §8.1). It lives in the **metadata**, not in the block
  text.
- **Text author**: for the default → global `lyricsBy` (`HCL)`); for a tagged
  edition → the `<…>` group on the `LYRICS)` block. For an author-only edition
  the name **IS** that edition's lyricsBy. The old per-language credit
  `HCL) … [language]` is **removed** (`neumaRk_header.md` §9.2).

The edition axis is **orthogonal** to the `%%versions` axis: two independent
user choices that compose. Version filtering (`applyVersionFiltering`)
rewrites the flow first; the active edition's lyrics then bind by-name to the
remaining notes. Available languages are **deduced** from the `LYRICS)`
blocks + the `[language]` tags on titles; there is no declaration header
(`HL)` stays out of scope, like the optional `HV)`).

#### 8.8.1 Title ↔ language bridge

A title carrying a language tag (`neumaRk_header.md` §8.1, e.g.
`HT) No More Blues [EN]`) is bound to that code. Opening the song **as** that
title (e.g. from a search result) preselects the language for the session: the
shown title and the lyrics language follow that choice. This is a **session
override** (like a URL parameter): it does **not** overwrite a saved user
preference, which stays settable from the menu.

### 8.9 Diagnostics

| Code | Severity | Description |
|------|----------|-------------|
| W157 | WARNING  | `LYRICS) [NAME]` references a non-existent section (reference-broken) |
| W158 | WARNING  | `LYRICS)` pickup group `<…>` overflows the available preceding-notes run (run shorter than N, leading excess dropped) — one per affected occurrence; silent skip if the run is empty (§8.4.1) |
| W131 | WARNING  | syllables in excess of the notes of an occurrence (shared with `L)` / `D)`) |

Both non-blocking. (Cap of 10 verses per note, §4, applies to the combined
inline+block total.)

### 8.10 Out of scope (MVP)

- **Per-occurrence text** (AABA singing different words each pass of the
  same `[A]`): not covered — verses stack vertically, they are not
  per-occurrence. Workaround: distinct section names `[A1]`/`[A2]`.
- **Voltas `|[1.]` / `|[2.]`** with different text per ending.
- **Multilingual binding to alternative titles** (Phase 3, §8.8).

### 8.11 Examples

Two verses on `[A]`, one verse on `[B]`, `[Instrumental]` left untexted:

```
M) [A]      | c4 d  e  f |
M) [Instrumental] | g a  b  c |
M) [B]      | c  b  a  g |

LYRICS)
[A] this is the first verse here
[A] and here the second verse goes
[B] the bridge has its own words now
```

Cross-datapack occurrence (one `[A]` over two datapacks):

```
M) [A]
N) c d e f

N) g a b c

LYRICS)
[A] eight syl-la-bles a-cross two rows
```


---

# Text markup

This document defines the syntax and semantics of **text markup**
in neumaRk: common formatting rules applicable to all textual
containers of the language (markers, end-decorators, comment-labels, note
annotations, section labels, form prose).

The goal is to provide a **unified and orthogonal** system in which a first
axis decides the graphical box (container), a second axis decides the default
style (hosting construct), and a third axis — optional — allows
the user to apply explicit markup.

---

## 1. Three orthogonal axes

Text rendering in neumaRk is a function of three independent axes:

1. **Container** — `[…]` (with box) or `"…"` (without box).
2. **Default style** — determined by the hosting construct (marker,
   comment-label, annotation, prose, etc.).
3. **User markup** — optional, defined through a subset of
   Markdown applied inside the container.

None of the three axes constrains the others. The same text can be
expressed in any combination of box/no-box, any default
semantics, with or without explicit markup.

> **Exception: marker `M)`.** In markers of the `M)` line (sections and
> annotations, see `neumaRk_markers.md` §3.1) the container `[…]` vs
> `"…"` also carries **structural semantics**, not just a graphical box:
> `[…]` = section (target of PLAY/FORM, delimits collapsible scopes),
> `"…"` = annotation (descriptive text, non-structural). The rule
> of "syntactic interchangeability" of §2.1 therefore has a normative
> exception in M).

---

## 2. Textual containers

### 2.1 Forms

A textual container is a sequence of characters delimited by:

- `[` … `]` → **container with box**;
- `"` … `"` → **container without box**.

The two forms are **syntactically interchangeable** in every context
that admits one of the two. The difference is the presence of the graphical box
in rendering, except for markers of the `M)` line where the
two forms also carry distinct structural semantics (section vs
annotation, see `neumaRk_markers.md` §3.1).

### 2.2 Where markup applies

The markup defined in this document applies to all textual
containers of the language:

| Construct                                  | Allowed containers | Reference                              |
|--------------------------------------------|--------------------|----------------------------------------|
| Section `M)`                               | `[…]`              | `neumaRk_markers.md` §3.1              |
| Annotation `M)`                            | `"…"`              | `neumaRk_markers.md` §3.1              |
| Textual end-decorator                      | `[…]`, `"…"`       | `neumaRk_flow_and_repeats.md` §4.3     |
| Comment-label chord / group / row          | `[…]`, `"…"`       | `neumaRk_chords.md` §7                 |
| Note annotation                            | `[…]`, `"…"`       | `neumaRk_notes_and_durations.md` §8    |
| Dynamics `D)` annotation                   | `[…]`, `"…"`       | `neumaRk_dynamics.md` §3.4             |
| Articulation `A)` label (wave, bracket)    | `"…"`              | `neumaRk_articulations.md` §10.2/§10.3 |
| Top/bottom section label box               | `"…"`              | `neumaRk_play_and_form.md` §3.3        |
| Free prose in `PLAY)` / `FORM)`             | all the prose      | `neumaRk_play_and_form.md` §5          |

Markup **does not apply** to:

- header values (title, credits, year, style, key, meter, BPM),
  which are rendered autonomously by the system;
- technical marker names when referenced in `PLAY)` / `FORM)`,
  where matching is by text-equality (markup, if present, is
  applied in display but stripped for matching);
- volta begin (`|[1.]`), which is a predetermined box-like container and
  does not admit internal markup.

---

## 3. Markup syntax

neumaRk markup is a subset of Markdown, chosen to be
deterministic and single-line.

### 3.1 Text size

The 3 prefixes `#`/`##`/`###` select a **relative size** that
depends on the **size role** of the construct (see §5):

- **role `reduced`** (default for: comment-label chord/group/row,
  note annotation, `D)` annotation, PLAY/FORM label, marker
  `"…"` annotation): the default is the **smallest** size;
  the prefixes scale only ABOVE.
- **role `body`** (default for: marker `M)` `[NAME]`, PLAY/FORM prose):
  the default is the **medium** size; the prefixes scale ABOVE and
  BELOW.

| Prefix    | role `reduced`               | role `body`                   |
|-----------|------------------------------|-------------------------------|
| `# `      | large (2.0× default)         | large (1.5× default)          |
| `## `     | medium (1.5× default)        | medium (1.0× default = body)  |
| `### `    | default (1.0×, = no prefix)  | small (0.7× default)          |

Rules:

- the **space after `#`/`##`/`###` is mandatory**: `#hashtag` is
  literal, `# title` opens the span;
- the prefix appears **only at the beginning of the container text** or
  **at the beginning of a prose run** (in `PLAY)` / `FORM)`, after a
  structural token or at the beginning of the body);
- the span opened by `#`/`##`/`###` **closes** at the first of the following
  events: end of the container, next structural token in `PLAY)` /
  `FORM)` (`[…]`, `&kw`, `$`, `@`);
- `####` and beyond are treated as literals;
- `### ` is allowed to make explicit one's own size level even if it is
  redundant with the default (e.g. in role `reduced`).

### 3.2 Emphasis

Three forms of emphasis, activated by paired delimiters:

| Syntax        | Effect              |
|---------------|---------------------|
| `*foo*`       | italic              |
| `**foo**`     | bold                |
| `***foo***`   | bold + italic       |

Rules:

- the spans are **closed delimiters**: an unclosed `*` is literal
  (no partial render);
- the closing asterisk must be preceded by non-empty content;
- the spans may appear in any position of the text;
- **nesting is not allowed** for emphasis (for example
  `**foo *bar* baz**` is invalid): the form `***foo***` is atomic.

### 3.3 Underline

Syntax activated by the **double underscore**:

| Syntax        | Effect              |
|---------------|---------------------|
| `__foo__`     | underline           |

Rules:

- like the emphasis spans, the span is a **closed delimiter**: an
  unclosed `__` is literal;
- the closing `__` must be preceded by non-empty content;
- the span may appear in any position of the text;
- **single underscore `_` is literal**: `_x_` is not alternative italic
  (NRK does not adopt the Markdown convention of `_` as an alias of `*`);
- **`___foo___`** (three or more opening/closing underscores) is
  treated as literal, analogously to `####` for size
  prefixes.

Underline **is not a form of emphasis**: it is an **orthogonal axis** to
bold/italic. The "no nesting of emphasis" rule of §3.2 does not
apply to underline.

### 3.4 Combination

Multiple emphasis spans can coexist in the same text, provided they are
disjoint:

```
*foo* and **bar**            ✓  disjoint italic + bold
*foo and **bar***            ✗  nesting not allowed
***foo*** plain ***bar***    ✓  two disjoint bold-italic spans
```

Underline is an orthogonal axis: it can coexist with bold and italic
in the same span:

```
**__foo__**                  ✓  bold + underline
*__foo__*                    ✓  italic + underline
***__foo__***                ✓  bold + italic + underline
__**foo**__                  ✓  free delimiter order
__*foo* and **bar**__        ✓  underline over a span with internal disjoint emphasis
```

An emphasis or underline span can coexist with a size
prefix: the prefix applies to the entire text span, the other
delimiters modify only the inner portion:

```
# Title with **bold** and __underline__ words
```

---

## 4. Escape

The character `\` (backslash) precedes a meta-character to make it
literal.

| Token | Escaped form  |
|-------|---------------|
| `*`   | `\*`          |
| `_`   | `\_`          |
| `#`   | `\#`          |
| `[`   | `\[`          |
| `]`   | `\]`          |
| `"`   | `\"`          |
| `\`   | `\\`          |

The escape `\_` is needed when one wants to insert a literal `__` in a
text that would otherwise be consumed by the markup (rare: single
`_` are already literal by default).

Examples:

```
M) | [The \*Real\* Book] |
c4"track \#3"
```

A `\` not followed by a meta-character is literal.

---

## 5. Default style per construct

The container `[…]` vs `"…"` decides **only** the presence of the box. The
default style (size, weight, italic) is a property of the **hosting
construct**.

| Construct                                | Default style                                  |
|------------------------------------------|------------------------------------------------|
| Marker `M)` `[NAME]`                     | bold, body size (role `body`, see §3.1)        |
| Marker `M)` `"…"` annotation             | plain, reduced size (role `reduced`)           |
| Textual end-decorator                    | plain, body size (role `body`)                 |
| Comment-label chord / group / row        | italic, reduced size (role `reduced`)          |
| Note annotation                          | plain, reduced size (role `reduced`)           |
| Dynamics `D)` annotation                 | plain, reduced size (role `reduced`)           |
| PLAY/FORM top/bottom label box           | plain, reduced size (role `reduced`)           |
| PLAY/FORM prose                          | plain, body size (role `body`)                 |

The **size role** decides how the prefixes `#`/`##`/`###` scale above the
default (see §3.1 table). Constructs with `role body` admit `###` to
go BELOW the default; those with `role reduced` do not (`###` = default).

User markup (§3) always overrides the default. For example in
comment-label `chord"*plain*"` it stays italic (the construct default) and
applies `*` as an additional visual override.

---

## 6. Parsing rules

### 6.1 Disambiguation of `[…]` by role

In neumaRk the delimiter `[…]` is shared among several constructs
(polychord, volta, end-decorator, comment-label, note annotation,
grace block, etc.). The disambiguation is **positional** and defined
in the specs of the individual constructs. Once the parser has
identified the role of the `[…]`, the content is interpreted according to
the rules of this document.

### 6.2 Single-line inside container

The containers `[…]` and `"…"` are **single-line**: they do not admit
newline characters. A `]` or `"` not closed within the end of the line is a
parsing error.

The prose of `PLAY)` / `FORM)` admits line continuation (see
related documents).

### 6.3 Empty containers

`[]` and `""` are **literals**: they are not interpreted as containers.

### 6.4 Reserved prefixes

In **note annotation**, if the first character after the opening of the
container is `$` followed by a reserved uppercase letter (`$F`, `$S`,
etc., see `neumaRk_notes_and_durations.md` §8), markup is
**disabled** on the entire annotation: the content is interpreted
as a structural directive (fingering, string number, etc.).

---

## 7. Edge cases

### 7.1 Markup in reference names

Inside `[NAME]` of references in `PLAY)` / `FORM)`, the NAME is
interpreted as text. The internal markup is applied in **display**
but removed before matching with the defined markers:

```
PLAY) [**Solo**] [A]
```

`[**Solo**]` looks for a marker named "Solo" and renders it in bold if
found. If the NAME contains unclosed or malformed markup, the
fallback is literal matching including the markup characters.

### 7.2 Spaces around emphasis and underline delimiters

Unlike standard Markdown, neumaRk **does not require** that the
delimiters (`*`, `__`) be "tight" with respect to the content: `* foo *`
is equivalent to `*foo*`, `__ foo __` is equivalent to `__foo__`. The
choice reduces common errors and keeps the markup more tolerant.

### 7.3 Mix of containers in constructs that admit both

Sections that admit both containers (`[…]` and `"…"`) may
use them freely at different points of the same document. The choice is
guided by the intended graphical meaning (with or without box).

```
M) | [Intro] | "freely" | [Verse 1] |
```

---

## 8. Summary

| Axis              | Values                       | Decides                               |
|-------------------|------------------------------|---------------------------------------|
| Container         | `[…]` / `"…"`                 | box / no-box                          |
| Construct         | marker, label, annotation, … | default size + weight + italic        |
| User markup       | `*…*`, `**…**`, `__…__`, `# …`, etc. | explicit override              |

The three axes are orthogonal. None of the three constrains the others.

---

This document defines the unified **text formatting system**
of neumaRk, applicable to all textual containers of the
language.


---

# Markers

## 1. What is a Marker

A _marker_ is a non-musical structural element that identifies a significant point in the flow of the song. Markers do not refer to a sounding element, have no musical duration of their own, and do not directly affect musical content (notes, chords, rhythms), but serve to:

- segment the song into logical sections;
- facilitate human reading and orientation;
- provide semantic anchors for rendering, navigation, and playback;
- support musical forms, repeats, and references.

Markers are part of the **musical datapack**, but belong to the domain of **structure**, not musical notation.

### Semantic scope

A _marker_ semantically belongs to a **measure**.

It identifies, labels, or qualifies a measure as a structural unit
of the song and is not tied to the musical flow or the execution order.

---

## 2. Markers line

Markers are contained in a **markers line**, which may be:

- explicitly declared with the line marker `M) `;
- implicitly deduced from the content of the line.

### 2.1 Position within the datapack

- The markers line, if present, is **the first line of the datapack**.
- It is **optional**.
- Only one markers line may appear per datapack.

Best practice: place the **measure decorators** (volta, segno, coda, etc.) in the markers line as well, in order to concentrate the formal structure in a single location.

---

## 3. Marker syntax

A marker is expressed in two container forms, which differ in their
**structural role** and in the presence of the graphic box:

- **`[<text>]`** — **section**: a structural unit of the song, with a box;
- **`"<text>"`** — **annotation**: descriptive text, without a box.

```
[Intro]            section (with box)
[A]                section
"freely"           annotation
"swing feel"       annotation
```

The marker admits the **text markup** defined in
`neumaRk_text_markup.md`. The default style is **bold, body size**, in
both forms.

### 3.1 Section vs annotation

The two containers have **different semantic value**:

| Form      | Type         | Structural value              | PLAY/FORM target | Closes collapsible scope |
|-----------|--------------|-------------------------------|------------------|--------------------------|
| `[…]`     | section      | yes (unit of the song)        | yes              | yes                      |
| `"…"`     | annotation   | no (descriptive text)         | no               | no                       |

A **section** identifies a recallable and referenceable structural
unit (Intro, Verse, Chorus, A, B, …). Sections are the
targets of `PLAY)` / `FORM)` (see `neumaRk_play_and_form.md` §3.1) and
delimit the scope of the collapsible sections (see §4).

An **annotation** is free text without structural value (e.g.
`"freely"`, `"swing feel"`, `"con feeling"`). Annotations are not
referenceable from `PLAY)` / `FORM)` and **do not close** the scope of a
collapsible section.

> **Normative note.** This distinction is a refinement of the
> 0.5 spec, where `[…]` and `"…"` were considered semantically
> equivalent. Existing documents are backward-compatible (the
> annotations `"…"` continue to exist as text); the only
> operational difference is the selective binding from PLAY/FORM and the
> behavior of `[? …]` (see §4).

### 3.2 Temporal anchoring

- A marker refers **to the start of the measure** in which it appears.
- If preceded by a barline and in the box form `[…]`, it **must be
  separated from it by at least one space**, to avoid ambiguity with the
  volta decorators.
- The `"…"` form does not collide with the volta decorators and may be
  adjacent to the barline; the space is nevertheless recommended for
  readability.

Valid example:

```
| [A]
| "freely"
```

Invalid example:

```
|[A]   // ambiguous: could be interpreted as a volta
```

---

## 4. Collapsible sections

A section may be declared **collapsible** (also called
*optional*) by prefixing `? ` (the character `?` followed by
**one space**) inside the marker:

```
[? Verse]
[? Solo 2]
[? Outro]
```

A collapsible section is a **UX property** of the marker: the user
can expand/collapse the section in the reading interface
(accordion). The expanded/collapsed state is a user preference, saved in
the user-index (Firestore `users/{uid}/song_view_state/{songId}`) and **not
in the NRK file**.

### 4.1 Scope of the collapsible section

The scope of `[? NAME]` extends from the marker's measure up to the
first of the following events:

- **the start of another section** `[…]` (of any name,
  collapsible or not, including the anonymous marker `[!]` of §4.2);
- **the end of the document**.

The **annotations** `"…"` interposed **do not close** the scope:
they nevertheless belong to the current collapsible section.

```
M) [? Verse] | … | "freely" | … | [Chorus] | …
   └─────── scope of Verse ─────┘
                                  └ Chorus opens a new scope
```

### 4.2 Anonymous marker `[!]` (implicit closure of an optional section)

When an optional section ends and there is no following marker
that closes it naturally (because "anonymous" flow follows, not
structured as a section), the special token `[!]` is used (square
brackets with a single `!`, no spaces).

`[!]` is semantically a marker for the **opening of an anonymous
non-optional section**: it adheres to the convention "marker = start-of-measure" (§3.2)
and the closure of the preceding scope is the natural side-effect of
rule §4.1.

```
M) [? Coda] | … | … | [!] | … |
   └── scope of Coda ─┘
                       └ non-collapsible, anonymous flow
```

Properties:

- **Not rendered** as a marker (no box, no label).
- **Not referenceable** from `PLAY)` / `FORM)`: it has no NAME. If used
  as a reference it is reference-broken (see `neumaRk_play_and_form.md`
  §7.3).
- **Admitted anywhere**: `[!]` does not require an open optional
  section. If there is no scope to close the token is redundant (warning
  **W146**, non-blocking).

### 4.3 No nesting

A `[? Inner]` internal to another `[? Outer]` **closes** the scope of
Outer and opens that of Inner, according to the general rule §4.1. There is
no mechanism for nested collapsible sections.

```
M) [? Outer] | … | [? Inner] | … |
   └ Outer ──┘   └─ Inner ─────…
```

### 4.4 Default state

When opening a song for the first time, the collapsible sections
are **expanded**. The user collapses them explicitly; the state is then
persistent in the user-index.

The `?` in the marker is clearly highlighted in the UI (chevron in the
margin, distinct title style) so that the presence of collapsible sections is
immediately recognizable, even when all are expanded.

### 4.5 References from PLAY/FORM

A `[? NAME]` section is referenced from `PLAY)` / `FORM)` using only the
**NAME**, without the `?` prefix:

```
M) [? Verse] | … | [Chorus] | …
PLAY) [Verse] [Chorus]
```

The `?` prefix is a UX property of the section, not part of the
structural name. The binding between `PLAY)` and `M)` is by text-equality on
the NAME, ignoring the `?` prefix.

### 4.6 Execution

The collapsed/expanded state is **UX-only**: the player executes a
collapsible section exactly like an ordinary section,
regardless of whether the user has collapsed or expanded it
in the view.

A collapsed section is not "skipped" by the player. To omit
a section from execution there are other mechanisms (versions,
an explicit `PLAY)` that excludes it).

### 4.7 Start-of-staff constraint

A collapsible section **must start and end at the start of a staff**
(= at the start of a system / datapack). Concretely:

- the marker `[? NAME]` must appear in the **first measure** of the
  system in which it appears;
- the closure of the scope (any other `[…]` or `[!]`) must in
  turn appear in the **first measure** of the system in which it appears;
- the scope also terminates at EOF (a valid case).

Rationale: the accordion UX compresses whole staves; a section that
starts or ends mid-staff would produce an ambiguous rendering (half a staff
would disappear, leaving a visual stub).

In case of violation:

- **W151** is emitted (warning, non-blocking);
- the section **is not collapsible on the UX side**: the user toggle is
  ignored on render (the section remains always expanded).

---

## 5. Identity relevance

The `~` prefix on a section marker declares it **identity-bearing**: it
flags its theme as the one that **characterizes** the song ("the part that
makes the piece recognizable"). It is a **structural and portable** property
of the composition — it travels with the file — not host data.

```
M) [Intro] | … |
M) [~ Theme] | … |          ← identity-bearing section of the song
M) [Coda] | … |
```

`~` is **not rendered** (no box, no extra label: the section is drawn like a
plain `[Theme]`) and is **preserved in round-trip** by the serializer.

> Identity relevance is a **musical annotation**, not a host label: it
> indicates *which* music characterizes the song. The marker is **agnostic
> to the analysis dimension**: the host may derive whatever it needs under
> any profile — melody, harmony, rhythm, harmonic rhythm, etc. (non-exhaustive
> list). The spec defines *which region* is identity-bearing; *what* is
> extracted from it and *on which dimension* is outside the language.

### 5.1 Scope of the identity region

The scope of `[~ NAME]` extends from the marker's measure to the **first** of
the following events:

- the start of a new section `[…]` **without** the `~` prefix;
- the end of the document.

A following section that **also** carries `~` does **not** close the region:
it **continues** it. Consecutive `~` sections therefore form a **single**
identity region; only a section without `~` closes it.

```
M) [~ A] | … | [~ B] | … | [C] | … | [~ D] | …
   └──── identity region 1 (A+B) ───┘        └ region 2 (D)
                              └ C not identity, closes region 1
```

The interposed **annotations** `"…"` do not close the scope (as in §4.1).

### 5.2 Multiple regions per song

**Multiple identity regions** are allowed within the same song (non-consecutive
`~` markers are distinct regions, see `[~ D]` above). How the host uses one or
more regions (e.g. which one to consider for which purpose) is not a matter of
language.

### 5.3 Default (no `~` marker)

In the absence of any `[~ …]` in the song, the identity-bearing region is
**implicitly** the stretch **from the start of the song to the first section
(exclusive)** (or to EOF if there are no sections). Songs that do not use the
marker therefore have a well-defined, host-independent identity region.

### 5.4 Anonymous marker `[~]`

`[~]` (square brackets with a single `~`, no spaces) is an **anonymous**
identity-bearing section: it behaves like the anonymous marker `[!]` (§4.2) —
it opens a non-optional section and closes the previous scope — but is
**flagged `~`**. It serves to mark "from here it is identity-bearing" when the
theme is not a named section. Conversely, a `[!]` (without `~`) following an
identity region **closes** it (it is a section without `~`, §5.1).

### 5.5 Composition with `?` (collapsible + identity)

A section can be **both** collapsible and identity-bearing. The two prefixes
are accepted in **free order** on input: `[?~ NAME]` and `[~? NAME]` are
**equivalent**. Being semantically identical, the serializer **normalizes**
them to the canonical form `[?~ NAME]` (as it already normalizes spacing and
other marker aspects).

```
M) [?~ Bridge] | … |
```

### 5.6 References from PLAY/FORM

As for `?` (§4.5), a `[~ NAME]` section is referenced from `PLAY)` / `FORM)`
using only the **NAME**, without the prefix. The binding is by text-equality on
the NAME, ignoring the `~` and `?` prefixes.

```
M) [~ Theme] | … |
PLAY) [Intro] [Theme] [Coda]
```

### 5.7 Anchoring

`[~ NAME]` / `[~]` follow the anchoring of sections (§3.2, §4.7): they appear at
the start of a measure; the scope boundaries (a section without `~`, or EOF)
fall at the start of a staff like any other section boundary.

---

## 6. Play directive on the `M)` line

The `M)` line admits, in addition to the textual markers `[…]` / `"…"`, also
**play directives** in the form `(=Style,Tempo)` to change the style
and/or the tempo of the song starting from a specific measure. See
`neumaRk_play_directive.md` for the full spec.

The play directive coexists freely with the textual markers in the
same measure. The disambiguation between the tokens is by **delimiters**:

| Token            | Type                                 |
|------------------|--------------------------------------|
| `[…]`            | section (structural marker)          |
| `[? …]`          | collapsible section (see §4)         |
| `[~ …]`          | identity-bearing section (§5)        |
| `[!]`            | anonymous non-optional section (§4.2)|
| `[~]`            | anonymous identity-bearing section (§5.4) |
| `"…"`            | annotation (descriptive text)        |
| `(=…)`           | play directive                       |

Example:

```
M) | [Intro] (=Rock,120bpm) | | | [A] (=swing,140bpm) |
```

---

## 7. Validity rules

A markers line is valid if it:

- contains only sections `[…]` / `[? …]` / `[~ …]`, anonymous markers `[!]`
  / `[~]`, annotations `"…"`, and play directives `(=…)`, separated by spaces
  and barlines;
- does not contain patterns reducible to notes or chords;
- respects the rules of separation from barlines.

In case of violation:

- the line **is not recognized as a markers line**;
- the parsing of the datapack continues according to the standard deduction
  rules.

### 7.1 Diagnostic codes

| Code | Severity | Description                                              |
|------|----------|----------------------------------------------------------|
| W146 | WARNING  | `[!]` redundant: no optional section to close            |
| W151 | WARNING  | Optional section not collapsible: `[? NAME]` or its closure not at start of staff (§4.7) |


---

# Flow, Measures, and Repeats

This document defines the **temporal semantics** of neumaRk: measures, barlines, decorators, repeats, and flow jumps.

The objective is to describe a **deterministic**, textual, and readable system, capable of representing complex musical structures without ambiguity.

---

## 1. Measure and barline

The **notes** and **chords** lines, as well as those of other types, contain barlines that delimit the measures.

### 1.1 Admitted barlines

The recognized barlines are:

```
|    ||    |.    .|    :|    |:
```

Rules:

- the closing barline of a measure must be preceded by a space
- the compound signs (`:|`, `|:`) do not admit internal spaces, **except** the compact label of the count-in repeat (`:xN|`, `:open|`, see §6.1)

---

## 2. Measure decorator

The **decorators** are symbols or textual constructs adjacent to a barline.

They modify the musical flow, the formal structure, or the rendering.

There are two classes of decorators:

- **BEGIN decorators** → act at the start of the measure
- **END decorators** → act at the end of the measure

Their position is semantically relevant.

### Decorators and barlines

A _decorator_ belongs semantically to a **barline**.

The decorators qualify the musical flow (repeats, jumps, coda,
end, etc.) and are always associated with a specific barline, not with a
measure in the structural sense.

---

## 3. BEGIN decorator (to the right of the barline)

### 3.1 Change of meter and key

A new meter and/or a new key may be indicated in parentheses:

```
|(3/4,Dm)
```

Rules:

- meter and key may appear in arbitrary order
- both are optional
- the meter may use the form with bracket in the numerator (e.g. `[3+2]/8`)

If present, these decorators **must come first**, immediately adjacent to the barline.

---

### 3.2 Volta (alternative ending)

A square bracket indicates a **volta**:

```
|[1.]
```

The volta:

- refers to the start of the measure
- may include arbitrary text

#### 3.2.1 Extension of the volta

The duration of the volta may be extended by adding `+n`:

```
|[1.]+4
```

In the absence of an extension, the volta closes **automatically** at the first repeat closing sign (`:|`) encountered within **4 measures** (typical case of `[1.]` endings).

If no `:|` appears in the following 4 measures, the volta does not close automatically and indicates an **exit** (explicit extension `+n` recommended in all non-standard cases).

---

### 3.3 Structure signs

Other admitted BEGIN decorators:

- `$` → segno
- `@` → coda

They may follow the meter/key change decorators.

---

## 4. END decorator (to the left of the barline)

The END decorators modify the flow **at the end of the measure**.

### 4.1 Flow jumps

The following constructs are admitted:

- `DC` → Da Capo
- `DCal@` → Da Capo al Coda
- `DCalFINE` → Da Capo al Fine
- `D$` → Dal Segno
- `D$al@` → Dal Segno al Coda
- `D$alFINE` → Dal Segno al Fine

---

### 4.2 Fine and Coda

- `FINE` → end of the piece
- `al@` → jump to the coda

---

### 4.3 Textual decorators

A textual decorator is expressed in two container forms,
**semantically equivalent**, that differ only in the presence
of the graphic box:

- **`[<text>]`** — form with box;
- **`"<text>"`** — form without box.

```
[D.S.]:|            textual decorator with box
"freely":|          textual decorator without box
[x4]                textual decorator with box
```

It is displayed at the top, at the right margin of the measure.

The decorator admits the **text markup** defined in
`neumaRk_text_markup.md`. The default style is **plain, body size**,
in both forms.

For the particular case of the number of executions of a repeat
(`[xN]:|`) or of an open repeat (`[open]:|`), the compact form
`:xN|` / `:open|` is also available (see §6.1), which is **interpreted by
the player** as an execution instruction.

---

## 5. Order and combination of decorators

Composition rules:

1. the BEGIN decorators always precede the content of the measure
2. the END decorators always follow the content of the measure
3. within each class, the order is semantically relevant
4. in case of conflict, the decorator closest to the barline prevails

---

## 6. Repeats

The repeats are indicated through the barlines:

- `|:` → start of repeat
- `:|` → end of repeat

The semantics of the repeats interacts with:

- voltas
- segni (`$`)
- DC / D$

The resolution of the flow must be **deterministic**.

### 6.1 Number of executions and open repeat

To indicate **how many times** to execute a repeat, or to mark it as **open** (number not specified, typical of jazz/pop-style codas), the sign `:|` admits a **compact label** between the two characters:

- `:xN|` (or equivalently `:Nx|`) with `N` an integer in `[2..99]` → execute the repeat `N` times
- `:open|` → open repeat (number of executions at the performer's discretion)

Examples:

```
|: a b c d | e f g a :x8|
|: a b c d | e f g a :8x|
|: a b c d | e f g a :open|
```

Rules:

- the token is atomic: no space between `:`, the label, and `|`
- `N` must have 1 or 2 digits; `:x1|` / `:1x|` and `:x100|` / `:100x|` (or beyond) are parsing errors
- `open` is **case-insensitive**: `:open|`, `:Open|`, `:OPEN|` are all accepted
- the label is rendered **above the barline, right-aligned** (same position as the textual decorator `[xN]` of §4.3), in the canonical form `xN` independently of the order used in the input

#### 6.1.1 Relation with the textual form `[xN]:|`

The compact form `:xN|` / `:open|` and the form with textual decorator
`[xN]:|` / `[open]:|` (§4.3) produce the **same graphic rendering**, but
have **different playback semantics**:

| Form                | Render             | Play                                       |
|---------------------|--------------------|--------------------------------------------|
| `:xN|`              | "xN" box above     | **executable** — the player executes N times  |
| `:open|`            | "open" box above   | **executable** — open repeat (UX prompt) |
| `[xN]:|`            | "xN" box above     | **decorative** — the player uses default (2x) |
| `[text]:|`          | "text" box above   | **decorative** — arbitrary text          |

The compact form `:xN|` is a **structured instruction** that the
player reads and executes; the form with textual decorator is **informative
text** for the human, and the player ignores it for the purposes of counting
the repeats (it follows the standard default, typically 2 executions).

Both remain valid. The compact form is recommended for the
count-in repeats where the number of executions must be
respected by playback; the form with textual decorator remains useful
for arbitrary labels other than `xN`/`open` (e.g. `[D.S.]`, `[fade]`)
or when the number of executions is purely informative.

---

## 7. Measure repeat

The symbol `%` indicates the **repeat of the content of the preceding measure(s)**. There are six forms, which distinguish the **graphic rendering** from the **explicit realization** of the content, for spans of 1, 2, or 4 measures:

| Token | Render | Span |
|-------|------|------|
| `%`   | similar glyph (`repeat1Bar`)        | 1 measure |
| `%!`  | visible copy of the content         | 1 measure |
| `%2`  | similar-2 glyph (`repeat2Bars`)     | 2 measures |
| `%!2` | visible copy of the content         | 2 measures |
| `%4`  | similar-4 glyph (`repeat4Bars`)     | 4 measures |
| `%!4` | visible copy of the content         | 4 measures |

The forms with `!` and without `!` are **musically equivalent**: they differ only in the engraving.

### 7.1 Syntactic rules

- the token is atomic: no whitespace between `%`, `!`, and the number
- 1 NRK cell = 1 measure: even the forms with span > 1 (`%N`/`%!N` for N>1) occupy a single measure per cell. **The token appears in each of the N consecutive measures of the run.**

  Examples (4/4):
  ```
  N) | a | b | %2  | %2  |
  N) | a | b | %!2 | %!2 |
  N) | a | b | c | d | %4 | %4 | %4 | %4 |
  N) | a | b | c | d | %!4 | %!4 | %!4 | %!4 |
  ```

- the token must be the **only content** of its measure (not mixable with notes/chords)
- admitted `N`: `{1, 2, 4}` (correspond to the standard SMuFL glyphs `repeat1Bar`, `repeat2Bars`, `repeat4Bars`). Other values (`%3`, `%5`, …) are parsing errors
- for the `%N` glyph tokens: the SMuFL glyph is drawn **only once** per run, anchored to the **central barline** of the run (N=2: barline between m1 and m2; N=4: barline between m2 and m3). The other measures of the run are musically part of the event but do not add graphic notation
- do not confuse with the note event repeat `!` of `neumaRk_notes_and_durations.md` §5: the lexer recognizes `%!` as a single token

### 7.2 Scope and resolution

The symbol applies to the **chord-row** and to the **notes-row**. The resolution is independent per row-type: a `%` in the chord-row inherits from the preceding chord-row; a `%` in the notes-row inherits from the preceding notes-row.

> **Classification of a line of only `%`.** Without an explicit marker, a line composed only of `%` (plus barlines and spaces) is classified according to `neumaRk_datapack.md §3.bis.5` **TB1bis**: at the head of the datapack and in the absence of a real chord-row it is a **chord-row** of repeats (it inherits the chords, also cross-datapack); after a real chord-row, or if it contains the rest-token `r`/`!`, it is a **notes-row**. To force the opposite reading use the marker (`C)` for chords, `N+`/`N)` for a notes staff).

For each measure of the run, the source is the measure **`i - N`** in the same row-type (simple offset). For `%2` repeated in a run (`m_a m_b → %2 %2`), the 1st measure `%2` has source `m_a`, the 2nd has source `m_b`. Same logic for N=4: each measure of the run of 4 copies from the corresponding offset-4 back.

The resolution **walks up the chain**: if the source `i - N` is itself a `%`/`%!`, it continues backwards using the `N` of the source measure encountered, until a "real" measure (non-repeat) is reached. This makes correct the idiomatic case of the run of `%` (N=1), in which each `%` repeats the preceding measure:

```
N) | a | % | % |     → a a a
```

The 1st `%` has source `a`; the 2nd `%` has as source the 1st `%`, so it walks back again by 1 up to `a`. In mixed cases the walk-up uses the offset of the source each time (e.g. `| a | b | %2 | %2 | % |`: the last `%` walks up to the 2nd `%2`, which has source `b` → the measure equals `b`). The walk-up limit is 32 steps; beyond that, or if no valid source measure exists, the measure is flagged with **E300** (see §7.1 and the rule below).

`%`/`%!` are not admitted as the first measure of the piece (and in general if there are no N preceding measures in the same row-type).

### 7.3 Behavior per layer

When the source content is inherited:

- **notes, chords, rhythm, durations** → copied
- **articulations** (staccato, accent, tenuto, …) → copied (they are attributes of the note)
- **point dynamics** (`p`, `f`, `mf`, …) → **not** re-emitted: the dynamic in force before the source measure continues to apply by standard notational inheritance
- **spanning dynamics** (cresc., decresc., hairpin) → truncated at the boundary of the source measure
- **lyrics** → **not** copied

The user may **add** new lyrics or new dynamics aligned to a `%`/`%!` measure without conflicting with the symbol (they are parallel layers).

### 7.4 Edge cases

- **Tie out from the source**: in the `%!` case the copy keeps the initial value tie if the `%!` measure is not the last of the chain; the tie propagates to the successor. For `%` the rule is the same, applied to the realized content.
- **Change of key or meter in the source**: it is structural and is not re-applied in the `%`/`%!` measure.
- **Autofill source**: if the source measure is a rest-only autofill, the `%` produces a measure of rests (intentional behavior, not a warning).

---

## 8. Markers lines and best practice

The barlines (simple and compound — `|`, `||`, `|.`, `.|`, `:|`, `|:`) and the measure decorators can be found in all the musical lines (markers, chords, articulations, notes, dynamics, lyrics).

The only exception is the **Format** line, which admits neither barlines nor decorators.

The markers line, if present, is the most suitable for containing the flow decorators (DC, D$, coda, etc.).

Since the markers are indicated in square brackets and refer to the start of the measure, if they are preceded by a barline (with eventual modifiers) they must be separated from it by a space to differentiate them from a volta-decorator.

---

## 9. Principles of flow resolution

- the flow is resolved as a linear sequence of measures
- the jumps do not introduce temporal ambiguities
- each measure has a unique temporal position

---

This document defines the **musical navigation logic** of neumaRk.


---

# PLAY) and FORM)

This document defines the syntax and semantics of the two neumaRk
sections dedicated to the **form of the song**:

- **`PLAY)`** — execution sub-program, **inline** between datapacks,
  read by the player in document order;
- **`FORM)`** — overview description of the form, **only one** per
  document, placed at the end, for human use and indexing.

The two sections share the same **section box grammar** and the same
postfix vocabulary, but differ in position, multiplicity and semantic
role (imperative vs descriptive).

---

## 1. Definition

### 1.1 PLAY)

A `PLAY)` section contains an **execution sub-program**: a sequence of
section boxes (with optional repeats, dynamics, fermatas, free prose)
that the player executes **at the moment it encounters it** in the
document.

Multiple `PLAY)` sections can coexist in the same document; they are
read **top to bottom**, in the order in which they appear.

### 1.2 FORM)

A `FORM)` section contains an **overview description of the form** of the
song (e.g. "AABA with coda", or extended prose detailing articulation
and dynamics of the sections). At most **one** `FORM)` per document
exists, placed **at the end**.

`FORM)` is not executable by the player: it has descriptive value, for
the human reader and for indexing/search.

> In a **playlist**, an item may declare its own `form` that
> **replaces** the song's `FORM)` for that occurrence ("tonight's form
> is this"). It is a descriptive overlay at the setlist level, not
> executed; `PLAY)`, being positional, cannot be expressed at that
> level. See `neumaRk_collections.md` §8.

### 1.3 Semantic distinction

| Aspect       | `PLAY)`                            | `FORM)`                           |
|--------------|------------------------------------|-----------------------------------|
| Role         | imperative ("execute this")         | descriptive ("here is the form")  |
| Multiplicity | multiple, inline                   | at most one, at the end           |
| Player       | executes                           | ignores                           |
| Use          | playback, execution sketch         | summary, search, teaching         |

The choice between "the player executes PLAY" and "the player follows
the natural flow of datapacks" **is not a property of the document**: it
is a **user preference** saved in the user-index (UI toggle). The
document contains both forms of information; the user decides what to
display/execute.

---

## 2. Structural position

### 2.1 PLAY)

- It is a **section line**, marked by `PLAY)` as the first token.
- It appears **between datapacks**, never inside a datapack.
- It is **non-recursive by design**: a `PLAY)` cannot appear as an
  internal line of another `PLAY)`. Static guarantee of the parser.
- A `PLAY)` may span **multiple lines** of the document: the newline is
  whitespace inside the section (see §6).

The `PLAY)` section ends at the first of the following events:

- start of the next datapack (a line that opens with a musical marker
  `M)`, `C)`, `N)`, `A)`, `D)`, `L)`, `F)`);
- start of another section (`PLAY)`, `FORM)`);
- end of document.

### 2.2 FORM)

- It is a **section line**, marked by `FORM)` as the first token.
- It appears **at the end of the document**, after the last datapack.
- It is **unique** per document. Multiple `FORM)` produce warning
  **W140**.
- A `FORM)` may span multiple lines (newline = whitespace).

`FORM)` ends only at the end of the document.

---

## 3. Section box grammar

In both `PLAY)` and `FORM)`, the atomic unit is the **section box**:

```
SECTION_BOX  := TOP_LABEL? '[' NAME ('|' BARS)? ']' POSTFIX*
TOP_LABEL    := '"text"'           // adjacent, no space
POSTFIX      := REPEAT | DYNAMIC | HAIRPIN | KEYWORD | BOTTOM_LABEL
                                    // all adjacent to the previous one
```

All box tokens are **adjacent**: no space between top-label, square
brackets, postfix.

### 3.1 NAME

The `NAME` inside `[…]` is the **name of a section** defined by an
`M)` line of the document (`neumaRk_markers.md` §3). The matching is by
**text-equality** on the section content (after stripping the markup,
see §3.2 of `neumaRk_text_markup.md` §7.1).

The binding is **selective**: only the **sections** `[…]` of M) are
considered (including the collapsible `[? NAME]`, with the `?` prefix
ignored in matching). The **annotations** `"…"` of M) are not
referenceable from `PLAY)` / `FORM)` (see
`neumaRk_markers.md` §3.1).

Examples:

```
[A]       references a section [A] in M)
[Intro]   references [Intro] or [? Intro] (prefix ? ignored)
[Solo 1]  multi-word, references [Solo 1] or [? Solo 1]
```

A `"freely"` in M) is **not** a valid target: `[freely]` in PLAY/FORM
would be a broken reference (see §7.3).

If the NAME does not correspond to any marker defined in the document,
the box is **reference broken**: it is rendered as non-clickable text,
**not executed**, and **generates no error or warning** (see §7.3).

### 3.2 Duration in measures `[NAME|BARS]`

Optional: an internal `|` and a number of bars.

```
[A|8]     A for 8 measures (informative)
[B|4]     B for 4 measures
[A]       A with no declared duration
```

`BARS` is a **positive integer** (1–999). Decimals, zero or negatives
produce warning **W141**.

The duration in `[NAME|BARS]` has **purely informative** value: it is a
graphical hint for the reader. It is not compared with the real extent
of the section marked `M)`; it is the writer's responsibility to
maintain consistency. No warning or error in case of discrepancy.

Durations are allowed **only** in `PLAY)` / `FORM)`. A marker in
`M)` does not allow `|N` (see `neumaRk_markers.md`).

### 3.3 Top and bottom labels

Top label: container `"…"` **adjacent before** `[`.
Bottom label: container `"…"` **adjacent after** the closing square
bracket (may appear as a postfix in any order, see §3.4).

```
"Tema"[A|8]                  top only
[A|8]"Variazione"            bottom only
"Tema"[A|8]"con feeling"     top + bottom
```

Labels allow **only** the container `"…"` (without box). The form
`[…]` collides grammatically with the section box and is not allowed as
a label.

Labels are subject to the **unified markup** of
`neumaRk_text_markup.md`. Default style: **plain, reduced size**.

### 3.4 Postfix

They are all **adjacent** to the preceding token (no spaces). The order
among postfixes is **free**: the parser identifies each postfix by its
form. Plurality is allowed only for the bottom label (one per box) and
for keywords (multiple distinct keywords possible).

#### 3.4.1 Repeat count

`xN` with `N` in 2–99 indicates the number of executions:

```
[A|8]x2       execute A twice (×2)
[A|8]x4       execute A four times
```

`x1` or `x0` or `xN` with `N > 99` produces warning **W142**.

#### 3.4.2 Dynamic

Punctual dynamic from the `D)` vocabulary (see `neumaRk_dynamics.md` §3.1):

```
[A|8]ff       section A at fortissimo
[B|4]p        section B at piano
```

Applies to the **entire duration of the section**.

#### 3.4.3 Hairpin

`<` or `>` adjacent open a hairpin **only within the opening box**: it
closes at the next adjacent dynamic, also within the same postfix-stack.

```
[A|8]<ff      cresc. up to ff at the end of the section
[B|4]>p       decresc. down to p
```

Hairpin **not cross-box**: `[A|8]< [B|4]ff` opens a hairpin that finds
no closure in box A and is closed implicitly at the end of the box. No
error, the render decides the representation.

#### 3.4.4 Keyword

`&keyword` family, case-insensitive, prefix for future extensions.

| Keyword       | Effect                                                 |
|---------------|--------------------------------------------------------|
| `&fermata`    | fermata on the final beat of the section               |
| `&caesura`    | caesura after the section                              |
| `&breath`     | breath after the section                               |
| `&GP`         | grand pause after the section                          |
| `&niente`     | "al niente" dynamic (decresc. down to silence)         |

Keywords are **reserved**: unknown keywords produce error **W143**. The
list is extensible in future versions of the spec.

#### 3.4.5 Bottom label

Container `"…"` adjacent, see §3.3.

### 3.5 Examples of complete boxes

```
[A]                            minimal reference
[A|8]                          A for 8 measures
"Tema"[A|8]                    A with top label
[A|8]x2&fermata                A repeated 2× with final fermata
"Tema"[A|8]ff<>p"crescendo"x2  complex combination
[FREE IMPRO!]                  reference broken (no marker of the same name)
```

---

## 4. Special tokens allowed in PLAY/FORM

In addition to section boxes, the following are allowed:

| Token       | Effect                                                  |
|-------------|---------------------------------------------------------|
| `$`         | segno (musical sign, target of D.S.)                    |
| `@`         | coda (target of D.C. al Coda)                           |
| `&fermata`  | stand-alone fermata (outside a box)                     |

These tokens keep the same semantics as the inline decorators of the
same name in the musical lines (see `neumaRk_flow_and_repeats.md`).

---

## 5. Free prose

Everything that is not a structural token (box, `&keyword`, `$`, `@`) is
**free prose** in `neumaRk_text_markup.md` markup mode.

```
PLAY) [Intro] then go to [A|8] twice [A|8]x2 finally [Outro]
```

In this example "then go to", "twice", "finally" are free prose
interpolated between boxes. They are rendered as descriptive text in the
PLAY display (e.g. in a separate band or next to the box).

The **player ignores** the free prose in `PLAY)`: it executes only the
boxes and the structural tokens. Free prose is exclusively informative
value for the reader.

In `FORM)`, the entire content is descriptive prose with section boxes
interpolated: the player executes nothing of `FORM)` in any case.

---

## 6. Whitespace and continuation

### 6.1 Newline = whitespace, blank line = terminator

Inside `PLAY)` and `FORM)`, a **single newline** has the same value as a
space: the section may span as many lines as the user prefers, simply
continuing (optionally with indentation) on the next line.

```
PLAY) [Intro]
      [A|8]x4
      [B|8]
      [A|8]
      [Outro]&fermata
```

is equivalent to:

```
PLAY) [Intro] [A|8]x4 [B|8] [A|8] [Outro]&fermata
```

A **blank line**, on the other hand, **closes** the section,
consistently with the convention of the rest of the NRK language where a
blank line separates datapacks. What follows is therefore interpreted
outside the `PLAY)`:

```
PLAY) [Intro]
      [A|8]

C7
a
```

The three lines `C7` / `a` form a new independent datapack; the `PLAY)`
section closed after `[A|8]`.

### 6.2 Explicit continuation

No continuation character is required. The section ends at the first of
the following events (see also §2.1 / §2.2):

- next datapack prefix (`M)/C)/N)/A)/D)/L)/F)`);
- new global section (`PLAY)`, `FORM)`, `%%…`);
- **blank line**;
- end of document.

---

## 7. Player semantics

### 7.1 Base model

Without any `PLAY)` in the document, the player executes the datapacks in
document order, applying the standard decorators (voltas, repeats, D.S.,
D.C., coda) described in `neumaRk_flow_and_repeats.md`.

### 7.2 With `PLAY)`

When the player encounters a `PLAY)` section, it executes the
sub-program contained in it **instead of** the natural flow of datapacks
at that point. After completing the `PLAY)`, it continues from the
datapack immediately following in the document.

Multiple consecutive `PLAY)` are read in order: the player executes each
in turn. Datapacks interposed between one `PLAY)` and another are
**ignored** from the executed flow, if referenced by section boxes
inside the `PLAY)` (datapacks are nonetheless tabulated by marker name;
they serve as the "definition" of the sections, not as a linear flow).

### 7.3 Reference broken

A box `[NAME]` whose `NAME` does not correspond to any `M)` marker of the
document is **reference broken**:

- it is rendered as non-clickable text (visible, marked as unresolvable);
- it is **not executed** by the player;
- it **generates no warning or error**.

This allows writing PLAY/FORM as a sketch or informal annotation without
constraints on consistency with the document's markers.

### 7.4 Execution of a box

The execution of a box `[A|8]ff<x2&fermata` consists of:

1. jump to the first datapack whose `M)` line contains the marker `A`;
2. application of the dynamic `ff` as the section's initial dynamic;
3. execution of all the datapacks of section `A` (up to the next marker
   or end of document), with hairpin `<` if present;
4. repetition N times (for `xN`);
5. final fermata (for `&fermata`).

The duration `|8` does not affect the execution: the actual extent is
given by the document's datapacks.

---

## 8. Render

### 8.1 PLAY)

`PLAY)` sections are rendered as a **compact band** above or below the
score, with the section boxes drawn as **rectangles with NAME and
duration** (if present). The labels, dynamics, hairpins and keywords are
rendered next to the box according to musical typographic conventions.

Reference broken boxes are rendered with a distinct style (e.g. italic
text in light gray) to signal unresolvability without hindering reading.

### 8.2 FORM)

`FORM)` sections are rendered as a **descriptive block** at the foot of
the document, with Markdown prose interpolated with section boxes. The
style is less emphatic than `PLAY)`: body text, boxes with a thin border.

### 8.3 Markup

All texts (top/bottom labels, free prose) support the unified markup of
`neumaRk_text_markup.md` §3. The default style is the one indicated in
`neumaRk_text_markup.md` §5 (labels: reduced plain; PLAY/FORM prose:
plain body).

---

## 9. Diagnostics

### 9.1 Diagnostic codes

| Code   | Description                                                                |
|--------|----------------------------------------------------------------------------|
| W140   | More than one `FORM)` section in the document                              |
| W141   | Invalid `|BARS` duration (integer 1–999 expected)                          |
| W142   | Repeat count `xN` out of range (2–99 expected)                             |
| W143   | Keyword `&xxx` not reserved                                                |
| W145   | `FORM)` not at the end of the document (datapacks following `FORM)`)       |

> A nested `PLAY)` (inside another `PLAY)` or inside a datapack) is
> **structurally prevented** (§3, non-recursive by design): the parser
> never produces it and **emits no diagnostic**. The code `W144` is used
> by the parser for the malformed `A)` slur (see
> `neumaRk_articulations.md`).

### 9.2 Non-errors

The following are not errors (see §3.1, §3.2):

- box `[NAME]` with NAME not traceable to any marker (reference broken);
- discrepancy between the declared `|N` duration and the real number of
  measures of the section;
- hairpin opened without closure within the end of the box;
- free prose with arbitrary characters (as long as it does not coincide
  with structural patterns).

---

## 10. Examples

### 10.1 Minimal PLAY

```
M) [Intro]
… Intro datapack …

M) [A]
… A datapack …

M) [B]
… B datapack …

PLAY) [Intro] [A|8]x2 [B|8] [A|8]
```

The player executes: Intro → A → A → B → A.

### 10.2 PLAY with dynamics and keywords

```
PLAY) [Intro]p [A|8]<ff [B|4]x2 [A|8]>pp&fermata
```

- Intro at piano.
- A with crescendo up to ff over 8 measures.
- B repeated 2 times (maintains ff).
- A with decresc. down to pp, final fermata.

### 10.3 PLAY with free prose

```
PLAY) Start with [Intro] freely.
      Then [A|8] twice, then [B|8].
      Optional [C|4] if vibe is right.
      End on [Outro] &fermata.
```

Interpolated prose serves the reader; the player executes only the
boxes: Intro → A → A → B → C → Outro+fermata.

### 10.4 Descriptive FORM

```
M) [Intro]
…

M) [A]
…

M) [B]
…

FORM) Standard AABA jazz: [Intro|4] sets the mood, then
      [A|8] is the main theme, [A|8] repeats with melodic
      variation, [B|8] is the bridge (modulating to IV), and
      a final [A|8] resolves to a [Coda|4] tag.
```

`FORM)` describes the form; the player ignores it (execution follows the
document flow or any separate `PLAY)`).

### 10.5 Reference broken (informal sketch)

```
PLAY) [Intro] [FREE IMPRO! whatever feels right] [A|8] [Outro]
```

`[FREE IMPRO! whatever feels right]` is not a defined marker: it is
rendered as descriptive text (unresolvable) and skipped by the player.
Execution: Intro → A → Outro.

### 10.6 Multiple PLAY in sequence

```
M) [A]
…

M) [B]
…

PLAY) [A|8] [B|8]

M) [C]
…

PLAY) [C|8]x3 &fermata
```

The player executes: A → B (first PLAY), then C → C → C with a fermata
(second PLAY). The datapack `[C]` defines the section referenced by the
second PLAY but is not executed linearly by the document flow (it is
already covered by the second PLAY).

### 10.7 Toggle player vs natural flow

The same document can be:

- **read as PLAY**: the player follows the `PLAY)` section(s) and
  ignores the linear flow of datapacks;
- **read as flow**: the player ignores the `PLAY)` sections and follows
  the datapacks in document order.

The choice is a user preference (user-index), not a property of the
document.

---

## 11. Summary

| Concept                | Syntax                                            | Section |
|------------------------|---------------------------------------------------|---------|
| PLAY section           | `PLAY) …`                                         | §1.1    |
| FORM section           | `FORM) …`                                         | §1.2    |
| Section box            | `"top"?[NAME(|BARS)?]POSTFIX*`                    | §3      |
| Top label              | `"text"` adjacent before `[`                      | §3.3    |
| Bottom label           | `"text"` adjacent as postfix                      | §3.3    |
| Repeat count           | `xN` (N 2–99)                                     | §3.4.1  |
| Dynamic                | `p`/`mp`/`mf`/`f`/`ff`/`sf`/`sfz` postfix         | §3.4.2  |
| Hairpin                | `<` / `>` postfix (no cross-box)                  | §3.4.3  |
| Keyword                | `&fermata`/`&caesura`/`&breath`/`&GP`/`&niente`   | §3.4.4  |
| Segno / coda           | `$` / `@`                                         | §4      |
| Free prose             | everything that is not a structural token         | §5      |
| Whitespace             | newline = space                                   | §6      |
| Reference broken       | `[NAME]` without marker of the same name, not executed | §7.3    |
| Informative duration   | `|BARS` graphical only, no checking               | §3.2    |
| Player/flow toggle     | user preference                                   | §1.3    |

---

This document defines `PLAY)` and `FORM)` as the two neumaRk sections
dedicated to the **form of the song**, completing the language's
structural vocabulary together with `M)` markers, `D)` annotation and
the play directive.


---

# Play directive

This document defines the syntax and semantics of the **play
directive**: a mechanism for locally changing a song's **style** and
**tempo**, taking effect from a specific measure and remaining in force
until a new directive.

The play directive addresses the need for lead sheets with sections at
different tempos or grooves (e.g. "vamp till cue" slowing down,
"double-time" over a solo, a switch from swing to latin midway through
the song) without resorting to separate songs.

---

## 1. Definition

A play directive is a **token** of the `M)` (Markers) line that
declares, locally, one or both of the following elements:

- a **style** (textual description of the musical character);
- a **tempo**, expressed as an explicit BPM or as a metric modulation
  (metric relationship between two NRK figures).

The play directive **is not a barline decorator**: it does not attach to
the `|` sign and does not belong to the family of measure decorators
(`[1.]` volta, `(3/4,Dm)` meter/key change). It is an autonomous token
that coexists with textual markers in the `M)` line.

---

## 2. Syntax

### 2.1 General form

Two alternative forms:

```
(=[Style][,Tempo])         with prefix `=` (Style/BPM/combined)
(<figure>=<figure>)        pure metric modulation (no prefix)
```

Inside the parentheses:

- The **prefix `=`** opens a directive with Style and/or Tempo slots
  (BPM or metric modulation), distinguishing it from a meter or key
  change `(3/4,Dm)`.
- A **metric-modulation-only** directive (e.g. `(4=4.)`) is written
  **without the prefix `=`**: the internal `=` between two NRK figures
  is already self-disambiguating with respect to the other tokens in
  parentheses.

When the prefix `=` is present and both Style and Tempo are declared,
the order is **fixed**: Style first, Tempo after, separated by a comma.

### 2.2 _Style_ slot

Free text describing the musical character (e.g. `Rock`,
`Fast swing`, `rock ballad`, `bossa`, `funk`). The same textual rules as
the `HS) Style` slot of the header apply
(`neumaRk_header.md` §11.2):

- free multi-word text, internal spaces allowed;
- **internal commas allowed** (e.g. `Fast, dirty swing`): the parser
  reconstructs the Style using the "parse from end" rule described below;
- no capitalization constraint (rendering preserves the spelling);
- it must not collide with patterns interpretable as `Tempo` (see §2.3
  and §3.2).

#### 2.2.1 Style/Tempo disambiguation ("parse from end")

When the directive contains a comma, the parser looks for **the last**
comma and tries to interpret what follows as a Tempo (BPM or metric
modulation). If the match succeeds → split there (Style = everything to
the left, Tempo = everything to the right). If it fails, the whole body
is treated as a single slot (Style if the user did not attempt a Tempo,
or Tempo-only if there are no commas and the body is a valid Tempo).

Practical consequences:

| Body                              | Style                | Tempo  |
|-----------------------------------|----------------------|--------|
| `=Rock,120bpm`                    | `Rock`               | 120bpm |
| `=Fast, dirty swing, 180bpm`      | `Fast, dirty swing`  | 180bpm |
| `=swing, 4=4.`                    | `swing`              | 4=4.   |
| `=foo, bar` (no trailing Tempo)   | `foo, bar`           | —      |
| `=120bpm` (no comma, is Tempo)    | —                    | 120bpm |

### 2.3 _Tempo_ slot

Two alternative, mutually exclusive forms:

#### 2.3.1 Explicit BPM

```
Nbpm
```

where `N` is a **2- or 3-digit integer** (range 10–999), immediately
followed by the `bpm` suffix (case-insensitive: `bpm`, `BPM`, `Bpm` all
allowed). Examples:

```
60bpm     120bpm     200bpm     90BPM
```

An out-of-bounds range (`5bpm`, `1000bpm`) produces warning **W136**.
Decimals (`120.5bpm`) are not allowed (parsing error).

#### 2.3.2 Metric modulation

```
<previous-figure>=<new-figure>
```

where each side is an **NRK figure** (`1`, `2`, `4`, `8`, `16`, `32`,
with dotted `.` and tuplet `t` allowed). Standard convention (Grove,
Carter): the value on the **left** is a figure in the **previous tempo**,
the value on the **right** is a figure in the **new tempo**; the two
figures have the same physical duration. Examples:

```
4=2     ♩ = 𝅗𝅥    (the quarter note of the previous tempo equals a new half note → double-time)
4=4.    ♩ = ♩.   (the previous quarter equals a new dotted quarter → speeds up)
2=4     𝅗𝅥 = ♩    (the previous half note equals a new quarter → half-time)
4.=4    ♩. = ♩   (the previous dotted quarter equals a new quarter → slows down)
8t=8    ♪₃ = ♪   (the previous triplet eighth equals a new eighth → speeds up)
```

Metric modulation is **executable**: the player recomputes the effective
BPM from the metric relationship applied to the current `currentBPM`
(formula in §5.2). Invalid figures (e.g. `5=4`, `4=k`) produce warning
**W137**.

### 2.4 Syntactic examples

```
(=Rock,120bpm)                 style + tempo
(=swing,4=4.)                  style + metric modulation
(=fast swing)                  style only (multi-word)
(=Fast, dirty swing, 180bpm)   style with internal commas + tempo
(=foo, bar)                    style only with comma (no trailing Tempo)
(=120bpm)                      BPM only
(8=4)                          metric modulation only (NO prefix `=`)
```

Invalid forms:

```
(=)                        W134 — empty directive
(=120bpm,Rock)             W135 — inverted slot order
(=5bpm)                    W136 — BPM out of range
(4=q)                      W137 — invalid NRK figure
```

---

## 3. Structural position

### 3.1 Only in the `M)` line

A play directive may appear **exclusively** in a Markers line
(`M)`, explicit or deduced according to
`neumaRk_markers.md` §2). Its presence in any other musical line
(`C)`, `N)`, `A)`, `D)`, `L)`, `F)`) produces warning **W138**.

### 3.2 Co-location with textual markers

A play directive coexists **freely** with textual markers
(`[Mark]`, `"freely"`) in the same measure of the `M)` line. The
disambiguation is by **delimiters**:

| Token            | Type                                    |
|------------------|-----------------------------------------|
| `[…]` / `"…"`    | textual marker                          |
| `(=…)`           | play directive (Style/BPM/combined)     |
| `(fig=fig)`      | play directive (pure metric modulation) |
| `(…)` other      | barline decorator (meter/key change) — not in `M)` |

Example:

```
M) | [A] (=Rock,120bpm) |
```

Measure 1 contains both the marker `[A]` and the play directive that
sets Rock 120 BPM from the same measure onward.

The order between textual markers and play directives is **free** in the
same measure: the parser identifies tokens by delimiters.

### 3.3 Temporal anchoring

A play directive applies from **beat 1 of the measure of appearance**,
and remains in force until a new play directive (see §4).

Mid-bar changes are not allowed: the horizontal position of the token in
the `M)` line does not alter the point of application, which is always
the beginning of the measure.

---

## 4. Persistence and context

### 4.1 `currentStyle` / `currentBPM` state machine

The song's persistent musical context (`neumaRk_specification.md`
§2.1) includes two **cross-datapack** variables:

- `currentStyle` — initialized by `HS) Style` of the header;
- `currentBPM` — initialized by `HB) BPM` of the header.

Each play directive **updates** one or both variables, starting from the
measure of appearance. The variables then remain in force until a new
play directive, **crossing datapack boundaries**.

### 4.2 Single-slot directives

A directive that declares a single slot **updates only that variable**,
leaving the other unchanged:

```
M) | (=Rock,120bpm) | | (=fast swing) | (2=4) |
```

- Measure 1: `currentStyle ← Rock`, `currentBPM ← 120`.
- Measure 3: `currentStyle ← fast swing`, `currentBPM` stays 120.
- Measure 4: `currentBPM ← currentBPM × (2/4) = 60` (metric modulation),
  `currentStyle` stays "fast swing".

### 4.3 No explicit reset

There is no special token to "return to the header values". To restore
the initial style/BPM, you redeclare it explicitly:

```
HS) swing
HB) 140

…
M) | (=Rock,80bpm) | … | (=swing,140bpm) |    ← explicit restore
```

This choice keeps the spec orthogonal: every directive is a positive
action, there is no hidden "turn-off" semantics.

---

## 5. Player semantics

### 5.1 Executable

Play directives are **executable instructions** for the runtime player:

- a change of `currentBPM` (explicit or via metric modulation) alters
  the execution speed immediately;
- a change of `currentStyle` signals to the accompaniment engine to
  change groove (Rock → Bossa → Swing produces different patterns of
  drums, bass, accompaniment guitar).

The actual `style → groove` mapping is the player's responsibility and
is not defined by this specification. Styles unknown to the player are
treated as a fallback to the default groove, without error.

### 5.2 Metric modulation: BPM calculation

Convention (standard musical, see Grove Music Online and Elliott
Carter): in a metric modulation `S = D` the value on the **left** is a
figure in the **previous** tempo, the value on the **right** is a figure
in the **new** tempo. The two figures have the **same physical
duration**.

From this equivalence we derive:

```
dur(S) × (60 / oldBPM) = dur(D) × (60 / newBPM)
⟹ newBPM = oldBPM × dur(D) / dur(S)
```

where `dur(F)` is the duration of NRK figure `F` in unit beats
(quarter = 1, whole = 4, half = 2, eighth = 0.5; dotted = 1.5×;
tuplet `t` = 2/3×).

Examples (assuming `currentBPM = 120`):

| Modulation | newBPM      | Musical effect                     |
|------------|-------------|------------------------------------|
| `4=2`      | 240         | double-time (old ♩ → new 𝅗𝅥)       |
| `4=4.`     | 180         | speeds up (old ♩ → new ♩.)         |
| `8t=8`     | 180         | speeds up (old ♪₃ → new ♪)         |
| `2=4`      | 60          | half-time (old 𝅗𝅥 → new ♩)         |
| `4.=4`     | 80          | slows down (old ♩. → new ♩)        |

---

## 6. Render

### 6.1 Marker band

All play directives are rendered in the **same marker band** (above the
staff), horizontally aligned to beat 1 of the measure of appearance.

### 6.2 Style

The style is rendered as **italic text**, body size. When co-located
with a textual marker in the same measure, the renderer applies a
vertical offset to avoid overlap, keeping both visible.

### 6.3 Explicit BPM tempo

`Nbpm` is rendered in **traditional notation**:

```
♩ = N
```

where the beat figure is derived from the denominator of the current
meter (4/4 → ♩, 6/8 → ♪., 3/2 → 𝅗𝅥, etc.). In the absence of an
identifiable meter, default `♩`.

### 6.4 Metric modulation

`figure₁=figure₂` is rendered in traditional notation as:

```
glyph(figure₁) = glyph(figure₂)
```

where `glyph(F)` is the black/white/open notehead of figure `F`, with a
dot if dotted, with `³` (or equivalent) if tuplet.

Examples:

```
4=4.    →   ♩ = ♩.
8=4     →   ♪ = ♩
8t=8    →   ♪³ = ♪
```

### 6.5 Combined Style + Tempo

When a directive contains both slots, the render presents **style above
the tempo** in two vertical lines, or on the same line separated by a
space. The choice is the renderer's.

---

## 7. Diagnostics

### 7.1 Diagnostic codes

| Code   | Description                                                              |
|--------|--------------------------------------------------------------------------|
| W134   | Empty directive `(=)`: no slot declared                                  |
| W135   | Inverted slot order: tempo before style                                  |
| W136   | BPM out of range (integer 10–999 expected)                               |
| W137   | Invalid NRK figure in metric modulation                                  |
| W138   | Play directive in a line other than `M)`                                 |

### 7.2 Unknown style

A style not recognized by the player (e.g. `(=mood music)`) **is not an
error**: it is respected as descriptive text and ignored by the
accompaniment engine (fallback to the default groove).

### 7.3 BPM = 0 or negative

Excluded from the range; produces **W136**.

### 7.4 Redundant directives

A directive that re-asserts exactly the current values (e.g.
`(=Rock,120bpm)` when `currentStyle="Rock"` and `currentBPM=120`) is
allowed, generating no warning. The player applies it as a no-op.

---

## 8. Examples

### 8.1 Tempo change midway through the song

```
HS) swing
HB) 140

…
M) | [Solo] | | | (=200bpm) | | | | |
```

A solo that starts at 140 BPM; from measure 4 onward it speeds up to
200 BPM.

### 8.2 Combined style + tempo change

```
M) | [Intro] (=Rock,120bpm) | | | [A] | | (=swing,160bpm) | |
```

- Measure 1: marker `[Intro]` + setup Rock 120 BPM.
- Measure 4: marker `[A]` (style and tempo unchanged).
- Measure 6: switch to swing 160 BPM.

### 8.3 Metric modulation

```
M) | (=swing,120bpm) | | | (2=4) | | | | (4=2) | | |
```

- Measure 1: swing at 120 BPM.
- Measure 4: half-time (currentBPM = 60).
- Measure 8: double-time relative to the previous (currentBPM = 120,
  back to the initial value).

### 8.4 Multi-word style

```
M) | (=Fast swing,200bpm) |
```

Style "Fast swing" (two words, internal space allowed), 200 BPM.

### 8.5 Vamp till cue with style change

```
M) | [A] | | | | [? Vamp] (=funk,90bpm) | | | (=swing,140bpm) [B] |
```

- Measures 1–4: section A (style/tempo from the header).
- Measures 5–7: vamp in funk at 90 BPM (the collapsible section
  `[? Vamp]` is defined in `neumaRk_markers.md` §4).
- Measure 8: return to swing 140 BPM, section B.

### 8.6 Metric modulation only

```
HS) jazz
HB) 120

…
M) | [Theme] | | (4=4.) | | | (4.=4) | |
```

Theme at 120 BPM; from measure 3 it speeds up to 180 BPM (the previous
quarter becomes a dotted quarter in the new tempo, so the new quarters
are shorter); from measure 6 it returns to 120 BPM (`4.=4`: the previous
dotted quarter becomes the new quarter).

---

## 9. Summary

| Concept                | Syntax                                    | Section |
|------------------------|-------------------------------------------|---------|
| Style/BPM directive    | `(=[Style][,Tempo])`                      | §2.1    |
| Pure metric modulation | `(figure=figure)` (without prefix `=`)    | §2.1    |
| Style                  | free multi-word text                      | §2.2    |
| BPM tempo              | `Nbpm` (integer 10–999)                   | §2.3.1  |
| Metric modulation      | `figure=figure` (valid NRK)               | §2.3.2  |
| Position               | only `M)` line, beat 1 of measure         | §3      |
| Persistence            | cross-datapack, until a new directive     | §4      |
| Semantics              | executable (player applies)               | §5      |
| Render                 | traditional notation (♩ = N, ♩ = ♩.)      | §6      |

Play directives extend the global header indications (`HS)`, `HB)`) with
the ability to make **local changes** during the song, preserving the
textual and parsable nature of the language.

---

This document defines the play directive as a **local mechanism for
controlling style and tempo** in neumaRk, completing the language's
system of performance indications.


---

# Song versions

This document defines the syntax and semantics of **versions**
in neumaRk: a mechanism for representing multiple variants of the
same song in a single file (alternative arrangements, reharmonizations of
single sections, complete rewrites).

The user chooses which variant to view/perform through the UI; the
preference is persistent in the user-index and **not in the NRK file**.

---

## 1. Definition

A **version** is an alternative variant of a portion of the song,
delimited by a **named block** of the form:

```
%%NAME
… content …
%%end
```

There are two classes of blocks:

- **Default** — block `%%NAME` without a label, is part of the linear flow
  of the song (it is the "canonical" version the reader sees by default);
- **Variant** — block `%%NAME "label"` with a label, lives alongside the
  flow. It is activated explicitly by the user.

A variant replaces **all** the occurrences of the same-named default
block during performance/rendering.

### 1.1 Minimal example

```
M) [Intro]
… original intro …

%%BRIDGE
M) [Bridge]
… original bridge …
%%end

M) [A]
… original final A …

%%BRIDGE "Bill Evans version"
M) [Bridge]
… Bill Evans bridge …
%%end
```

The user opens the song and sees the canonical version. By selecting "Bill
Evans version" from the UI selector, the `%%BRIDGE` block is replaced
by the variant; the rest of the song (Intro, A) remains unchanged.

---

## 2. Syntax

### 2.1 Opening the block

```
%%NAME                       default block
%%NAME "label"               variant block
```

- `%%` must be **at the beginning of the line** (possibly preceded
  by spaces only, according to the general whitespace rules of neumaRk).
- `NAME` is an identifier: one or more letters/digits/underscores,
  case-sensitive. No internal spaces.
- `"label"` (optional, present only in variants) is a textual
  container `"…"` adjacent to the NAME, with a separating space.
  It admits the unified markup (`neumaRk_text_markup.md`).

### 2.2 Closing the block

```
%%end
```

- `%%end` must also be at the beginning of the line.
- It closes the most recently opened block.
- A `%%end` without an open block produces warning **W148**.

### 2.3 Block content

A block contains **one or more** valid datapacks (see
`neumaRk_datapack.md`). All the musical rules (markers, chords,
notes, dynamics, etc.) apply normally inside the block.

### 2.4 Nesting not allowed

A `%%NAME` block cannot be opened inside another block. The
parser produces warning **W149** if it encounters `%%X` while a block is
open.

### 2.5 Reserved: `%%`

The sequence `%%` at the beginning of a line is **reserved** for versions blocks.
It is not allowed in other contexts of the language (NRK comments use
`//`, see `neumaRk_datapack.md` for the spec of single-line comments).

---

## 3. Structural position

### 3.1 Standalone between datapacks

The `%%NAME` blocks live **between** musical datapacks, not
inside them. The structure of the document is an alternating sequence of:

- normal datapacks (flow common to all versions);
- default `%%NAME` blocks (named sections of the flow);
- variant `%%NAME "label"` blocks (variants of the named sections).

```
[datapack] [datapack] %%BRIDGE [datapack] %%end [datapack]
                     └─ default ─┘
[datapack] %%BRIDGE "Bill Evans" [datapack] %%end
          └─────────── variant ───────────┘
```

### 3.2 Position of variants

The variants `%%NAME "label"` may appear in **any position**
of the document (recommended: immediately after the same-named default
block, or at the end of the document). The matching is by name, not by position.

---

## 4. Substitution semantics

### 4.1 Fundamental rule

When the user activates the variant `%%NAME "label"`, **all** the
occurrences of the default block `%%NAME` in the document are
replaced by the content of the variant.

The portions of the song **outside blocks** (normal datapacks) remain
unchanged in all versions: they belong to the "common trunk".

### 4.2 Multiple occurrences of the default

If a default `%%NAME` block appears multiple times (e.g. AABA with three distinct `%%A`),
a single variant `%%NAME "label"` **replaces all
the occurrences**.

```
%%A
… A original …
%%end

%%B
… B …
%%end

%%A
… A original (second occurrence, may be musically identical
   or varied) …
%%end

%%A "miles"
… A Miles version …
%%end
```

Activating "miles": both default `%%A` are replaced by the
Miles version. For per-position variants (e.g. only the second A is
different), use distinct names: `%%A1`, `%%A2`.

### 4.3 Orthogonal M) markers

The markers of the `M)` line internal to a `%%NAME` block are
**independent** of the block name. The parser does not require that
`M) [Bridge]` appear inside `%%BRIDGE`: it is the author's convention
to name them the same, but it is not constrained.

```
%%PEDAL
M) [A pedal]
… …
%%end
```

`PEDAL` is the name of the block (for the versions selector); `A pedal` is
the marker of the section (for PLAY/FORM, render, navigation).

### 4.4 Total rewrites

For complete arrangements (e.g. "Round Midnight, Miles arrangement"),
the author may enclose the entire song in a default `%%NAME` block
(with a name of choice: `%%SONG`, `%%MAIN`, etc.) and provide the rewrite
as a variant.

```
%%SONG
M) [Intro]
… complete original song …
M) [Outro]
…
%%end

%%SONG "Miles Davis arrangement"
M) [Intro Miles]
… complete Miles arrangement …
M) [Coda]
…
%%end
```

There is no reserved keyword for "the whole song": any name
works, the author chooses the one they prefer.

---

## 5. Optional header `HV)`

The document header (`neumaRk_header.md`) admits a new optional
entry **`HV)`** to explicitly declare the available versions
and the default one:

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

### 5.1 Syntax

```
HV) versions: [<label1>, <label2>, …] [default=<label>]
```

- `versions:` mandatory keyword.
- List of labels in square brackets, separated by commas.
- `default=<label>` optional: specifies which variant to show at the
  first opening (in the absence of a user preference). In the absence of
  `default=`, the default is the **default flow** (`%%NAME` blocks
  without a label).

### 5.2 Functions of `HV)`

- **Documentation**: makes the song versions explicit in the header.
- **UI ordering**: the labels are presented in the UI selector
  in the declared order.
- **Named label of the default**: without `HV)`, the default is "unnamed";
  with `HV)` it may receive a name (e.g. `original`) and appear in the
  selector together with the variants.

### 5.3 `HV)` optional

In the absence of `HV)`, the variants are deduced from the
`%%NAME "label"` blocks present in the document. The order is the order of
appearance in the file. The default is the unlabeled flow.

### 5.4 Discrepancies

A label declared in `HV)` but absent from the document (or vice versa)
**is not an error**: the UI selector shows only the variants
actually present. It is the author's responsibility to maintain
consistency.

---

## 6. User preference

The "current version" state is a **user preference** saved in
the user-index Firestore (e.g.
`users/{uid}/song_view_state/{songId}.version`).

- At first opening, the document shows the **default** (flow without
  labeled `%%NAME` blocks, or whatever is declared in `HV)
  default=`).
- The user changes version through the UI selector (badge with dropdown).
- The choice is persistent for that specific song for that user.

The version state **is never written into the NRK file**: the file
is immutable with respect to the reading preference.

---

## 7. Diagnostics

### 7.1 Diagnostic codes

| Code   | Description                                                                 |
|--------|-----------------------------------------------------------------------------|
| W147   | `%%NAME` block not closed (missing `%%end` by end of document)              |
| W148   | Orphan `%%end` (no open block)                                              |
| W149   | `%%NAME` block nested inside another block                                  |
| W150   | Malformed `HV)` (expected `versions: [list] [default=label]`)               |

### 7.2 Non-errors

- Variant without a same-named default (`%%X "label"` but no `%%X`
  default): the variant is ignored during performance, but remains in the file.
  Render UI may flag it as "orphan".
- Default without variants (`%%X` only): allowed; the block is a
  simple section "prepared for future variants".
- Label `%%X "label"` repeated multiple times: the last wins (silently),
  or the render shows a UI warning.

---

## 8. Examples

### 8.1 Days of Wine and Roses with Bill Evans bridge

```
HT) Days of Wine and Roses
HC) Henry Mancini
HK) F
HM) 4/4
HV) versions: [original, bill_evans] default=original

M) [Intro]
… intro …

M) [A]
… A original …

%%BRIDGE
M) [Bridge]
… bridge original …
%%end

M) [A]
… final A original …

%%BRIDGE "bill_evans"
M) [Bridge]
… Bill Evans reharmonized bridge …
%%end
```

### 8.2 Round Midnight, total Miles rewrite

```
HT) Round Midnight
HC) Thelonious Monk
HV) versions: [original, miles] default=original

%%SONG
M) [Intro]
… standard intro …
M) [A]
… original A …
M) [B]
… original B …
M) [A]
… final A …
%%end

%%SONG "miles"
M) [Intro Miles]
… Miles intro …
M) [A]
… A with changed chords …
M) [B]
… B with added phrase …
M) [Coda]
… Miles coda …
%%end
```

The user chooses "miles" from the selector → the original `%%SONG` block is
replaced by the rewrite.

### 8.3 AABA with A "miles" replacing all the A

```
%%A
… original A …
%%end

%%A
… (second occurrence, identical or varied) …
%%end

%%B
… B …
%%end

%%A
… final A …
%%end

%%A "miles"
… Miles version of the A …
%%end
```

Activating "miles": the three default `%%A` are replaced by the variant.
The `%%B` remains unchanged.

### 8.4 Per-position variant (distinct names)

```
%%A1
… first A …
%%end

%%B
… B …
%%end

%%A2
… second A (slightly different) …
%%end

%%A2 "minor key"
… A2 in minor mode …
%%end
```

Only the second A is replaceable by the "minor key" variant. The first
A is not involved because it has a different name (`%%A1`).

---

## 9. Summary

| Concept               | Syntax                                            | Section |
|-----------------------|---------------------------------------------------|---------|
| Default block         | `%%NAME … %%end`                                  | §2.1    |
| Variant block         | `%%NAME "label" … %%end`                          | §2.1    |
| Block closing         | `%%end`                                           | §2.2    |
| Block position        | standalone between datapacks, no nesting          | §3.1    |
| Substitution          | variant replaces all default `%%NAME`             | §4.1    |
| M) markers            | orthogonal to the block name                      | §4.3    |
| Total rewrite         | enclose the song in a single block (e.g. `%%SONG`) | §4.4 |
| Header                | `HV) versions: [list] default=label` (optional)   | §5      |
| User preference       | user-index Firestore, not NRK                     | §6      |

---

This document defines the **song versions** in neumaRk:
a robust and granular mechanism for representing alternative
arrangements, targeted reharmonizations and complete rewrites of the
same song within a single file.


---

# Collections (book / playlist)

This document defines the text format by which an **ordered set of
songs** — a *book* or a *playlist* — is represented in a single neumaRk
file.

A collection **does not introduce a new language**: it is a thin
container layer around a sequence of songs, each of which is a
standalone neumaRk document as already defined by the rest of the
specification. The same parser reads single songs and collections; the
distinction is made on the **first line of the file**.

---

## 1. Purpose and role

The collection format serves to **export, share, and re-import** a book
or a playlist as a single `.nrk` file — self-contained and readable.

The guiding principle is **portability**: the file is a *self-sufficient
snapshot* of the collection. All songs are embedded as **snapshots**
(frozen copies), so that the file can be opened and imported by anyone,
even without access to the original songs and even if the originals
change or disappear.

Everything that is **product-specific** (and not part of the musical
language) — cover art, curated tags, sharing, roles, database
identifiers — **is not part of the file** (see §7).

---

## 2. Collection and single song

A neumaRk file may represent:

- a **single song**, whose first line is the version declaration
  `nrk:<major>.<minor>` (see `neumaRk_header.md` §2);
- a **collection**, whose first line is `nrk-book:<v>` or
  `nrk-playlist:<v>` (§3).

The distinction is given **by the content of the first line alone**,
never by the file extension: a `.nrk` may contain either.

A file starting with `nrk:` is a single song as always: the collection
format is **backward-compatible** and does not alter the reading of
existing files.

> The term **collection** is a conceptual umbrella used in this
> specification and in tooling; it **never appears as a token** in the
> file. The type (book or playlist) is written directly into the
> first-line marker.

---

## 3. Opening line and type

The first line of a collection is a version declaration that
**embeds the type**:

```
nrk-book:0.6
```

or

```
nrk-playlist:0.6
```

Characteristics:

- it is **mandatory** and must be the **first line of the file**;
- the type (`book` / `playlist`) is part of the marker: reading the
  first line tells you *both* that the file is a collection *and* which
  type;
- the version follows the same `nrk:` numbering of the language.

Functional difference between the two types:

- a **book** is a curated set of songs, **without** per-song overrides;
- a **playlist** is an executable sequence in which each song may carry
  a **per-occurrence override** (§6).

---

## 4. Collection header

After the opening line, and any blank lines, a **collection header** may
appear: a block of **directives** in the form `key: value`.

```
nrk-playlist:0.6
name: My Setlist
desc: live at the Blue Note
```

| Directive | Meaning | Mandatory |
|---|---|---|
| `name:` | collection name | no (recommended) |
| `desc:` | free description | no |

Header directives:

- use `:` as the separator (same syntactic family as `nrk:`);
- precede any song block;
- are **part of neumaRk** (as the `HT)` title is for the song): the
  textual identity of the collection.

A header directive appearing **after** the first song block is out of
place (**W155**).

---

## 5. Song blocks

The body of the collection is a **sequence of song blocks**. Each block:

- is a **standalone neumaRk document**, starting with its own
  `nrk:<v>` line and continuing with header and datapacks as usual;
- is a self-sufficient **snapshot** (the musical content is embedded,
  not referenced);
- is copy-pasteable as a valid `.nrk` file on its own.

The **song order is the order of the blocks in the file**: there is no
numeric ordering key.

```
nrk-playlist:0.6
name: My Setlist

nrk:0.6
First Tune (Author)
F 120bpm
F| Bb| C7| F|

nrk:0.6
Second Tune (Author)
Bb 90bpm
Bb| Eb| F7| Bb|
```

A collection **with no song blocks** is degenerate (**W156**).

---

## 6. Per-item override (playlist only)

In a playlist, each song may be preceded by an `item:` line declaring
its **overrides for that occurrence in the setlist**. The overrides
**are not properties of the song** (the same song in two playlists may
have different ones): they are a layer of the *setlist entry*.

```
item: transpose=+2 notes="capo 3" form=[Intro] [A|8]x2 [B|8] [A|8]
nrk:0.6
My Tune (Author)
…
```

Rules:

- the `item:` line **applies to the song block that immediately
  follows** it (the next `nrk:`);
- it appears **only if there is at least one override**; its absence
  means "no overlay";
- it is allowed **only in playlists**. An `item:` line in an
  `nrk-book:` is out of context (**W152**).

### 6.1 Parameter syntax

Parameters are `key=value` pairs separated by spaces. The `=` sign
distinguishes the **inline parameter** from the header directive (`:`),
so that no symbol has a double role.

A `value`:

- is a **simple token** (no spaces), e.g. `transpose=+2`; or
- is **quoted** `"…"` when it contains spaces (literal text,
  quote-aware as in the rest of neumaRk), e.g. `notes="capo 3"`.

Allowed keys: `transpose`, `notes`, `form`. An unknown key is ignored
with diagnostic **W153**.

| Key | Type | Meaning |
|---|---|---|
| `transpose` | signed integer | performance transposition (overlay, ± semitones) |
| `notes` | text | personal annotation for this entry |
| `form` | FORM grammar | performance form for this occurrence (§8) |

### 6.2 `form=` consumes the rest of the line

Since the FORM grammar itself uses `"…"` containers for labels (see §8),
the `form=` parameter **is not quoted**: it consumes **everything that
follows up to end of line**, verbatim. For this reason `form=`, when
present, is **the last parameter** of the `item:` line.

```
item: transpose=-1 form="Theme"[A|8]ff [B|4]x2 "Coda"[A|8]&fermata
```

The quotes here are **internal to the FORM grammar** (labels), not
delimiters of the parameter. (A multi-line form is out of scope in this
version.)

A null `transpose` (`+0`, no-op) and an empty `notes` are not errors.

---

## 7. Portability mode: inside and outside the file

The collection carries **only music and minimal structure**. Everything
that is application product is **reconstructed on import** from defaults,
as when creating a new collection.

**In the file (it is neumaRk):**

- the type (`nrk-book:` / `nrk-playlist:`);
- `name:` / `desc:`;
- the song order (= order of the blocks);
- for playlists: the `transpose` / `notes` / `form` overrides on
  `item:`;
- each song in full, as a **snapshot**.

**Outside the file (it is not neumaRk):**

- cover art, curated tags, subscriber count;
- sharing, roles, permissions;
- the songs' database identifiers;
- the *dynamic vs snapshot* distinction of playlist entries (on export
  every entry is **resolved to a snapshot**).

### 7.1 The file is intentionally anonymous

Consistent with the principle above, a collection file carries **no
origin identity**: no database identifiers, no deduplication keys, no
host tags. It is, by design, *anonymous*.

Consequence: a song's **identity** (deciding whether two songs are "the
same") **is not a property of the file** — it is a host concern, to be
derived from the **music** (see §7.2), never from an opaque tag stuck to
the file. This is deliberate: the format does not carry data it cannot
itself understand.

### 7.2 Import semantics (host behavior)

*How* a host re-imports a collection **is not defined by neumaRk** — it
is application behavior. In leadsheet.app, because the file is anonymous
(§7.1):

- importing a **book** creates **copies** of the songs in the user's
  library; import is not idempotent — re-importing the same book
  recreates the copies;
- **deduplication** ("do I already have this song?") is **deferred** and,
  when it lands, will be based on the **melodic fingerprint** (a property
  of the music, shared with search) as an *advisory* — not on an exact
  key glued to the file. An exact, durable identity is not obtainable
  from a deliberately pure file; so dedup is derived from the music and
  is, by nature, a suggestion rather than an automatism.

### 7.3 Header absorption on import — header-probe module (lossless)

On import, each song is **split** into header (→ `prop`) and datapack
(→ clean `cont`), so an imported song is **consistent with WRITE-saved
ones** (header in properties, body in `cont`) and the export→import
round-trip is **lossless**.

The split uses the **real parser** (`parseText`, text→`Music`) exposed by a
**dedicated WASM module** (`createModuleHeader`, source
`wasm/src/neumark/header_probe.cpp` → `parseHeaderOnly`), served under
`assets/wasm/header/` and **lazy-loaded only on import**. The *library*
app's WASM bundle stays intentionally lean (no parser at normal boot); the
parser cost is paid once, on the first import.

In *view*, which already bundles the parser, `parseHeaderOnly` is exposed on
the **same module** (`createModuleView`) and used by the persisted save
(`collection-view.service`), with no separate module load.

`parseHeaderOnly` returns:

- `prop`: the full header in DB shape (`tit`, `crd{mus,lyr,arr,trs}`, `key`,
  `bpm`, `mtr`, `sty`, `sub`, `yr`, `alt[]`, `lng[]`) — values from the parsed
  `Music`, presence from the `map.header` ranges;
- `cont`: the clean datapack (lines after the header, leading/trailing blanks
  removed).

**Fallback:** if the module fails to load, import falls back to the
**lightweight scan** (`parse_block_header` in `collections.cpp`, a subset of
fields) with the header left inside `cont`, which WRITE normalizes on the next
save. The lightweight scan thus remains a safety net, no longer the primary
path.

**Known limitation:** the split needs the blank line between header and
datapack (which `generate_nrk` always emits on export); on hand-written files
**without** that separator `parseText` cannot tell header from body — same as
WRITE's import.

---

## 8. FORM at the collection level

The `form` parameter of a playlist entry (§6) uses the **`FORM)`
grammar** defined in `neumaRk_play_and_form.md` (section boxes,
informative durations `|N`, labels, dynamics, keywords, free prose).

### 8.1 Semantics: replacement

If a playlist entry carries a `form`, it **replaces** the `FORM)`
section possibly contained in the song's snapshot, **for that
occurrence**.

It serves to declare: *"the form in which we play this song tonight is
this, regardless of the song's original form."*

- override present → the item `form` **wins** over the song's `FORM)`;
- override absent → the song's `FORM)` remains (if present).

It is a replacement, **not** a merge.

### 8.2 Why FORM and not PLAY

`FORM)` is **position-independent** (a single, descriptive section at
the end of the document; the player ignores it): it lends itself to
being declared at the setlist level, where only a *reference* to a song
exists.

`PLAY)` instead is **positional/inline**: its effect depends on *where*
it is placed among the datapacks (see `neumaRk_play_and_form.md` §2.1).
At the setlist level there is no position inside the song into which to
inject it, so `PLAY)` **is not expressible** as an entry override. The
form override is therefore always **descriptive** (FORM), never
executed: it does not alter playback, but *what the musicians read as
the form*.

### 8.3 Reference resolution

The `[NAME]` boxes of the item `form` resolve against the **`M)` markers
of the entry's song** (the snapshot that follows), with the same model
as `neumaRk_play_and_form.md` §3.1. A box that matches no marker is
**reference broken**: rendered as non-executed text, **with no error or
warning** (`neumaRk_play_and_form.md` §7.3). This allows informal
setlist forms.

Box diagnostics (`W141` duration, `W142` repeat, `W143` keyword) remain
applicable; document-placement ones (`W140` multiple `FORM)`, `W145`
`FORM)` not at the end) **do not** apply to the item `form`.

---

## 9. Parsing rules

### 9.1 Split before musical parsing

The collection file is **split into blocks at the `nrk:` lines before**
any musical analysis. The song parser receives **only** the text from
one `nrk:` line to the next.

Consequence: the collection tokens (`nrk-book:` / `nrk-playlist:`,
`name:` / `desc:`, `item:`) live **in the segments outside the blocks**
and **cannot collide** with musical content.

### 9.2 Recognition

- first line `nrk-book:` → book collection;
- first line `nrk-playlist:` → playlist collection;
- first line `nrk:` → single song.

The parser entry-point, which for songs enforces "`nrk:` must be the
first line", accepts `nrk-book:` / `nrk-playlist:` as **alternative
first-line tokens**. They are distinct literal prefixes: recognition is
additive and unambiguous.

### 9.3 Blank lines and versions

- Blank lines separate the collection header from the blocks and the
  blocks from one another, consistent with datapack delimitation
  (`neumaRk_datapack.md` §1).
- The `%%NAME … %%end` block (song versions, `neumaRk_versions.md`)
  remains **internal to the single song block**: it is text the song
  parser sees, not a collection token. The collection layer **does not
  use `%%`**.

---

## 10. Diagnostics

| Code | Description |
|---|---|
| W152 | `item:` line in an `nrk-book:` collection (books have no per-item overrides) |
| W153 | Unknown override key in `item:` (allowed: `transpose` / `notes` / `form`) |
| W154 | `item:` line not followed by a song block (`nrk:`) |
| W155 | Collection header directive (`name:` / `desc:`) after the first song block |
| W156 | Collection with no song blocks |

### 10.1 Non-errors

- a snapshot block whose `FORM)` is replaced by the item `form` (§8.1);
- an item `form` box `[NAME]` with no matching marker (reference broken,
  §8.3);
- `transpose=+0` (no-op) and empty `notes`;
- extra blank lines in the header or between blocks.

---

## 11. Examples

### 11.1 Playlist with overrides

```
nrk-playlist:0.6
name: Friday Gig
desc: trio set

item: transpose=+2
nrk:0.6
Blue Bossa (Kenny Dorham)
Cm 140bpm
Cm| Fm| Dm7b5| G7| Cm|

item: form=[Intro|4] [A|16]x2 [Solos] [A|16] [Outro]&fermata
nrk:0.6
So What (Miles Davis)
M) [A] [Solos] [Outro]
…datapack…
```

The first entry plays Blue Bossa transposed +2; the second declares a
performance form that replaces the song's own.

### 11.2 Book (no overrides)

```
nrk-book:0.6
name: My Real Book — Vol. 1

nrk:0.6
Autumn Leaves (J. Kosma)
…

nrk:0.6
All The Things You Are (J. Kern)
…
```

### 11.3 Single-song collection

```
nrk-playlist:0.6
name: Solo Spot

nrk:0.6
Naima (J. Coltrane)
…
```

It degrades transparently: a collection with a single block is valid.

---

## 12. Summary

| Concept | Syntax | Section |
|---|---|---|
| Book opening | `nrk-book:<v>` | §3 |
| Playlist opening | `nrk-playlist:<v>` | §3 |
| Collection header | `name:` / `desc:` | §4 |
| Song block | `nrk:<v>` … (snapshot) | §5 |
| Order | order of the blocks in the file | §5 |
| Entry override | `item: key=value …` (playlist only) | §6 |
| Entry parameters | `transpose` / `notes` / `form` | §6.1 |
| Entry form | `form=` (FORM grammar, rest-of-line) | §6.2, §8 |
| Form replacement | item `form` replaces the song's `FORM)` | §8.1 |
| Split | at `nrk:` lines, before musical parsing | §9.1 |
| Portability | all snapshot; cover/tags/roles outside | §7 |

---

This document defines **collections** (books and playlists) as
neumaRk's portable container layer, built by reuse around the
song documents and the song form (`neumaRk_play_and_form.md`).


---

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


---

# Official Changelog

---

## neumaRk 0.6.0 — Current version (in development)

Reference version declared by the examples in the specification
(`nrk:0.6`). It extends 0.5.0 with a broad wave of features, listed
below.

### What's new in 0.6

0.6 extends 0.5.0 with the following features; each is specified in the
referenced document.

| Feature | Document |
|---|---|
| Grace notes | `neumaRk_grace_notes.md` |
| Second voice `N2` | `neumaRk_voices.md` |
| Staff continuity `N+` / multi-stave | `neumaRk_datapack.md` §4 |
| Measure repeat `%` | `neumaRk_flow_and_repeats.md` §7 |
| Polychords `[top\|bottom]` | `neumaRk_chords.md` §6 |
| Comment-label / alternate chords `C+` | `neumaRk_chords.md` §7 |
| Harmony persistence (empty cell + leading `.` continuation) + no-chord `NC` | `neumaRk_chords.md` §1.1-1.2 |
| Unified text markup | `neumaRk_text_markup.md` |
| Collapsible sections `[? …]` / `[!]` | `neumaRk_markers.md` §4 |
| Extended dynamics `D)` | `neumaRk_dynamics.md` |
| Play directive `(=Style,Tempo)` | `neumaRk_play_directive.md` |
| `PLAY)` / `FORM)` | `neumaRk_play_and_form.md` |
| Versions `%%NAME … %%end` | `neumaRk_versions.md` |
| Articulations `A)` (base + extensions §8-12) | `neumaRk_articulations.md` |
| Lyrics `L)` + `LYRICS)` block | `neumaRk_lyrics.md` |
| Extended notes `N)` (noteheads, glissando, rhythm `{}`) | `neumaRk_notes_and_durations.md` §11-12 |
| Multi-measure rest `RN` | `neumaRk_notes_and_durations.md` §13 |
| Spacer `s` (invisible rest) | `neumaRk_notes_and_durations.md` §14 |
| Section anacrusis (`>>>` open measure + `>` mid-song upbeat) | `neumaRk_notes_and_durations.md` §7.1 |
| Collections (book / playlist) | `neumaRk_collections.md` |

### Notable normative changes in 0.6

Beyond the new features, 0.6 introduces a few changes to syntax or codes
relative to earlier drafts:

- **`LYRICS)` block codes renumbered to `W157`/`W158`.** An earlier draft had
  the `LYRICS)` block share `W152`/`W153` with Collections; every code now has a
  single meaning (Collections: `W152`–`W156`; `LYRICS)` block: `W157` =
  non-existent section, `W158` = pickup overflow).
- **Optional-section close: `[!]` replaces `[?]`** (`neumaRk_markers.md` §4.2).
  `[!]` is an anonymous non-optional section-open marker; it closes the preceding
  optional scope as a consequence of the general rule §4.1.
- **Measure repeat `%` with span N>1**: the token appears in *each* of the N
  consecutive measures in the run (e.g. `| a | b | %2 | %2 |`), preserving the
  "one cell = one measure" invariant (`neumaRk_flow_and_repeats.md` §7).
- **An empty chord cell now makes the harmony *persist*** (previously:
  silence). A `C)` measure with no symbols/`%`/`NC` re-realizes the previous
  chord on the downbeat (`neumaRk_chords.md` §1.1). To explicitly declare the
  absence of harmony, use the new **`NC`** token (§1.2, `N.C.` glyph, error
  `E128` if mixed with a chord). The implicit slash-notation trigger changes
  accordingly: it now includes persisting harmony and excludes `NC`
  (`neumaRk_notes_and_durations.md` §10).

### Diagnostic-code convention

- **`E###`** — *error*: invalid construct, emitted as a blocking
  error (`LOG_ERROR`).
- **`W###`** — *warning*: non-blocking diagnostic, best-effort
  (`LOG_WARNING`); parsing continues.

The prefix indicates the **severity**, not the category. The entire 0.6+
diagnostic family (`W130`–`W158`: dynamics, articulations, play directive,
`PLAY)` / `FORM)`, collapsible sections, versions, `HV)`, collections,
`LYRICS)` block) is emitted as a **warning** and has been renamed from
`E13x`/`E14x`/`E15x` to `W13x`/`W14x`/`W15x` to align the prefix with the
actual severity.

The two tables below — **base codes** (pre-0.6 and fundamental) and
**0.6+ codes** — together form the **complete, authoritative** map
code → meaning, aligned with the parser. Each code has a single meaning.
Internal codes `E901`–`E905` are dev-facing (EN-only) and not normative.

#### Base code allocation (pre-0.6 and fundamental)

| Code | Meaning | Family (doc) |
|---|---|---|
| E001 | Uninterpretable token: note / grace event / chord-stack `<…>` / rhythm group `{…}` malformed or not closed | Notes & durations / Grace |
| E002 | A duration cannot follow `.` or `!` | Notes & durations |
| E003 | Invalid tuplet | Notes & durations |
| E004 | Cannot parse pitch | Notes & durations |
| E005 | Note durations exceed the measure meter | Notes & durations |
| E006 | More than one slash-rhythm `/` per measure | Notes & durations |
| E007 | Slash `/` has no room (less than one beat after beat alignment) | Notes & durations |
| E008 | Absolute octave `@<n>_` requires an explicit duration | Notes & durations |
| E009 | Missing duration on first grace event, or non-conforming (only `4`/`8`/`16`) | Grace notes |
| E010 | Modifier `/` or `^` allowed only on the block's last grace event | Grace notes |
| E011 | Empty grace block `[]` | Grace notes |
| E012 | Grace block with more than 4 events | Grace notes |
| E013 | Rest not allowed as a grace event | Grace notes |
| E101 | Compact rhythm list / polychord / chord expression unparsable | Chords |
| E102 | Unrecognized token in the chord line | Chords |
| E110 | Too many staves in datapack (max 4) | Datapack / multi-stave |
| E122 | `N)` without match: more continuations than staves in the previous datapack (use `N+`) | Datapack (`N+`) |
| E123 | `N2` without a valid parent stave | Voices |
| E124 | Duplicate `N2` on the same stave | Voices |
| E125 | Key directive not allowed on an `N2` row | Voices |
| E126 | More than one comment-label on the same chord / group / row | Chords (alternate) |
| E127 | Max 2 alternative `C+` rows per datapack | Chords (alternate) |
| E128 | `NC` mixed with other content in the same measure | Chords |
| E300 | Measure-repeat (`%` / `RN`) with no valid source | Flow / MMR |
| E301 | Cannot parse the key-signature note | Header / key |
| W002 | Tuplet not closed before measure end (auto-filled with 1/64 rests) | Notes & durations |
| W003 | Grace block not adjacent to the main note (ignored) | Grace notes |
| W004 | Grace block without an adjacent main note (ignored) | Grace notes |
| W006 | Pitch outside the MIDI range [1..127] | Notes & durations |
| W007 | Invalid rhythm-notation token `{…}` (duration or tuplet) | Notes & durations |
| W008 | Multi-measure rest `RN` over a span with content: degraded to a normal rest | Notes & durations (MMR) |
| W009 | Modifier not allowed on spacer `s` (ignored) | Notes & durations (spacer) |
| W103 | Unrecognized chord suffix | Chords |
| W301 | Could not deduce title or credits from the first header line | Header |
| W400 | Chord-rhythm note with non-positive duration (omitted) | Chords (rhythm) |

#### 0.6+ code allocation (single source)

The `A)`/`D)`/`L)` lines share **W131** (excess tokens) by semantic
identity, not by collision.

| Code | Meaning | Family (doc) |
|---|---|---|
| W130 | `D)` without a valid parent `N)`/`N+`/`N2` line | Dynamics |
| W131 | Tokens in excess of the `N)` events | `A)`/`D)`/`L)` (shared) |
| W132 | `D)` token `-` not reducible to extension/barline | Dynamics |
| W133 | Text container not closed at end of line | Dynamics |
| W134 | Empty play directive `(=)` | Play directive |
| W135 | Reversed slot order (tempo before style) | Play directive |
| W136 | BPM out of range (10–999) | Play directive |
| W137 | Invalid NRK figure in metric modulation | Play directive |
| W138 | Play directive in a line other than `M)` | Play directive |
| W139 | `A)` token outside the vocabulary | Articulations |
| W140 | More than one `FORM)` section | PLAY/FORM |
| W141 | Invalid `|BARS` duration (1–999) | PLAY/FORM |
| W142 | Repeat count `xN` out of range (2–99) | PLAY/FORM |
| W143 | Keyword `&xxx` not reserved | PLAY/FORM |
| W144 | Malformed `A)` slur (not closed at end of line) | Articulations |
| W145 | `FORM)` not at the end of the document | PLAY/FORM |
| W146 | Redundant `[!]`: no optional section to close | Markers |
| W147 | `%%NAME` block not closed (missing `%%end`) | Versions |
| W148 | Orphan `%%end` (no open block) | Versions |
| W149 | Nested `%%NAME` block | Versions |
| W150 | Malformed `HV)` | Versions |
| W151 | Collapsible section not at start of line (§4.7) | Markers |
| W152 | `item:` line in an `nrk-book:` collection | Collections |
| W153 | Unknown override key in `item:` | Collections |
| W154 | `item:` line not followed by a song block | Collections |
| W155 | Collection header directive after the first block | Collections |
| W156 | Collection with no song blocks | Collections |
| W157 | `LYRICS) [NAME]` references a non-existent section (reference-broken) | Lyrics (`LYRICS)` block) |
| W158 | `LYRICS)` pickup group `<…>` overflows the available preceding-notes run | Lyrics (`LYRICS)` block) |

> Historical note: `W144` had also been drafted for "nested `PLAY)`", a case
> **structurally prevented** by the parser (never emitted); the code therefore
> remains with the articulations. The collapsible-section-not-at-start-of-line case
> was moved from `W147` (which collided with Versions) to **`W151`** (2026-05-26).

---

## neumaRk 0.5.0 — First public release

### Status

Public preview. The language is usable and coherent,
but subject to short-term evolution.

### Version meaning

This is the **first public release** of neumaRk.
The number 0.5 reflects an already advanced conceptual maturity,
while not guaranteeing definitive stability of the semantic interface.

### Included features

- datapack-based structure
- header with conservative deduction
- notes with implicit and explicit durations
- chords with rhythmic semantics and implicit/explicit durations
- chords with a **compact duration list** `X(a,b,r16,c,...)` (see §4.4)
- repeat and flow management
- support for Compact / Human / Verbose formats

### Normative clarifications

- persistent musical context
- contextual semantics of symbols
- priority of a single note in the measure
- deducible Format line

### Not yet stabilized

> Historical list **as of 0.5.0**. The current state of these items is
> in the table in §0.6.0 (many are now stabilized and implemented).

- articulations, dynamics, lyrics
- polychords (syntax `[top|bottom]`, see `neumaRk_chords.md` §6)
- multi-stave per datapack (up to 4 staves, see `neumaRk_datapack.md` §4) — spec described, runtime implementation in progress
- measure repeat (syntax `%` / `%!` / `%2` / `%!2` / `%4` / `%!4`, see `neumaRk_flow_and_repeats.md` §7) — spec described, note-row implemented; chord-row N>1 and first-measure validation not yet
- possible syntactic extensions
- refinement of the deduction rules
- complete formal validation

### Compatibility

There are no previous public versions.