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").addAnnotation("chordLabel", "C")
    .addRest(1, "4n")
    // etc.
    .getDEocument();

Constructors

constructor

new DocumentBuilder(options?: DocumentOptions): DocumentBuilder
Create new document builder instance.
Parameters
- Optionaloptions: DocumentOptions
Returns DocumentBuilder

Methods

addAnnotation

addAnnotation(
    labelKind: AnnotationKindLabelValue,
    labelText: string,
    options?: AnnotationOptions,
): DocumentBuilder
Add annotation with label text to current measure.
Parameters
- labelKind: AnnotationKindLabelValue
  Annotation kind.
- labelText: string
  Label text.
- Optionaloptions: AnnotationOptions
  Annotation options.
Returns DocumentBuilder
- This document builder instance.
addAnnotation(kind: string, options?: AnnotationOptions): DocumentBuilder
Add any annotation kind to current measure.
Parameters
- kind: string
  Annotation kind (e.g. "pp").
- Optionaloptions: AnnotationOptions
  Annotation options.
Returns DocumentBuilder
- This document builder instance.

addAnnotation(...args: (string | number | AnnotationOptions)[]): DocumentBuilder

Catch all overload for deprecated stuff. Wil be removed in future release.

// Deprecated:
addAnnotation(group: AnnotationGroup, kind: string, options?: AnnotationOptions): DocumentBuilder;
// Use instead:
addAnnotation(kind: string, { group: AnnotationGroup }): DocumentBuilder;

// Deprecated:
addAnnotation("ending", ...endingPassages: number[]): DocumentBuilder;
// Use instead:
addAnnotation("ending", { endingPassages: number | number[] }): DocumentBuilder;

// Deprecated:
addAnnotation("endRepeat", repeatCount?: number): DocumentBuilder;
// Use instead:
addAnnotation("endRepeat", { repeatCount: number }): DocumentBuilder;

Parameters

...args: (string | number | AnnotationOptions)[]

Returns DocumentBuilder

Deprecated

Use AnnotationOptions instead for extra args. Will be removed in future release.

addAnnotationTo

addAnnotationTo(
    staffTargets: StaffTargets,
    labelKind: AnnotationKindLabelValue,
    labelText: string,
    options?: AnnotationOptions,
): DocumentBuilder
Add annotation with label text to current measure.
Parameters
- staffTargets: StaffTargets
  Single or multiple staff/tab/group identifiers.
- labelKind: AnnotationKindLabelValue
  Annotation kind.
- labelText: string
  Label text.
- Optionaloptions: AnnotationOptions
  Annotation options.
Returns DocumentBuilder
- This document builder instance.
addAnnotationTo(
    staffTargets: StaffTargets,
    kind: string,
    options?: AnnotationOptions,
): DocumentBuilder
Add any annotation kind to current measure.
Parameters
- staffTargets: StaffTargets
  Single or multiple staff/tab/group identifiers.
- kind: string
  Annotation kind (e.g. "pp").
- Optionaloptions: AnnotationOptions
  Annotation options.
Returns DocumentBuilder
- This document builder instance.

addAnnotationTo(
staffTargets: StaffTargets,
...args: (string | number | AnnotationOptions)[],
): DocumentBuilder

Catch all overload for deprecated stuff. Wil be removed in future release.

// Deprecated:
addAnnotation(staffTargets, group: AnnotationGroup, kind: string, options?: AnnotationOptions): DocumentBuilder;
// Use instead:
addAnnotation(staffTargets, kind: string, { group: AnnotationGroup }): DocumentBuilder;

// Deprecated:
addAnnotation(staffTargets, "ending", ...endingPassages: number[]): DocumentBuilder;
// Use instead:
addAnnotation(staffTargets, "ending", { endingPassages: number | number[] }): DocumentBuilder;

// Deprecated:
addAnnotation(staffTargets, "endRepeat", repeatCount?: number): DocumentBuilder;
// Use instead:
addAnnotation(staffTargets, "endRepeat", { repeatCount: number }): DocumentBuilder;

Parameters

staffTargets: StaffTargets
...args: (string | number | AnnotationOptions)[]

Returns DocumentBuilder

Deprecated

