Class Song

constructor

• new Song(metadata?: Record<string, string | string[]> | Metadata | null): Song

  Creates a new {Song} instance

  Parameters

  • metadata: Record<string, string | string[]> | Metadata | null = null

    {Record<string, string | string[]>|Metadata} predefined metadata

  Returns Song

lines

bodyLines

• get bodyLines(): Line[]

  Returns song lines, skipping leading empty/meta-only lines.

  Returns Line[]

bodyParagraphs

• get bodyParagraphs(): Paragraph[]

  Returns song paragraphs, skipping paragraphs with only empty lines.

  Returns Paragraph[]

expandedBodyParagraphs

• get expandedBodyParagraphs(): Paragraph[]

  The body paragraphs with any {chorus} tag expanded into the targeted chorus

  Returns Paragraph[]

metadata

• get metadata(): Metadata

  The song's metadata. When there is only one value for an entry, the value is a string. Else, the value is an array containing all unique values for the entry.

  Returns Metadata

paragraphs

• get paragraphs(): Paragraph[]

  The Paragraph items of which the song consists

  Returns Paragraph[]

  Member

renderParagraphs

• get renderParagraphs(): Paragraph[]

  Returns Paragraph[]

  Deprecated

  No longer used internally; use bodyParagraphs or expandedBodyParagraphs.

• set renderParagraphs(paragraphs: Paragraph[]): void

  Parameters

  • paragraphs: Paragraph[]

  Returns void

  Deprecated

  No longer used internally. See renderParagraphs.

changeKey

• changeKey(newKey: string | Key): Song

  Returns a copy of the song with the key set to the specified key. It changes:

  • the value for key in the metadata set
  • any existing key directive
  • all chords, those are transposed according to the distance between the current and the new key

  Parameters

  • newKey: string | Key

    The new key.

  Returns Song

  The changed song

changeMetadata

• changeMetadata(name: string, value: string | string[] | null): Song

  Returns a copy of the song with the directive value(s) set to the specified value(s).

  • when there is a matching directive in the song, it will update the directive
  • when there is no matching directive, it will be inserted If value is null it will act as a delete, any directive matching name will be removed.

  Parameters

  • name: string

    The directive name

  • value: string | string[] | null

    The value to set, or null to remove the directive

  Returns Song

  The changed song

  Example

  song.changeMetadata('author', 'John');
  song.changeMetadata('composer', ['Jane', 'John']);
  song.changeMetadata('key', null); // Remove key directive
  Copy

• changeMetadata(metadata: Record<string, string | string[] | null>): Song

  Returns a copy of the song with the metadata changed. It will:

  • update the metadata
  • update any existing directive matching the metadata key
  • insert a new directive if it does not exist

  Parameters

  • metadata: Record<string, string | string[] | null>

    The metadata to change

  Returns Song

  Example

  song.changeMetadata({
    author: 'John',
    composer: ['Jane', 'John'],
    key: null, // Remove key directive
  });
  Copy

clone

• clone(): Song

  Returns a deep clone of the song

  Returns Song

decapo

• decapo(): Song

  Returns a copy of the song with the capo eliminated, like ChordPro's decapo setting. It changes:

  • all chords, those are transposed up by the capo amount so they sound the same without a capo
  • the song key in metadata and any existing key directive, to the sounding key
  • the value for capo in metadata and any existing capo directive, which are removed

  The song is returned unchanged when it has no usable capo, or when any of its keys cannot be parsed.

  Returns Song

  The changed song

getChordDefinitions

• getChordDefinitions(
      context?: FormattingContext,
  ): Record<string, ChordDefinition>

  Returns all chord definitions from the song. Definitions are made using the {chord} or {define} directive. A chord definitions overrides a previous chord definition for the exact same chord.

  Parameters

  • Optionalcontext: FormattingContext

  Returns Record<string, ChordDefinition>

  the chord definitions

  See

  • https://chordpro.org/chordpro/directives-define/
  • https://chordpro.org/chordpro/directives-chord/

getChords

• getChords(): string[]

  Returns all unique chords used in the song

  Returns string[]

  the chords

mapItems

