ChordSheetJS

A JavaScript library for parsing and formatting chord sheets

Contents

• Installation
• How to ...?
• Supported ChordPro directives
• API docs

Installation

ChordSheetJS is on npm, to install run:

npm install chordsheetjs

Load with import:

import ChordSheetJS from 'chordsheetjs';

or require():

var ChordSheetJS = require('chordsheetjs').default;

How to ...?

Parse chord sheet

Regular chord sheets

const chordSheet = `
       Am         C/G        F          C
Let it be, let it be, let it be, let it be
C                G              F  C/E Dm C
Whisper words of wisdom, let it be`.substring(1);

const parser = new ChordSheetJS.ChordSheetParser();
const song = parser.parse(chordSheet);

Ultimate Guitar chord sheets

const chordSheet = `
[Chorus]
       Am         C/G        F          C
Let it be, let it be, let it be, let it be
C                G              F  C/E Dm C
Whisper words of wisdom, let it be`.substring(1);

const parser = new ChordSheetJS.UltimateGuitarParser();
const song = parser.parse(chordSheet);

Chord pro format

const chordSheet = `
{title: Let it be}
{subtitle: ChordSheetJS example version}
{Chorus}

Let it [Am]be, let it [C/G]be, let it [F]be, let it [C]be
[C]Whisper words of [G]wisdom, let it [F]be [C/E] [Dm] [C]`.substring(1);

const parser = new ChordSheetJS.ChordProParser();
const song = parser.parse(chordSheet);

Display a parsed sheet

Plain text format

const formatter = new ChordSheetJS.TextFormatter();
const disp = formatter.format(song);

HTML format

Table-based layout

const formatter = new ChordSheetJS.HtmlTableFormatter();
const disp = formatter.format(song);

Div-based layout

const formatter = new ChordSheetJS.HtmlDivFormatter();
const disp = formatter.format(song);

Chord pro format

const formatter = new ChordSheetJS.ChordProFormatter();
const disp = formatter.format(song);

Supported ChordPro directives

✔️ = supported

🕑 = will be supported in a future version

✖️ = currently no plans to support it in the near future

Meta-data directives

Formatting directives

Environment directives

Chord diagrams

Fonts, sizes and colours

Output related directives

Custom extensions

API docs

Note: all classes, methods and constants that are documented here can be considered public API and will only be subject to breaking changes between major versions.

Classes

ChordLyricsPair

Represents a chord with the corresponding (partial) lyrics

Comment

Represents a comment. See https://www.chordpro.org/chordpro/chordpro-file-format-specification/#overview

Line

Represents a line in a chord sheet, consisting of items of type ChordLyricsPair or Tag

Metadata

Stores song metadata. Properties can be accessed using the get() method:

const metadata = new Metadata({ author: 'John' }); metadata.get('author') // => 'John'

See get

Paragraph

Represents a paragraph of lines in a chord sheet

Song

Represents a song in a chord sheet. Currently a chord sheet can only have one song.

Tag

Represents a tag/directive. See https://www.chordpro.org/chordpro/chordpro-directives/

ChordProFormatter

Formats a song into a ChordPro chord sheet

HtmlDivFormatter

Formats a song into HTML. It uses DIVs to align lyrics with chords, which makes it useful for responsive web pages.

HtmlFormatter

Acts as a base class for HTML formatters, taking care of whitelisting prototype property access.

HtmlTableFormatter

Formats a song into HTML. It uses TABLEs to align lyrics with chords, which makes the HTML for things like PDF conversion.

TextFormatter

Formats a sonf into a plain text chord sheet

ChordProParser

Parses a ChordPro chord sheet

ChordSheetParser

Parses a normal chord sheet

ParserWarning

Represents a parser warning, currently only used by ChordProParser.

UltimateGuitarParser

Parses an Ultimate Guitar chord sheet with metadata Inherits from ChordSheetParser

Constants

ALBUM : string

Album meta directive. See https://www.chordpro.org/chordpro/directives-album/

ARTIST : string

Artist meta directive. See https://www.chordpro.org/chordpro/directives-artist/

CAPO : string

Capo meta directive. See https://www.chordpro.org/chordpro/directives-capo/

COMMENT : string

Comment directive. See https://www.chordpro.org/chordpro/directives-comment/

COMPOSER : string

Composer meta directive. See https://www.chordpro.org/chordpro/directives-composer/

COPYRIGHT : string

Copyright meta directive. See https://www.chordpro.org/chordpro/directives-copyright/

DURATION : string

