@coderline/alphatab 1.9.0-alpha.1883 → 1.9.0-alpha.1962

package/dist/alphaTab.d.ts

@@ -226,6 +226,7 @@ declare class AlphaSynthMidiFileHandler implements IMidiFileHandler {
     addTickShift(tickShift: number): void;
     addTimeSignature(tick: number, timeSignatureNumerator: number, timeSignatureDenominator: number): void;
     addRest(track: number, tick: number, channel: number): void;
+    addMetronome(tick: number, counter: number, durationInTicks: number): void;
     addNote(track: number, start: number, length: number, key: number, velocity: number, channel: number): void;
     private static _fixValue;
     addControlChange(track: number, tick: number, channel: number, controller: ControllerType, value: number): void;
@@ -2087,6 +2088,10 @@ export declare class AlphaTabApiBase<TSettings> {
     private _onNoteMouseUp;
     private _updateSelectionCursor;
     private _setupClickHandling;
+    /**
+     * Rebuilds the selection highlight against the current layout. A selection without an end beat yields an empty highlight.
+     */
+    private _refreshSelectionHighlight;
     /**
      * Places the highlight markers at the specified start and end-beat range.
      * @param startBeat The start beat where the selection should start
@@ -3144,8 +3149,9 @@ export declare enum AlphaTabErrorType {
 }
 
 /**
- * Represents a metronome event. This event is emitted by the synthesizer only during playback and
- * is typically not part of the midi file itself.
+ * Represents a metronome event. alphaTab places these events bar by bar into the midi files generated for playback
+ * (respecting repeats, time signatures and pick-up bars). They are not written into standard midi files (SMF1 mode).
+ * For midi files without these events the synthesizer generates them during playback according to the time signatures.
  * @public
  */
 declare class AlphaTabMetronomeEvent extends AlphaTabSysExEvent {
@@ -3246,6 +3252,7 @@ export declare namespace alphaTex {
         AlphaTexDiagnosticCode,
         AlphaTexDiagnosticsSeverity,
         AlphaTexStaffNoteKind,
+        AlphaTexStaffType,
         AlphaTexVoiceMode,
         ArgumentListParseTypesMode,
         IAlphaTexImporter,
@@ -3619,6 +3626,10 @@ declare enum AlphaTexDiagnosticCode {
      * Error parsing arguments: unexpected additional arguments. Signatures: %s
      */
     AT220 = 220,
+    /**
+     * A string number can only be specified on pitched notes, use the 'fret.string' syntax to specify the string of fretted notes.
+     */
+    AT221 = 221,
     /**
      * Expected no arguments, but found some.
      */
@@ -3647,6 +3658,10 @@ declare enum AlphaTexDiagnosticCode {
      * This staff metadata tag should be specified as staff property.
      */
     AT306 = 306,
+    /**
+     * The staff display property is not supported by the staff type, the value has no effect.
+     */
+    AT307 = 307,
     /**
      * The dots separating score metadata, score contents and the sync points can be removed.
      */
@@ -4087,6 +4102,21 @@ declare enum AlphaTexStaffNoteKind {
     Articulation = 2
 }
 
+/**
+ * The staff types selected by the alphaTex staff display tags (`\defaultStaffDisplay`, `\staffDisplay`, `\barDisplay`).
+ * @public
+ */
+declare enum AlphaTexStaffType {
+    /** Standard notation */
+    Score = 0,
+    /** Guitar tablature */
+    Tabs = 1,
+    /** Slash notation */
+    Slash = 2,
+    /** Numbered notation (Jianpu) */
+    Numbered = 3
+}
+
 /**
  * A string literal within alphaTex.
  * @record
@@ -4283,6 +4313,10 @@ declare class Automation {
     syncPointValue: SyncPointData | undefined;
     /**
      * Gets or sets the relative position of of the automation.
+     * @remarks
+     * The position is relative to the full duration of the bar's time signature (0 = bar start, 1 = bar end).
+     * This also applies to pick-up bars (`MasterBar.isAnacrusis`) which are shorter than their time signature:
+     * an automation on the 3rd eighth note of a 3/8 pick-up in 2/4 has the position 0.5 (as written by Guitar Pro).
      */
     ratioPosition: number;
     /**
@@ -4326,7 +4360,7 @@ declare enum AutomationType {
     /**
      * Midi Bank change.
      */
-    Bank = 4
+    Bank = 5
 }
 
 /**
@@ -7918,6 +7952,29 @@ export declare class EngravingSettings {
      * in case of multi-voice note head overlaps.
      */
     multiVoiceDisplacedNoteHeadSpacing: number;
+    /**
+     * The minimum vertical padding between the content of two adjacent staves
+     * (e.g. a stem below one staff and a fret number above the next one).
+     * Additional space is only added between staves where their content would come closer than this.
+     * @remarks
+     * Behind Bars: characters should not be closer than 1/2 stave-space and never collide.
+     */
+    staffContentPadding: number;
+    /**
+     * The minimum horizontal padding between the content of two adjacent beats
+     * (e.g. a notehead and the accidental or grace notes of the following beat).
+     * Additional space is only added between beats where their content would come closer than this.
+     * @remarks
+     * Behind Bars: where space is limited, characters should not be closer than 1/2 stave-space and never collide.
+     */
+    beatContentPadding: number;
+    /**
+     * The minimum horizontal padding between the content of the last beat in a bar and the bar line.
+     * Additional space is only added where the content would come closer than this.
+     * @remarks
+     * Behind Bars: stems must never come closer to a barline than one stave-space.
+     */
+    barlineContentPadding: number;
     /**
      * Calculates the stem height for a note of the given duration.
      * @param duration The duration to calculate the height respecting flag sizes.
@@ -8326,6 +8383,29 @@ declare interface EngravingSettingsJson {
      * in case of multi-voice note head overlaps.
      */
     multiVoiceDisplacedNoteHeadSpacing?: number;
+    /**
+     * The minimum vertical padding between the content of two adjacent staves
+     * (e.g. a stem below one staff and a fret number above the next one).
+     * Additional space is only added between staves where their content would come closer than this.
+     * @remarks
+     * Behind Bars: characters should not be closer than 1/2 stave-space and never collide.
+     */
+    staffContentPadding?: number;
+    /**
+     * The minimum horizontal padding between the content of two adjacent beats
+     * (e.g. a notehead and the accidental or grace notes of the following beat).
+     * Additional space is only added between beats where their content would come closer than this.
+     * @remarks
+     * Behind Bars: where space is limited, characters should not be closer than 1/2 stave-space and never collide.
+     */
+    beatContentPadding?: number;
+    /**
+     * The minimum horizontal padding between the content of the last beat in a bar and the bar line.
+     * Additional space is only added where the content would come closer than this.
+     * @remarks
+     * Behind Bars: stems must never come closer to a barline than one stave-space.
+     */
+    barlineContentPadding?: number;
     /**
      * The space needed by flags on the stem-side from top to bottom to place.
      */
@@ -8891,6 +8971,7 @@ declare enum GolpeType {
 declare class Gp7Exporter extends ScoreExporter {
     get name(): string;
     writeScore(score: Score): void;
+    private static _cloneScore;
 }
 
 /**
@@ -9534,10 +9615,17 @@ declare interface IContainer {
     mouseDown: IEventEmitterOfT<IMouseEventArgs>;
     /**
      * This event occurs when a mouse/finger moves on top of the control.
+     *
+     * @remarks
+     * While a press started on this control is active, moves are reported even if they happen outside the control.
      */
     mouseMove: IEventEmitterOfT<IMouseEventArgs>;
     /**
      * This event occurs when a mouse/finger is released from the control.
+     *
+     * @remarks
+     * Every press started on this control ends with exactly one mouseUp, also when the release happens
+     * outside the control or the gesture is cancelled by the system.
      */
     mouseUp: IEventEmitterOfT<IMouseEventArgs>;
 }
@@ -9780,6 +9868,16 @@ declare interface IMidiFileHandler {
      * This shift is applied in case grace beats
      */
     addTickShift(tickShift: number): void;
+    /**
+     * Adds a metronome click to the generated midi file.
+     * @param tick The midi ticks when the click should be happening.
+     * @param counter The index of the beat within the bar as per time signature (0 = first beat of the bar).
+     * @param durationInTicks The duration of one metronome beat in midi ticks.
+     * @remarks
+     * The clicks are generated bar by bar respecting repeats, the time signature and pick-up bars. Handlers
+     * which do not need a metronome (e.g. when writing standard midi files) can ignore this call.
+     */
+    addMetronome(tick: number, counter: number, durationInTicks: number): void;
 }
 
 /**
@@ -10984,6 +11082,33 @@ declare class MasterBar {
      * @json_ignore
      */
     index: number;
+    /**
+     * A custom string to display for the bar number as override.
+     * Even with a custom string, this masterbar contributes to the incremental bar numbers
+     * across the score. Set the {@link customBarNumber} for the next master bar if you want
+     * alternative counting.
+     */
+    customBarNumberText?: string;
+    /**
+     * A custom bar number affecting this and subsequent bar numbers.
+     * e.g. allows setting the initial bar number to 10 and the second will be 11.
+     * Any change to {@link customBarNumber} requires an additional call to {@link Score.finish}
+     * to consolidate the counting.
+     */
+    customBarNumber?: number;
+    /**
+     * The actual bar number of this masterbar respecting any Pick-Up bars and manually overriden bar numbers.
+     * Returns NaN for pick-up bars (see {@link isAnacrusis}) Only available after data model finish.
+     * The final bar number is not guaranteed to be unique. using {@see customBarNumber}
+     * users might reset or change counting in any custom fashion. Do not rely on the bar number
+     * for lookup or indexing.
+     */
+    get barNumber(): number;
+    /**
+     * Returns the actual text displayed for this master bar respecting any custom overrides and
+     * out-of-order numbers. Only available after data model finish.
+     */
+    get barNumberText(): string;
     /**
      * Whether the masterbar is has any changes applied to it (e.g. tempo changes, time signature changes etc)
      * The first bar is always considered changed due to initial setup of values. It does not consider
@@ -11619,6 +11744,7 @@ declare class MidiFileGenerator {
     private static _processBarTimeNoSyncPoints;
     private static _toChannelShort;
     private _generateMasterBar;
+    private _generateMetronome;
     private _generateBar;
     private _getPlaybackBar;
     private _generateVoice;
@@ -13064,10 +13190,13 @@ declare class Note {
      * Gets or sets the string number where the note is placed.
      * 1 is the lowest string on the guitar and the bottom line on the tablature.
      * It then increases the the number of strings on available on the track.
+     * On pitched notes (no fret) the string is only an annotation shown via {@link showStringNumber}
+     * and has no effect on playback. Staves without tuning assume a standard 6 string instrument for this case.
      */
     string: number;
     /**
      * Gets or sets whether the string number for this note should be shown.
+     * For pitched notes this requires {@link string} to be set.
      */
     showStringNumber: boolean;
     get isPiano(): boolean;
@@ -13386,6 +13515,10 @@ declare class Note {
     style?: NoteStyle;
     get stringTuning(): number;
     static getStringTuning(staff: Staff, noteString: number): number;
+    /**
+     * The number of strings assumed for string number annotations on staves without tuning.
+     */
+    private static readonly _defaultAnnotationStringCount;
     get realValue(): number;
     get realValueWithoutHarmonic(): number;
     /**
@@ -13395,6 +13528,10 @@ declare class Note {
      * @returns The calculated note value as midi key.
      */
     calculateRealValue(applyTranspositionPitch: boolean, applyHarmonic: boolean): number;
+    /**
+     * The interval in semitones the harmonic sounds above the played pitch. Natural harmonics are relative to the open string
+     * and therefore need a string, the other types are an interval above the played note on any pitched note.
+     */
     get harmonicPitch(): number;
     get initialBendValue(): number;
     get displayValue(): number;
@@ -15527,8 +15664,17 @@ declare class ScoreRenderer implements IScoreRenderer {
     updateSettings(settings: Settings): void;
     renderResult(resultId: string): void;
     render(renderHints?: RenderHints): void;
+    /**
+     * Renders within the 'render.total' profiling frame.
+     * The finished events are raised by the caller once all profiling frames are closed:
+     * listeners might start a new render right away (e.g. on another thread).
+     * @returns whether the rendering finished (and the finished events need to be raised).
+     */
+    private _renderProfiled;
+    private _render;
     resizeRender(): void;
     private _layoutAndRender;
+    private _notifyRenderFinished;
     readonly preRender: IEventEmitterOfT<boolean>;
     readonly renderFinished: IEventEmitterOfT<RenderFinishedEventArgs>;
     readonly partialRenderFinished: IEventEmitterOfT<RenderFinishedEventArgs>;
@@ -16629,6 +16775,12 @@ declare class Track {
     style?: TrackStyle;
     ensureStaveCount(staveCount: number): void;
     addStaff(staff: Staff): void;
+    /**
+     * Returns the index of {@link articulation} in {@link percussionArticulations},
+     * appending it (deduplicated by `uniqueId`) when not yet present. Callers store the
+     * returned index in {@link Note.percussionArticulation}.
+     */
+    getOrRegisterPercussionArticulation(articulation: InstrumentArticulation): number;
     finish(settings: Settings, sharedDataBag?: Map<string, unknown> | null): void;
     applyLyrics(lyrics: Lyrics[]): void;
 }