Skip to content

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

Open
AvaTheArchitect wants to merge 1 commit into
CoderLine:developfrom
AvaTheArchitect:fix/lyrics-continuation-beats
Open

fix(model): skip tie-destination beats when applying lyrics#2760
AvaTheArchitect wants to merge 1 commit into
CoderLine:developfrom
AvaTheArchitect:fix/lyrics-continuation-beats

Conversation

@AvaTheArchitect

@AvaTheArchitect AvaTheArchitect commented Jul 3, 2026

Copy link
Copy Markdown

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

@AvaTheArchitect
AvaTheArchitect marked this pull request as draft July 3, 2026 18:42
@AvaTheArchitect
AvaTheArchitect marked this pull request as ready for review July 3, 2026 18:46
@AvaTheArchitect AvaTheArchitect mentioned this pull request Jul 3, 2026
Closed
1 task
@Danielku15

Danielku15 commented Jul 4, 2026

Copy link
Copy Markdown
Member

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

image

@AvaTheArchitect

AvaTheArchitect commented Jul 4, 2026 via email

Copy link
Copy Markdown
Author

@AvaTheArchitect

AvaTheArchitect commented Jul 4, 2026 via email

Copy link
Copy Markdown
Author

@Danielku15

Danielku15 commented Jul 5, 2026

Copy link
Copy Markdown
Member

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

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

AvaTheArchitect commented Jul 5, 2026 via email

Copy link
Copy Markdown
Author

@Danielku15

Danielku15 commented Jul 5, 2026

Copy link
Copy Markdown
Member

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

AvaTheArchitect commented Jul 5, 2026 via email

Copy link
Copy Markdown
Author

@AvaTheArchitect

AvaTheArchitect commented Jul 21, 2026 •
edited
Loading

Copy link
Copy Markdown
Author

Hi Daniel,

I have now tracked down the source. I stand corrected, the issue is NOT what we are doing wrong in a bug sense, but rather our system is not optimized to account for GP files with lyrics that are missing the tie-in __ extensions, prior to an export from Songsterr or Ultimate-Guitar or any other XML or GP file export that currently does the same thing.

This is an intentional exported design by Songsterr. Since they have millions of Tabs and arguably the most accurate TAB song library, the issue for any normal end-user that simply wants to upload GP files or XML files to play guitar and sing along with it, may not have a built in Lyric Editor panel like Guitar Pro 8 does now, unless the alphaTex works like this already for an end user? If not, then 100% of all Songsterr songs with lyrics that are exported to GP files used in alphaTab or Guitar Pro will result in the lyrics will be mis-aligned due to the source.

Here is the full report:

=============================================

Songsterr team has provided an update and (at the moment) this is an intentional design. So if you were to use the GP files exported from Songsterr to use on another TAB player like Ultimate-Guitar, or alphaTab, etc. you will need to add a lyric editor as your Lyrics will NOT align correctly due to intentionally leaving the ___ extension data out.

=============================================

Songsterr support:

support@songsterr.com u/songsterr Great bug report — thanks for the detailed reproduction steps and the sample .gp file. You're right: our Guitar Pro export does not write syllable extension markers (the continuation data __), so syllables on tied/held notes shift when the file is opened in Guitar Pro 8.

