@tspro/web-music-score 4.0.0 → 4.1.0

package/dist/scale-bnD0WnMV.d.mts

@@ -0,0 +1,230 @@
+import { N as Note, S as SymbolSet } from './note-eA2xPPiG.mjs';
+import { K as KeySignature } from './tempo-S85Q7uJA.mjs';
+
+/** Interval direction type. */
+type IntervalDirection = "Unison" | "Ascending" | "Descending";
+/** Interval quality type. */
+type IntervalQuality = "Perfect" | "Major" | "minor" | "Augmented" | "Doubly Augmented" | "diminished" | "doubly diminished";
+/**
+ * Validate interval quality of unkown value.
+ * @param q - Interval quality to validate.
+ * @returns - Interval quality if valid, else throws.
+ */
+declare function validateIntervalQuality(q: unknown): IntervalQuality;
+/** Interval class. */
+declare class Interval {
+    readonly note1: Note;
+    readonly note2: Note;
+    /** Interval direction. */
+    readonly direction: IntervalDirection;
+    /** Number of semitones. */
+    readonly semitones: number;
+    /** Interval quantity. */
+    readonly quantity: number;
+    /** Interval quality. */
+    readonly quality: IntervalQuality;
+    private constructor();
+    /**
+     * Get interval between given two notes.
+     * @param note1 - First note.
+     * @param note2 - Second note.
+     * @returns - Interval if valid, or undefined.
+     */
+    static get(note1: Note, note2: Note): Interval | undefined;
+    /**
+     * Get string presentation of interval (e.g. "Descending Major 2").
+     * @returns - Interval string.
+     */
+    toString(): string;
+    /**
+     * Get abbrevated string presentation of interval (e.g. "↓M2").
+     * @returns - Interval abbrevated string.
+     */
+    toAbbrString(): string;
+}
+
+/** Degree type. */
+type Degree = 1 | 2 | "b3" | 3 | 4 | "b5" | 5 | "#5" | 6 | "bb7" | "b7" | 7 | "#7" | "b9" | 9 | "#9" | 11 | 13;
+/** Scale type enum. */
+declare enum ScaleType {
+    /** Major scale. */
+    Major = "Major",
+    /** Natural minor scale. */
+    NaturalMinor = "Natural Minor",
+    /** Harmonic minor scale. */
+    HarmonicMinor = "Harmonic Minor",
+    /** Mode: Ionian. */
+    Ionian = "Ionian",
+    /** Mode: Dorian. */
+    Dorian = "Dorian",
+    /** Mode: Phrygian. */
+    Phrygian = "Phrygian",
+    /** Mode: Lydian. */
+    Lydian = "Lydian",
+    /** Mode: Mixolydian. */
+    Mixolydian = "Mixolydian",
+    /** Mode: Aeolian (minor). */
+    Aeolian = "Aeolian",
+    /** Mode: Locrian (rare). */
+    Locrian = "Locrian",
+    /** Major pentatonic scale. */
+    MajorPentatonic = "Major Pentatonic",
+    /** Minor pentatoni scale. */
+    MinorPentatonic = "Minor Pentatonic",
+    /** Major hexatonic blues scale. */
+    MajorHexatonicBlues = "Major Hexatonic Blues",
+    /** Minor hexatonic blues scale. */
+    MinorHexatonicBlues = "Minor Hexatonic Blues",
+    /** Heptatonic blues scale. */
+    HeptatonicBlues = "Heptatonic Blues"
+}
+/** Scale class. */
+declare class Scale extends KeySignature {
+    readonly tonic: string;
+    readonly scaleType: ScaleType;
+    /** Degrees of scale notes. */
+    private readonly scaleDegrees;
+    /** Scale notes. */
+    private readonly scaleNotes;
+    /** Degrees (or undefined) of chromatic classes. */
+    private readonly chromaticClassDegree;
+    /**
+     * Create nev scale object instance.
+     * @param tonic - Tonic (e.g. "C" in "C Major").
+     * @param scaleType - Scale typo ("e.g. "Major" in "C Major").
+     */
+    constructor(tonic: string, scaleType: ScaleType);
+    /**
+     * Compare if two scales equals.
+     * @param a - Scale a.
+     * @param b - Scale b.
+     * @returns - Boolean equality of given scales.
+     */
+    static equals(a: Scale | null | undefined, b: Scale | null | undefined): boolean;
+    /**
+     * Get scale name.
+     * @param symbolSet - Symbol set to format scale name in ascii or unicode.
+     * @returns - Scale name string.
+     */
+    getScaleName(symbolSet?: SymbolSet): string;
+    /**
+     * Get scale notes.
+     * @param bottomNote - Computed scale notes begin no lower than this note.
+     * @param numOctaves - How many octaves?
+     * @returns - Array of scale notes.
+     */
+    getScaleNotes(bottomNote: string, numOctaves: number): ReadonlyArray<Note>;
+    /**
+     * Get scale overview (e.g. "C - D - E - F - G - A - B" for "C Major" scale).
+     * @returns - Scale overview string.
+     */
+    getScaleOverview(): string;
+    /**
+     * Get scale steps, array of 1 (half step) and 2 (whole step), (e.g. [2, 2, 1, 2, 2, 2, 1] for Major scale).
+     * @returns - Array of scale steps.
+     */
+    getScaleSteps(): number[];
+    /**
+     * Get scale steps string presentation, array of "H" (half step) and "W" (whole step), (e.g. ["W", "W", "H", "W", "W", "W", "H"] for Major scale).
+     * @returns - Array of scale steps string presentation.
+     */
+    getScaleStringSteps(): string[];
+    /**
+     * Test if given note is scale note.
+     * @param note - Note to test.
+     * @returns - True/false.
+     */
+    isScaleNote(note: Note): boolean;
+    /**
+     * Test if given note is scale root note.
+     * @param note - Note to test.
+     * @returns - True/false.
+     */
+    isScaleRootNote(note: Note): boolean;
+    /**
+     * Get interval value between scale root note and given note.
+     * @param note - Note.
+     * @returns - Interval.
+     */
+    getIntervalFromRootNote(note: Note): Interval;
+    private preferredChromaticNoteCache;
+    /**
+     * Get preferred chromatic note from given chromatic id.
+     * @param chromaticId - Chromatic id.
+     * @returns - Note.
+     */
+    getPreferredChromaticNote(chromaticId: number): Note;
+}
+/** Scale factory class. */
+declare class ScaleFactory {
+    readonly type: ScaleType;
+    private tonicList;
+    private scaleMap;
+    /**
+     * Create new scale factory object instance.
+     * @param type - Scale type.
+     */
+    constructor(type: ScaleType);
+    /**
+     * Get list of tonics (e.g. "C", "C#", ... for Major scale type).
+     * @returns - Array of tonics.
+     */
+    getTonicList(): ReadonlyArray<string>;
+    /**
+     * Get default tonic.
+     * @returns - Default tonic.
+     */
+    getDefaultTonic(): string;
+    /**
+     * Get scale type.
+     * @returns - SCale type.
+     */
+    getType(): ScaleType;
+    /**
+     * Get scale by given tonic.
+     * @param tonic - Tonic (e.g. "C").
+     * @returns - Scale.
+     */
+    getScale(tonic: string): Scale;
+    /**
+     * Test if this scale factory has scale for given tonic value.
+     * @param tonic - Tonic.
+     * @returns - True/false.
+     */
+    hasScale(tonic: string): boolean;
+}
+/**
+ * Get array of scale factories, has some title string between to category.
+ * @returns - Array of scale factories.
+ */
+declare function getScaleFactoryList(): ReadonlyArray<ScaleFactory | string>;
+/**
+ * Get scale factory for given scale type.
+ * @param scaleType - Scale type.
+ * @returns - Scale factory.
+ */
+declare function getScaleFactory(scaleType: ScaleType | `${ScaleType}`): ScaleFactory;
+/**
+ * Validate scale type.
+ * @param scaleType - Scale type of unknown value.
+ * @returns - Scale type if given argument was valid scale type, or throws.
+ */
+declare function validateScaleType(scaleType: unknown): ScaleType;
+/**
+ * Get scale.
+ * @param tonic - Tonic (e.g. "C").
+ * @param scaleType - Scale type (e.g. "Major").
+ */
+declare function getScale(tonic: string, scaleType: ScaleType | `${ScaleType}`): Scale;
+/**
+ * Get scale.
+ * @param scale - Scale name (e.g. "C Major").
+ */
+declare function getScale(scale: string): Scale;
+/**
+ * Get default scale ("C Major").
+ * @returns - Default scale.
+ */
+declare function getDefaultScale(): Scale;
+
+export { type Degree as D, type IntervalDirection as I, ScaleType as S, type IntervalQuality as a, Interval as b, Scale as c, ScaleFactory as d, getScaleFactory as e, validateScaleType as f, getScaleFactoryList as g, getScale as h, getDefaultScale as i, validateIntervalQuality as v };

