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.

Generates a PDF document directly. Requires configuration for page size and fonts.

const formatter = new ChordSheetJS.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)

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

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