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("pp")
    .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(
kind: AnnotationKindValue,
options?: AnnotationOptions,
): DocumentBuilder
Add annotation to current measure.
Parameters
- kind: AnnotationKindValue
  Annotation kind (e.g. "pp").
- Optionaloptions: AnnotationOptions
  Annotation options.
Returns DocumentBuilder
- This document builder instance.
addAnnotation(
    kind: string,
    group: AnnotationGroupValue,
    options?: AnnotationOptions,
): DocumentBuilder
Add annotation to current measure.
Parameters
- kind: string
  Annotation kind (e.g. "pp").
- group: AnnotationGroupValue
  Annotation group (e.g. "dynamics").
- Optionaloptions: AnnotationOptions
  Annotation options.
Returns DocumentBuilder
- This document builder instance.

addAnnotationTo

addAnnotationTo(
    staffTargets: StaffTargets,
    kind: AnnotationKindValue,
    options?: AnnotationOptions,
): DocumentBuilder
Add annotation to current measure.
Parameters
- staffTargets: StaffTargets
  Single or multiple staff/tab/group identifiers.
- kind: AnnotationKindValue
  Annotation kind (e.g. "pp").
- Optionaloptions: AnnotationOptions
  Annotation options.
Returns DocumentBuilder
- This document builder instance.
addAnnotationTo(
    staffTargets: StaffTargets,
    kind: string,
    group: AnnotationGroupValue,
    options?: AnnotationOptions,
): DocumentBuilder
Add annotation to current measure.
Parameters
- staffTargets: StaffTargets
  Single or multiple staff/tab/group identifiers.
- kind: string
  Annotation kind (e.g. "pp").
- group: AnnotationGroupValue
  Annotation group (e.g. "dynamics").
- Optionaloptions: AnnotationOptions
  Annotation options.
Returns DocumentBuilder
- This document builder instance.

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,
    options?: ConnectiveOptions,
): 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.
- Optionaloptions: ConnectiveOptions
  Optional values.
Returns DocumentBuilder
- This document builder instance.
addConnective(
    connective: ConnectiveSlurValue,
    slurSpan?: number,
    notAnchor?: NoteAnchorValue,
    options?: ConnectiveOptions,
): 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.
- Optionaloptions: ConnectiveOptions
  Optional values.
Returns DocumentBuilder
- This document builder instance.
addConnective(
    connective: ConnectiveSlideValue,
    notAnchor?: NoteAnchorValue,
    options?: ConnectiveOptions,
): 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.
- Optionaloptions: ConnectiveOptions
  Optional values.
Returns DocumentBuilder
- This document builder instance.

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.

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,
    pitchLabelTarget?: StaffTarget,
): 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.
- OptionalpitchLabelTarget: StaffTarget
Returns DocumentBuilder
- This document builder instance.

addSpan

addSpan(
    kind: AnnotationKindValue,
    span: (span: SpanBuilder) => void,
    options?: AnnotationOptions,
): DocumentBuilder
Add annotation with span to current measure.
Parameters
- kind: AnnotationKindValue
  Annotation kind (e.g. "pp").
- span: (span: SpanBuilder) => void
  Span builder (e.g. span => span.measures(2)).
- Optionaloptions: AnnotationOptions
  Annotation options.
Returns DocumentBuilder
- This document builder instance.
addSpan(
    kind: string,
    group: AnnotationGroupValue,
    span: (span: SpanBuilder) => void,
    options?: AnnotationOptions,
): DocumentBuilder
Add annotation with span to current measure.
Parameters
- kind: string
  Annotation kind (e.g. "pp").
- group: AnnotationGroupValue
  Annotation group (e.g. "dynamics").
- span: (span: SpanBuilder) => void
  Span builder (e.g. span => span.measures(2)).
- Optionaloptions: AnnotationOptions
  Annotation options.
Returns DocumentBuilder
- This document builder instance.

addSpanTo

addSpanTo(
    staffTargets: StaffTargets,
    kind: AnnotationKindValue,
    span: (span: SpanBuilder) => void,
    options?: AnnotationOptions,
): DocumentBuilder
Add annotation with span to current measure.
Parameters
- staffTargets: StaffTargets
  Single or multiple staff/tab/group identifiers.
- kind: AnnotationKindValue
  Annotation kind (e.g. "pp").
- span: (span: SpanBuilder) => void
  Span builder (e.g. span => span.measures(2)).
- Optionaloptions: AnnotationOptions
  Annotation options.
Returns DocumentBuilder
- This document builder instance.
addSpanTo(
    staffTargets: StaffTargets,
    kind: string,
    group: AnnotationGroupValue,
    span: (span: SpanBuilder) => void,
    options?: AnnotationOptions,
): DocumentBuilder
Add annotation with span to current measure.
Parameters
- staffTargets: StaffTargets
  Single or multiple staff/tab/group identifiers.
- kind: string
  Annotation kind (e.g. "pp").
- group: AnnotationGroupValue
  Annotation group (e.g. "dynamics").
- span: (span: SpanBuilder) => void
  Span builder (e.g. span => span.measures(2)).
- Optionaloptions: AnnotationOptions
  Annotation options.
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.

setInstrument

setInstrument(
voiceId: VoiceId | VoiceId[],
instrument: InstrumentValue,
): DocumentBuilder
Set instrument to use for playback for given voiceId(s).
Parameters
- voiceId: VoiceId | VoiceId[]
  Voice id or array.
- instrument: InstrumentValue
  Instrument name (string) or midi program (number).
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

addAnnotationTo

Parameters

Returns DocumentBuilder

Parameters

Returns DocumentBuilder

addChord

Parameters

Returns DocumentBuilder

addConnective

Parameters

Returns DocumentBuilder

Parameters

Returns DocumentBuilder

Parameters

Returns DocumentBuilder

addLyrics

Parameters

Returns DocumentBuilder

addLyricsTo

Parameters

Returns DocumentBuilder

addMeasure

Parameters

Returns DocumentBuilder

addNote

Parameters

Returns DocumentBuilder

addRest

Parameters

Returns DocumentBuilder

addScaleArpeggio

Parameters

Returns DocumentBuilder

addSpan

Parameters

Returns DocumentBuilder

Parameters

Returns DocumentBuilder

addSpanTo

Parameters

Returns DocumentBuilder

Parameters

Returns DocumentBuilder

addStaffGroup

Parameters

Returns DocumentBuilder

addTuplet

Parameters

Returns DocumentBuilder

endRow

Returns DocumentBuilder

endSection

Returns DocumentBuilder

endSong

Returns DocumentBuilder

fillWithRests

Parameters

Returns DocumentBuilder

getDocument

Returns MDocument

repeat

Parameters

Returns DocumentBuilder

setErrorHandler

Parameters

Returns DocumentBuilder