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

package/dist/alphaTab.js

@@ -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.
  *
@@ -1419,7 +1419,7 @@
             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;
@@ -3377,18 +3377,26 @@
             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;
@@ -20221,7 +20229,11 @@
             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);
@@ -38602,6 +38614,93 @@
         }
     }
 
+    /**
+     * 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;
@@ -38616,11 +38715,27 @@
      */
     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
@@ -38699,6 +38814,7 @@
             this._previousTick = 0;
             this._currentBeat = null;
             this._currentBeatBounds = null;
+            this._isInitialBeatCursorUpdate = true;
             this._previousStateForCursor = PlayerState.Paused;
             this._previousCursorCache = null;
             this._lastScroll = 0;
@@ -39357,7 +39473,40 @@
              */
             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;
@@ -39371,46 +39520,46 @@
             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 !== exports.PlayerMode.Disabled) {
                 this.setupOrDestroyPlayer();
@@ -39485,7 +39634,7 @@
             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.
@@ -39530,12 +39679,30 @@
             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
@@ -39730,30 +39897,33 @@
             }
             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) {
@@ -39915,13 +40085,10 @@
          * ```
          */
         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());
@@ -39996,7 +40163,7 @@
          * @since 1.5.0
          */
         get boundsLookup() {
-            return this.renderer.boundsLookup;
+            return this._renderer.boundsLookup;
         }
         /**
          * The alphaSynth player used for playback.
@@ -40428,6 +40595,10 @@
             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 === exports.PlayerMode.EnabledAutomatic) {
@@ -40445,6 +40616,7 @@
             let newPlayer = null;
             if (mode !== this._actualPlayerMode) {
                 this.destroyPlayer();
+                this.updateCursors();
                 switch (mode) {
                     case exports.PlayerMode.Disabled:
                         newPlayer = null;
@@ -40462,9 +40634,9 @@
             }
             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;
@@ -40472,6 +40644,13 @@
             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;
@@ -40875,6 +41054,7 @@
                     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);
@@ -40914,7 +41094,7 @@
             if (!beat) {
                 return;
             }
-            const cache = this.renderer.boundsLookup;
+            const cache = this._renderer.boundsLookup;
             if (!cache) {
                 return;
             }
@@ -41037,6 +41217,7 @@
                     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;
@@ -41061,13 +41242,16 @@
                 }
                 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) {
@@ -41231,11 +41415,11 @@
                 }
                 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);
                         }
@@ -41248,11 +41432,11 @@
                 }
                 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);
                         }
@@ -41268,11 +41452,11 @@
                 }
                 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 {
@@ -41280,7 +41464,7 @@
                     }
                 }
             });
-            this.renderer.postRenderFinished.on(() => {
+            this._renderer.postRenderFinished.on(() => {
                 if (!this._selectionStart ||
                     this.settings.player.playerMode === exports.PlayerMode.Disabled ||
                     !this.settings.player.enableCursor ||
@@ -41291,7 +41475,7 @@
             });
         }
         cursorSelectRange(startBeat, endBeat) {
-            const cache = this.renderer.boundsLookup;
+            const cache = this._renderer.boundsLookup;
             if (!cache) {
                 return;
             }
@@ -41360,7 +41544,8 @@
             }
             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();
             }
         }
@@ -41390,7 +41575,7 @@
                 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);
         }
@@ -46946,7 +47131,7 @@
             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) {
@@ -47760,6 +47945,9 @@
                         }
                     }
                 }
+                else {
+                    this.tuningGlyph = null;
+                }
             }
             // chord diagram glyphs
             if (notation.isNotationElementVisible(exports.NotationElement.ChordDiagrams)) {
@@ -47788,6 +47976,12 @@
                         }
                     }
                 }
+                if (this.chordDiagrams.isEmpty) {
+                    this.chordDiagrams = null;
+                }
+            }
+            else {
+                this.chordDiagrams = null;
             }
         }
         createEmptyStaffSystem() {
@@ -60531,9 +60725,9 @@
             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.
@@ -64847,9 +65041,11 @@
         ActiveBeatsChangedEventArgs,
         AlphaSynth,
         AlphaSynthAudioWorkletOutput,
+        AlphaSynthBase,
         AlphaSynthScriptProcessorOutput,
         AlphaSynthWebAudioOutputBase,
         AlphaSynthWebWorkerApi,
+        BackingTrackSyncPoint,
         CircularSampleBuffer,
         MidiEventsPlayedEventArgs,
         PlaybackRange,