🐛 Bug Report: Header and Notation Elements Displaced in Horizontal Layout Mode

[AvaTheArchitect]

https://youtube.com/shorts/X83iBkI8eGo?si=kGMuGQ9BkLh1Iwmy

Staff-attached notation elements (tempo, dynamics, bends) miscalculate vertical position in Horizontal layout mode along with a runaway Header.

First I don't see the option to submit this under the Bug Category any longer in GitHub, so I apologize if I missed something in advance.

It's my understanding that by default when using alphaTab in the horizontal orientation view that the Header is hidden. Looking back at some of the images and videos I had shared with you previously regards to future implementation of smooth autoscroll and fixed cursor position for the horizontal mode, I discovered this issue was still present then but I didn't realize it then.

I noticed for a while that their is a gap the staff and the tempo or bpm = 104 and other elements of the staff in the horizontal view. But I didn't realize that during the orientation and mode Changes from default synth mode to original mode that the header appears for a millisecond flash and is gone. During the orientation as I studied it closer, it moves upwards and off the screen and seems to pull the staff elements with it.

In the mode changes the header actually takes off to the right of the screen to infinity and beyond!

If AlphaTab is designed to automatically hide the header in LayoutMode.Horizontal, but it still flashes briefly during layout changes — then that means it’s rendering the header in the wrong Z-order or lifecycle stage.

This supports the theory of a “phantom header influence”:
• The header is instantiated during the layout mode switch (Page → Horizontal), even though it should be suppressed.
• It appears for a brief frame or two, long enough to influence the vertical layout of the SVG elements like ♩=104, f, etc.
• Then it disappears visually — but its layout offset remains “baked in” to the SVG Y-coordinate stack.

This is a classic render-time race condition in layout engines, where the internal scoreHeader height is still applied before the visibility flag is respected.

📍 Summary

When switching AlphaTab from Page layout mode to Horizontal layout mode (e.g., on mobile orientation change), notation elements that are attached to the staff such as tempo markings (♩ = …), dynamics (f, mf, etc.), time signature labels (e.g., 1½, 2½), and bend text are vertically misplaced by large amounts (100px–300px). And of course our runaway header upwards or taking off horizontally 10,000 px.
These elements are calculated relative to Page view first and then not recomputed correctly for Horizontal mode.

This is not a settings issue — it is a coordinate computation bug within the core SVG layout engine. Nothing in the public API or settings namespace can remove or reposition these elements correctly after a mode switch.

Affected Notation Elements

The following elements render correctly in Page mode but are displaced in Horizontal mode:
• Tempo markings (e.g., ♩ = 104)
• Dynamic text (e.g., f, mf, etc.)
• Time signature change labels
• Bend text (e.g., “full”)

These are part of the staff notation, not the header.

**What I would Expect
**

I would expect that when the orientation changes to horizontal and mode changes that the staff elements and notations would remain the same and without the gaps suddenly appearing above the staff.

Also if the Header is truly hidden by default of alphaTab for it to actually be hidden and not become visible or become a factor of the now flattened layout in the horizontal view.

✅ Expected Behavior

Notation elements should maintain their relative Y-offset from the staff, regardless of layout mode. Switching layout modes should trigger a recalculation relative to the new baseline.

To look like this:

And not like this:

Or by comparison: (this was from a rendering issue during the orientation changes now fixed but is a good illustration)

🔍 Implication

AlphaTab likely calculates the vertical layout before it fully hides or re-evaluates header visibility in Horizontal mode — so your BPM/dynamics inherit the wrong top offset.

✅ Summary of Your Discovery
• Header is officially hidden in Horizontal mode.
• But it still affects layout, showing up momentarily and shifting tempo/dynamic positions.
• All attempts to prevent this — even destroying the AlphaTab instance and restarting — failed to stop the brief appearance.
• That means the problem is internal to AlphaTab’s layout engine, not API-controllable.

🧩 Additional Discovery: Phantom Header Influence

Although AlphaTab is designed to suppress the header in Horizontal layout, we confirmed that:
• The header still appears briefly during layout transitions (especially from Page → Horizontal).
• This causes tempo/dynamic elements to be displaced as if the header still exists.
• Attempts to prevent this using:
• API settings
• updateSettings()
• api.render()
• Full API destruction and re-initialization
• CSS overrides
All failed.

This confirms the issue is within AlphaTab’s internal render sequence — likely calculating layout using header offsets before the header visibility is correctly enforced.

🧪 Steps to Reproduce

1.	Initialize AlphaTab in Page layout:

const settings = new alphaTab.Settings();
settings.core.engine = 'svg';
settings.display.layoutMode = alphaTab.LayoutMode.Page;

2. Load a score that includes tempo/dynamic/bend markings (e.g., a guitar track with complex notation).
   3. Allow the score to render.
   4. Change layout to Horizontal:

api.settings.display.layoutMode = alphaTab.LayoutMode.Horizontal;
await api.updateSettings();
api.render();

🤯📸 Observational Notes

•	The bug first appeared during mode switching (synth ↔ original), not just orientation change — this delayed detection.
•	The header temporarily appears during transitions (especially orientation flip), then disappears in milliseconds. However, it still influences positioning of the staff-linked elements.
•	A runaway header width issue (10,000px) was previously affecting rendering — now resolved — but the Y-displacement persists.
•	After attempting to fix the header glitch, auto-scroll and seekTo began functioning correctly, confirming linkage between header influence and core layout logic. But the header issues remained along with the rest.

⸻

🧬 Technical Diagnosis

These elements are not ScoreInfo/header components and cannot be toggled with:

api.settings.notation.elements.set(NotationElement.ScoreTitle, false);

