Skip to content

Fix hand assignment for grand-staff pianos imported from MusicXML, Guitar Pro and Capella - #42

Merged
Squarebow merged 2 commits into
Squarebow:devfrom
Shishudy:fix/41-mxl-import-bug
Nov 14, 2026
Merged

Squarebow merged 2 commits into
Squarebow:devfrom
Shishudy:fix/41-mxl-import-bug

Conversation

@Shishudy

Copy link
Copy Markdown

Fixes #41.

Problem

Importing a .mxl/.musicxml (and, by the same mechanism, Guitar Pro/Capella) file with a piano or organ part gave noticeably wrong left/right hand assignment compared to loading a .mid file exported directly from the same notation software.

Root cause

alphaTab (@coderline/alphatab) keeps a whole grand staff on one Track with one shared channel — playbackInfo (program, channel) lives once per Track, not per Staff — and never writes a track-name meta event at all. A notation program's own MIDI export, by contrast, always splits a grand staff into two separate tracks sharing one channel. handAssignment.ts's findStavePairs() specifically looks for that two-tracks-one-channel (or matching RH/LH name) shape to trust a piano's two staves outright; alphaTab-converted files never had that shape, so they always fell through to the generic per-track dividing-line guess instead.

A second, easy-to-miss piece: alphaTab also defaults to SMF Type 0 (single track, channels multiplexed together). Even after splitting the staves into two Track objects sharing one channel, writing them out with the default format silently merges them back into one indistinguishable stream — there's nowhere in a Type 0 file to keep two same-channel tracks apart.

Fix

In src/utils/foreignFormatImport.ts:

  • Split any multi-staff piano/organ track (GM program 0–7 or 16–23, non-percussion) into one track per staff before generation, each keeping the original track's channel — matching the convention MuseScore/Sibelius/Finale already use in their own MIDI export.
  • Set the generated MidiFile's format to MidiFileFormat.MultiTrack (SMF Type 1), so the split tracks actually survive serialisation instead of being multiplexed back onto one channel.

This applies uniformly to MusicXML, Guitar Pro and Capella, since the split runs against alphaTab's shared Score/Track/Staff model after import, regardless of which importer produced it — verified with a Guitar-Pro-shaped multi-channel test case (two separate grand-staff pianos on their own channels) as well as the MusicXML grand-staff and 3-staff-organ cases.

Testing

  • npm run typecheck and npm test (65 files) pass, including a new src/utils/foreignFormatImportTest.ts (14 checks) covering: a grand-staff piano gets a confidence-1 staff pair with correct hands; a 3-staff organ keeps its three staves on one shared channel without crashing the fallback; single-staff keyboard and non-keyboard parts are left untouched; two separate duet pianos each get independently correct hands (never pooled together).
  • Verified end-to-end against the real assignHandsByTrack()/findStavePairs() on dev, not just the old engine.

Built and tested against the current dev (merged in locally before pushing), so it sits on top of the staff-based hand-assignment rework already on dev.

@Squarebow
Squarebow merged commit 205609d into Squarebow:dev Nov 14, 2026
4 checks passed
@Squarebow

Copy link
Copy Markdown
Owner

Thanks a lot, Rafael! Merged into dev with you as the author, so you're in the Contributors list. It'll ship in the next release, and the changelog credits you.

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.

2 participants