Use AnnotationOptions instead for extra args. Will be removed in future release.

addChord

addChord(
    voiceId: VoiceId,
    notes: (string | Note)[],
    noteLength: NoteLengthValue,
    noteOptions?: NoteOptions,
): DocumentBuilder
Add chord to current measure.
Parameters
- voiceId: VoiceId
  Voice id to add chord to.
- notes: (string | Note)[]
  Array of notes, each instance of Theory.Note or string (e.g. "D4").
- noteLength: NoteLengthValue
  Theory.Note length (e.g. "4n").
- OptionalnoteOptions: NoteOptions
  Theory.Note options.
Returns DocumentBuilder
- This document builder instance.

addConnective

addConnective(
    connective: ConnectiveTieValue,
    tieSpan?: number | TieTypeValue,
    notAnchor?: NoteAnchorValue,
): DocumentBuilder
Add tie starting from last added note/chord.
Parameters
- connective: ConnectiveTieValue
  T.Connective type ("tie" or T.Connective.Tie).
- OptionaltieSpan: number | TieTypeValue
  How many notes across this tie spans.
- OptionalnotAnchor: NoteAnchorValue
  Anchor point for note and this tie.
Returns DocumentBuilder
- This document builder instance.
addConnective(
    connective: ConnectiveSlurValue,
    slurSpan?: number,
    notAnchor?: NoteAnchorValue,
): DocumentBuilder
Add slur starting from last added note/chord.
Parameters
- connective: ConnectiveSlurValue
  T.Connective type ("slur" or T.Connective.Slur).
- OptionalslurSpan: number
  How many notes across this slur spans.
- OptionalnotAnchor: NoteAnchorValue
  Anchor point for note and this slur.
Returns DocumentBuilder
- This document builder instance.
addConnective(
connective: ConnectiveSlideValue,
notAnchor?: NoteAnchorValue,
): DocumentBuilder
Add slide starting from last added note/chord.
Parameters
- connective: ConnectiveSlideValue
  T.Connective type ("slide" or T.Connective.Slide).
- OptionalnotAnchor: NoteAnchorValue
  Anchor point for note and this slide.
Returns DocumentBuilder
- This document builder instance.

addExtension

addExtension(
extensionBuilder?: (ext: ExtensionBuilder) => void,
): DocumentBuilder

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.

addFermata

addFermata(fermata?: FermataValue): DocumentBuilder
Add fermata to current measure.
Parameters
- fermata: FermataValue = Types.Fermata.AtNote
  Fermata position: "atNote" (default) or "atMeasureEnd".
Returns DocumentBuilder
- This document builder instance.
Deprecated
addFermata() is deprecated. Will be removed in future release. Use addAnnotation() instead.

addFermataTo

addFermataTo(
staffTargets: StaffTargets,
fermata?: FermataValue,
): DocumentBuilder
Add fermata to current measure.
Parameters
- staffTargets: StaffTargets
  Single or multiple staff/tab/group identifiers.
- fermata: FermataValue = Types.Fermata.AtNote
  Fermata position: "atNote" (default) or "atMeasureEnd".
Returns DocumentBuilder
- This document builder instance.
Deprecated
addFermataTo() is deprecated. Will be removed in future release. Use addAnnotation() instead.

addLabel

addLabel(label: LabelValue, text: string): DocumentBuilder
Add label text to column of last added note/chord/rest in current measure.
Parameters
- label: LabelValue
  T.Label type: "chord" or "note".
- text: string
  label text.
Returns DocumentBuilder
- This document builder instance.
Deprecated
addLabel() is deprecated. Will be removed in future release. Use addAnnotation() instead.

addLabelTo

addLabelTo(
    staffTargets: StaffTargets,
    label: LabelValue,
    text: string,
): DocumentBuilder
Add label text to column of last added note/chord/rest in current measure to given staff/tab/group.
Parameters
- staffTargets: StaffTargets
  Single or multiple staff/tab/group identifiers.
- label: LabelValue
  T.Label type "chord" or "note".
- text: string
  label text.
Returns DocumentBuilder
- This document builder instance.
Deprecated
addLabelTo() is deprecated. Will be removed in future release. Use addAnnotation() instead.

addLyrics

