Feature Request: Configurable Scroll Trigger Ratio for Cursor Tracking for ScrollMode#smooth

[comus111]

Description

This feature would allow the cursor to move from the left until it reaches a specific percentage of the notation width. Once reached, the cursor stays visually fixed at that position while the score starts to scroll.

Proposed API

/// The relative horizontal position within the viewport (0.0 to 1.0) 
/// where the cursor should stay fixed while the score scrolls.
///
/// When the cursor reaches this percentage of the viewport width, 
/// alphaTab will start scrolling the score horizontally instead of 
/// moving the cursor further right.
/// Only works if the scroll mode is smooth.

scrollOffsetXRatio: number = 0.5; 

Behavioral Logic

1. Initial Phase: As playback starts, the cursor moves from left to right normally.
2. Trigger: When , the auto-scroll mechanism kicks in.
3. Sticky Phase: The cursor's visual position remains constant (e.g., at 25% or 50% of the notation width), and the music notation starts to scroll/move.
4. End Phase: When the score scrolls to the end and there is no more content to scroll, the cursor releases from its fixed position and moves toward the right edge of the viewport to finish the piece.

---

Use Cases

The "Center-Focus" Reading Mode

• Setting: scrollOffsetXRatio = 0.5
• User Experience: The musician always looks at the center of the screen. This is ideal for performers who want to see an equal amount of "past" notes and "upcoming" notes, reducing eye strain during fast passages.

[Danielku15]

You can implement such specific custom scrolling needs via https://alphatab.net/docs/reference/api/customscrollhandler

It's unlikely we add such a specific behavior to the core of alphaTab.

[AvaTheArchitect]

I think we already did this in the new version 1.8.0 As I had requested the same thing to mirror the Songsterr behavior of a fixed cursor in horizontal or landscape view. The Cursor stays fixed about the second measure and the score is continuously running under the cursor instead. I have not yet tested this since I updated to the 1.8.0 are you on the latest version?

…

On Sun, Jan 25, 2026 at 8:48 AM Comus ***@***.***> wrote: Description This feature would allow the cursor to move from the left until it reaches a specific percentage of the notation width. Once reached, the cursor stays visually fixed at that position while the score starts to scroll. Proposed API /// The relative horizontal position within the viewport (0.0 to 1.0) /// where the cursor should stay fixed while the score scrolls.////// When the cursor reaches this percentage of the viewport width, /// alphaTab will start scrolling the score horizontally instead of /// moving the cursor further right./// Only works if the scroll mode is smooth. scrollOffsetXRatio: number = 0.5; Behavioral Logic 1. *Initial Phase:* As playback starts, the cursor moves from left to right normally. 2. *Trigger:* When , the auto-scroll mechanism kicks in. 3. *Sticky Phase:* The cursor's visual position remains constant (e.g., at 25% or 50% of the notation width), and the music notation starts to scroll/move. 4. *End Phase:* When the score scrolls to the end and there is no more content to scroll, the cursor releases from its fixed position and moves toward the right edge of the viewport to finish the piece. ------------------------------ Use Cases The "Center-Focus" Reading Mode - *Setting:* scrollOffsetXRatio = 0.5 - *User Experience:* The musician always looks at the center of the screen. This is ideal for performers who want to see an equal amount of "past" notes and "upcoming" notes, reducing eye strain during fast passages. — Reply to this email directly, view it on GitHub <#2522>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/BNLESQCZELLNXJCXBVFAX7L4ITXVFAVCNFSM6AAAAACS2RXCN2VHI2DSMVQWIX3LMV43ERDJONRXK43TNFXW4OZZGM4DOMBUGI> . You are receiving this because you are subscribed to this thread.Message ID: ***@***.***>

[AvaTheArchitect]

I thought we added something similar for the smooth scroll in 1.8.0 didn’t we already?

…

On Sun, Jan 25, 2026 at 11:13 AM Daniel Kuschny ***@***.***> wrote: You can implement such specific custom scrolling needs via https://alphatab.net/docs/reference/api/customscrollhandler It's unlikely we add such a specific behavior to the core of alphaTab. — Reply to this email directly, view it on GitHub <#2522 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/BNLESQFPDE6Z3V647TWWLW34IUIWHAVCNFSM6AAAAACS2RXCN2VHI2DSMVQWIX3LMV43URDJONRXK43TNFXW4Q3PNVWWK3TUHMYTKNJZHE3TIMQ> . You are receiving this because you are subscribed to this thread.Message ID: ***@***.*** com>

