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

Proposed changes

Problem

With notation.transpositionPitches (or alphaTex \transpose), the tab subtracts the transposition from the fret and never changes the string. Transposing down turns open strings into negative frets (-4); transposing up pushes notes beyond the neck.

Behavior

When a staff with tablature is transposed, every note is placed on a playable position of the staff's tuning:

• A note keeps its string while the shifted fret is playable there (0 to 24 minus the capo, or higher if the original note already uses a higher fret). Tabs that were valid before render unchanged.
• Notes continuing a tie, slide or hammer-on/pull-off follow the string of their origin, including across barlines.
• Other notes take the free string whose fret is closest to the frets of the beat or of the previous beat. Notes of one chord never share a string.
• Bends, slides, vibrato, tapped notes and hammer-on destinations never land on an open string; pull-offs to an open string are allowed. Trills need a playable trill fret.
• Natural harmonics move to the node that sounds the transposed pitch.
• A note that no string can play keeps its string and its out-of-range fret. It is painted in the new display.resources.tabUnplayableFretColor (default red). If another note of the beat took that string, the note moves to the free string where its fret is closest to the neck instead of overlapping it.
• String-number circles in the standard notation show the displayed string. Left-hand finger numbers on the score staff are hidden for notes that moved or became open strings.

The model is not changed. The positions exist only on the rendered tab, so changing transpositionPitches at runtime takes effect on the next render.

Design

TabFingering decides the positions of a beat while TabBeatGlyph creates its note glyphs. It reads only the beat, the glyphs of earlier beats and the tie/slide/hammer-on links of the notes. The result lives on NoteNumberGlyph (displayString, displayFret, isMoved, isUnplayable); ties, slurs, bends, brushes, flags, the skyline and the staff-line gaps read it from there. Nothing is stored on the model or the layout, and there is no extra model traversal during rendering. A partial render restarts at the bar of the earliest origin of a note in the changed bar, so a placement whose origin is in an earlier system is decided again.

Untransposed staves and percussion staves take the existing path unchanged.

Platform

Fixes for gaps found while implementing this:

• C#/Kotlin runtime: Int8Array; fill/subarray/set for Int16Array and Uint16Array; Kotlin DoubleList.splice now matches JS (it copied the wrong range for removals before the end of the list) and has the inserting overload; Kotlin BooleanList.fill and List.fill return the list.
• Transpiler: compound bitwise assignments (a |= b) cast the right operand to int like plain bitwise operators; a non-null assertion on pop()/shift() of a number array no longer emits .Value in C#.

Measurements

• Over all Guitar Pro files in test-data (342 files, transposed by −4, +3 and +7): moved notes keep the hand movement per beat of a segment-wide beam-search prototype (1.55 vs 1.56 frets), with 3.7% more unplayable notes and slightly wider chords (2.62 vs 2.44 frets).
• Allocation per render of test-data/conversion/full-song.gp, compared with develop: no measurable difference untransposed; about +0.3 MB at −4.

Known limitations and follow-ups

• Chord diagrams, chord names and the barre text are not transposed (as before). A follow-up issue will cover them.
• Placement is greedy per beat without lookahead. Voices are placed independently, so notes of different voices sounding at the same time can share a string.
• A natural harmonic without a node at the transposed pitch is marked unplayable.
• Left-hand finger numbers in the effect-band fingering modes are not hidden for moved notes.
• Possible follow-up: show an unplayable note on its own string next to the note occupying it, instead of moving it to another string.
• The banjo drone string and partial capos are not modelled; all strings count from the same nut and capo.

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

Tests:

• 19 visual tests in GuitarTabs.test.ts (transpose-*), each rendering the original and the transposed track. They cover open strings, chords, ties across barlines, hammer-ons/slides, pull-offs to open strings, bends, natural harmonics, dead notes, trills, ukulele, bass, capo, grace notes, repeated bars and multiple voices.
• TabFingeringPartialUpdate.test.ts: a partial render matches a fresh render when a hammer-on crosses a system boundary.
• TypeScript (2400), C# (2261) and Kotlin (2261) 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
• Docs / release notes updated in website/