@coderline/alphatab 1.6.0-alpha.1409 → 1.6.0-alpha.1416

package/dist/alphaTab.core.mjs

@@ -1,5 +1,5 @@
 /*!
- * alphaTab v1.6.0-alpha.1409 (develop, build 1409)
+ * alphaTab v1.6.0-alpha.1416 (develop, build 1416)
  *
  * Copyright © 2025, Daniel Kuschny and Contributors, All rights reserved.
  *
@@ -1413,7 +1413,7 @@ class SyncPointData {
         this.barOccurence = 0;
         /**
          * The modified tempo at which the cursor should move (aka. the tempo played within the external audio track).
-         * This information is used together with the {@link originalTempo} to calculate how much faster/slower the
+         * This information is used together with normal tempo changes to calculate how much faster/slower the
          * cursor playback is performed to align with the audio track.
          */
         this.modifiedTempo = 0;
@@ -3371,18 +3371,26 @@ class ModelUtils {
         const lookup = new Map();
         const score = tracks[0].score;
         let currentIndex = startIndex;
+        let tempo = score.tempo;
         while (currentIndex <= endIndexInclusive) {
             const currentGroupStartIndex = currentIndex;
             let currentGroup = null;
             while (currentIndex <= endIndexInclusive) {
                 const masterBar = score.masterBars[currentIndex];
+                let hasTempoChange = false;
+                for (const a of masterBar.tempoAutomations) {
+                    if (a.value !== tempo) {
+                        hasTempoChange = true;
+                    }
+                    tempo = a.value;
+                }
                 // check if masterbar breaks multibar rests, it must be fully empty with no annotations
                 if (masterBar.alternateEndings ||
                     (masterBar.isRepeatStart && masterBar.index !== currentGroupStartIndex) ||
                     masterBar.isFreeTime ||
                     masterBar.isAnacrusis ||
                     masterBar.section !== null ||
-                    (masterBar.index !== currentGroupStartIndex && masterBar.tempoAutomations.length > 0) ||
+                    (masterBar.index !== currentGroupStartIndex && hasTempoChange) ||
                     (masterBar.fermata !== null && masterBar.fermata.size > 0) ||
                     (masterBar.directions !== null && masterBar.directions.size > 0)) {
                     break;
@@ -20215,7 +20223,11 @@ class MusicXmlImporter extends ScoreImporter {
         for (const c of element.childElements()) {
             switch (c.localName) {
                 case 'direction-type':
-                    directionTypes.push(c.firstElement);
+                    // See https://github.com/CoderLine/alphaTab/issues/2102
+                    const type = c.firstElement;
+                    if (type) {
+                        directionTypes.push(type);
+                    }
                     break;
                 case 'offset':
                     offset = Number.parseFloat(c.innerText);
@@ -38596,6 +38608,93 @@ class AlphaSynthWrapper {
     }
 }
 
+/**
+ * A {@link IScoreRenderer} implementation wrapping and underling other {@link IScoreRenderer}
+ * allowing dynamic changing of the underlying instance without loosing aspects like the
+ * event listeners.
+ */
+class ScoreRendererWrapper {
+    constructor() {
+        this._width = 0;
+        this._score = null;
+        this._trackIndexes = null;
+        this.preRender = new EventEmitterOfT();
+        this.renderFinished = new EventEmitterOfT();
+        this.partialRenderFinished = new EventEmitterOfT();
+        this.partialLayoutFinished = new EventEmitterOfT();
+        this.postRenderFinished = new EventEmitter();
+        this.error = new EventEmitterOfT();
+    }
+    get instance() {
+        return this._instance;
+    }
+    set instance(value) {
+        this._instance = value;
+        // unregister all events from previous instance
+        const unregister = this._instanceEventUnregister;
+        if (unregister) {
+            for (const e of unregister) {
+                e();
+            }
+        }
+        if (value) {
+            // regsiter to events of new player and forward them to existing listeners
+            const newUnregister = [];
+            newUnregister.push(value.preRender.on(v => this.preRender.trigger(v)));
+            newUnregister.push(value.renderFinished.on(v => this.renderFinished.trigger(v)));
+            newUnregister.push(value.partialRenderFinished.on(v => this.partialRenderFinished.trigger(v)));
+            newUnregister.push(value.partialLayoutFinished.on(v => this.partialLayoutFinished.trigger(v)));
+            newUnregister.push(value.postRenderFinished.on(() => this.postRenderFinished.trigger()));
+            newUnregister.push(value.error.on(v => this.error.trigger(v)));
+            this._instanceEventUnregister = newUnregister;
+            if (this._settings) {
+                value.updateSettings(this._settings);
+            }
+            value.width = this._width;
+            if (this._score !== null) {
+                value.renderScore(this._score, this._trackIndexes);
+            }
+        }
+        else {
+            this._instanceEventUnregister = undefined;
+        }
+    }
+    get boundsLookup() {
+        return this._instance ? this._instance.boundsLookup : null;
+    }
+    get width() {
+        return this._instance ? this._instance.width : 0;
+    }
+    set width(value) {
+        this._width = value;
+        if (this._instance) {
+            this._instance.width = value;
+        }
+    }
+    render() {
+        this._instance?.render();
+    }
+    resizeRender() {
+        this._instance?.resizeRender();
+    }
+    renderScore(score, trackIndexes) {
+        this._score = score;
+        this._trackIndexes = trackIndexes;
+        this._instance?.renderScore(score, trackIndexes);
+    }
+    renderResult(resultId) {
+        this._instance?.renderResult(resultId);
+    }
+    updateSettings(settings) {
+        this._settings = settings;
+        this._instance?.updateSettings(settings);
+    }
+    destroy() {
+        this._instance?.destroy();
+        this._instance = undefined;
+    }
+}
+
 class SelectionInfo {
     constructor(beat) {
         this.bounds = null;
@@ -38610,11 +38709,27 @@ class SelectionInfo {
  */
 class AlphaTabApiBase {
     /**
-     * The actual player mode which is currently active (e.g. allows determining whether a backing track or the synthesizer is active).
+     * The actual player mode which is currently active.
+     * @remarks
+     * Allows determining whether a backing track or the synthesizer is active in case automatic detection is enabled.
+     * @category Properties - Player
+     * @since 1.6.0
      */
     get actualPlayerMode() {
         return this._actualPlayerMode;
     }
+    /**
+     * The score renderer used for rendering the music sheet.
+     * @remarks
+     * This is the low-level API responsible for the actual rendering engine.
+     * Gets access to the underling {@link IScoreRenderer} that is used for the rendering.
+     *
+     * @category Properties - Core
+     * @since 0.9.4
+     */
+    get renderer() {
+        return this._renderer;
+    }
     /**
      * The score holding all information about the song being rendered
      * @category Properties - Core
@@ -38693,6 +38808,7 @@ class AlphaTabApiBase {
         this._previousTick = 0;
         this._currentBeat = null;
         this._currentBeatBounds = null;
+        this._isInitialBeatCursorUpdate = true;
         this._previousStateForCursor = PlayerState.Paused;
         this._previousCursorCache = null;
         this._lastScroll = 0;
@@ -39351,7 +39467,40 @@ class AlphaTabApiBase {
          */
         this.midiLoaded = new EventEmitterOfT();
         /**
-         * @internal
+         * This event is fired when a settings update was requested.
+         *
+         * @eventProperty
+         * @category Events - Core
+         * @since 1.6.0
+         *
+         * @example
+         * JavaScript
+         * ```js
+         * const api = new alphaTab.AlphaTabApi(document.querySelector('#alphaTab'));
+         * api.settingsUpdated.on(() => {
+         *     updateSettingsUI(api.settings);
+         * });
+         * ```
+         *
+         * @example
+         * C#
+         * ```cs
+         * var api = new AlphaTabApi<MyControl>(...);
+         * api.SettingsUpdated.On(() =>
+         * {
+         *     UpdateSettingsUI(api.settings);
+         * });
+         * ```
+         *
+         * @example
+         * Android
+         * ```kotlin
+         * val api = AlphaTabApi<MyControl>(...)
+         * api.SettingsUpdated.on {
+         *     updateSettingsUI(api.settings)
+         * }
+         * ```
+         *
          */
         this.settingsUpdated = new EventEmitter();
         this.uiFacade = uiFacade;
@@ -39365,46 +39514,46 @@ class AlphaTabApiBase {
         Environment.printEnvironmentInfo(false);
         this.canvasElement = uiFacade.createCanvasElement();
         this.container.appendChild(this.canvasElement);
+        this._renderer = new ScoreRendererWrapper();
         if (this.settings.core.useWorkers &&
             this.uiFacade.areWorkersSupported &&
             Environment.getRenderEngineFactory(this.settings.core.engine).supportsWorkers) {
-            this.renderer = this.uiFacade.createWorkerRenderer();
+            this._renderer.instance = this.uiFacade.createWorkerRenderer();
         }
         else {
-            this.renderer = new ScoreRenderer(this.settings);
+            this._renderer.instance = new ScoreRenderer(this.settings);
         }
         this.container.resize.on(Environment.throttle(() => {
             if (this._isDestroyed) {
                 return;
             }
-            if (this.container.width !== this.renderer.width) {
+            if (this.container.width !== this._renderer.width) {
                 this.triggerResize();
             }
         }, uiFacade.resizeThrottle));
         const initialResizeEventInfo = new ResizeEventArgs();
-        initialResizeEventInfo.oldWidth = this.renderer.width;
+        initialResizeEventInfo.oldWidth = this._renderer.width;
         initialResizeEventInfo.newWidth = this.container.width | 0;
         initialResizeEventInfo.settings = this.settings;
         this.onResize(initialResizeEventInfo);
-        this.renderer.preRender.on(this.onRenderStarted.bind(this));
-        this.renderer.renderFinished.on(renderingResult => {
+        this._renderer.preRender.on(this.onRenderStarted.bind(this));
+        this._renderer.renderFinished.on(renderingResult => {
             this.onRenderFinished(renderingResult);
         });
-        this.renderer.postRenderFinished.on(() => {
+        this._renderer.postRenderFinished.on(() => {
             const duration = Date.now() - this._startTime;
             Logger.debug('rendering', `Rendering completed in ${duration}ms`);
             this.onPostRenderFinished();
         });
-        this.renderer.preRender.on(_ => {
+        this._renderer.preRender.on(_ => {
             this._startTime = Date.now();
         });
-        this.renderer.partialLayoutFinished.on(this.appendRenderResult.bind(this));
-        this.renderer.partialRenderFinished.on(this.updateRenderResult.bind(this));
-        this.renderer.renderFinished.on(r => {
-            this.appendRenderResult(r);
-            this.appendRenderResult(null); // marks last element
+        this._renderer.partialLayoutFinished.on(r => this.appendRenderResult(r, false));
+        this._renderer.partialRenderFinished.on(this.updateRenderResult.bind(this));
+        this._renderer.renderFinished.on(r => {
+            this.appendRenderResult(r, true);
         });
-        this.renderer.error.on(this.onError.bind(this));
+        this._renderer.error.on(this.onError.bind(this));
         this.setupPlayerWrapper();
         if (this.settings.player.playerMode !== PlayerMode.Disabled) {
             this.setupOrDestroyPlayer();
@@ -39479,7 +39628,7 @@ class AlphaTabApiBase {
         this._isDestroyed = true;
         this._player.destroy();
         this.uiFacade.destroy();
-        this.renderer.destroy();
+        this._renderer.destroy();
     }
     /**
      * Applies any changes that were done to the settings object.
@@ -39524,12 +39673,30 @@ class AlphaTabApiBase {
         if (score) {
             ModelUtils.applyPitchOffsets(this.settings, score);
         }
-        this.renderer.updateSettings(this.settings);
-        if (this.setupOrDestroyPlayer()) {
-            this.loadMidiForScore();
-        }
+        this.updateRenderer();
+        this._renderer.updateSettings(this.settings);
+        this.setupOrDestroyPlayer();
         this.onSettingsUpdated();
     }
+    updateRenderer() {
+        const renderer = this._renderer;
+        if (this.settings.core.useWorkers &&
+            this.uiFacade.areWorkersSupported &&
+            Environment.getRenderEngineFactory(this.settings.core.engine).supportsWorkers) {
+            // switch from non-worker to worker renderer
+            if (renderer.instance instanceof ScoreRenderer) {
+                renderer.destroy();
+                renderer.instance = this.uiFacade.createWorkerRenderer();
+            }
+        }
+        else {
+            // switch from worker to non-worker renderer
+            if (!(renderer.instance instanceof ScoreRenderer)) {
+                renderer.destroy();
+                renderer.instance = new ScoreRenderer(this.settings);
+            }
+        }
+    }
     /**
      * Initiates a load of the score using the given data.
      * @returns true if the data object is supported and a load was initiated, otherwise false
@@ -39724,30 +39891,33 @@ class AlphaTabApiBase {
         }
         else {
             const resizeEventInfo = new ResizeEventArgs();
-            resizeEventInfo.oldWidth = this.renderer.width;
+            resizeEventInfo.oldWidth = this._renderer.width;
             resizeEventInfo.newWidth = this.container.width;
             resizeEventInfo.settings = this.settings;
             this.onResize(resizeEventInfo);
-            this.renderer.updateSettings(this.settings);
-            this.renderer.width = this.container.width;
-            this.renderer.resizeRender();
+            this._renderer.updateSettings(this.settings);
+            this._renderer.width = this.container.width;
+            this._renderer.resizeRender();
         }
     }
-    appendRenderResult(result) {
-        if (result) {
+    appendRenderResult(result, isLast) {
+        // resizing the canvas and wrapper elements at the end is enough
+        // it avoids flickering on resizes and re-renders. 
+        // the individual partials are anyhow sized correctly
+        if (isLast) {
             this.canvasElement.width = result.totalWidth;
             this.canvasElement.height = result.totalHeight;
             if (this._cursorWrapper) {
                 this._cursorWrapper.width = result.totalWidth;
                 this._cursorWrapper.height = result.totalHeight;
             }
-            if (result.width > 0 || result.height > 0) {
-                this.uiFacade.beginAppendRenderResults(result);
-            }
         }
-        else {
+        if (result.width > 0 || result.height > 0) {
             this.uiFacade.beginAppendRenderResults(result);
         }
+        if (isLast) {
+            this.uiFacade.beginAppendRenderResults(null);
+        }
     }
     updateRenderResult(result) {
         if (result && result.renderResult) {
@@ -39909,13 +40079,10 @@ class AlphaTabApiBase {
      * ```
      */
     render() {
-        if (!this.renderer) {
-            return;
-        }
         if (this.uiFacade.canRender) {
             // when font is finally loaded, start rendering
-            this.renderer.width = this.container.width;
-            this.renderer.renderScore(this.score, this._trackIndexes);
+            this._renderer.width = this.container.width;
+            this._renderer.renderScore(this.score, this._trackIndexes);
         }
         else {
             this.uiFacade.canRenderChanged.on(() => this.render());
@@ -39990,7 +40157,7 @@ class AlphaTabApiBase {
      * @since 1.5.0
      */
     get boundsLookup() {
-        return this.renderer.boundsLookup;
+        return this._renderer.boundsLookup;
     }
     /**
      * The alphaSynth player used for playback.
@@ -40422,6 +40589,10 @@ class AlphaTabApiBase {
         this._previousTick = 0;
         this.destroyCursors();
     }
+    /**
+     *
+     * @returns true if a new player was created, false if no player was created (includes destroy & reuse of the current one)
+     */
     setupOrDestroyPlayer() {
         let mode = this.settings.player.playerMode;
         if (mode === PlayerMode.EnabledAutomatic) {
@@ -40439,6 +40610,7 @@ class AlphaTabApiBase {
         let newPlayer = null;
         if (mode !== this._actualPlayerMode) {
             this.destroyPlayer();
+            this.updateCursors();
             switch (mode) {
                 case PlayerMode.Disabled:
                     newPlayer = null;
@@ -40456,9 +40628,9 @@ class AlphaTabApiBase {
         }
         else {
             // no change in player mode, just update song info if needed
-            return true;
+            this.updateCursors();
+            return false;
         }
-        this.updateCursors();
         this._actualPlayerMode = mode;
         if (!newPlayer) {
             return false;
@@ -40466,6 +40638,13 @@ class AlphaTabApiBase {
         this._player.instance = newPlayer;
         return false;
     }
+    /**
+     * Re-creates the midi for the current score and loads it.
+     * @remarks
+     * This will result in the player to stop playback. Some setting changes require re-genration of the midi song.
+     * @category Methods - Player
+     * @since 1.6.0
+     */
     loadMidiForScore() {
         if (!this.score) {
             return;
@@ -40869,6 +41048,7 @@ class AlphaTabApiBase {
                 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);
@@ -40908,7 +41088,7 @@ class AlphaTabApiBase {
         if (!beat) {
             return;
         }
-        const cache = this.renderer.boundsLookup;
+        const cache = this._renderer.boundsLookup;
         if (!cache) {
             return;
         }
@@ -41031,6 +41211,7 @@ class AlphaTabApiBase {
                 if (isPlayingUpdate) {
                     // we do not "reset" the cursor if we are smoothly moving from left to right.
                     const jumpCursor = !previousBeatBounds ||
+                        this._isInitialBeatCursorUpdate ||
                         barBounds.y !== previousBeatBounds.barBounds.masterBarBounds.visualBounds.y ||
                         startBeatX < previousBeatBounds.onNotesX ||
                         barBoundings.index > previousBeatBounds.barBounds.masterBarBounds.index + 1;
@@ -41055,13 +41236,16 @@ class AlphaTabApiBase {
             }
             else {
                 // ticking cursor
+                beatCursor.transitionToX(0, startBeatX);
                 beatCursor.setBounds(startBeatX, barBounds.y, 1, barBounds.h);
             }
+            this._isInitialBeatCursorUpdate = false;
         }
-        // if playing, animate the cursor to the next beat
-        if (this.settings.player.enableElementHighlighting) {
-            this.uiFacade.removeHighlights();
+        else {
+            this._isInitialBeatCursorUpdate = true;
         }
+        // if playing, animate the cursor to the next beat
+        this.uiFacade.removeHighlights();
         // actively playing? -> animate cursor and highlight items
         let shouldNotifyBeatChange = false;
         if (isPlayingUpdate) {
@@ -41225,11 +41409,11 @@ class AlphaTabApiBase {
             }
             const relX = e.getX(this.canvasElement);
             const relY = e.getY(this.canvasElement);
-            const beat = this.renderer.boundsLookup?.getBeatAtPos(relX, relY) ?? null;
+            const beat = this._renderer.boundsLookup?.getBeatAtPos(relX, relY) ?? null;
             if (beat) {
                 this.onBeatMouseDown(e, beat);
                 if (this.settings.core.includeNoteBounds) {
-                    const note = this.renderer.boundsLookup?.getNoteAtPos(beat, relX, relY);
+                    const note = this._renderer.boundsLookup?.getNoteAtPos(beat, relX, relY);
                     if (note) {
                         this.onNoteMouseDown(e, note);
                     }
@@ -41242,11 +41426,11 @@ class AlphaTabApiBase {
             }
             const relX = e.getX(this.canvasElement);
             const relY = e.getY(this.canvasElement);
-            const beat = this.renderer.boundsLookup?.getBeatAtPos(relX, relY) ?? null;
+            const beat = this._renderer.boundsLookup?.getBeatAtPos(relX, relY) ?? null;
             if (beat) {
                 this.onBeatMouseMove(e, beat);
                 if (this._noteMouseDown) {
-                    const note = this.renderer.boundsLookup?.getNoteAtPos(beat, relX, relY);
+                    const note = this._renderer.boundsLookup?.getNoteAtPos(beat, relX, relY);
                     if (note) {
                         this.onNoteMouseMove(e, note);
                     }
@@ -41262,11 +41446,11 @@ class AlphaTabApiBase {
             }
             const relX = e.getX(this.canvasElement);
             const relY = e.getY(this.canvasElement);
-            const beat = this.renderer.boundsLookup?.getBeatAtPos(relX, relY) ?? null;
+            const beat = this._renderer.boundsLookup?.getBeatAtPos(relX, relY) ?? null;
             this.onBeatMouseUp(e, beat);
             if (this._noteMouseDown) {
                 if (beat) {
-                    const note = this.renderer.boundsLookup?.getNoteAtPos(beat, relX, relY) ?? null;
+                    const note = this._renderer.boundsLookup?.getNoteAtPos(beat, relX, relY) ?? null;
                     this.onNoteMouseUp(e, note);
                 }
                 else {
@@ -41274,7 +41458,7 @@ class AlphaTabApiBase {
                 }
             }
         });
-        this.renderer.postRenderFinished.on(() => {
+        this._renderer.postRenderFinished.on(() => {
             if (!this._selectionStart ||
                 this.settings.player.playerMode === PlayerMode.Disabled ||
                 !this.settings.player.enableCursor ||
@@ -41285,7 +41469,7 @@ class AlphaTabApiBase {
         });
     }
     cursorSelectRange(startBeat, endBeat) {
-        const cache = this.renderer.boundsLookup;
+        const cache = this._renderer.boundsLookup;
         if (!cache) {
             return;
         }
@@ -41354,7 +41538,8 @@ class AlphaTabApiBase {
         }
         this.scoreLoaded.trigger(score);
         this.uiFacade.triggerEvent(this.container, 'scoreLoaded', score);
-        if (this.setupOrDestroyPlayer()) {
+        if (!this.setupOrDestroyPlayer()) {
+            // feed midi into current player (a new player will trigger a midi generation once the player is ready)
             this.loadMidiForScore();
         }
     }
@@ -41384,7 +41569,7 @@ class AlphaTabApiBase {
             return;
         }
         this._currentBeat = null;
-        this.cursorUpdateTick(this._previousTick, false, 1, this._previousTick > 10);
+        this.cursorUpdateTick(this._previousTick, false, 1, true, true);
         this.postRenderFinished.trigger();
         this.uiFacade.triggerEvent(this.container, 'postRenderFinished', null);
     }
@@ -46940,7 +47125,7 @@ class StaffSystem {
         return this.masterBarsRenderers[0].masterBar.index;
     }
     get lastBarIndex() {
-        return this.masterBarsRenderers[this.masterBarsRenderers.length - 1].masterBar.index;
+        return this.masterBarsRenderers[this.masterBarsRenderers.length - 1].lastMasterBarIndex;
     }
     addMasterBarRenderers(tracks, renderers) {
         if (tracks.length === 0) {
@@ -47754,6 +47939,9 @@ class ScoreLayout {
                     }
                 }
             }
+            else {
+                this.tuningGlyph = null;
+            }
         }
         // chord diagram glyphs
         if (notation.isNotationElementVisible(NotationElement.ChordDiagrams)) {
@@ -47782,6 +47970,12 @@ class ScoreLayout {
                     }
                 }
             }
+            if (this.chordDiagrams.isEmpty) {
+                this.chordDiagrams = null;
+            }
+        }
+        else {
+            this.chordDiagrams = null;
         }
     }
     createEmptyStaffSystem() {
@@ -60525,9 +60719,9 @@ class VersionInfo {
         print(`build date: ${VersionInfo.date}`);
     }
 }
-VersionInfo.version = '1.6.0-alpha.1409';
-VersionInfo.date = '2025-05-14T02:06:32.990Z';
-VersionInfo.commit = 'f91fed13b0a0946b3fa9306b480ddf8044b948e2';
+VersionInfo.version = '1.6.0-alpha.1416';
+VersionInfo.date = '2025-05-19T16:41:23.634Z';
+VersionInfo.commit = '4aff072e1be5292482c3d77f434dd1555b6cbb8d';
 
 /**
  * A factory for custom layout engines.
@@ -64841,9 +65035,11 @@ const _barrel = /*#__PURE__*/Object.freeze(/*#__PURE__*/Object.defineProperty({
     ActiveBeatsChangedEventArgs,
     AlphaSynth,
     AlphaSynthAudioWorkletOutput,
+    AlphaSynthBase,
     AlphaSynthScriptProcessorOutput,
     AlphaSynthWebAudioOutputBase,
     AlphaSynthWebWorkerApi,
+    BackingTrackSyncPoint,
     CircularSampleBuffer,
     MidiEventsPlayedEventArgs,
     PlaybackRange,