ChordSheetJS

A JavaScript library for parsing and formatting chord sheets

Contents

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

Installation

Package managers

ChordSheetJS is on npm, to install run:

npm install chordsheetjs

Load with import:

import ChordSheetJS from 'chordsheetjs';

or require():

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

Standalone bundle file

If you're not using a build tool, you can download and use the bundle.js from the latest release:

<script src="bundle.js"></script>
<script>
// ChordSheetJS is available in global namespace now
const parser = new ChordSheetJS.ChordProParser();
</script>

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.ChordsOverWordsParser();
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}

{start_of_chorus: 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]
{end_of_chorus}`.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);

Serialize/deserialize

Chord sheets (Songs) can be serialized to plain JavaScript objects, which can be converted to JSON, XML etc by third-party libraries. The serialized object can also be deserialized back into a Song.

const serializedSong = new ChordSheetSerializer().serialize(song);
const deserialized = new ChordSheetSerializer().deserialize(serializedSong);

Add styling

The HTML formatters (HtmlTableFormatter and HtmlDivFormatter) can provide basic CSS to help with styling the output:

HtmlTableFormatter.cssString();
// .paragraph {
//   margin-bottom: 1em;
// }

HtmlTableFormatter.cssString('.chordSheetViewer');
// .chordSheetViewer .paragraph {
//   margin-bottom: 1em;
// }

HtmlTableFormatter.cssObject();
// '.paragraph': {
//   marginBottom: '1em'
// }

Parsing and modifying chords

import { Chord } from 'chordsheetjs';

Parse

const chord = Chord.parse('Ebsus4/Bb');

Parse numeric chords (Nashville system):

const chord = Chord.parse('b1sus4/#3');

Display with #toString

Use #toString() to convert the chord to a chord string (eg Dsus/F#)

const chord = Chord.parse('Ebsus4/Bb');
chord.toString(); // --> "Ebsus4/Bb"

Clone

var chord2 = chord.clone();

Normalize

Normalizes keys B#, E#, Cb and Fb to C, F, B and E

const chord = Chord.parse('E#/B#');
normalizedChord = chord.normalize();
normalizedChord.toString(); // --> "F/C"

Switch modifier

Deprecated

Convert # to b and vice versa

const chord = parseChord('Eb/Bb');
const chord2 = chord.switchModifier();
chord2.toString(); // --> "D#/A#"

Use specific modifier

Set the chord to a specific modifier (# or b)

const chord = Chord.parse('Eb/Bb');
const chord2 = chord.useModifier('#');
chord2.toString(); // --> "D#/A#"

const chord = Chord.parse('Eb/Bb');
const chord2 = chord.useModifier('b');
chord2.toString(); // --> "Eb/Bb"

Transpose up

const chord = Chord.parse('Eb/Bb');
const chord2 = chord.transposeUp();
chord2.toString(); // -> "E/B"

Transpose down

const chord = Chord.parse('Eb/Bb');
const chord2 = chord.transposeDown();
chord2.toString(); // -> "D/A"

Transpose

const chord = Chord.parse('C/E');
const chord2 = chord.transpose(4);
chord2.toString(); // -> "E/G#"

const chord = Chord.parse('C/E');
const chord2 = chord.transpose(-4);
chord2.toString(); // -> "Ab/C"

Convert numeric chord to chord symbol

const numericChord = Chord.parse('2/4');
const chordSymbol = numericChord.toChordSymbol('E');
chordSymbol.toString(); // -> "F#/A"

Supported ChordPro directives

All directives are parsed and are added to Song.metadata. The list below indicates whether formatters actually use those to change the generated output.

✔️ = 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

ChordSheetSerializer

Serializes a song into een plain object, and deserializes the serialized object back into a [Song](#Song)

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](#Metadata+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/

Chord

Represents a Chord, consisting of a root, suffix (quality) and bass

ChordProFormatter

Formats a song into a ChordPro chord sheet

ChordsOverWordsFormatter

Formats a song into a plain text chord sheet

Formatter

Base class for all formatters, taking care of receiving a configuration wrapping that inside a Configuration object

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

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 song into a plain text chord sheet

Key

Represents a key, such as Eb (symbol), #3 (numeric) or VII (numeral).

The only function considered public API is Key.distance

ChordProParser

Parses a ChordPro chord sheet

~~ChordSheetParser~~

Parses a normal chord sheet

ChordSheetParser is deprecated, please use ChordsOverWordsParser.

ChordsOverWordsParser aims to support any kind of chord, whereas ChordSheetParser lacks support for many variations. Besides that, some chordpro feature have been ported back to ChordsOverWordsParser, which adds some interesting functionality.

ChordsOverWordsParser

Parses a chords over words sheet into a song

It support "regular" chord sheets:

       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

Additionally, some chordpro features have been "ported back". For example, you can use chordpro directives:

{title: Let it be}
{key: C}
Chorus 1:
       Am
Let it be

For convenience, you can leave out the brackets:

title: Let it be
Chorus 1:
       Am
Let it be

You can even use a markdown style frontmatter separator to separate the header from the song:

title: Let it be
key: C
---
Chorus 1:
       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

ChordsOverWordsParser is the better version of ChordSheetParser, which is deprecated.

ParserWarning

Represents a parser warning, currently only used by ChordProParser.

UltimateGuitarParser

Parses an Ultimate Guitar chord sheet with metadata Inherits from [ChordSheetParser](#ChordSheetParser)

Constants

ALBUM : string: Album meta directive. See https://www.chordpro.org/chordpro/directives-album/
ARRANGER : string: Arranger meta directive. See https://chordpro.org/chordpro/directives-arranger/
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_ABC : string: End of ABC music notation section See https://chordpro.org/chordpro/directives-env_abc/
END_OF_BRIDGE : string: End of bridge directive. See https://chordpro.org/chordpro/directives-env_bridge/
END_OF_CHORUS : string: End of chorus directive. See https://www.chordpro.org/chordpro/directives-env_chorus/
END_OF_GRID : string: End of grid directive. See https://www.chordpro.org/chordpro/directives-env_grid/
END_OF_LY : string: End of Lilypond music notation section See https://chordpro.org/chordpro/directives-env_ly/
END_OF_TAB : string: End of tab directive. See https://www.chordpro.org/chordpro/directives-env_tab/
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/
_KEY : string: _Key meta directive. Reflects the key as transposed by the capo value See https://www.chordpro.org/chordpro/directives-key/
LYRICIST : string: Lyricist meta directive. See https://www.chordpro.org/chordpro/directives-lyricist/
SORTTITLE : string: Sorttitle meta directive. See https://chordpro.org/chordpro/directives-sorttitle/
START_OF_ABC : string: Start of ABC music notation section See https://chordpro.org/chordpro/directives-env_abc/
START_OF_BRIDGE : string: Start of bridge directive. See https://chordpro.org/chordpro/directives-env_bridge/
START_OF_CHORUS : string: Start of chorus directive. See https://www.chordpro.org/chordpro/directives-env_chorus/
START_OF_GRID : string: Start of grid directive. See https://www.chordpro.org/chordpro/directives-env_grid/
START_OF_LY : string: Start of Lilypond music notation section See https://chordpro.org/chordpro/directives-env_ly/
START_OF_TAB : string: Start of tab directive. See https://www.chordpro.org/chordpro/directives-env_tab/
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/
TRANSPOSE : string: Transpose meta directive. See: https://www.chordpro.org/chordpro/directives-transpose/
NEW_KEY : string: New Key meta directive. See: bettermusic#53
YEAR : string: Year meta directive. See https://www.chordpro.org/chordpro/directives-year/
CHORDFONT : string: Chordfont directive. See https://www.chordpro.org/chordpro/directives-props_chord_legacy/
CHORDSIZE : string: Chordfont directive. See https://www.chordpro.org/chordpro/directives-props_chord_legacy/
CHORDCOLOUR : string: Chordfont directive. See https://www.chordpro.org/chordpro/directives-props_chord_legacy/
TEXTFONT : string: Chordfont directive. See https://www.chordpro.org/chordpro/directives-props_text_legacy/
TEXTSIZE : string: Chordfont directive. See https://www.chordpro.org/chordpro/directives-props_text_legacy/
TEXTCOLOUR : string: Chordfont directive. See https://www.chordpro.org/chordpro/directives-props_text_legacy/
TITLEFONT : string: Chordfont directive. See https://www.chordpro.org/chordpro/directives-props_title_legacy/
TITLESIZE : string: Chordfont directive. See https://www.chordpro.org/chordpro/directives-props_title_legacy/
TITLECOLOUR : string: Chordfont directive. See https://www.chordpro.org/chordpro/directives-props_title_legacy/
CHORUS : string: Chorus directive. Support repeating an earlier defined section. See https://www.chordpro.org/chordpro/directives-env_chorus/
CHORD_STYLE : string: Chord type directive. Determines the type of chords used in the rendered chord sheet. Possible values are 'solfege', 'symbol', 'numeral' and 'number'
BRIDGE : string: Used to mark a paragraph as bridge
CHORUS : string: Used to mark a paragraph as chorus
GRID : string: Used to mark a paragraph as grid
INDETERMINATE : string: Used to mark a paragraph as containing lines with both verse and chorus type
NONE : string: Used to mark a paragraph as not containing a line marked with a type
TAB : string: Used to mark a paragraph as tab
VERSE : string: Used to mark a paragraph as verse
LILYPOND : string: Used to mark a section as Lilypond notation
ABC : string: Used to mark a section as ABC music notation

Functions

scopedCss(scope) ⇒ string: Generates basic CSS, scoped within the provided selector, to use with output generated by [HtmlTableFormatter](#HtmlTableFormatter)
scopedCss(scope) ⇒ string: Generates basic CSS, scoped within the provided selector, to use with output generated by [HtmlTableFormatter](#HtmlTableFormatter)
getCapos(key) ⇒ Object.<string, string>: Returns applicable capos for the provided key
getKeys(key) ⇒ Array.<string>: Returns applicable keys to transpose to from the provided key

ChordSheetSerializer

Serializes a song into een plain object, and deserializes the serialized object back into a [Song](#Song)

Kind: global class

ChordSheetSerializer
- .serialize() ⇒
- .deserialize(serializedSong) ⇒ Song

chordSheetSerializer.serialize() ⇒

Serializes the chord sheet to a plain object, which can be converted to any format like JSON, XML etc Can be deserialized using [deserialize](deserialize)

Kind: instance method of ChordSheetSerializer
Returns:

object A plain JS object containing all chord sheet data

chordSheetSerializer.deserialize(serializedSong) ⇒ `Song`

Deserializes a song that has been serialized using [serialize](serialize)

Kind: instance method of ChordSheetSerializer
Returns: Song -

The deserialized song

Param	Type	Description
serializedSong	`object`	The serialized song

ChordLyricsPair

Represents a chord with the corresponding (partial) lyrics

Kind: global class

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

new ChordLyricsPair(chords, lyrics, annotation)

Initialises a ChordLyricsPair

Param	Type	Default	Description
chords	`string`		The chords
lyrics	`string` \| `null`	`null`	The lyrics
annotation	`string` \| `null`	`null`	The annotation

chordLyricsPair.chords : `string`

The chords

Kind: instance property of ChordLyricsPair

chordLyricsPair.lyrics : `string`

The lyrics

Kind: instance property of ChordLyricsPair

chordLyricsPair.annotation : `string`

The annotation

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
- .isEmpty() ⇒ boolean
- .addItem(item)
- .hasRenderableItems() ⇒ boolean
- .clone() ⇒ Line
- .isBridge() ⇒ boolean
- .isChorus() ⇒ boolean
- .isGrid() ⇒ boolean
- .isTab() ⇒ boolean
- .isVerse() ⇒ boolean
- ~~.hasContent() ⇒ boolean~~