Duration meta directive. See https://www.chordpro.org/chordpro/directives-duration/

END_OF_CHORUS : string

End of chorus directive. See https://www.chordpro.org/chordpro/directives-env_chorus/

END_OF_VERSE : string

End of verse directive. See https://www.chordpro.org/chordpro/directives-env_verse/

KEY : string

Key meta directive. See https://www.chordpro.org/chordpro/directives-key/

LYRICIST : string

Lyricist meta directive. See https://www.chordpro.org/chordpro/directives-lyricist/

START_OF_CHORUS : string

Start of chorus directive. See https://www.chordpro.org/chordpro/directives-env_chorus/

START_OF_VERSE : string

Start of verse directive. See https://www.chordpro.org/chordpro/directives-env_verse/

SUBTITLE : string

Subtitle meta directive. See https://www.chordpro.org/chordpro/directives-subtitle/

TEMPO : string

Tempo meta directive. See https://www.chordpro.org/chordpro/directives-tempo/

TIME : string

Time meta directive. See https://www.chordpro.org/chordpro/directives-time/

TITLE : string

Title meta directive. See https://www.chordpro.org/chordpro/directives-title/

YEAR : string

Year meta directive. See https://www.chordpro.org/chordpro/directives-year/

ChordLyricsPair

Represents a chord with the corresponding (partial) lyrics

Kind: global class

• ChordLyricsPair
  • new ChordLyricsPair(chords, lyrics)
  • .chords : string
  • .lyrics : string
  • .isRenderable() ⇒ boolean
  • .clone() ⇒ ChordLyricsPair

new ChordLyricsPair(chords, lyrics)

Initialises a ChordLyricsPair

chordLyricsPair.chords : string

The chords

Kind: instance property of ChordLyricsPair

chordLyricsPair.lyrics : string

The lyrics

Kind: instance property of ChordLyricsPair

chordLyricsPair.isRenderable() ⇒ boolean

Indicates whether a ChordLyricsPair should be visible in a formatted chord sheet (except for ChordPro sheets)

Kind: instance method of ChordLyricsPair

chordLyricsPair.clone() ⇒ ChordLyricsPair

Returns a deep copy of the ChordLyricsPair, useful when programmatically transforming a song

Kind: instance method of ChordLyricsPair

Comment

Represents a comment. See https://www.chordpro.org/chordpro/chordpro-file-format-specification/#overview

Kind: global class

• Comment
  • .isRenderable() ⇒ boolean
  • .clone() ⇒ Comment

comment.isRenderable() ⇒ boolean

Indicates whether a Comment should be visible in a formatted chord sheet (except for ChordPro sheets)

Kind: instance method of Comment

comment.clone() ⇒ Comment

Returns a deep copy of the Comment, useful when programmatically transforming a song

Kind: instance method of Comment

Line

Represents a line in a chord sheet, consisting of items of type ChordLyricsPair or Tag

Kind: global class

• Line
  • .items : Array.<(ChordLyricsPair|Tag|Comment)>
  • .type : string
  • .isEmpty() ⇒ boolean
  • .addItem(item)
  • .hasRenderableItems() ⇒ boolean
  • .clone() ⇒ Line
  • .isVerse() ⇒ boolean
  • .isChorus() ⇒ boolean
  • .hasContent() ⇒ boolean

line.items : Array.<(ChordLyricsPair|Tag|Comment)>

The items (ChordLyricsPair or Tag or Comment) of which the line consists

Kind: instance property of Line

line.type : string

The line type, This is set by the ChordProParser when it read tags like {start_of_chorus} or {start_of_verse} Values can be VERSE, CHORUS or NONE

Kind: instance property of Line

line.isEmpty() ⇒ boolean

Indicates whether the line contains any items

Kind: instance method of Line

line.addItem(item)

Adds an item (ChordLyricsPair or Tag) to the line

Kind: instance method of Line

line.hasRenderableItems() ⇒ boolean

Indicates whether the line contains items that are renderable

Kind: instance method of Line

line.clone() ⇒ Line

Returns a deep copy of the line and all of its items

Kind: instance method of Line

line.isVerse() ⇒ boolean

Indicates whether the line type is VERSE

Kind: instance method of Line

line.isChorus() ⇒ boolean

Indicates whether the line type is CHORUS

Kind: instance method of Line

line.hasContent() ⇒ boolean

Deprecated

Indicates whether the line contains items that are renderable. Please use hasRenderableItems

Kind: instance method of Line

Metadata

Stores song metadata. Properties can be accessed using the get() method:

