ChordChartJS

A JavaScript library for parsing and formatting chord sheets

Contents

• Installation
• How to ...?
• Supported ChordPro directives
• API docs

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.ChordSheetParser();
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}
{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]`.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);

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 { parseChord } from 'chordsheetjs';

Parse

const chord = parseChord('Ebsus4/Bb');

Parse numeric chords (Nashville system):

const chord = parseChord('b1sus4/#3');

Display with #toString

Use #toString() to convert the chord to a chord string (eg Dsus/F#)

const chord = parseChord('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 = parseChord('E#/B#'),
normalizedChord = chord.normalize();
normalizedChord.toString(); // --> "F/C"

Switch modifier

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 = parseChord('Eb/Bb');
const chord2 = chord.useModifier('#');
chord2.toString(); // --> "D#/A#"

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

Transpose up

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

Transpose down

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

Transpose

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

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

Convert numeric chord to chord symbol

const numericChord = parseChord('2/4');
const chordSymbol = toChordSymbol(numericChord, 'E');
chordSymbol.toString(); // -> "F#m/A"

Supported ChordPro directives

: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_multiplication_x: | | end_of_tab (short: eot) | :heavy_multiplication_x: | | start_of_grid | :heavy_multiplication_x: | | end_of_grid | :heavy_multiplication_x: |

Chord diagrams

| Directive | Support | |:--------- |:------------------------:| | define | :heavy_multiplication_x: | | chord | :heavy_multiplication_x: |

Fonts, sizes and colours

| Directive | Support | |:----------- |:------------------------:| | textfont | :clock2: | | textsize | :clock2: | | textcolour | :clock2: | | chordfont | :clock2: | | chordsize | :clock2: | | chordcolour | :clock2: | | 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

Note: all classes, methods and constants that are documented here can be considered public API and will only be subject to breaking changes between major versions.

Classes

Members

Constants

Functions

ChordLyricsPair

Kind: global class

• ChordLyricsPair
  • new ChordLyricsPair(chords, lyrics)
  • .chords : string
  • .lyrics : string
  • .isRenderable() ⇒ boolean
  • .clone() ⇒ ChordLyricsPair

new ChordLyricsPair(chords, lyrics)

| Param | Type | Description | | --- | --- | --- | | chords | string | The chords | | lyrics | string | The lyrics |

chordLyricsPair.chords : string

Kind: instance property of ChordLyricsPair

chordLyricsPair.lyrics : string

Kind: instance property of ChordLyricsPair

chordLyricsPair.isRenderable() ⇒ boolean

Kind: instance method of ChordLyricsPair

chordLyricsPair.clone() ⇒ ChordLyricsPair

Kind: instance method of ChordLyricsPair

Comment

Kind: global class

• Comment
  • .isRenderable() ⇒ boolean
  • .clone() ⇒ Comment

comment.isRenderable() ⇒ boolean

Kind: instance method of Comment

comment.clone() ⇒ Comment

Kind: instance method of Comment

Metadata

Kind: global class

• Metadata
  • .get(prop) ⇒ Array.<String> | String
  • .clone() ⇒ Metadata

metadata.get(prop) ⇒ Array.<String> | String

Kind: instance method of Metadata
Returns: Array.<String> | String - the metadata value(s). If there is only one value, it will return a String, else it returns an array of strings.

| Param | Description | | --- | --- | | prop | the property name |

metadata.clone() ⇒ Metadata

Kind: instance method of Metadata
Returns: Metadata - the cloned Metadata object

Paragraph

Kind: global class

• Paragraph
  • .type ⇒ string
  • .hasRenderableItems() ⇒ boolean

paragraph.type ⇒ string

Kind: instance property of Paragraph

paragraph.hasRenderableItems() ⇒ boolean

Kind: instance method of Paragraph
See: Line.hasRenderableItems

Song

Kind: global class

• Song
  • new Song(metadata)
  • .bodyLines ⇒ Array.<Line>
  • .bodyParagraphs ⇒ Array.<Paragraph>
  • .paragraphs : Array.<Paragraph>
  • ~~.metaData ⇒~~
  • .clone() ⇒ Song
  • .setKey(key) ⇒ Song
  • .setCapo(capo) ⇒ Song
  • .transpose(delta, [options]) ⇒ Song
  • .transposeUp([options]) ⇒ Song
  • .transposeDown([options]) ⇒ Song
  • .changeKey(newKey) ⇒ Song
  • .changeMetadata(name, value)
  • .mapItems(func) ⇒ Song
  • .mapLines(func) ⇒ Song

new Song(metadata)

| Param | Type | Description | | --- | --- | --- | | metadata | Object | Metadata | predefined metadata |

song.bodyLines ⇒ Array.<Line>

Kind: instance property of Song
Returns: Array.<Line> - The song body lines

song.bodyParagraphs ⇒ Array.<Paragraph>

Kind: instance property of Song
See: bodyLines

song.paragraphs : Array.<Paragraph>

Kind: instance property of Song

~~song.metaData ⇒~~

Deprecated

Kind: instance property of Song
Returns: Metadata The metadata

song.clone() ⇒ Song

Kind: instance method of Song
Returns: Song - The cloned song

song.setKey(key) ⇒ Song

Kind: instance method of Song
Returns: Song - The changed song

| Param | Type | Description | | --- | --- | --- | | key | number | null | the key. Passing null will: remove the current key from metadata remove any key directive |

song.setCapo(capo) ⇒ Song

Kind: instance method of Song
Returns: Song - The changed song

| Param | Type | Description | | --- | --- | --- | | capo | number | null | the capo. Passing null will: remove the current key from metadata remove any capo directive |

song.transpose(delta, [options]) ⇒ Song

Kind: instance method of Song
Returns: Song - The transposed song

| Param | Type | Default | Description | | --- | --- | --- | --- | | delta | number | | The number of semitones (positive or negative) to transpose with | | [options] | Object | {} | options | | [options.normalizeChordSuffix] | boolean | false | whether to normalize the chord suffixes after transposing |

song.transposeUp([options]) ⇒ Song

Kind: instance method of Song
Returns: Song - The transposed song

| Param | Type | Default | Description | | --- | --- | --- | --- | | [options] | Object | {} | options | | [options.normalizeChordSuffix] | boolean | false | whether to normalize the chord suffixes after transposing |

song.transposeDown([options]) ⇒ Song

Kind: instance method of Song
Returns: Song - The transposed song

| Param | Type | Default | Description | | --- | --- | --- | --- | | [options] | Object | {} | options | | [options.normalizeChordSuffix] | boolean | false | whether to normalize the chord suffixes after transposing |

song.changeKey(newKey) ⇒ Song

Kind: instance method of Song
Returns: Song - The changed song

| Param | Type | Description | | --- | --- | --- | | newKey | string | The new key. |

song.changeMetadata(name, value)

Kind: instance method of Song

| Param | Type | Description | | --- | --- | --- | | name | string | The directive name | | value | string | null | The value to set, or null to remove the directive |

song.mapItems(func) ⇒ Song

Kind: instance method of Song
Returns: Song - the changed song

| Param | Type | Description | | --- | --- | --- | | func | MapItemsCallback | the callback function |

Example

// transpose all chords:
song.mapItems((item) => {
  if (item instanceof ChordLyricsPair) {
    return item.transpose(2, 'D');
  }

  return item;
});

song.mapLines(func) ⇒ Song

Kind: instance method of Song
Returns: Song - the changed song

| Param | Type | Description | | --- | --- | --- | | func | MapLinesCallback | the callback function |

Example

// remove lines with only Tags:
song.mapLines((line) => {
  if (line.items.every(item => item instanceof Tag)) {
    return null;
  }

  return line;
});

Tag

Kind: global class

• Tag
  • .name : string
  • .originalName : string
  • .value : string | null
  • .hasValue() ⇒ boolean
  • .isRenderable() ⇒ boolean
  • .isMetaTag() ⇒ boolean
  • .clone() ⇒ Tag

tag.name : string

Kind: instance property of Tag

tag.originalName : string

Kind: instance property of Tag

tag.value : string | null

Kind: instance property of Tag

tag.hasValue() ⇒ boolean

Kind: instance method of Tag

tag.isRenderable() ⇒ boolean

Kind: instance method of Tag

tag.isMetaTag() ⇒ boolean

Kind: instance method of Tag

tag.clone() ⇒ Tag

Kind: instance method of Tag
Returns: Tag - The cloned tag

ChordProFormatter

Kind: global class

chordProFormatter.format(song) ⇒ string

Kind: instance method of ChordProFormatter
Returns: string - The ChordPro string

| Param | Type | Description | | --- | --- | --- | | song | Song | The song to be formatted |

Formatter

Kind: global class

new Formatter([configuration])

| Param | Type | Default | Description | | --- | --- | --- | --- | | [configuration] | Object | {} | options | | [configuration.evaluate] | boolean | false | Whether or not to evaluate meta expressions. For more info about meta expressions, see: https://bit.ly/2SC9c2u | | [configuration.metadata] | object | {} | | | [configuration.metadata.separator] | string | "&quot;, &quot;" | The separator to be used when rendering a metadata value that has multiple values. See: https://bit.ly/2SC9c2u |

HtmlDivFormatter

Kind: global class

• HtmlDivFormatter
  • instance
    • .format(song) ⇒ string
  • static
    • .cssString(scope) ⇒ string
    • .cssObject() ⇒ Object.<string, Object.<string, string>>

htmlDivFormatter.format(song) ⇒ string

Kind: instance method of HtmlDivFormatter
Returns: string - The HTML string

| Param | Type | Description | | --- | --- | --- | | song | Song | The song to be formatted |

HtmlDivFormatter.cssString(scope) ⇒ string

Kind: static method of HtmlDivFormatter
Returns: string - the CSS string

| Param | Description | | --- | --- | | scope | the CSS scope to use, for example .chordSheetViewer |

HtmlDivFormatter.cssObject() ⇒ Object.<string, Object.<string, string>>

Kind: static method of HtmlDivFormatter
Returns: Object.<string, Object.<string, string>> - the CSS object

HtmlFormatter

Kind: global class

HtmlTableFormatter

Kind: global class

• HtmlTableFormatter
  • instance
    • .format(song) ⇒ string
  • static
    • .cssString(scope) ⇒ string
    • .cssObject() ⇒ Object.<string, Object.<string, string>>

htmlTableFormatter.format(song) ⇒ string

Kind: instance method of HtmlTableFormatter
Returns: string - The HTML string

| Param | Type | Description | | --- | --- | --- | | song | Song | The song to be formatted |

HtmlTableFormatter.cssString(scope) ⇒ string

Kind: static method of HtmlTableFormatter
Returns: string - the CSS string

| Param | Description | | --- | --- | | scope | the CSS scope to use, for example .chordSheetViewer |

HtmlTableFormatter.cssObject() ⇒ Object.<string, Object.<string, string>>

Kind: static method of HtmlTableFormatter
Returns: Object.<string, Object.<string, string>> - the CSS object

TextFormatter

Kind: global class

textFormatter.format(song) ⇒ string

Kind: instance method of TextFormatter
Returns: string - the chord sheet

| Param | Type | Description | | --- | --- | --- | | song | Song | The song to be formatted |

ChordProParser

Kind: global class

• ChordProParser
  • .warnings : Array.<ParserWarning>
  • .parse(chordProChordSheet) ⇒ Song

chordProParser.warnings : Array.<ParserWarning>

Kind: instance property of ChordProParser

chordProParser.parse(chordProChordSheet) ⇒ Song

Kind: instance method of ChordProParser
Returns: Song - The parsed song

| Param | Type | Description | | --- | --- | --- | | chordProChordSheet | string | the ChordPro chord sheet |

ChordSheetParser

Kind: global class

• ChordSheetParser
  • new ChordSheetParser([options])
  • .parse(chordSheet, [options]) ⇒ Song

new ChordSheetParser([options])

| Param | Type | Default | Description | | --- | --- | --- | --- | | [options] | Object | {} | options | | [options.preserveWhitespace] | boolean | true | whether to preserve trailing whitespace for chords |

chordSheetParser.parse(chordSheet, [options]) ⇒ Song

Kind: instance method of ChordSheetParser
Returns: Song - The parsed song

| Param | Type | Default | Description | | --- | --- | --- | --- | | chordSheet | string | | The ChordPro chord sheet | | [options] | Object | {} | Optional parser options | | [options.song] | Song | | The Song to store the song data in |

ParserWarning

Kind: global class

parserWarning.toString() ⇒ string

Kind: instance method of ParserWarning
Returns: string - The string warning

UltimateGuitarParser

Kind: global class

Chord

Kind: global class

• Chord
  • instance
    • .clone() ⇒ Chord
    • .toChordSymbol([key]) ⇒ Chord
    • .toChordSymbolString([key]) ⇒ string
    • .isChordSymbol() ⇒ boolean
    • .toNumeric([key]) ⇒ Chord
    • .toNumeral(key) ⇒ Chord
    • .toNumeralString([key]) ⇒ string
    • .isNumeric() ⇒ boolean
    • .toNumericString([key]) ⇒ string
    • .isNumeral() ⇒ boolean
    • .toString() ⇒ string
    • .normalize([key], [options]) ⇒ Chord
    • .useModifier(newModifier) ⇒ Chord
    • .transposeUp() ⇒ Chord
    • .transposeDown() ⇒ Chord
    • .transpose(delta) ⇒ Chord
  • static
    • .parse(chordString) ⇒ null | Chord

chord.clone() ⇒ Chord

Kind: instance method of Chord

chord.toChordSymbol([key]) ⇒ Chord

Kind: instance method of Chord
Returns: Chord - the chord symbol

| Param | Type | Default | Description | | --- | --- | --- | --- | | [key] | Key | string | | the reference key |

chord.toChordSymbolString([key]) ⇒ string

Kind: instance method of Chord
Returns: string - the chord symbol string
See: {toChordSymbol}

| Param | Type | Default | Description | | --- | --- | --- | --- | | [key] | Key | string | | the reference key |

chord.isChordSymbol() ⇒ boolean

Kind: instance method of Chord

chord.toNumeric([key]) ⇒ Chord

Kind: instance method of Chord
Returns: Chord - the numeric chord

| Param | Type | Default | Description | | --- | --- | --- | --- | | [key] | Key | string | | the reference key |

chord.toNumeral(key) ⇒ Chord

Kind: instance method of Chord
Returns: Chord - the numeral chord

| Param | Type | Default | Description | | --- | --- | --- | --- | | key | Key | string | null | | the reference key. The key is required when converting a chord symbol |

chord.toNumeralString([key]) ⇒ string

Kind: instance method of Chord
Returns: string - the numeral chord string
See: {toNumeral}

| Param | Type | Default | Description | | --- | --- | --- | --- | | [key] | Key | string | | the reference key |

chord.isNumeric() ⇒ boolean

Kind: instance method of Chord

chord.toNumericString([key]) ⇒ string

Kind: instance method of Chord
Returns: string - the numeric chord string
See: {toNumeric}

| Param | Type | Default | Description | | --- | --- | --- | --- | | [key] | Key | string | | the reference key |

chord.isNumeral() ⇒ boolean

Kind: instance method of Chord

chord.toString() ⇒ string

Kind: instance method of Chord
Returns: string - the chord string

chord.normalize([key], [options]) ⇒ Chord

Kind: instance method of Chord
Returns: Chord - the normalized chord

| Param | Type | Default | Description | | --- | --- | --- | --- | | [key] | Key | string | | the key to normalize to | | [options] | Object | {} | options | | [options.normalizeSuffix] | boolean | true | whether to normalize the chord suffix after transposing |

chord.useModifier(newModifier) ⇒ Chord

Kind: instance method of Chord
Returns: Chord - the new, changed chord

| Param | Description | | --- | --- | | newModifier | the modifier to use: '#' or 'b' |

chord.transposeUp() ⇒ Chord

Kind: instance method of Chord
Returns: Chord - the new, transposed chord

chord.transposeDown() ⇒ Chord

Kind: instance method of Chord
Returns: Chord - the new, transposed chord

chord.transpose(delta) ⇒ Chord

Kind: instance method of Chord
Returns: Chord - the new, transposed chord

| Param | Description | | --- | --- | | delta | de number of semitones |

Chord.parse(chordString) ⇒ null | Chord

Kind: static method of Chord

| Param | Description | | --- | --- | | chordString | the chord string, eg Esus4/G# or 1sus4/#3 |

ChordSheetSerializer

Kind: global class

• ChordSheetSerializer
  • .serialize() ⇒
  • .deserialize(serializedSong) ⇒ Song

chordSheetSerializer.serialize() ⇒

Kind: instance method of ChordSheetSerializer
Returns: object A plain JS object containing all chord sheet data

chordSheetSerializer.deserialize(serializedSong) ⇒ Song

Kind: instance method of ChordSheetSerializer
Returns: Song - The deserialized song

| Param | Type | Description | | --- | --- | --- | | serializedSong | object | The serialized song |

ALBUM : string

Kind: global variable

ARTIST : string

Kind: global variable

CAPO : string

Kind: global variable

COMMENT : string

Kind: global variable

COMPOSER : string

Kind: global variable

COPYRIGHT : string

Kind: global variable

DURATION : string

Kind: global variable

END_OF_CHORUS : string

Kind: global variable

END_OF_TAB : string

Kind: global variable

END_OF_VERSE : string

Kind: global variable

KEY : string

Kind: global variable

_KEY : string

Kind: global variable

LYRICIST : string

Kind: global variable

START_OF_CHORUS : string

Kind: global variable

START_OF_TAB : string

Kind: global variable

START_OF_VERSE : string

Kind: global variable

SUBTITLE : string

Kind: global variable

TEMPO : string

Kind: global variable

TIME : string

Kind: global variable

TITLE : string

Kind: global variable

TRANSPOSE : string

Kind: global variable

NEW_KEY : string

Kind: global variable

defaultCss ⇒ string

Kind: global variable
Returns: string - the CSS string

| Param | Description | | --- | --- | | scope | the CSS scope to use, for example .chordSheetViewer |

defaultCss : Object.<string, Object.<string, string>>

Kind: global constant

VERSE : string

Kind: global constant

VERSE : string

Kind: global constant

CHORUS : string

Kind: global constant

NONE : string

Kind: global constant

INDETERMINATE : string

Kind: global constant

~~parseChord(chordString) ⇒ null | Chord~~

Deprecated

Kind: global function

| Param | Description | | --- | --- | | chordString | the chord string, eg Esus4/G# or 1sus4/#3 |

getCapos(key) ⇒ Object.<string, string>

Kind: global function
Returns: Object.<string, string> - The available capos, where the keys are capo numbers and the values are the effective key for that capo.

| Param | Type | Description | | --- | --- | --- | | key | Key | string | The key to get capos for |

getKeys(key) ⇒ Array.<string>

Kind: global function
Returns: Array.<string> - The available keys

| Param | Type | Description | | --- | --- | --- | | key | Key | string | The key to get keys for |