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

Note-anchored elements — tokens in 1:1 correspondence with the notes of the parent N) line (or N2). The principal class.
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.