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: > ***@***.***> >

[Danielku15]

If somebody writes Guitar Pro files, they write lyrics in a way, using the syntax to ensure the lyrics are assigned as intended. alphaTab ensures that we follow the same logic as Guitar Pro to match the authors intent.

There is no reason why Guitar Pro or alphaTab should actively prevent that somebody can put some sort of lyrics to a tied note beat. If you want no syllable on the tied note, you will write the lyrics accordingly (e.g. adding an additional space).

As the Arobas support says: doing things different in alphaTab would cause a inconsistency with the files written in Guitar Pro.

Here an example: It's a bit hard to recognize, but there are simply two spaces after far to account for the tied note. If somebody would like to write fa ar to indicate the stretch that's also possible.

Technically you might add some "effects" to the second beat (like a bend, accentuation, vibrato) to indicate special singing styles at the second half of a word. You write is a tied note to indicate that the continuous singing of the word without pause, but on the second half you would sing it differently.

alphaTab has two paths for GP6-8 files: if lyrics are already applied to the beats (splitting happened in GP), we take the information as-is from the file:

alphaTab/packages/alphatab/src/importer/GpifParser.ts

Lines 1853 to 1856 in 770d9e5

	case 'Lyrics':
	beat.lyrics = this._parseBeatLyrics(c);
	this._skipApplyLyrics = true;
	break;

Only if there are not lyrics explicitly assigned to beats, we do the assignment on our own.

alphaTab/packages/alphatab/src/importer/GpifParser.ts

Line 182 in 770d9e5

track.applyLyrics(lyrics);

That said: I think there is no bug or misbehavior (neither GP nor alphaTab) but it is by-design to allow placing syllables on tied notes. People author the files accordingly and alphaTab respects all details as good as possible. If you find any discrepancies between GP and alphatab I'm happy to fix things to be aligned.

[AvaTheArchitect]

Hi Daniel, There is a misunderstanding here. Arobas is talking about Raw files, he said if you (alphaTab) are not parsing the GP files correctly and instead moving the lyrics forward on every tie-in note you will end up with thousands of incorrect songs, which is why he said you need to use the + when working with raw files. When you open an authentic, unedited Guitar Pro file directly inside the official Guitar Pro 8 software, the native layout engine reads the spacing data flawlessly. It correctly interprets consecutive spaces, hyphens, and + symbols exactly as the original transcriber intended, skipping over the tied notes and keeping everything perfectly synchronized to the audio. I uploaded the same GP files into Guitar Pro 8 and the same Guns n Roses and Van Halen and the lyrics are NOT landing on the tie-in note, and are parsed correctly on every one of them. So GP files rely on the correct parsing system to detect this. Here is from this from the manual GP files vs Raw or Manually Tabbed: *Guitar Pro 8 user manual in English (Lyrics) page 138/334* * Writing lyrics* The capture area is where you can type in the lyrics properly speaking. Guitar Pro *automatically distributes (parses) each syllable over a different beat. *The change of syllable occurs when a space or + or a hyphen - appears. You may thus use the hyphens to separate syllables in a word. *If you do not wish Guitar Pro to separate two words."*I uploaded the same GP files into Guitar Pro 8 and the same Guns n Roses and Van Halen and the lyrics are NOT landing on the tie-in note, and are parsed correctly on every one of them. So GP files rely on the correct parsing system" *This matches exactly what Arobas is saying:*The claim that "lyrics drifting onto tied notes is normal Guitar Pro behavior" is not accurate. In native Guitar Pro, 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 skips the destination note and keeps the syllable sustained *Here is where you are correct by adding your own lyrics and raw files:* You are entirely right about Guitar Pro's raw layout data structure: if a user types words with just a single space (like *AAA BBB*), Guitar Pro rigidly maps them to the very next sequential layout slot, even if it's a tied destination note. However, according to the Official Guitar Pro 8 User Manual under, 'Writing Lyrics': *Guitar Pro 8 user manual in English (Lyrics) page 138/334* 'Guitar Pro automatically distributes each syllable over a different beat. [...] If you wish to leave a blank on a given beat, just add several hyphens or consecutive spaces.' In real-world song files, transcribers follow this manual rule. They use consecutive spaces or hyphens to leave the tied-in note blank so that the lyric timeline matches the actual audio playback (where a tied note is treated natively as a continuation marker, not a fresh lyric attack). The timeline 'snowball effect' desynchronization happens because alphaTab's parser is currently failing to honor those consecutive spaces/hyphens or the *+* syntax over tied notes/rests. Instead of skipping the beat visually to leave it blank as intended by the transcriber, alphaTab forces the next lyric chunk forward anyway. *The issue alphaTab:* If a user uploads a standard, unedited .gp file, and alphaTab's parser is broken, the engine completely misinterprets those formatting tags. Instead of leaving the tied notes blank as the transcriber intended, alphaTab strips or ignores the +, -, or consecutive spaces, collapsing the array and forwarding the lyrics onto every single tie-in or continuation note. To protect layout compatibility with your screenshot while fixing the synchronization bug for real song files, we should adjust the PR to ensure alphaTab correctly parses these consecutive spaces and syntax characters to leave slots blank when they land on tied notes. What do you think?" When you open an authentic, unedited Guitar Pro file directly inside the official Guitar Pro 8 software, the native layout engine reads the spacing data flawlessly. It correctly interprets consecutive spaces, hyphens, and + symbols exactly as the original transcriber intended, skipping over the tied notes and keeping everything perfectly synchronized to the audio. The software doesn't break its own legacy files because the file binary structures already contain explicit instructions telling Guitar Pro's internal engine how to parse those characters.

