@coderline/alphatab 1.8.0 → 1.8.2

package/dist/alphaTab.d.ts

@@ -365,6 +365,8 @@ export declare class AlphaTabApiBase<TSettings> {
     private _player;
     private _renderer;
     private _defaultScrollHandler?;
+    private _defaultCursorHandler?;
+    private _customCursorHandler?;
     /**
      * 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.
@@ -839,6 +841,62 @@ export declare class AlphaTabApiBase<TSettings> {
      * ```
      */
     render(renderHints?: RenderHints): void;
+    /**
+     * A custom cursor handler which will be used to update the cursor positions during playback.
+     *
+     * @category Properties - Player
+     * @since 1.8.1
+     * @example
+     * JavaScript
+     * ```js
+     * const api = new alphaTab.AlphaTabApi(document.querySelector('#alphaTab'));
+     * api.customCursorHandler = {
+     *   _customAdorner: undefined,
+     *   onAttach(cursors) {
+     *     this._customAdorner = document.createElement('div');
+     *     this._customAdorner.classList.add('cursor-adorner');
+     *     cursors.cursorWrapper.element.appendChild(this._customAdorner);
+     *   },
+     *   onDetach(cursors) { this._customAdorner.remove(); },
+     *   placeBarCursor(barCursor, beatBounds) {
+     *     const barBoundings = beatBounds.barBounds.masterBarBounds;
+     *     const barBounds = barBoundings.visualBounds;
+     *     barCursor.setBounds(barBounds.x, barBounds.y, barBounds.w, barBounds.h);
+     *   },
+     *   placeBeatCursor(beatCursor, beatBounds, startBeatX) {
+     *     const barBoundings = beatBounds.barBounds.masterBarBounds;
+     *     const barBounds = barBoundings.visualBounds;
+     *     beatCursor.transitionToX(0, startBeatX);
+     *     beatCursor.setBounds(startBeatX, barBounds.y, 1, barBounds.h);
+     *     this._customAdorner.style.left = startBeatX + 'px';
+     *     this._customAdorner.style.top = (barBounds.y - 10) + 'px';
+     *     this._customAdorner.style.width = '1px';
+     *     this._customAdorner.style.height = '10px';
+     *     this._customAdorner.style.transition = 'left 0ms linear'; // stop animation
+     *   },
+     *   transitionBeatCursor(beatCursor, beatBounds, startBeatX, endBeatX, duration, cursorMode) {
+     *     this._customAdorner.style.transition = `left ${duration}ms linear`; // start animation
+     *     this._customAdorner.style.left = endBeatX + 'px';
+     *   }
+     * }
+     * ```
+     *
+     * @example
+     * C#
+     * ```cs
+     * var api = new AlphaTabApi<MyControl>(...);
+     * api.CustomCursorHandler = new CustomCursorHandler();
+     * ```
+     *
+     * @example
+     * Android
+     * ```kotlin
+     * val api = AlphaTabApi<MyControl>(...)
+     * api.customCursorHandler = CustomCursorHandler();
+     * ```
+     */
+    get customCursorHandler(): ICursorHandler | undefined;
+    set customCursorHandler(value: ICursorHandler | undefined);
     private _tickCache;
     /**
      * A custom scroll handler which will be used to handle scrolling operations during playback.
@@ -1686,6 +1744,8 @@ export declare class AlphaTabApiBase<TSettings> {
     private _destroyCursors;
     private _createCursors;
     private _updateCursors;
+    private _cursorHandlerMode;
+    private _updateCursorHandler;
     private _scrollHandlerMode;
     private _scrollHandlerVertical;
     private _updateScrollHandler;
@@ -5522,22 +5582,10 @@ declare class Bounds {
  * @public
  */
 declare class BoundsLookup {
-    /**
-     * @target web
-     */
-    toJson(): unknown;
-    /**
-     * @target web
-     */
-    static fromJson(json: unknown, score: Score): BoundsLookup;
-    /**
-     * @target web
-     */
+    toJson(): Map<string, unknown>;
+    static fromJson(json: Map<string, unknown> | null, score: Score): BoundsLookup | null;
     private static _boundsFromJson;
-    /**
-     * @target web
-     */
-    private _boundsToJson;
+    private static _boundsToJson;
     private _beatLookup;
     private _masterBarLookup;
     private _currentStaffSystem;
@@ -8120,6 +8168,7 @@ export declare class Environment {
      */
     private static _globalThis;
 
+
     /**
      * @target web
      */
@@ -8148,13 +8197,6 @@ export declare class Environment {
      * @target web
      */
     static get isRunningInAudioWorklet(): boolean;
-
-
-    /**
-     * @target web
-     * @partial
-     */
-    static throttle(action: () => void, delay: number): () => void;
     /**
      * @target web
      */
@@ -8203,7 +8245,7 @@ export declare class Environment {
     /**
      * @target web
      */
-    static initializeMain(createWebWorker: (settings: Settings) => Worker, createAudioWorklet: (context: AudioContext, settings: Settings) => Promise<void>): void;
+    static initializeMain(createWebWorker: (settings: Settings, nameHint: string) => Worker, createAudioWorklet: (context: AudioContext, settings: Settings) => Promise<void>): void;
 
 
     /**
@@ -9112,6 +9154,7 @@ declare interface IAudioExporter extends Disposable {
      * slightly longer audio is contained in the result.
      *
      * When the song ends, the chunk might contain less than the requested duration.
+     * @async
      */
     render(milliseconds: number): Promise<AudioExportChunk | undefined>;
     destroy(): void;
@@ -9130,6 +9173,7 @@ declare interface IAudioExporterWorker extends IAudioExporter {
      * @param midi The midi file to load
      * @param syncPoints The sync points of the song (if any)
      * @param transpositionPitches The initial transposition pitches for the midi file.
+     * @async
      */
     initialize(options: AudioExportOptions, midi: MidiFile, syncPoints: BackingTrackSyncPoint[], transpositionPitches: Map<number, number>): Promise<void>;
 }
@@ -9283,6 +9327,50 @@ declare interface IContainer {
     mouseUp: IEventEmitterOfT<IMouseEventArgs>;
 }
 
+/**
+ * Classes implementing this interface can handle the cursor placement logic
+ * as the playback in alphaTab progresses.
+ *
+ * @public
+ */
+declare interface ICursorHandler {
+    /**
+     * Called when this handler activates. This can be on dynamic cursor creation
+     * or when setting a custom handler with cursors already created.
+     * @param cursors  A container holding information about the cursor elements.
+     */
+    onAttach(cursors: Cursors): void;
+    /**
+     * Called when this handler deactivates. This can be on dynamic cursor destroy
+     * or when setting a new custom handler.
+     * @param cursors A container holding information about the cursor elements.
+     */
+    onDetach(cursors: Cursors): void;
+    /**
+     * Instructs the handler to place the bar cursor for the given beat bounds instantly .
+     * @param barCursor The bar cursor.
+     * @param beatBounds The bounds of the currently active beat.
+     */
+    placeBarCursor(barCursor: IContainer, beatBounds: BeatBounds): void;
+    /**
+     * Instructs the handler to place the beat cursor for the given beat bounds instantly.
+     * @param barCursor The beat cursor.
+     * @param beatBounds The bounds of the currently active beat.
+     */
+    placeBeatCursor(beatCursor: IContainer, beatBounds: BeatBounds, startBeatX: number): void;
+    /**
+     * Instructs the handler to initiate a transition of the beat cursor (e.g. for dynamic animation).
+     * @param beatCursor The beat cursor
+     * @param beatBounds The bounds of the currently active beat.
+     * @param startBeatX The X-position where the transition of the beat cursor should start.
+     * @param nextBeatX The X-position where the transition of the beat cursor should end
+     * (typically the next beat or end of bar depending on the cursor mode and seeks)
+     * @param duration The duration in milliseconds on how long the transition should take.
+     * @param cursorMode The active cursor mode for the cursor placement.
+     */
+    transitionBeatCursor(beatCursor: IContainer, beatBounds: BeatBounds, startBeatX: number, nextBeatX: number, duration: number, cursorMode: MidiTickLookupFindBeatResultCursorMode): void;
+}
+
 /**
  * An emitter for an event without any value passed to the listeners.
  * @public
@@ -9372,6 +9460,18 @@ declare interface IExternalMediaSynthOutput extends IBackingTrackSynthOutput {
     updatePosition(currentTime: number): void;
 }
 
+/**
+ * A UI element implementation wrapping HTML elements.
+ * @target web
+ * @public
+ */
+declare interface IHtmlElementContainer extends IContainer {
+    /**
+     * The wrapped UI element.
+     */
+    readonly element: HTMLElement;
+}
+
 /**
  * @public
  */
@@ -10163,6 +10263,18 @@ declare interface IUiFacade<TSettings> {
      * @param action
      */
     beginInvoke(action: () => void): void;
+    /**
+     * Creates a throttled/debounced version of the provided action.
+     * @param action The action to call.
+     * @param delay The delay to wait for additional call before actually executing.
+     * @returns A function which executes the provided action after the given delay.
+     * If multiple calls are made before the action is started, the already scheduled
+     * action is cancelled and a new one is scheduled after the given delay.
+     * If called endlessly, the action is never executed.
+     *
+     * Already executing actions will not be cancelled but will complete before another action executes.
+     */
+    throttle(action: () => void, delay: number): () => void;
     /**
      * Tells the UI layer to remove all highlights from highlighted music notation elements.
      */
@@ -10317,7 +10429,7 @@ declare class JsonConverter {
      * @param score The score object to serialize
      * @returns A serialized score object without ciruclar dependencies that can be used for further serializations.
      */
-    static scoreToJsObject(score: Score): unknown;
+    static scoreToJsObject(score: Score): Map<string, unknown> | null;
     /**
      * Converts the given JavaScript object into a score object.
      * @param jsObject The javascript object created via {@link Score}
@@ -11371,6 +11483,11 @@ declare class MidiTickLookup {
      * This info allows building the correct "next" beat and duration.
      */
     multiBarRestInfo: Map<number, number[]> | null;
+    /**
+     * An optional playback range to consider when performing lookups.
+     * This will mainly influence the used {@link MidiTickLookupFindBeatResultCursorMode}
+     */
+    playbackRange: PlaybackRange | null;
     /**
      * Finds the currently played beat given a list of tracks and the current time.
      * @param trackLookup The tracks indices in which to search the played beat for.
@@ -11488,9 +11605,14 @@ declare enum MidiTickLookupFindBeatResultCursorMode {
      */
     ToNextBext = 1,
     /**
-     * The cursor should animate to the end of the bar (typically on repeats and jumps)
+     * @deprecated replaced by {@link ToEndOfBeat}
+     */
+    ToEndOfBar = 2,
+    /**
+     * The cursor should animate to the end of the **beat** (typically on repeats and jumps)
+     * (this is named end of bar historically)
      */
-    ToEndOfBar = 2
+    ToEndOfBeat = 3
 }
 
 /**
@@ -13283,12 +13405,13 @@ export declare namespace platform {
     export {
         Cursors,
         ICanvas,
+        MeasuredText,
         TextAlign,
         TextBaseline,
-        MeasuredText,
         IContainer,
         IMouseEventArgs,
-        IUiFacade
+        IUiFacade,
+        IHtmlElementContainer
     }
 }