[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 #2802

Proposed changes

Tunings keep the sharp or flat spelling of every string (F#3 vs Gb3) from import to rendering and export. The tuning display shows the accidentals as ♯ and ♭.

One representation of a written pitch

• The new public SpelledPitch is an immutable value: step, alter and octave, plus the derived MIDI value.
• It replaces the internal TuningParseResult and ResolvedSpelling types and their duplicated lookup tables. ModelUtils.resolveSpelling and the new ModelUtils.parsePitch (same acceptance rules as before) return it.
• resolveSpelling no longer allocates closures for its candidate lookups.

Tuning model

• Tuning.pitches is the stored tuning.
• Tuning.tunings is derived from it; setting it spells the strings with flats, as before.
• The score JSON writes pitches as text ("D#4") and still reads the tunings values of earlier versions (@json_read_only).
• The serializer generator now supports arrays of @json_immutable values.

Formats

• alphaTex: \tuning keeps the spelling as written and exports it back.
• Guitar Pro:
  • A tuning with the Flat element is spelled with flats, all others with sharps. This was checked against Guitar Pro 8 files saved with sharp and with flat display.
  • The exporter writes flats unless every string with an accidental is spelled sharp, because Guitar Pro has only one choice per tuning.
  • Guitar Pro 6 files never contain the element, so they show sharps.
• MusicXML: tuning-step and tuning-alter give the spelling.

Rendering

• The score tuning and the staff tuning draw the names as text with ♯ ♭ 𝄪 𝄫.
• Natural tunings render unchanged.
• This needed alphaSkia 4.0.157, which aligns text mixing several fonts like the HTML5 canvas. Before, a fallback glyph (here from Noto Music) moved the whole line down.

Other

• Kotlin runtime: indexed DoubleList.map and List.slice(start, end).
• Number.isInteger in the C# and Kotlin runtimes.
• C# test runtime: Expect(Action, string).
• Tuning.noteNames, getTextForTuning and getTextPartsForTuning are deprecated and unchanged.

Behaviour notes (also in the release notes)

• Changing the array returned by Tuning.tunings in place no longer changes the tuning; assign a new array instead.
• The score JSON contains pitches instead of tunings.
• Guitar Pro tunings with accidentals and no flat flag, including all Guitar Pro 6 files, show sharps instead of flats.

Reference images

• Tuning references with accidentals changed.
• The alphaSkia update changed several MusicXML and general references.
• alphaSkia 4's FreeType mode falls back to fonts installed on the machine. The visual tests therefore register Noto Sans SC (CJK texts) and Noto Sans Math (symbols like arrows and ⍉) and list them in the font families. All characters the tests draw now come from fonts in the repository.

Tests

• New tests for SpelledPitch, the tuning pitches and their JSON form, alphaTex, Guitar Pro 6/8 and MusicXML import and export, and the round trips.
• Visual tests for the score and staff tuning with accidentals and for the Guitar Pro test file.
• Local runs: TypeScript 2527/2527, C# 2352/2352, Kotlin 2352/2352.

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
• Docs / release notes updated in website/