fix(model): skip tie-destination beats when applying lyrics

[AvaTheArchitect]

Issues

Related to #2728

Proposed changes

This PR fixes lyric chunks being assigned to beats whose notes are all tie destinations.

Before this change, Track.applyLyrics() skipped empty and rest beats, but pure tie-destination beats were still treated as lyric-eligible. This could cause lyric syllables to appear on tied continuation notes / held-note destinations instead of the next fresh note attack.

Changes included:

• Added a private helper in Track to detect beats where all notes are tie destinations.
• Updated Track.applyLyrics() to skip those beats when distributing lyric chunks.
• Added a focused regression test using AlphaTex:

\track "V" 3.3.4 -.3.4 5.3.4 |

The Test Verifies:

* the first lyric lands on the first fresh note
* the tie-destination beat receives no lyrics
* the next lyric lands on the next fresh note

### Checklist
- [x] I consent that this change becomes part of alphaTab under it's current or any future open source license
- [x] Changes are implemented
- [x] New tests were added 

## Further details
- [ ] This is a breaking change
- [ ] This change will require update of the documentation/website

[Danielku15]

This PR breaks compatibility with the Guitar Pro behavior. In Guitar Pro also tied notes get a lyric chunk applied.

[AvaTheArchitect]

Interesting! I’ll have to sent a support ticket in the Guitar Pro (See details below) In standard music practices real live recordings as a professional singer musician, I would be singing those lyrics way too early and the chorus starts before the chorus starts as a result. So if this is the case the bug moves up even further. According to all standard music websites and Music theory: No, Because a tie merges two identical pitches into a single, continuous sound, the singer does not re-articulate or sing a new syllable on the tied note A tie-in is meant to be a held note, and a singer would hold that for the duration. There cannot be another word on a sustained note. What do you propose? Are you a singer as well? Play the real songs and compare the audio or even YouTube video and you will see the lyrics are way out of alignment if that is true. The singer would have already sung nearly an entire Chorus line before the Chorus even began playing. Why would Guitar Pro do something that does not align with standard music sheets? See message below Also, I have some standard sheet music and musescore that shows that would be musically incorrect: No, standard notation does not place a new lyric syllable under a tied-in note. A tie connects two notes of the same pitch so they are sung as a single, sustained sound. Because no new note is articulated, no new syllable is sung. The rules for lyrics and tied notes: - One syllable per articulation: The syllable remains under the *first* note of the tied pair. Extension lines: If a single syllable is sustained across several tied notes (a melisma), an underscore line (or extender line) is drawn from the syllable to the right. *Arobas Music* (Guitar Pro) July 4th, 2026 Hello, Thanks for reaching out to Arobas Music support. You are entirely right about Guitar Pro's raw internal data structure: Guitar Pro faces persistent engine-level limitations where lyrics mistakenly land on tie-in notes or fail to advance properly when processing raw data imports (such as unquantized MIDI or raw MusicXML) In Guitar Pro 7/8, each syllable maps sequentially to an independent, plucked/sung note attack. When a note is tied to a destination note to sustain a sound, the software is designed to skip the destination note and keeps the syllable sustained. When editing use Guitar Pro's lyric syntax (+). Here is a link to our guide that shows the correct placements are not on tie-in notes: https://blog.guitar-pro.com/wp-content/uploads/2018/10/GuitarPro7-user-guide.pdf lyrics are parsed sequentially to correspond "only" to rhythmic beats that have fresh note attacks Guitar Pro natively treats a tied note as a continuation marker ( isTieDestination) Visual Markers vs. Timeline Attacks In the Guitar Pro desktop editor interface, clicking through beats via the arrow keys *does* let the cursor land on a tied note. Because of this UI quirk, Guitar Pro assigns an internal "lyric chunk index" to every distinct beat slot. When editing use Guitar Pro's lyric syntax (+). If you type text sequentially into Guitar Pro over tied notes, the software automatically holds the active syllable across the duration of the tie. It does not shift the next verse line or syllable forward early. In a real song file, a proper transcriber avoids the desynchronization problem you mentioned by using Guitar Pro's lyric syntax (+). If alphaTab shifts the syllable text forward, it is introducing a massive desynchronization bug that does not exist in native Guitar Pro files. If alphaTab skipped the tied note, it would break the visual rendering of thousands of existing Guitar Pro files. I hope it helps. Musically, Nicolas // Support Team Arobas Music [image: Screenshot 2026-07-04 at 6.32.04 AM.png] [image: Screenshot 2026-07-04 at 6.24.03 AM.png] There are no lyrics at the ends of the tie-in notes and the one is an example from the same songs I showed you in the ticket. https://youtu.be/orWDmO8FCD4?si=8KA97NTs36uy6AVp

