Class Song

constructor

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

  Creates a new {Song} instance

  Parameters

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

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

  Returns Song

lines

bodyLines

• get bodyLines(): Line[]

  Returns the song lines, skipping the leading empty lines (empty as in not rendering any content). This is useful if you want to skip the "header lines": the lines that only contain meta data.

  Returns Line[]

  The song body lines

bodyParagraphs

• get bodyParagraphs(): Paragraph[]

  Returns the song paragraphs, skipping the paragraphs that only contain empty lines (empty as in not rendering any content)

  Returns Paragraph[]

  See

  bodyLines

expandedBodyParagraphs

• get expandedBodyParagraphs(): Paragraph[]

  The body paragraphs of the song, 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: null | string | string[]): Song

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

  • 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: null | string | string[]

    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

  The changed 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

  The cloned 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) => null | Line): Song

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

  Parameters

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

    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?: null | string | Key,
      options?: { normalizeSuffix?: boolean },
  ): Song

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

  Parameters

  • key: null | string | Key = null

    the key to normalize to
  • options: { normalizeSuffix?: boolean } = {}

    options

    • OptionalnormalizeSuffix?: boolean

      whether to normalize the chord suffixes

  Returns Song

setCapo

• setCapo(capo: null | number): 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: null | number

    the capo. Passing null will:

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

  Returns Song

  The changed song

setKey

• setKey(key: null | string | number): 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: null | string | number

    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?: { modifier?: null | Modifier; 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: { modifier?: null | Modifier; normalizeChordSuffix?: boolean } = {}

    options

    • Optionalmodifier?: null | Modifier

    • 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

useModifier

• useModifier(modifier: Modifier): Song

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

  Examples:

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

  Parameters

  • modifier: Modifier

    the new modifier

  Returns Song

  the changed song