bkeepers / ChordSheetJS

A JavaScript library for parsing and formatting ChordPro chord sheets

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);

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

Directive	Support
title (short: t)	✔️
subtitle	✔️
artist	✔️
composer	✔️
lyricist	✔️
copyright	✔️
album	✔️
year	✔️
key	✔️
time	✔️
tempo	✔️
duration	✔️
capo	✔️
meta	✔️

Formatting directives

Directive	Support
comment (short: c)	✔️
comment_italic (short: ci)	✖️
comment_box (short: cb)	✖️
chorus	✖️
image	✖️

Environment directives

Directive	Support
start_of_chorus (short: soc)	✔️
end_of_chorus (short: eoc)	✔️
start_of_verse	✔️
end_of_verse	✔️
start_of_tab (short: sot)	✖️
end_of_tab (short: eot)	✖️
start_of_grid	✖️
end_of_grid	✖️

Chord diagrams

Directive	Support
define	✖️
chord	✖️

Fonts, sizes and colours

Directive	Support
textfont	🕑
textsize	🕑
textcolour	🕑
chordfont	🕑
chordsize	🕑
chordcolour	🕑
tabfont	✖️
tabsize	✖️
tabcolour	✖️

Output related directives

Directive	Support
new_page (short: np)	✖️
new_physical_page (short: npp)	✖️
column_break (short: cb)	✖️
grid (short: g)	✖️
no_grid (short: ng)	✖️
titles	✖️
columns (short: col)	✖️

Custom extensions

Directive	Support
x_	✔️

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

Line

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

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

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.

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

ParserWarning

Represents a parser warning, currently only used by ChordProParser.

Constants

ALBUM : string

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

ARTIST : string

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

CAPO : string

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

COMMENT : string

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

COMPOSER : string

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

COPYRIGHT : string

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

DURATION : string

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

END_OF_CHORUS : string

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

END_OF_VERSE : string

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

KEY : string

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

LYRICIST : string

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

START_OF_CHORUS : string

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

START_OF_VERSE : string

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

SUBTITLE : string

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

TEMPO : string

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

TIME : string

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

TITLE : string

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

YEAR : string

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

Functions

parse(chordSheet) ⇒ Song

Parses a chord sheet into a song

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

Param	Type	Description
chords	string	The chords
lyrics	string	The lyrics

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

Line

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

Kind: global class

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

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

The items (ChordLyricsPair or Tag) 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

Param	Type	Description
item	ChordLyricsPair | Tag	The item to be added

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

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
  • .lines : Array.<Line>
  • .paragraphs : Array.<Line>
  • .bodyLines ⇒ Array.<Line>
  • .metaData ⇒ object
  • .clone() ⇒ Song

song.lines : Array.<Line>

The Line items of which the song consists

Kind: instance property of Song

song.paragraphs : Array.<Line>

The Paragraph items of which the song consists

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 ⇒ object

Returns the song 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
Returns: object - 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.html

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

Param	Type	Description
song	Song	The song to be formatted

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

Param	Type	Description
song	Song	The song to be formatted

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

Param	Type	Description
song	Song	The song to be formatted

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

Param	Type	Description
song	Song	The song to be formatted

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

Param	Type	Description
chordProChordSheet	string	the ChordPro chord sheet

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

ALBUM : string

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

Kind: global constant

ARTIST : string

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

Kind: global constant

CAPO : string

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

Kind: global constant

COMMENT : string

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

Kind: global constant

COMPOSER : string

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

Kind: global constant

COPYRIGHT : string

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

Kind: global constant

DURATION : string

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

Kind: global constant

END_OF_CHORUS : string

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

Kind: global constant

END_OF_VERSE : string

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

Kind: global constant

KEY : string

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

Kind: global constant

LYRICIST : string

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

Kind: global constant

START_OF_CHORUS : string

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

Kind: global constant

START_OF_VERSE : string

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

Kind: global constant

SUBTITLE : string

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

Kind: global constant

TEMPO : string

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

Kind: global constant

TIME : string

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

Kind: global constant

TITLE : string

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

Kind: global constant

YEAR : string

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

Kind: global constant

parse(chordSheet) ⇒ Song

Parses a chord sheet into a song

Kind: global function
Returns: Song - The parsed song

Param	Type	Description
chordSheet	string	The ChordPro chord sheet