A JavaScript library for parsing and formatting chord sheets
Contents
- Installation
- How to ...?
- Try it online
- Supported ChordPro directives
- Project board
- API docs
- Contributing
ChordSheetJS is on npm, to install run:
npm install chordsheetjsLoad with import:
import ChordSheetJS from 'chordsheetjs';or require():
var ChordSheetJS = require('chordsheetjs').default;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>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);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);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);const formatter = new ChordSheetJS.TextFormatter();
const disp = formatter.format(song);const formatter = new ChordSheetJS.HtmlTableFormatter();
const disp = formatter.format(song);const formatter = new ChordSheetJS.HtmlDivFormatter();
const disp = formatter.format(song);const formatter = new ChordSheetJS.ChordProFormatter();
const disp = formatter.format(song);const formatter = new ChordSheetJS.ChordsOverWordsFormatter();
const disp = formatter.format(song);Note:
PdfFormatteris 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');Note:
MeasuredHtmlFormatteris 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);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 DOMCanvasMeasurer- Measures text using HTML CanvasJsPdfMeasurer- 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.
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);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'
// }import { Chord } from 'chordsheetjs';const chord = Chord.parse('Ebsus4/Bb');Parse numeric chords (Nashville system):
const chord = Chord.parse('b1sus4/#3');Use #toString() to convert the chord to a chord string (eg Dsus/F#)
const chord = Chord.parse('Ebsus4/Bb');
chord.toString(); // --> "Ebsus4/Bb"var chord2 = chord.clone();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"Deprecated
Convert # to b and vice versa
const chord = parseChord('Eb/Bb');
const chord2 = chord.switchModifier();
chord2.toString(); // --> "D#/A#"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"const chord = Chord.parse('Eb/Bb');
const chord2 = chord.transposeUp();
chord2.toString(); // -> "E/B"const chord = Chord.parse('Eb/Bb');
const chord2 = chord.transposeDown();
chord2.toString(); // -> "D/A"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"const numericChord = Chord.parse('2/4');
const chordSymbol = numericChord.toChordSymbol('E');
chordSymbol.toString(); // -> "F#/A"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
| Directive | Support |
|---|---|
| title (short: t) | ✔️ |
| subtitle | ✔️ |
| artist | ✔️ |
| composer | ✔️ |
| lyricist | ✔️ |
| copyright | ✔️ |
| album | ✔️ |
| year | ✔️ |
| key | ✔️ |
| time | ✔️ |
| tempo | ✔️ |
| duration | ✔️ |
| capo | ✔️ |
| meta | ✔️ |
| Directive | Support |
|---|---|
| comment (short: c) | ✔️ |
| comment_italic (short: ci) | ✖️ |
| comment_box (short: cb) | ✖️ |
| chorus | ✖️ |
| image | ✖️ |
| 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 | ✔️ |
| Directive | Support |
|---|---|
| define | ✔️ |
| chord | ✔️ |
| Directive | Support |
|---|---|
| textfont | ✔️ |
| textsize | ✔️ |
| textcolour | ✔️ |
| chordfont | ✔️ |
| chordsize | ✔️ |
| chordcolour | ✔️ |
| tabfont | ✖️ |
| tabsize | ✖️ |
| tabcolour | ✖️ |
| 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) | ✖️ |
| Directive | Support |
|---|---|
| x_ | ✔️ |
For more information, see the API docs.