ChordSheetJS

A JavaScript library for parsing and formatting chord sheets

Contents

• Installation
• How to ...?
• Try it online
• Supported ChordPro directives
• Project board
• 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);

Chords over words format

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

PDF format (BETA)

Note: PdfFormatter is currently in beta. Its API may change in future releases.

PDF support is available as a separate entry point to keep the main bundle small. To use it, install jspdf as a dependency:

npm install jspdf

Then import PdfFormatter from chordsheetjs/pdf:

import { PdfFormatter } from 'chordsheetjs/pdf';

const formatter = new PdfFormatter();
const doc = formatter.format(song);
doc.save('song.pdf');

Measured HTML format (BETA)

Note: MeasuredHtmlFormatter is currently in beta. Its API may change in future releases.

Creates HTML output with precise text measurement for accurate chord positioning.

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

Layout Engine

The PdfFormatter and MeasuredHtmlFormatter are powered by a layout engine that handles text measurement and precise positioning of chords above lyrics. The layout engine uses measurers to calculate text dimensions:

• DomMeasurer - Measures text using the browser's DOM
• CanvasMeasurer - Measures text using HTML Canvas
• JsPdfMeasurer - Measures text using jsPDF (for PDF output, available from chordsheetjs/pdf)

These are used internally by the measurement-based formatters but can also be accessed directly for advanced use cases.

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'
// }

Change chord notation (transcoding)

ChordSheetJS can render the chords of a sheet in a different notation system than the one they were written in. This is controlled with the {chord_style} directive, in combination with the song {key}.

Four notation styles are supported:

Style	Description	Example (key of C)
symbol	Letter notation (the default)	C, Dm, F, G, Am
solfege	Solfège / romance-language notation	Do, Rem, Fa, Sol
numeral	Roman numeral / functional notation	I, ii, IV, V, vi
number	Nashville number notation	1, 2m, 4, 5, 6m

The symbol and solfege styles are absolute (they name an actual pitch), while numeral and number are relative to the key. Because of that, a song {key} is required to convert between an absolute and a relative style. Conversion works in every direction: the chords in the source sheet may be written in any of the four styles.

const chordSheet = `
{key: C}
{chord_style: numeral}

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

const song = new ChordSheetJS.ChordProParser().parse(chordSheet);
new ChordSheetJS.TextFormatter().format(song);
// Am -> vi, F -> IV, C -> I, G -> V

Using {chord_style: number} on the same sheet would render Am as 6m, F as 4, C as 1 and G as 5.

Because conversion is bidirectional, a sheet written in Roman numerals can be rendered as chord symbols by combining a concrete {key} with {chord_style: symbol}:

const chordSheet = `
{key: C}
{chord_style: symbol}

[I] [ii] [iii] [IV] [V] [vi] [vii]`.substring(1);

const song = new ChordSheetJS.ChordProParser().parse(chordSheet);
new ChordSheetJS.TextFormatter().format(song);
// I -> C, ii -> Dm, iii -> Em, IV -> F, V -> G, vi -> Am, vii -> Bm

The TextFormatter, HtmlTableFormatter, HtmlDivFormatter and ChordsOverWordsFormatter apply {chord_style} automatically. The ChordProFormatter preserves the original chord notation by default (so a round-trip stays lossless); pass applyChordStyle: true to have it convert the chords as well:

new ChordSheetJS.ChordProFormatter({ applyChordStyle: true }).format(song);

You can also convert a single chord programmatically, without a sheet, using the Chord methods (see Parsing and modifying chords below), e.g. Chord.parse('2/4').toChordSymbol('E').

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

For more information, see the API docs.