@coderline/alphatab 1.8.1 → 1.8.3

package/dist/alphaTab.d.ts

@@ -105,15 +105,12 @@ declare class AlphaSynth extends AlphaSynthBase {
  * @public
  */
 declare class AlphaSynthBase implements IAlphaSynth {
-
-
     protected isSoundFontLoaded: boolean;
     private _isMidiLoaded;
     private _tickPosition;
     private _timePosition;
     private _metronomeVolume;
     private _countInVolume;
-
     protected midiEventsPlayedFilterSet: Set<MidiEventType>;
     private _notPlayedSamples;
     private _synthStopping;
@@ -149,7 +146,6 @@ declare class AlphaSynthBase implements IAlphaSynth {
     get isLooping(): boolean;
     set isLooping(value: boolean);
     destroy(): void;
-
     protected onSampleRequest(): void;
     play(): boolean;
     private _playInternal;
@@ -203,8 +199,6 @@ declare class AlphaSynthBase implements IAlphaSynth {
      * @lateinit
      */
     readonly playbackRangeChanged: IEventEmitterOfT<PlaybackRangeChangedEventArgs>;
-
-
     loadBackingTrack(_score: Score): void;
     updateSyncPoints(_syncPoints: BackingTrackSyncPoint[]): void;
 }
@@ -697,7 +691,6 @@ export declare class AlphaTabApiBase<TSettings> {
      */
     renderTracks(tracks: Track[], renderHints?: RenderHints): void;
     private _internalRenderTracks;
-
     private _appendRenderResult;
     private _updateRenderResult;
     /**
@@ -2508,7 +2501,6 @@ export declare class AlphaTabApiBase<TSettings> {
      *
      */
     readonly error: IEventEmitterOfT<Error>;
-
     /**
      * This event is fired when all required data for playback is loaded and ready.
      * @remarks
@@ -3287,7 +3279,6 @@ declare interface AlphaTexArgumentList extends AlphaTexAstNode {
      * The close parenthesis token grouping the arguments.
      */
     closeParenthesis?: AlphaTexParenthesisCloseTokenNode;
-
     /**
      * A list of indices to signatures which were selected as candidates matching
      * this argument list.
@@ -3763,7 +3754,6 @@ declare class AlphaTexImporter extends ScoreImporter implements IAlphaTexImporte
     private _beatDuration;
     private _parseDuration;
     private _note;
-
     applyStaffNoteKind(staff: Staff, staffNoteKind: AlphaTexStaffNoteKind): void;
     private _noteEffects;
     private _handleTransposition;
@@ -3838,7 +3828,6 @@ declare interface AlphaTexMetaDataNode extends AlphaTexAstNode {
      * The optional properties defined for the metadata.
      */
     properties?: AlphaTexPropertiesNode;
-
 }
 
 /**
@@ -4003,7 +3992,6 @@ declare class AlphaTexParser {
     get lexerDiagnostics(): AlphaTexDiagnosticBag;
     readonly parserDiagnostics: AlphaTexDiagnosticBag;
     addParserDiagnostic(diagnostics: AlphaTexDiagnostic): void;
-
     constructor(source: string);
     read(): AlphaTexScoreNode;
     private _score;
@@ -4408,7 +4396,6 @@ declare class BackingTrackSyncPoint {
  */
 declare class Bar {
     private static _globalBarId;
-
     /**
      * Gets or sets the unique id of this bar.
      */
@@ -4520,7 +4507,6 @@ declare class Bar {
      * If specified, overrides the value from the stylesheet on score level.
      */
     barNumberDisplay?: BarNumberDisplay;
-
     /**
      * The bar line to draw on the left side of the bar with an "automatic" type resolved to the actual one.
      * @param isFirstOfSystem  Whether the bar is the first one in the system.
@@ -4787,12 +4773,6 @@ declare class BeamingRules {
      * The map value defines the "groups" placed within the sliced.
      */
     groups: Map<Duration, number[]>;
-
-
-
-
-
-
 }
 
 /**
@@ -4805,7 +4785,6 @@ declare class BeamingRules {
  */
 declare class Beat {
     private static _globalBeatId;
-
     /**
      * Gets or sets the unique id of this beat.
      * @clone_ignore
@@ -5582,22 +5561,10 @@ declare class Bounds {
  * @public
  */
 declare class BoundsLookup {
-    /**
-     * @target web
-     */
-    toJson(): unknown;
-    /**
-     * @target web
-     */
-    static fromJson(json: unknown, score: Score): BoundsLookup;
-    /**
-     * @target web
-     */
+    toJson(): Map<string, unknown>;
+    static fromJson(json: Map<string, unknown> | null, score: Score): BoundsLookup | null;
     private static _boundsFromJson;
-    /**
-     * @target web
-     */
-    private _boundsToJson;
+    private static _boundsToJson;
     private _beatLookup;
     private _masterBarLookup;
     private _currentStaffSystem;
@@ -6760,9 +6727,16 @@ export declare class DisplaySettings {
      *
      * The page layout does not use `displayWidth`. The use of absolute widths would break the proper alignments needed for this kind of display.
      *
-     * Also note that the sizing is including any glyphs and notation elements within the bar. e.g. if there are clefs in the bar, they are still "squeezed" into the available size.
-     * It is not the case that the actual notes with their lengths are sized accordingly. This fits the sizing system of Guitar Pro and when files are customized there,
-     * alphaTab will match this layout quite close.
+     * In both modes, prefix and postfix glyphs (clef, key signature, time signature, barlines) are treated as fixed overhead: they keep their
+     * natural size and the remaining staff width is distributed across bars by a per-bar weight. This matches the convention used by
+     * Guitar Pro, Dorico, Finale, Sibelius and MuseScore. Bars that carry a system-start prefix or a mid-line clef/key/time-signature change
+     * are therefore visibly wider than plain bars with the same weight. The weight source depends on the mode:
+     *
+     * * `Automatic` (default for `page` layout): weights come from the built-in spacing engine (the natural content width of each bar).
+     *   `displayScale` on the model is ignored.
+     * * `UseModelLayout` (and the `parchment` layout): weights come from `bar.displayScale` / `masterBar.displayScale`. An unset
+     *   `displayScale` defaults to `1` and behaves identically to an explicit `1`, matching Guitar Pro (which omits the value when the
+     *   author hasn't customized it).
      *
      * ### Horizontal Layout
      *
@@ -7119,9 +7093,16 @@ declare interface DisplaySettingsJson {
      *
      * The page layout does not use `displayWidth`. The use of absolute widths would break the proper alignments needed for this kind of display.
      *
-     * Also note that the sizing is including any glyphs and notation elements within the bar. e.g. if there are clefs in the bar, they are still "squeezed" into the available size.
-     * It is not the case that the actual notes with their lengths are sized accordingly. This fits the sizing system of Guitar Pro and when files are customized there,
-     * alphaTab will match this layout quite close.
+     * In both modes, prefix and postfix glyphs (clef, key signature, time signature, barlines) are treated as fixed overhead: they keep their
+     * natural size and the remaining staff width is distributed across bars by a per-bar weight. This matches the convention used by
+     * Guitar Pro, Dorico, Finale, Sibelius and MuseScore. Bars that carry a system-start prefix or a mid-line clef/key/time-signature change
+     * are therefore visibly wider than plain bars with the same weight. The weight source depends on the mode:
+     *
+     * * `Automatic` (default for `page` layout): weights come from the built-in spacing engine (the natural content width of each bar).
+     *   `displayScale` on the model is ignored.
+     * * `UseModelLayout` (and the `parchment` layout): weights come from `bar.displayScale` / `masterBar.displayScale`. An unset
+     *   `displayScale` defaults to `1` and behaves identically to an explicit `1`, matching Guitar Pro (which omits the value when the
+     *   author hasn't customized it).
      *
      * ### Horizontal Layout
      *
@@ -7291,6 +7272,14 @@ declare class ElementStyle<TSubElements extends number> {
     colors: Map<TSubElements, Color | null>;
 }
 
+/**
+ * Thrown whenever we hit the end of input data unexpectedly.
+ * @public
+ */
+declare class EndOfReaderError extends AlphaTabError {
+    constructor();
+}
+
 /**
  * Represents the end of the track indicating that no more events for this track follow.
  * @public
@@ -7325,7 +7314,6 @@ declare class EndOfTrackEvent extends MidiEvent {
  */
 export declare class EngravingSettings {
     private static _bravuraDefaults?;
-
     /**
      * A {@link EngravingSettings} copy filled with the settings of the Bravura font used by default in alphaTab.
      */
@@ -7505,14 +7493,12 @@ export declare class EngravingSettings {
      * @smufl 1.4
      */
     glyphHeights: Map<MusicFontSymbol, number>;
-
     /**
      * Fills the engraving settings from the provided smufl metdata.
      * @param smufl The metadata shipped together with the SMuFL fonts.
      * @param musicFontSize The font size to configure in alphaTab for the music font.
      */
     fillFromSmufl(smufl: SmuflMetadata, musicFontSize?: number): void;
-
     private static _smuflNameToMusicFontSymbol;
     /**
      * The size of the bars drawn in numbered notation to indicate the durations.
@@ -8174,12 +8160,10 @@ declare interface EngravingStemInfoJson {
  * @public
  */
 export declare class Environment {
-
     /**
      * @target web
      */
     private static _globalThis;
-
     /**
      * @target web
      */
@@ -8208,18 +8192,10 @@ export declare class Environment {
      * @target web
      */
     static get isRunningInAudioWorklet(): boolean;
-
-
-    /**
-     * @target web
-     * @partial
-     */
-    static throttle(action: () => void, delay: number): () => void;
     /**
      * @target web
      */
     private static _detectScriptFile;
-
     private static _appendScriptName;
     /**
      * @target web
@@ -8230,10 +8206,7 @@ export declare class Environment {
      */
     private static _registerJQueryPlugin;
     static readonly renderEngines: Map<string, RenderEngineFactory>;
-
-
     static getRenderEngineFactory(engine: string): RenderEngineFactory;
-
     /**
      * Gets all default ScoreImporters
      * @returns
@@ -8257,15 +8230,12 @@ export declare class Environment {
      * @partial
      */
     private static _createPlatformSpecificRenderEngines;
-
     private static _createDefaultStaveProfiles;
     private static _createDefaultLayoutEngines;
     /**
      * @target web
      */
-    static initializeMain(createWebWorker: (settings: Settings) => Worker, createAudioWorklet: (context: AudioContext, settings: Settings) => Promise<void>): void;
-
-
+    static initializeMain(createWebWorker: (settings: Settings, nameHint: string) => Worker, createAudioWorklet: (context: AudioContext, settings: Settings) => Promise<void>): void;
     /**
      * @target web
      */
@@ -8296,9 +8266,6 @@ export declare class Environment {
      * @partial
      */
     private static _printPlatformInfo;
-
-
-
 }
 
 export declare namespace exporter {
@@ -9172,6 +9139,7 @@ declare interface IAudioExporter extends Disposable {
      * slightly longer audio is contained in the result.
      *
      * When the song ends, the chunk might contain less than the requested duration.
+     * @async
      */
     render(milliseconds: number): Promise<AudioExportChunk | undefined>;
     destroy(): void;
@@ -9190,6 +9158,7 @@ declare interface IAudioExporterWorker extends IAudioExporter {
      * @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.
+     * @async
      */
     initialize(options: AudioExportOptions, midi: MidiFile, syncPoints: BackingTrackSyncPoint[], transpositionPitches: Map<number, number>): Promise<void>;
 }
@@ -9684,6 +9653,17 @@ export declare class ImporterSettings {
      * ![Disabled](https://alphatab.net/img/reference/property/beattextaslyrics-disabled.png)
      */
     beatTextAsLyrics: boolean;
+    /**
+     * This setting controls the escape hatch for handling potentially malicous or corrupt
+     * input files. At selected spots in the codebase, we use this buffer size as maximum
+     * allowed sizes. e.g. during unzipping or decoding strings.
+     * This prevents resource exhaustion, especially when alphaTab is used on server side.
+     * Increase this buffer size if you need to handle very big files.
+     * @defaultValue `128000000`
+     * @category Core
+     * @since 1.9.0
+     */
+    maxDecodingBufferSize: number;
 }
 
 /**
@@ -9750,6 +9730,17 @@ declare interface ImporterSettingsJson {
      * ![Disabled](https://alphatab.net/img/reference/property/beattextaslyrics-disabled.png)
      */
     beatTextAsLyrics?: boolean;
+    /**
+     * This setting controls the escape hatch for handling potentially malicous or corrupt
+     * input files. At selected spots in the codebase, we use this buffer size as maximum
+     * allowed sizes. e.g. during unzipping or decoding strings.
+     * This prevents resource exhaustion, especially when alphaTab is used on server side.
+     * Increase this buffer size if you need to handle very big files.
+     * @defaultValue `128000000`
+     * @category Core
+     * @since 1.9.0
+     */
+    maxDecodingBufferSize?: number;
 }
 
 /**
@@ -9807,7 +9798,6 @@ declare class InstrumentArticulation {
      */
     outputMidiNumber: number;
     constructor(elementType?: string, staffLine?: number, outputMidiNumber?: number, noteHeadDefault?: MusicFontSymbol, noteHeadHalf?: MusicFontSymbol, noteHeadWhole?: MusicFontSymbol, techniqueSymbol?: MusicFontSymbol, techniqueSymbolPlacement?: TechniqueSymbolPlacement, id?: number);
-
     getSymbol(duration: Duration): MusicFontSymbol;
 }
 
@@ -9815,6 +9805,8 @@ export declare namespace io {
     export {
         IWriteable,
         IReadable,
+        OverflowError,
+        EndOfReaderError,
         ByteBuffer,
         IOHelper
     }
@@ -10279,6 +10271,18 @@ declare interface IUiFacade<TSettings> {
      * @param action
      */
     beginInvoke(action: () => void): void;
+    /**
+     * Creates a throttled/debounced version of the provided action.
+     * @param action The action to call.
+     * @param delay The delay to wait for additional call before actually executing.
+     * @returns A function which executes the provided action after the given delay.
+     * If multiple calls are made before the action is started, the already scheduled
+     * action is cancelled and a new one is scheduled after the given delay.
+     * If called endlessly, the action is never executed.
+     *
+     * Already executing actions will not be cancelled but will complete before another action executes.
+     */
+    throttle(action: () => void, delay: number): () => void;
     /**
      * Tells the UI layer to remove all highlights from highlighted music notation elements.
      */
@@ -10433,7 +10437,7 @@ declare class JsonConverter {
      * @param score The score object to serialize
      * @returns A serialized score object without ciruclar dependencies that can be used for further serializations.
      */
-    static scoreToJsObject(score: Score): unknown;
+    static scoreToJsObject(score: Score): Map<string, unknown> | null;
     /**
      * Converts the given JavaScript object into a score object.
      * @param jsObject The javascript object created via {@link Score}
@@ -10791,7 +10795,6 @@ declare class MasterBar {
      * Defines the custom beaming rules which should be applied to this bar and all bars following.
      */
     beamingRules?: BeamingRules;
-
     /**
      * Gets or sets whether the bar indicates a free time playing.
      */
@@ -11357,7 +11360,6 @@ declare class MidiFileGenerator {
      * @returns The generated sync points for usage in the backing track playback.
      */
     static generateSyncPoints(score: Score, createNew?: boolean): BackingTrackSyncPoint[];
-
     private static _playThroughSong;
     private static _processBarTime;
     private static _processBarTimeWithNewSyncPoints;
@@ -11476,7 +11478,6 @@ declare class MidiFileGenerator {
  */
 declare class MidiTickLookup {
     private _currentMasterBar;
-
     /**
      * A list of all {@link MasterBarTickLookup} sorted by time.
      */
@@ -11546,6 +11547,12 @@ declare class MidiTickLookup {
      * @returns The time in midi ticks at which the beat is played the first time or 0 if the beat is not contained
      */
     getBeatStart(beat: Beat): number;
+    /**
+     * Gets the playback range in midi ticks for a given beat.
+     * @param beat The beat to find the time period for.
+     * @returns The relative playback range within the parent masterbar at which the beat start and ends playing
+     */
+    getRelativeBeatPlaybackRange(beat: Beat): PlaybackRange | undefined;
     /**
      * Adds a new {@link MasterBarTickLookup} to the lookup table.
      * @param masterBar The item to add.
@@ -12263,7 +12270,15 @@ export declare enum NotationElement {
     /**
      * The slurs shown on bend effects within the score staff.
      */
-    ScoreBendSlur = 55
+    ScoreBendSlur = 55,
+    /**
+     * The hammer-on pull-off text shown on slurs.
+     */
+    EffectHammerOnPullOffText = 56,
+    /**
+     * The slide text shown on slurs.
+     */
+    EffectSlideText = 57
 }
 
 /**
@@ -12730,8 +12745,6 @@ declare interface NotationSettingsJson {
  * @public
  */
 declare class Note {
-
-
     /**
      * Gets or sets the unique id of this note.
      * @clone_ignore
@@ -13132,8 +13145,6 @@ declare class Note {
     private static _noteIdLookupKey;
     private _noteIdBag;
     chain(sharedDataBag?: Map<string, unknown> | null): void;
-
-
 }
 
 /**
@@ -13367,6 +13378,14 @@ declare enum Ottavia {
     _15mb = 4
 }
 
+/**
+ * Thrown whenever an overflow in data or buffer sizes is detected.
+ * @public
+ */
+declare class OverflowError extends AlphaTabError {
+    constructor(message: string);
+}
+
 /**
  * Lists all types of pick strokes.
  * @public
@@ -14350,6 +14369,13 @@ declare interface RenderHints {
      * internally it might still be decided to clear the viewport.
      */
     reuseViewport?: boolean;
+    /**
+     * Indicates the index of the first masterbar which was modified in the data model.
+     * @remarks
+     * AlphaTab will try to optimize the rendering and other updates to keep unchanged parts.
+     * At this point only the rendering is affected and the generated MIDI has to be updated separately.
+     */
+    firstChangedMasterBar?: number;
 }
 
 export declare namespace rendering {
@@ -14383,7 +14409,6 @@ export declare class RenderingResources {
      * The default fonts for notation elements if not specified by the user.
      */
     static defaultFonts: Map<NotationElement, Font>;
-
     /**
      * The SMuFL Metrics to use for rendering music symbols.
      * @defaultValue `alphaTab`
@@ -14580,7 +14605,6 @@ export declare class RenderingResources {
      */
     scoreInfoColor: Color;
     constructor();
-
 }
 
 /**
@@ -14591,7 +14615,6 @@ export declare class RenderingResources {
  * @target web
  */
 declare interface RenderingResourcesJson {
-
     /**
      * The SMuFL Metrics to use for rendering music symbols.
      * @defaultValue `alphaTab`
@@ -15049,7 +15072,6 @@ declare class ScoreRenderer implements IScoreRenderer {
     canvas: ICanvas | null;
     score: Score | null;
     tracks: Track[] | null;
-
     settings: Settings;
     boundsLookup: BoundsLookup | null;
     width: number;
@@ -15238,7 +15260,6 @@ export declare class Settings {
      * @target web
      */
     fillFromJson(json: SettingsJson): void;
-
 }
 
 /**
@@ -15637,7 +15658,14 @@ declare class StaffSystemBounds {
      */
     boundsLookup: BoundsLookup;
     /**
-     * Finished the lookup for optimized access.
+     * Whether this system's bounds have already been scaled via `finish`. Prevents double-scaling
+     * when the parent `BoundsLookup` is preserved across partial renders and `finish` is invoked
+     * again on a mix of already-scaled (preserved) and newly-registered (natural-coordinate) systems.
+     */
+    isFinished: boolean;
+    /**
+     * Finished the lookup for optimized access. Idempotent: once finished, further calls are no-ops
+     * so preserved systems survive partial renders without being re-scaled.
      */
     finish(scale?: number): void;
     /**
@@ -16160,7 +16188,6 @@ declare class TremoloPickingEffect {
      * The style of the tremolo picking.
      */
     style: TremoloPickingStyle;
-
     /**
      * Gets the duration of a single tremolo note played in a beat of the given duration
      * based on the configured marks.
@@ -16454,7 +16481,6 @@ declare class Voice {
     private _isEmpty;
     private _isRestOnly;
     private static _globalVoiceId;
-
     /**
      * Gets or sets the unique id of this bar.
      */
@@ -16482,12 +16508,10 @@ declare class Voice {
      * The style customizations for this item.
      */
     style?: VoiceStyle;
-
     /**
      * Gets or sets a value indicating whether this voice is empty.
      */
     get isRestOnly(): boolean;
-
     insertBeat(after: Beat, newBeat: Beat): void;
     addBeat(beat: Beat): void;
     private _chain;