web-music-score 0.0.1 → 6.0.0-pre.0

package/dist/score/index.d.ts

@@ -0,0 +1,466 @@
+import { N as NoteOptions, R as RestOptions, S as StaffPreset, a as ScoreConfiguration, M as MDocument, b as MeasureOptions, V as VoiceId, T as TupletOptions, c as VerseNumber, L as LyricsOptions, d as StaffTabOrGroups, F as Fermata, e as Navigation, A as AnnotationText, f as Annotation, g as Label, C as Connective, h as TieType, i as NoteAnchor, j as VerticalPosition } from '../music-objects-DLmp5uL6.js';
+export { ak as Arpeggio, a6 as BaseConfig, a5 as Clef, ao as DynamicsAnnotation, am as LyricsAlign, an as LyricsHyphen, t as MAccidental, v as MArpeggio, H as MBarLineLeft, G as MBarLineRight, w as MBeamGroup, u as MConnective, y as MEnding, a4 as MExtensionLine, z as MFermata, B as MHeader, D as MImage, a3 as MLyrics, E as MMeasure, J as MNoteGroup, r as MPlaybackButtons, p as MPlayer, q as MRenderContext, P as MRest, U as MRhythmColumn, W as MScoreRow, X as MScoreRowGroup, a1 as MSpecialText, Y as MStaff, I as MStaffBarLine, x as MStaffBeamGroup, K as MStaffNoteGroup, Q as MStaffRest, _ as MStaffSignature, Z as MTab, O as MTabNoteGroup, a0 as MTabRhythm, $ as MTabSignature, a2 as MText, s as MusicInterface, aq as PlayState, ar as PlayStateChangeListener, l as ScoreEvent, o as ScoreEventListener, k as ScoreEventType, n as ScoreObjectEvent, m as ScoreStaffPosEvent, a7 as StaffConfig, al as StaffTabOrGroup, aj as Stem, ac as StringNumber, a8 as TabConfig, ap as TempoAnnotation, ad as getStringNumbers, ag as getVerseNumbers, a9 as getVoiceIds, ae as isStringNumber, ah as isVerseNumber, aa as isVoiceId, af as validateStringNumber, ai as validateVerseNumber, ab as validateVoiceId } from '../music-objects-DLmp5uL6.js';
+import { N as Note } from '../note-RVXvpfyV.js';
+import { S as ScaleType, c as Scale } from '../scale-B1M10_fu.js';
+import { N as NoteLength, h as NoteLengthStr, K as KeySignature, a as TimeSignature, T as TimeSignatures, B as BeamGrouping, k as TupletRatio } from '../tempo-D-JF-8b_.js';
+import '@tspro/ts-utils-lib';
+
+/**
+ * Color attributes.
+ * ```
+ * Attribute hierarchy is:
+ *  + background
+ *  + header
+ *      + title
+ *      + composer
+ *      + arranger
+ *  + rowgroup
+ *      + instrument
+ *      + frame
+ *  + staff|tab
+ *      + frame
+ *      + note
+ *      + rest
+ *      + connective
+ *      + signature
+ *          + clef (staff only)
+ *          + key (staff only)
+ *          + time
+ *          + tempo
+ *          + measurenum
+ *      + tuning (tab only)
+ *      + element
+ *          + fermata
+ *          + annotation
+ *          + navigation
+ *          + label
+ * ```
+ */
+type ColorAttr = "background" | "header" | "title" | "composer" | "arranger" | "rowgroup" | "instrument" | "frame" | "staff" | "tab" | "frame" | "note" | "rest" | "connective" | "signature" | "clef" | "key" | "time" | "tempo" | "measurenum" | "tuning" | "element" | "fermata" | "annotation" | "navigation" | "label";
+/**
+ * Set color of any score document element. Use combination of color attributes to set color of specific elements.
+ * ```ts
+ * setColor("red", "staff");                        // Set color of all staff elements to red.
+ * setColor("red", "staff", "signature");           // Set color of all signature elements of staff to red.
+ * setColor("red", "staff", "key", "signature");    // Set color of key signature of staff to red.
+ * setColor("green", "staff", "time", "signature"); // Set color of time signature of staff to green.
+ * // etc.
+ * ```
+ * See {@link ColorAttr} for attribute hierarchy tree.
+ *
+ * @param color - Color (HTML color code e.g. "green", "#AA6644", etc.)
+ * @param colorAttrs - Any number of color attributes.
+ */
+declare function setColor(color: string, ...colorAttrs: ColorAttr[]): void;
+
+/** Tuplet builder type. */
+type TupletBuilder = {
+    /**
+     * Add note to a tuplet.
+     * @param note - Instance of Note or string, single value (e.g. "C4") or array (e.g. ["C4", "E4", "G4"]).
+     * @param noteLength - Note length (e.g. "4n").
+     * @param noteOptions - Note options.
+     * @returns - This tuplet builder object.
+     */
+    addNote: (note: Note | string | (Note | string)[], noteLength: NoteLength | NoteLengthStr, noteOptions?: 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 noteOptions - Note options.
+     * @returns - This tuplet builder object.
+     */
+    addChord: (notes: (Note | string)[], noteLength: NoteLength | NoteLengthStr, noteOptions?: NoteOptions) => TupletBuilder;
+    /**
+     * Add rest to a tuplet.
+     * @param restLength - Rest length (e.g. "4n").
+     * @param restOptions - Rest options.
+     * @returns - This tuplet builder object.
+     */
+    addRest: (restLength: NoteLength | NoteLengthStr, restOptions?: 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.
+ * ```ts
+ * // 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();
+ * ```
+ */
+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 static DefaultMeasureOptions;
+    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.
+     * @param measureOptions - Measure options.
+     * @returns - This document builder instance.
+     */
+    addMeasure(measureOptions?: MeasureOptions): 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;
+    /**
+     * 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;
+    /**
+     * Add note to current measure.
+     * @param voiceId - Voice id to add note to.
+     * @param note - Instance of Note or string, single value (e.g. "C4") or array (e.g. ["C4", "E4", "G4"]).
+     * @param noteLength - Note length (e.g. "4n").
+     * @param noteOptions - Note options.
+     * @returns - This document builder instance.
+     */
+    addNote(voiceId: VoiceId, note: Note | string | (Note | string)[], noteLength: NoteLength | NoteLengthStr, noteOptions?: NoteOptions): DocumentBuilder;
+    /**
+     * Add chord to current measure.
+     * @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 noteOptions - Note options.
+     * @returns - This document builder instance.
+     */
+    addChord(voiceId: VoiceId, notes: (Note | string)[], noteLength: NoteLength | NoteLengthStr, noteOptions?: NoteOptions): DocumentBuilder;
+    /**
+     * Add rest to current measure.
+     * @param voiceId - Voice id to add rest to.
+     * @param restLength - Rest length (e.g. "4n").
+     * @param restOptions - Rest options.
+     * @returns - This document builder instance.
+     */
+    addRest(voiceId: VoiceId, restLength: NoteLength | NoteLengthStr, restOptions?: RestOptions): DocumentBuilder;
+    /**
+     * Usage:
+     * ```ts
+     * addTuplet(0, Theory.Tuplet.Triplet, notes => {
+     *     notes.addNote("G3", Theory.NoteLength.Eighth);
+     *     notes.addNote("B3", Theory.NoteLength.Eighth);
+     *     notes.addNote("D4", Theory.NoteLength.Eighth);
+     * });
+     * ```
+     *
+     * @param voiceId - Voice id to add tuplet to.
+     * @param tupletRatio - You can also use Theory.Tuplet presets (e.g. Theory.Tuplet.Triplet).
+     * @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 currentLyricsAlign;
+    private addLyricsInternal;
+    /**
+     * Add lyrics to current measure.
+     * @param verse - Verse number (e.g. 1).
+     * @param lyricsLength - Lyrics text length (e.g. "2n").
+     * @param lyricsText - Lyrics text (empty space if omitted), single value or array.
+     * @param lyricsOptions - Lyrics options.
+     * @returns - This document builder instance.
+     */
+    addLyrics(verse: VerseNumber, lyricsLength: NoteLength | NoteLengthStr, lyricsText?: string | string[], lyricsOptions?: LyricsOptions): DocumentBuilder;
+    /**
+     * Add lyrics to current measure to given staff/tab/group.
+     * @param staffTabOrGroups - staff/tab index (0=top), staff/tab name, or staff group name.
+     * @param verse - Verse number (e.g. 1).
+     * @param lyricsLength - Lyrics text length (e.g. "2n").
+     * @param lyricsText - Lyrics text (empty space if omitted), single value or array.
+     * @param lyricsOptions - Lyrics options.
+     * @returns - This document builder instance.
+     */
+    addLyricsTo(staffTabOrGroups: StaffTabOrGroups, verse: VerseNumber, lyricsLength: NoteLength | NoteLengthStr, lyricsText?: string | string[], lyricsOptions?: LyricsOptions): 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;
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * Add extension line to previously added annotation or label element.
+     * ```ts
+     *     // 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
+     * ```
+     * @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 - 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, AnnotationText, type ColorAttr, Connective, DocumentBuilder, type ExtensionBuilder, Fermata, Label, LyricsOptions, MDocument, MeasureOptions, Navigation, NoteAnchor, NoteOptions, RestOptions, ScoreConfiguration, StaffPreset, StaffTabOrGroups, TieType, type TupletBuilder, TupletOptions, VerseNumber, VerticalPosition, VoiceId, setColor };