const metadata = new Metadata({ author: 'John' }); metadata.get('author') // => 'John'

See get

Kind: global class

• Metadata
  • .get(prop) ⇒ Array.<String> | String
  • .clone() ⇒ Metadata

metadata.get(prop) ⇒ Array.<String> | String

Reads a metadata value by key. This method supports simple value lookup, as fetching single array values.

This method deprecates direct property access, eg: metadata['author']

Examples:

const metadata = new Metadata({ lyricist: 'Pete', author: ['John', 'Mary'] }); metadata.get('lyricist') // => 'Pete' metadata.get('author') // => ['John', 'Mary'] metadata.get('author.1') // => 'John' metadata.get('author.2') // => 'Mary'

Using a negative index will start counting at the end of the list:

const metadata = new Metadata({ lyricist: 'Pete', author: ['John', 'Mary'] }); metadata.get('author.-1') // => 'Mary' metadata.get('author.-2') // => 'John'

Kind: instance method of Metadata
Returns: Array.<String> | String - the metadata value(s). If there is only one value, it will return a String, else it returns an array of strings.

metadata.clone() ⇒ Metadata

Returns a deep clone of this Metadata object

Kind: instance method of Metadata
Returns: Metadata - the cloned Metadata object

Paragraph

Represents a paragraph of lines in a chord sheet

Kind: global class

• Paragraph
  • .lines : Array.<Line>
  • .type ⇒ string

paragraph.lines : Array.<Line>

The Line items of which the paragraph consists

Kind: instance property of Paragraph

paragraph.type ⇒ string

Tries to determine the common type for all lines. If the types for all lines are equal, it returns that type. If not, it returns INDETERMINATE

Kind: instance property of Paragraph

Song

Represents a song in a chord sheet. Currently a chord sheet can only have one song.

Kind: global class

• Song
  • new Song(metadata)
  • .lines : Array.<Line>
  • .paragraphs : Array.<Paragraph>
  • .metadata : Metadata
  • .bodyLines ⇒ Array.<Line>
  • .metaData ⇒
  • .clone() ⇒ Song

new Song(metadata)

Creates a new {Song} instance

song.lines : Array.<Line>

The Line items of which the song consists

Kind: instance property of Song

song.paragraphs : Array.<Paragraph>

The Paragraph items of which the song consists

Kind: instance property of Song

song.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.

Kind: instance property of Song

song.bodyLines ⇒ Array.<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.

Kind: instance property of Song
Returns: Array.<Line> - The song body lines

song.metaData ⇒

Deprecated

The song's metadata. Please use metadata instead.

Kind: instance property of Song
Returns: Metadata The metadata

song.clone() ⇒ Song

Returns a deep clone of the song

Kind: instance method of Song
Returns: Song - The cloned song

Tag

Represents a tag/directive. See https://www.chordpro.org/chordpro/chordpro-directives/

Kind: global class

• Tag
  • .name : string
  • .originalName : string
  • .value : string | null
  • .hasValue() ⇒ boolean
  • .isRenderable() ⇒ boolean
  • .isMetaTag() ⇒ boolean
  • .clone() ⇒ Tag

tag.name : string

The tag full name. When the original tag used the short name, name will return the full name.

Kind: instance property of Tag

tag.originalName : string

The original tag name that was used to construct the tag.

Kind: instance property of Tag

tag.value : string | null

The tag value

Kind: instance property of Tag

tag.hasValue() ⇒ boolean

Checks whether the tag value is a non-empty string.

Kind: instance method of Tag

tag.isRenderable() ⇒ boolean

Checks whether the tag is usually rendered inline. It currently only applies to comment tags.

Kind: instance method of Tag

tag.isMetaTag() ⇒ boolean

Checks whether the tag is either a standard meta tag or a custom meta directive ({x_some_name})

Kind: instance method of Tag

tag.clone() ⇒ Tag

Returns a clone of the tag.

Kind: instance method of Tag
Returns: Tag - The cloned tag

ChordProFormatter

Formats a song into a ChordPro chord sheet

Kind: global class

chordProFormatter.format(song) ⇒ string

Formats a song into a ChordPro chord sheet.

Kind: instance method of ChordProFormatter
Returns: string - The ChordPro string

HtmlDivFormatter

Formats a song into HTML. It uses DIVs to align lyrics with chords, which makes it useful for responsive web pages.

Kind: global class

htmlDivFormatter.format(song) ⇒ string

Formats a song into HTML.

Kind: instance method of HtmlDivFormatter
Returns: string - The HTML string