…

On Sat, Jul 4, 2026 at 2:54 AM Daniel Kuschny ***@***.***> wrote: *Danielku15* left a comment (CoderLine/alphaTab#2760) <#2760 (comment)> This PR breaks compatibility with the Guitar Pro behavior. In Guitar Pro also tied notes get a lyric chunk applied. image.png (view on web) <https://github.com/user-attachments/assets/35c3e365-b1d6-4782-8863-d010b4b24d34> — Reply to this email directly, view it on GitHub <#2760?email_source=notifications&email_token=BNLESQBEP5JEQEHNPQPL6I35DDH7DA5CNFSNUABFM5UWIORPF5TWS5BNNB2WEL2JONZXKZKDN5WW2ZLOOQXTIOBYGE2TGNJYGE32M4TFMFZW63VGMF2XI2DPOKSWK5TFNZ2KYZTPN52GK4S7MNWGSY3L#issuecomment-4881535817>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/BNLESQECEXIXHW6QWVFJBHT5DDH7DAVCNFSNUABDKJSXA33TNF2G64TZHMYTIOJRGE4TEO2JONZXKZJ3GQ4DANJWGA3DOMRXUF3AE> . You are receiving this because you authored the thread.Message ID: ***@***.***>

[AvaTheArchitect]

Daniel, just a follow up on that. I understand the compatibility concern, but I think there is an important distinction here now based on this new information. I checked Guitar Pro’s own engine-level lyric behavior/resources, and the intended lyric workflow does not appear to be “assign a new syllable to every beat slot, including tie destinations.” Guitar Pro’s lyric syntax provides a way to control lyric advancement, including using `+` to skip/advance placement. This is important because a tied destination is not a fresh note attack — it is a continuation of the previous note. So I think there are two separate layers: 1. The visual/editor beat grid The cursor/editor can still land on tied destination beats, and Guitar Pro may display or store lyric chunks against sequential beat slots. 2. The musical lyric timeline A lyric syllable should correspond to a fresh sung/played onset. A pure tie destination is a continuation, so it should not normally consume the next lyric syllable unless the source explicitly encodes that placement. The examples from standard sheet music / MuseScore show the same convention: when a syllable continues across a held or tied note, it is shown with an extender/continuation line, and the next syllable begins at the next fresh onset. So I do not think the musical issue is incorrect. The question is whether alphaTab’s default should strictly mirror Guitar Pro’s visual/editor grid behavior, or whether it should respect the lyric syntax / onset semantics when distributing lyric chunks. I agree that we should not break existing Guitar Pro visual compatibility by default. If the current PR is too broad, I can rework it so the default remains Guitar Pro-compatible, and the tie-destination skipping behavior becomes parser-aware or optional. Would that be an acceptable direction? On Sat, Jul 4, 2026 at 7:24 AM Brett Bolzenthal ***@***.***> wrote:

…

Interesting! I’ll have to sent a support ticket in the Guitar Pro (See details below) In standard music practices real live recordings as a professional singer musician, I would be singing those lyrics way too early and the chorus starts before the chorus starts as a result. So if this is the case the bug moves up even further. According to all standard music websites and Music theory: No, Because a tie merges two identical pitches into a single, continuous sound, the singer does not re-articulate or sing a new syllable on the tied note A tie-in is meant to be a held note, and a singer would hold that for the duration. There cannot be another word on a sustained note. What do you propose? Are you a singer as well? Play the real songs and compare the audio or even YouTube video and you will see the lyrics are way out of alignment if that is true. The singer would have already sung nearly an entire Chorus line before the Chorus even began playing. Why would Guitar Pro do something that does not align with standard music sheets? See message below Also, I have some standard sheet music and musescore that shows that would be musically incorrect: No, standard notation does not place a new lyric syllable under a tied-in note. A tie connects two notes of the same pitch so they are sung as a single, sustained sound. Because no new note is articulated, no new syllable is sung. The rules for lyrics and tied notes: - One syllable per articulation: The syllable remains under the *first* note of the tied pair. Extension lines: If a single syllable is sustained across several tied notes (a melisma), an underscore line (or extender line) is drawn from the syllable to the right. *Arobas Music* (Guitar Pro) July 4th, 2026 Hello, Thanks for reaching out to Arobas Music support. You are entirely right about Guitar Pro's raw internal data structure: Guitar Pro faces persistent engine-level limitations where lyrics mistakenly land on tie-in notes or fail to advance properly when processing raw data imports (such as unquantized MIDI or raw MusicXML) In Guitar Pro 7/8, each syllable maps sequentially to an independent, plucked/sung note attack. When a note is tied to a destination note to sustain a sound, the software is designed to skip the destination note and keeps the syllable sustained. When editing use Guitar Pro's lyric syntax (+). Here is a link to our guide that shows the correct placements are not on tie-in notes: https://blog.guitar-pro.com/wp-content/uploads/2018/10/GuitarPro7-user-guide.pdf lyrics are parsed sequentially to correspond "only" to rhythmic beats that have fresh note attacks Guitar Pro natively treats a tied note as a continuation marker ( isTieDestination) Visual Markers vs. Timeline Attacks In the Guitar Pro desktop editor interface, clicking through beats via the arrow keys *does* let the cursor land on a tied note. Because of this UI quirk, Guitar Pro assigns an internal "lyric chunk index" to every distinct beat slot. When editing use Guitar Pro's lyric syntax (+). If you type text sequentially into Guitar Pro over tied notes, the software automatically holds the active syllable across the duration of the tie. It does not shift the next verse line or syllable forward early. In a real song file, a proper transcriber avoids the desynchronization problem you mentioned by using Guitar Pro's lyric syntax (+). If alphaTab shifts the syllable text forward, it is introducing a massive desynchronization bug that does not exist in native Guitar Pro files. If alphaTab skipped the tied note, it would break the visual rendering of thousands of existing Guitar Pro files. I hope it helps. Musically, Nicolas // Support Team Arobas Music [image: Screenshot 2026-07-04 at 6.32.04 AM.png] [image: Screenshot 2026-07-04 at 6.24.03 AM.png] There are no lyrics at the ends of the tie-in notes and the one is an example from the same songs I showed you in the ticket. https://youtu.be/orWDmO8FCD4?si=8KA97NTs36uy6AVp On Sat, Jul 4, 2026 at 2:54 AM Daniel Kuschny ***@***.***> wrote: > *Danielku15* left a comment (CoderLine/alphaTab#2760) > <#2760 (comment)> > > This PR breaks compatibility with the Guitar Pro behavior. In Guitar Pro > also tied notes get a lyric chunk applied. > image.png (view on web) > <https://github.com/user-attachments/assets/35c3e365-b1d6-4782-8863-d010b4b24d34> > > — > Reply to this email directly, view it on GitHub > <#2760?email_source=notifications&email_token=BNLESQBEP5JEQEHNPQPL6I35DDH7DA5CNFSNUABFM5UWIORPF5TWS5BNNB2WEL2JONZXKZKDN5WW2ZLOOQXTIOBYGE2TGNJYGE32M4TFMFZW63VGMF2XI2DPOKSWK5TFNZ2KYZTPN52GK4S7MNWGSY3L#issuecomment-4881535817>, > or unsubscribe > <https://github.com/notifications/unsubscribe-auth/BNLESQECEXIXHW6QWVFJBHT5DDH7DAVCNFSNUABDKJSXA33TNF2G64TZHMYTIOJRGE4TEO2JONZXKZJ3GQ4DANJWGA3DOMRXUF3AE> > . > You are receiving this because you authored the thread.Message ID: > ***@***.***> >