@coderline/alphatab 1.8.0-alpha.1650 → 1.8.0-alpha.1653

package/dist/alphaTab.js

@@ -1,5 +1,5 @@
 /*!
- * alphaTab v1.8.0-alpha.1650 (develop, build 1650)
+ * alphaTab v1.8.0-alpha.1653 (develop, build 1653)
  *
  * Copyright © 2025, Daniel Kuschny and Contributors, All rights reserved.
  *
@@ -209,9 +209,9 @@
      * @internal
      */
     class VersionInfo {
-        static version = '1.8.0-alpha.1650';
-        static date = '2025-12-20T02:07:19.755Z';
-        static commit = '5789b59da2b7f8897debe003c9b75e4d48b5e9b3';
+        static version = '1.8.0-alpha.1653';
+        static date = '2025-12-23T02:21:29.054Z';
+        static commit = 'b85546e1908f06f3bd049e35e881c4856fb92846';
         static print(print) {
             print(`alphaTab ${VersionInfo.version}`);
             print(`commit: ${VersionInfo.commit}`);
@@ -13095,7 +13095,7 @@
      */
     class MasterBarBounds {
         /**
-         * Gets or sets the index of this bounds relative within the parent lookup.
+         * The MasterBar index within the data model represented by these bounds.
          */
         index = 0;
         /**
@@ -13303,6 +13303,7 @@
                     mb.visualBounds = this._boundsToJson(masterBar.visualBounds);
                     mb.realBounds = this._boundsToJson(masterBar.realBounds);
                     mb.index = masterBar.index;
+                    mb.isFirstOfLine = masterBar.isFirstOfLine;
                     mb.bars = [];
                     for (const bar of masterBar.bars) {
                         const b = {};
@@ -13359,7 +13360,7 @@
                     mb.lineAlignedBounds = BoundsLookup._boundsFromJson(masterBar.lineAlignedBounds);
                     mb.visualBounds = BoundsLookup._boundsFromJson(masterBar.visualBounds);
                     mb.realBounds = BoundsLookup._boundsFromJson(masterBar.realBounds);
-                    sg.addBar(mb);
+                    lookup.addMasterBar(mb);
                     for (const bar of masterBar.bars) {
                         const b = new BarBounds();
                         b.visualBounds = BoundsLookup._boundsFromJson(bar.visualBounds);
@@ -43663,6 +43664,12 @@
          * Scrolling happens as soon the cursors exceed the displayed range.
          */
         ScrollMode[ScrollMode["OffScreen"] = 2] = "OffScreen";
+        /**
+         * Scrolling happens constantly in a smooth fashion.
+         * This will disable the use of any native scroll optimizations but
+         * manually scroll the scroll container in the required speed.
+         */
+        ScrollMode[ScrollMode["Smooth"] = 3] = "Smooth";
     })(exports.ScrollMode || (exports.ScrollMode = {}));
     /**
      * This object defines the details on how to generate the vibrato effects.
@@ -48593,6 +48600,25 @@
         }
     }
 
+    /**
+     * Represents the information related to a resize event.
+     * @public
+     */
+    class ResizeEventArgs {
+        /**
+         * Gets the size before the resizing happened.
+         */
+        oldWidth = 0;
+        /**
+         * Gets the size after the resize was complete.
+         */
+        newWidth = 0;
+        /**
+         * Gets the settings currently used for rendering.
+         */
+        settings = null;
+    }
+
     /**
      * Lists the different position modes for {@link BarRendererBase.getBeatX}
      * @internal
@@ -49019,22 +49045,262 @@
     }
 
     /**
-     * Represents the information related to a resize event.
-     * @public
+     * Some basic scroll handler checking for changed offsets and scroll if changed.
+     * @internal
      */
-    class ResizeEventArgs {
-        /**
-         * Gets the size before the resizing happened.
-         */
-        oldWidth = 0;
-        /**
-         * Gets the size after the resize was complete.
-         */
-        newWidth = 0;
-        /**
-         * Gets the settings currently used for rendering.
-         */
-        settings = null;
+    class BasicScrollHandler {
+        api;
+        lastScroll = -1;
+        constructor(api) {
+            this.api = api;
+        }
+        [Symbol.dispose]() {
+        }
+        forceScrollTo(currentBeatBounds) {
+            this._scrollToBeat(currentBeatBounds, true);
+            this.lastScroll = -1; // force new scroll on next update
+        }
+        _scrollToBeat(currentBeatBounds, force) {
+            const newLastScroll = this.calculateLastScroll(currentBeatBounds);
+            // no change, and no instant/force scroll
+            if (newLastScroll === this.lastScroll && !force) {
+                return;
+            }
+            this.lastScroll = newLastScroll;
+            this.doScroll(currentBeatBounds);
+        }
+        onBeatCursorUpdating(startBeat, _endBeat, _cursorMode, _actualBeatCursorStartX, _actualBeatCursorEndX, _actualBeatCursorTransitionDuration) {
+            this._scrollToBeat(startBeat, false);
+        }
+    }
+    /**
+     * This is the default scroll handler for vertical layouts using {@link ScrollMode.Continuous}.
+     * Whenever the system changes, we scroll to the new system position vertically.
+     * @internal
+     */
+    class VerticalContinuousScrollHandler extends BasicScrollHandler {
+        calculateLastScroll(currentBeatBounds) {
+            return currentBeatBounds.barBounds.masterBarBounds.realBounds.y;
+        }
+        doScroll(currentBeatBounds) {
+            const ui = this.api.uiFacade;
+            const settings = this.api.settings;
+            const scroll = ui.getScrollContainer();
+            const elementOffset = ui.getOffset(scroll, this.api.container);
+            const y = currentBeatBounds.barBounds.masterBarBounds.realBounds.y + settings.player.scrollOffsetY;
+            ui.scrollToY(scroll, elementOffset.y + y, this.api.settings.player.scrollSpeed);
+        }
+    }
+    /**
+     * This is the default scroll handler for vertical layouts using {@link ScrollMode.OffScreen}.
+     * Whenever the system changes, we check if the new system bounds are out-of-screen and if yes, we scroll.
+     * @internal
+     */
+    class VerticalOffScreenScrollHandler extends BasicScrollHandler {
+        calculateLastScroll(currentBeatBounds) {
+            // check for system change
+            return currentBeatBounds.barBounds.masterBarBounds.realBounds.y;
+        }
+        doScroll(currentBeatBounds) {
+            const ui = this.api.uiFacade;
+            const settings = this.api.settings;
+            const scroll = ui.getScrollContainer();
+            const elementBottom = scroll.scrollTop + ui.getOffset(null, scroll).h;
+            const barBoundings = currentBeatBounds.barBounds.masterBarBounds;
+            if (barBoundings.visualBounds.y + barBoundings.visualBounds.h >= elementBottom ||
+                barBoundings.visualBounds.y < scroll.scrollTop) {
+                const scrollTop = barBoundings.realBounds.y + settings.player.scrollOffsetY;
+                ui.scrollToY(scroll, scrollTop, settings.player.scrollSpeed);
+            }
+        }
+    }
+    /**
+     * This is the default scroll handler for vertical layouts using {@link ScrollMode.Smooth}.
+     * vertical smooth scrolling aims to place the on-time position
+     * at scrollOffsetY **at the time when a system starts**
+     * this means when a system starts, it is at scrollOffsetY,
+     * then gradually scrolls down the system height reaching the bottom
+     * when the system completes.
+     * @internal
+     */
+    class VerticalSmoothScrollHandler {
+        _api;
+        _lastScroll = -1;
+        _scrollContainerResizeUnregister;
+        constructor(api) {
+            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, true);
+            });
+        }
+        [Symbol.dispose]() {
+            this._api.uiFacade.setCanvasOverflow(this._api.canvasElement, 0, true);
+            this._scrollContainerResizeUnregister();
+        }
+        forceScrollTo(currentBeatBounds) {
+            const ui = this._api.uiFacade;
+            const settings = this._api.settings;
+            const scroll = ui.getScrollContainer();
+            const systemTop = currentBeatBounds.barBounds.masterBarBounds.realBounds.y + settings.player.scrollOffsetY;
+            ui.scrollToY(scroll, systemTop, 0);
+            this._lastScroll = -1;
+        }
+        onBeatCursorUpdating(startBeat, _endBeat, _cursorMode, _actualBeatCursorStartX, _actualBeatCursorEndX, actualBeatCursorTransitionDuration) {
+            const ui = this._api.uiFacade;
+            const settings = this._api.settings;
+            const barBoundings = startBeat.barBounds.masterBarBounds;
+            const systemTop = barBoundings.realBounds.y + settings.player.scrollOffsetY;
+            if (systemTop === this._lastScroll && actualBeatCursorTransitionDuration > 0) {
+                return;
+            }
+            // jump to start of new system
+            const scroll = ui.getScrollContainer();
+            ui.scrollToY(scroll, systemTop, 0);
+            // instant scroll
+            if (actualBeatCursorTransitionDuration === 0) {
+                this._lastScroll = -1;
+                return;
+            }
+            // dynamic scrolling
+            this._lastScroll = systemTop;
+            // scroll to bottom over time
+            const systemBottom = systemTop + barBoundings.realBounds.h;
+            // NOTE: this calculation is a bit more expensive, but we only do it once per system
+            // so we should be good:
+            // * the more bars we have, the longer the system will play, hence the duration can take a bit longer
+            // * if we have less bars, we calculate more often, but the calculation will be faster because we sum up less bars.
+            const systemDuration = this._calculateSystemDuration(barBoundings);
+            ui.scrollToY(scroll, systemBottom, systemDuration);
+        }
+        _calculateSystemDuration(barBoundings) {
+            const systemBars = barBoundings.staffSystemBounds.bars;
+            const tickCache = this._api.tickCache;
+            let duration = 0;
+            const masterBars = this._api.score.masterBars;
+            for (const bar of systemBars) {
+                const mb = masterBars[bar.index];
+                const mbInfo = tickCache.getMasterBar(mb);
+                const tempoChanges = tickCache.getMasterBar(mb).tempoChanges;
+                let tempo = tempoChanges[0].tempo;
+                let tick = tempoChanges[0].tick;
+                for (let i = 1; i < tempoChanges.length; i++) {
+                    const diff = tempoChanges[i].tick - tick;
+                    duration += MidiUtils.ticksToMillis(diff, tempo);
+                    tempo = tempoChanges[i].tempo;
+                    tick = tempoChanges[i].tick;
+                }
+                const toEnd = mbInfo.end - tick;
+                duration += MidiUtils.ticksToMillis(toEnd, tempo);
+            }
+            return duration;
+        }
+    }
+    /**
+     * This is the default scroll handler for horizontal layouts using {@link ScrollMode.Continuous}.
+     * Whenever the master bar changes, we scroll to the position horizontally.
+     * @internal
+     */
+    class HorizontalContinuousScrollHandler extends BasicScrollHandler {
+        calculateLastScroll(currentBeatBounds) {
+            return currentBeatBounds.barBounds.masterBarBounds.visualBounds.x;
+        }
+        doScroll(currentBeatBounds) {
+            const ui = this.api.uiFacade;
+            const settings = this.api.settings;
+            const scroll = ui.getScrollContainer();
+            const barBoundings = currentBeatBounds.barBounds.masterBarBounds;
+            const scrollLeftContinuous = barBoundings.realBounds.x + settings.player.scrollOffsetX;
+            ui.scrollToX(scroll, scrollLeftContinuous, settings.player.scrollSpeed);
+        }
+    }
+    /**
+     * This is the default scroll handler for horizontal layouts using {@link ScrollMode.OffScreen}.
+     * Whenever the system changes, we check if the new system bounds are out-of-screen and if yes, we scroll.
+     * @internal
+     */
+    class HorizontalOffScreenScrollHandler extends BasicScrollHandler {
+        calculateLastScroll(currentBeatBounds) {
+            return currentBeatBounds.barBounds.masterBarBounds.visualBounds.x;
+        }
+        doScroll(currentBeatBounds) {
+            const ui = this.api.uiFacade;
+            const settings = this.api.settings;
+            const scroll = ui.getScrollContainer();
+            const elementRight = scroll.scrollLeft + ui.getOffset(null, scroll).w;
+            const barBoundings = currentBeatBounds.barBounds.masterBarBounds;
+            if (barBoundings.visualBounds.x + barBoundings.visualBounds.w >= elementRight ||
+                barBoundings.visualBounds.x < scroll.scrollLeft) {
+                const scrollLeftOffScreen = barBoundings.realBounds.x + settings.player.scrollOffsetX;
+                ui.scrollToX(scroll, scrollLeftOffScreen, settings.player.scrollSpeed);
+            }
+        }
+    }
+    /**
+     * This is the default scroll handler for horizontal layouts using {@link ScrollMode.Smooth}.
+     * horiontal smooth scrolling aims to place the on-time position
+     * at scrollOffsetX from a beat-to-beat perspective.
+     * This achieves an steady cursor at the same position with rather the music sheet scrolling past it.
+     * Due to some animation inconsistencies (e.g. CSS animation vs scrolling) there might be a slight
+     * flickering of the cursor.
+     *
+     * To get a fully steady cursor the beat cursor can simply be visually hidden and a cursor can be placed at
+     * `scrollOffsetX` by the integrator.
+     * @internal
+     */
+    class HorizontalSmoothScrollHandler {
+        _api;
+        _lastScroll = -1;
+        _scrollContainerResizeUnregister;
+        constructor(api) {
+            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);
+        }
+        forceScrollTo(currentBeatBounds) {
+            const ui = this._api.uiFacade;
+            const settings = this._api.settings;
+            const scroll = ui.getScrollContainer();
+            const barStartX = currentBeatBounds.onNotesX + settings.player.scrollOffsetY;
+            ui.scrollToY(scroll, barStartX, 0);
+            this._lastScroll = -1;
+        }
+        onBeatCursorUpdating(_startBeat, _endBeat, _cursorMode, actualBeatCursorStartX, actualBeatCursorEndX, actualBeatCursorTransitionDuration) {
+            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);
+        }
     }
 
     /**
@@ -49677,6 +49943,7 @@
         _actualPlayerMode = exports.PlayerMode.Disabled;
         _player;
         _renderer;
+        _defaultScrollHandler;
         /**
          * An indicator by how many midi-ticks the song contents are shifted.
          * Grace beats at start might require a shift for the first beat to start at 0.
@@ -50446,6 +50713,42 @@
             }
         }
         _tickCache = null;
+        /**
+         * A custom scroll handler which will be used to handle scrolling operations during playback.
+         *
+         * @category Properties - Player
+         * @since 1.8.0
+         * @example
+         * JavaScript
+         * ```js
+         * const api = new alphaTab.AlphaTabApi(document.querySelector('#alphaTab'));
+         * api.customScrollHandler = {
+         *   forceScrollTo(currentBeatBounds) {
+         *     const scroll = api.uiFacade.getScrollElement();
+         *     api.uiFacade.scrollToY(scroll, currentBeatBounds.barBounds.masterBarBounds.realBounds.y, 0);
+         *   },
+         *   onBeatCursorUpdating(startBeat, endBeat, cursorMode, relativePosition, actualBeatCursorStartX, actualBeatCursorEndX, actualBeatCursorTransitionDuration) {
+         *     const scroll = api.uiFacade.getScrollElement();
+         *     api.uiFacade.scrollToY(scroll, startBeat.barBounds.masterBarBounds.realBounds.y, 0);
+         *   }
+         * }
+         * ```
+         *
+         * @example
+         * C#
+         * ```cs
+         * var api = new AlphaTabApi<MyControl>(...);
+         * api.CustomScrollHandler = new CustomScrollHandler();
+         * ```
+         *
+         * @example
+         * Android
+         * ```kotlin
+         * val api = AlphaTabApi<MyControl>(...)
+         * api.customScrollHandler = CustomScrollHandler();
+         * ```
+         */
+        customScrollHandler;
         /**
          * The tick cache allowing lookup of midi ticks to beats.
          * @remarks
@@ -51424,7 +51727,6 @@
         _isInitialBeatCursorUpdate = true;
         _previousStateForCursor = PlayerState.Paused;
         _previousCursorCache = null;
-        _lastScroll = 0;
         _destroyCursors() {
             if (!this._cursorWrapper) {
                 return;
@@ -51435,28 +51737,79 @@
             this._beatCursor = null;
             this._selectionWrapper = null;
         }
+        _createCursors() {
+            if (this._cursorWrapper) {
+                return;
+            }
+            const cursors = this.uiFacade.createCursors();
+            if (cursors) {
+                // store options and created elements for fast access
+                this._cursorWrapper = cursors.cursorWrapper;
+                this._barCursor = cursors.barCursor;
+                this._beatCursor = cursors.beatCursor;
+                this._selectionWrapper = cursors.selectionWrapper;
+                this._isInitialBeatCursorUpdate = true;
+            }
+            if (this._currentBeat !== null) {
+                this._cursorUpdateBeat(this._currentBeat, false, this._previousTick > 10, 1, true);
+            }
+        }
         _updateCursors() {
+            this._updateScrollHandler();
             const enable = this._hasCursor;
-            if (enable && !this._cursorWrapper) {
-                //
-                // Create cursors
-                const cursors = this.uiFacade.createCursors();
-                if (cursors) {
-                    // store options and created elements for fast access
-                    this._cursorWrapper = cursors.cursorWrapper;
-                    this._barCursor = cursors.barCursor;
-                    this._beatCursor = cursors.beatCursor;
-                    this._selectionWrapper = cursors.selectionWrapper;
-                    this._isInitialBeatCursorUpdate = true;
-                }
-                if (this._currentBeat !== null) {
-                    this._cursorUpdateBeat(this._currentBeat, false, this._previousTick > 10, 1, true);
-                }
+            if (enable) {
+                this._createCursors();
             }
             else if (!enable && this._cursorWrapper) {
                 this._destroyCursors();
             }
         }
+        _scrollHandlerMode = exports.ScrollMode.Off;
+        _scrollHandlerVertical = true;
+        _updateScrollHandler() {
+            const currentHandler = this._defaultScrollHandler;
+            const scrollMode = this.settings.player.scrollMode;
+            const isVertical = Environment.getLayoutEngineFactory(this.settings.display.layoutMode).vertical;
+            // no change
+            if (this._scrollHandlerMode === scrollMode && this._scrollHandlerVertical === isVertical) {
+                return;
+            }
+            // destroy current handler in favor of new one
+            if (currentHandler) {
+                currentHandler[Symbol.dispose]();
+                const scroll = this.uiFacade.getScrollContainer();
+                this.uiFacade.stopScrolling(scroll);
+            }
+            switch (scrollMode) {
+                case exports.ScrollMode.Off:
+                    this._defaultScrollHandler = undefined;
+                    break;
+                case exports.ScrollMode.Continuous:
+                    if (isVertical) {
+                        this._defaultScrollHandler = new VerticalContinuousScrollHandler(this);
+                    }
+                    else {
+                        this._defaultScrollHandler = new HorizontalContinuousScrollHandler(this);
+                    }
+                    break;
+                case exports.ScrollMode.OffScreen:
+                    if (isVertical) {
+                        this._defaultScrollHandler = new VerticalOffScreenScrollHandler(this);
+                    }
+                    else {
+                        this._defaultScrollHandler = new HorizontalOffScreenScrollHandler(this);
+                    }
+                    break;
+                case exports.ScrollMode.Smooth:
+                    if (isVertical) {
+                        this._defaultScrollHandler = new VerticalSmoothScrollHandler(this);
+                    }
+                    else {
+                        this._defaultScrollHandler = new HorizontalSmoothScrollHandler(this);
+                    }
+                    break;
+            }
+        }
         /**
          * updates the cursors to highlight the beat at the specified tick position
          * @param tick
@@ -51519,57 +51872,9 @@
         scrollToCursor() {
             const beatBounds = this._currentBeatBounds;
             if (beatBounds) {
-                this._internalScrollToCursor(beatBounds.barBounds.masterBarBounds);
-            }
-        }
-        _internalScrollToCursor(barBoundings) {
-            const scrollElement = this.uiFacade.getScrollContainer();
-            const isVertical = Environment.getLayoutEngineFactory(this.settings.display.layoutMode).vertical;
-            const mode = this.settings.player.scrollMode;
-            if (isVertical) {
-                // when scrolling on the y-axis, we preliminary check if the new beat/bar have
-                // moved on the y-axis
-                const y = barBoundings.realBounds.y + this.settings.player.scrollOffsetY;
-                if (y !== this._lastScroll) {
-                    this._lastScroll = y;
-                    switch (mode) {
-                        case exports.ScrollMode.Continuous:
-                            const elementOffset = this.uiFacade.getOffset(scrollElement, this.container);
-                            this.uiFacade.scrollToY(scrollElement, elementOffset.y + y, this.settings.player.scrollSpeed);
-                            break;
-                        case exports.ScrollMode.OffScreen:
-                            const elementBottom = scrollElement.scrollTop + this.uiFacade.getOffset(null, scrollElement).h;
-                            if (barBoundings.visualBounds.y + barBoundings.visualBounds.h >= elementBottom ||
-                                barBoundings.visualBounds.y < scrollElement.scrollTop) {
-                                const scrollTop = barBoundings.realBounds.y + this.settings.player.scrollOffsetY;
-                                this.uiFacade.scrollToY(scrollElement, scrollTop, this.settings.player.scrollSpeed);
-                            }
-                            break;
-                    }
-                }
-            }
-            else {
-                // when scrolling on the x-axis, we preliminary check if the new bar has
-                // moved on the x-axis
-                const x = barBoundings.visualBounds.x;
-                if (x !== this._lastScroll) {
-                    this._lastScroll = x;
-                    switch (mode) {
-                        case exports.ScrollMode.Continuous:
-                            const scrollLeftContinuous = barBoundings.realBounds.x + this.settings.player.scrollOffsetX;
-                            this._lastScroll = barBoundings.visualBounds.x;
-                            this.uiFacade.scrollToX(scrollElement, scrollLeftContinuous, this.settings.player.scrollSpeed);
-                            break;
-                        case exports.ScrollMode.OffScreen:
-                            const elementRight = scrollElement.scrollLeft + this.uiFacade.getOffset(null, scrollElement).w;
-                            if (barBoundings.visualBounds.x + barBoundings.visualBounds.w >= elementRight ||
-                                barBoundings.visualBounds.x < scrollElement.scrollLeft) {
-                                const scrollLeftOffScreen = barBoundings.realBounds.x + this.settings.player.scrollOffsetX;
-                                this._lastScroll = barBoundings.visualBounds.x;
-                                this.uiFacade.scrollToX(scrollElement, scrollLeftOffScreen, this.settings.player.scrollSpeed);
-                            }
-                            break;
-                    }
+                const handler = this.customScrollHandler ?? this._defaultScrollHandler;
+                if (handler) {
+                    handler.forceScrollTo(beatBounds);
                 }
             }
         }
@@ -51585,11 +51890,12 @@
             }
             const isPlayingUpdate = this._player.state === PlayerState.Playing && !stop;
             let nextBeatX = barBoundings.visualBounds.x + barBoundings.visualBounds.w;
+            let nextBeatBoundings = null;
             // get position of next beat on same system
             if (nextBeat && cursorMode === MidiTickLookupFindBeatResultCursorMode.ToNextBext) {
                 // if we are moving within the same bar or to the next bar
                 // transition to the next beat, otherwise transition to the end of the bar.
-                const nextBeatBoundings = cache.findBeat(nextBeat);
+                nextBeatBoundings = cache.findBeat(nextBeat);
                 if (nextBeatBoundings &&
                     nextBeatBoundings.barBounds.masterBarBounds.staffSystemBounds === barBoundings.staffSystemBounds) {
                     nextBeatX = nextBeatBoundings.onNotesX;
@@ -51615,25 +51921,29 @@
                             beatCursor.transitionToX(0, startBeatX);
                             beatCursor.setBounds(startBeatX, barBounds.y, 1, barBounds.h);
                         }
+                        // it can happen that the cursor reaches the target position slightly too early (especially on backing tracks)
+                        // to avoid the cursor stopping, causing a wierd look, we animate the cursor to the double position in double time.
+                        // beatCursor!.transitionToX((duration / cursorSpeed), nextBeatX);
+                        const factor = cursorMode === MidiTickLookupFindBeatResultCursorMode.ToNextBext ? 2 : 1;
+                        nextBeatX = startBeatX + (nextBeatX - startBeatX) * factor;
+                        duration = (duration / cursorSpeed) * factor;
                         // we need to put the transition to an own animation frame
                         // otherwise the stop animation above is not applied.
                         this.uiFacade.beginInvoke(() => {
-                            // it can happen that the cursor reaches the target position slightly too early (especially on backing tracks)
-                            // to avoid the cursor stopping, causing a wierd look, we animate the cursor to the double position in double time.
-                            // beatCursor!.transitionToX((duration / cursorSpeed), nextBeatX);
-                            const factor = cursorMode === MidiTickLookupFindBeatResultCursorMode.ToNextBext ? 2 : 1;
-                            const doubleEndBeatX = startBeatX + (nextBeatX - startBeatX) * factor;
-                            beatCursor.transitionToX((duration / cursorSpeed) * factor, doubleEndBeatX);
+                            beatCursor.transitionToX(duration, nextBeatX);
                         });
                     }
                     else {
-                        beatCursor.transitionToX(0, startBeatX);
+                        duration = 0;
+                        beatCursor.transitionToX(duration, nextBeatX);
                         beatCursor.setBounds(startBeatX, barBounds.y, 1, barBounds.h);
                     }
                 }
                 else {
                     // ticking cursor
-                    beatCursor.transitionToX(0, startBeatX);
+                    duration = 0;
+                    nextBeatX = startBeatX;
+                    beatCursor.transitionToX(duration, nextBeatX);
                     beatCursor.setBounds(startBeatX, barBounds.y, 1, barBounds.h);
                 }
                 this._isInitialBeatCursorUpdate = false;
@@ -51656,7 +51966,10 @@
                 shouldNotifyBeatChange = true;
             }
             if (shouldScroll && !this._isBeatMouseDown && this.settings.player.scrollMode !== exports.ScrollMode.Off) {
-                this._internalScrollToCursor(barBoundings);
+                const handler = this.customScrollHandler ?? this._defaultScrollHandler;
+                if (handler) {
+                    handler.onBeatCursorUpdating(beatBoundings, nextBeatBoundings === null ? undefined : nextBeatBoundings, cursorMode, startBeatX, nextBeatX, duration);
+                }
             }
             // trigger an event for others to indicate which beat/bar is played
             if (shouldNotifyBeatChange) {
@@ -53030,6 +53343,7 @@
                 const tickCache = this._tickCache;
                 if (currentBeat && tickCache) {
                     this._player.tickPosition = tickCache.getBeatStart(currentBeat.beat);
+                    this.scrollToCursor();
                 }
             }
             this.uiFacade.triggerEvent(this.container, 'playerStateChanged', e);
@@ -54990,6 +55304,22 @@
             canvasElement.style.position = 'relative';
             return new HtmlElementContainer(canvasElement);
         }
+        setCanvasOverflow(canvasElement, overflow, isVertical) {
+            const html = canvasElement.element;
+            if (overflow === 0) {
+                html.style.boxSizing = '';
+                html.style.paddingRight = '';
+                html.style.paddingBottom = '';
+            }
+            else if (isVertical) {
+                html.style.boxSizing = 'content-box';
+                html.style.paddingBottom = `${overflow}px`;
+            }
+            else {
+                html.style.boxSizing = 'content-box';
+                html.style.paddingRight = `${overflow}px`;
+            }
+        }
         triggerEvent(container, name, details = null, originalEvent) {
             const element = container.element;
             name = `alphaTab.${name}`;
@@ -55547,54 +55877,79 @@
         scrollToX(element, scrollTargetY, speed) {
             this._internalScrollToX(element.element, scrollTargetY, speed);
         }
+        stopScrolling(scrollElement) {
+            // stop any current animation
+            const currentAnimation = this._scrollAnimationLookup.get(scrollElement.element);
+            if (currentAnimation !== undefined) {
+                this._activeScrollAnimations.delete(currentAnimation);
+            }
+        }
+        get _nativeBrowserSmoothScroll() {
+            const settings = this._api.settings.player;
+            return settings.nativeBrowserSmoothScroll && settings.scrollMode !== exports.ScrollMode.Smooth;
+        }
+        _scrollAnimationId = 0;
+        _activeScrollAnimations = new Set();
+        _scrollAnimationLookup = new Map();
         _internalScrollToY(element, scrollTargetY, speed) {
-            if (this._api.settings.player.nativeBrowserSmoothScroll) {
+            if (this._nativeBrowserSmoothScroll) {
                 element.scrollTo({
                     top: scrollTargetY,
                     behavior: 'smooth'
                 });
             }
             else {
-                const startY = element.scrollTop;
-                const diff = scrollTargetY - startY;
-                let start = 0;
-                const step = (x) => {
-                    if (start === 0) {
-                        start = x;
-                    }
-                    const time = x - start;
-                    const percent = Math.min(time / speed, 1);
-                    element.scrollTop = (startY + diff * percent) | 0;
-                    if (time < speed) {
-                        window.requestAnimationFrame(step);
-                    }
-                };
-                window.requestAnimationFrame(step);
+                this._internalScrollTo(element, element.scrollTop, scrollTargetY, speed, scroll => {
+                    element.scrollTop = scroll;
+                });
+            }
+        }
+        _internalScrollTo(element, startScroll, endScroll, scrollDuration, setValue) {
+            // stop any current animation
+            const currentAnimation = this._scrollAnimationLookup.get(element);
+            if (currentAnimation !== undefined) {
+                this._activeScrollAnimations.delete(currentAnimation);
+            }
+            if (scrollDuration === 0) {
+                setValue(endScroll);
+                return;
             }
+            // start new animation
+            const animationId = this._scrollAnimationId++;
+            this._scrollAnimationLookup.set(element, animationId);
+            this._activeScrollAnimations.add(animationId);
+            const diff = endScroll - startScroll;
+            let start = 0;
+            const step = (x) => {
+                if (!this._activeScrollAnimations.has(animationId)) {
+                    return;
+                }
+                if (start === 0) {
+                    start = x;
+                }
+                const time = x - start;
+                const percent = Math.min(time / scrollDuration, 1);
+                setValue((startScroll + diff * percent) | 0);
+                if (time < scrollDuration) {
+                    window.requestAnimationFrame(step);
+                }
+                else {
+                    this._activeScrollAnimations.delete(animationId);
+                }
+            };
+            window.requestAnimationFrame(step);
         }
         _internalScrollToX(element, scrollTargetX, speed) {
-            if (this._api.settings.player.nativeBrowserSmoothScroll) {
+            if (this._nativeBrowserSmoothScroll) {
                 element.scrollTo({
                     left: scrollTargetX,
                     behavior: 'smooth'
                 });
             }
             else {
-                const startX = element.scrollLeft;
-                const diff = scrollTargetX - startX;
-                let start = 0;
-                const step = (t) => {
-                    if (start === 0) {
-                        start = t;
-                    }
-                    const time = t - start;
-                    const percent = Math.min(time / speed, 1);
-                    element.scrollLeft = (startX + diff * percent) | 0;
-                    if (time < speed) {
-                        window.requestAnimationFrame(step);
-                    }
-                };
-                window.requestAnimationFrame(step);
+                this._internalScrollTo(element, element.scrollLeft, scrollTargetX, speed, scroll => {
+                    element.scrollLeft = scroll;
+                });
             }
         }
         createBackingTrackPlayer() {
@@ -61707,8 +62062,8 @@
                                 }
                             }
                         }
+                        this.accoladeWidth += settings.display.systemLabelPaddingLeft;
                         if (hasAnyTrackName) {
-                            this.accoladeWidth += settings.display.systemLabelPaddingLeft;
                             this.accoladeWidth += settings.display.systemLabelPaddingRight;
                         }
                     }