package/dist/score/index.d.mts

@@ -1,63 +1,209 @@
-import { N as NoteOptions, R as RestOptions, S as StaffPreset, a as ScoreConfiguration, M as MDocument, V as VoiceId, T as TupletOptions, F as Fermata, b as StaffTabOrGroups, c as Navigation, A as Annotation, L as Label, C as Connective, d as TieType, e as NoteAnchor, f as VerticalPosition } from '../interface-XoKiryoV.mjs';
-export { a5 as Arpeggio, _ as Clef, D as DivRect, m as MAccidental, o as MArpeggio, x as MBarLineLeft, w as MBarLineRight, p as MBeamGroup, n as MConnective, r as MEnding, W as MExtensionLine, s as MFermata, t as MHeader, u as MImage, v as MMeasure, z as MNoteGroup, Z as MPlaybackButtons, X as MPlayer, Y as MRenderer, G as MRest, I as MRhythmColumn, J as MScoreRow, P as MSignature, Q as MSpecialText, K as MStaff, q as MStaffBeamGroup, B as MStaffNoteGroup, H as MStaffRest, y as MStaffTabBarLine, O as MTab, E as MTabNoteGroup, U as MText, l as MusicInterface, a7 as PlayState, a8 as PlayStateChangeListener, h as ScoreEvent, k as ScoreEventListener, g as ScoreEventType, j as ScoreObjectEvent, i as ScoreStaffPosEvent, $ as StaffConfig, a6 as StaffTabOrGroup, a4 as Stem, a2 as StringNumber, a0 as TabConfig, a3 as getStringNumbers, a1 as getVoiceIds } from '../interface-XoKiryoV.mjs';
-import { N as Note } from '../note-BFa43I86.mjs';
-import { S as ScaleType, c as Scale } from '../scale-C2pCNxdE.mjs';
-import { N as NoteLength, h as NoteLengthStr, K as KeySignature, a as TimeSignature, T as TimeSignatureString, j as TupletRatio } from '../tempo-BAYoZ_Li.mjs';
+import { N as NoteOptions, R as RestOptions, S as StaffPreset, a as ScoreConfiguration, M as MDocument, V as VoiceId, T as TupletOptions, F as Fermata, b as StaffTabOrGroups, c as Navigation, A as AnnotationText, d as Annotation, L as Label, C as Connective, e as TieType, f as NoteAnchor, g as VerticalPosition } from '../music-objects-DIaqNPjs.mjs';
+export { a6 as Arpeggio, $ as Clef, D as DivRect, a8 as DynamicsAnnotation, q as MAccidental, s as MArpeggio, E as MBarLineLeft, B as MBarLineRight, t as MBeamGroup, r as MConnective, v as MEnding, _ as MExtensionLine, w as MFermata, x as MHeader, y as MImage, z as MMeasure, H as MNoteGroup, o as MPlaybackButtons, m as MPlayer, n as MRenderer, K as MRest, P as MRhythmColumn, Q as MScoreRow, X as MSignature, Y as MSpecialText, U as MStaff, u as MStaffBeamGroup, I as MStaffNoteGroup, O as MStaffRest, G as MStaffTabBarLine, W as MTab, J as MTabNoteGroup, Z as MText, p as MusicInterface, aa as PlayState, ab as PlayStateChangeListener, i as ScoreEvent, l as ScoreEventListener, h as ScoreEventType, k as ScoreObjectEvent, j as ScoreStaffPosEvent, a0 as StaffConfig, a7 as StaffTabOrGroup, a5 as Stem, a3 as StringNumber, a1 as TabConfig, a9 as TempoAnnotation, a4 as getStringNumbers, a2 as getVoiceIds } from '../music-objects-DIaqNPjs.mjs';
+import { N as Note } from '../note-eA2xPPiG.mjs';
+import { S as ScaleType, c as Scale } from '../scale-bnD0WnMV.mjs';
+import { N as NoteLength, i as NoteLengthStr, K as KeySignature, b as TimeSignature, T as TimeSignatures, B as BeamGrouping, k as TupletRatio } from '../tempo-S85Q7uJA.mjs';
 import '@tspro/ts-utils-lib';
 
