@coderline/alphatab 1.6.0-alpha.1444 → 1.6.0-alpha.1449

package/dist/alphaTab.d.ts

@@ -83,6 +83,16 @@ declare class AlphaSynth extends AlphaSynthBase {
      * @param output The output to use for playing the generated samples.
      */
     constructor(output: ISynthOutput, bufferTimeInMilliseconds: number);
+    /**
+     * Creates a new audio exporter, initialized with the given data.
+     * @param options The export options to use.
+     * The track volume and transposition pitches must lists must be filled with midi channels.
+     * @param midi The midi file to use.
+     * @param syncPoints The sync points to use
+     * @param transpositionPitches The initial transposition pitches to apply.
+     * @param transpositionPitches The initial transposition pitches to apply.
+     */
+    exportAudio(options: AudioExportOptions, midi: MidiFile, syncPoints: BackingTrackSyncPoint[], mainTranspositionPitches: Map<number, number>): IAlphaSynthAudioExporter;
 }
 
 /**
@@ -298,6 +308,7 @@ declare class AlphaSynthWebWorkerApi implements IAlphaSynth {
     get isReadyForPlayback(): boolean;
     get state(): PlayerState;
     get logLevel(): LogLevel;
+    get worker(): Worker;
     set logLevel(value: LogLevel);
     get masterVolume(): number;
     set masterVolume(value: number);
@@ -2949,6 +2960,20 @@ export declare class AlphaTabApiBase<TSettings> {
      *
      */
     getOutputDevice(): Promise<ISynthOutputDevice | null>;