addLyrics(
    verse: VerseNumber,
    lyricsText: string | string[],
    lyricsLength: NoteLengthValue,
    lyricsOptions?: LyricsOptions,
): DocumentBuilder
Add lyrics to current measure.
Parameters
- verse: VerseNumber
  Verse number (e.g. 1).
- lyricsText: string | string[]
  Lyrics text (empty space if omitted), single value or array.
- lyricsLength: NoteLengthValue
  Lyrics text length (e.g. "2n").
- OptionallyricsOptions: LyricsOptions
  Lyrics options.
Returns DocumentBuilder
- This document builder instance.

addLyricsTo

addLyricsTo(
    staffTargets: StaffTargets,
    verse: VerseNumber,
    lyricsText: string | string[],
    lyricsLength: NoteLengthValue,
    lyricsOptions?: LyricsOptions,
): DocumentBuilder
Add lyrics to current measure to given staff/tab/group.
Parameters
- staffTargets: StaffTargets
  Single or multiple staff/tab/group identifiers.
- verse: VerseNumber
  Verse number (e.g. 1).
- lyricsText: string | string[]
  Lyrics text (empty space if omitted), single value or array.
- lyricsLength: NoteLengthValue
  Lyrics text length (e.g. "2n").
- OptionallyricsOptions: LyricsOptions
  Lyrics options.
Returns DocumentBuilder
- This document builder instance.

addMeasure

addMeasure(measureOptions?: MeasureOptions): DocumentBuilder
Add new measure.
Parameters
- OptionalmeasureOptions: MeasureOptions
  Measure options.
Returns DocumentBuilder
- This document builder instance.

addNavigation

addNavigation(navigation: NavigationValue): DocumentBuilder
Add navigation to current measure.
Parameters
- navigation: NavigationValue
  Navigation annotation to add.
Returns DocumentBuilder
- This document builder instance.
addNavigation(
navigation: NavigationEndRepeatValue,
playCount: number,
): DocumentBuilder
Add end repeat navigation to current measure.
Parameters
- navigation: NavigationEndRepeatValue
  Navigation annotation to add.
- playCount: number
  Play count for the repeated section.
Returns DocumentBuilder
- This document builder instance.
addNavigation(
navigation: NavigationEndingValue,
...passages: number[],
): DocumentBuilder
Add ending navigation to current measure.
Parameters
- navigation: NavigationEndingValue
  Navigation annotation to add.
- ...passages: number[]
  Passages that this ending is played.
Returns DocumentBuilder
- This document builder instance.

addNavigationTo

addNavigationTo(
staffTargets: StaffTargets,
navigation: NavigationValue,
): DocumentBuilder
Add navigation to current measure to given staff/tab/group.
Parameters
- staffTargets: StaffTargets
  Single or multiple staff/tab/group identifiers.
- navigation: NavigationValue
  Navigation annotation to add.
Returns DocumentBuilder
- This document builder instance.
addNavigationTo(
    staffTargets: StaffTargets,
    navigation: NavigationEndRepeatValue,
    playCount: number,
): DocumentBuilder
Add end repeat navigation to current measure to given staff/tab/group.
Parameters
- staffTargets: StaffTargets
  Single or multiple staff/tab/group identifiers.
- navigation: NavigationEndRepeatValue
  Navigation annotation to add.
- playCount: number
  Play count for the repeated section.
Returns DocumentBuilder
- This document builder instance.
addNavigationTo(
    staffTargets: StaffTargets,
    navigation: NavigationEndingValue,
    ...passages: number[],
): DocumentBuilder
Add ending navigation to current measure to given staff/tab/group.
Parameters
- staffTargets: StaffTargets
  Single or multiple staff/tab/group identifiers.
- navigation: NavigationEndingValue
  Navigation annotation to add.
- ...passages: number[]
  Passages that this ending is played.
Returns DocumentBuilder
- This document builder instance.

addNote

addNote(
    voiceId: VoiceId,
    note: string | Note | (string | Note)[],
    noteLength: NoteLengthValue,
    noteOptions?: NoteOptions,
): DocumentBuilder
Add note to current measure.
Parameters
- voiceId: VoiceId
  Voice id to add note to.