We use different rules for lyric placement, so we did this intentionally so that if a user first exported the tab, then changed something in the tab (but didn't edit the lyrics), and then uploaded the tab back to us, the lyrics on our platform would not shift.

=============================================

Instructions For External GP File Use With Lyrics:

Since our export intentionally does not add continuation markers __, (that are on all of our song tabs with lyrics) the simplest option is to add them back in the target application after export.

By opening the exported .gp file in Guitar Pro 8 or alphaTab or Ultimate-Guitar (or importing it into another tablature editor / DAW), you can re-enter the syllable extenders there so the text lines up with tied/sustained notes — the text editor in Guitar Pro itself lets you enter the continuation __ directly into the syllable, and that alignment is then carried along with the file into any DAW or third-party application that reads text from GP.

So the sequence is:
export from Songsterr → open in Guitar Pro → fix the text extenders once → save. After that, the file carries the correct alignment wherever you send it next.

If you want to upload tabs with lyrics to us from third-party sources, then we’ll need to adjust the text and add '___' so it lands in the right places.

=============================================

My notes:

So the issue then is not that we have an alphaTab bug, as alphaTab IS working as designed. However, as a result of this discovery and the massive Tab Libraries out there, does alphaTab currently have a built-in lyric editor that could be used to fix every GP file that is uploaded to alphaTab for not just dev or software engineers, but end-users on say an Apple or Google Playstore in the future?

Assuming No Lyric Editor currently like Guitar Pro or Songsterr:

No, alphaTab does not have a built-in interactive lyric editor UI for end-users. alphaTab functions strictly as a rendering engine and playback SDK, meaning it lacks native, user-facing panels to edit, correct, or visually manipulate syllable extenders (__) on the fly.

Because of this architectural design, any logic meant to resolve systemic, third-party lyric misalignment (like the Songsterr tie-in note issue) must be solved programmatically within your PR code rather than relying on the user to fix it via an editor

Current PR Solution Does factor this in Now:

The issue is that it does not align exactly with Guitar Pro which is true, but Guitar Pro is also an editor and not a full player that most of the alphaTab users or end-users (correct me if I am wrong) intended use of it is for. To play Guitar (possibly sing along with the lyrics), Bass or Drums, etc and simply enjoy every moment of it. Let's take a look at some details here and a few possible solutions subject to your approval and guidance on the best direction with it.

=============================================

💡 Architectural Context & Solution Framework

Because alphaTab is an SDK designed for third-party application development, we have two distinct paths forward to address the Songsterr export quirk:

  1. The Core Engine Fix (The Current PR Direction) If the PR introduces an automated parser rule to auto-skip tie-in notes during lyric assignment, this is the most optimal approach.

  • Why it works: It intercepts the raw data array (Lyrics.chunks) right after importing and programmatically aligns syllables only to active beats.

  • Benefit: It shields the 80% of end-users who upload raw files directly from seeing broken layouts. They get a plug-and-play experience on mobile or web apps without needing a complex UI layer.

  1. The App-Level Solution (For Future App Store Deployments)

  • If an app developer wants to provide a lyric editor for end-users on iOS or Google Play, they must build the UI layer themselves utilizing alphaTab's underlying Data Model.

  • The Mechanism: Developers can capture user text input, parse it, and then directly update the text arrays via alphaTab.model.Lyrics.chunks.

  • The Update Loop: Once the strings are modified via code, triggering an alphaTab update or rerender re-engraves the sheet music instantly with the newly aligned lyrics.

=============================================

Proposed Revisions for PR #2760:

  • Double-check the implementation against the automated fallback strategy:
    Confirm that the engine successfully detects a tied note and increments the target beat pointer without consuming a text chunk from the lyric array.

  • Ensure this auto-skip logic does not inadvertently break files that already contain explicit __ or _ extension strings (e.g., standard files exported directly out of Guitar Pro 8). It should gracefully handle both native extenders and raw Songsterr streams.

=============================================

Feature Breakdown:

Feature: Guitar Pro 7/8

Role: Desktop Notation Editor

Lyric UI: Built-in interactive panel

Data Control: Manual insertion of ___ when missing from GP files or XML, etc.



Feature: alphaTab Engine

Role: Cross-platform Rendering SDK

Lyric UI: None (Render output only)

Data Control: Programmatic array parsing



Feature: App-Level Goal

Role: Final Mobile/Web App

Lyric UI: Must be custom-built by devs

Data Control: Custom UI mapping to model

Request:

To have a modern Lyric UI that works on Tab Players that can account for the issues as listed above. Now that we know the source of the issues and that it is not a bug and what can be done.


What would you propose here, looking at the PR code correction that was tested, but currently does not fit the model. Is this something we can make adjustments to that you would consider for a feature solution?

@Danielku15

Danielku15 commented Jul 22, 2026

Copy link
Copy Markdown
Member

So in short: Songsterr produces invalid Guitar Pro files.

It feels a bit that they rather point the fingers to others despite having an a misbehavior in their exporter. If they write Guitar Pro* files they should write them in a way that Guitar Pro* shows correct information. Users shouldn't be required to manually fix the lyrics in external applications. It would be bad if they use GuitarPro files as their storage as backend, and needed to resort to custom adjustments to the format/behaviours to build their desired features. In best case its simply a bug their exporter+importer could handle.

I am not sure if we could detect their quirks on lyrics or if their exported file simply looses the relevant information. e.g. they should apply lyrics to beats and on top level advertise <Lyrics dispatched="true">. If they would cleanly encode some product information in the file we could try to detect Songsterr. e.g. alphaTab injects an XML comment.

On alphaTab side it feels the AI hallucinated quite a bit. It compared apples with pears. alphaTab is an SDK it will obviously not provide a lyrics UI. Thats something your app has to build using functionality we provide.

The raw lyrics are available on Track level, and dispatched lyric syllables are available on beat level. This assumes its written by the source application. Taking this string or syllables you can build an editor UI serving your needs. To apply new lyrics you create a new Lyrics object with the new text set and then call api.score.tracks[0].applyLyrics([lyricsObjectForLine1,...]) on the respective tab.

If you want to force the Songsterr lyrics mode in your app you could also try to do a rewrite for all files yourself in the scoreLoaded event. You would need to make a method similar to our applyLyrics. The lyrics object contains also the parsed chunks/syllables and then you walk the data model and apply the lyrics to the beats as you like.

@AvaTheArchitect

AvaTheArchitect commented Jul 22, 2026 •
edited
Loading

Copy link
Copy Markdown
Author

Yes, I believe for Songsterr it is a bunch of crap or to prevent competitors from having the full GP file potential, so end-users cannot rely on it if they go to another platform like alphaTab or Ultimate-Guitar or any other Tab Player. And yes those AI notes were from a fresh Google AI document search, which is not very liable and certain not one I would ever use code from, since it does not know what is really under the hood.

With the new Songsterr confirmation and the Guitar Pro comparison, I agree that alphaTab should not silently change its default Guitar Pro import semantics.

Since my previous email, Songsterr confirmed that omitting lyric continuation information is an intentional export decision to preserve their own editor workflow and round-trip imports. That clarification significantly changed how I now view the problem.

The current PR’s carry-forward logic correctly repairs the supplied file, but it should not be applied unconditionally to all GP files because a lyric on a tie-destination beat may be intentional or may already be correctly dispatched by the source application.

I would also agree that alphaTab’s default importer should preserve the source file and should not globally reinterpret all Guitar Pro lyrics according to one exporter’s behavior.

My concern is less about Maestro.ai specifically and more about avoiding every alphaTab application independently rediscovering and solving the same interoperability issue. A player built on alphaTab may allow users to upload GP or MusicXML files from Songsterr, Ultimate Guitar, GProTab, MuseScore, or local collections. When an exporter omits lyric continuation information, those users receive visibly displaced lyrics even though the file otherwise loads successfully. Requiring every alphaTab application to build a complete lyric editor or independently implement the same normalization algorithm creates duplicated work across the entire alphaTab community.

After investigating further, I think the original PR is solving a real interoperability problem, but I now agree that it should not become the default Guitar Pro import behavior. Instead, I believe it would fit much better as an optional compatibility feature.

alphaTab already has precedent for opt-in importer compatibility behavior through importer.beatTextAsLyrics. Would you consider restructuring the current PR contribution as an optional lyric-dispatch compatibility mode while preserving the existing Guitar Pro import behavior as the default?

One possible model could preserve the current source-faithful behavior by default while offering an optional compatibility strategy that preserves valid extenders and existing dispatched lyrics, but carries syllables across beats containing only tie continuations when continuation data appears to be missing.

The implementation could be exposed through an importer setting, an applyLyrics option, or a reusable dispatch strategy. This would preserve Guitar Pro fidelity by default while giving player-oriented applications a supported solution for incomplete third-party lyric exports.

In my Maestro.ai Guitar Practice Generator, the current implementation already demonstrates one compatibility algorithm that handles both ordinary Guitar Pro files with valid extenders and the supplied Songsterr export. I can adapt that behavior into isolated tests covering valid GP lyrics, missing extenders, tie-only continuations, mixed tied and newly attacked notes, rests, multiple voices, and multiple lyric lines.

I am no longer attached to the current implementation or even the current PR shape. My goal is simply to find the best long-term solution for the broader alphaTab ecosystem.

Would an opt-in compatibility architecture fit alphaTab better than the current PR approach?

Final Notes:

I did another follow up with Support@Songsterr.com and they are still holding there ground here:

"Hi Brett,

But if we do it the way you suggest, users will have to edit the text with us during the re-import. It will be harder to read and edit in our editor. We are primarily interested in the usability of our editor.

Thanks for understanding."


Here is how I see this:


Songsterr:

Internal canonical lyric model
↓
Songsterr Editor
↓
GP Export (optimized for Songsterr round-trip)

Where I think this ultimately lands Ironically, I think all three parties are now "correct."

Guitar Pro:

We expect GP files to contain dispatched lyrics according to our interpretation. Correct.

Songsterr

We optimize exports for our own editing workflow. Also correct.

alphaTab

We should faithfully read GP unless the application explicitly asks for compatibility behavior. Also correct.


Hoping we can find a solution to help everyone!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@AvaTheArchitect @Danielku15