+    /**
+     * Starts the audio export for the currently loaded song.
+     * @remarks
+     * This will not export or use any backing track media but will always use the synthesizer to generate the output.
+     * This method works with any PlayerMode active but changing the mode during export can lead to unexpected side effects.
+     *
+     * See [Audio Export](https://www.alphatab.net/docs/guides/audio-export) for further guidance how to use this feature.
+     *
+     * @param options The export options.
+     * @category Methods - Player
+     * @since 1.6.0
+     * @returns An exporter instance to export the audio in a streaming fashion.
+     */
+    exportAudio(options: AudioExportOptions): Promise<IAudioExporter>;
 }
 
 export declare class AlphaTabError extends Error {
@@ -3164,6 +3189,94 @@ declare class AlphaTexImporter extends ScoreImporter {
     private parseWhammyType;
 }
 
+/**
+ * Represents a single chunk of audio produced.
+ */
+declare class AudioExportChunk {
+    /**
+     * The generated samples for the requested chunk.
+     */
+    samples: Float32Array;
+    /**
+     * The current time position within the song in milliseconds.
+     */
+    currentTime: number;
+    /**
+     * The total length of the song in milliseconds.
+     */
+    endTime: number;
+    /**
+     * The current time position within the song in midi ticks.
+     */
+    currentTick: number;
+    /**
+     * The total length of the song in midi ticks.
+     */
+    endTick: number;
+}
+
+/**
+ * The options controlling how to export the audio.
+ */
+declare class AudioExportOptions {
+    /**
+     * The soundfonts to load and use for generating the audio.
+     * If not provided, the already loaded soundfonts of the synthesizer will be used.
+     * If no existing synthesizer is initialized, the generated audio might not contain any hearable audio.
+     */
+    soundFonts?: Uint8Array[];
+    /**
+     * The output sample rate.
+     * @default `44100`
+     */
+    sampleRate: number;
+    /**
+     * Whether to respect sync point information during export.
+     * @default `true`
+     * @remarks
+     * If the song contains sync point information for synchronization with an external media,
+     * this option allows controlling whether the synthesized audio is aligned with these points.
+     *
+     * This is useful when mixing the exported audio together with external media, keeping the same timing.
+     *
+     * Disable this option if you want the original/exact timing as per music sheet in the exported audio.
+     */
+    useSyncPoints: boolean;
+    /**
+     * The current master volume as percentage. (range: 0.0-3.0, default 1.0)
+     */
+    masterVolume: number;
+    /**
+     * The metronome volume. (range: 0.0-3.0, default 0.0)
+     */
+    metronomeVolume: number;
+    /**
+     * The range of the song that should be exported. Set this to null
+     * to play the whole song.
+     */
+    playbackRange?: PlaybackRange;
+    /**
+     * The volume for individual tracks as percentage (range: 0.0-3.0).
+     * @remarks
+     * The key is the track index, and the value is the relative volume.
+     * The configured volume (as per data model) still applies, this is an additional volume control.
+     * If no custom value is set, 100% is used.
+     * No values from the currently active synthesizer are applied.
+     *
+     * The meaning of the key changes when used with AlphaSynth directly, in this case the key is the midi channel .
+     */
+    trackVolume: Map<number, number>;
+    /**
+     * The additional semitone pitch transpose to apply for individual tracks.
+     * @remarks
+     * The key is the track index, and the value is the number of semitones to apply.
+     * No values from the currently active synthesizer are applied.
+     *
+     * The meaning of the key changes when used with AlphaSynth directly, in this case the key is the midi channel .
+     */
+    trackTranspositionPitches: Map<number, number>;
+}
+
 /**
  * Automations are used to change the behaviour of a song.
  * @cloneable
@@ -5191,7 +5304,7 @@ export declare class CoreSettings {
     /**
      * Builds the default SMuFL font sources for the usage with alphaTab in cases
      * where no custom {@link smuflFontSources} are provided.
-     * @param fontDirectory The {@link fontDirectory} configured.
+     * @param fontDirectory The {@link CoreSettings.fontDirectory} configured.
      * @target web
      */
     static buildDefaultSmuflFontSources(fontDirectory: string | null): Map<FontFileFormat, string>;
@@ -7350,6 +7463,26 @@ declare interface IAlphaSynth {
     readonly playbackRangeChanged: IEventEmitterOfT<PlaybackRangeChangedEventArgs>;
 }
 
+/**
+ * An audio exporter allowing streaming synthesis of audio samples with a fixed configuration.
+ * This is the internal synchronous version of the public {@link IAudioExporter}.
+ */
+declare interface IAlphaSynthAudioExporter {
+    /**
+     * Renders the next chunk of audio and provides it as result.
+     *
+     * @param milliseconds The rough number of milliseconds that should be synthesized and exported as chunk.
+     * @returns The requested chunk holding the samples and time information.
+     * If the song completed playback `undefined` is returned indicating the end.
+     * The provided audio might not be exactly the requested number of milliseconds as the synthesizer internally
+     * uses a fixed block size of 64 samples for synthesizing audio. Depending on the sample rate
+     * slightly longer audio is contained in the result.
+     *
+     * When the song ends, the chunk might contain less than the requested duration.
+     */
+    render(milliseconds: number): AudioExportChunk | undefined;
+}
+
 /**
  * A {@link IBackingTrackSynthOutput} which uses a HTMLAudioElement as playback mechanism.
  * Allows the access to the element for further custom usage.
@@ -7364,6 +7497,42 @@ declare interface IAudioElementBackingTrackSynthOutput extends IBackingTrackSynt
     readonly audioElement: HTMLAudioElement;
 }
 
+/**
+ * A exporter which can be used to obtain the synthesized audio for custom processing.
+ */
+declare interface IAudioExporter extends Disposable {
+    /**
+     * Renders the next chunk of audio and provides it as result.
+     *
+     * @param milliseconds The rough number of milliseconds that should be synthesized and exported as chunk.
+     * @returns The requested chunk holding the samples and time information.
+     * If the song completed playback `undefined` is returned indicating the end.
+     * The provided audio might not be exactly the requested number of milliseconds as the synthesizer internally
+     * uses a fixed block size of 64 samples for synthesizing audio. Depending on the sample rate
+     * slightly longer audio is contained in the result.
+     *
+     * When the song ends, the chunk might contain less than the requested duration.
+     */
+    render(milliseconds: number): Promise<AudioExportChunk | undefined>;
+    destroy(): void;
+}
+
+/**
+ * This is the internal worker interface implemented by IAudioExporters and consists
+ * of the internal APIs needed to spawn new exporters. Its mainly used to simplify
+ * the public API visible when using exporters.
+ */
+declare interface IAudioExporterWorker extends IAudioExporter {
+    /**
+     * Initializes the worker.
+     * @param options The options to use
+     * @param midi The midi file to load
+     * @param syncPoints The sync points of the song (if any)
+     * @param transpositionPitches The initial transposition pitches for the midi file.
+     */
+    initialize(options: AudioExportOptions, midi: MidiFile, syncPoints: BackingTrackSyncPoint[], transpositionPitches: Map<number, number>): Promise<void>;
+}
+
 /**
  * Classes implementing this interface can act as main audio synthesis engine
  * within alphaSynth.
@@ -8412,6 +8581,14 @@ declare interface IUiFacade<TSettings> {
      * @returns
      */
     createWorkerPlayer(): IAlphaSynth | null;
+    /**
+     * Tells the UI layer to create a new audio exporter.
+     * @param synth The currently active alphaSynth that might be used for synthesizing.
+     * If the provided synthesizer is already an active player worker (created via {@link createWorkerPlayer}),
+     * it can reuse the already initialized state.
+     * @returns
+     */
+    createWorkerAudioExporter(synth: IAlphaSynth | null): IAudioExporterWorker;
     /**
      * Tells the UI layer to create a player which can play backing tracks.
      * @returns
@@ -9566,6 +9743,8 @@ declare class MidiFileSequencer {
     get currentEndTime(): number;
     get currentTempo(): number;
     get modifiedTempo(): number;
+    get syncPointTempo(): number;
+    get currentSyncPoints(): BackingTrackSyncPoint[];
     /**
      * Gets or sets the playback speed.
      */
@@ -9583,7 +9762,9 @@ declare class MidiFileSequencer {
     mainTickPositionToTimePosition(tickPosition: number): number;
     mainUpdateSyncPoints(syncPoints: BackingTrackSyncPoint[]): void;
     currentTimePositionToTickPosition(timePosition: number): number;
+    currentUpdateCurrentTempo(timePosition: number): void;
     private updateCurrentTempo;
+    currentUpdateSyncPoints(timePosition: number): void;
     private updateSyncPoints;
     mainTimePositionFromBackingTrack(timePosition: number, backingTrackLength: number): number;
     mainTimePositionToBackingTrack(timePosition: number, backingTrackLength: number): number;
@@ -9615,7 +9796,6 @@ declare class MidiSequencerState {
     division: number;
     eventIndex: number;
     currentTime: number;
-    currentTick: number;
     syncPointIndex: number;
     playbackRange: PlaybackRange | null;
     playbackRangeStartTime: number;
@@ -9623,7 +9803,7 @@ declare class MidiSequencerState {
     endTick: number;
     endTime: number;
     currentTempo: number;
-    modifiedTempo: number;
+    syncPointTempo: number;
 }
 
 /**
@@ -13866,6 +14046,7 @@ export declare namespace synth {
     export {
         AlphaSynthBase,
         AlphaSynth,
+        IAlphaSynthAudioExporter,
         CircularSampleBuffer,
         PlaybackRange,
         ISynthOutput,
@@ -13885,7 +14066,11 @@ export declare namespace synth {
         AlphaSynthAudioWorkletOutput,
         IAudioElementBackingTrackSynthOutput,
         IExternalMediaHandler,
-        IExternalMediaSynthOutput
+        IExternalMediaSynthOutput,
+        IAudioExporter,
+        IAudioExporterWorker,
+        AudioExportChunk,
+        AudioExportOptions
     }
 }