- note: string | Note | (string | Note)[]
  Instance of Theory.Note or string, single value (e.g. "C4") or array (e.g. ["C4", "E4", "G4"]).
- noteLength: NoteLengthValue
  Theory.Note length (e.g. "4n").
- OptionalnoteOptions: NoteOptions
  Theory.Note options.
Returns DocumentBuilder
- This document builder instance.

addRest

addRest(
    voiceId: VoiceId,
    restLength: NoteLengthValue,
    restOptions?: RestOptions,
): DocumentBuilder
Add rest to current measure.
Parameters
- voiceId: VoiceId
  Voice id to add rest to.
- restLength: NoteLengthValue
  Rest length (e.g. "4n").
- OptionalrestOptions: RestOptions
  Rest options.
Returns DocumentBuilder
- This document builder instance.

addScaleArpeggio

addScaleArpeggio(
    scale: Scale,
    bottomNote: string,
    numOctaves: number,
): DocumentBuilder
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.

addStaffGroup

addStaffGroup(
    groupName: string,
    staffsTabsAndGroups: string | number | (string | number)[],
    verticalPosition?: VerticalPositionValue,
): DocumentBuilder
Add staff group.
Parameters
- groupName: string
  Name of staff group.
- staffsTabsAndGroups: string | number | (string | number)[]
  Single or multiple staff/tab/group identifiers. Single value or array.
- verticalPosition: VerticalPositionValue = Types.VerticalPosition.Auto
  Vertical position, are elements added above, below or both.
Returns DocumentBuilder
- This document builder instance.

addTuplet

addTuplet(
    voiceId: VoiceId,
    tupletRatio: TupletRatio & TupletOptions,
    tupletBuilder: (notes: TupletBuilder) => void,
): DocumentBuilder
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.

endRow

endRow(): DocumentBuilder
End current score row. Next measure will start new row.

Returns DocumentBuilder
- This document builder instance.

endSection

endSection(): DocumentBuilder
Add section end. Adds certain bar line at the end of measure.

Returns DocumentBuilder
- This document builder instance.

endSong

endSong(): DocumentBuilder
Add song end. Adds certain bar line at the end of measure.

Returns DocumentBuilder
- This document builder instance.

fillWithRests

fillWithRests(...voiceId: VoiceId[]): DocumentBuilder
Fill current measure with rests.
Parameters
- ...voiceId: VoiceId[]
  Voice id to add rests to. Single value, array or all if omitted.
Returns DocumentBuilder
- This document builder instance.

getDocument

getDocument(): MDocument
Get music document after finished building.

Returns MDocument
- Music document.

repeat

repeat(
times: number,
repeatCreator: (builder: DocumentBuilder) => void,
): DocumentBuilder
Add and repeat builder section.
Parameters
- times: number
  Repeat count.
- repeatCreator: (builder: DocumentBuilder) => void
  Repeat creator function.
Returns DocumentBuilder
- This document builder instance.

setErrorHandler

setErrorHandler(fn: (e: unknown) => void): DocumentBuilder

Usage examples:

// throw (default)
builder.setErrorHandler((e) => { throw e; });
// log
builder.setErrorHandler((e) => { console.error("Doc build failed:", e); });
// log and throw
builder.setErrorHandler((e) => { console.error("Doc build failed:", e); throw e; });
// Silent
builder.setErrorHandler((e) => { });

Parameters

fn: (e: unknown) => void
Error handler function.

Returns DocumentBuilder

setHeader

setHeader(title?: string, composer?: string, arranger?: string): DocumentBuilder
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.

setKeySignature

setKeySignature(tonic: string, scaleType: ScaleTypeValue): DocumentBuilder
Set key signature for current measure and forward.
Parameters
- tonic: string
  Tonic note (e.g. "C").
- scaleType: ScaleTypeValue
  Scale type (e.g. string "Major" or ScaleType.Major).
Returns DocumentBuilder
- This document builder instance.
setKeySignature(keySignature: KeySignature): DocumentBuilder
Set key signature for current measure and forward.
Parameters
- keySignature: KeySignature
  KeySignature object instance.
