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
Copy

Load with import:

import ChordSheetJS from 'chordsheetjs';
Copy

or require():

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

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>
Copy

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

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

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

Display a parsed sheet

Plain text format

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

HTML format

Table-based layout

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

Div-based layout

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

Chord pro format

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

Chords over words format

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

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
Copy

Then import PdfFormatter from chordsheetjs/pdf:

import { PdfFormatter } from 'chordsheetjs/pdf';

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

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

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

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

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
Copy

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
Copy

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

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';
Copy

Parse

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

Parse numeric chords (Nashville system):

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

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"
Copy

Clone

var chord2 = chord.clone();
Copy

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"
Copy

Switch modifier

Deprecated

Convert # to b and vice versa

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

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#"
Copy

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

Transpose up

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

Transpose down

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

Transpose

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

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

Convert numeric chord to chord symbol

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

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.

:heavy_check_mark: = supported

:clock2: = will be supported in a future version

:heavy_multiplication_x: = currently no plans to support it in the near future

Meta-data directives

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

Formatting directives

Directive	Support
comment (short: c)	:heavy_check_mark:
comment_italic (short: ci)	:heavy_multiplication_x:
comment_box (short: cb)	:heavy_multiplication_x:
chorus	:heavy_multiplication_x:
image	:heavy_multiplication_x:

Environment directives

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

Chord diagrams

Directive	Support
define	:heavy_check_mark:
chord	:heavy_check_mark:

Fonts, sizes and colours

Directive	Support
textfont	:heavy_check_mark:
textsize	:heavy_check_mark:
textcolour	:heavy_check_mark:
chordfont	:heavy_check_mark:
chordsize	:heavy_check_mark:
chordcolour	:heavy_check_mark:
tabfont	:heavy_multiplication_x:
tabsize	:heavy_multiplication_x:
tabcolour	:heavy_multiplication_x:

Output related directives

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

Custom extensions

Directive	Support
x_	:heavy_check_mark:

API docs

For more information, see the API docs.