ChordSheetJS

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

ChordLyricsPair

Represents a chord with the corresponding (partial) lyrics

Comment

Represents a comment. See https://www.chordpro.org/chordpro/chordpro-file-format-specification/#overview

Metadata

Stores song metadata. Properties can be accessed using the get() method:

const metadata = new Metadata({ author: 'John' }); metadata.get('author') // => 'John'

See [get](#Metadata+get)

Paragraph

Represents a paragraph of lines in a chord sheet

Song

Represents a song in a chord sheet. Currently a chord sheet can only have one song.

Tag

Represents a tag/directive. See https://www.chordpro.org/chordpro/chordpro-directives/

ChordProFormatter

Formats a song into a ChordPro chord sheet

Formatter

Base class for all formatters, taking care of receiving a configuration wrapping that inside a Configuration object

HtmlDivFormatter

Formats a song into HTML. It uses DIVs to align lyrics with chords, which makes it useful for responsive web pages.

HtmlFormatter

Acts as a base class for HTML formatters, taking care of whitelisting prototype property access.

HtmlTableFormatter

Formats a song into HTML. It uses TABLEs to align lyrics with chords, which makes the HTML for things like PDF conversion.

TextFormatter

Formats a song into a plain text chord sheet

ChordProParser

Parses a ChordPro chord sheet

ChordSheetParser

Parses a normal chord sheet

ParserWarning

Represents a parser warning, currently only used by ChordProParser.

UltimateGuitarParser

Parses an Ultimate Guitar chord sheet with metadata Inherits from [ChordSheetParser](#ChordSheetParser)

Chord

Represents a Chord, consisting of a root, suffix (quality) and bass

ChordSheetSerializer

Serializes a song into een plain object, and deserializes the serialized object back into a [Song](#Song)

Members

ALBUM : string: Artist meta directive. See https://www.chordpro.org/chordpro/directives-artist/
ARTIST : string: Capo meta directive. See https://www.chordpro.org/chordpro/directives-capo/
CAPO : string: Comment directive. See https://www.chordpro.org/chordpro/directives-comment/
COMMENT : string: Composer meta directive. See https://www.chordpro.org/chordpro/directives-composer/
COMPOSER : string: Copyright meta directive. See https://www.chordpro.org/chordpro/directives-copyright/
COPYRIGHT : string: Duration meta directive. See https://www.chordpro.org/chordpro/directives-duration/
DURATION : string: End of chorus directive. See https://www.chordpro.org/chordpro/directives-env_chorus/
END_OF_CHORUS : string: End of tab directive. See https://www.chordpro.org/chordpro/directives-env_tab/
END_OF_TAB : string: End of verse directive. See https://www.chordpro.org/chordpro/directives-env_verse/
END_OF_VERSE : string: Key meta directive. See https://www.chordpro.org/chordpro/directives-key/
KEY : string: _Key meta directive. Reflects the key as transposed by the capo value See https://www.chordpro.org/chordpro/directives-key/
_KEY : string: Lyricist meta directive. See https://www.chordpro.org/chordpro/directives-lyricist/
LYRICIST : string: Start of chorus directive. See https://www.chordpro.org/chordpro/directives-env_chorus/
START_OF_CHORUS : string: Start of tab directive. See https://www.chordpro.org/chordpro/directives-env_tab/
START_OF_TAB : string: Start of verse directive. See https://www.chordpro.org/chordpro/directives-env_verse/
START_OF_VERSE : string: Subtitle meta directive. See https://www.chordpro.org/chordpro/directives-subtitle/
SUBTITLE : string: Tempo meta directive. See https://www.chordpro.org/chordpro/directives-tempo/
TEMPO : string: Time meta directive. See https://www.chordpro.org/chordpro/directives-time/
TIME : string: Title meta directive. See https://www.chordpro.org/chordpro/directives-title/
TITLE : string: Transpose meta directive. See: https://www.chordpro.org/chordpro/directives-transpose/
TRANSPOSE : string: New Key meta directive. See: https://github.com/PraiseCharts/ChordChartJS/issues/53
NEW_KEY : string: Year meta directive. See https://www.chordpro.org/chordpro/directives-year/
defaultCss ⇒ string: Generates basic CSS, scoped within the provided selector, to use with output generated by [HtmlTableFormatter](#HtmlTableFormatter)

Constants

defaultCss : Object.<string, Object.<string, string>>: Basic CSS, in object style à la useStyles, to use with output generated by {@link }HtmlTableFormatter} For a CSS string see [scopedCss](scopedCss)
VERSE : string: Used to mark a paragraph as verse
VERSE : string: Used to mark a paragraph as chorus
CHORUS : string: Used to mark a paragraph as not containing a line marked with a type
NONE : string: Used to mark a paragraph as containing lines with both verse and chorus type
INDETERMINATE : string: Used to mark a paragraph as tab

Functions

~~parseChord(chordString) ⇒ null | Chord~~: Tries to parse a chord string into a chord
getCapos(key) ⇒ Object.<string, string>: Returns applicable capos for the provided key
getKeys(key) ⇒ Array.<string>: Returns applicable keys to transpose to from the provided key

ChordLyricsPair

Represents a chord with the corresponding (partial) lyrics

Kind: global class

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

new ChordLyricsPair(chords, lyrics)

Initialises a ChordLyricsPair

Param	Type	Description
chords	`string`	The chords
lyrics	`string`	The lyrics

chordLyricsPair.chords : `string`

The chords

Kind: instance property of ChordLyricsPair

chordLyricsPair.lyrics : `string`

The lyrics

Kind: instance property of ChordLyricsPair

chordLyricsPair.isRenderable() ⇒ `boolean`

Indicates whether a ChordLyricsPair should be visible in a formatted chord sheet (except for ChordPro sheets)

Kind: instance method of ChordLyricsPair

chordLyricsPair.clone() ⇒ `ChordLyricsPair`

Returns a deep copy of the ChordLyricsPair, useful when programmatically transforming a song

Kind: instance method of ChordLyricsPair

Comment

Represents a comment. See https://www.chordpro.org/chordpro/chordpro-file-format-specification/#overview

Kind: global class

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

comment.isRenderable() ⇒ `boolean`

Indicates whether a Comment should be visible in a formatted chord sheet (except for ChordPro sheets)

Kind: instance method of Comment

comment.clone() ⇒ `Comment`

Returns a deep copy of the Comment, useful when programmatically transforming a song

Kind: instance method of Comment

Metadata

Stores song metadata. Properties can be accessed using the get() method:

const metadata = new Metadata({ author: 'John' }); metadata.get('author') // => 'John'

See [get](#Metadata+get)

Kind: global class

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

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

Reads a metadata value by key. This method supports simple value lookup, as fetching single array values.

This method deprecates direct property access, eg: metadata['author']

Examples:

const metadata = new Metadata({ lyricist: 'Pete', author: ['John', 'Mary'] }); metadata.get('lyricist') // => 'Pete' metadata.get('author') // => ['John', 'Mary'] metadata.get('author.1') // => 'John' metadata.get('author.2') // => 'Mary'

Using a negative index will start counting at the end of the list:

const metadata = new Metadata({ lyricist: 'Pete', author: ['John', 'Mary'] }); metadata.get('author.-1') // => 'Mary' metadata.get('author.-2') // => 'John'

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`

Returns a deep clone of this Metadata object

Kind: instance method of Metadata
Returns: Metadata -

the cloned Metadata object

Paragraph

Represents a paragraph of lines in a chord sheet

Kind: global class

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

paragraph.type ⇒ `string`

Tries to determine the common type for all lines. If the types for all lines are equal, it returns that type. If not, it returns [INDETERMINATE](#INDETERMINATE)

Kind: instance property of Paragraph

paragraph.hasRenderableItems() ⇒ `boolean`

Indicates whether the paragraph contains lines with renderable items.

Kind: instance method of Paragraph
See: Line.hasRenderableItems

Song

Represents a song in a chord sheet. Currently a chord sheet can only have one 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)

Creates a new {Song} instance

Param	Type	Description
metadata	`Object` \| `Metadata`	predefined metadata

song.bodyLines ⇒ `Array.<Line>`

Returns the song lines, skipping the leading empty lines (empty as in not rendering any content). This is useful if you want to skip the "header lines": the lines that only contain meta data.

Kind: instance property of Song
Returns: Array.<Line> -

The song body lines

song.bodyParagraphs ⇒ `Array.<Paragraph>`

Returns the song paragraphs, skipping the paragraphs that only contain empty lines (empty as in not rendering any content)

Kind: instance property of Song
See: bodyLines

song.paragraphs : `Array.<Paragraph>`

The [Paragraph](#Paragraph) items of which the song consists

Kind: instance property of Song

song.metaData ⇒

Deprecated

The song's metadata. Please use [metadata](metadata) instead.

Kind: instance property of Song
Returns:

Metadata The metadata

song.clone() ⇒ `Song`

Returns a deep clone of the song

Kind: instance method of Song
Returns: Song -

The cloned song

song.setKey(key) ⇒ `Song`

Returns a copy of the song with the key value set to the specified key. It changes:

the value for key in the [metadata](metadata) set
any existing key directive

Kind: instance method of Song
Returns: Song -

The changed song

Param Type Description

key

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

number | null

the key. Passing null will:

remove the current key from metadata
remove any key directive

song.setCapo(capo) ⇒ `Song`

Returns a copy of the song with the key value set to the specified capo. It changes:

the value for capo in the [metadata](metadata) set
any existing capo directive

Kind: instance method of Song
Returns: Song -

The changed song

Param Type Description

capo

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

number | null

the capo. Passing null will:

remove the current key from metadata
remove any capo directive

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

Transposes the song by the specified delta. It will:

transpose all chords, see: [transpose](#Chord+transpose)
transpose the song key in [metadata](metadata)
update any existing key directive

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`

Transposes the song up by one semitone. It will:

transpose all chords, see: [transpose](#Chord+transpose)
transpose the song key in [metadata](metadata)
update any existing key directive

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`

Transposes the song down by one semitone. It will:

transpose all chords, see: [transpose](#Chord+transpose)
transpose the song key in [metadata](metadata)
update any existing key directive

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`

Returns a copy of the song with the key set to the specified key. It changes:

the value for key in the [metadata](metadata) set
any existing key directive
all chords, those are transposed according to the distance between the current and the new key

Kind: instance method of Song
Returns: Song -

The changed song

Param	Type	Description
newKey	`string`	The new key.

song.changeMetadata(name, value)

Returns a copy of the song with the directive value set to the specified value.

when there is a matching directive in the song, it will update the directive
when there is no matching directive, it will be inserted If value is null it will act as a delete, any directive matching name will be removed.

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`

Change the song contents inline. Return a new [Item](Item) to replace it. Return null to remove it.

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`

Change the song contents inline. Return a new [Line](Line) to replace it. Return null to remove it.

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

ChordProFormatter

Formats a song into a ChordPro chord sheet

Kind: global class

chordProFormatter.format(song) ⇒ `string`

Formats a song into a ChordPro chord sheet.

Kind: instance method of ChordProFormatter
Returns: string -

The ChordPro string

Param	Type	Description
song	`Song`	The song to be formatted

Formatter

Base class for all formatters, taking care of receiving a configuration wrapping that inside a Configuration object

Kind: global class

new Formatter([configuration])

Instantiate

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`	`"", ""`	The separator to be used when rendering a metadata value that has multiple values. See: https://bit.ly/2SC9c2u

HtmlDivFormatter

Formats a song into HTML. It uses DIVs to align lyrics with chords, which makes it useful for responsive web pages.

Kind: global class

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

htmlDivFormatter.format(song) ⇒ `string`

Formats a song into HTML.

Kind: instance method of HtmlDivFormatter
Returns: string -

The HTML string

Param	Type	Description
song	`Song`	The song to be formatted

HtmlDivFormatter.cssString(scope) ⇒ `string`

Generates basic CSS, optionally scoped within the provided selector, to use with output generated by [HtmlDivFormatter](#HtmlDivFormatter)

For example, execute cssString('.chordSheetViewer') will result in CSS like:

.chordSheetViewer .paragraph {
  margin-bottom: 1em;
}

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>>`

Basic CSS, in object style à la useStyles, to use with output generated by [HtmlDivFormatter](#HtmlDivFormatter)

Example:

'.paragraph': {
  marginBottom: '1em'
}

For a CSS string see [cssString](cssString)

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

the CSS object

HtmlFormatter

Acts as a base class for HTML formatters, taking care of whitelisting prototype property access.

Kind: global class

HtmlTableFormatter

Formats a song into HTML. It uses TABLEs to align lyrics with chords, which makes the HTML for things like PDF conversion.

Kind: global class

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

htmlTableFormatter.format(song) ⇒ `string`

Formats a song into HTML.

Kind: instance method of HtmlTableFormatter
Returns: string -

The HTML string

Param	Type	Description
song	`Song`	The song to be formatted

HtmlTableFormatter.cssString(scope) ⇒ `string`

Generates basic CSS, optionally scoped within the provided selector, to use with output generated by [HtmlTableFormatter](#HtmlTableFormatter)

For example, execute cssString('.chordSheetViewer') will result in CSS like:

.chordSheetViewer .paragraph {
  margin-bottom: 1em;
}

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>>`

Basic CSS, in object style à la useStyles, to use with output generated by [HtmlTableFormatter](#HtmlTableFormatter) For a CSS string see [cssString](cssString)

Example:

'.paragraph': {
  marginBottom: '1em'
}

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

the CSS object

TextFormatter

Formats a song into a plain text chord sheet

Kind: global class

textFormatter.format(song) ⇒ `string`

Formats a song into a plain text chord sheet

Kind: instance method of TextFormatter
Returns: string -

the chord sheet

Param	Type	Description
song	`Song`	The song to be formatted

ChordProParser

Parses a ChordPro chord sheet

Kind: global class

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

chordProParser.warnings : `Array.<ParserWarning>`

All warnings raised during parsing the ChordPro chord sheet

Kind: instance property of ChordProParser

chordProParser.parse(chordProChordSheet) ⇒ `Song`

Parses a ChordPro chord sheet into a song

Kind: instance method of ChordProParser
Returns: Song -

The parsed song

Param	Type	Description
chordProChordSheet	`string`	the ChordPro chord sheet

ChordSheetParser

Parses a normal chord sheet

Kind: global class

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

new ChordSheetParser([options])

Instantiate a chord sheet parser

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

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

Parses a chord sheet into a 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

Represents a parser warning, currently only used by ChordProParser.

Kind: global class

parserWarning.toString() ⇒ `string`

Returns a stringified version of the warning

Kind: instance method of ParserWarning
Returns: string -

The string warning

UltimateGuitarParser

Parses an Ultimate Guitar chord sheet with metadata Inherits from [ChordSheetParser](#ChordSheetParser)

Kind: global class

Chord

Represents a Chord, consisting of a root, suffix (quality) and bass

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`

Returns a deep copy of the chord

Kind: instance method of Chord

chord.toChordSymbol([key]) ⇒ `Chord`

Converts the chord to a chord symbol, using the supplied key as a reference. For example, a numeric chord #4 with reference key E will return the chord symbol A#. When the chord is already a chord symbol, it will return a clone of the object.

Kind: instance method of Chord
Returns: Chord -

the chord symbol

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

chord.toChordSymbolString([key]) ⇒ `string`

Converts the chord to a chord symbol string, using the supplied key as a reference. For example, a numeric chord #4 with reference key E will return the chord symbol A#. When the chord is already a chord symbol, it will return a string version of the chord.

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`

Determines whether the chord is a chord symbol

Kind: instance method of Chord

chord.toNumeric([key]) ⇒ `Chord`

Converts the chord to a numeric chord, using the supplied key as a reference. For example, a chord symbol A# with reference key E will return the numeric chord #4.

Kind: instance method of Chord
Returns: Chord -

the numeric chord

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

chord.toNumeral(key) ⇒ `Chord`

Converts the chord to a numeral chord, using the supplied key as a reference. For example, a chord symbol A# with reference key E will return the numeral chord #IV.

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`

Converts the chord to a numeral chord string, using the supplied kye as a reference. For example, a chord symbol A# with reference key E will return the numeral chord #4.

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`

Determines whether the chord is numeric

Kind: instance method of Chord

chord.toNumericString([key]) ⇒ `string`

Converts the chord to a numeric chord string, using the supplied kye as a reference. For example, a chord symbol A# with reference key E will return the numeric chord #4.

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`

Determines whether the chord is a numeral

Kind: instance method of Chord

chord.toString() ⇒ `string`

Converts the chord to a string, eg Esus4/G# or 1sus4/#3

Kind: instance method of Chord
Returns: string -

the chord string

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

Normalizes the chord root and bass notes:

Fb becomes E
Cb becomes B
B# becomes C
E# becomes F
4b becomes 3
1b becomes 7
7# becomes 1
3# becomes 4

Besides that it normalizes the suffix if normalizeSuffix is true. For example, sus2 becomes 2, sus4 becomes sus. All suffix normalizations can be found in src/normalize_mappings/suffix-mapping.txt.

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`

Switches to the specified modifier

Kind: instance method of Chord
Returns: Chord -

the new, changed chord

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

chord.transposeUp() ⇒ `Chord`

Transposes the chord up by 1 semitone. Eg. A becomes A#, Eb becomes E

Kind: instance method of Chord
Returns: Chord -

the new, transposed chord

chord.transposeDown() ⇒ `Chord`

Transposes the chord down by 1 semitone. Eg. A# becomes A, E becomes Eb

Kind: instance method of Chord
Returns: Chord -

the new, transposed chord

chord.transpose(delta) ⇒ `Chord`

Transposes the chord by the specified number of semitones

Kind: instance method of Chord
Returns: Chord -

the new, transposed chord

Param	Description
delta	de number of semitones

Chord.parse(chordString) ⇒ `null` | `Chord`

Tries to parse a chord string into a chord

Kind: static method of Chord

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

ChordSheetSerializer

Serializes a song into een plain object, and deserializes the serialized object back into a [Song](#Song)

Kind: global class

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

chordSheetSerializer.serialize() ⇒

Serializes the chord sheet to a plain object, which can be converted to any format like JSON, XML etc Can be deserialized using [deserialize](deserialize)

Kind: instance method of ChordSheetSerializer
Returns:

object A plain JS object containing all chord sheet data

chordSheetSerializer.deserialize(serializedSong) ⇒ `Song`

Deserializes a song that has been serialized using [serialize](serialize)

Kind: instance method of ChordSheetSerializer
Returns: Song -

The deserialized song

Param	Type	Description
serializedSong	`object`	The serialized song

ALBUM : `string`

Artist meta directive. See https://www.chordpro.org/chordpro/directives-artist/

Kind: global variable

ARTIST : `string`

Capo meta directive. See https://www.chordpro.org/chordpro/directives-capo/

Kind: global variable

CAPO : `string`

Comment directive. See https://www.chordpro.org/chordpro/directives-comment/

Kind: global variable

COMMENT : `string`

Composer meta directive. See https://www.chordpro.org/chordpro/directives-composer/

Kind: global variable

COMPOSER : `string`

Kind: global variable

COPYRIGHT : `string`

Duration meta directive. See https://www.chordpro.org/chordpro/directives-duration/

Kind: global variable

DURATION : `string`

End of chorus directive. See https://www.chordpro.org/chordpro/directives-env_chorus/

Kind: global variable

END_OF_CHORUS : `string`

End of tab directive. See https://www.chordpro.org/chordpro/directives-env_tab/

Kind: global variable

END_OF_TAB : `string`

End of verse directive. See https://www.chordpro.org/chordpro/directives-env_verse/

Kind: global variable

END_OF_VERSE : `string`

Key meta directive. See https://www.chordpro.org/chordpro/directives-key/

Kind: global variable

KEY : `string`

_Key meta directive. Reflects the key as transposed by the capo value See https://www.chordpro.org/chordpro/directives-key/

Kind: global variable

_KEY : `string`

Lyricist meta directive. See https://www.chordpro.org/chordpro/directives-lyricist/

Kind: global variable

LYRICIST : `string`

Start of chorus directive. See https://www.chordpro.org/chordpro/directives-env_chorus/

Kind: global variable

START_OF_CHORUS : `string`

Start of tab directive. See https://www.chordpro.org/chordpro/directives-env_tab/

Kind: global variable

START_OF_TAB : `string`

Start of verse directive. See https://www.chordpro.org/chordpro/directives-env_verse/

Kind: global variable

START_OF_VERSE : `string`

Subtitle meta directive. See https://www.chordpro.org/chordpro/directives-subtitle/

Kind: global variable

SUBTITLE : `string`

Tempo meta directive. See https://www.chordpro.org/chordpro/directives-tempo/

Kind: global variable

TEMPO : `string`

Time meta directive. See https://www.chordpro.org/chordpro/directives-time/

Kind: global variable

TIME : `string`

Title meta directive. See https://www.chordpro.org/chordpro/directives-title/

Kind: global variable

TITLE : `string`

Transpose meta directive. See: https://www.chordpro.org/chordpro/directives-transpose/

Kind: global variable

TRANSPOSE : `string`

New Key meta directive. See: https://github.com/PraiseCharts/ChordChartJS/issues/53

Kind: global variable

NEW_KEY : `string`

Year meta directive. See https://www.chordpro.org/chordpro/directives-year/

Kind: global variable

defaultCss ⇒ `string`

Generates basic CSS, scoped within the provided selector, to use with output generated by [HtmlTableFormatter](#HtmlTableFormatter)

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>>`

Basic CSS, in object style à la useStyles, to use with output generated by {@link }HtmlTableFormatter} For a CSS string see [scopedCss](scopedCss)

Kind: global constant

VERSE : `string`

Used to mark a paragraph as verse

Kind: global constant

VERSE : `string`

Used to mark a paragraph as chorus

Kind: global constant

CHORUS : `string`

Used to mark a paragraph as not containing a line marked with a type

Kind: global constant

NONE : `string`

Used to mark a paragraph as containing lines with both verse and chorus type

Kind: global constant

INDETERMINATE : `string`

Used to mark a paragraph as tab

Kind: global constant

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

Deprecated

Tries to parse a chord string into a chord

Kind: global function

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

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

Returns applicable capos for the provided key

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>`

Returns applicable keys to transpose to from the provided key

Kind: global function
Returns: Array.<string> -

The available keys

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

ChordSheetJS ChordSheetJS copied to clipboard

Metadata

ChordSheetJS

Installation

Package managers

Standalone bundle file

How to ...?

Parse chord sheet

Regular chord sheets

Ultimate Guitar chord sheets

Chord pro format

Display a parsed sheet

Plain text format

HTML format

Table-based layout

Div-based layout

Chord pro format

Serialize/deserialize

Add styling

Parsing and modifying chords

Parse

Display with #toString

Clone

Normalize

Switch modifier

Use specific modifier

Transpose up

Transpose down

Transpose

Convert numeric chord to chord symbol

Supported ChordPro directives

Meta-data directives

Formatting directives

Environment directives

Chord diagrams

Fonts, sizes and colours

Output related directives

Custom extensions

API docs

Classes

Members

Constants

Functions

ChordLyricsPair

new ChordLyricsPair(chords, lyrics)

chordLyricsPair.chords : string

chordLyricsPair.lyrics : string

chordLyricsPair.isRenderable() ⇒ boolean

chordLyricsPair.clone() ⇒ ChordLyricsPair

Comment

comment.isRenderable() ⇒ boolean

comment.clone() ⇒ Comment

Metadata

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

metadata.clone() ⇒ Metadata

Paragraph

paragraph.type ⇒ string

paragraph.hasRenderableItems() ⇒ boolean

Song

new Song(metadata)

song.bodyLines ⇒ Array.<Line>

song.bodyParagraphs ⇒ Array.<Paragraph>

song.paragraphs : Array.<Paragraph>

~~song.metaData ⇒~~

song.clone() ⇒ Song

song.setKey(key) ⇒ Song

song.setCapo(capo) ⇒ Song

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

song.transposeUp([options]) ⇒ Song

song.transposeDown([options]) ⇒ Song

song.changeKey(newKey) ⇒ Song

song.changeMetadata(name, value)

song.mapItems(func) ⇒ Song

song.mapLines(func) ⇒ Song

Tag

tag.name : string

tag.originalName : string

tag.value : string | null

tag.hasValue() ⇒ boolean

tag.isRenderable() ⇒ boolean

ChordSheetJS
ChordSheetJS copied to clipboard

chordLyricsPair.chords : `string`

chordLyricsPair.lyrics : `string`

chordLyricsPair.isRenderable() ⇒ `boolean`

chordLyricsPair.clone() ⇒ `ChordLyricsPair`

comment.isRenderable() ⇒ `boolean`

comment.clone() ⇒ `Comment`

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

metadata.clone() ⇒ `Metadata`

paragraph.type ⇒ `string`

paragraph.hasRenderableItems() ⇒ `boolean`

song.bodyLines ⇒ `Array.<Line>`

song.bodyParagraphs ⇒ `Array.<Paragraph>`

song.paragraphs : `Array.<Paragraph>`

song.metaData ⇒

song.clone() ⇒ `Song`

song.setKey(key) ⇒ `Song`

song.setCapo(capo) ⇒ `Song`

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

song.transposeUp([options]) ⇒ `Song`

song.transposeDown([options]) ⇒ `Song`

song.changeKey(newKey) ⇒ `Song`

song.mapItems(func) ⇒ `Song`

song.mapLines(func) ⇒ `Song`

tag.name : `string`

tag.originalName : `string`

tag.value : `string` | `null`

tag.hasValue() ⇒ `boolean`

tag.isRenderable() ⇒ `boolean`

tag.isMetaTag() ⇒ `boolean`

tag.clone() ⇒ `Tag`

chordProFormatter.format(song) ⇒ `string`

htmlDivFormatter.format(song) ⇒ `string`

HtmlDivFormatter.cssString(scope) ⇒ `string`

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

htmlTableFormatter.format(song) ⇒ `string`

HtmlTableFormatter.cssString(scope) ⇒ `string`

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

textFormatter.format(song) ⇒ `string`

chordProParser.warnings : `Array.<ParserWarning>`

chordProParser.parse(chordProChordSheet) ⇒ `Song`

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

parserWarning.toString() ⇒ `string`

chord.clone() ⇒ `Chord`

chord.toChordSymbol([key]) ⇒ `Chord`

chord.toChordSymbolString([key]) ⇒ `string`

chord.isChordSymbol() ⇒ `boolean`

chord.toNumeric([key]) ⇒ `Chord`

chord.toNumeral(key) ⇒ `Chord`

chord.toNumeralString([key]) ⇒ `string`

chord.isNumeric() ⇒ `boolean`

chord.toNumericString([key]) ⇒ `string`

chord.isNumeral() ⇒ `boolean`

chord.toString() ⇒ `string`

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

chord.useModifier(newModifier) ⇒ `Chord`

chord.transposeUp() ⇒ `Chord`

chord.transposeDown() ⇒ `Chord`

chord.transpose(delta) ⇒ `Chord`

Chord.parse(chordString) ⇒ `null` | `Chord`

chordSheetSerializer.deserialize(serializedSong) ⇒ `Song`

ALBUM : `string`

ARTIST : `string`

CAPO : `string`

COMMENT : `string`

COMPOSER : `string`

COPYRIGHT : `string`

DURATION : `string`

END_OF_CHORUS : `string`

END_OF_TAB : `string`

END_OF_VERSE : `string`

KEY : `string`

_KEY : `string`

LYRICIST : `string`

START_OF_CHORUS : `string`

START_OF_TAB : `string`

START_OF_VERSE : `string`

SUBTITLE : `string`

TEMPO : `string`

TIME : `string`