@tspro/web-music-score 3.1.1 → 4.0.0

package/dist/score/index.d.ts

@@ -1,54 +1,121 @@
-import { S as StaffPreset, a as ScoreConfiguration, M as MDocument, N as NoteOptions, R as RestOptions, F as Fermata, b as StaffTabOrGroups, c as Navigation, L as Label, A as Annotation, C as Connective, T as TieType, d as NoteAnchor, V as VerticalPosition } from '../interface-Fn8ufBQx.js';
-export { a4 as Arpeggio, Y as Clef, a5 as ConnectiveSpan, D as DivRect, k as MAccidental, m as MArpeggio, v as MBarLineLeft, u as MBarLineRight, n as MBeamGroup, l as MConnective, p as MEnding, Q as MExtensionLine, q as MFermata, r as MHeader, s as MImage, t as MMeasure, x as MNoteGroup, X as MPlaybackButtons, U as MPlayer, W as MRenderer, B as MRest, G as MRhythmColumn, H as MScoreRow, K as MSignature, O as MSpecialText, I as MStaff, o as MStaffBeamGroup, y as MStaffNoteGroup, E as MStaffRest, w as MStaffTabBarLine, J as MTab, z as MTabNoteGroup, P as MText, j as MusicInterface, a7 as PlayState, a8 as PlayStateChangeListener, f as ScoreEvent, i as ScoreEventListener, e as ScoreEventType, h as ScoreObjectEvent, g as ScoreStaffPosEvent, Z as StaffConfig, a6 as StaffTabOrGroup, a3 as Stem, a1 as StringNumber, _ as TabConfig, $ as VoiceId, a2 as getStringNumbers, a0 as getVoiceIds } from '../interface-Fn8ufBQx.js';
-import { N as Note } from '../note-BFa43I86.js';
-import { S as ScaleType, c as Scale } from '../scale-ebJm37q1.js';
-import { K as KeySignature, a as TimeSignature, T as TimeSignatureString, N as NoteLength } from '../tempo-DgqDEsn0.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 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 '@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}`;
+
+type TupletBuilder = {
+    addNote: (note: Note | string, noteLength: NoteLength | NoteLengthStr, options?: NoteOptions) => TupletBuilder;
+    addChord: (notes: (Note | string)[], noteLength: NoteLength | NoteLengthStr, options?: NoteOptions) => TupletBuilder;
+    addRest: (restLength: NoteLength | NoteLengthStr, options?: RestOptions) => TupletBuilder;
+};
+type ExtensionBuilder = {
+    notes: (noteLength: NoteLength | NoteLengthStr, noteCount?: number) => ExtensionBuilder;
+    measures: (measureCount: number) => ExtensionBuilder;
+    infinity: () => ExtensionBuilder;
+    hide: () => ExtensionBuilder;
+};
 declare class DocumentBuilder {
     private readonly doc;
     constructor();
-    setScoreConfiguration(staffPreset: StaffPreset): DocumentBuilder;
+    setScoreConfiguration(staffPreset: StaffPreset | `${StaffPreset}`): DocumentBuilder;
     setScoreConfiguration(config: ScoreConfiguration): DocumentBuilder;
     private getMeasure;
     getDocument(): MDocument;
     setHeader(title?: string, composer?: string, arranger?: string): DocumentBuilder;
     setMeasuresPerRow(measuresPerRow: number): DocumentBuilder;
     addMeasure(): DocumentBuilder;
-    setKeySignature(tonic: string, scaleType: ScaleType): DocumentBuilder;
+    setKeySignature(tonic: string, scaleType: ScaleType | `${ScaleType}`): DocumentBuilder;
     setKeySignature(keySignature: KeySignature): DocumentBuilder;
+    setKeySignature(keySignature: string): DocumentBuilder;
     setKeySignature(scale: Scale): DocumentBuilder;
     setTimeSignature(timeSignature: TimeSignature | TimeSignatureString): DocumentBuilder;
-    setTempo(beatsPerMinute: number, beatLength?: NoteLength, dotted?: boolean): DocumentBuilder;
-    addNote(voiceId: number, note: Note | string, noteLength: NoteLength, options?: NoteOptions): DocumentBuilder;
-    addChord(voiceId: number, notes: (Note | string)[], noteLength: NoteLength, options?: NoteOptions): DocumentBuilder;
-    addRest(voiceId: number, restLength: NoteLength, options?: RestOptions): DocumentBuilder;
+    setTempo(beatsPerMinute: number): DocumentBuilder;
+    setTempo(beatsPerMinute: number, beatLength: NoteLength | NoteLengthStr): DocumentBuilder;
+    /** @deprecated - Use dotted beatLength instead (e.g. "4..") */
+    setTempo(beatsPerMinute: number, beatLength: NoteLength | NoteLengthStr, dotted: boolean | number): DocumentBuilder;
+    addNote(voiceId: number, note: Note | string, noteLength: NoteLength | NoteLengthStr, options?: NoteOptions): DocumentBuilder;
+    addChord(voiceId: number, notes: (Note | string)[], noteLength: NoteLength | NoteLengthStr, options?: NoteOptions): DocumentBuilder;
+    addRest(voiceId: number, restLength: NoteLength | NoteLengthStr, options?: RestOptions): DocumentBuilder;
+    /**
+     * Usage:
+     * <pre>
+     * addTuplet(0, Theory.Tuplet.Triplet, notes => {
+     *     notes.addNote("G3", Theory.NoteLength.Eighth);
+     *     notes.addNote("B3", Theory.NoteLength.Eighth);
+     *     notes.addNote("D4", Theory.NoteLength.Eighth);
+     * });
+     * </pre>
+     *
+     * @param voiceId
+     * @param tupletRatio - You can also use Theory.Tuplet presets (e.g. Theory.Tuplet.Triplet).
+     * @param tupletBuilder
+     * @returns
+     */
+    addTuplet(voiceId: VoiceId, tupletRatio: TupletRatio & TupletOptions, tupletBuilder: (notes: TupletBuilder) => void): DocumentBuilder;
     private addFermataInternal;
-    addFermata(fermata?: Fermata): DocumentBuilder;
+    addFermata(fermata?: Fermata | `${Fermata}`): DocumentBuilder;
     /** @param staffTabOrGroups  - staff/tab index (0=top), staff/tab name, or staff group name. */
-    addFermataTo(staffTabOrGroups: StaffTabOrGroups, fermata?: Fermata): DocumentBuilder;
+    addFermataTo(staffTabOrGroups: StaffTabOrGroups, fermata?: Fermata | `${Fermata}`): DocumentBuilder;
     private addNavigationInternal;
-    addNavigation(navigation: Navigation): DocumentBuilder;
-    addNavigation(navigation: Navigation.EndRepeat, playCount: number): DocumentBuilder;
-    addNavigation(navigation: Navigation.Ending, ...passages: number[]): DocumentBuilder;
+    addNavigation(navigation: Navigation | `${Navigation}`): DocumentBuilder;
+    addNavigation(navigation: Navigation.EndRepeat | `${Navigation.EndRepeat}`, playCount: number): DocumentBuilder;
+    addNavigation(navigation: Navigation.Ending | `${Navigation.Ending}`, ...passages: number[]): DocumentBuilder;
     /** @param staffTabOrGroups  - staff/tab index (0=top), staff/tab name, or staff group name. */
-    addNavigationTo(staffTabOrGroups: StaffTabOrGroups, navigation: Navigation): DocumentBuilder;
+    addNavigationTo(staffTabOrGroups: StaffTabOrGroups, navigation: Navigation | `${Navigation}`): DocumentBuilder;
     /** @param staffTabOrGroups  - staff/tab index (0=top), staff/tab name, or staff group name. */
-    addNavigationTo(staffTabOrGroups: StaffTabOrGroups, navigation: Navigation.EndRepeat, playCount: number): DocumentBuilder;
+    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. */
-    addNavigationTo(staffTabOrGroups: StaffTabOrGroups, navigation: Navigation.Ending, ...passages: number[]): DocumentBuilder;
-    private addLabelInternal;
-    addLabel(label: Label, text: string): DocumentBuilder;
-    /** @param staffTabOrGroups  - staff/tab index (0=top), staff/tab name, or staff group name. */
-    addLabelTo(staffTabOrGroups: StaffTabOrGroups, label: Label, text: string): DocumentBuilder;
+    addNavigationTo(staffTabOrGroups: StaffTabOrGroups, navigation: Navigation.Ending | `${Navigation.Ending}`, ...passages: number[]): DocumentBuilder;
     private addAnnotationInternal;
-    addAnnotation(annotation: Annotation, text: string): DocumentBuilder;
+    addAnnotation(text: AnnotationsType): DocumentBuilder;
+    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. */
+    addAnnotationTo(staffTabOrGroups: StaffTabOrGroups, annotation: Annotation | `${Annotation}`, text: string): DocumentBuilder;
+    private addLabelInternal;
+    addLabel(label: Label | `${Label}`, text: string): DocumentBuilder;
     /** @param staffTabOrGroups  - staff/tab index (0=top), staff/tab name, or staff group name. */
-    addAnnotationTo(staffTabOrGroups: StaffTabOrGroups, annotation: Annotation, text: string): DocumentBuilder;
-    addConnective(connective: Connective.Tie, tieSpan?: number | TieType, notAnchor?: NoteAnchor): DocumentBuilder;
-    addConnective(connective: Connective.Slur, slurSpan?: number, notAnchor?: NoteAnchor): DocumentBuilder;
-    addConnective(connective: Connective.Slide, notAnchor?: NoteAnchor): DocumentBuilder;
-    addExtension(extensionLength: NoteLength | number, extensionVisible?: boolean): DocumentBuilder;
+    addLabelTo(staffTabOrGroups: StaffTabOrGroups, label: Label | `${Label}`, text: string): DocumentBuilder;
+    addConnective(connective: Connective.Tie | `${Connective.Tie}`, tieSpan?: number | TieType | `${TieType}`, notAnchor?: NoteAnchor | `${NoteAnchor}`): DocumentBuilder;
+    addConnective(connective: Connective.Slur | `${Connective.Slur}`, slurSpan?: number, notAnchor?: NoteAnchor | `${NoteAnchor}`): DocumentBuilder;
+    addConnective(connective: Connective.Slide | `${Connective.Slide}`, notAnchor?: NoteAnchor | `${NoteAnchor}`): DocumentBuilder;
+    /**
+     * Extension length example:
+     * <pre>
+     *     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
+     */
+    addExtension(extensionBuilder?: (ext: ExtensionBuilder) => void): DocumentBuilder;
     /**
      *
      * @param groupName - Name of staff group.
@@ -56,12 +123,12 @@ declare class DocumentBuilder {
      * @param verticalPosition - Vertical position, are elements added above, below or both.
      * @returns
      */
-    addStaffGroup(groupName: string, staffsTabsAndGroups: number | string | (number | string)[], verticalPosition?: VerticalPosition): DocumentBuilder;
+    addStaffGroup(groupName: string, staffsTabsAndGroups: number | string | (number | string)[], verticalPosition?: VerticalPosition | `${VerticalPosition}`): DocumentBuilder;
     endSong(): DocumentBuilder;
     endSection(): DocumentBuilder;
     endRow(): DocumentBuilder;
-    completeRests(voiceId?: number): DocumentBuilder;
+    completeRests(voiceId?: VoiceId | VoiceId[]): DocumentBuilder;
     addScaleArpeggio(scale: Scale, bottomNote: string, numOctaves: number): DocumentBuilder;
 }
 
-export { Annotation, Connective, DocumentBuilder, Fermata, Label, MDocument, Navigation, NoteAnchor, NoteOptions, RestOptions, ScoreConfiguration, StaffPreset, StaffTabOrGroups, TieType, VerticalPosition };
+export { Annotation, Connective, DocumentBuilder, type ExtensionBuilder, Fermata, Label, MDocument, Navigation, NoteAnchor, NoteOptions, RestOptions, ScoreConfiguration, StaffPreset, StaffTabOrGroups, TieType, type TupletBuilder, TupletOptions, VerticalPosition, VoiceId };