@coderline/alphatab 1.8.0-alpha.1632 → 1.8.0-alpha.1637

package/dist/alphaTab.d.ts

@@ -217,12 +217,19 @@ declare class AlphaSynthBase implements IAlphaSynth {
 declare class AlphaSynthMidiFileHandler implements IMidiFileHandler {
     private _midiFile;
     private _smf1Mode;
+    /**
+     * An indicator by how many midi-ticks the song contents are shifted.
+     * Grace beats at start might require a shift for the first beat to start at 0.
+     * This information can be used to translate back the player time axis to the music notation.
+     */
+    tickShift: number;
     /**
      * Initializes a new instance of the {@link AlphaSynthMidiFileHandler} class.
      * @param midiFile The midi file.
      * @param smf1Mode Whether to generate a SMF1 compatible midi file. This might break multi note bends.
      */
     constructor(midiFile: MidiFile, smf1Mode?: boolean);
+    addTickShift(tickShift: number): void;
     addTimeSignature(tick: number, timeSignatureNumerator: number, timeSignatureDenominator: number): void;
     addRest(track: number, tick: number, channel: number): void;
     addNote(track: number, start: number, length: number, key: number, velocity: number, channel: number): void;
@@ -356,6 +363,12 @@ export declare class AlphaTabApiBase<TSettings> {
     private _actualPlayerMode;
     private _player;
     private _renderer;
+    /**
+     * An indicator by how many midi-ticks the song contents are shifted.
+     * Grace beats at start might require a shift for the first beat to start at 0.
+     * This information can be used to translate back the player time axis to the music notation.
+     */
+    get midiTickShift(): number;
     /**
      * The actual player mode which is currently active.
      * @remarks
@@ -1732,8 +1745,8 @@ export declare class AlphaTabApiBase<TSettings> {
     private _onActiveBeatsChanged;
     private _isBeatMouseDown;
     private _isNoteMouseDown;
-    private _selectionStart;
-    private _selectionEnd;
+    private _selectionStart?;
+    private _selectionEnd?;
     /**
      * This event is fired whenever a the user presses the mouse button on a beat.
      * @eventProperty
@@ -1977,6 +1990,163 @@ export declare class AlphaTabApiBase<TSettings> {
     private _onNoteMouseUp;
     private _updateSelectionCursor;
     private _setupClickHandling;
+    /**
+     * Places the highlight markers at the specified start and end-beat range.
+     * @param startBeat The start beat where the selection should start
+     * @param endBeat The end beat where the selection should end.
+     *
+     * @remarks
+     * Unlike actually setting {@link playbackRange} this method only places the selection markers without actually
+     * changing the playback range. This method can be used when building custom selection systems (e.g. having draggable handles).
+     *
+     * @category Methods - Player
+     * @since 1.8.0
+     *
+     * @example
+     * JavaScript
+     * ```js
+     * const api = new alphaTab.AlphaTabApi(document.querySelector('#alphaTab'));
+     * const startBeat = api.score.tracks[0].staves[0].bars[0].voices[0].beats[0];
+     * const endBeat = api.score.tracks[0].staves[0].bars[3].voices[0].beats[0];
+     * api.highlightPlaybackRange(startBeat, endBeat);
+     * ```
+     *
+     * @example
+     * C#
+     * ```cs
+     * var api = new AlphaTabApi<MyControl>(...);
+     * api.ChangeTrackVolume(new Track[] { api.Score.Tracks[0], api.Score.Tracks[1] }, 1.5);
+     * api.ChangeTrackVolume(new Track[] { api.Score.Tracks[2] }, 0.5);
+     * var startBeat = api.Score.Tracks[0].Staves[0].Bars[0].Voices[0].Beats[0];
+     * var endBeat = api.Score.Tracks[0].Staves[0].Bars[3].Voices[0].Beats[0];
+     * api.HighlightPlaybackRange(startBeat, endBeat);
+     * ```
+     *
+     * @example
+     * Android
+     * ```kotlin
+     * val api = AlphaTabApi<MyControl>(...)
+     * val startBeat = api.score.tracks[0].staves[0].bars[0].voices[0].beats[0]
+     * val endBeat = api.score.tracks[0].staves[0].bars[3].voices[0].beats[0]
+     * api.highlightPlaybackRange(startBeat, endBeat)
+     * ```
+     */
+    highlightPlaybackRange(startBeat: Beat, endBeat: Beat): void;
+    /**
+     * Applies the playback range from the currently highlighted range.
+     *
+     * @remarks
+     * This method can be used when building custom selection systems (e.g. having draggable handles).
+     *
+     * @category Methods - Player
+     * @since 1.8.0
+     *
+     * @example
+     * JavaScript
+     * ```js
+     * const api = new alphaTab.AlphaTabApi(document.querySelector('#alphaTab'));
+     * const startBeat = api.score.tracks[0].staves[0].bars[0].voices[0].beats[0];
+     * const endBeat = api.score.tracks[0].staves[0].bars[3].voices[0].beats[0];
+     * api.highlightPlaybackRange(startBeat, endBeat);
+     * api.applyPlaybackRangeFromHighlight();
+     * ```
+     *
+     * @example
+     * C#
+     * ```cs
+     * var api = new AlphaTabApi<MyControl>(...);
+     * api.ChangeTrackVolume(new Track[] { api.Score.Tracks[0], api.Score.Tracks[1] }, 1.5);
+     * api.ChangeTrackVolume(new Track[] { api.Score.Tracks[2] }, 0.5);
+     * var startBeat = api.Score.Tracks[0].Staves[0].Bars[0].Voices[0].Beats[0];
+     * var endBeat = api.Score.Tracks[0].Staves[0].Bars[3].Voices[0].Beats[0];
+     * api.HighlightPlaybackRange(startBeat, endBeat);
+     * api.ApplyPlaybackRangeFromHighlight();
+     * ```
+     *
+     * @example
+     * Android
+     * ```kotlin
+     * val api = AlphaTabApi<MyControl>(...)
+     * val startBeat = api.score.tracks[0].staves[0].bars[0].voices[0].beats[0]
+     * val endBeat = api.score.tracks[0].staves[0].bars[3].voices[0].beats[0]
+     * api.highlightPlaybackRange(startBeat, endBeat)
+     * api.applyPlaybackRangeFromHighlight()
+     * ```
+     */
+    applyPlaybackRangeFromHighlight(): void;
+    /**
+     * Clears the highlight markers marking the currently selected playback range.
+     *
+     * @remarks
+     * Unlike actually setting {@link playbackRange} this method only clears the selection markers without actually
+     * changing the playback range. This method can be used when building custom selection systems (e.g. having draggable handles).
+     *
+     * @category Methods - Player
+     * @since 1.8.0
+     *
+     * @example
+     * JavaScript
+     * ```js
+     * const api = new alphaTab.AlphaTabApi(document.querySelector('#alphaTab'));
+     * api.clearPlaybackRangeHighlight();
+     * ```
+     *
+     * @example
+     * C#
+     * ```cs
+     * var api = new AlphaTabApi<MyControl>(...);
+     * api.clearPlaybackRangeHighlight();
+     * ```
+     *
+     * @example
+     * Android
+     * ```kotlin
+     * val api = AlphaTabApi<MyControl>(...)
+     * api.clearPlaybackRangeHighlight()
+     * ```
+     */
+    clearPlaybackRangeHighlight(): void;
+    /**
+     * This event is fired the shown highlights for the selected playback range changes.
+     *
+     * @remarks
+     * This event is fired already during selection and not only when the selection is completed.
+     * This event can be used to place additional custom selection markers (like drag handles).
+     *
+     * @eventProperty
+     * @category Events - Player
+     * @since 1.8.0
+     *
+     * @example
+     * JavaScript
+     * ```js
+     * const api = new alphaTab.AlphaTabApi(document.querySelector('#alphaTab'));
+     * api.playbackRangeHighlightChanged.on(e => {
+     *    updateSelectionHandles(e);
+     * });
+     * ```
+     *
+     * @example
+     * C#
+     * ```cs
+     * var api = new AlphaTabApi<MyControl>(...);
+     * api.PlaybackRangeHighlightChanged.On(e =>
+     * {
+     *    UpdateSelectionHandles(e);
+     * });
+     * ```
+     *
+     * @example
+     * Android
+     * ```kotlin
+     * val api = AlphaTabApi<MyControl>(...)
+     * api.playbackRangeHighlightChanged.on { e ->
+     *     updateSelectionHandles(e)
+     * }
+     * ```
+     *
+     */
+    readonly playbackRangeHighlightChanged: IEventEmitterOfT<PlaybackHighlightChangeEventArgs>;
     private _cursorSelectRange;
     /**
      * This event is fired whenever a new song is loaded.
@@ -3744,6 +3914,7 @@ declare class AlphaTexParser {
     private _beatMultiplier;
     private _noteList;
     private _note;
+    private static readonly _allowValuesAfterProperties;
     private _metaData;
     private _properties;
     private _property;
@@ -5216,6 +5387,7 @@ declare class Bounds {
      */
     h: number;
     scaleWith(scale: number): void;
+    constructor(x?: number, y?: number, w?: number, h?: number);
 }
 
 /**
@@ -6106,6 +6278,7 @@ export declare class DisplaySettings {
      * @remarks
      * AlphaTab has various stave profiles that define which staves will be shown in for the rendered tracks. Its recommended
      * to keep this on {@link StaveProfile.Default} and rather rely on the options available ob {@link Staff} level
+     * @deprecated Set the notation visibility by modifying the {@link Staff} properties.
      */
     staveProfile: StaveProfile;
     /**
@@ -6221,7 +6394,7 @@ export declare class DisplaySettings {
      * The top padding applied to first system.
      * @since 1.4.0
      * @category Display
-     * @defaultValue `5`
+     * @defaultValue `0`
      */
     firstSystemPaddingTop: number;
     /**
@@ -6235,14 +6408,14 @@ export declare class DisplaySettings {
      * The bottom padding applied to systems beside the last one.
      * @since 1.4.0
      * @category Display
-     * @defaultValue `20`
+     * @defaultValue `10`
      */
     systemPaddingBottom: number;
     /**
      * The bottom padding applied to the last system.
      * @since 1.4.0
      * @category Display
-     * @defaultValue `0`
+     * @defaultValue `5`
      */
     lastSystemPaddingBottom: number;
     /**
@@ -6267,17 +6440,31 @@ export declare class DisplaySettings {
      */
     accoladeBarPaddingRight: number;
     /**
-     * The bottom padding applied to main notation staves (standard, tabs, numbered, slash).
+     * The top padding applied to the first main notation staff (standard, tabs, numbered, slash).
+     * @since 1.8.0
+     * @category Display
+     * @defaultValue `0`
+     */
+    firstNotationStaffPaddingTop: number;
+    /**
+     * The bottom padding applied to last main notation staff (standard, tabs, numbered, slash).
+     * @since 1.8.0
+     * @category Display
+     * @defaultValue `0`
+     */
+    lastNotationStaffPaddingBottom: number;
+    /**
+     * The top padding applied to main notation staves (standard, tabs, numbered, slash).
      * @since 1.4.0
      * @category Display
-     * @defaultValue `5`
+     * @defaultValue `0`
      */
     notationStaffPaddingTop: number;
     /**
      * The bottom padding applied to main notation staves (standard, tabs, numbered, slash).
      * @since 1.4.0
      * @category Display
-     * @defaultValue `5`
+     * @defaultValue `0`
      */
     notationStaffPaddingBottom: number;
     /**
@@ -6285,6 +6472,8 @@ export declare class DisplaySettings {
      * @since 1.4.0
      * @category Display
      * @defaultValue `0`
+     * @deprecated Effect staves do not exist anymore, effects are now part of the main notation staves. This value has no effect anymore.
+     * Use {@link effectBandPaddingBottom} to control the padding after effect bands.
      */
     effectStaffPaddingTop: number;
     /**
@@ -6292,6 +6481,8 @@ export declare class DisplaySettings {
      * @since 1.4.0
      * @category Display
      * @defaultValue `0`
+     * @deprecated Effect staves do not exist anymore, effects are now part of the main notation staves. This value has no effect anymore.
+     * Use {@link effectBandPaddingBottom} to control the padding after effect bands.
      */
     effectStaffPaddingBottom: number;
     /**
@@ -6315,6 +6506,13 @@ export declare class DisplaySettings {
      * @defaultValue `2`
      */
     effectBandPaddingBottom: number;
+    /**
+     * The additional padding to apply between the staves of two separate tracks.
+     * @since 1.8.0
+     * @category Display
+     * @defaultValue `5`
+     */
+    trackStaffPaddingBetween: number;
     /**
      * The mode used to arrange staves and systems.
      * @since 1.3.0
@@ -6431,6 +6629,7 @@ declare interface DisplaySettingsJson {
      * @remarks
      * AlphaTab has various stave profiles that define which staves will be shown in for the rendered tracks. Its recommended
      * to keep this on {@link StaveProfile.Default} and rather rely on the options available ob {@link Staff} level
+     * @deprecated Set the notation visibility by modifying the {@link Staff} properties.
      */
     staveProfile?: StaveProfile | keyof typeof StaveProfile | Lowercase<keyof typeof StaveProfile>;
     /**
@@ -6546,7 +6745,7 @@ declare interface DisplaySettingsJson {
      * The top padding applied to first system.
      * @since 1.4.0
      * @category Display
-     * @defaultValue `5`
+     * @defaultValue `0`
      */
     firstSystemPaddingTop?: number;
     /**
@@ -6560,14 +6759,14 @@ declare interface DisplaySettingsJson {
      * The bottom padding applied to systems beside the last one.
      * @since 1.4.0
      * @category Display
-     * @defaultValue `20`
+     * @defaultValue `10`
      */
     systemPaddingBottom?: number;
     /**
      * The bottom padding applied to the last system.
      * @since 1.4.0
      * @category Display
-     * @defaultValue `0`
+     * @defaultValue `5`
      */
     lastSystemPaddingBottom?: number;
     /**
@@ -6592,17 +6791,31 @@ declare interface DisplaySettingsJson {
      */
     accoladeBarPaddingRight?: number;
     /**
-     * The bottom padding applied to main notation staves (standard, tabs, numbered, slash).
+     * The top padding applied to the first main notation staff (standard, tabs, numbered, slash).
+     * @since 1.8.0
+     * @category Display
+     * @defaultValue `0`
+     */
+    firstNotationStaffPaddingTop?: number;
+    /**
+     * The bottom padding applied to last main notation staff (standard, tabs, numbered, slash).
+     * @since 1.8.0
+     * @category Display
+     * @defaultValue `0`
+     */
+    lastNotationStaffPaddingBottom?: number;
+    /**
+     * The top padding applied to main notation staves (standard, tabs, numbered, slash).
      * @since 1.4.0
      * @category Display
-     * @defaultValue `5`
+     * @defaultValue `0`
      */
     notationStaffPaddingTop?: number;
     /**
      * The bottom padding applied to main notation staves (standard, tabs, numbered, slash).
      * @since 1.4.0
      * @category Display
-     * @defaultValue `5`
+     * @defaultValue `0`
      */
     notationStaffPaddingBottom?: number;
     /**
@@ -6610,6 +6823,8 @@ declare interface DisplaySettingsJson {
      * @since 1.4.0
      * @category Display
      * @defaultValue `0`
+     * @deprecated Effect staves do not exist anymore, effects are now part of the main notation staves. This value has no effect anymore.
+     * Use {@link effectBandPaddingBottom} to control the padding after effect bands.
      */
     effectStaffPaddingTop?: number;
     /**
@@ -6617,6 +6832,8 @@ declare interface DisplaySettingsJson {
      * @since 1.4.0
      * @category Display
      * @defaultValue `0`
+     * @deprecated Effect staves do not exist anymore, effects are now part of the main notation staves. This value has no effect anymore.
+     * Use {@link effectBandPaddingBottom} to control the padding after effect bands.
      */
     effectStaffPaddingBottom?: number;
     /**
@@ -6640,6 +6857,13 @@ declare interface DisplaySettingsJson {
      * @defaultValue `2`
      */
     effectBandPaddingBottom?: number;
+    /**
+     * The additional padding to apply between the staves of two separate tracks.
+     * @since 1.8.0
+     * @category Display
+     * @defaultValue `5`
+     */
+    trackStaffPaddingBetween?: number;
     /**
      * The mode used to arrange staves and systems.
      * @since 1.3.0
@@ -7193,6 +7417,11 @@ export declare class EngravingSettings {
      * The size of the dashes on bends (e.g. on holds)
      */
     tabBendDashSize: number;
+    /**
+     * The additional padding between the staff and the point
+     * where bend values are calculated from.
+     */
+    tabBendStaffPadding: number;
     /**
      * The height applied per quarter-note.
      */
@@ -7580,6 +7809,11 @@ declare interface EngravingSettingsJson {
      * The size of the dashes on bends (e.g. on holds)
      */
     tabBendDashSize?: number;
+    /**
+     * The additional padding between the staff and the point
+     * where bend values are calculated from.
+     */
+    tabBendStaffPadding?: number;
     /**
      * The height applied per quarter-note.
      */
@@ -7710,13 +7944,6 @@ declare interface EngravingStemInfoJson {
  * @public
  */
 export declare class Environment {
-    private static readonly _staffIdBeforeSlashAlways;
-    private static readonly _staffIdBeforeScoreAlways;
-    private static readonly _staffIdBeforeScoreHideable;
-    private static readonly _staffIdBeforeNumberedAlways;
-    private static readonly _staffIdBeforeTabAlways;
-    private static readonly _staffIdBeforeTabHideable;
-    private static readonly _staffIdBeforeEndAlways;
 
     /**
      * @target web
@@ -7800,7 +8027,7 @@ export declare class Environment {
      * @partial
      */
     private static _createPlatformSpecificRenderEngines;
-    private static _createDefaultRenderers;
+
     private static _createDefaultStaveProfiles;
     private static _createDefaultLayoutEngines;
     /**
@@ -9051,6 +9278,12 @@ declare interface IMidiFileHandler {
      * @param tick The end tick for this track.
      */
     finishTrack(track: number, tick: number): void;
+    /**
+     * Registers a general shift of the time-axis for the generate midi file.
+     * @param tickShift The shift in midi ticks by which all midi events beside the initial channel setups are shifted.
+     * This shift is applied in case grace beats
+     */
+    addTickShift(tickShift: number): void;
 }
 
 /**
@@ -10608,6 +10841,12 @@ declare class MidiFile {
      * Gets or sets the division per quarter notes.
      */
     division: number;
+    /**
+     * An indicator by how many midi-ticks the song contents are shifted.
+     * Grace beats at start might require a shift for the first beat to start at 0.
+     * This information can be used to translate back the player time axis to the music notation.
+     */
+    tickShift: number;
     /**
      * Gets a list of midi events sorted by time.
      */
@@ -10690,6 +10929,7 @@ declare class MidiFileGenerator {
      * Starts the generation of the midi file.
      */
     generate(): void;
+    private _detectTickShift;
     private _generateTrack;
     private _addProgramChange;
     private _addBankChange;
@@ -11562,7 +11802,11 @@ export declare enum NotationElement {
     /**
      * The absolute playback time of beats.
      */
-    EffectBeatTimer = 49
+    EffectBeatTimer = 49,
+    /**
+     * The whammy bar line effect shown above the tab staff
+     */
+    EffectWhammyBarLine = 50
 }
 
 /**
@@ -11722,7 +11966,7 @@ export declare class NotationSettings {
      * Controls how high the ryhthm notation is rendered below the tab staff
      * @since 0.9.6
      * @category Notation
-     * @defaultValue `15`
+     * @defaultValue `25`
      * @remarks
      * This setting can be used in combination with the {@link rhythmMode} setting to control how high the rhythm notation should be rendered below the tab staff.
      */
@@ -11935,7 +12179,7 @@ declare interface NotationSettingsJson {
      * Controls how high the ryhthm notation is rendered below the tab staff
      * @since 0.9.6
      * @category Notation
-     * @defaultValue `15`
+     * @defaultValue `25`
      * @remarks
      * This setting can be used in combination with the {@link rhythmMode} setting to control how high the rhythm notation should be rendered below the tab staff.
      */
@@ -12717,6 +12961,35 @@ export declare namespace platform {
     }
 }
 
+/**
+ * Holds information about the highlights shown for the playback range.
+ * @public
+ * @record
+ */
+export declare interface PlaybackHighlightChangeEventArgs {
+    /**
+     * The beat where the selection starts. undefined if there is no selection.
+     */
+    startBeat?: Beat;
+    /**
+     * The bounds of the start beat to determine its location and size.
+     */
+    startBeatBounds?: BeatBounds;
+    /**
+     * The beat where the selection ends. undefined if there is no selection.
+     */
+    endBeat?: Beat;
+    /**
+     * The bounds of the end beat to determine its location and size.
+     */
+    endBeatBounds?: BeatBounds;
+    /**
+     * A list of the individual rectangular areas where highlight blocks are placed.
+     * If a selection spans multiple lines this array will hold all items.
+     */
+    highlightBlocks?: Bounds[];
+}
+
 /**
  * This public class stores the midi specific information of a track needed
  * for playback.
@@ -13981,6 +14254,10 @@ declare class RenderStylesheet {
      * If single track: Whether to render multiple subsequent empty (or rest-only) bars together as multi-bar rest.
      */
     perTrackMultiBarRest: Set<number> | null;
+    /**
+     * Whether barlines should be drawn across staves within the same system.
+     */
+    extendBarLines: boolean;
 }
 
 /**