• mapItems(func: MapItemsCallback): Song

  Change the song contents inline. Return a new Item to replace it. Return null to remove it.

  Parameters

  • func: MapItemsCallback

    the callback function

  Returns Song

  the changed song

  Example

  // transpose all chords:
  song.mapItems((item) => {
    if (item instanceof ChordLyricsPair) {
      return item.transpose(2, 'D');
    }
  
    return item;
  });
  Copy

mapLines

• mapLines(func: (_line: Line) => Line | null): Song

  Change the song contents inline. Return a new Line to replace it. Return null to remove it.

  Parameters

  • func: (_line: Line) => Line | null

    the callback function

  Returns Song

  the changed song

  Example

  // remove lines with only Tags:
  song.mapLines((line) => {
    if (line.items.every(item => item instanceof Tag)) {
      return null;
    }
  
    return line;
  });
  Copy

normalizeChords

• normalizeChords(
      key?: string | Key | null,
      options?: { normalizeSuffix?: boolean },
  ): Song

  Returns a copy of the song with all chords normalized to the specified key. See Chord#normalize.

  Parameters

  • key: string | Key | null = null

    the key to normalize to

  • options: { normalizeSuffix?: boolean } = {}

    options

    • OptionalnormalizeSuffix?: boolean

      whether to normalize the chord suffixes

  Returns Song

setCapo

• setCapo(capo: number | null): Song

  Returns a copy of the song with the key value set to the specified capo. It changes:

  • the value for capo in the metadata set
  • any existing capo directive

  Parameters

  • capo: number | null

    the capo. Passing null will:

    • remove the current key from metadata
    • remove any capo directive

  Returns Song

  The changed song

setKey

• setKey(key: string | number | null): Song

  Returns a copy of the song with the key value set to the specified key. It changes:

  • the value for key in the metadata set
  • any existing key directive

  Parameters

  • key: string | number | null

    the key. Passing null will:

    • remove the current key from metadata
    • remove any key directive

  Returns Song

  The changed song

transpose

• transpose(
      delta: number,
      options?: {
          accidental?: Accidental | null;
          normalizeChordSuffix?: boolean;
      },
  ): Song

  Transposes the song by the specified delta. It will:

  • transpose all chords, see: Chord#transpose
  • transpose the song key in metadata
  • update any existing key directive

  Parameters

  • delta: number

    The number of semitones (positive or negative) to transpose with

  • Optionaloptions: { accidental?: Accidental | null; normalizeChordSuffix?: boolean } = {}

    options

    • Optionalaccidental?: Accidental | null

    • OptionalnormalizeChordSuffix?: boolean

      whether to normalize the chord suffixes after transposing

  Returns Song

  The transposed song

transposeDown

• transposeDown(options?: { normalizeChordSuffix?: boolean }): Song

  Transposes the song down by one semitone. It will:

  • transpose all chords, see: Chord#transpose
  • transpose the song key in metadata
  • update any existing key directive

  Parameters

  • Optionaloptions: { normalizeChordSuffix?: boolean } = {}

    options

    • OptionalnormalizeChordSuffix?: boolean

      whether to normalize the chord suffixes after transposing

  Returns Song

  The transposed song

transposeUp

• transposeUp(options?: { normalizeChordSuffix?: boolean }): Song

  Transposes the song up by one semitone. It will:

  • transpose all chords, see: Chord#transpose
  • transpose the song key in metadata
  • update any existing key directive

  Parameters

  • Optionaloptions: { normalizeChordSuffix?: boolean } = {}

    options

    • OptionalnormalizeChordSuffix?: boolean

      whether to normalize the chord suffixes after transposing

  Returns Song

  The transposed song

useAccidental

• useAccidental(accidental: Accidental): Song

  Returns a copy of the song with all chords changed to the specified accidental.

  Examples:

  song.useAccidental('#');
  song.useAccidental('b');
  Copy

  Parameters

  • accidental: Accidental

    the new accidental

  Returns Song

  the changed song

useModifier

• useModifier(accidental: Accidental): Song

  Parameters

  • accidental: Accidental

  Returns Song

  Deprecated

  Use useAccidental instead