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 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) executed at the moment it is encountered 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: 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
Execution	follows	ignores
Use	execution guide	summary, search, teaching

The choice between "execution follows PLAY" and "execution follows the natural flow of datapacks" is not a property of the document: it is a preference of the reader, kept by the host. The document contains both forms of information; the reader 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 a blank line (§6.1) or at the first unescaped explicit line marker: the single end rule of free-text blocks, neumaRk_datapack.md §13. A [NAME] box alone on a line remains content of the PLAY).

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 like PLAY) (§2.1): at a blank line or at the first explicit line marker (neumaRk_datapack.md §13).

---

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

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

In the NAME \] is a literal ] and does not close the box (neumaRk_text_markup.md §4): [Coda \] finale] references the section written [Coda \] finale] in M), which reads Coda ] finale.

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, medium size.

A label breaks on ; (neumaRk_text_markup.md §3bis) and, line by line, also when it is wider than the box. Lines stay centred on the box; the top label grows upward, the bottom one downward.

"Tema;uno"[A|8]"con;feeling"     top and bottom on two lines

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 xN with N > 99 produces warning W142 (recoverable, count clamped). x0, by contrast, is contradictory ("execute 0 times" → the material is never performed) and produces the error E302.

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

Keywords are reserved: unknown keywords produce warning 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)
;	line break in the rendering (§6.3), no effect on execution

The first three 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 free prose in PLAY) is not executed: only the boxes and the structural tokens are. Free prose is exclusively informative value for the reader.

Two bracketed forms are prose, not boxes: the footnote reference [^label] and the link [text=>url] (neumaRk_text_markup.md §3ter and §3quater). A […] that starts with ^ or contains => never opens a section box:

PLAY) [A|8]x2 as on the [1961 record=>https://example.org/lp] [B|8]

In FORM), the entire content is descriptive prose with section boxes interpolated: nothing of FORM) is executed in any case.

The same descriptive body is also written in the Format row F), beside a short system: F) |* On cue, D.S. al @ (neumaRk_datapack.md §9.1).

---

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 a blank line, at the first unescaped explicit line marker (neumaRk_datapack.md §13) or at the end of the document. A prose line that starts with a marker is written with a leading \ (\N) …); the \ is removed when rendered.

6.3 Forced line break: ;

The elements of a section are laid out in a row and wrap on their own only when the row is full. To break the row at a specific point, write a ;, as in containers (neumaRk_text_markup.md §3bis):

PLAY) [Intro] [A|8]x2 ; [B|8] [A|8] [Outro]&fermata

[Intro] and [A|8]x2 sit on the first row, the rest on the second.

• Every unescaped ; breaks the row, even when attached to a word: then;[B] is "then", a break, [B]. To print a ; write \; (neumaRk_text_markup.md §4).
• ; separates like a space: @;[B] is a coda, then a break.
• A leading, trailing or repeated ; (; ;) produces no empty rows.
• The ; only affects rendering: it does not change execution and does not split the section in two.

---

7. Execution semantics

7.1 Base model

Without any PLAY) in the document, the datapacks are executed 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 a PLAY) section is encountered, the sub-program contained in it is executed instead of the natural flow of datapacks at that point. After the PLAY) completes, execution continues from the datapack immediately following in the document.

Multiple consecutive PLAY) are read in order and each is executed 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;
• 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 box distinct from that of resolved references (thinner border, more rounded corners), with the text in the normal style: they 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))
E302	Repeat count x0 (contradictory: "execute 0 times")

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]

Execution: 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; only the boxes are executed: 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; it is not executed (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. 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

Execution: 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 PLAY vs natural flow

The same document can be:

• read as PLAY: the PLAY) section(s) are followed and the linear flow of datapacks is ignored;
• read as flow: the PLAY) sections are ignored and the reading follows the datapacks in document order.

The choice is a preference of the reader (§1.3), 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
Line break	; (literal: \;)	§6.3
Reference broken	[NAME] without marker of the same name, not executed	§7.3
Informative duration	|BARS graphical only, no checking	§3.2
PLAY/flow toggle	reader preference, not in the file	§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.