…

On Sun, Jul 5, 2026 at 5:00 AM Daniel Kuschny ***@***.***> wrote: *Danielku15* left a comment (CoderLine/alphaTab#2760) <#2760 (comment)> If somebody writes Guitar Pro files, they write lyrics in a way, using the syntax to ensure the lyrics are assigned as intended. alphaTab ensures that we follow the same logic as Guitar Pro to match the *authors* intent. There is no reason why Guitar Pro or alphaTab should actively prevent that somebody can put some sort of lyrics to a tied note beat. If you want no syllable on the tied note, you will write the lyrics accordingly (e.g. adding an additional space). As the Arobas support says: doing things different in alphaTab would cause a inconsistency with the files written in Guitar Pro. Here an example: It's a bit hard to recognize, but there are simply two spaces after far to account for the tied note. If somebody would like to write fa ar to indicate the stretch that's also possible. image.png (view on web) <https://github.com/user-attachments/assets/53d4824f-3dfe-4789-9b6e-5d9c718bebb7> Technically you might add some "effects" to the second beat (like a bend, accentuation, vibrato) to indicate special singing styles at the second half of a word. You write is a tied note to indicate that the continuous singing of the word without pause, but on the second half you would sing it differently. alphaTab has two paths for GP6-8 files: if lyrics are already applied to the beats (splitting happened in GP), we take the information as-is from the file: https://github.com/CoderLine/alphaTab/blob/770d9e5f9fa71e92e08bdeb8b27a7144b1ef1418/packages/alphatab/src/importer/GpifParser.ts#L1853-L1856 Only if there are not lyrics explicitly assigned to beats, we do the assignment on our own. https://github.com/CoderLine/alphaTab/blob/770d9e5f9fa71e92e08bdeb8b27a7144b1ef1418/packages/alphatab/src/importer/GpifParser.ts#L182 That said: I think there is no bug or misbehavior (neither GP nor alphaTab) but it is by-design to allow placing syllables on tied notes. People author the files accordingly and alphaTab respects all details as good as possible. If you find any discrepancies between GP and alphatab I'm happy to fix things to be aligned. — Reply to this email directly, view it on GitHub <#2760?email_source=notifications&email_token=BNLESQH7NT65PILWKJ6P4Q35DI7NHA5CNFSNUABFM5UWIORPF5TWS5BNNB2WEL2JONZXKZKDN5WW2ZLOOQXTIOBYGU4TKNZSHE32M4TFMFZW63VGMF2XI2DPOKSWK5TFNZ2KYZTPN52GK4S7MNWGSY3L#issuecomment-4885957297>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/BNLESQHBNHACI6YNMKBGHHL5DI7NHAVCNFSNUABDKJSXA33TNF2G64TZHMYTIOJRGE4TEO2JONZXKZJ3GQ4DANJWGA3DOMRXUF3AE> . You are receiving this because you authored the thread.Message ID: ***@***.***>

[Danielku15]

You still didn't clearly explain where alphaTab would be doing anything wrong. We use the parsed lyric information from Guitar Pro files if they are embedded. And when we apply things we respect the special syntax constructs of Guitar Pro.

If you think there is a problem. Please prepare a minimal example with concrete references what is wrong. Keep things concise and focus on the concrete problems. No guessing what the theory, alphaTab or Guitar Pro might or might not be doing, no deep analysis. Just show a single concrete example.

Without a single example where we are inconsistent with Guitar Pro I cannot analyze anything

[AvaTheArchitect]

Thanks Daniel, I understand the need for a concrete example. I will run more tests using files from various sources to determine if the lyric extension markers, spaces, or syntax characters are being lost during the parsing process. It appears right now the extension markers __ from the imported GP files are missing or undetected. I want to verify if the spacing information is missing from the specific files I was testing or if the symbols are truly going undetected by alphaTab. Let's put this PR on hold for now until I can provide an independent study and minimal concrete references to illustrate the issue clearly. Thank you for your thorough approach and for your amazing work on this project; it ensures the best possible outcome for the future of alphaTab.

…

On Sun, Jul 5, 2026 at 7:27 AM Daniel Kuschny ***@***.***> wrote: *Danielku15* left a comment (CoderLine/alphaTab#2760) <#2760 (comment)> You still didn't clearly explain where alphaTab would be doing anything wrong. We use the parsed lyric information from Guitar Pro files if they are embedded. And when we apply things we respect the special syntax constructs of Guitar Pro. If you think there is a problem. Please prepare a *minimal* example with concrete references what is wrong. Keep things concise and focus on the concrete problems. No guessing what the theory, alphaTab or Guitar Pro might or might not be doing, no deep analysis. Just show a single concrete example. Without a single example where we are inconsistent with Guitar Pro I cannot analyze anything — Reply to this email directly, view it on GitHub <#2760?email_source=notifications&email_token=BNLESQARWW3KXVHPOQQYKBT5DJQUPA5CNFSNUABFM5UWIORPF5TWS5BNNB2WEL2JONZXKZKDN5WW2ZLOOQXTIOBYGYZTONZWHAYKM4TFMFZW63VGMF2XI2DPOKSWK5TFNZ2KYZTPN52GK4S7MNWGSY3L#issuecomment-4886377680>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/BNLESQEGZKJLANMZ55B7OUD5DJQUPAVCNFSNUABDKJSXA33TNF2G64TZHMYTIOJRGE4TEO2JONZXKZJ3GQ4DANJWGA3DOMRXUF3AE> . You are receiving this because you authored the thread.Message ID: ***@***.***>