@coderline/alphatab 1.6.0-alpha.1426 → 1.6.0-alpha.1428

package/dist/alphaTab.core.mjs

@@ -1,5 +1,5 @@
 /*!
- * alphaTab v1.6.0-alpha.1426 (develop, build 1426)
+ * alphaTab v1.6.0-alpha.1428 (develop, build 1428)
  *
  * Copyright © 2025, Daniel Kuschny and Contributors, All rights reserved.
  *
@@ -1418,7 +1418,7 @@ class SyncPointData {
          */
         this.modifiedTempo = 0;
         /**
-         * The uadio offset marking the position within the audio track in milliseconds.
+         * The audio offset marking the position within the audio track in milliseconds.
          * This information is used to regularly sync (or on seeking) to match a given external audio time axis with the internal time axis.
          */
         this.millisecondOffset = 0;
@@ -7299,6 +7299,61 @@ class Score {
             this.tracks[i].finish(settings, sharedDataBag);
         }
     }
+    /**
+     * Applies the given list of {@link FlatSyncPoint} to this song.
+     * @param syncPoints The list of sync points to apply.
+     * @since 1.6.0
+     */
+    applyFlatSyncPoints(syncPoints) {
+        for (const b of this.masterBars) {
+            b.syncPoints = undefined;
+        }
+        for (const syncPoint of syncPoints) {
+            const automation = new Automation();
+            automation.ratioPosition = Math.min(1, Math.max(0, syncPoint.barPosition));
+            automation.type = AutomationType.SyncPoint;
+            automation.syncPointValue = new SyncPointData();
+            automation.syncPointValue.modifiedTempo = syncPoint.modifiedTempo;
+            automation.syncPointValue.millisecondOffset = syncPoint.millisecondOffset;
+            automation.syncPointValue.barOccurence = syncPoint.barOccurence;
+            if (syncPoint.barIndex < this.masterBars.length) {
+                this.masterBars[syncPoint.barIndex].addSyncPoint(automation);
+            }
+        }
+        for (const b of this.masterBars) {
+            if (b.syncPoints) {
+                b.syncPoints.sort((a, b) => {
+                    const occurence = a.syncPointValue.barOccurence - b.syncPointValue.barOccurence;
+                    if (occurence !== 0) {
+                        return occurence;
+                    }
+                    return a.ratioPosition - b.ratioPosition;
+                });
+            }
+        }
+    }
+    /**
+     * Exports all sync points in this song to a {@link FlatSyncPoint} list.
+     * @since 1.6.0
+     */
+    exportFlatSyncPoints() {
+        const syncPoints = [];
+        for (const masterBar of this.masterBars) {
+            const masterBarSyncPoints = masterBar.syncPoints;
+            if (masterBarSyncPoints) {
+                for (const syncPoint of masterBarSyncPoints) {
+                    syncPoints.push({
+                        barIndex: masterBar.index,
+                        barOccurence: syncPoint.syncPointValue.barOccurence,
+                        barPosition: syncPoint.ratioPosition,
+                        millisecondOffset: syncPoint.syncPointValue.millisecondOffset,
+                        modifiedTempo: syncPoint.syncPointValue.modifiedTempo
+                    });
+                }
+            }
+        }
+        return syncPoints;
+    }
 }
 
 /**
@@ -13607,6 +13662,7 @@ var XmlNodeType;
     XmlNodeType[XmlNodeType["CDATA"] = 3] = "CDATA";
     XmlNodeType[XmlNodeType["Document"] = 4] = "Document";
     XmlNodeType[XmlNodeType["DocumentType"] = 5] = "DocumentType";
+    XmlNodeType[XmlNodeType["Comment"] = 6] = "Comment";
 })(XmlNodeType || (XmlNodeType = {}));
 class XmlNode {
     constructor() {
@@ -14183,7 +14239,7 @@ class XmlWriter {
                         this.indent();
                         for (const child of xml.childNodes) {
                             // skip text nodes in case of multiple children
-                            if (child.nodeType === XmlNodeType.Element) {
+                            if (child.nodeType === XmlNodeType.Element || child.nodeType === XmlNodeType.Comment) {
                                 this.writeNode(child);
                             }
                         }
@@ -14214,6 +14270,9 @@ class XmlWriter {
             case XmlNodeType.DocumentType:
                 this.write(`<!DOCTYPE ${xml.value}>`);
                 break;
+            case XmlNodeType.Comment:
+                this.write(`<!-- ${xml.value} -->`);
+                break;
         }
     }
     unindend() {
@@ -16810,7 +16869,7 @@ GpifParser.BendPointPositionFactor = BendPoint.MaxPosition / 100.0;
  * Internal Range: 1 per quarter note
  */
 GpifParser.BendPointValueFactor = 1 / 25.0;
