Skip to content

fix(importer): read MusicXML fingering digits by instrument convention - #2927

Merged
Danielku15 merged 3 commits into
developfrom
fix/2826-musicxml-guitar-fingering
Oct 7, 2026
Merged

Danielku15 merged 3 commits into
developfrom
fix/2826-musicxml-guitar-fingering

Conversation

@Danielku15

Copy link
Copy Markdown
Member

Note

AI-authored disclosure (alphatab-ai-authored-v1)

Portions of this content were authored by an AI agent. The agent has read
AGENTS.md and the human submitter accepts responsibility for
compliance with the rules in that document.

Issues

Fixes #2826

Proposed changes

The MusicXML importer read <fingering> digits with keyboard numbering (1 = thumb) on every instrument. On guitar and other non-piano parts a written 1 (index) therefore became the thumb and was shown as t, and every other finger was off by one.

Why the numbering depends on the instrument:

  • The MusicXML spec leaves finger numbering open. <fingering> is free text, "typically indicated 1,2,3,4,5" (w3c-cg/musicxml#438: "any string value is valid").
  • In practice, keyboards and the plucking hand write 1 = thumb. Fretted and bowed left hands write 0 = open and 1–4 = index…little (MuseScore, Finale, Dorico).
  • alphaTab's renderer already displays fingers this way (FingeringGroupGlyph.fingerToMusicFontSymbol), switching on GeneralMidi.isPiano(program). Only the importer ignored the instrument.

What changes (in _parseFingering, still a single switch):

written non-piano <fingering> piano <fingering> and <pluck>
0 open open
1 / 2 / 3 / 4 Index / Middle / Annular / Little Thumb / Index / Middle / Annular (unchanged)
5 Thumb (only finger not covered by 1–4) Little (unchanged)
p, t, T Thumb Thumb
i / m / a Index / Middle / Annular Index / Middle / Annular
c, e, o, q, s, x Little Little
  • The non-piano mapping applies only to <fingering> on tracks where GeneralMidi.isPiano(program) is false. That is the same check the renderer uses, so fingerings display as written.
  • Every input accepted before is still accepted.
  • T and the SMuFL little-finger letters e o q s x are new. Letters now match case-insensitively.
  • A doc comment on _parseFingering records this reasoning.
  • No model, renderer or settings changes.
  • Existing test-suite files with fingering (32a, 34b, 34c) have no <midi-program>, so they count as piano and are unaffected.

Checklist

  • I consent that this change becomes part of alphaTab under its current or any future open source license
  • This PR is linked to an accepted issue (see above)
  • Changes are implemented
  • New tests were added
  • I have read AGENTS.md if an AI helped draft any part of this PR

New test: MusicXmlImporterTests > fingering, using test-data/musicxml4/fingering.xml. It has a guitar part and a piano part, each with every input value as <fingering> and as <pluck>, and it checks every column of the table above. The TypeScript, C# and Kotlin test suites pass.

AI authorship disclosure

  • No AI agent authored any part of this PR (description, code, tests, or commit messages)
  • An AI agent contributed to this PR. The AI-authored disclosure block
    (alphatab-ai-authored-v1) is present at the top of this body, and I have
    personally reviewed every change and can explain each one

Further details

  • This is a breaking change
  • This change will require update of the documentation/website

On non-piano parts <fingering> digits now follow the fretting hand
numbering (0 = open, 1 = index ... 4 = little, 5 = thumb) instead of the
keyboard numbering, matching how the renderer displays fingers.
Adds the remaining SMuFL fingering letters (T, e, o, q, s, x) and
case-insensitive matching.

Fixes #2826
@Danielku15
Danielku15 merged commit 8cb7412 into develop Oct 7, 2026
6 checks passed
@Danielku15
Danielku15 deleted the fix/2826-musicxml-guitar-fingering branch October 7, 2026 10:34
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

MusicXML: <fingering> on a fretted instrument imports one finger too low (written 1 becomes thumb)

1 participant