@tspro/web-music-score
    Preparing search index...

    Class DocumentBuilder

    Document builder class.

    // 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();
    Index

    Constructors

    constructor

    Methods

    addAnnotation addAnnotationTo addChord addConnective addExtension addFermata addFermataTo addLabel addLabelTo addLyrics addLyricsTo addMeasure addNavigation addNavigationTo addNote addRest addScaleArpeggio addStaffGroup addTuplet completeRests endRow endSection endSong getDocument setHeader setKeySignature setMeasuresPerRow setScoreConfiguration setTempo setTimeSignature

    Constructors

    Methods

    • Add annotation text to column of last added note/chord/rest in current measure.

      Parameters

      Returns DocumentBuilder

      • This document builder instance.

    • Add annotation text to column of last added note/chord/rest in current measure.

      Parameters

      • annotation: "dynamics" | "tempo" | Annotation

        Annotation type (e.g. "tempo" or Annotation.Tempo).

      • text: string

        Annotation text (unrestricted).

      Returns DocumentBuilder

      • This document builder instance.

    • Add annotation text to column of last added note/chord/rest in current measure to given staff/tab/group.

      Parameters

      • staffTabOrGroups: StaffTabOrGroups

        staff/tab index (0=top), staff/tab name, or staff group name.

      • text: AnnotationText

        Known annotation text (e.g. "pp").

      Returns DocumentBuilder

      • This document builder instance.

    • Add annotation text to column of last added note/chord/rest in current measure to given staff/tab/group.

      Parameters

      • staffTabOrGroups: StaffTabOrGroups

        staff/tab index (0=top), staff/tab name, or staff group name.

      • annotation: "dynamics" | "tempo" | Annotation

        Annotation type (e.g. "tempo" or Annotation.Tempo).

      • text: string

        Annotation text (unrestricted).

      Returns DocumentBuilder

      • This document builder instance.

    • Add chord to current measure.

      Parameters

      • voiceId: VoiceId

        Voice id to add chord to.

      • notes: (string | Note)[]

        Array of notes, each instance of Note or string (e.g. "D4").

      • noteLength:
            | "1n"
            | "1t"
            | "1."
            | "1.."
            | "1..."
            | "1...."
            | "1....."
            | "1......"
            | "2n"
            | "2t"
            | "2."
            | "2.."
            | "2..."
            | "2...."
            | "2....."
            | "4n"
            | "4t"
            | "4."
            | "4.."
            | "4..."
            | "4...."
            | "8n"
            | "8t"
            | "8."
            | "8.."
            | "8..."
            | "16n"
            | "16t"
            | "16."
            | "16.."
            | "32n"
            | "32t"
            | "32."
            | "64n"
            | "64t"
            | NoteLength

        Note length (e.g. "4n").

      • OptionalnoteOptions: NoteOptions

        Note options.

      Returns DocumentBuilder

      • This document builder instance.

    • Add tie starting from last added note/chord.

      Parameters

      • connective: "tie" | Tie

        Connective type ("tie" or Connective.Tie).

      • OptionaltieSpan: number | "stub" | "toMeasureEnd" | TieType

        How many notes across this tie spans.

      • OptionalnotAnchor: "auto" | "above" | "center" | "below" | "stemTip" | NoteAnchor

        Anchor point for note and this tie.

      Returns DocumentBuilder

      • This document builder instance.

    • Add slur starting from last added note/chord.

      Parameters

      • connective: "slur" | Slur

        Connective type ("slur" or Connective.Slur).

      • OptionalslurSpan: number

        How many notes across this slur spans.

      • OptionalnotAnchor: "auto" | "above" | "center" | "below" | "stemTip" | NoteAnchor

        Anchor point for note and this slur.

      Returns DocumentBuilder

      • This document builder instance.

    • Add slide starting from last added note/chord.

      Parameters

      • connective: "slide" | Slide

        Connective type ("slide" or Connective.Slide).

      • OptionalnotAnchor: "auto" | "above" | "center" | "below" | "stemTip" | NoteAnchor

        Anchor point for note and this slide.

      Returns DocumentBuilder

      • This document builder instance.

    • Add extension line to previously added annotation or label element.

          // 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

      Parameters

      • OptionalextensionBuilder: (ext: ExtensionBuilder) => void

        Extension builder function used to build exstension.

      Returns DocumentBuilder

      • This document builder instance.

    • Add fermata to current measure.

      Parameters

      • fermata: "atNote" | "atMeasureEnd" | Fermata = Fermata.AtNote

        Fermata type (e.g. "atNote" or Fermata.AtrNote).

      Returns DocumentBuilder

      • This document builder instance.

    • Add Fermata to current measure to given staff/tab/group.

      Parameters

      • staffTabOrGroups: StaffTabOrGroups

        staff/tab index (0=top), staff/tab name, or staff group name.

      • fermata: "atNote" | "atMeasureEnd" | Fermata = Fermata.AtNote

        Fermata type (e.g. "atNote" or Fermata.AtrNote).

      Returns DocumentBuilder

      • This document builder instance.

    • Add label text to column of last added note/chord/rest in current measure.

      Parameters

      • label: "note" | "chord" | Label

        Label type (e.g. "chord" or Label.Chord).

      • text: string

        label text (e.g. "Am").

      Returns DocumentBuilder

      • This document builder instance.

    • Add label text to column of last added note/chord/rest in current measure to given staff/tab/group.

      Parameters

      • staffTabOrGroups: StaffTabOrGroups

        staff/tab index (0=top), staff/tab name, or staff group name.

      • label: "note" | "chord" | Label

        Label type (e.g. "chord" or Label.Chord).

      • text: string

        label text (e.g. "Am").

      Returns DocumentBuilder

      • This document builder instance.

    • Add lyrics to current measure.

      Parameters

      • verse: VerseNumber

        Verse number (e.g. 1).

      • lyricsLength:
            | "1n"
            | "1t"
            | "1."
            | "1.."
            | "1..."
            | "1...."
            | "1....."
            | "1......"
            | "2n"
            | "2t"
            | "2."
            | "2.."
            | "2..."
            | "2...."
            | "2....."
            | "4n"
            | "4t"
            | "4."
            | "4.."
            | "4..."
            | "4...."
            | "8n"
            | "8t"
            | "8."
            | "8.."
            | "8..."
            | "16n"
            | "16t"
            | "16."
            | "16.."
            | "32n"
            | "32t"
            | "32."
            | "64n"
            | "64t"
            | NoteLength

        Lyrics text length (e.g. "2n").

      • OptionallyricsText: string | string[]

        Lyrics text (empty space if omitted), single value or array.

      • OptionallyricsOptions: LyricsOptions

        Lyrics options.

      Returns DocumentBuilder

      • This document builder instance.

    • Add lyrics to current measure to given staff/tab/group.

      Parameters

      • staffTabOrGroups: StaffTabOrGroups

        staff/tab index (0=top), staff/tab name, or staff group name.

      • verse: VerseNumber

        Verse number (e.g. 1).

      • lyricsLength:
            | "1n"
            | "1t"
            | "1."
            | "1.."
            | "1..."
            | "1...."
            | "1....."
            | "1......"
            | "2n"
            | "2t"
            | "2."
            | "2.."
            | "2..."
            | "2...."
            | "2....."
            | "4n"
            | "4t"
            | "4."
            | "4.."
            | "4..."
            | "4...."
            | "8n"
            | "8t"
            | "8."
            | "8.."
            | "8..."
            | "16n"
            | "16t"
            | "16."
            | "16.."
            | "32n"
            | "32t"
            | "32."
            | "64n"
            | "64t"
            | NoteLength

        Lyrics text length (e.g. "2n").

      • OptionallyricsText: string | string[]

        Lyrics text (empty space if omitted), single value or array.

      • OptionallyricsOptions: LyricsOptions

        Lyrics options.

      Returns DocumentBuilder

      • This document builder instance.

    • Add navigation element to current measure.

      Parameters

      • navigation:
            | "D.C. al Fine"
            | "D.C. al Coda"
            | "D.S. al Fine"
            | "D.S. al Coda"
            | "Coda"
            | "toCoda"
            | "Segno"
            | "Fine"
            | "startRepeat"
            | "endRepeat"
            | "ending"
            | Navigation

        Navigation element (e.g. "D.S. al Fine" or Navigation.DS_al_Fine).

      Returns DocumentBuilder

      • This document builder instance.

    • Add end repeat navigation element to current measure.

      Parameters

      • navigation: "endRepeat" | EndRepeat

        End repeat navigation element ("endRepeat" or Navigation.EndRepeat).

      • playCount: number

        Number of times to play the ended repeat section.

      Returns DocumentBuilder

      • This document builder instance.

    • Add ending navigation element to current measure.

      Parameters

      • navigation: "ending" | Ending

        Ending navigation element ("ending" or Navigation.Ending).

      • ...passages: number[]

        Passage numbers for measure marked by this ending is played.

      Returns DocumentBuilder

      • This document builder instance.

    • Add navigation element to current measure to given staff/tab/group.

      Parameters

      • staffTabOrGroups: StaffTabOrGroups

        staff/tab index (0=top), staff/tab name, or staff group name.

      • navigation:
            | "D.C. al Fine"
            | "D.C. al Coda"
            | "D.S. al Fine"
            | "D.S. al Coda"
            | "Coda"
            | "toCoda"
            | "Segno"
            | "Fine"
            | "startRepeat"
            | "endRepeat"
            | "ending"
            | Navigation

      Returns DocumentBuilder

      • This document builder instance.

    • Add end repeat navigation element to current measure to given staff/tab/group.

      Parameters

      • staffTabOrGroups: StaffTabOrGroups

        staff/tab index (0=top), staff/tab name, or staff group name.

      • navigation: "endRepeat" | EndRepeat
      • playCount: number

      Returns DocumentBuilder

      • This document builder instance.

    • Add ending navigation element to current measure to given staff/tab/group.

      Parameters

      • staffTabOrGroups: StaffTabOrGroups

        staff/tab index (0=top), staff/tab name, or staff group name.

      • navigation: "ending" | Ending
      • ...passages: number[]

      Returns DocumentBuilder

      • This document builder instance.

    • Add note to current measure.

      Parameters

      • voiceId: VoiceId

        Voice id to add note to.

      • note: string | Note | (string | Note)[]

        Instance of Note or string, single value (e.g. "C4") or array (e.g. ["C4", "E4", "G4"]).

      • noteLength:
            | "1n"
            | "1t"
            | "1."
            | "1.."
            | "1..."
            | "1...."
            | "1....."
            | "1......"
            | "2n"
            | "2t"
            | "2."
            | "2.."
            | "2..."
            | "2...."
            | "2....."
            | "4n"
            | "4t"
            | "4."
            | "4.."
            | "4..."
            | "4...."
            | "8n"
            | "8t"
            | "8."
            | "8.."
            | "8..."
            | "16n"
            | "16t"
            | "16."
            | "16.."
            | "32n"
            | "32t"
            | "32."
            | "64n"
            | "64t"
            | NoteLength

        Note length (e.g. "4n").

      • OptionalnoteOptions: NoteOptions

        Note options.

      Returns DocumentBuilder

      • This document builder instance.

    • Add rest to current measure.

      Parameters

      • voiceId: VoiceId

        Voice id to add rest to.

      • restLength:
            | "1n"
            | "1t"
            | "1."
            | "1.."
            | "1..."
            | "1...."
            | "1....."
            | "1......"
            | "2n"
            | "2t"
            | "2."
            | "2.."
            | "2..."
            | "2...."
            | "2....."
            | "4n"
            | "4t"
            | "4."
            | "4.."
            | "4..."
            | "4...."
            | "8n"
            | "8t"
            | "8."
            | "8.."
            | "8..."
            | "16n"
            | "16t"
            | "16."
            | "16.."
            | "32n"
            | "32t"
            | "32."
            | "64n"
            | "64t"
            | NoteLength

        Rest length (e.g. "4n").

      • OptionalrestOptions: RestOptions

        Rest options.

      Returns DocumentBuilder

      • This document builder instance.

    • Add notes of given scale in ascending order.

      Parameters

      • scale: Scale

        Scale.

      • bottomNote: string

        Scale starts from note >= bottom note.

      • numOctaves: number

        Number of octaves to add.

      Returns DocumentBuilder

      • This document builder instance.

    • Add staff group.

      Parameters

      • groupName: string

        Name of staff group.

      • staffsTabsAndGroups: string | number | (string | number)[]

        staff/tab index (0=top), staff/tab name, or staff group name. Single value or array.

      • verticalPosition: "auto" | "above" | "below" | "both" | VerticalPosition = VerticalPosition.Auto

        Vertical position, are elements added above, below or both.

      Returns DocumentBuilder

      • This document builder instance.

    • Usage:

      addTuplet(0, Theory.Tuplet.Triplet, notes => {
          notes.addNote("G3", Theory.NoteLength.Eighth);
          notes.addNote("B3", Theory.NoteLength.Eighth);
          notes.addNote("D4", Theory.NoteLength.Eighth);
      });

      Parameters

      • voiceId: VoiceId

        Voice id to add tuplet to.

      • tupletRatio: TupletRatio & TupletOptions

        You can also use Theory.Tuplet presets (e.g. Theory.Tuplet.Triplet).

      • tupletBuilder: (notes: TupletBuilder) => void

        Tuplet builder function to build tuplet.

      Returns DocumentBuilder

      • This document builder instance.

    • Get music document after finished building.

      Returns MDocument

      • Music document.

    • Set header texts.

      Parameters

      • Optionaltitle: string

        Title of this docmument/musical piece.

      • Optionalcomposer: string

        Composer of this document/musical piece.

      • Optionalarranger: string

        Arranger of this document/musical piece.

      Returns DocumentBuilder

      • This document builder instance.

    • Set key signature for current measure and forward.

      Parameters

      • tonic: string

        Tonic note (e.g. "C").

      • scaleType:
            | ScaleType
            | "Major"
            | "Natural Minor"
            | "Harmonic Minor"
            | "Ionian"
            | "Dorian"
            | "Phrygian"
            | "Lydian"
            | "Mixolydian"
            | "Aeolian"
            | "Locrian"
            | "Major Pentatonic"
            | "Minor Pentatonic"
            | "Major Hexatonic Blues"
            | "Minor Hexatonic Blues"
            | "Heptatonic Blues"

        Scale type (e.g. string "Major" or ScaleType.Major).

      Returns DocumentBuilder

      • This document builder instance.

    • Set key signature for current measure and forward.

      Parameters

      Returns DocumentBuilder

      • This document builder instance.

    • Set key signature for current measure and forward.

      Parameters

      • keySignature: string

        Key signature string (e.g. "C Major").

      Returns DocumentBuilder

      • This document builder instance.

    • Set key signature for current measure and forward.

      Parameters

      • scale: Scale

        Scale object instance.

      Returns DocumentBuilder

      • This document builder instance.

    • Automatically limit number of measures per score row.

      Parameters

      • measuresPerRow: number

        Number of measures per row. Must be integer >=1 or Infinity.

      Returns DocumentBuilder

      • This document builder instance.

    • Use staff preset values to set score confguration. This call will request new score row.

      Parameters

      • staffPreset:
            | "treble"
            | "bass"
            | "grand"
            | "guitarTreble"
            | "guitarTab"
            | "guitarCombined"
            | StaffPreset

        Staff preset (e.g. "treble").

      Returns DocumentBuilder

    • Use staff preset values to set score confguration. This call will request new score row.

      Parameters

      • config: ScoreConfiguration

        Score configuration (e.g. { type: "staff", clef: "G", isOctavewDown: true }).

      Returns DocumentBuilder

    • Set tempo.

      Parameters

      • beatsPerMinute: number

        Tempo beats per minute.

      Returns DocumentBuilder

      • This document builder instance.

    • Set tempo.

      Parameters

      • beatsPerMinute: number

        Tempo beats per minute.

      • beatLength:
            | "1n"
            | "1t"
            | "1."
            | "1.."
            | "1..."
            | "1...."
            | "1....."
            | "1......"
            | "2n"
            | "2t"
            | "2."
            | "2.."
            | "2..."
            | "2...."
            | "2....."
            | "4n"
            | "4t"
            | "4."
            | "4.."
            | "4..."
            | "4...."
            | "8n"
            | "8t"
            | "8."
            | "8.."
            | "8..."
            | "16n"
            | "16t"
            | "16."
            | "16.."
            | "32n"
            | "32t"
            | "32."
            | "64n"
            | "64t"
            | NoteLength

        Length of one beat.

      Returns DocumentBuilder

      • This document builder instance.

    • Parameters

      • beatsPerMinute: number

        Tempo beats per minute.

      • beatLength:
            | "1n"
            | "1t"
            | "1."
            | "1.."
            | "1..."
            | "1...."
            | "1....."
            | "1......"
            | "2n"
            | "2t"
            | "2."
            | "2.."
            | "2..."
            | "2...."
            | "2....."
            | "4n"
            | "4t"
            | "4."
            | "4.."
            | "4..."
            | "4...."
            | "8n"
            | "8t"
            | "8."
            | "8.."
            | "8..."
            | "16n"
            | "16t"
            | "16."
            | "16.."
            | "32n"
            | "32t"
            | "32."
            | "64n"
            | "64t"
            | NoteLength

        Length of one beat.

      • dotted: number | boolean

        Dot count of length of one beat.

      Returns DocumentBuilder

      • This document builder instance.
      • Use dotted beatLength instead (e.g. "4..").

    • Set time signature for current measure and forward.

      Parameters

      Returns DocumentBuilder

      • This document builder instance.

    • Set time signature for current measure and forward.

      Parameters

      • timeSignature:
            | "2/4"
            | "3/4"
            | "4/4"
            | "3/8"
            | "5/8"
            | "6/8"
            | "7/8"
            | "9/8"
            | "12/8"
            | TimeSignatures

        TimeSignatures enum value or string (e.g. "3/4").

      • OptionalbeamGrouping: "2-3" | "3-2" | "2-2-3" | "3-2-2" | BeamGrouping

        Beam grouping (e.g. "3-2" for time signature "5/8").

      Returns DocumentBuilder

      • This document builder instance.

    • Set time signature for current measure and forward.

      Parameters

      • beatCount: number

        Beat count of time signature (e.g. 3 in "3/4").

      • beatSize: number

        Beat size of time signature (e.g. 4 in "3/4").

      • OptionalbeamGrouping: "2-3" | "3-2" | "2-2-3" | "3-2-2" | BeamGrouping

        Beam grouping (e.g. "3-2" for time signature "5/8").

      Returns DocumentBuilder

      • This document builder instance.

    Settings

    Member Visibility

    On This Page

    Constructors
    Methods