@coderline/alphatab 1.8.0-alpha.1647 → 1.8.0-alpha.1651

package/dist/alphaTab.js

@@ -1,5 +1,5 @@
 /*!
- * alphaTab v1.8.0-alpha.1647 (develop, build 1647)
+ * alphaTab v1.8.0-alpha.1651 (develop, build 1651)
  *
  * Copyright © 2025, Daniel Kuschny and Contributors, All rights reserved.
  *
@@ -209,9 +209,9 @@
      * @internal
      */
     class VersionInfo {
-        static version = '1.8.0-alpha.1647';
-        static date = '2025-12-17T02:10:13.730Z';
-        static commit = 'a1bd11d4a3eef22409f1f49a5dd172ace16108cc';
+        static version = '1.8.0-alpha.1651';
+        static date = '2025-12-21T02:27:24.035Z';
+        static commit = '758ae890dfa8cdb21a9dd469ade012f834ac0433';
         static print(print) {
             print(`alphaTab ${VersionInfo.version}`);
             print(`commit: ${VersionInfo.commit}`);
@@ -2750,6 +2750,23 @@
          * Whether barlines should be drawn across staves within the same system.
          */
         extendBarLines = false;
+        /**
+         * Whether to hide empty staves.
+         */
+        hideEmptyStaves = false;
+        /**
+         * Whether to also hide empty staves in the first system.
+         * @remarks
+         * Only has an effect when activating {@link hideEmptyStaves}.
+         */
+        hideEmptyStavesInFirstSystem = false;
+        /**
+         * Whether to show brackets and braces across single staves.
+         * @remarks
+         * This allows a more consistent view for identifying staves when using
+         * {@link hideEmptyStaves}
+         */
+        showSingleStaffBrackets = false;
     }
 
     /**
@@ -8679,7 +8696,10 @@
             ['firstsystemtracknameorientation', [[[[10, 17], 0, ['horizontal', 'vertical']]]]],
             ['othersystemstracknameorientation', [[[[10, 17], 0, ['horizontal', 'vertical']]]]],
             ['extendbarlines', null],
-            ['chorddiagramsinscore', [[[[10], 1, ['true', 'false']]]]]
+            ['chorddiagramsinscore', [[[[10], 1, ['true', 'false']]]]],
+            ['hideemptystaves', null],
+            ['hideemptystavesinfirstsystem', null],
+            ['showsinglestaffbrackets', null]
         ]);
         static staffMetaDataSignatures = AlphaTex1LanguageDefinitions._signatures([
             ['tuning', [[[[10, 17], 0, ['piano', 'none', 'voice']]], [[[10, 17], 5]]]],
@@ -9019,6 +9039,9 @@
             ['othersystemstracknameorientation', null],
             ['extendbarlines', null],
             ['chorddiagramsinscore', null],
+            ['hideemptystaves', null],
+            ['hideemptystavesinfirstsystem', null],
+            ['showsinglestaffbrackets', null],
             [
                 'tuning',
                 [
@@ -13072,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;
         /**
@@ -13280,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 = {};
@@ -13336,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);
@@ -13893,6 +13917,15 @@
                         ? AlphaTex1LanguageHandler._booleanLikeValue(metaData.arguments.arguments, 0)
                         : true;
                     return ApplyNodeResult.Applied;
+                case 'hideemptystaves':
+                    score.stylesheet.hideEmptyStaves = true;
+                    return ApplyNodeResult.Applied;
+                case 'hideemptystavesinfirstsystem':
+                    score.stylesheet.hideEmptyStavesInFirstSystem = true;
+                    return ApplyNodeResult.Applied;
+                case 'showsinglestaffbrackets':
+                    score.stylesheet.showSingleStaffBrackets = true;
+                    return ApplyNodeResult.Applied;
                 default:
                     return ApplyNodeResult.NotAppliedUnrecognizedMarker;
             }
@@ -15724,6 +15757,15 @@
             if (stylesheet.globalDisplayChordDiagramsInScore) {
                 nodes.push(Atnf.meta('chordDiagramsInScore'));
             }
+            if (stylesheet.hideEmptyStaves) {
+                nodes.push(Atnf.meta('hideEmptyStaves'));
+            }
+            if (stylesheet.hideEmptyStavesInFirstSystem) {
+                nodes.push(Atnf.meta('hideEmptyStavesInFirstSystem'));
+            }
+            if (stylesheet.showSingleStaffBrackets) {
+                nodes.push(Atnf.meta('showSingleStaffBrackets'));
+            }
             // Unsupported:
             // 'globaldisplaychorddiagramsontop',
             // 'pertrackchorddiagramsontop',
@@ -38810,6 +38852,9 @@
                 }
             }
             o.set("extendbarlines", obj.extendBarLines);
+            o.set("hideemptystaves", obj.hideEmptyStaves);
+            o.set("hideemptystavesinfirstsystem", obj.hideEmptyStavesInFirstSystem);
+            o.set("showsinglestaffbrackets", obj.showSingleStaffBrackets);
             return o;
         }
         static setProperty(obj, property, v) {
@@ -38871,6 +38916,15 @@
                 case "extendbarlines":
                     obj.extendBarLines = v;
                     return true;
+                case "hideemptystaves":
+                    obj.hideEmptyStaves = v;
+                    return true;
+                case "hideemptystavesinfirstsystem":
+                    obj.hideEmptyStavesInFirstSystem = v;
+                    return true;
+                case "showsinglestaffbrackets":
+                    obj.showSingleStaffBrackets = v;
+                    return true;
             }
             return false;
         }
@@ -43610,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.
@@ -45898,6 +45958,19 @@
             }
             return null;
         }
+        /**
+         * Looks for the first visible beat which starts at this lookup so it can be used for cursor placement.
+         * @param checker The custom checker to see if a beat is visible.
+         * @returns The first beat which is visible according to the given tracks or null.
+         */
+        getVisibleBeatAtStartWithChecker(checker) {
+            for (const b of this.highlightedBeats) {
+                if (b.playbackStart === this.start && checker.isVisible(b.beat)) {
+                    return b.beat;
+                }
+            }
+            return null;
+        }
     }
 
     /**
@@ -46337,6 +46410,18 @@
             }
         }
     }
+    /**
+     * @internal
+     */
+    class TrackLookupBeatVisibilityChecker {
+        _lookup;
+        constructor(lookup) {
+            this._lookup = lookup;
+        }
+        isVisible(beat) {
+            return this._lookup.has(beat.voice.bar.staff.track.index);
+        }
+    }
     /**
      * This class holds all information about when {@link MasterBar}s and {@link Beat}s are played.
      *
@@ -46397,31 +46482,44 @@
          * @returns The information about the current beat or null if no beat could be found.
          */
         findBeat(trackLookup, tick, currentBeatHint = null) {
+            return this.findBeatWithChecker(new TrackLookupBeatVisibilityChecker(trackLookup), tick, currentBeatHint);
+        }
+        /**
+         * Finds the currently played beat given a list of tracks and the current time.
+         * @param checker The checker to ask whether a beat is visible and should be considered for result.
+         * @param tick The current time in midi ticks.
+         * @param currentBeatHint Used for optimized lookup during playback. By passing in a previous result lookup of the next one can be optimized using heuristics. (optional).
+         * @returns The information about the current beat or null if no beat could be found.
+         */
+        findBeatWithChecker(checker, tick, currentBeatHint = null) {
             let result = null;
             if (currentBeatHint) {
-                result = this._findBeatFast(trackLookup, currentBeatHint, tick);
+                result = this._findBeatFast(checker, currentBeatHint, tick);
             }
             if (!result) {
-                result = this._findBeatSlow(trackLookup, currentBeatHint, tick, false);
+                result = this._findBeatSlow(checker, currentBeatHint, tick, false);
             }
             return result;
         }
