Fingering (`$)` row)¶

STATUS: SPEC. Marker, order and datapack grammar are defined in neumaRk_datapack.md §2.1, §3 and §3.bis.1. History in neumaRk_changelog.md, What's new in 0.6.

1. Definition¶

The $) row (Fingering) carries, position by position, the fingering indications for the events of the notes row it is bound to:

the pressing finger (left hand on string instruments, the hand's finger on the piano), including finger substitution;
the string on which the note is played;
the plucking finger (right hand, guitar and the like);
the fixed position: a bracket holding the hand in one position over a stretch of notes.

It is a parallel layer, like A): it does not alter rhythm, durations or flow. It is purely graphical: no effect on the musical content or on execution.

$) | .  2A[ 3 1 3 4] 1B["C II" 3] |
N) | a8 b   c d e f  g          a  |

2. Structural position and binding¶

Marker $): 2 characters wide like the other line markers, it is the only one whose first character is not an uppercase letter.
Always explicit. The implicit line-type deduction (neumaRk_datapack.md §3.bis) never produces a fingering row: without the $) marker the line is classified like any other line without a marker.
Binding. A $) fingers the first notes line below it (N), N+ or N2); the group's A) may sit in between. It never binds to the chord rhythm of a C).
Canonical order of the lines:

M)  C)  $)  A)  N)  D)  L)  F)

Fingering sits above articulation: in the rendering the articulation is closest to the notehead, the fingering further out. - Voice 2. The N2 group has its own $), independent of voice 1's, like its own A) (neumaRk_voices.md §3.1). - Orphan $). A $) with no notes line below it (another $) comes first, or the datapack ends) fingers nothing: it is ignored and the parser emits W174 (W174.fingering_orphan).

$) | 1 2 3 4 |
A) | > . . ! |
N) | c4 d e f |     // the $) skips the A) and fingers the N)

3. Count-based alignment¶

The correspondence with the events of the notes row is positional by count, left to right, with the same rules as A) (neumaRk_articulations.md §4):

one token per event;
rests, the arrival note of a tie ^ and the slash / count (a run of slashes is a single slot);
grace notes do not count: they belong to their main note;
the N) prolongation . (neumaRk_notes_and_durations.md §4) counts as a slot; but a non-empty token at that position would merge into the previous note, so it is ignored with W181 (W181.fingering_prolongation): write the fingering on the note itself;
the token . alone = no fingering on that note;
if the tokens are fewer than the events, the remaining notes have no fingering;
if the tokens are more than the events, the extra ones are ignored and the parser emits W131 (W131.excess_fingering);
the | of the row are real barlines, as in A): they separate the measures, and a fixed position [ … | … ] crosses them (§7).

A fingering on a rest is ignored with W181 (W181.fingering_rest).

4. The token¶

4.1 The three parts¶

A token is made of up to three parts, always in this order:

#	Part	Alphabet	Examples
1	pressing finger	one digit `0`–`5`, or the substitution `n-m`	`3`, `0`, `4-1`, `1-2`
2	string	name `A`–`G` optionally followed by `b` or `#`, or number `1`–`9`	`A`, `Bb`, `F#`, `3`
3	plucking finger	one of `p` `i` `m` `a` `c` (`c` = little finger)	`p`, `m`

The three parts are written together, without spaces. Examples:

Token	Meaning
`1`	finger 1
`0A`	open string (finger 0) on the A string
`2Bb`	finger 2 on the B♭ string
`4-5`	substitution: finger 4, then finger 5 on the same note
`1-2G`	substitution 1→2 on the G string
`13`	finger 1 on string 3
`3m`	finger 3, plucked with the middle finger
`0Ap`	open A string, plucked with the thumb

The finger is always a single digit (or an n-m pair): in 13 the first digit is the finger, the second the string.

4.2 The dot: skipped note and empty part¶

The . character has two roles, told apart by its position:

. alone, as a whole token, skips the note: no fingering at that position (as in A) and D)).
. attached to other parts stands for an empty part:

Token	Meaning
`.2`	string 2, no finger (`2` alone would be finger 2)
`.G`	the G string only
`..m`	the plucking finger only

Since the three alphabets are disjoint, the attached . is required only for a numeric string without finger (.3). Elsewhere it is optional: G = .G, p = ..p. The reference form is the shortest one.

4.3 Malformed token¶

A token that does not follow the grammar of §4.1 (unknown part, parts out of order) is ignored as a whole and the parser emits W180: the note has no fingering.

5. Chords `<…>`¶

Above a chord, the <…> group gives one entry per pitch, in the source order of the chord in the N) row. Each entry is a §4.1 token; a . inside the group skips a pitch.