HtmlFormatter

Acts as a base class for HTML formatters, taking care of whitelisting prototype property access.

Kind: global class

HtmlTableFormatter

Formats a song into HTML. It uses TABLEs to align lyrics with chords, which makes the HTML for things like PDF conversion.

Kind: global class

htmlTableFormatter.format(song) ⇒ string

Formats a song into HTML.

Kind: instance method of HtmlTableFormatter
Returns: string - The HTML string

TextFormatter

Formats a sonf into a plain text chord sheet

Kind: global class

textFormatter.format(song) ⇒ string

Formats a song into a plain text chord sheet

Kind: instance method of TextFormatter
Returns: string - the chord sheet

ChordProParser

Parses a ChordPro chord sheet

Kind: global class

• ChordProParser
  • .warnings : Array.<ParserWarning>
  • .parse(chordProChordSheet) ⇒ Song

chordProParser.warnings : Array.<ParserWarning>

All warnings raised during parsing the ChordPro chord sheet

Kind: instance property of ChordProParser

chordProParser.parse(chordProChordSheet) ⇒ Song

Parses a ChordPro chord sheet into a song

Kind: instance method of ChordProParser
Returns: Song - The parsed song

ChordSheetParser

Parses a normal chord sheet

Kind: global class

• ChordSheetParser
  • new ChordSheetParser(options)
  • .parse(chordSheet, options) ⇒ Song

new ChordSheetParser(options)

Instantiate a chord sheet parser

chordSheetParser.parse(chordSheet, options) ⇒ Song

Parses a chord sheet into a song

Kind: instance method of ChordSheetParser
Returns: Song - The parsed song

ParserWarning

Represents a parser warning, currently only used by ChordProParser.

Kind: global class

• ParserWarning
  • .message : string
  • .lineNumber : integer
  • .toString() ⇒ string

parserWarning.message : string

The warning message

Kind: instance property of ParserWarning

parserWarning.lineNumber : integer

The chord sheet line number on which the warning occurred

Kind: instance property of ParserWarning

parserWarning.toString() ⇒ string

Returns a stringified version of the warning

Kind: instance method of ParserWarning
Returns: string - The string warning

UltimateGuitarParser

Parses an Ultimate Guitar chord sheet with metadata Inherits from ChordSheetParser

Kind: global class

ALBUM : string

Album meta directive. See https://www.chordpro.org/chordpro/directives-album/

Kind: global constant

ARTIST : string

Artist meta directive. See https://www.chordpro.org/chordpro/directives-artist/

Kind: global constant

CAPO : string

Capo meta directive. See https://www.chordpro.org/chordpro/directives-capo/

Kind: global constant

COMMENT : string

Comment directive. See https://www.chordpro.org/chordpro/directives-comment/

Kind: global constant

COMPOSER : string

Composer meta directive. See https://www.chordpro.org/chordpro/directives-composer/

Kind: global constant

COPYRIGHT : string

Copyright meta directive. See https://www.chordpro.org/chordpro/directives-copyright/

Kind: global constant

DURATION : string

Duration meta directive. See https://www.chordpro.org/chordpro/directives-duration/

Kind: global constant

END_OF_CHORUS : string

End of chorus directive. See https://www.chordpro.org/chordpro/directives-env_chorus/

Kind: global constant

END_OF_VERSE : string

End of verse directive. See https://www.chordpro.org/chordpro/directives-env_verse/

Kind: global constant

KEY : string

Key meta directive. See https://www.chordpro.org/chordpro/directives-key/

Kind: global constant

LYRICIST : string

Lyricist meta directive. See https://www.chordpro.org/chordpro/directives-lyricist/

Kind: global constant

START_OF_CHORUS : string

Start of chorus directive. See https://www.chordpro.org/chordpro/directives-env_chorus/

Kind: global constant

START_OF_VERSE : string

Start of verse directive. See https://www.chordpro.org/chordpro/directives-env_verse/

Kind: global constant

SUBTITLE : string

Subtitle meta directive. See https://www.chordpro.org/chordpro/directives-subtitle/

Kind: global constant

TEMPO : string

Tempo meta directive. See https://www.chordpro.org/chordpro/directives-tempo/

Kind: global constant

TIME : string

Time meta directive. See https://www.chordpro.org/chordpro/directives-time/

Kind: global constant

TITLE : string

Title meta directive. See https://www.chordpro.org/chordpro/directives-title/

Kind: global constant

YEAR : string

Year meta directive. See https://www.chordpro.org/chordpro/directives-year/

Kind: global constant