-// test have shown that Guitar Pro seem to always work with 44100hz for the frame offsets,
+// tests have shown that Guitar Pro seem to always work with 44100hz for the frame offsets,
 // they are NOT using the sample rate of the input file. 
 // Downsampling a 44100hz ogg to 8000hz and using it in as audio track resulted in the same frame offset when placing sync points.
 GpifParser.SampleRate = 44100;
@@ -22619,6 +22678,8 @@ class MidiFileSequencer {
             }
         }
         state.syncPointIndex = 0;
+        state.modifiedTempo =
+            state.syncPoints.length > 0 ? state.syncPoints[0].modifiedTempo : state.currentTempo;
     }
     currentTimePositionToTickPosition(timePosition) {
         const state = this._currentState;
@@ -38480,6 +38541,7 @@ class AlphaSynthWrapper {
                 value.playbackSpeed = this._playbackSpeed;
                 value.isLooping = this._isLooping;
                 value.midiEventsPlayedFilter = this._midiEventsPlayedFilter;
+                this.ready.trigger();
             }
             else {
                 newUnregister.push(value.ready.on(() => {
@@ -43840,6 +43902,9 @@ class AudioElementBackingTrackSynthOutput {
         const audioElement = document.createElement('audio');
         audioElement.style.display = 'none';
         document.body.appendChild(audioElement);
+        audioElement.addEventListener('seeked', () => {
+            this.updatePosition();
+        });
         audioElement.addEventListener('timeupdate', () => {
             this.updatePosition();
         });
@@ -60935,9 +61000,9 @@ class VersionInfo {
         print(`build date: ${VersionInfo.date}`);
     }
 }
-VersionInfo.version = '1.6.0-alpha.1426';
-VersionInfo.date = '2025-05-27T02:07:22.361Z';
-VersionInfo.commit = '6f8b50015eb3eaebd605045bc9f5aaf6fbf2882d';
+VersionInfo.version = '1.6.0-alpha.1428';
+VersionInfo.date = '2025-05-29T00:44:50.954Z';
+VersionInfo.commit = 'fa81a14da248f229511867324cee663ea70a72b3';
 
 /**
  * A factory for custom layout engines.
@@ -61850,18 +61915,24 @@ class GpifWriter {
     writeDom(parent, score) {
         const gpif = parent.addElement('GPIF');
         // just some values at the time this was implemented,
-        gpif.addElement('GPVersion').innerText = '7';
+        gpif.addElement('GPVersion').innerText = '8.1.3';
         const gpRevision = gpif.addElement('GPRevision');
-        gpRevision.innerText = '7';
-        gpRevision.attributes.set('required', '12021');
-        gpRevision.attributes.set('recommended', '12023');
-        gpRevision.innerText = '12025';
-        gpif.addElement('Encoding').addElement('EncodingDescription').innerText = 'GP7';
+        gpRevision.attributes.set('required', '12024');
+        gpRevision.attributes.set('recommended', '13000');
+        gpRevision.innerText = '13007';
+        const encoding = gpif.addElement('Encoding');
+        encoding.addElement('EncodingDescription').innerText = 'GP8';
+        const alphaTabComment = new XmlNode();
+        alphaTabComment.nodeType = XmlNodeType.Comment;
+        alphaTabComment.value = `Written by alphaTab ${VersionInfo.version} (${VersionInfo.commit})`;
+        encoding.addChild(alphaTabComment);
         this.writeScoreNode(gpif, score);
         this.writeMasterTrackNode(gpif, score);
+        this.writeBackingTrackNode(gpif, score);
         this.writeAudioTracksNode(gpif, score);
         this.writeTracksNode(gpif, score);
         this.writeMasterBarsNode(gpif, score);
+        this.writeAssets(gpif, score);
         const bars = gpif.addElement('Bars');
         const voices = gpif.addElement('Voices');
         const beats = gpif.addElement('Beats');
@@ -61884,6 +61955,42 @@ class GpifWriter {
             }
         }
     }
+    writeAssets(parent, score) {
+        if (!score.backingTrack?.rawAudioFile) {
+            return;
+        }
+        const assets = parent.addElement('Assets');
+        const asset = assets.addElement('Asset');
+        asset.attributes.set('id', this.backingTrackAssetId);
+        this.backingTrackAssetFileName = 'Content/Assets/backing-track';
+        asset.addElement('EmbeddedFilePath').setCData(this.backingTrackAssetFileName);
+    }
+    writeBackingTrackNode(parent, score) {
+        if (!score.backingTrack?.rawAudioFile) {
+            return;
+        }
+        const backingTrackNode = parent.addElement('BackingTrack');
+        const backingTrackAssetId = '0';
+        this.backingTrackAssetId = backingTrackAssetId;
+        backingTrackNode.addElement('IconId').innerText = '21';
+        backingTrackNode.addElement('Color').innerText = '0 0 0';
+        backingTrackNode.addElement('Name').setCData('Audio Track');
+        backingTrackNode.addElement('ShortName').setCData('a.track');
+        backingTrackNode.addElement('PlaybackState').innerText = 'Default';
+        backingTrackNode.addElement('Enabled').innerText = 'true';
+        backingTrackNode.addElement('Source').innerText = 'Local';
+        backingTrackNode.addElement('AssetId').innerText = backingTrackAssetId;
+        const channelStrip = backingTrackNode.addElement('ChannelStrip');
+        channelStrip.addElement('Parameters').innerText =
+            '0.500000 0.500000 0.500000 0.500000 0.500000 0.500000 0.500000 0.500000 0.500000 0.000000 0.500000 0.500000 0.800000 0.500000 0.500000 0.500000';
+        channelStrip.addElement('YouTubeVideoUrl').innerText = '';
+        channelStrip.addElement('Filter').innerText = '6';
+        channelStrip.addElement('FramesPerPixel').innerText = '400';
+        const framePadding = this.backingTrackFramePadding !== undefined ? this.backingTrackFramePadding : 0;
+        backingTrackNode.addElement('FramePadding').innerText = `${framePadding}`;
+        backingTrackNode.addElement('Semitones').innerText = '0';
+        backingTrackNode.addElement('Cents').innerText = '0';
+    }
     writeNoteNode(parent, note) {
         const noteNode = parent.addElement('Note');
         noteNode.attributes.set('id', note.id.toString());
@@ -62540,6 +62647,11 @@ class GpifWriter {
                 initialTempoAutomation.addElement('Text').innerText = score.tempoLabel;
             }
         }
+        const initialSyncPoint = score.masterBars[0].syncPoints
+            ? score.masterBars[0].syncPoints.find(p => p.ratioPosition === 0 && p.syncPointValue.barOccurence === 0)
+            : undefined;
+        const millisecondPadding = initialSyncPoint ? initialSyncPoint.syncPointValue.millisecondOffset : 0;
+        this.backingTrackFramePadding = (-1 * ((millisecondPadding / 1000) * GpifWriter.SampleRate)) | 0;
         for (const mb of score.masterBars) {
             for (const automation of mb.tempoAutomations) {
                 const tempoAutomation = automations.addElement('Automation');
@@ -62553,6 +62665,25 @@ class GpifWriter {
                     tempoAutomation.addElement('Text').innerText = automation.text;
                 }
             }
+            if (mb.syncPoints) {
+                for (const syncPoint of mb.syncPoints) {
+                    const syncPointAutomation = automations.addElement('Automation');
+                    syncPointAutomation.addElement('Type').innerText = 'SyncPoint';
+                    syncPointAutomation.addElement('Linear').innerText = 'false';
+                    syncPointAutomation.addElement('Bar').innerText = mb.index.toString();
+                    syncPointAutomation.addElement('Position').innerText = syncPoint.ratioPosition.toString();
+                    syncPointAutomation.addElement('Visible').innerText = 'true';
+                    const value = syncPointAutomation.addElement('Value');
+                    value.addElement('BarIndex').innerText = mb.index.toString();
+                    value.addElement('BarOccurrence').innerText = syncPoint.syncPointValue.barOccurence.toString();
+                    value.addElement('ModifiedTempo').innerText = syncPoint.syncPointValue.modifiedTempo.toString();
+                    value.addElement('OriginalTempo').innerText = score.tempo.toString();
+                    const frameOffset = (((syncPoint.syncPointValue.millisecondOffset - millisecondPadding) / 1000) *
+                        GpifWriter.SampleRate) |
+                        0;
+                    value.addElement('FrameOffset').innerText = frameOffset.toString();
+                }
+            }
         }
     }
     writeAudioTracksNode(parent, score) {
@@ -63203,6 +63334,10 @@ class GpifWriter {
         voiceNode.addElement('Beats').innerText = voice.beats.map(v => v.id).join(' ');
     }
 }
+// tests have shown that Guitar Pro seem to always work with 44100hz for the frame offsets,
+// they are NOT using the sample rate of the input file.
+// Downsampling a 44100hz ogg to 8000hz and using it in as audio track resulted in the same frame offset when placing sync points.
+GpifWriter.SampleRate = 44100;
 GpifWriter.MidiProgramInfoLookup = new Map([
     [0, new GpifMidiProgramInfo(GpifIconIds.Piano, 'Acoustic Piano')],
     [1, new GpifMidiProgramInfo(GpifIconIds.Piano, 'Acoustic Piano')],
@@ -64940,11 +65075,11 @@ class ZipWriter {
 }
 
 /**
- * This ScoreExporter can write Guitar Pro 7 (gp) files.
+ * This ScoreExporter can write Guitar Pro 7+ (gp) files.
  */
 class Gp7Exporter extends ScoreExporter {
     get name() {
-        return 'Guitar Pro 7';
+        return 'Guitar Pro 7-8';
     }
     writeScore(score) {
         Logger.debug(this.name, 'Writing data entries');
@@ -64961,6 +65096,9 @@ class Gp7Exporter extends ScoreExporter {
         fileSystem.writeEntry(new ZipEntry('Content/PartConfiguration', partConfiguration));
         fileSystem.writeEntry(new ZipEntry('Content/LayoutConfiguration', layoutConfiguration));
         fileSystem.writeEntry(new ZipEntry('Content/score.gpif', IOHelper.stringToBytes(gpifXml)));
+        if (gpifWriter.backingTrackAssetFileName) {
+            fileSystem.writeEntry(new ZipEntry(gpifWriter.backingTrackAssetFileName, score.backingTrack.rawAudioFile));
+        }
         fileSystem.end();
     }
 }

package/dist/alphaTab.d.ts

@@ -6474,6 +6474,36 @@ declare enum Fingers {
     LittleFinger = 4
 }
 
+/**
+ * A simple flat sync point for easy persistence separate to the main data model.
+ * @record
+ */
+declare interface FlatSyncPoint {
+    /**
+     * Indicates index of the masterbar for which this sync point is valid.
+     */
+    barIndex: number;
+    /**
+     * Indicates relative position (0-1) of the sync point in within the masterbar.
+     */
+    barPosition: number;
+    /**
+     * Indicates for which repeat occurence this sync point is valid (e.g. 0 on the first time played, 1 on the second time played)
+     */
+    barOccurence: number;
+    /**
+     * The modified tempo at which the cursor should move (aka. the tempo played within the external audio track).
+     * 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.
+     */
+    modifiedTempo: number;
+    /**
+     * The uadio offset marking the position within the audio track in milliseconds.
+     * This information is used to regularly sync (or on seeking) to match a given external audio time axis with the internal time axis.
+     */
+    millisecondOffset: number;
+}
+
 /**
  * @json_immutable
  */
@@ -6706,7 +6736,7 @@ declare enum GolpeType {
 }
 
 /**
- * This ScoreExporter can write Guitar Pro 7 (gp) files.
+ * This ScoreExporter can write Guitar Pro 7+ (gp) files.
  */
 declare class Gp7Exporter extends ScoreExporter {
     get name(): string;
@@ -7453,6 +7483,52 @@ export declare interface IEventEmitterOfT<T> {
     off(value: (arg: T) => void): void;
 }
 
+/**
+ * A custom handler for integrating alphaTab with an external media source.
+ */
+declare interface IExternalMediaHandler {
+    /**
+     * The total duration of the backing track in milliseconds.
+     */
+    readonly backingTrackDuration: number;
+    /**
+     * The playback rate at which the output should playback.
+     */
+    playbackRate: number;
+    /**
+     * The volume at which the output should play (0-1)
+     */
+    masterVolume: number;
+    /**
+     * Instructs the output to seek to the given time position.
+     * @param time The absolute time in milliseconds.
+     */
+    seekTo(time: number): void;
+    /**
+     * Instructs the external media to start the playback.
+     */
+    play(): void;
+    /**
+     * Instructs the external media to pause the playback.
+     */
+    pause(): void;
+}
+
+/**
+ * A output handling the playback via an external media.
+ */
+declare interface IExternalMediaSynthOutput extends IBackingTrackSynthOutput {
+    /**
+     * The handler to which the media control will be delegated.
+     */
+    handler: IExternalMediaHandler | undefined;
+    /**
+     * Updates the playback position from the external media source.
+     * @param currentTime The current time in the external media.
+     */
+    updatePosition(currentTime: number): void;
+}
+
 export declare interface ILogger {
     debug(category: string, msg: string, ...details: unknown[]): void;
     warning(category: string, msg: string, ...details: unknown[]): void;
@@ -9539,6 +9615,7 @@ export declare namespace model {
         AutomationType,
         Automation,
         SyncPointData,
+        FlatSyncPoint,
         Bar,
         SustainPedalMarkerType,
         SustainPedalMarker,
@@ -12740,6 +12817,17 @@ declare class Score {
     private addMasterBarToRepeatGroups;
     addTrack(track: Track): void;
     finish(settings: Settings): void;
+    /**
+     * Applies the given list of {@link FlatSyncPoint} to this song.
+     * @param syncPoints The list of sync points to apply.
+     * @since 1.6.0
+     */
+    applyFlatSyncPoints(syncPoints: FlatSyncPoint[]): void;
+    /**
+     * Exports all sync points in this song to a {@link FlatSyncPoint} list.
+     * @since 1.6.0
+     */
+    exportFlatSyncPoints(): FlatSyncPoint[];
 }
 
 /**
@@ -13575,7 +13663,7 @@ declare class SyncPointData {
      */
     modifiedTempo: number;
     /**
-     * The uadio offset marking the position within the audio track in milliseconds.
+     * The audio offset marking the position within the audio track in milliseconds.
      * This information is used to regularly sync (or on seeking) to match a given external audio time axis with the internal time axis.
      */
     millisecondOffset: number;
@@ -13602,7 +13690,9 @@ export declare namespace synth {
         AlphaSynthWebAudioOutputBase,
         AlphaSynthScriptProcessorOutput,
         AlphaSynthAudioWorkletOutput,
-        IAudioElementBackingTrackSynthOutput
+        IAudioElementBackingTrackSynthOutput,
+        IExternalMediaHandler,
+        IExternalMediaSynthOutput
     }
 }