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 that finds no preceding N)/N+/N2 in the same datapack is not an error: it is bound to an implicit stave (stave 0 with auto-rests) and the parser emits no diagnostic. This tolerance is specific to D): an A) without its row below is instead ignored with W174 (neumaRk_articulations.md §2).

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 following the frame model (see neumaRk_text_markup.md §2.1): the text sits between quotes, the frame is optional.

Form	Effect
`"text"`	annotation without a frame
`["text"]`	annotation in a box (reference form)
`[text]`	shorthand for `["text"]`: same box
`("text")`	annotation in a round frame

The forms apply in every position: on the note, at the barline (§6), with or without an extension (§5). In D) the round parenthesis serves only the ("…") frame: a ( or ) in any other form (e.g. (mf), (text)) is ignored and reported with W177. (mf) therefore produces mf, without parentheses; for an editorial dynamic in parentheses write it as text: ("mf").

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, medium size (role reduced; ### makes it small): 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 event. It serves to "skip" an event (note or rest) 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 an event (note or rest) 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

Rests count as a position (like neumaRk_articulations.md §4, and unlike L) which skips them): a . above a rest is an event in its own right. The count is per-event, not per-note. Example: D) | f p mf | over N) | c4 r4 e4 | = 3 tokens over 3 events (2 notes + 1 rest), no W131.

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 events (notes and rests) 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"]/[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"dim."- - - - - - - - - | - - - - - - - pp |
//   └──── extension 1 ─────────┘└──── extension 2, across the barline ───────┘

The second extension starts from the text "dim." that goes with ppp: a punctual dynamic alone does not extend (§5.1), and a - glued to ppp would open nothing.

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 at the opening barline of the current measure (just before the new anchor) and opens a new begin-bar anchor aligned there.

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" at the barline (just
//                              before "new"), 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 -.

Line rendering. The dashed line covers the full width of the last extended note and stops just before the onset of the closing event — be it a note-anchored element, a new text annotation, or the begin-bar of the following measure. This is the same termination as graphical and textual hairpins (§3.2, §3.3). The only exception: implicit closing at the end of the system extends the line to the right edge of the stave.

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

"text"- that OPENS (note-anchored reclassification). A "text"- as the last token of a measure, when no line is open upon reaching it and the next measure continues with -, closes nothing: it opens a new cross-bar line. The label is then reclassified as a note-anchored opening on the measure's last event (rendered ON the note — e.g. the first slash of a slash measure — not at the barline), and the line runs rightward until it closes (a note or end-of-system). This is how to label an interior point with a crossing line (e.g. D) | . "solo break"- | - puts "solo break" on the first slash and draws the line to end-of-system). The forms . "x"- and . "x"- - (with the extra - under slash=1slot) are equivalent and round-trip lossless. It does NOT trigger if a line is already open ("end" closes, above) or if the next measure does not continue (stays a punctual end-bar label).

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.

6.6 Terminator `-|` (close on the end-bar, no text)¶

An open extension normally closes on a note (§5.4) — the last covered note or the closing event. The terminator covers the case "close on the barline, hook, no text", idiomatic of the rhythm tacet ----| (where after the line there is neither text nor a note to rest on): a - glued to the composite border as the last token of the measure.

D) | -"vamp"- - | - -| |
//     ↑ begin-bar + opens   ↑ terminator: closes on the end-bar of measure 2

Prefix of the whole border, uniform (no special case per decorator): -|, -:|, -:open|, -:x3|, -||, -|., -DCal@| → the parser strips the leading - (= "close span + hook"), the rest is the normal border of the measure (§6.1), parsed as everywhere.
Glued/spaced discriminator (§7.2): -| (glued) hooks the border; - | (spaced) is a continuation - that crosses the barline.
The terminator is anchored to the barline, not to a note column: it does not touch the 1:1 correspondence with N).
It is mirrored in A) (neumaRk_articulations.md §13.5): same form, same effect, above the staff.

Rendering: the dashed line reaches the right edge of the measure, with a hook at the end (toward the staff); no label.

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 ("…", ["…"]/[…], ("…")) 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)
`-\\|` (or `-:\\|`, `-\\|.`…) as LAST token, glued to the border	terminator: closes on the end-bar, no text (§6.6)

A - not reducible to any of these patterns has no effect: it becomes an empty continuation, with no diagnostics (code W132, meant for this case, is reserved and not emitted).

7.3 Disambiguation of `[…]` and `(`¶

The container […] in D) is always a text annotation in 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.

A ( in D) is a round frame only in the form ("…"). Any other parenthesis ((mf), (text), p(…) is ignored with W177; play directives (=…) outside M) are still reported by W138.

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 the containers in D) is subject to the unified markup of neumaRk_text_markup.md §3. The default style applied is plain, medium 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 with the dynamic glyphs of the music font (the traditional italic letters of p, mf, sfz…), 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: plain, medium size (consistent with §3.4 and §7.5; italic/bold/underline only via markup *…*/**…**/__…__). Annotations with ["…"]/[…] show a box around the text, those with ("…") a pair of round parentheses; annotations with "…" are text only.

A ; in the annotation breaks the line (neumaRk_text_markup.md §3bis). The stack sits below the staff and grows downward: the first line stays where the single line would be. Each line is centred on the note; if the stack would run past the staff, it moves as a whole, based on the widest line. A single frame (box or round frame) wraps the whole stack.

D) | "dolce;espr." . . . |      // →   dolce
//                                  espr.

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. With a multi-line label the line follows the first line.

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. On multiple lines the alignment applies line by line: begin to the left, end to the right.

9. Diagnostics¶

9.1 Diagnostic codes¶

Code	Description
W131	Number of note-anchored tokens in `D)` greater than the events of `N)` (`W131.excess_dynamic`)
W132	Reserved, not emitted: `-` token not reducible to extension or barline anchor (§7.2)
W133	Text container not closed within the measure (`"…`, `[…` or `("…` without closing): the rest of the measure is read as text
W138	Play directive `(=…)` outside the `M)` row: ignored (`neumaRk_play_directive.md`)
W177	Parentheses outside a `("…")` frame (`(mf)`, `(text)`): ignored (`neumaRk_text_markup.md` §2.1)

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 and emits no warning. Since hairpins extend by repetition, a single occurrence has no distinct closing note: it is rendered with the width of the note's duration — the wedge (or the cresc./dim. line) extends from the note to just before the next note's onset, or, if it is the last note of the line, to the right edge of the stave. This is the idiomatic case of the final note of the piece fading in a dim./cresc. al niente, where repeating the sign is impossible by construction.

With a co-located dynamic (graphic hairpin </> + dynamic on the same note) the written order determines the horizontal layout along the note's duration, mirroring the musical meaning:

pp> — dynamic first: the dynamic is the starting one, sits on the onset, and the wedge opens to its right;
>pp — hairpin first: the dynamic is the arrival one, the wedge starts at the onset and the dynamic is placed at the wedge's right end.

Both forms are valid; choose based on where you want the dynamic (start vs arrival). This applies to graphic hairpins; text hairpins (c/d) with a co-located dynamic have no such distinction.

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"]` (`[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
Terminator	`-\\|` last token, glued to the border (closes with no text)	§6.6
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.