Returns DocumentBuilder
- This document builder instance.
setKeySignature(keySignature: string): DocumentBuilder
Set key signature for current measure and forward.
Parameters
- keySignature: string
  Key signature string (e.g. "C Major").
Returns DocumentBuilder
- This document builder instance.
setKeySignature(scale: Scale): DocumentBuilder
Set key signature for current measure and forward.
Parameters
- scale: Scale
  Scale object instance.
Returns DocumentBuilder
- This document builder instance.

setMeasuresPerRow

setMeasuresPerRow(measuresPerRow: number): DocumentBuilder
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.

setScoreConfiguration

setScoreConfiguration(staffPreset: StaffPresetValue): DocumentBuilder
Use staff preset values to set score confguration. This call will request new score row.
Parameters
- staffPreset: StaffPresetValue
  Staff preset (e.g. "treble").
Returns DocumentBuilder
setScoreConfiguration(config: ScoreConfiguration): 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

setTempo

setTempo(beatsPerMinute: number): DocumentBuilder
Set tempo.
Parameters
- beatsPerMinute: number
  Tempo beats per minute.
Returns DocumentBuilder
- This document builder instance.
setTempo(beatsPerMinute: number, beatLength: NoteLengthValue): DocumentBuilder
Set tempo.
Parameters
- beatsPerMinute: number
  Tempo beats per minute.
- beatLength: NoteLengthValue
  Length of one beat.
Returns DocumentBuilder
- This document builder instance.

setTimeSignature

setTimeSignature(timeSignature: "C" | "C|"): DocumentBuilder
Set common or cut time signature for current measure and forward.
Parameters
- timeSignature: "C" | "C|"
  "C" or "C|".
Returns DocumentBuilder
- This document builder instance.
setTimeSignature(timeSignature: TimeSignature): DocumentBuilder
Set time signature for current measure and forward.
Parameters
- timeSignature: TimeSignature
  TimeSignature object instance.
Returns DocumentBuilder
- This document builder instance.
setTimeSignature(
timeSignature: TimeSignaturesValue,
beamGrouping?: BeamGroupingValue,
): DocumentBuilder
Set time signature for current measure and forward.
Parameters
- timeSignature: TimeSignaturesValue
  TimeSignatures enum value or string (e.g. "3/4").
- OptionalbeamGrouping: BeamGroupingValue
  Beam grouping (e.g. "3-2" for time signature "5/8").
Returns DocumentBuilder
- This document builder instance.
setTimeSignature(
    beatCount: number,
    beatSize: number,
    beamGrouping?: BeamGroupingValue,
): DocumentBuilder
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: BeamGroupingValue
  Beam grouping (e.g. "3-2" for time signature "5/8").
Returns DocumentBuilder
- This document builder instance.

Class DocumentBuilder

Index

Constructors

Methods

Constructors

constructor

Parameters

Returns DocumentBuilder

Methods

addAnnotation

Parameters

Returns DocumentBuilder

Parameters

Returns DocumentBuilder

Parameters

Returns DocumentBuilder

Deprecated

addAnnotationTo

Parameters

Returns DocumentBuilder

Parameters

Returns DocumentBuilder

Parameters

Returns DocumentBuilder

Deprecated

addChord

Parameters

Returns DocumentBuilder

addConnective

Parameters

Returns DocumentBuilder

Parameters

Returns DocumentBuilder

Parameters

Returns DocumentBuilder

addExtension

Parameters

Returns DocumentBuilder

addFermata

Parameters

Returns DocumentBuilder

Deprecated

addFermataTo

Parameters

Returns DocumentBuilder

Deprecated

addLabel

Parameters

Returns DocumentBuilder

Deprecated

addLabelTo

Parameters

Returns DocumentBuilder

Deprecated

addLyrics

Parameters

Returns DocumentBuilder

addLyricsTo

Parameters

Returns DocumentBuilder

addMeasure

Parameters

Returns DocumentBuilder

addNavigation

Parameters

Returns DocumentBuilder

Parameters

Returns DocumentBuilder

Parameters

Returns DocumentBuilder

addNavigationTo

Parameters

Returns DocumentBuilder

Parameters

Returns DocumentBuilder

Parameters

Returns DocumentBuilder

addNote

Parameters

Returns DocumentBuilder