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.

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

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)

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

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.

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