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