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

Proposed changes

Lyrics always sat in a fixed place: between standard notation and tabs, above the staff for tab-only tracks, and below the staff for tracks without tabs. On guitar tracks, the space above the tab staff is where bends, whammy bar, vibrato and technique texts go, so lyrics there collide with them or need a lot of vertical space. Guitar Pro has a stylesheet setting for this (Above Staff / Below Staff / Hide). This PR adds the same option.

Model

• New RenderStylesheet.lyricsPlacement with the new enum LyricsPlacement: Below (default), Above, Hidden.
• Like in Guitar Pro, the placement is relative to the standard notation staff. If standard notation is not shown, the lyrics go to the next shown staff in the staff cascade (tablature, slash, numbered). A tab-only track therefore shows lyrics below the tabs.

Rendering

• One lyrics effect per side is registered on every staff renderer factory. Glyphs are only created on the cascade-primary staff and only for the stylesheet's placement. The effect band and skyline placement code is unchanged.

Importers / exporters

• alphaTex: \lyricsPlacement below|above|hidden (score metadata). It is exported when not Below.
• Guitar Pro 6–8: System/hideLyrics maps to Hidden and System/drawLyricsUpside maps to Above; Hidden wins if both are set. The exporter writes both keys. The mapping was checked against files saved in Guitar Pro 8 with each option; the Staff/ variants of these keys did not change.
• MusicXML: placement is stored per <lyric>. The score becomes Above only when every lyric has placement="above". Files that mix above and below (e.g. test suite 42a and 43f) keep Below. There is no MusicXML exporter.

UI

• The player settings panel gets a "Lyrics placement" entry.

Visual change for existing scores

• Tab-only tracks: lyrics move from above to below the tab staff.
• Standard notation + tabs: lyrics now sit directly below the standard notation staff, in its bottom effect band. Before, they were in the top band of the tab staff, so they move up slightly.
• Tracks without tabs are unchanged.
• The release notes have an upgrade note for this.

Known difference to Guitar Pro

• With Above, lyrics stack outside tempo, marker and chord texts, following the existing row ordering of effect bands. Guitar Pro draws them below the tempo marking.

Tests

• EffectPlacement.test.ts: which staff and side gets the lyrics for every placement and staff combination, including the cascade order (slash + tabs → tabs) and Hidden.
• AlphaTexImporter.test.ts: parsing, export round-trip, and the error for invalid values.
• Gp8Importer.test.ts: four new Guitar Pro 8 files, one per option. The existing GP8 export round-trip covers them as well.
• MusicXmlImporter.test.ts: all above, mixed, no placement, and the 42a/43f test suite files.
• Visual tests in EffectsAndAnnotations.test.ts: below/above with score+tab, tab only and score only, plus hidden. Two existing references (font-fallback, overlay-rod-multi-staff-aggregation) were updated for the moved lyrics.
• Ran: the full TypeScript test suite. C# and Kotlin builds, plus their test classes for the touched areas (effect placement, alphaTex, GP import/export, MusicXML, JSON, the affected visual suites).

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/