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:

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