@tspro/web-music-score 4.0.0 → 4.1.0

package/dist/score/index.d.ts

@@ -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-7k8qGG44.js';
-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-7k8qGG44.js';
-import { N as Note } from '../note-CcVdUFqS.js';
-import { S as ScaleType, c as Scale } from '../scale-CvPbJvfN.js';
-import { N as NoteLength, h as NoteLengthStr, K as KeySignature, a as TimeSignature, T as TimeSignatureString, j as TupletRatio } from '../tempo-r2sb6Ku2.js';
+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-xJJNlFwK.js';
+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-xJJNlFwK.js';
+import { N as Note } from '../note-eA2xPPiG.js';
+import { S as ScaleType, c as Scale } from '../scale-DQNA-YLD.js';
+import { N as NoteLength, i as NoteLengthStr, K as KeySignature, b as TimeSignature, T as TimeSignatures, B as BeamGrouping, k as TupletRatio } from '../tempo-Bp1UzsrZ.js';
 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 };