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.