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

package/dist/alphaTab.d.ts

@@ -3092,17 +3092,48 @@ declare class BackingTrack {
  * Rerpresents a point to sync the alphaTab time axis with an external backing track.
  */
 declare class BackingTrackSyncPoint {
-    tick: number;
-    data: SyncPointData;
-    constructor(tick: number, data: SyncPointData);
-}
-
-declare class BackingTrackSyncPointWithTime {
-    alphaTabTick: number;
-    alphaTabTime: number;
-    modifiedTempo: number;
-    millisecondOffset: number;
-    constructor(tick: number, time: number, modifiedTempo: number, millisecondOffset: number);
+    /**
+     * The index of the masterbar to which this sync point belongs to.
+     * @remarks
+     * This property is purely informative for external use like in editors.
+     * It has no impact to the synchronization itself.
+     */
+    masterBarIndex: number;
+    /**
+     * The occurence of the masterbar to which this sync point belongs to. The occurence
+     * is 0-based and increases with every repeated play of a masterbar (e.g. on repeats or jumps).
+     * @remarks
+     * This property is purely informative for external use like in editors.
+     * It has no impact to the synchronization itself.
+     */
+    masterBarOccurence: number;
+    /**
+     * The BPM the synthesizer has at the exact tick position of this sync point.
+     */
+    synthBpm: number;
+    /**
+     * The millisecond time position of the synthesizer when this sync point is reached.
+     */
+    synthTime: number;
+    /**
+     * The midi tick position of the synthesizer when this sync point is reached.
+     */
+    synthTick: number;
+    /**
+     * The millisecond time in the external media marking the synchronization point.
+     */
+    syncTime: number;
+    /**
+     * The BPM the song will have virtually after this sync point to align the external media time axis
+     * with the one from the synthesizer.
+     */
+    syncBpm: number;
+    /**
+     * Updates the synchronization BPM that will apply after this sync point.
+     * @param nextSyncPointSynthTime The synthesizer time of the next sync point after this one.
+     * @param nextSyncPointSyncTime The synchronization time of the next sync point after this one.
+     */
+    updateSyncBpm(nextSyncPointSynthTime: number, nextSyncPointSyncTime: number): void;
 }
 
 /**
@@ -6474,6 +6505,30 @@ 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 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;
+}
+
 /**
  * @json_immutable
  */
@@ -6706,7 +6761,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 +7508,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;
@@ -9195,7 +9296,11 @@ declare class MidiFileGenerator {
      * @returns The generated sync points for usage in the backing track playback.
      */
     static generateSyncPoints(score: Score): BackingTrackSyncPoint[];
+    /* Excluded from this release type: buildModifiedTempoLookup */
     private static playThroughSong;
+    private static processBarTime;
+    private static processBarTimeWithSyncPoints;
+    private static processBarTimeNoSyncPoints;
     private static toChannelShort;
     private generateMasterBar;
     private generateBar;
@@ -9339,7 +9444,7 @@ declare class MidiFileSequencerTempoChange {
 declare class MidiSequencerState {
     tempoChanges: MidiFileSequencerTempoChange[];
     tempoChangeIndex: number;
-    syncPoints: BackingTrackSyncPointWithTime[];
+    syncPoints: BackingTrackSyncPoint[];
     firstProgramEventPerChannel: Map<number, SynthEvent>;
     firstTimeSignatureNumerator: number;
     firstTimeSignatureDenominator: number;
@@ -9539,6 +9644,7 @@ export declare namespace model {
         AutomationType,
         Automation,
         SyncPointData,
+        FlatSyncPoint,
         Bar,
         SustainPedalMarkerType,
         SustainPedalMarker,
@@ -12740,6 +12846,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[];
 }
 
 /**
@@ -13569,13 +13686,7 @@ declare class SyncPointData {
      */
     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.
+     * 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 +13713,9 @@ export declare namespace synth {
         AlphaSynthWebAudioOutputBase,
         AlphaSynthScriptProcessorOutput,
         AlphaSynthAudioWorkletOutput,
-        IAudioElementBackingTrackSynthOutput
+        IAudioElementBackingTrackSynthOutput,
+        IExternalMediaHandler,
+        IExternalMediaSynthOutput
     }
 }