-declare enum DynamicsAnnotations {
-    cresc = "cresc.",
-    decresc = "decresc.",
-    dim = "dim.",
-    ppp = "ppp",
-    pp = "pp",
-    p = "p",
-    mp = "mp",
-    m = "m",
-    mf = "mf",
-    f = "f",
-    ff = "ff",
-    fff = "fff"
-}
-declare enum TempoAnnotations {
-    accel = "accel.",
-    rit = "rit.",
-    a_tempo = "a tempo"
-}
-type AnnotationsType = `${DynamicsAnnotations}` | `${TempoAnnotations}`;
-
+/** Tuplet builder type. */
 type TupletBuilder = {
+    /**
+     * Add note to a tuplet.
+     * @param note - Note instance of Note or string (e.g. "D4").
+     * @param noteLength - Note length (e.g. "4n").
+     * @param options - Note options.
+     * @returns - This tuplet builder object.
+     */
     addNote: (note: Note | string, noteLength: NoteLength | NoteLengthStr, options?: NoteOptions) => TupletBuilder;
+    /**
+     * Add chord to a tuplet.
+     * @param notes - Array of notes, each instance of Note or string (e.g. "D4").
+     * @param noteLength - Note length (e.g. "4n").
+     * @param options - Note options.
+     * @returns - This tuplet builder object.
+     */
     addChord: (notes: (Note | string)[], noteLength: NoteLength | NoteLengthStr, options?: NoteOptions) => TupletBuilder;
+    /**
+     * Add rest to a tuplet.
+     * @param restLength - Rest length (e.g. "4n").
+     * @param options - Rest options.
+     * @returns - This tuplet builder object.
+     */
     addRest: (restLength: NoteLength | NoteLengthStr, options?: RestOptions) => TupletBuilder;
 };