[comus111]

@AvaTheArchitect I have tried the latest and scrollOffsetX that is similar to this use case, but it uses fixed horizontal pixel offset. So we hope there is something like scrollOffsetXRatio that uses e.g., 25% or 50% of the viewport width.

[AvaTheArchitect]

Is what you are looking for similar to Songsterr in landscape or horizontal? I am hoping to work on this myself tomorrow and if I can figure something out, I am happy to shave some code snippets.

…

On Sun, Jan 25, 2026 at 4:44 PM Comus ***@***.***> wrote: @AvaTheArchitect <https://github.com/AvaTheArchitect> I have tried the latest and scrollOffsetX that is similar to this use case, but it uses fixed horizontal pixel offset. So we hope there is something like scrollOffsetXRatio that uses e.g., 25% or 50% of the viewport width. — Reply to this email directly, view it on GitHub <#2522 (reply in thread)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/BNLESQHSDAAIQM4RVXMJHOT4IVPN3AVCNFSM6AAAAACS2RXCN2VHI2DSMVQWIX3LMV43URDJONRXK43TNFXW4Q3PNVWWK3TUHMYTKNRQGEYTIMQ> . You are receiving this because you were mentioned.Message ID: ***@***.***>

[Danielku15]

The default scroll handlers can be looked at here:

alphaTab/packages/alphatab/src/ScrollHandlers.ts

Lines 331 to 398 in 8d3bc71

	export class HorizontalSmoothScrollHandler<TSettings> implements IScrollHandler {
	private _api: AlphaTabApiBase<TSettings>;
	private _lastScroll = -1;
	private _scrollContainerResizeUnregister: () => void;
	public constructor(api: AlphaTabApiBase<TSettings>) {
	this._api = api;
	// we need a resize listener for the overflow calculation
	this._scrollContainerResizeUnregister = api.uiFacade.getScrollContainer().resize.on(() => {
	const scrollContainer = api.uiFacade.getScrollContainer();
	const overflowNeeded = api.settings.player.scrollOffsetX;
	const viewPortSize = scrollContainer.width;
	// the content needs to shift out of screen (and back into screen with the offset)
	// that's why we need the whole width as additional overflow
	const overflowNeededAbsolute = viewPortSize + overflowNeeded;
	api.uiFacade.setCanvasOverflow(api.canvasElement, overflowNeededAbsolute, false);
	});
	}
	[Symbol.dispose]() {
	this._scrollContainerResizeUnregister();
	this._api.uiFacade.setCanvasOverflow(this._api.canvasElement, 0, false);
	}
	public forceScrollTo(currentBeatBounds: BeatBounds): void {
	const ui = this._api.uiFacade;
	const settings = this._api.settings;
	const scroll = ui.getScrollContainer();
	const barStartX: number = currentBeatBounds.onNotesX + settings.player.scrollOffsetY;
	ui.scrollToY(scroll, barStartX, 0);
	this._lastScroll = -1;
	}
	public onBeatCursorUpdating(
	_startBeat: BeatBounds,
	_endBeat: BeatBounds | undefined,
	_cursorMode: MidiTickLookupFindBeatResultCursorMode,
	actualBeatCursorStartX: number,
	actualBeatCursorEndX: number,
	actualBeatCursorTransitionDuration: number
	): void {
	const ui = this._api.uiFacade;
	if (actualBeatCursorEndX === this._lastScroll && actualBeatCursorTransitionDuration > 0) {
	return;
	}
	// jump to start of new system
	const settings = this._api.settings;
	const scroll = ui.getScrollContainer();
	ui.scrollToX(scroll, actualBeatCursorStartX + settings.player.scrollOffsetX, 0);
	// instant scroll
	if (actualBeatCursorTransitionDuration === 0) {
	this._lastScroll = -1;
	return;
	}
	this._lastScroll = actualBeatCursorEndX;
	const scrollX = actualBeatCursorEndX + settings.player.scrollOffsetX;
	ui.scrollToX(scroll, scrollX, actualBeatCursorTransitionDuration);
	}
	}

Based on that you might be able to build what you need considering a ratio offset. As you can see alphaTab needs to "reserve" additional paddings to ensure the cursor can stay in place at the respective position. Just like in the original implementation you'd then apply paddings and offsets accordingly. Instead of a fixed offset you simply calculate the ratio using the sizes of the viewport.

Or you simply listen to the resize of your viewport and update the padding to the absolute calculated value. It's a matter of programming what you need, I think all building blocks are available.