@coderline/alphatab 1.6.0-alpha.1401 → 1.6.0-alpha.1405

package/dist/alphaTab.d.ts

@@ -77,17 +77,47 @@ declare class ActiveBeatsChangedEventArgs {
  * This is the main synthesizer component which can be used to
  * play a {@link MidiFile} via a {@link ISynthOutput}.
  */
-declare class AlphaSynth implements IAlphaSynth {
-    private _sequencer;
-    private _synthesizer;
-    private _isSoundFontLoaded;
+declare class AlphaSynth extends AlphaSynthBase {
+    /**
+     * Initializes a new instance of the {@link AlphaSynth} class.
+     * @param output The output to use for playing the generated samples.
+     */
+    constructor(output: ISynthOutput, bufferTimeInMilliseconds: number);
+}
+
+/**
+ * This class implements a HTML5 Web Audio API based audio output device
+ * for alphaSynth. It can be controlled via a JS API.
+ * @target web
+ */
+declare class AlphaSynthAudioWorkletOutput extends AlphaSynthWebAudioOutputBase {
+    private _worklet;
+    private _bufferTimeInMilliseconds;
+    private readonly _settings;
+    constructor(settings: Settings);
+    open(bufferTimeInMilliseconds: number): void;
+    play(): void;
+    private handleMessage;
+    pause(): void;
+    addSamples(f: Float32Array): void;
+    resetSamples(): void;
+}
+
+/**
+ * This is the base class for synthesizer components which can be used to
+ * play a {@link MidiFile} via a {@link ISynthOutput}.
+ */
+declare class AlphaSynthBase implements IAlphaSynth {
+    protected sequencer: MidiFileSequencer;
+    protected synthesizer: IAudioSampleSynthesizer;
+    protected isSoundFontLoaded: boolean;
     private _isMidiLoaded;
     private _tickPosition;
     private _timePosition;
     private _metronomeVolume;
     private _countInVolume;
-    private _playedEventsQueue;
-    private _midiEventsPlayedFilter;
+    protected _playedEventsQueue: Queue<SynthEvent>;
+    protected _midiEventsPlayedFilter: Set<MidiEventType>;
     private _notPlayedSamples;
     private _synthStopping;
     private _output;
@@ -99,6 +129,7 @@ declare class AlphaSynth implements IAlphaSynth {
     set logLevel(value: LogLevel);
     get masterVolume(): number;
     set masterVolume(value: number);
+    protected updateMasterVolume(value: number): void;
     get metronomeVolume(): number;
     set metronomeVolume(value: number);
     get countInVolume(): number;
@@ -107,6 +138,7 @@ declare class AlphaSynth implements IAlphaSynth {
     set midiEventsPlayedFilter(value: MidiEventType[]);
     get playbackSpeed(): number;
     set playbackSpeed(value: number);
+    protected updatePlaybackSpeed(value: number): void;
     get tickPosition(): number;
     set tickPosition(value: number);
     get timePosition(): number;
@@ -117,10 +149,11 @@ declare class AlphaSynth implements IAlphaSynth {
     set isLooping(value: boolean);
     destroy(): void;
     /**
-     * Initializes a new instance of the {@link AlphaSynth} class.
+     * Initializes a new instance of the {@link AlphaSynthBase} class.
      * @param output The output to use for playing the generated samples.
      */
-    constructor(output: ISynthOutput, bufferTimeInMilliseconds: number);
+    constructor(output: ISynthOutput, synthesizer: IAudioSampleSynthesizer, bufferTimeInMilliseconds: number);
+    protected onSampleRequest(): void;
     play(): boolean;
     private playInternal;
     pause(): void;
@@ -143,9 +176,9 @@ declare class AlphaSynth implements IAlphaSynth {
     setChannelSolo(channel: number, solo: boolean): void;
     setChannelVolume(channel: number, volume: number): void;
     private onSamplesPlayed;
-    private checkForFinish;
+    protected checkForFinish(): void;
     private stopOneTimeMidi;
-    private updateTimePosition;
+    protected updateTimePosition(timePosition: number, isSeek: boolean): void;
     readonly ready: IEventEmitter;
     readonly readyForPlayback: IEventEmitter;
     readonly finished: IEventEmitter;
@@ -159,24 +192,7 @@ declare class AlphaSynth implements IAlphaSynth {
     readonly playbackRangeChanged: IEventEmitterOfT<PlaybackRangeChangedEventArgs>;
     /* Excluded from this release type: hasSamplesForProgram */
     /* Excluded from this release type: hasSamplesForPercussion */
-}
-
-/**
- * This class implements a HTML5 Web Audio API based audio output device
- * for alphaSynth. It can be controlled via a JS API.
- * @target web
- */
-declare class AlphaSynthAudioWorkletOutput extends AlphaSynthWebAudioOutputBase {
-    private _worklet;
-    private _bufferTimeInMilliseconds;
-    private readonly _settings;
-    constructor(settings: Settings);
-    open(bufferTimeInMilliseconds: number): void;
-    play(): void;
-    private handleMessage;
-    pause(): void;
-    addSamples(f: Float32Array): void;
-    resetSamples(): void;
+    loadBackingTrack(_score: Score, _syncPoints: BackingTrackSyncPoint[]): void;
 }
 
 /**
@@ -237,7 +253,6 @@ declare abstract class AlphaSynthWebAudioOutputBase implements ISynthOutput {
     get sampleRate(): number;
     activate(resumedCallback?: () => void): void;
     private patchIosSampleRate;
-    private createAudioContext;
     open(bufferTimeInMilliseconds: number): void;
     private registerResumeHandler;
     private unregisterResumeHandler;
@@ -252,8 +267,6 @@ declare abstract class AlphaSynthWebAudioOutputBase implements ISynthOutput {
     protected onSamplesPlayed(numberOfSamples: number): void;
     protected onSampleRequest(): void;
     protected onReady(): void;
-    private checkSinkIdSupport;
-    private _knownDevices;
     enumerateOutputDevices(): Promise<ISynthOutputDevice[]>;
     setOutputDevice(device: ISynthOutputDevice | null): Promise<void>;
     getOutputDevice(): Promise<ISynthOutputDevice | null>;
@@ -337,6 +350,7 @@ declare class AlphaSynthWebWorkerApi implements IAlphaSynth {
     onOutputSampleRequest(): void;
     onOutputSamplesPlayed(samples: number): void;
     private onOutputReady;
+    loadBackingTrack(_score: Score): void;
 }
 
 /**
@@ -456,6 +470,11 @@ export declare class AlphaTabApiBase<TSettings> {
     private _isDestroyed;
     private _score;
     private _tracks;
+    private _actualPlayerMode;
+    /**
+     * The actual player mode which is currently active (e.g. allows determining whether a backing track or the synthesizer is active).
+     */
+    get actualPlayerMode(): PlayerMode;
     /**
      * Gets the UI facade to use for interacting with the user interface.
      */
@@ -975,9 +994,6 @@ export declare class AlphaTabApiBase<TSettings> {
      * @since 1.5.0
      */
     get boundsLookup(): BoundsLookup | null;
-    /**
-     * Gets the alphaSynth player used for playback. This is the low-level API to the Midi synthesizer used for playback.
-     */
     /**
      * The alphaSynth player used for playback.
      * @remarks
@@ -2952,6 +2968,10 @@ declare class Automation {
      * Gets or sets the target value of the automation.
      */
     value: number;
+    /**
+     * The sync point data in case of {@link AutomationType.SyncPoint}
+     */
+    syncPointValue: SyncPointData | undefined;
     /**
      * Gets or sets the relative position of of the automation.
      */
@@ -2983,7 +3003,43 @@ declare enum AutomationType {
     /**
      * Balance change.
      */
-    Balance = 3
+    Balance = 3,
+    /**
+     * A sync point for synchronizing the internal time axis with an external audio track.
+     */
+    SyncPoint = 4
+}
+
+/**
+ * Holds information about the backing track which can be played instead of synthesized audio.
+ * @json
+ * @json_strict
+ */
+declare class BackingTrack {
+    /**
+     * The data of the raw audio file to be used for playback.
+     * @json_ignore
+     */
+    rawAudioFile: Uint8Array | undefined;
+    /**
+     * The number of milliseconds the audio should be shifted to align with the song.
+     * (e.g. negative values allow skipping potential silent parts at the start of the file and directly start with the first note).
+     */
+    padding: number;
+}
+
+/**
+ * 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 extends BackingTrackSyncPoint {
+    time: number;
+    constructor(tick: number, data: SyncPointData, time: number);
 }
 
 /**
@@ -6656,6 +6712,116 @@ declare class HeaderFooterStyle {
     private static readonly PlaceholderPattern;
 }
 
+declare class Hydra {
+    phdrs: HydraPhdr[];
+    pbags: HydraPbag[];
+    pmods: HydraPmod[];
+    pgens: HydraPgen[];
+    insts: HydraInst[];
+    ibags: HydraIbag[];
+    imods: HydraImod[];
+    igens: HydraIgen[];
+    sHdrs: HydraShdr[];
+    sampleData: Uint8Array;
+    private _sampleCache;
+    decodeSamples(startByte: number, endByte: number, decompressVorbis: boolean): Float32Array;
+    load(readable: IReadable): void;
+}
+
+declare class HydraGenAmount {
+    wordAmount: number;
+    get shortAmount(): number;
+    get lowByteAmount(): number;
+    get highByteAmount(): number;
+    constructor(reader: IReadable);
+}
+
+declare class HydraIbag {
+    static readonly SizeInFile: number;
+    instGenNdx: number;
+    instModNdx: number;
+    constructor(reader: IReadable);
+}
+
+declare class HydraIgen {
+    static readonly SizeInFile: number;
+    genOper: number;
+    genAmount: HydraGenAmount;
+    constructor(reader: IReadable);
+}
+
+declare class HydraImod {
+    static readonly SizeInFile: number;
+    modSrcOper: number;
+    modDestOper: number;
+    modAmount: number;
+    modAmtSrcOper: number;
+    modTransOper: number;
+    constructor(reader: IReadable);
+}
+
+declare class HydraInst {
+    static readonly SizeInFile: number;
+    instName: string;
+    instBagNdx: number;
+    constructor(reader: IReadable);
+}
+
+declare class HydraPbag {
+    static readonly SizeInFile: number;
+    genNdx: number;
+    modNdx: number;
+    constructor(reader: IReadable);
+}
+
+declare class HydraPgen {
+    static readonly SizeInFile: number;
+    static readonly GenInstrument: number;
+    static readonly GenKeyRange: number;
+    static readonly GenVelRange: number;
+    static readonly GenSampleId: number;
+    genOper: number;
+    genAmount: HydraGenAmount;
+    constructor(reader: IReadable);
+}
+
+declare class HydraPhdr {
+    static readonly SizeInFile: number;
+    presetName: string;
+    preset: number;
+    bank: number;
+    presetBagNdx: number;
+    library: number;
+    genre: number;
+    morphology: number;
+    constructor(reader: IReadable);
+}
+
+declare class HydraPmod {
+    static readonly SizeInFile: number;
+    modSrcOper: number;
+    modDestOper: number;
+    modAmount: number;
+    modAmtSrcOper: number;
+    modTransOper: number;
+    constructor(reader: IReadable);
+}
+
+declare class HydraShdr {
+    static readonly SizeInFile: number;
+    sampleName: string;
+    start: number;
+    end: number;
+    startLoop: number;
+    endLoop: number;
+    sampleRate: number;
+    originalPitch: number;
+    pitchCorrection: number;
+    sampleLink: number;
+    sampleType: number;
+    constructor(reader: IReadable);
+}
+
 /**
  * The public API interface for interacting with the synthesizer.
  */
@@ -6760,6 +6926,11 @@ declare interface IAlphaSynth {
      * @param midi
      */
     loadMidiFile(midi: MidiFile): void;
+    /**
+     * Loads the synchronization information from the given score (used for backing tracks and external media).
+     * @param score
+     */
+    loadBackingTrack(score: Score, syncPoints: BackingTrackSyncPoint[]): void;
     /**
      * Applies the given transposition pitches to be used during playback.
      * @param transpositionPitches a map defining the transposition pitches for midi channel.
@@ -6849,6 +7020,176 @@ declare interface IAlphaSynth {
     readonly playbackRangeChanged: IEventEmitterOfT<PlaybackRangeChangedEventArgs>;
 }
 
+/**
+ * A {@link IBackingTrackSynthOutput} which uses a HTMLAudioElement as playback mechanism.
+ * Allows the access to the element for further custom usage.
+ * @target web
+ */
+declare interface IAudioElementBackingTrackSynthOutput extends IBackingTrackSynthOutput {
+    /**
+     * The audio element used for playing the backing track.
+     * @remarks
+     * Direct interaction with the element might not result in correct alphaTab behavior.
+     */
+    readonly audioElement: HTMLAudioElement;
+}
+
+/**
+ * Classes implementing this interface can act as main audio synthesis engine
+ * within alphaSynth.
+ */
+declare interface IAudioSampleSynthesizer {
+    /**
+     * The master volume to produce.
+     */
+    masterVolume: number;
+    /**
+     * The volume of metronome ticks.
+     */
+    metronomeVolume: number;
+    /**
+     * The output sample rate which is produced.
+     */
+    readonly outSampleRate: number;
+    /**
+     * The current tempo according to the processed midi events (used for metronome event generation)
+     */
+    readonly currentTempo: number;
+    /**
+     * The current time signature numerator according to the processed midi events  (used for metronome event generation)
+     */
+    readonly timeSignatureNumerator: number;
+    /**
+     * The current time signature denominator according to the processed midi events  (used for metronome event generation)
+     */
+    readonly timeSignatureDenominator: number;
+    /**
+     * The number of voices which are currently active in the syntheiszer and still producing audio.
+     */
+    readonly activeVoiceCount: number;
+    /**
+     * Ensures for all active notes a note-off is issued to stop playing the keys.
+     * @param immediate Whether the stop should happen immediately or with sustain->release.
+     */
+    noteOffAll(immediate: boolean): void;
+    /**
+     * Stop all playing notes immediatly and reset all channel parameters but keeps user
+     * defined settings
+     */
+    resetSoft(): void;
+    /**
+     * Resets all loaded presets.
+     */
+    resetPresets(): void;
+    /**
+     * Loads the presets from the given SoundFont hydra structure.
+     * @param hydra  The SoundFont hydra structure.
+     * @param instrumentPrograms The used instrument programs to load the samples for.
+     * @param percussionKeys The instrument keys used.
+     * @param append Whether the presets should be appended or whether they should replace all loaded ones.
+     */
+    loadPresets(hydra: Hydra, instrumentPrograms: Set<number>, percussionKeys: Set<number>, append: boolean): void;
+    /**
+     * Configures the channel used to generate metronome sounds.
+     * @param metronomeVolume The volume for the channel.
+     */
+    setupMetronomeChannel(metronomeVolume: number): void;
+    /**
+     * Synthesizes the given number of samples without producing an output (e.g. on seeking)
+     * @param sampleCount The number of samples to synthesize.
+     */
+    synthesizeSilent(sampleCount: number): void;
+    /**
+     * Processes the given synth event.
+     * @param synthEvent The synth event.
+     */
+    dispatchEvent(synthEvent: SynthEvent): void;
+    /**
+     * Synthesizes the given number of samples into the provided output buffer.
+     * @param buffer The buffer to fill.
+     * @param bufferPos The offset in the buffer to start writing into.
+     * @param sampleCount The number of samples to synthesize.
+     */
+    synthesize(buffer: Float32Array, bufferPos: number, sampleCount: number): SynthEvent[];
+    /**
+     * Applies the given transposition pitches used for general pitch changes that should be applied to the song.
+     * Used for general transpositions applied to the file.
+     * @param transpositionPitches A map defining for a given list of midi channels the number of semitones that should be adjusted.
+     */
+    applyTranspositionPitches(transpositionPitches: Map<number, number>): void;
+    /**
+     * Sets the transposition pitch of a given channel. This pitch is additionally applied beside the
+     * ones applied already via {@link applyTranspositionPitches}.
+     * @param channel The channel number
+     * @param semitones The number of semitones to apply as pitch offset.
+     */
+    setChannelTranspositionPitch(channel: number, semitones: number): void;
+    /**
+     * Sets the mute state of a channel.
+     * @param channel The channel number
+     * @param mute true if the channel should be muted, otherwise false.
+     */
+    channelSetMute(channel: number, mute: boolean): void;
+    /**
+     * Gets the solo state of a channel.
+     * @param channel The channel number
+     * @param solo true if the channel should be played solo, otherwise false.
+     */
+    channelSetSolo(channel: number, solo: boolean): void;
+    /**
+     * Resets the mute/solo state of all channels
+     */
+    resetChannelStates(): void;
+    /**
+     * Gets or sets the current and initial volume of the given channel.
+     * @param channel The channel number.
+     * @param volume The volume of of the channel (0.0-1.0)
+     */
+    channelSetMixVolume(channel: number, volume: number): void;
+    /**
+     * Checks whether the synth has loaded the samples for a given midi program.
+     * @param program The program to check.
+     */
+    hasSamplesForProgram(program: number): boolean;
+    /**
+     * Checks whether the synth has loaded the samples for a given percussion key.
+     * @param key The midi key defining the percussion instrument.
+     */
+    hasSamplesForPercussion(key: number): boolean;
+}
+
+/**
+ * A synth output for playing backing tracks.
+ */
+declare interface IBackingTrackSynthOutput extends ISynthOutput {
+    /**
+     * An event fired when the playback time changes. The time is in absolute milliseconds.
+     */
+    readonly timeUpdate: IEventEmitterOfT<number>;
+    /**
+     * 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 output to load the given backing track.
+     * @param backingTrack The backing track to load.
+     */
+    loadBackingTrack(backingTrack: BackingTrack): void;
+}
+
 /**
  * This is the base public interface for canvas implementations on different plattforms.
  */
@@ -7664,10 +8005,15 @@ declare interface IUiFacade<TSettings> {
      */
     createWorkerRenderer(): IScoreRenderer;
     /**
-     * Tells the UI layer to create a player worker.
+     * Tells the UI layer to create a player worker for the synthesizer.
      * @returns
      */
     createWorkerPlayer(): IAlphaSynth | null;
+    /**
+     * Tells the UI layer to create a player which can play backing tracks.
+     * @returns
+     */
+    createBackingTrackPlayer(): IAlphaSynth | null;
     /**
      * Creates the cursor objects that are used to highlight the currently played beats and bars.
      * @returns
@@ -8164,6 +8510,12 @@ declare class MasterBar {
      * Gets or sets all tempo automation for this bar.
      */
     tempoAutomations: Automation[];
+    /**
+     * The sync points for this master bar to synchronize the alphaTab time axis with the
+     * external backing track audio.
+     * @json_add addSyncPoint
+     */
+    syncPoints: Automation[] | undefined;
     /**
      * Gets or sets the reference to the score this song belongs to.
      * @json_ignore
@@ -8216,6 +8568,11 @@ declare class MasterBar {
      * @returns
      */
     getFermata(beat: Beat): Fermata | null;
+    /**
+     * Adds the given sync point to the list of sync points for this bar.
+     * @param syncPoint  The sync point to add.
+     */
+    addSyncPoint(syncPoint: Automation): void;
 }
 
 /**
@@ -8654,6 +9011,10 @@ declare class MidiFileGenerator {
      * Gets or sets whether transposition pitches should be applied to the individual midi events or not.
      */
     applyTranspositionPitches: boolean;
+    /**
+     * The computed sync points for synchronizing the midi file with an external backing track.
+     */
+    syncPoints: BackingTrackSyncPoint[];
     /**
      * Gets the transposition pitches for the individual midi channels.
      */
@@ -8750,6 +9111,91 @@ declare class MidiFileGenerator {
     generateSingleNote(note: Note): void;
 }
 
+/**
+ * This sequencer dispatches midi events to the synthesizer based on the current
+ * synthesize position. The sequencer does not consider the playback speed.
+ */
+declare class MidiFileSequencer {
+    private _synthesizer;
+    private _currentState;
+    private _mainState;
+    private _oneTimeState;
+    private _countInState;
+    get isPlayingMain(): boolean;
+    get isPlayingOneTimeMidi(): boolean;
+    get isPlayingCountIn(): boolean;
+    constructor(synthesizer: IAudioSampleSynthesizer);
+    get mainPlaybackRange(): PlaybackRange | null;
+    set mainPlaybackRange(value: PlaybackRange | null);
+    isLooping: boolean;
+    get currentTime(): number;
+    /**
+     * Gets the duration of the song in ticks.
+     */
+    get currentEndTick(): number;
+    get currentEndTime(): number;
+    get currentTempo(): number;
+    get modifiedTempo(): number;
+    /**
+     * Gets or sets the playback speed.
+     */
+    playbackSpeed: number;
+    mainSeek(timePosition: number): void;
+    private mainSilentProcess;
+    loadOneTimeMidi(midiFile: MidiFile): void;
+    instrumentPrograms: Set<number>;
+    percussionKeys: Set<number>;
+    loadMidi(midiFile: MidiFile): void;
+    createStateFromFile(midiFile: MidiFile): MidiSequencerState;
+    fillMidiEventQueue(): boolean;
+    fillMidiEventQueueToEndTime(endTime: number): boolean;
+    private fillMidiEventQueueLimited;
+    mainTickPositionToTimePosition(tickPosition: number): number;
+    mainTimePositionToTickPosition(timePosition: number): number;
+    mainUpdateSyncPoints(syncPoints: BackingTrackSyncPoint[]): void;
+    currentTimePositionToTickPosition(timePosition: number): number;
+    mainTimePositionFromBackingTrack(timePosition: number, backingTrackLength: number): number;
+    mainTimePositionToBackingTrack(timePosition: number, backingTrackLength: number): number;
+    private tickPositionToTimePositionWithSpeed;
+    private timePositionToTickPositionWithSpeed;
+    private get internalEndTime();
+    get isFinished(): boolean;
+    stop(): void;
+    resetOneTimeMidi(): void;
+    resetCountIn(): void;
+    startCountIn(): void;
+    generateCountInMidi(): void;
+}
+
+declare class MidiFileSequencerTempoChange {
+    bpm: number;
+    ticks: number;
+    time: number;
+    constructor(bpm: number, ticks: number, time: number);
+}
+
+declare class MidiSequencerState {
+    tempoChanges: MidiFileSequencerTempoChange[];
+    tempoChangeIndex: number;
+    syncPoints: BackingTrackSyncPointWithTime[];
+    firstProgramEventPerChannel: Map<number, SynthEvent>;
+    firstTimeSignatureNumerator: number;
+    firstTimeSignatureDenominator: number;
+    synthData: SynthEvent[];
+    division: number;
+    eventIndex: number;
+    currentTime: number;
+    currentTick: number;
+    syncPointIndex: number;
+    playbackRange: PlaybackRange | null;
+    playbackRangeStartTime: number;
+    playbackRangeEndTime: number;
+    endTick: number;
+    endTime: number;
+    currentTempo: number;
+    modifiedTempo: number;
+}
+
 /**
  * This class holds all information about when {@link MasterBar}s and {@link Beat}s are played.
  *
@@ -8927,6 +9373,7 @@ export declare namespace model {
         AccidentalType,
         AutomationType,
         Automation,
+        SyncPointData,
         Bar,
         SustainPedalMarkerType,
         SustainPedalMarker,
@@ -9003,7 +9450,8 @@ export declare namespace model {
         VoiceStyle,
         WahPedal,
         WhammyType,
-        ElementStyle
+        ElementStyle,
+        BackingTrack
     }
 }
 
@@ -10715,6 +11163,35 @@ declare class PlaybackRangeChangedEventArgs {
     constructor(playbackRange: PlaybackRange | null);
 }
 
+/**
+ * Lists the different modes how the internal alphaTab player (and related cursor behavior) is working.
+ */
+export declare enum PlayerMode {
+    /**
+     * The player functionality is fully disabled.
+     */
+    Disabled = 0,
+    /**
+     * The player functionality is enabled.
+     * If the loaded file provides a backing track, it is used for playback.
+     * If no backing track is provided, the midi synthesizer is used.
+     */
+    EnabledAutomatic = 1,
+    /**
+     * The player functionality is enabled and the synthesizer is used (even if a backing track is embedded in the file).
+     */
+    EnabledSynthesizer = 2,
+    /**
+     * The player functionality is enabled. If the input data model has no backing track configured, the player might not work as expected (as playback completes instantly).
+     */
+    EnabledBackingTrack = 3,
+    /**
+     * The player functionality is enabled and an external audio/video source is used as time axis.
+     * The related player APIs need to be used to update the current position of the external audio source within alphaTab.
+     */
+    EnabledExternalMedia = 4
+}
+
 /**
  * Lists the different modes how alphaTab will play the generated audio.
  * @target web
@@ -10776,6 +11253,7 @@ export declare class PlayerSettings {
      * @since 0.9.6
      * @defaultValue `false`
      * @category Player
+     * @deprecated Use {@link playerMode} instead.
      * @remarks
      * This setting configures whether the player feature is enabled or not. Depending on the platform enabling the player needs some additional actions of the developer.
      * For the JavaScript version the [player.soundFont](/docs/reference/settings/player/soundfont) property must be set to the URL of the sound font that should be used or it must be loaded manually via API.
@@ -10784,6 +11262,37 @@ export declare class PlayerSettings {
      * AlphaTab does not ship a default UI for the player. The API must be hooked up to some UI controls to allow the user to interact with the player.
      */
     enablePlayer: boolean;
+    /**
+     * Whether the player should be enabled and which mode it should use.
+     * @since 1.6.0
+     * @defaultValue `PlayerMode.Disabled`
+     * @category Player
+     * @remarks
+     * This setting configures whether the player feature is enabled or not. Depending on the platform enabling the player needs some additional actions of the developer.
+     *
+     * **Synthesizer**
+     *
+     * If the synthesizer is used (via {@link PlayerMode.EnabledAutomatic} or {@link PlayerMode.EnabledSynthesizer}) a sound font is needed so that the midi synthesizer can produce the audio samples.
+     *
+     * For the JavaScript version the [player.soundFont](/docs/reference/settings/player/soundfont) property must be set to the URL of the sound font that should be used or it must be loaded manually via API.
+     * For .net manually the soundfont must be loaded.
+     *
+     * **Backing Track**
+     *
+     * For a built-in backing track of the input file no additional data needs to be loaded (assuming everything is filled via the input file).
+     * Otherwise the `score.backingTrack` needs to be filled before loading and the related sync points need to be configured.
+     *
+     * **External Media**
+     *
+     * For synchronizing alphaTab with an external media no data needs to be loaded into alphaTab. The configured sync points on the MasterBars are used
+     * as reference to synchronize the external media with the internal time axis. Then the related APIs on the AlphaTabApi object need to be used
+     * to update the playback state and exterrnal audio position during playback.
+     *
+     * **User Interface**
+     *
+     * AlphaTab does not ship a default UI for the player. The API must be hooked up to some UI controls to allow the user to interact with the player.
+     */
+    playerMode: PlayerMode;
     /**
      * Whether playback cursors should be displayed.
      * @since 0.9.6
@@ -11015,6 +11524,7 @@ declare interface PlayerSettingsJson {
      * @since 0.9.6
      * @defaultValue `false`
      * @category Player
+     * @deprecated Use {@link playerMode} instead.
      * @remarks
      * This setting configures whether the player feature is enabled or not. Depending on the platform enabling the player needs some additional actions of the developer.
      * For the JavaScript version the [player.soundFont](/docs/reference/settings/player/soundfont) property must be set to the URL of the sound font that should be used or it must be loaded manually via API.
@@ -11023,6 +11533,37 @@ declare interface PlayerSettingsJson {
      * AlphaTab does not ship a default UI for the player. The API must be hooked up to some UI controls to allow the user to interact with the player.
      */
     enablePlayer?: boolean;
+    /**
+     * Whether the player should be enabled and which mode it should use.
+     * @since 1.6.0
+     * @defaultValue `PlayerMode.Disabled`
+     * @category Player
+     * @remarks
+     * This setting configures whether the player feature is enabled or not. Depending on the platform enabling the player needs some additional actions of the developer.
+     *
+     * **Synthesizer**
+     *
+     * If the synthesizer is used (via {@link PlayerMode.EnabledAutomatic} or {@link PlayerMode.EnabledSynthesizer}) a sound font is needed so that the midi synthesizer can produce the audio samples.
+     *
+     * For the JavaScript version the [player.soundFont](/docs/reference/settings/player/soundfont) property must be set to the URL of the sound font that should be used or it must be loaded manually via API.
+     * For .net manually the soundfont must be loaded.
+     *
+     * **Backing Track**
+     *
+     * For a built-in backing track of the input file no additional data needs to be loaded (assuming everything is filled via the input file).
+     * Otherwise the `score.backingTrack` needs to be filled before loading and the related sync points need to be configured.
+     *
+     * **External Media**
+     *
+     * For synchronizing alphaTab with an external media no data needs to be loaded into alphaTab. The configured sync points on the MasterBars are used
+     * as reference to synchronize the external media with the internal time axis. Then the related APIs on the AlphaTabApi object need to be used
+     * to update the playback state and exterrnal audio position during playback.
+     *
+     * **User Interface**
+     *
+     * AlphaTab does not ship a default UI for the player. The API must be hooked up to some UI controls to allow the user to interact with the player.
+     */
+    playerMode?: PlayerMode | keyof typeof PlayerMode | Lowercase<keyof typeof PlayerMode>;
     /**
      * Whether playback cursors should be displayed.
      * @since 0.9.6
@@ -11267,6 +11808,14 @@ declare class PositionChangedEventArgs {
      * @since 1.2.0
      */
     isSeek: boolean;
+    /**
+     * The original tempo in which alphaTab internally would be playing right now.
+     */
+    originalTempo: number;
+    /**
+     * The modified tempo in which the actual playback is happening (e.g. due to playback speed or external audio synchronization)
+     */
+    modifiedTempo: number;
     /**
      * Initializes a new instance of the {@link PositionChangedEventArgs} class.
      * @param currentTime The current time.
@@ -11275,7 +11824,7 @@ declare class PositionChangedEventArgs {
      * @param endTick The end tick.
      * @param isSeek Whether the time was seeked.
      */
-    constructor(currentTime: number, endTime: number, currentTick: number, endTick: number, isSeek: boolean);
+    constructor(currentTime: number, endTime: number, currentTick: number, endTick: number, isSeek: boolean, originalTempo: number, modifiedTempo: number);
 }
 
 /**
@@ -11315,6 +11864,16 @@ export declare class ProgressEventArgs {
     constructor(loaded: number, total: number);
 }
 
+declare class Queue<T> {
+    private _head?;
+    private _tail?;
+    get isEmpty(): boolean;
+    clear(): void;
+    enqueue(item: T): void;
+    peek(): T | undefined;
+    dequeue(): T | undefined;
+}
+
 /**
  * Lists all Rasgueado types.
  */
@@ -11997,6 +12556,10 @@ declare class Score {
      * Gets or sets the rendering stylesheet for this song.
      */
     stylesheet: RenderStylesheet;
+    /**
+     * Information about the backing track that can be used instead of the synthesized audio.
+     */
+    backingTrack: BackingTrack | undefined;
     /**
      * The style customizations for this item.
      */
@@ -12826,6 +13389,31 @@ declare abstract class SvgCanvas implements ICanvas {
     endRotate(): void;
 }
 
+/**
+ * Represents the data of a sync point for synchronizing the internal time axis with
+ * an external audio file.
+ * @cloneable
+ * @json
+ * @json_strict
+ */
+declare class SyncPointData {
+    /**
+     * 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 the {@link originalTempo} 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;
+}
+
 export declare namespace synth {
     export {
         AlphaSynth,
@@ -12833,6 +13421,7 @@ export declare namespace synth {
         PlaybackRange,
         ISynthOutput,
         ISynthOutputDevice,
+        IBackingTrackSynthOutput,
         IAlphaSynth,
         PlayerState,
         PlayerStateChangedEventArgs,
@@ -12843,10 +13432,20 @@ export declare namespace synth {
         AlphaSynthWebWorkerApi,
         AlphaSynthWebAudioOutputBase,
         AlphaSynthScriptProcessorOutput,
-        AlphaSynthAudioWorkletOutput
+        AlphaSynthAudioWorkletOutput,
+        IAudioElementBackingTrackSynthOutput
     }
 }
 
+declare class SynthEvent {
+    eventIndex: number;
+    event: MidiEvent;
+    readonly isMetronome: boolean;
+    time: number;
+    constructor(eventIndex: number, e: MidiEvent);
+    static newMetronomeEvent(eventIndex: number, tick: number, counter: number, durationInTicks: number, durationInMillis: number): SynthEvent;
+}
+
 declare abstract class SystemBracket {
     firstStaffInBracket: RenderStaff | null;
     lastStaffInBracket: RenderStaff | null;
@@ -12934,7 +13533,15 @@ declare class TempoChangeEvent extends MidiEvent {
     /**
      * The tempo in microseconds per quarter note (aka USQ). A time format typically for midi.
      */
-    microSecondsPerQuarterNote: number;
+    get microSecondsPerQuarterNote(): number;
+    /**
+     * The tempo in microseconds per quarter note (aka USQ). A time format typically for midi.
+     */
+    set microSecondsPerQuarterNote(value: number);
+    /**
+     * The tempo in beats per minute
+     */
+    beatsPerMinute: number;
     constructor(tick: number, microSecondsPerQuarterNote: number);
     writeTo(s: IWriteable): void;
 }