+/** Etension builder type. */
 type ExtensionBuilder = {
+    /**
+     * Increase extension length by note length multiplied by number of notes.
+     * @param noteLength - Length of note (e.g. "2n").
+     * @param noteCount - Number of note lengths (default = 1).
+     * @returns - this extension builder object.
+     */
     notes: (noteLength: NoteLength | NoteLengthStr, noteCount?: number) => ExtensionBuilder;
+    /**
+     * Increase length of extension length by given number of measures.
+     * @param measureCount - Number of measures.
+     * @returns - this extension builder object.
+     */
     measures: (measureCount: number) => ExtensionBuilder;
+    /**
+     * Create as long extension line as possible.
+     * @returns - this extension builder object.
+     */
     infinity: () => ExtensionBuilder;
+    /**
+     * Create an invisible extension.
+     * @returns - this extension builder object.
+     */
     hide: () => ExtensionBuilder;
 };
+/**
+ * Document builder class.
+ * <pre>
+ * // Example
+ * let doc = new Score.DocumentBuilder()
+ *     .addScoreConfiguration({ type: "staff", clef: "G", isOctavewDown: true })
+ *     .setMeasuresPerRow(4)
+ *     .addMeasure()
+ *     .addNote(1, "C3", "4n")
+ *     .addChord(1, ["C3", "E3", "G3"], "4n").addLabel("chord", "C")
+ *     .addRest(1, "4n")
+ *     // etc.
+ *     .getDEocument();
+ * </pre>
+ */
 declare class DocumentBuilder {
     private readonly doc;
+    /**
+     * Create new document builder instance.
+     */
     constructor();
+    /**
+     * Use staff preset values to set score confguration. This call will request new score row.
+     * @param staffPreset - Staff preset (e.g. "treble").
+     */
     setScoreConfiguration(staffPreset: StaffPreset | `${StaffPreset}`): DocumentBuilder;
+    /**
+     * Use staff preset values to set score confguration. This call will request new score row.
+     * @param config - Score configuration (e.g. { type: "staff", clef: "G", isOctavewDown: true }).
+     */
     setScoreConfiguration(config: ScoreConfiguration): DocumentBuilder;
     private getMeasure;
+    /**
+     * Get music document after finished building.
+     * @returns - Music document.
+     */
     getDocument(): MDocument;
+    /**
+     * Set header texts.
+     * @param title - Title of this docmument/musical piece.
+     * @param composer - Composer of this document/musical piece.
+     * @param arranger - Arranger of this document/musical piece.
+     * @returns - This document builder instance.
+     */
     setHeader(title?: string, composer?: string, arranger?: string): DocumentBuilder;
+    /**
+     * Automatically limit number of measures per score row.
+     * @param measuresPerRow - Number of measures per row. Must be integer >=1 or Infinity.
+     * @returns - This document builder instance.
+     */
     setMeasuresPerRow(measuresPerRow: number): DocumentBuilder;
+    /**
+     * Add new measure.
+     * @returns - This document builder instance.
+     */
     addMeasure(): DocumentBuilder;
+    /**
+     * Set key signature for current measure and forward.
+     * @param tonic - Tonic note (e.g. "C").
+     * @param scaleType - Scale type (e.g. string "Major" or ScaleType.Major).
+     * @returns - This document builder instance.
+     */
     setKeySignature(tonic: string, scaleType: ScaleType | `${ScaleType}`): DocumentBuilder;
+    /**
+     * Set key signature for current measure and forward.
+     * @param keySignature - KeySignature object instance.
+     * @returns - This document builder instance.
+     */
     setKeySignature(keySignature: KeySignature): DocumentBuilder;
+    /**
+     * Set key signature for current measure and forward.
+     * @param keySignature - Key signature string (e.g. "C Major").
+     * @returns - This document builder instance.
+     */
     setKeySignature(keySignature: string): DocumentBuilder;
+    /**
+     * Set key signature for current measure and forward.
+     * @param scale - Scale object instance.
+     * @returns - This document builder instance.
+     */
     setKeySignature(scale: Scale): DocumentBuilder;
-    setTimeSignature(timeSignature: TimeSignature | TimeSignatureString): DocumentBuilder;
+    /**
+     * Set time signature for current measure and forward.
+     * @param timeSignature - TimeSignature object instance.
+     * @returns - This document builder instance.
+     */
+    setTimeSignature(timeSignature: TimeSignature): DocumentBuilder;
+    /**
+     * Set time signature for current measure and forward.
+     * @param timeSignature - TimeSignatures enum value or string (e.g. "3/4").
+     * @param beamGrouping - Beam grouping (e.g. "3-2" for time signature "5/8").
+     * @returns - This document builder instance.
+     */
+    setTimeSignature(timeSignature: TimeSignatures | `${TimeSignatures}`, beamGrouping?: BeamGrouping | `${BeamGrouping}`): DocumentBuilder;
+    /**
+     * Set time signature for current measure and forward.
+     * @param beatCount - Beat count of time signature (e.g. 3 in "3/4").
+     * @param beatSize - Beat size of time signature (e.g. 4 in "3/4").
+     * @param beamGrouping - Beam grouping (e.g. "3-2" for time signature "5/8").
+     * @returns - This document builder instance.
+     */
+    setTimeSignature(beatCount: number, beatSize: number, beamGrouping?: BeamGrouping | `${BeamGrouping}`): DocumentBuilder;
+    /**
+     * Set tempo.
+     * @param beatsPerMinute - Tempo beats per minute.
+     * @returns - This document builder instance.
+     */
     setTempo(beatsPerMinute: number): DocumentBuilder;
+    /**
+     * Set tempo.
+     * @param beatsPerMinute - Tempo beats per minute.
+     * @param beatLength - Length of one beat.
+     * @returns - This document builder instance.
+     */
     setTempo(beatsPerMinute: number, beatLength: NoteLength | NoteLengthStr): DocumentBuilder;
-    /** @deprecated - Use dotted beatLength instead (e.g. "4..") */
+    /**
+     * @deprecated - Use dotted beatLength instead (e.g. "4..").
+     * @param beatsPerMinute - Tempo beats per minute.
+     * @param beatLength - Length of one beat.
+     * @param dotted - Dot count of length of one beat.
+     * @returns - This document builder instance.
+     */
     setTempo(beatsPerMinute: number, beatLength: NoteLength | NoteLengthStr, dotted: boolean | number): DocumentBuilder;
+    /**
+     * Add note o current measure.
+     * @param voiceId - Voice id to add note to.
+     * @param note - Note instance of Note or string (e.g. "D4").
+     * @param noteLength - Note length (e.g. "4n").
+     * @param options - Note options.
+     * @returns - This document builder instance.
+     */
     addNote(voiceId: number, note: Note | string, noteLength: NoteLength | NoteLengthStr, options?: NoteOptions): DocumentBuilder;
+    /**
+     * @param voiceId - Voice id to add chord to.
+     * @param notes - Array of notes, each instance of Note or string (e.g. "D4").
+     * @param noteLength - Note length (e.g. "4n").
+     * @param options - Note options.
+     * @returns - This document builder instance.
+     */
     addChord(voiceId: number, notes: (Note | string)[], noteLength: NoteLength | NoteLengthStr, options?: NoteOptions): DocumentBuilder;
+    /**
+     *
+     * @param voiceId - Voice id to add rest to.
+     * @param restLength - Rest length (e.g. "4n").
+     * @param options - Rest options.
+     * @returns - This document builder instance.
+     */
     addRest(voiceId: number, restLength: NoteLength | NoteLengthStr, options?: RestOptions): DocumentBuilder;
     /**
      * Usage:
@@ -69,66 +215,188 @@ declare class DocumentBuilder {
      * });
      * </pre>
      *
-     * @param voiceId
+     * @param voiceId - Voice id to add tuplet to.
      * @param tupletRatio - You can also use Theory.Tuplet presets (e.g. Theory.Tuplet.Triplet).
-     * @param tupletBuilder
-     * @returns
+     * @param tupletBuilder - Tuplet builder function to build tuplet.
+     * @returns - This document builder instance.
      */
     addTuplet(voiceId: VoiceId, tupletRatio: TupletRatio & TupletOptions, tupletBuilder: (notes: TupletBuilder) => void): DocumentBuilder;
     private addFermataInternal;
+    /**
+     * Add fermata to current measure.
+     * @param fermata - Fermata type (e.g. "atNote" or Fermata.AtrNote).
+     * @returns - This document builder instance.
+     */
     addFermata(fermata?: Fermata | `${Fermata}`): DocumentBuilder;
-    /** @param staffTabOrGroups  - staff/tab index (0=top), staff/tab name, or staff group name. */
+    /**
+     * Add Fermata to current measure to given staff/tab/group.
+     * @param staffTabOrGroups - staff/tab index (0=top), staff/tab name, or staff group name.
+     * @param fermata - Fermata type (e.g. "atNote" or Fermata.AtrNote).
+     * @returns - This document builder instance.
+     */
     addFermataTo(staffTabOrGroups: StaffTabOrGroups, fermata?: Fermata | `${Fermata}`): DocumentBuilder;
     private addNavigationInternal;
+    /**
+     * Add navigation element to current measure.
+     * @param navigation - Navigation element (e.g. "D.S. al Fine" or Navigation.DS_al_Fine).
+     * @returns - This document builder instance.
+     */
     addNavigation(navigation: Navigation | `${Navigation}`): DocumentBuilder;
+    /**
+     * Add end repeat navigation element to current measure.
+     * @param navigation - End repeat navigation element ("endRepeat" or Navigation.EndRepeat).
+     * @param playCount - Number of times to play the ended repeat section.
+     * @returns - This document builder instance.
+     */
     addNavigation(navigation: Navigation.EndRepeat | `${Navigation.EndRepeat}`, playCount: number): DocumentBuilder;
+    /**
+     * Add ending navigation element to current measure.
+     * @param navigation - Ending navigation element ("ending" or Navigation.Ending).
+     * @param passages - Passage numbers for measure marked by this ending is played.
+     * @returns - This document builder instance.
+     */
     addNavigation(navigation: Navigation.Ending | `${Navigation.Ending}`, ...passages: number[]): DocumentBuilder;
-    /** @param staffTabOrGroups  - staff/tab index (0=top), staff/tab name, or staff group name. */
+    /**
+     * Add navigation element to current measure to given staff/tab/group.
+     * @param staffTabOrGroups - staff/tab index (0=top), staff/tab name, or staff group name.
+     * @param navigation
+     * @returns - This document builder instance.
+     */
     addNavigationTo(staffTabOrGroups: StaffTabOrGroups, navigation: Navigation | `${Navigation}`): DocumentBuilder;
-    /** @param staffTabOrGroups  - staff/tab index (0=top), staff/tab name, or staff group name. */
+    /**
+     * Add end repeat navigation element to current measure to given staff/tab/group.
+     * @param staffTabOrGroups - staff/tab index (0=top), staff/tab name, or staff group name.
+     * @param navigation
+     * @param playCount
+     * @returns - This document builder instance.
+     */
     addNavigationTo(staffTabOrGroups: StaffTabOrGroups, navigation: Navigation.EndRepeat | `${Navigation.EndRepeat}`, playCount: number): DocumentBuilder;
-    /** @param staffTabOrGroups  - staff/tab index (0=top), staff/tab name, or staff group name. */
+    /**
+     * Add ending navigation element to current measure to given staff/tab/group.
+     * @param staffTabOrGroups - staff/tab index (0=top), staff/tab name, or staff group name.
+     * @param navigation
+     * @param passages
+     * @returns - This document builder instance.
+     */
     addNavigationTo(staffTabOrGroups: StaffTabOrGroups, navigation: Navigation.Ending | `${Navigation.Ending}`, ...passages: number[]): DocumentBuilder;
     private addAnnotationInternal;
-    addAnnotation(text: AnnotationsType): DocumentBuilder;
+    /**
+     * Add annotation text to column of last added note/chord/rest in current measure.
+     * @param text - Known annotation text (e.g. "pp").
+     * @returns - This document builder instance.
+     */
+    addAnnotation(text: AnnotationText): DocumentBuilder;
+    /**
+     * Add annotation text to column of last added note/chord/rest in current measure.
+     * @param annotation - Annotation type (e.g. "tempo" or Annotation.Tempo).
+     * @param text - Annotation text (unrestricted).
+     * @returns - This document builder instance.
+     */
     addAnnotation(annotation: Annotation | `${Annotation}`, text: string): DocumentBuilder;
-    /** @param staffTabOrGroups  - staff/tab index (0=top), staff/tab name, or staff group name. */
-    addAnnotationTo(staffTabOrGroups: StaffTabOrGroups, text: AnnotationsType): DocumentBuilder;
-    /** @param staffTabOrGroups  - staff/tab index (0=top), staff/tab name, or staff group name. */
+    /**
+     * Add annotation text to column of last added note/chord/rest in current measure to given staff/tab/group.
+     * @param staffTabOrGroups - staff/tab index (0=top), staff/tab name, or staff group name.
+     * @param text - Known annotation text (e.g. "pp").
+     * @returns - This document builder instance.
+     */
+    addAnnotationTo(staffTabOrGroups: StaffTabOrGroups, text: AnnotationText): DocumentBuilder;
+    /**
+     * Add annotation text to column of last added note/chord/rest in current measure to given staff/tab/group.
+     * @param staffTabOrGroups - staff/tab index (0=top), staff/tab name, or staff group name.
+     * @param annotation - Annotation type (e.g. "tempo" or Annotation.Tempo).
+     * @param text - Annotation text (unrestricted).
+     * @returns - This document builder instance.
+     */
     addAnnotationTo(staffTabOrGroups: StaffTabOrGroups, annotation: Annotation | `${Annotation}`, text: string): DocumentBuilder;
     private addLabelInternal;
+    /**
+     * Add label text to column of last added note/chord/rest in current measure.
+     * @param label - Label type (e.g. "chord" or Label.Chord).
+     * @param text - label text (e.g. "Am").
+     * @returns - This document builder instance.
+     */
     addLabel(label: Label | `${Label}`, text: string): DocumentBuilder;
-    /** @param staffTabOrGroups  - staff/tab index (0=top), staff/tab name, or staff group name. */
+    /**
+     * Add label text to column of last added note/chord/rest in current measure to given staff/tab/group.
+     * @param staffTabOrGroups - staff/tab index (0=top), staff/tab name, or staff group name.
+     * @param label - Label type (e.g. "chord" or Label.Chord).
+     * @param text - label text (e.g. "Am").
+     * @returns - This document builder instance.
+     */
     addLabelTo(staffTabOrGroups: StaffTabOrGroups, label: Label | `${Label}`, text: string): DocumentBuilder;
+    /**
+     * Add tie starting from last added note/chord.
+     * @param connective - Connective type ("tie" or Connective.Tie).
+     * @param tieSpan - How many notes across this tie spans.
+     * @param notAnchor - Anchor point for note and this tie.
+     * @returns - This document builder instance.
+     */
     addConnective(connective: Connective.Tie | `${Connective.Tie}`, tieSpan?: number | TieType | `${TieType}`, notAnchor?: NoteAnchor | `${NoteAnchor}`): DocumentBuilder;
+    /**
+     * Add slur starting from last added note/chord.
+     * @param connective - Connective type ("slur" or Connective.Slur).
+     * @param slurSpan - How many notes across this slur spans.
+     * @param notAnchor - Anchor point for note and this slur.
+     * @returns - This document builder instance.
+     */
     addConnective(connective: Connective.Slur | `${Connective.Slur}`, slurSpan?: number, notAnchor?: NoteAnchor | `${NoteAnchor}`): DocumentBuilder;
+    /**
+     * Add slide starting from last added note/chord.
+     * @param connective - Connective type ("slide" or Connective.Slide).
+     * @param notAnchor - Anchor point for note and this slide.
+     * @returns - This document builder instance.
+     */
     addConnective(connective: Connective.Slide | `${Connective.Slide}`, notAnchor?: NoteAnchor | `${NoteAnchor}`): DocumentBuilder;
     /**
-     * Extension length example:
+     * Add extension line to previously added annotation or label element.
      * <pre>
+     *     // Example
      *     addExtension(ext => ext.notes("1n", 2))          // length is 2 whole notes
      *     addExtension(ext => ext.measures(3).hide())      // length is 3 measures, hidden
      *     addExtension(ext => ext.measures(1).notes("8n")) // length is 1 measure + 1 eigth note
      *     addExtension(ext => ext.infinity())              // length is as long as possible
      * </pre>
-     * @param extensionLength
-     * @param extensionVisible
-     * @returns
+     * @param extensionBuilder - Extension builder function used to build exstension.
+     * @returns - This document builder instance.
      */
     addExtension(extensionBuilder?: (ext: ExtensionBuilder) => void): DocumentBuilder;
     /**
-     *
+     * Add staff group.
      * @param groupName - Name of staff group.
      * @param staffsTabsAndGroups - staff/tab index (0=top), staff/tab name, or staff group name. Single value or array.
      * @param verticalPosition - Vertical position, are elements added above, below or both.
-     * @returns
+     * @returns - This document builder instance.
      */
     addStaffGroup(groupName: string, staffsTabsAndGroups: number | string | (number | string)[], verticalPosition?: VerticalPosition | `${VerticalPosition}`): DocumentBuilder;
+    /**
+     * Add song end. Adds certain bar line at the end of measure.
+     * @returns - This document builder instance.
+     */
     endSong(): DocumentBuilder;
+    /**
+     * Add section end. Adds certain bar line at the end of measure.
+     * @returns - This document builder instance.
+     */
     endSection(): DocumentBuilder;
+    /**
+     * End current score row. Next measure will start new row.
+     * @returns - This document builder instance.
+     */
     endRow(): DocumentBuilder;
+    /**
+     * Add rests to fill current measure.
+     * @param voiceId - Voice id to add rests to. Single value, array or all if omitted.
+     * @returns - This document builder instance.
+     */
     completeRests(voiceId?: VoiceId | VoiceId[]): DocumentBuilder;
+    /**
+     * Add notes of given scale in ascending order.
+     * @param scale - Scale.
+     * @param bottomNote - Scale starts from note >= bottom note.
+     * @param numOctaves - Number of octaves to add.
+     * @returns - This document builder instance.
+     */
     addScaleArpeggio(scale: Scale, bottomNote: string, numOctaves: number): DocumentBuilder;
 }
 
-export { Annotation, Connective, DocumentBuilder, type ExtensionBuilder, Fermata, Label, MDocument, Navigation, NoteAnchor, NoteOptions, RestOptions, ScoreConfiguration, StaffPreset, StaffTabOrGroups, TieType, type TupletBuilder, TupletOptions, VerticalPosition, VoiceId };
+export { Annotation, AnnotationText, Connective, DocumentBuilder, type ExtensionBuilder, Fermata, Label, MDocument, Navigation, NoteAnchor, NoteOptions, RestOptions, ScoreConfiguration, StaffPreset, StaffTabOrGroups, TieType, type TupletBuilder, TupletOptions, VerticalPosition, VoiceId };