@coderline/alphatab 1.8.0-alpha.1636 → 1.8.0-alpha.1637

package/dist/alphaTab.core.mjs

@@ -1,5 +1,5 @@
 /*!
- * alphaTab v1.8.0-alpha.1636 (develop, build 1636)
+ * alphaTab v1.8.0-alpha.1637 (develop, build 1637)
  *
  * Copyright © 2025, Daniel Kuschny and Contributors, All rights reserved.
  *
@@ -203,9 +203,9 @@ class AlphaTabError extends Error {
  * @internal
  */
 class VersionInfo {
-    static version = '1.8.0-alpha.1636';
-    static date = '2025-12-06T02:04:52.462Z';
-    static commit = '49c68ed64403080028c852fe371cc6bdcca8dc3a';
+    static version = '1.8.0-alpha.1637';
+    static date = '2025-12-07T02:26:27.382Z';
+    static commit = 'aa2c8101456d3ddfc777491468bc483789cc6c12';
     static print(print) {
         print(`alphaTab ${VersionInfo.version}`);
         print(`commit: ${VersionInfo.commit}`);
@@ -12950,25 +12950,31 @@ class Bounds {
     /**
      * Gets or sets the X-position of the rectangle within the music notation.
      */
-    x = 0;
+    x;
     /**
      * Gets or sets the Y-position of the rectangle within the music notation.
      */
-    y = 0;
+    y;
     /**
      * Gets or sets the width of the rectangle.
      */
-    w = 0;
+    w;
     /**
      * Gets or sets the height of the rectangle.
      */
-    h = 0;
+    h;
     scaleWith(scale) {
         this.x *= scale;
         this.y *= scale;
         this.w *= scale;
         this.h *= scale;
     }
+    constructor(x = 0, y = 0, w = 0, h = 0) {
+        this.x = x;
+        this.y = y;
+        this.h = h;
+        this.w = w;
+    }
 }
 
 /**
@@ -49454,16 +49460,6 @@ class ExternalMediaPlayer extends BackingTrackPlayer {
     }
 }
 
-/**
- * @internal
- */
-class SelectionInfo {
-    beat;
-    bounds = null;
-    constructor(beat) {
-        this.beat = beat;
-    }
-}
 /**
  * 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}
@@ -51563,8 +51559,8 @@ class AlphaTabApiBase {
     }
     _isBeatMouseDown = false;
     _isNoteMouseDown = false;
-    _selectionStart = null;
-    _selectionEnd = null;
+    _selectionStart;
+    _selectionEnd;
     /**
      * This event is fired whenever a the user presses the mouse button on a beat.
      * @eventProperty
@@ -51807,8 +51803,8 @@ class AlphaTabApiBase {
             return;
         }
         if (this._hasCursor && this.settings.player.enableUserInteraction) {
-            this._selectionStart = new SelectionInfo(beat);
-            this._selectionEnd = null;
+            this._selectionStart = { beat };
+            this._selectionEnd = undefined;
         }
         this._isBeatMouseDown = true;
         this.beatMouseDown.trigger(beat);
@@ -51828,7 +51824,7 @@ class AlphaTabApiBase {
         }
         if (this.settings.player.enableUserInteraction) {
             if (!this._selectionEnd || this._selectionEnd.beat !== beat) {
-                this._selectionEnd = new SelectionInfo(beat);
+                this._selectionEnd = { beat };
                 this._cursorSelectRange(this._selectionStart, this._selectionEnd);
             }
         }
@@ -51847,45 +51843,7 @@ class AlphaTabApiBase {
             return;
         }
         if (this._hasCursor && this.settings.player.enableUserInteraction) {
-            if (this._selectionEnd) {
-                const startTick = this._tickCache?.getBeatStart(this._selectionStart.beat) ??
-                    this._selectionStart.beat.absolutePlaybackStart;
-                const endTick = this._tickCache?.getBeatStart(this._selectionEnd.beat) ??
-                    this._selectionEnd.beat.absolutePlaybackStart;
-                if (endTick < startTick) {
-                    const t = this._selectionStart;
-                    this._selectionStart = this._selectionEnd;
-                    this._selectionEnd = t;
-                }
-            }
-            if (this._selectionStart && this._tickCache) {
-                // get the start and stop ticks (which consider properly repeats)
-                const tickCache = this._tickCache;
-                const realMasterBarStart = tickCache.getMasterBarStart(this._selectionStart.beat.voice.bar.masterBar);
-                // move to selection start
-                this._currentBeat = null; // reset current beat so it is updating the cursor
-                if (this._player.state === PlayerState.Paused) {
-                    this._cursorUpdateTick(this._tickCache.getBeatStart(this._selectionStart.beat), false, 1);
-                }
-                this.tickPosition = realMasterBarStart + this._selectionStart.beat.playbackStart;
-                // set playback range
-                if (this._selectionEnd && this._selectionStart.beat !== this._selectionEnd.beat) {
-                    const realMasterBarEnd = tickCache.getMasterBarStart(this._selectionEnd.beat.voice.bar.masterBar);
-                    const range = new PlaybackRange();
-                    range.startTick = realMasterBarStart + this._selectionStart.beat.playbackStart;
-                    range.endTick =
-                        realMasterBarEnd +
-                            this._selectionEnd.beat.playbackStart +
-                            this._selectionEnd.beat.playbackDuration -
-                            50;
-                    this.playbackRange = range;
-                }
-                else {
-                    this._selectionStart = null;
-                    this.playbackRange = null;
-                    this._cursorSelectRange(this._selectionStart, this._selectionEnd);
-                }
-            }
+            this.applyPlaybackRangeFromHighlight();
         }
         this.beatMouseUp.trigger(beat);
         this.uiFacade.triggerEvent(this.container, 'beatMouseUp', beat, originalEvent);
@@ -51907,13 +51865,13 @@ class AlphaTabApiBase {
             const startBeat = this._tickCache.findBeat(this._trackIndexLookup, range.startTick);
             const endBeat = this._tickCache.findBeat(this._trackIndexLookup, range.endTick);
             if (startBeat && endBeat) {
-                const selectionStart = new SelectionInfo(startBeat.beat);
-                const selectionEnd = new SelectionInfo(endBeat.beat);
+                const selectionStart = { beat: startBeat.beat };
+                const selectionEnd = { beat: endBeat.beat };
                 this._cursorSelectRange(selectionStart, selectionEnd);
             }
         }
         else {
-            this._cursorSelectRange(null, null);
+            this._cursorSelectRange(undefined, undefined);
         }
     }
     _setupClickHandling() {
@@ -51982,24 +51940,230 @@ class AlphaTabApiBase {
             this._cursorSelectRange(this._selectionStart, this._selectionEnd);
         });
     }
+    /**
+     * Places the highlight markers at the specified start and end-beat range.
+     * @param startBeat The start beat where the selection should start
+     * @param endBeat The end beat where the selection should end.
+     *
+     * @remarks
+     * Unlike actually setting {@link playbackRange} this method only places the selection markers without actually
+     * changing the playback range. This method can be used when building custom selection systems (e.g. having draggable handles).
+     *
+     * @category Methods - Player
+     * @since 1.8.0
+     *
+     * @example
+     * JavaScript
+     * ```js
+     * const api = new alphaTab.AlphaTabApi(document.querySelector('#alphaTab'));
+     * const startBeat = api.score.tracks[0].staves[0].bars[0].voices[0].beats[0];
+     * const endBeat = api.score.tracks[0].staves[0].bars[3].voices[0].beats[0];
+     * api.highlightPlaybackRange(startBeat, endBeat);
+     * ```
+     *
+     * @example
+     * C#
+     * ```cs
+     * var api = new AlphaTabApi<MyControl>(...);
+     * api.ChangeTrackVolume(new Track[] { api.Score.Tracks[0], api.Score.Tracks[1] }, 1.5);
+     * api.ChangeTrackVolume(new Track[] { api.Score.Tracks[2] }, 0.5);
+     * var startBeat = api.Score.Tracks[0].Staves[0].Bars[0].Voices[0].Beats[0];
+     * var endBeat = api.Score.Tracks[0].Staves[0].Bars[3].Voices[0].Beats[0];
+     * api.HighlightPlaybackRange(startBeat, endBeat);
+     * ```
+     *
+     * @example
+     * Android
+     * ```kotlin
+     * val api = AlphaTabApi<MyControl>(...)
+     * val startBeat = api.score.tracks[0].staves[0].bars[0].voices[0].beats[0]
+     * val endBeat = api.score.tracks[0].staves[0].bars[3].voices[0].beats[0]
+     * api.highlightPlaybackRange(startBeat, endBeat)
+     * ```
+     */
+    highlightPlaybackRange(startBeat, endBeat) {
+        this._selectionStart = { beat: startBeat };
+        this._selectionEnd = { beat: endBeat };
+        this._cursorSelectRange(this._selectionStart, this._selectionEnd);
+    }
+    /**
+     * Applies the playback range from the currently highlighted range.
+     *
+     * @remarks
+     * This method can be used when building custom selection systems (e.g. having draggable handles).
+     *
+     * @category Methods - Player
+     * @since 1.8.0
+     *
+     * @example
+     * JavaScript
+     * ```js
+     * const api = new alphaTab.AlphaTabApi(document.querySelector('#alphaTab'));
+     * const startBeat = api.score.tracks[0].staves[0].bars[0].voices[0].beats[0];
+     * const endBeat = api.score.tracks[0].staves[0].bars[3].voices[0].beats[0];
+     * api.highlightPlaybackRange(startBeat, endBeat);
+     * api.applyPlaybackRangeFromHighlight();
+     * ```
+     *
+     * @example
+     * C#
+     * ```cs
+     * var api = new AlphaTabApi<MyControl>(...);
+     * api.ChangeTrackVolume(new Track[] { api.Score.Tracks[0], api.Score.Tracks[1] }, 1.5);
+     * api.ChangeTrackVolume(new Track[] { api.Score.Tracks[2] }, 0.5);
+     * var startBeat = api.Score.Tracks[0].Staves[0].Bars[0].Voices[0].Beats[0];
+     * var endBeat = api.Score.Tracks[0].Staves[0].Bars[3].Voices[0].Beats[0];
+     * api.HighlightPlaybackRange(startBeat, endBeat);
+     * api.ApplyPlaybackRangeFromHighlight();
+     * ```
+     *
+     * @example
+     * Android
+     * ```kotlin
+     * val api = AlphaTabApi<MyControl>(...)
+     * val startBeat = api.score.tracks[0].staves[0].bars[0].voices[0].beats[0]
+     * val endBeat = api.score.tracks[0].staves[0].bars[3].voices[0].beats[0]
+     * api.highlightPlaybackRange(startBeat, endBeat)
+     * api.applyPlaybackRangeFromHighlight()
+     * ```
+     */
+    applyPlaybackRangeFromHighlight() {
+        if (this._selectionEnd) {
+            const startTick = this._tickCache?.getBeatStart(this._selectionStart.beat) ??
+                this._selectionStart.beat.absolutePlaybackStart;
+            const endTick = this._tickCache?.getBeatStart(this._selectionEnd.beat) ??
+                this._selectionEnd.beat.absolutePlaybackStart;
+            if (endTick < startTick) {
+                const t = this._selectionStart;
+                this._selectionStart = this._selectionEnd;
+                this._selectionEnd = t;
+            }
+        }
+        if (this._selectionStart && this._tickCache) {
+            // get the start and stop ticks (which consider properly repeats)
+            const tickCache = this._tickCache;
+            const realMasterBarStart = tickCache.getMasterBarStart(this._selectionStart.beat.voice.bar.masterBar);
+            // move to selection start
+            this._currentBeat = null; // reset current beat so it is updating the cursor
+            if (this._player.state === PlayerState.Paused) {
+                this._cursorUpdateTick(this._tickCache.getBeatStart(this._selectionStart.beat), false, 1);
+            }
+            this.tickPosition = realMasterBarStart + this._selectionStart.beat.playbackStart;
+            // set playback range
+            if (this._selectionEnd && this._selectionStart.beat !== this._selectionEnd.beat) {
+                const realMasterBarEnd = tickCache.getMasterBarStart(this._selectionEnd.beat.voice.bar.masterBar);
+                const range = new PlaybackRange();
+                range.startTick = realMasterBarStart + this._selectionStart.beat.playbackStart;
+                range.endTick =
+                    realMasterBarEnd +
+                        this._selectionEnd.beat.playbackStart +
+                        this._selectionEnd.beat.playbackDuration -
+                        50;
+                this.playbackRange = range;
+            }
+            else {
+                this._selectionStart = undefined;
+                this.playbackRange = null;
+                this._cursorSelectRange(this._selectionStart, this._selectionEnd);
+            }
+        }
+    }
+    /**
+     * Clears the highlight markers marking the currently selected playback range.
+     *
+     * @remarks
+     * Unlike actually setting {@link playbackRange} this method only clears the selection markers without actually
+     * changing the playback range. This method can be used when building custom selection systems (e.g. having draggable handles).
+     *
+     * @category Methods - Player
+     * @since 1.8.0
+     *
+     * @example
+     * JavaScript
+     * ```js
+     * const api = new alphaTab.AlphaTabApi(document.querySelector('#alphaTab'));
+     * api.clearPlaybackRangeHighlight();
+     * ```
+     *
+     * @example
+     * C#
+     * ```cs
+     * var api = new AlphaTabApi<MyControl>(...);
+     * api.clearPlaybackRangeHighlight();
+     * ```
+     *
+     * @example
+     * Android
+     * ```kotlin
+     * val api = AlphaTabApi<MyControl>(...)
+     * api.clearPlaybackRangeHighlight()
+     * ```
+     */
+    clearPlaybackRangeHighlight() {
+        this._cursorSelectRange(undefined, undefined);
+    }
+    /**
+     * This event is fired the shown highlights for the selected playback range changes.
+     *
+     * @remarks
+     * This event is fired already during selection and not only when the selection is completed.
+     * This event can be used to place additional custom selection markers (like drag handles).
+     *
+     * @eventProperty
+     * @category Events - Player
+     * @since 1.8.0
+     *
+     * @example
+     * JavaScript
+     * ```js
+     * const api = new alphaTab.AlphaTabApi(document.querySelector('#alphaTab'));
+     * api.playbackRangeHighlightChanged.on(e => {
+     *    updateSelectionHandles(e);
+     * });
+     * ```
+     *
+     * @example
+     * C#
+     * ```cs
+     * var api = new AlphaTabApi<MyControl>(...);
+     * api.PlaybackRangeHighlightChanged.On(e =>
+     * {
+     *    UpdateSelectionHandles(e);
+     * });
+     * ```
+     *
+     * @example
+     * Android
+     * ```kotlin
+     * val api = AlphaTabApi<MyControl>(...)
+     * api.playbackRangeHighlightChanged.on { e ->
+     *     updateSelectionHandles(e)
+     * }
+     * ```
+     *
+     */
+    playbackRangeHighlightChanged = new EventEmitterOfT();
     _cursorSelectRange(startBeat, endBeat) {
         const cache = this._renderer.boundsLookup;
         if (!cache) {
+            this.playbackRangeHighlightChanged.trigger({});
             return;
         }
         const selectionWrapper = this._selectionWrapper;
         if (!selectionWrapper) {
+            this.playbackRangeHighlightChanged.trigger({});
             return;
         }
         selectionWrapper.clear();
         if (!startBeat || !endBeat || startBeat.beat === endBeat.beat) {
+            this.playbackRangeHighlightChanged.trigger({});
             return;
         }
         if (!startBeat.bounds) {
-            startBeat.bounds = cache.findBeat(startBeat.beat);
+            startBeat.bounds = cache.findBeat(startBeat.beat) ?? undefined;
         }
         if (!endBeat.bounds) {
-            endBeat.bounds = cache.findBeat(endBeat.beat);
+            endBeat.bounds = cache.findBeat(endBeat.beat) ?? undefined;
         }
         const startTick = this._tickCache?.getBeatStart(startBeat.beat) ?? startBeat.beat.absolutePlaybackStart;
         const endTick = this._tickCache?.getBeatStart(endBeat.beat) ?? endBeat.beat.absolutePlaybackStart;
@@ -52008,7 +52172,17 @@ class AlphaTabApiBase {
             startBeat = endBeat;
             endBeat = t;
         }
-        const startX = startBeat.bounds.realBounds.x;
+        const eventArgs = {
+            startBeat: startBeat.beat,
+            startBeatBounds: startBeat.bounds,
+            endBeat: endBeat.beat,
+            endBeatBounds: endBeat.bounds,
+            highlightBlocks: []
+        };
+        let startX = startBeat.bounds.realBounds.x;
+        if (startBeat.beat.index === 0) {
+            startX = startBeat.bounds.barBounds.masterBarBounds.realBounds.x;
+        }
         let endX = endBeat.bounds.realBounds.x + endBeat.bounds.realBounds.w;
         if (endBeat.beat.index === endBeat.beat.voice.beats.length - 1) {
             endX =
@@ -52025,18 +52199,24 @@ class AlphaTabApiBase {
             const staffEndX = startBeat.bounds.barBounds.masterBarBounds.staffSystemBounds.visualBounds.x +
                 startBeat.bounds.barBounds.masterBarBounds.staffSystemBounds.visualBounds.w;
             const startSelection = this.uiFacade.createSelectionElement();
-            startSelection.setBounds(startX, startBeat.bounds.barBounds.masterBarBounds.visualBounds.y, staffEndX - startX, startBeat.bounds.barBounds.masterBarBounds.visualBounds.h);
+            const startSelectionBounds = new Bounds(startX, startBeat.bounds.barBounds.masterBarBounds.visualBounds.y, staffEndX - startX, startBeat.bounds.barBounds.masterBarBounds.visualBounds.h);
+            startSelection.setBounds(startSelectionBounds.x, startSelectionBounds.y, startSelectionBounds.w, startSelectionBounds.h);
+            eventArgs.highlightBlocks.push(startSelectionBounds);
             selectionWrapper.appendChild(startSelection);
             const staffStartIndex = startBeat.bounds.barBounds.masterBarBounds.staffSystemBounds.index + 1;
             const staffEndIndex = endBeat.bounds.barBounds.masterBarBounds.staffSystemBounds.index;
             for (let staffIndex = staffStartIndex; staffIndex < staffEndIndex; staffIndex++) {
                 const staffBounds = cache.staffSystems[staffIndex];
                 const middleSelection = this.uiFacade.createSelectionElement();
-                middleSelection.setBounds(staffStartX, staffBounds.visualBounds.y, staffEndX - staffStartX, staffBounds.visualBounds.h);
+                const middleSelectionBounds = new Bounds(staffStartX, staffBounds.visualBounds.y, staffEndX - staffStartX, staffBounds.visualBounds.h);
+                eventArgs.highlightBlocks.push(middleSelectionBounds);
+                middleSelection.setBounds(middleSelectionBounds.x, middleSelectionBounds.y, middleSelectionBounds.w, middleSelectionBounds.h);
                 selectionWrapper.appendChild(middleSelection);
             }
             const endSelection = this.uiFacade.createSelectionElement();
-            endSelection.setBounds(staffStartX, endBeat.bounds.barBounds.masterBarBounds.visualBounds.y, endX - staffStartX, endBeat.bounds.barBounds.masterBarBounds.visualBounds.h);
+            const endSelectionBounds = new Bounds(staffStartX, endBeat.bounds.barBounds.masterBarBounds.visualBounds.y, endX - staffStartX, endBeat.bounds.barBounds.masterBarBounds.visualBounds.h);
+            eventArgs.highlightBlocks.push(endSelectionBounds);
+            endSelection.setBounds(endSelectionBounds.x, endSelectionBounds.y, endSelectionBounds.w, endSelectionBounds.h);
             selectionWrapper.appendChild(endSelection);
         }
         else {
@@ -52045,6 +52225,7 @@ class AlphaTabApiBase {
             selection.setBounds(startX, startBeat.bounds.barBounds.masterBarBounds.visualBounds.y, endX - startX, startBeat.bounds.barBounds.masterBarBounds.visualBounds.h);
             selectionWrapper.appendChild(selection);
         }
+        this.playbackRangeHighlightChanged.trigger(eventArgs);
     }
     /**
      * This event is fired whenever a new song is loaded.

package/dist/alphaTab.d.ts

@@ -1745,8 +1745,8 @@ export declare class AlphaTabApiBase<TSettings> {
     private _onActiveBeatsChanged;
     private _isBeatMouseDown;
     private _isNoteMouseDown;
-    private _selectionStart;
-    private _selectionEnd;
+    private _selectionStart?;
+    private _selectionEnd?;
     /**
      * This event is fired whenever a the user presses the mouse button on a beat.
      * @eventProperty
@@ -1990,6 +1990,163 @@ export declare class AlphaTabApiBase<TSettings> {
     private _onNoteMouseUp;
     private _updateSelectionCursor;
     private _setupClickHandling;
+    /**
+     * Places the highlight markers at the specified start and end-beat range.
+     * @param startBeat The start beat where the selection should start
+     * @param endBeat The end beat where the selection should end.
+     *
+     * @remarks
+     * Unlike actually setting {@link playbackRange} this method only places the selection markers without actually
+     * changing the playback range. This method can be used when building custom selection systems (e.g. having draggable handles).
+     *
+     * @category Methods - Player
+     * @since 1.8.0
+     *
+     * @example
+     * JavaScript
+     * ```js
+     * const api = new alphaTab.AlphaTabApi(document.querySelector('#alphaTab'));
+     * const startBeat = api.score.tracks[0].staves[0].bars[0].voices[0].beats[0];
+     * const endBeat = api.score.tracks[0].staves[0].bars[3].voices[0].beats[0];
+     * api.highlightPlaybackRange(startBeat, endBeat);
+     * ```
+     *
+     * @example
+     * C#
+     * ```cs
+     * var api = new AlphaTabApi<MyControl>(...);
+     * api.ChangeTrackVolume(new Track[] { api.Score.Tracks[0], api.Score.Tracks[1] }, 1.5);
+     * api.ChangeTrackVolume(new Track[] { api.Score.Tracks[2] }, 0.5);
+     * var startBeat = api.Score.Tracks[0].Staves[0].Bars[0].Voices[0].Beats[0];
+     * var endBeat = api.Score.Tracks[0].Staves[0].Bars[3].Voices[0].Beats[0];
+     * api.HighlightPlaybackRange(startBeat, endBeat);
+     * ```
+     *
+     * @example
+     * Android
+     * ```kotlin
+     * val api = AlphaTabApi<MyControl>(...)
+     * val startBeat = api.score.tracks[0].staves[0].bars[0].voices[0].beats[0]
+     * val endBeat = api.score.tracks[0].staves[0].bars[3].voices[0].beats[0]
+     * api.highlightPlaybackRange(startBeat, endBeat)
+     * ```
+     */
+    highlightPlaybackRange(startBeat: Beat, endBeat: Beat): void;
+    /**
+     * Applies the playback range from the currently highlighted range.
+     *
+     * @remarks
+     * This method can be used when building custom selection systems (e.g. having draggable handles).
+     *
+     * @category Methods - Player
+     * @since 1.8.0
+     *
+     * @example
+     * JavaScript
+     * ```js
+     * const api = new alphaTab.AlphaTabApi(document.querySelector('#alphaTab'));
+     * const startBeat = api.score.tracks[0].staves[0].bars[0].voices[0].beats[0];
+     * const endBeat = api.score.tracks[0].staves[0].bars[3].voices[0].beats[0];
+     * api.highlightPlaybackRange(startBeat, endBeat);
+     * api.applyPlaybackRangeFromHighlight();
+     * ```
+     *
+     * @example
+     * C#
+     * ```cs
+     * var api = new AlphaTabApi<MyControl>(...);
+     * api.ChangeTrackVolume(new Track[] { api.Score.Tracks[0], api.Score.Tracks[1] }, 1.5);
+     * api.ChangeTrackVolume(new Track[] { api.Score.Tracks[2] }, 0.5);
+     * var startBeat = api.Score.Tracks[0].Staves[0].Bars[0].Voices[0].Beats[0];
+     * var endBeat = api.Score.Tracks[0].Staves[0].Bars[3].Voices[0].Beats[0];
+     * api.HighlightPlaybackRange(startBeat, endBeat);
+     * api.ApplyPlaybackRangeFromHighlight();
+     * ```
+     *
+     * @example
+     * Android
+     * ```kotlin
+     * val api = AlphaTabApi<MyControl>(...)
+     * val startBeat = api.score.tracks[0].staves[0].bars[0].voices[0].beats[0]
+     * val endBeat = api.score.tracks[0].staves[0].bars[3].voices[0].beats[0]
+     * api.highlightPlaybackRange(startBeat, endBeat)
+     * api.applyPlaybackRangeFromHighlight()
+     * ```
+     */
+    applyPlaybackRangeFromHighlight(): void;
+    /**
+     * Clears the highlight markers marking the currently selected playback range.
+     *
+     * @remarks
+     * Unlike actually setting {@link playbackRange} this method only clears the selection markers without actually
+     * changing the playback range. This method can be used when building custom selection systems (e.g. having draggable handles).
+     *
+     * @category Methods - Player
+     * @since 1.8.0
+     *
+     * @example
+     * JavaScript
+     * ```js
+     * const api = new alphaTab.AlphaTabApi(document.querySelector('#alphaTab'));
+     * api.clearPlaybackRangeHighlight();
+     * ```
+     *
+     * @example
+     * C#
+     * ```cs
+     * var api = new AlphaTabApi<MyControl>(...);
+     * api.clearPlaybackRangeHighlight();
+     * ```
+     *
+     * @example
+     * Android
+     * ```kotlin
+     * val api = AlphaTabApi<MyControl>(...)
+     * api.clearPlaybackRangeHighlight()
+     * ```
+     */
+    clearPlaybackRangeHighlight(): void;
+    /**
+     * This event is fired the shown highlights for the selected playback range changes.
+     *
+     * @remarks
+     * This event is fired already during selection and not only when the selection is completed.
+     * This event can be used to place additional custom selection markers (like drag handles).
+     *
+     * @eventProperty
+     * @category Events - Player
+     * @since 1.8.0
+     *
+     * @example
+     * JavaScript
+     * ```js
+     * const api = new alphaTab.AlphaTabApi(document.querySelector('#alphaTab'));
+     * api.playbackRangeHighlightChanged.on(e => {
+     *    updateSelectionHandles(e);
+     * });
+     * ```
+     *
+     * @example
+     * C#
+     * ```cs
+     * var api = new AlphaTabApi<MyControl>(...);
+     * api.PlaybackRangeHighlightChanged.On(e =>
+     * {
+     *    UpdateSelectionHandles(e);
+     * });
+     * ```
+     *
+     * @example
+     * Android
+     * ```kotlin
+     * val api = AlphaTabApi<MyControl>(...)
+     * api.playbackRangeHighlightChanged.on { e ->
+     *     updateSelectionHandles(e)
+     * }
+     * ```
+     *
+     */
+    readonly playbackRangeHighlightChanged: IEventEmitterOfT<PlaybackHighlightChangeEventArgs>;
     private _cursorSelectRange;
     /**
      * This event is fired whenever a new song is loaded.
@@ -5230,6 +5387,7 @@ declare class Bounds {
      */
     h: number;
     scaleWith(scale: number): void;
+    constructor(x?: number, y?: number, w?: number, h?: number);
 }
 
 /**
@@ -12803,6 +12961,35 @@ export declare namespace platform {
     }
 }
 
+/**
+ * Holds information about the highlights shown for the playback range.
+ * @public
+ * @record
+ */
+export declare interface PlaybackHighlightChangeEventArgs {
+    /**
+     * The beat where the selection starts. undefined if there is no selection.
+     */
+    startBeat?: Beat;
+    /**
+     * The bounds of the start beat to determine its location and size.
+     */
+    startBeatBounds?: BeatBounds;
+    /**
+     * The beat where the selection ends. undefined if there is no selection.
+     */
+    endBeat?: Beat;
+    /**
+     * The bounds of the end beat to determine its location and size.
+     */
+    endBeatBounds?: BeatBounds;
+    /**
+     * A list of the individual rectangular areas where highlight blocks are placed.
+     * If a selection spans multiple lines this array will hold all items.
+     */
+    highlightBlocks?: Bounds[];
+}
+
 /**
  * This public class stores the midi specific information of a track needed
  * for playback.