api.settings.notation.elements.set(NotationElement.ScoreTitle, false);

🔎 Root Bug

Staff-linked notation elements (tempo, dynamics, bends) are rendered with a correct Y-offset in Page layout but become incorrectly positioned (displaced vertically by 100–300px) in Horizontal layout. This offset becomes worse on tracks with complex notation.

🧬 Why This Happens (Core Bug)

Investigating rendered outputs indicates:
• In Page mode, Y‑offsets are computed relative to system stacks (multiple rows).
• In Horizontal mode, layout flattens into a continuous flow; however, the baseline origin used for the staff elements is still being treated as if in Page mode, causing Y offsets to be wrongly applied.

📁 Environment

•	AlphaTab Version: 1.7.1
•	Next Planned Version: 1.8.0 (ETA unknown)
•	Framework: Next.js 14 + React 18
•	Rendering Engine: SVG
•	Layout Modes: Page ↔ Horizontal (via settings or mobile orientation)
•	Devices Tested: iPhone 15/16 Pro Max (Safari), Android (Chrome), Desktop (Chrome, Edge)
•	File Types: .gp5, .gpx (Guitar Pro)

🪲 Why Settings Don’t Fix It

We have tried:

api.settings.notation.elements.set(NotationElement.ScoreTitle, false);
api.settings.notation.elements.set(NotationElement.ScoreArtist, false);
settings.notation.rhythmMode = TabRhythmMode.Hidden;
settings.display.staveProfile = StaveProfile.Score;

None of these change these staff‑attached elements because they are not exposed as removable header components — they are part of the staff’s rendered SVG.

❓ Questions for AlphaTab Team
1. Is this a known issue in v1.6.3 or any other versions?
2. Is there a recommended official workaround?
3. Is a patch planned in v1.7.1/ v1.8?
4. Can Y‑offset recalculation be forced manually today?
5. I know that you had already made developments for the upcoming 1.8.0 - is there an ETA for that yet as I didn't recall seeing anything mentioned in discussions?

Sorry this is long, let me know if you have any other questions,and thank you!

[AvaTheArchitect]

The very bottom image or last image I shared is what I was able to capture after dozens of attempts right after changing the page view to horizontal view - and appears to show everything with exception of the single unified row still in a page view format, which in the video changes in milliseconds after to what you see.

Some of the other images I shared are actually from screenshots on November 18th with the double cursor or ghost cursor, which we solved as we discovered duplicate canvas creations were being layered under each other and that is now fixed. But the images are a good representation of the timeline differences and showing that the other bug factors were still present even at that time, just overlooked.

[Danielku15]

For bug reports please use https://github.com/CoderLine/alphaTab/issues/new?template=bug_report_form.yml and not discussions. GitHub Discussions are rather for informal discusisons. For actual bug reports use the issue tracker and follow the template there.

Also please try to reduce your report to the core aspects targeting the problem inside alphaTab and eliminate surrounding bits that are specific to your application unless you can provide a full project I can run on my side.

[AvaTheArchitect]

My apologies I thought I used to see a category for bug reports before under the drop down menu… but dont see that anymore? Do you want me to close this one and open a new one under the bug report link now or just going forward? Sorry again for the inconvenience and misplacement. On Thu, Jan 8, 2026 at 12:48 PM Daniel Kuschny ***@***.***> wr:

…

For bug reports please use https://github.com/CoderLine/alphaTab/issues/new?template=bug_report_form.yml and not discussions. GitHub Discussions are rather for informal discusisons. For actual bug reports use the issue tracker and follow the template there. Also please try to reduce your report to the core aspects targeting the problem inside alphaTab and eliminate surrounding bits that are specific to your application unless you can provide a full project I can run on my side. — Reply to this email directly, view it on GitHub <#2486 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/BNLESQBQBCXQRWF622CMCV34F27CFAVCNFSM6AAAAACRDNJ3GCVHI2DSMVQWIX3LMV43URDJONRXK43TNFXW4Q3PNVWWK3TUHMYTKNBUHA4DANI> . You are receiving this because you authored the thread.Message ID: ***@***.***>

[Danielku15]

There is GitHub Discussions which is like a mix between a forum and StackOverflow. This is the area we are in now.

And there is GitHub Issues which is a issue tracker for organizing stuff more project oriented (bugs, features etc.)

[AvaTheArchitect]

Thank you! Again if you want me to move it I can do that? I noticed as I was looking apparently GitHub on IOS 2 step verification has some issues. But I should be able to use a browser or MacBook Pro alternatively. But at least I know where to find it for the future and saved it to my notes.

…

On Thu, Jan 8, 2026 at 1:56 PM Daniel Kuschny ***@***.***> wrote: There is GitHub Discussions <https://docs.github.com/en/discussions/collaborating-with-your-community-using-discussions/about-discussions> which is like a mix between a forum and StackOverflow. This is the area we are in now. And there is GitHub Issues <https://github.com/features/issues> which is a issue tracker for organizing stuff more project oriented (bugs, features etc.) image.png (view on web) <https://github.com/user-attachments/assets/c8b06b17-3427-4b72-9bd5-54f635c2b52d> — Reply to this email directly, view it on GitHub <#2486 (reply in thread)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/BNLESQGKMZMEFVTXXFAQZJD4F3G7HAVCNFSM6AAAAACRDNJ3GCVHI2DSMVQWIX3LMV43URDJONRXK43TNFXW4Q3PNVWWK3TUHMYTKNBUHEYTQOI> . You are receiving this because you authored the thread.Message ID: ***@***.***>

[Danielku15]

Yes, pleas move it and try to make the request more "lightweight". The most important thing is to describe the problem and how to reproduce it. Based on that we can dive into the root cause.