-        _findBeatFast(trackLookup, currentBeatHint, tick) {
+        _findBeatFast(checker, currentBeatHint, tick) {
             // still within current lookup.
             if (tick >= currentBeatHint.start && tick < currentBeatHint.end) {
                 return currentBeatHint;
             }
             // already on the next beat?
-            if (currentBeatHint.nextBeat && tick >= currentBeatHint.nextBeat.start && tick < currentBeatHint.nextBeat.end) {
+            if (currentBeatHint.nextBeat &&
+                tick >= currentBeatHint.nextBeat.start &&
+                tick < currentBeatHint.nextBeat.end &&
+                (checker === undefined || checker.isVisible(currentBeatHint.nextBeat.beat))) {
                 const next = currentBeatHint.nextBeat;
                 // fill next in chain
-                this._fillNextBeat(next, trackLookup);
+                this._fillNextBeat(next, checker);
                 return next;
             }
             // likely a loop or manual seek, need to fallback to slow path
             return null;
         }
-        _fillNextBeatMultiBarRest(current, trackLookup) {
+        _fillNextBeatMultiBarRest(current, checker) {
             const group = this.multiBarRestInfo.get(current.masterBar.masterBar.index);
             // this is a bit sensitive. we assume that the sequence of multi-rest bars and the
             // chained nextMasterBar equal. so we just jump over X bars
@@ -46435,7 +46533,7 @@
             if (endMasterBar) {
                 // one more following -> use start of next
                 if (endMasterBar.nextMasterBar) {
-                    current.nextBeat = this._firstBeatInMasterBar(trackLookup, endMasterBar.nextMasterBar, endMasterBar.nextMasterBar.start, true);
+                    current.nextBeat = this._firstBeatInMasterBar(checker, endMasterBar.nextMasterBar, endMasterBar.nextMasterBar.start, true);
                     // if we have the next beat take the difference between the times as duration
                     if (current.nextBeat) {
                         current.tickDuration = current.nextBeat.start - current.start;
@@ -46465,19 +46563,19 @@
             }
             current.calculateDuration();
         }
-        _fillNextBeat(current, trackLookup) {
+        _fillNextBeat(current, checker) {
             // on multibar rests take the duration until the end.
             if (this._isMultiBarRestResult(current)) {
-                this._fillNextBeatMultiBarRest(current, trackLookup);
+                this._fillNextBeatMultiBarRest(current, checker);
             }
             else {
-                this._fillNextBeatDefault(current, trackLookup);
+                this._fillNextBeatDefault(current, checker);
             }
         }
-        _fillNextBeatDefault(current, trackLookup) {
-            current.nextBeat = this._findBeatInMasterBar(current.masterBar, current.beatLookup.nextBeat, current.end, trackLookup, true);
+        _fillNextBeatDefault(current, checker) {
+            current.nextBeat = this._findBeatInMasterBar(current.masterBar, current.beatLookup.nextBeat, current.end, checker, true);
             if (current.nextBeat == null) {
-                current.nextBeat = this._findBeatSlow(trackLookup, current, current.end, true);
+                current.nextBeat = this._findBeatSlow(checker, current, current.end, true);
             }
             // if we have the next beat take the difference between the times as duration
             if (current.nextBeat) {
@@ -46508,7 +46606,7 @@
                 beat.isRest &&
                 beat.voice.bar.isRestOnly);
         }
-        _findBeatSlow(trackLookup, currentBeatHint, tick, isNextSearch) {
+        _findBeatSlow(checker, currentBeatHint, tick, isNextSearch) {
             // get all beats within the masterbar
             let masterBar = null;
             if (currentBeatHint != null) {
@@ -46530,14 +46628,14 @@
             if (!masterBar) {
                 return null;
             }
-            return this._firstBeatInMasterBar(trackLookup, masterBar, tick, isNextSearch);
+            return this._firstBeatInMasterBar(checker, masterBar, tick, isNextSearch);
         }
-        _firstBeatInMasterBar(trackLookup, startMasterBar, tick, isNextSearch) {
+        _firstBeatInMasterBar(checker, startMasterBar, tick, isNextSearch) {
             let masterBar = startMasterBar;
             // scan through beats and find first one which has a beat visible
             while (masterBar) {
                 if (masterBar.firstBeat) {
-                    const beat = this._findBeatInMasterBar(masterBar, masterBar.firstBeat, tick, trackLookup, isNextSearch);
+                    const beat = this._findBeatInMasterBar(masterBar, masterBar.firstBeat, tick, checker, isNextSearch);
                     if (beat) {
                         return beat;
                     }
@@ -46555,7 +46653,7 @@
          * @param isNextSearch
          * @returns
          */
-        _findBeatInMasterBar(masterBar, currentStartLookup, tick, visibleTracks, isNextSearch) {
+        _findBeatInMasterBar(masterBar, currentStartLookup, tick, checker, isNextSearch) {
             if (!currentStartLookup) {
                 return null;
             }
@@ -46569,7 +46667,7 @@
                 (currentStartLookup.start <= relativeTick || (isNextSearch && relativeTick < 0)) &&
                     relativeTick < currentStartLookup.end) {
                     startBeatLookup = currentStartLookup;
-                    startBeat = currentStartLookup.getVisibleBeatAtStart(visibleTracks);
+                    startBeat = currentStartLookup.getVisibleBeatAtStartWithChecker(checker);
                     // found the matching beat lookup but none of the beats are visible
                     // in this case scan further to the next lookup which has any visible beat
                     if (!startBeat) {
@@ -46577,7 +46675,7 @@
                             let currentMasterBar = masterBar;
                             while (currentMasterBar != null && startBeat == null) {
                                 while (currentStartLookup != null) {
-                                    startBeat = currentStartLookup.getVisibleBeatAtStart(visibleTracks);
+                                    startBeat = currentStartLookup.getVisibleBeatAtStartWithChecker(checker);
                                     if (startBeat) {
                                         startBeatLookup = currentStartLookup;
                                         masterBar = currentMasterBar;
@@ -46595,7 +46693,7 @@
                             let currentMasterBar = masterBar;
                             while (currentMasterBar != null && startBeat == null) {
                                 while (currentStartLookup != null) {
-                                    startBeat = currentStartLookup.getVisibleBeatAtStart(visibleTracks);
+                                    startBeat = currentStartLookup.getVisibleBeatAtStartWithChecker(checker);
                                     if (startBeat) {
                                         startBeatLookup = currentStartLookup;
                                         masterBar = currentMasterBar;
@@ -46619,17 +46717,17 @@
             if (startBeat == null) {
                 return null;
             }
-            const result = this._createResult(masterBar, startBeatLookup, startBeat, isNextSearch, visibleTracks);
+            const result = this._createResult(masterBar, startBeatLookup, startBeat, isNextSearch, checker);
             return result;
         }
-        _createResult(masterBar, beatLookup, beat, isNextSearch, visibleTracks) {
+        _createResult(masterBar, beatLookup, beat, isNextSearch, checker) {
             const result = new MidiTickLookupFindBeatResult(masterBar);
             result.beat = beat;
             result.beatLookup = beatLookup;
             result.tickDuration = beatLookup.end - beatLookup.start;
             if (!isNextSearch) {
                 // the next beat filling will adjust this result with the respective durations
-                this._fillNextBeat(result, visibleTracks);
+                this._fillNextBeat(result, checker);
             }
             else if (this._isMultiBarRestResult(result)) {
                 const multiRest = this.multiBarRestInfo.get(masterBar.masterBar.index);
@@ -48502,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
@@ -48928,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);
+        }
     }
 
     /**
@@ -49556,6 +49913,19 @@
         }
     }
 
+    /**
+     * @internal
+     */
+    class BoundsLookupVisibilityChecker {
+        bounds = null;
+        isVisible(beat) {
+            const bounds = this.bounds;
+            if (!bounds) {
+                return false;
+            }
+            return bounds.findBeat(beat) !== null;
+        }
+    }
     /**
      * This class represents the public API of alphaTab and provides all logic to display
      * a music sheet in any UI using the given {@link IUiFacade}
@@ -49566,12 +49936,14 @@
         _startTime = 0;
         _trackIndexes = null;
         _trackIndexLookup = null;
+        _beatVisibilityChecker = new BoundsLookupVisibilityChecker();
         _isDestroyed = false;
         _score = null;
         _tracks = [];
         _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.
@@ -50341,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
@@ -51319,7 +51727,6 @@
         _isInitialBeatCursorUpdate = true;
         _previousStateForCursor = PlayerState.Paused;
         _previousCursorCache = null;
-        _lastScroll = 0;
         _destroyCursors() {
             if (!this._cursorWrapper) {
                 return;
@@ -51330,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
@@ -51362,12 +51820,9 @@
             this._previousTick = tick;
             const cache = this._tickCache;
             if (cache) {
-                const tracks = this._trackIndexLookup;
-                if (tracks != null && tracks.size > 0) {
-                    const beat = cache.findBeat(tracks, tick, this._currentBeat);
-                    if (beat) {
-                        this._cursorUpdateBeat(beat, stop, shouldScroll, cursorSpeed, forceUpdate || this.playerState === PlayerState.Paused);
-                    }
+                const beat = cache.findBeatWithChecker(this._beatVisibilityChecker, tick, this._currentBeat);
+                if (beat) {
+                    this._cursorUpdateBeat(beat, stop, shouldScroll, cursorSpeed, forceUpdate || this.playerState === PlayerState.Paused);
                 }
             }
         }
@@ -51417,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);
                 }
             }
         }
@@ -51483,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;
@@ -51513,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;
@@ -51554,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) {
@@ -52569,6 +52984,7 @@
             if (this._isDestroyed) {
                 return;
             }
+            this._beatVisibilityChecker.bounds = this.boundsLookup;
             this._currentBeat = null;
             this._cursorUpdateTick(this._previousTick, false, 1, true, true);
             this.postRenderFinished.trigger();
@@ -52927,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);
@@ -54887,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}`;
@@ -55444,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() {
@@ -60576,8 +61034,10 @@
         height = 0;
         index = 0;
         staffIndex = 0;
+        isVisible = false;
+        _emptyBarCount = 0;
         get isFirstInSystem() {
-            return this.index === 0;
+            return this.system.firstVisibleStaff === this;
         }
         topEffectInfos = [];
         bottomEffectInfos = [];
@@ -60612,10 +61072,11 @@
         get contentBottom() {
             return this.y + this.topPadding + this.topOverflow + this.staffBottom;
         }
-        constructor(trackIndex, staff, factory) {
+        constructor(system, trackIndex, staff, factory) {
             this._factory = factory;
             this.trackIndex = trackIndex;
             this.modelStaff = staff;
+            this.system = system;
             for (const b of factory.effectBands) {
                 if (b.shouldCreate && !b.shouldCreate(staff)) {
                     continue;
@@ -60631,6 +61092,7 @@
                         break;
                 }
             }
+            this._updateVisibility();
         }
         getSharedLayoutData(key, def) {
             if (this._sharedLayoutData.has(key)) {
@@ -60657,6 +61119,20 @@
             renderer.reLayout();
             this.barRenderers.push(renderer);
             this.system.layout.registerBarRenderer(this.staffId, renderer);
+            if (renderer.bar.isEmpty || renderer.bar.isRestOnly) {
+                this._emptyBarCount++;
+            }
+            this._updateVisibility();
+        }
+        _updateVisibility() {
+            const stylesheet = this.modelStaff.track.score.stylesheet;
+            const canHideEmptyStaves = stylesheet.hideEmptyStaves && (stylesheet.hideEmptyStavesInFirstSystem || this.system.index > 0);
+            if (canHideEmptyStaves) {
+                this.isVisible = this._emptyBarCount < this.barRenderers.length;
+            }
+            else {
+                this.isVisible = true;
+            }
         }
         addBar(bar, layoutingInfo, additionalMultiBarsRestBars) {
             const renderer = this._factory.create(this.system.layout.renderer, bar);
@@ -60676,6 +61152,10 @@
             }
             this.barRenderers.push(renderer);
             this.system.layout.registerBarRenderer(this.staffId, renderer);
+            if (bar.isEmpty || bar.isRestOnly) {
+                this._emptyBarCount++;
+            }
+            this._updateVisibility();
         }
         revertLastBar() {
             this._sharedLayoutData = new Map();
@@ -60686,6 +61166,10 @@
             for (const r of this.barRenderers) {
                 r.afterStaffBarReverted();
             }
+            if (lastBar.bar.isEmpty || lastBar.bar.isRestOnly) {
+                this._emptyBarCount--;
+            }
+            this._updateVisibility();
             return lastBar;
         }
         scaleToWidth(width) {
@@ -60796,6 +61280,7 @@
                 this.height += this.topPadding + topOverflow + this.bottomOverflow + this.bottomPadding;
             }
             this.height = Math.ceil(this.height);
+            this._updateVisibility();
         }
         paint(cx, cy, canvas, startIndex, count) {
             if (this.height === 0 || count === 0) {
@@ -61196,6 +61681,8 @@
         track;
         staffSystem;
         staves = [];
+        firstVisibleStaff;
+        lastVisibleStaff;
         bracket = null;
         constructor(staffSystem, track) {
             this.staffSystem = staffSystem;
@@ -61210,18 +61697,47 @@
      * @internal
      */
     class SystemBracket {
-        firstStaffInBracket = null;
-        lastStaffInBracket = null;
+        _system;
+        firstStaffInBracket;
+        lastStaffInBracket;
+        firstVisibleStaffInBracket;
+        lastVisibleStaffInBracket;
         drawAsBrace = false;
         braceScale = 1;
         width = 0;
         index = 0;
-        get canPaint() {
-            return this.firstStaffInBracket !== null && this.lastStaffInBracket !== null;
+        canPaint = false;
+        constructor(system) {
+            this._system = system;
+        }
+        updateCanPaint() {
+            let firstVisibleStaff = undefined;
+            let lastVisibleStaff = undefined;
+            for (let i = this.firstStaffInBracket.index; i <= this.lastStaffInBracket.index; i++) {
+                const staff = this._system.allStaves[i];
+                if (staff.isVisible) {
+                    if (!firstVisibleStaff) {
+                        firstVisibleStaff = staff;
+                    }
+                    lastVisibleStaff = staff;
+                }
+            }
+            this.firstVisibleStaffInBracket = firstVisibleStaff;
+            this.lastVisibleStaffInBracket = lastVisibleStaff;
+            if (!firstVisibleStaff || !lastVisibleStaff) {
+                this.canPaint = false;
+                return;
+            }
+            // single staff brackets?
+            const singleStaffBrackets = this._system.layout.renderer.score.stylesheet.showSingleStaffBrackets;
+            if (!singleStaffBrackets && firstVisibleStaff === lastVisibleStaff) {
+                this.canPaint = false;
+                return;
+            }
+            this.canPaint = true;
         }
         finalizeBracket(smuflMetrics) {
-            // systems with just a single staff do not have a bracket
-            if (this.firstStaffInBracket === this.lastStaffInBracket) {
+            if (!this.canPaint) {
                 this.width = 0;
                 return;
             }
@@ -61235,11 +61751,11 @@
             else {
                 this.width = smuflMetrics.bracketThickness;
             }
-            if (!this.drawAsBrace || !this.firstStaffInBracket || !this.lastStaffInBracket) {
+            if (!this.drawAsBrace) {
                 return;
             }
-            const firstStart = this.firstStaffInBracket.contentTop;
-            const lastEnd = this.lastStaffInBracket.contentBottom;
+            const firstStart = this.firstVisibleStaffInBracket.contentTop;
+            const lastEnd = this.lastVisibleStaffInBracket.contentBottom;
             const requiredHeight = lastEnd - firstStart;
             const requiredScaleForBracket = requiredHeight / bravuraBraceHeightAtMusicFontSize;
             this.braceScale = requiredScaleForBracket;
@@ -61251,8 +61767,8 @@
      */
     class SingleTrackSystemBracket extends SystemBracket {
         track;
-        constructor(track) {
-            super();
+        constructor(system, track) {
+            super(system);
             this.track = track;
             this.drawAsBrace = SingleTrackSystemBracket.isTrackDrawAsBrace(track);
         }
@@ -61317,6 +61833,7 @@
         topPadding;
         bottomPadding;
         allStaves = [];
+        firstVisibleStaff;
         constructor(layout) {
             this.layout = layout;
             this.topPadding = layout.renderer.settings.display.systemPaddingTop;
@@ -61335,14 +61852,40 @@
             this.masterBarsRenderers.push(renderers);
             renderers.layoutingInfo.preBeatSize = 0;
             let src = 0;
-            for (let i = 0, j = this.staves.length; i < j; i++) {
-                const g = this.staves[i];
-                for (let k = 0, l = g.staves.length; k < l; k++) {
-                    const s = g.staves[k];
+            let firstVisibleStaff = undefined;
+            let anyStaffVisible = false;
+            for (const g of this.staves) {
+                let firstVisibleStaffInGroup = undefined;
+                let lastVisibleStaffInGroup = undefined;
+                for (const s of g.staves) {
                     const renderer = renderers.renderers[src++];
                     s.addBarRenderer(renderer);
+                    if (s.isVisible) {
+                        anyStaffVisible = true;
+                        if (!firstVisibleStaffInGroup) {
+                            firstVisibleStaffInGroup = s;
+                        }
+                        if (!firstVisibleStaff) {
+                            firstVisibleStaff = s;
+                        }
+                        lastVisibleStaffInGroup = s;
+                    }
+                }
+                g.firstVisibleStaff = firstVisibleStaffInGroup;
+                g.lastVisibleStaff = lastVisibleStaffInGroup;
+                if (!firstVisibleStaff) {
+                    firstVisibleStaff = firstVisibleStaffInGroup;
                 }
             }
+            if (!anyStaffVisible) {
+                const group = this.staves[0];
+                const firstStaff = group.staves[0];
+                firstStaff.isVisible = true;
+                group.firstVisibleStaff = firstStaff;
+                group.lastVisibleStaff = firstStaff;
+                firstVisibleStaff = firstStaff;
+            }
+            this.firstVisibleStaff = firstVisibleStaff;
             this._calculateAccoladeSpacing(tracks);
             this._updateWidthFromLastBar();
             return renderers;
@@ -61353,15 +61896,26 @@
             result.layoutingInfo = new BarLayoutingInfo();
             result.masterBar = tracks[0].score.masterBars[barIndex];
             this.masterBarsRenderers.push(result);
+            let firstVisibleStaff = undefined;
+            let anyStaffVisible = false;
             // add renderers
             const barLayoutingInfo = result.layoutingInfo;
             for (const g of this.staves) {
+                let firstVisibleStaffInGroup = undefined;
+                let lastVisibleStaffInGroup = undefined;
                 for (const s of g.staves) {
                     const bar = g.track.staves[s.modelStaff.index].bars[barIndex];
                     const additionalMultiBarsRestBars = additionalMultiBarRestIndexes == null
                         ? null
                         : additionalMultiBarRestIndexes.map(b => g.track.staves[s.modelStaff.index].bars[b]);
                     s.addBar(bar, barLayoutingInfo, additionalMultiBarsRestBars);
+                    if (s.isVisible) {
+                        anyStaffVisible = true;
+                        if (!firstVisibleStaffInGroup) {
+                            firstVisibleStaffInGroup = s;
+                        }
+                        lastVisibleStaffInGroup = s;
+                    }
                     const renderer = s.barRenderers[s.barRenderers.length - 1];
                     result.renderers.push(renderer);
                     if (renderer.isLinkedToPrevious) {
@@ -61371,7 +61925,21 @@
                         result.canWrap = false;
                     }
                 }
+                g.firstVisibleStaff = firstVisibleStaffInGroup;
+                g.lastVisibleStaff = lastVisibleStaffInGroup;
+                if (!firstVisibleStaff) {
+                    firstVisibleStaff = firstVisibleStaffInGroup;
+                }
+            }
+            if (!anyStaffVisible) {
+                const group = this.staves[0];
+                const firstStaff = group.staves[0];
+                firstStaff.isVisible = true;
+                group.firstVisibleStaff = firstStaff;
+                group.lastVisibleStaff = firstStaff;
+                firstVisibleStaff = firstStaff;
             }
+            this.firstVisibleStaff = firstVisibleStaff;
             this._calculateAccoladeSpacing(tracks);
             barLayoutingInfo.finish();
             // ensure same widths of new renderer
@@ -61384,19 +61952,35 @@
                 this.masterBarsRenderers.splice(this.masterBarsRenderers.length - 1, 1);
                 let width = 0;
                 let barDisplayScale = 0;
-                for (let i = 0, j = this.allStaves.length; i < j; i++) {
-                    const s = this.allStaves[i];
-                    const lastBar = s.revertLastBar();
-                    const computedWidth = lastBar.computedWidth;
-                    if (computedWidth > width) {
-                        width = computedWidth;
+                let firstVisibleStaff = undefined;
+                for (const g of this.staves) {
+                    let firstVisibleStaffInGroup = undefined;
+                    let lastVisibleStaffInGroup = undefined;
+                    for (const s of g.staves) {
+                        const lastBar = s.revertLastBar();
+                        const computedWidth = lastBar.computedWidth;
+                        if (computedWidth > width) {
+                            width = computedWidth;
+                        }
+                        const newBarDisplayScale = lastBar.barDisplayScale;
+                        if (newBarDisplayScale > barDisplayScale) {
+                            barDisplayScale = newBarDisplayScale;
+                        }
+                        lastBar.afterReverted();
+                        if (s.isVisible) {
+                            if (!firstVisibleStaffInGroup) {
+                                firstVisibleStaffInGroup = s;
+                            }
+                            lastVisibleStaffInGroup = s;
+                        }
                     }
-                    const newBarDisplayScale = lastBar.barDisplayScale;
-                    if (newBarDisplayScale > barDisplayScale) {
-                        barDisplayScale = newBarDisplayScale;
+                    g.firstVisibleStaff = firstVisibleStaffInGroup;
+                    g.lastVisibleStaff = lastVisibleStaffInGroup;
+                    if (!firstVisibleStaff) {
+                        firstVisibleStaff = firstVisibleStaffInGroup;
                     }
-                    lastBar.afterReverted();
                 }
+                this.firstVisibleStaff = firstVisibleStaff;
                 this.width -= width;
                 this.computedWidth -= width;
                 this.totalBarDisplayScale -= barDisplayScale;
@@ -61478,8 +62062,8 @@
                                 }
                             }
                         }
+                        this.accoladeWidth += settings.display.systemLabelPaddingLeft;
                         if (hasAnyTrackName) {
-                            this.accoladeWidth += settings.display.systemLabelPaddingLeft;
                             this.accoladeWidth += settings.display.systemLabelPaddingRight;
                         }
                     }
@@ -61503,6 +62087,7 @@
                 }
                 let braceWidth = 0;
                 for (const b of this._brackets) {
+                    b.updateCanPaint();
                     b.finalizeBracket(settings.display.resources.engravingSettings);
                     braceWidth = Math.max(braceWidth, b.width);
                 }
@@ -61510,6 +62095,12 @@
                 this.width += this.accoladeWidth;
                 this.computedWidth += this.accoladeWidth;
             }
+            else {
+                for (const b of this._brackets) {
+                    b.updateCanPaint();
+                    b.finalizeBracket(settings.display.resources.engravingSettings);
+                }
+            }
         }
         _getStaffTrackGroup(track) {
             for (let i = 0, j = this.staves.length; i < j; i++) {
@@ -61539,12 +62130,12 @@
                         break;
                     case BracketExtendMode.GroupStaves:
                         // when grouping staves, we create one bracket for the whole track across all staves
-                        bracket = new SingleTrackSystemBracket(track);
+                        bracket = new SingleTrackSystemBracket(this, track);
                         bracket.index = this._brackets.length;
                         this._brackets.push(bracket);
                         break;
                     case BracketExtendMode.GroupSimilarInstruments:
-                        bracket = new SimilarInstrumentSystemBracket(track);
+                        bracket = new SimilarInstrumentSystemBracket(this, track);
                         bracket.index = this._brackets.length;
                         this._brackets.push(bracket);
                         break;
@@ -61591,8 +62182,10 @@
             }
         }
         paintPartial(cx, cy, canvas, startIndex, count) {
-            for (let i = 0, j = this.allStaves.length; i < j; i++) {
-                this.allStaves[i].paint(cx, cy, canvas, startIndex, count);
+            for (const s of this.allStaves) {
+                if (s.isVisible) {
+                    s.paint(cx, cy, canvas, startIndex, count);
+                }
             }
             const res = this.layout.renderer.settings.display.resources;
             if (this.staves.length > 0 && startIndex === 0) {
@@ -61629,9 +62222,9 @@
                         const oldBaseLine = canvas.textBaseline;
                         const oldTextAlign = canvas.textAlign;
                         for (const g of this.staves) {
-                            if (g.staves.length > 0) {
-                                const firstStart = cy + g.staves[0].contentTop;
-                                const lastEnd = cy + g.staves[g.staves.length - 1].contentBottom;
+                            if (g.firstVisibleStaff) {
+                                const firstStart = cy + g.firstVisibleStaff.contentTop;
+                                const lastEnd = cy + g.lastVisibleStaff.contentBottom;
                                 let trackNameText = '';
                                 switch (trackNameMode) {
                                     case TrackNameMode.FullName:
@@ -61685,6 +62278,9 @@
                 if (this.allStaves.length > 0 && needsSystemBarLine) {
                     let previousStaffInBracket = null;
                     for (const s of this.allStaves) {
+                        if (!s.isVisible) {
+                            continue;
+                        }
                         if (previousStaffInBracket !== null) {
                             const previousBottom = previousStaffInBracket.contentBottom;
                             const thisTop = s.contentTop;
@@ -61711,17 +62307,17 @@
             const settings = this.layout.renderer.settings;
             for (const bracket of this._brackets) {
                 if (bracket.canPaint) {
-                    const barStartX = cx + bracket.firstStaffInBracket.x;
+                    const barStartX = cx + bracket.firstVisibleStaffInBracket.x;
                     const barSize = bracket.width;
                     const barOffset = settings.display.accoladeBarPaddingRight;
-                    const firstStart = cy + bracket.firstStaffInBracket.contentTop;
-                    const lastEnd = cy + bracket.lastStaffInBracket.contentBottom;
+                    const firstStart = cy + bracket.firstVisibleStaffInBracket.contentTop;
+                    const lastEnd = cy + bracket.lastVisibleStaffInBracket.contentBottom;
                     let accoladeStart = firstStart;
                     let accoladeEnd = lastEnd;
                     if (bracket.drawAsBrace) {
                         CanvasHelper.fillMusicFontSymbolSafe(canvas, barStartX - barOffset - barSize, accoladeEnd, bracket.braceScale, MusicFontSymbol.Brace);
                     }
-                    else if (bracket.firstStaffInBracket !== bracket.lastStaffInBracket) {
+                    else if (bracket.firstVisibleStaffInBracket !== bracket.lastVisibleStaffInBracket) {
                         // brackets typically overflow by 1/4 staff-space
                         const smuflMetrics = settings.display.resources.engravingSettings;
                         const bracketOverflow = smuflMetrics.oneStaffSpace * 0.25;
@@ -61753,40 +62349,86 @@
                 this.bottomPadding = Math.max(this.bottomPadding, neededHeight);
                 this._hasSystemSeparator = true;
             }
+            const anyStaffVisible = this._finalizeTrackGroups();
+            // for now we always force one staff to be visible.
+            // making also whole systems invisible needs separate attention (also on player cursor handling)
+            if (!anyStaffVisible) {
+                const group = this.staves[0];
+                const firstStaff = group.staves[0];
+                firstStaff.isVisible = true;
+                this._finalizeTrackGroups(true);
+            }
+            for (const b of this._brackets) {
+                b.finalizeBracket(settings.display.resources.engravingSettings);
+            }
+        }
+        _finalizeTrackGroups(onlyFirstGroup = false) {
             let currentY = 0;
+            const settings = this.layout.renderer.settings;
             const smufl = settings.display.resources.engravingSettings;
             const topBracketSpikeHeight = smufl.glyphHeights.get(MusicFontSymbol.BracketTop);
             const bottomBracketSpikeHeight = smufl.glyphHeights.get(MusicFontSymbol.BracketBottom);
             let previousStaff = undefined;
-            for (const staff of this.allStaves) {
-                // check if we need "in-between padding"
-                if (previousStaff !== undefined && previousStaff.trackIndex !== staff.trackIndex) {
-                    currentY += settings.display.trackStaffPaddingBetween;
-                }
-                const bracket = this._staffToBracket.has(staff) ? this._staffToBracket.get(staff) : undefined;
-                const hasBracket = bracket && !bracket.drawAsBrace && bracket.canPaint;
-                if (hasBracket && bracket.firstStaffInBracket === staff) {
-                    const spikeOverflow = topBracketSpikeHeight - staff.topOverflow;
-                    if (spikeOverflow > 0) {
-                        currentY += spikeOverflow;
+            let endSpikeOverflow = 0;
+            let anyStaffVisible = false;
+            for (const group of this.staves) {
+                let firstVisibleStaffInGroup = undefined;
+                let lastVisibleStaffInGroup = undefined;
+                for (const staff of group.staves) {
+                    // check if we need "in-between padding"
+                    if (previousStaff !== undefined && previousStaff.trackIndex !== staff.trackIndex) {
+                        currentY += settings.display.trackStaffPaddingBetween;
+                    }
+                    const bracket = this._staffToBracket.has(staff) ? this._staffToBracket.get(staff) : undefined;
+                    const hasBracket = bracket && !bracket.drawAsBrace && bracket.canPaint;
+                    if (hasBracket && bracket.firstStaffInBracket === staff) {
+                        const spikeOverflow = topBracketSpikeHeight - staff.topOverflow;
+                        if (spikeOverflow > 0) {
+                            currentY += spikeOverflow;
+                        }
+                    }
+                    staff.x = this.accoladeWidth;
+                    staff.y = currentY;
+                    if (!onlyFirstGroup) {
+                        staff.finalizeStaff();
+                    }
+                    if (staff.isVisible) {
+                        currentY += staff.height;
+                        anyStaffVisible = true;
+                        previousStaff = staff;
+                        if (!firstVisibleStaffInGroup) {
+                            firstVisibleStaffInGroup = staff;
+                        }
+                        lastVisibleStaffInGroup = staff;
+                    }
+                    endSpikeOverflow = 0;
+                    if (hasBracket && bracket.lastStaffInBracket === staff) {
+                        const spikeOverflow = bottomBracketSpikeHeight - staff.bottomOverflow;
+                        if (spikeOverflow > 0) {
+                            if (staff.isVisible) {
+                                currentY += spikeOverflow;
+                            }
+                            else {
+                                endSpikeOverflow = spikeOverflow;
+                            }
+                        }
                     }
                 }
-                staff.x = this.accoladeWidth;
-                staff.y = currentY;
-                staff.finalizeStaff();
-                currentY += staff.height;
-                if (hasBracket && bracket.lastStaffInBracket === staff) {
-                    const spikeOverflow = bottomBracketSpikeHeight - staff.bottomOverflow;
-                    if (spikeOverflow > 0) {
-                        currentY += spikeOverflow;
-                    }
+                group.firstVisibleStaff = firstVisibleStaffInGroup;
+                group.lastVisibleStaff = lastVisibleStaffInGroup;
+                if (!this.firstVisibleStaff) {
+                    this.firstVisibleStaff = firstVisibleStaffInGroup;
+                }
+                if (onlyFirstGroup) {
+                    break;
                 }
-                previousStaff = staff;
             }
-            this._contentHeight = currentY;
-            for (const b of this._brackets) {
-                b.finalizeBracket(smufl);
+            // ensure we add overflow if last bracket is hidden
+            if (endSpikeOverflow) {
+                currentY += endSpikeOverflow;
             }
+            this._contentHeight = currentY;
+            return anyStaffVisible;
         }
         buildBoundingsLookup(cx, cy) {
             if (this.layout.renderer.boundsLookup.isFinished) {
@@ -61820,6 +62462,9 @@
             const masterBarBoundsLookup = new Map();
             for (let i = 0; i < this.staves.length; i++) {
                 for (const staff of this.staves[i].staves) {
+                    if (!staff.isVisible) {
+                        continue;
+                    }
                     for (const renderer of staff.barRenderers) {
                         let masterBarBounds;
                         if (!masterBarBoundsLookup.has(renderer.bar.masterBar.index)) {
@@ -62130,8 +62775,9 @@
         }
         firstBarIndex = 0;
         lastBarIndex = 0;
-        createEmptyStaffSystem() {
+        createEmptyStaffSystem(index) {
             const system = new StaffSystem(this);
+            system.index = index;
             const allFactories = Environment.defaultRenderers;
             const renderStaves = [];
             for (let trackIndex = 0; trackIndex < this.renderer.tracks.length; trackIndex++) {
@@ -62143,7 +62789,7 @@
                     let previousStaff = undefined;
                     for (const factory of allFactories) {
                         if (this.profile.has(factory.staffId) && factory.canCreate(track, staff)) {
-                            const renderStaff = new RenderStaff(trackIndex, staff, factory);
+                            const renderStaff = new RenderStaff(system, trackIndex, staff, factory);
                             // insert shared effect bands at front
                             renderStaff.topEffectInfos.splice(0, 0, ...sharedTopEffects);
                             renderStaff.bottomEffectInfos.push(...sharedBottomEffects);
@@ -65301,7 +65947,7 @@
             }
             endBarIndex = startIndex + endBarIndex - 1; // map count to array index
             endBarIndex = Math.min(score.masterBars.length - 1, Math.max(0, endBarIndex));
-            this._system = this.createEmptyStaffSystem();
+            this._system = this.createEmptyStaffSystem(0);
             this._system.isLast = true;
             this._system.x = this.pagePadding[0];
             this._system.y = this.pagePadding[1];
@@ -65574,8 +66220,7 @@
                 this._systems = [];
                 let currentIndex = 0;
                 const maxWidth = this._maxWidth;
-                let system = this.createEmptyStaffSystem();
-                system.index = this._systems.length;
+                let system = this.createEmptyStaffSystem(this._systems.length);
                 system.x = this.pagePadding[0];
                 system.y = y;
                 while (currentIndex < this._allMasterBarRenderers.length) {
@@ -65606,8 +66251,7 @@
                         this._fitSystem(system);
                         y += this._paintSystem(system, oldHeight);
                         // note: we do not increase currentIndex here to have it added to the next system
-                        system = this.createEmptyStaffSystem();
-                        system.index = this._systems.length;
+                        system = this.createEmptyStaffSystem(this._systems.length);
                         system.x = this.pagePadding[0];
                         system.y = y;
                     }
@@ -65692,8 +66336,7 @@
             return barsPerRow;
         }
         _createStaffSystem(currentBarIndex, endIndex) {
-            const system = this.createEmptyStaffSystem();
-            system.index = this._systems.length;
+            const system = this.createEmptyStaffSystem(this._systems.length);
             const barsPerRow = this._getBarsPerSystem(system.index);
             const maxWidth = this._maxWidth;
             const end = endIndex + 1;
@@ -68373,16 +69016,77 @@
     class ClefGlyph extends MusicFontGlyph {
         _clef;
         _clefOttava;
+        _ottavaGlyph;
         constructor(x, y, clef, clefOttava) {
             super(x, y, 1, ClefGlyph._getSymbol(clef, clefOttava));
             this._clef = clef;
             this._clefOttava = clefOttava;
         }
+        getBoundingBoxTop() {
+            let top = super.getBoundingBoxTop();
+            const ottava = this._ottavaGlyph;
+            if (ottava) {
+                const ottavaTop = this.y + ottava.getBoundingBoxTop();
+                top = ModelUtils.minBoundingBox(top, ottavaTop);
+            }
+            return top;
+        }
+        getBoundingBoxBottom() {
+            let bottom = super.getBoundingBoxBottom();
+            const ottava = this._ottavaGlyph;
+            if (ottava) {
+                const ottavaBottom = this.y + ottava.getBoundingBoxBottom();
+                bottom = ModelUtils.maxBoundingBox(bottom, ottavaBottom);
+            }
+            return bottom;
+        }
         doLayout() {
             this.center = true;
             super.doLayout();
             this.width = this.renderer.smuflMetrics.glyphWidths.get(MusicFontSymbol.GClef);
             this.offsetX = this.width / 2;
+            this._ottavaGlyph = undefined;
+            switch (this._clef) {
+                case Clef.C3:
+                case Clef.C4:
+                    switch (this._clefOttava) {
+                        case Ottavia._8vb:
+                            return;
+                    }
+                    break;
+                case Clef.F4:
+                case Clef.G2:
+                    return;
+            }
+            let ottavaSymbol;
+            let top = false;
+            switch (this._clefOttava) {
+                case Ottavia._15ma:
+                    ottavaSymbol = MusicFontSymbol.Clef15;
+                    top = true;
+                    break;
+                case Ottavia._8va:
+                    ottavaSymbol = MusicFontSymbol.Clef8;
+                    top = true;
+                    break;
+                case Ottavia._8vb:
+                    ottavaSymbol = MusicFontSymbol.Clef8;
+                    break;
+                case Ottavia._15mb:
+                    ottavaSymbol = MusicFontSymbol.Clef15;
+                    break;
+                default:
+                    return;
+            }
+            const ottavaX = this.width / 2;
+            const ottavaY = top
+                ? this.renderer.smuflMetrics.glyphTop.get(this.symbol)
+                : this.renderer.smuflMetrics.glyphBottom.get(this.symbol) -
+                    this.renderer.smuflMetrics.glyphHeights.get(ottavaSymbol);
+            this._ottavaGlyph = new MusicFontGlyph(ottavaX, -ottavaY, 1, ottavaSymbol);
+            this._ottavaGlyph.center = true;
+            this._ottavaGlyph.renderer = this.renderer;
+            this._ottavaGlyph.doLayout();
         }
         static _getSymbol(clef, clefOttava) {
             switch (clef) {
@@ -68430,44 +69134,10 @@
             const _ = ElementStyleHelper.bar(canvas, BarSubElement.StandardNotationClef, this.renderer.bar);
             try {
                 super.paint(cx, cy, canvas);
-                switch (this._clef) {
-                    case Clef.C3:
-                    case Clef.C4:
-                        switch (this._clefOttava) {
-                            case Ottavia._8vb:
-                                return;
-                        }
-                        break;
-                    case Clef.F4:
-                    case Clef.G2:
-                        return;
-                }
-                let ottavaGlyph;
-                let top = false;
-                switch (this._clefOttava) {
-                    case Ottavia._15ma:
-                        ottavaGlyph = MusicFontSymbol.Clef15;
-                        top = true;
-                        break;
-                    case Ottavia._8va:
-                        ottavaGlyph = MusicFontSymbol.Clef8;
-                        top = true;
-                        break;
-                    case Ottavia._8vb:
-                        ottavaGlyph = MusicFontSymbol.Clef8;
-                        break;
-                    case Ottavia._15mb:
-                        ottavaGlyph = MusicFontSymbol.Clef15;
-                        break;
-                    default:
-                        return;
+                const ottava = this._ottavaGlyph;
+                if (ottava) {
+                    ottava.paint(cx + this.x, cy + this.y, canvas);
                 }
-                const ottavaX = this.width / 2;
-                const ottavaY = top
-                    ? this.renderer.smuflMetrics.glyphTop.get(this.symbol)
-                    : this.renderer.smuflMetrics.glyphBottom.get(this.symbol) -
-                        this.renderer.smuflMetrics.glyphHeights.get(ottavaGlyph);
-                CanvasHelper.fillMusicFontSymbolSafe(canvas, cx + this.x + ottavaX, cy + this.y - ottavaY, 1, ottavaGlyph, true);
             }
             finally {
                 _?.[Symbol.dispose]?.();