[Danielku15]

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 #2822

Proposed changes

A <technical><string> on a staff without tuning is a string indication for the player (e.g. a circled string number in classical guitar music), not a tab position. The importer converted it using the empty staff tuning, which stored invalid strings (0 or negative). Combined with a <fret>, the note became a stringed note with a wrong pitch and NaN MIDI ticks, which silenced playback.

alphaTab now treats a string without a usable tab position as an annotation on the pitched note. Playback and standard notation keep using the written pitch, and no tab is created.

MusicXML import

• No tuning: the string is stored relative to a standard 6-string instrument (note.string) and note.showStringNumber is set. A <fret> is ignored with a warning because it has no meaning without a tuning.
• Tuning present, <string> without <fret>: string number annotation.
• Tuning present, <string> + <fret>: tab position as before.
• Strings outside the available range are dropped with a warning.

Rendering

• String number annotations are also painted for pitched notes, not only for stringed notes.
• New internal Note.getStringCount(staff): the tuning length, or 6 for staves without tuning. The importer, the glyph and alphaTex all use it, so conversions agree.

alphaTex

• The string note property gets an overload with a value for pitched notes, e.g. a4{string 1} (1 = highest string, same numbering as fret.string). This keeps the new model state roundtrip-safe.
• On fretted or percussion notes the value is rejected with the new diagnostic AT221, since their string comes from fret.string. Out-of-range values report AT211.
• The exporter writes string N for pitched notes. The language definitions are regenerated from packages/alphatex.

Related fixes found while testing

• GP7 export changed the input score. To write string/fret for pitched staves, GpifWriter assigns fingerings to the notes and temporarily sets a default tuning. Only the tuning was restored. Afterwards the score played wrong pitches, and a second export wrote a file without tuning and with wrong MIDI values. Gp7Exporter now exports a copy of the score created via the JSON serializer; the backing track audio is shared with the copy because it is not serialized.
• MusicXML: every bar had an additional empty voice (regression from fix(musicxml gp-exporter): optimized handling of more than 4 voices #2831). The first voice mapped on a staff now uses the voice each bar is created with, instead of inserting a new one.
• GP7 exporter tests: the folder roundtrips now only include Guitar Pro files (.gp3, .gp4, .gp5, .gpx, .gp). This replaces the individual MusicXML exclusions, since MusicXML differs too much from the Guitar Pro model for a full roundtrip.

Known limitations (not addressed here)

• On GP7 export, the fingering assignment picks its own strings for pitched notes, so string number annotations do not carry over to the GP file.
• A string-only note on a tab staff with tuning still renders oddly on the tab staff.

Tests

• MusicXML importer: string-only and string + fret, each on staves with and without tuning; out-of-range strings; no non-finite MIDI ticks.
• alphaTex importer: {string N} on pitched notes, AT211 / AT221 diagnostics, export roundtrip.
• New visual test string-numbers-pitched (MusicXML) plus a dedicated alphaTex roundtrip of it.
• GP7 exporter: exporting leaves the score unchanged and a repeated export produces the same file.
• Updated references:
  • 32a-Notations.png now shows the string number of the note marked "string".
  • Four MusicXML importer snapshots no longer contain the empty trailing voice.

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

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