$) | <1G 3B 0E> <1 . 4> |
N) | <c e g>2   <c e g>  |   // c: finger 1 string G, e: 3 on B, g: open E string
                            // then c: 1, e: nothing, g: 4

Fewer entries than pitches: the remaining pitches have no fingering.
More entries than pitches: the extra ones are ignored with W181 (W181.fingering_chord_excess).
A <…> above a single note uses only the first entry, with W181 (W181.fingering_not_chord).
A token without <…> above a chord fingers the chord's first pitch.

6. Finger placement: prefixes `'` `-` `+`¶

A token whose first character is ', - or + sets where the numbers of the pressing finger are written:

Prefix	Placement
`'`	above the noteheads
`-`	left of the noteheads
`+`	right of the noteheads

$) | -<1 3 5> '3 +2 4 |
N) | <c e g>4  d  e  f |   // chord on the left, d above, e and f on the right

The choice applies from that note on, for that staff and voice, across datapacks and systems, until the next prefix.
Before any prefix: above for single notes, left for chords.
A prefix may stand on a token without finger ('.): it sets the placement from that note, without fingering it.
The prefixes concern only the pressing finger: the string is always below, the plucking finger always above (§8).

7. Fixed position `[ … ]`¶

A fixed position is a span marking a stretch played holding the hand in one position. It follows the rules of the A) analysis bracket { } (neumaRk_articulations.md §10.3):

[ opens on its token's note, ] closes on its token's note.
[ and ] attach before or after the rest of the token: 2A[, [1, 4].
In the same token, ][ closes and reopens (chained positions):

$) | [1 ][2 ] |
N) | c4 d  e f |   // one position from c to d, the next from d to e

Optional label, right after [: 1B["C II" 3]. It is a text-markup container like the analysis-bracket label (neumaRk_text_markup.md §2.2). Without a label, the bracket is drawn with no text.
It crosses barlines and systems: the span lives on the logical staff (neumaRk_datapack.md §4.5), per voice.
One position at a time: a second [ while one is open is ignored together with the ] that closes it (W144, W144.position_open_overlap).
Orphan ] → W144 (W144.position_close_unmatched), ignored.
[ and ] on the same note ([]) → degenerate, W144 (W144.position_degenerate), ignored.
Position never closed → W144 (W144.position_unclosed_eol) and implicit close on the last note of the system where it opens.
Rendering: square bracket above the staff, with the arms pointing down towards the notes, like the analysis bracket; the label left-aligned above the opening.

$) | 1 [ |
N) | c2 d |

$) | 2 ] |
N) | c2 d |     // fixed position from the d of the first system to the d of the second

8. Rendering¶

Part	Placement	Style
pressing finger	above the note (default), or left/right by prefix (§6)	number; the substitution `4-5` as a single text
string	below the note	circled name or number
plucking finger	above the note	italic
fixed position	above the staff	square bracket with arms down

Above a chord, the fingers above the noteheads stack in the same vertical order as the notes. With the stem up, the stack starts above the stem tip.

How a renderer draws these signs (glyphs, sizes, distances) is not normative; their meaning and placement (above, below, beside) are.

9. Diagnostics¶

Code	Case	Effect
`W131.excess_fingering`	tokens in excess of the measure's events	extra ignored
`W144.position_open_overlap`	second `[` while a position is open	ignored with its `]`
`W144.position_close_unmatched`	`]` without opening	ignored
`W144.position_degenerate`	`[` and `]` on the same note	ignored
`W144.position_unclosed_eol`	position never closed	closed on the last note of the system where it opens
`W174.fingering_orphan`	`$)` with no notes line below	row ignored
`W180`	malformed token	token ignored
`W181.fingering_rest`	fingering on a rest	ignored
`W181.fingering_prolongation`	non-empty token on a prolongation `.`	ignored
`W181.fingering_not_chord`	`<…>` on a single note	first entry used
`W181.fingering_chord_excess`	`<…>` with more entries than pitches	extra ignored

All cases are non-blocking warnings.

10. Examples¶

$) | 0A 2Bb 4-5 1-2G | 13 .3 ..p 0Ai | <1G 3B 0E> . |
A) | >               |
N) | a8 b c d r2     | e4 f g a      | <c e g>2 r   |

measure 1: a open A string (with the accent of the A)), b finger 2 on B♭, c substitution 4→5, d substitution 1→2 on the G string; the rest has no token;
measure 2: e finger 1 on string 3, f string 3 only, g plucking thumb only, a open A string plucked with the index finger;
measure 3: chord fingered pitch by pitch; the . skips the rest.

$) | .  2A[ 3 1 3 4] 1B["C II" 3] |
N) | a8 b   c d e f  g          a  |

Fixed position without label from b to f, then position "C II" from g to a.

Fingering ($) row)¶