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

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

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