Name	Name	Last commit message	Last commit date
Latest commit martijnversluis 6.2.0 Apr 16, 2022 a41982f · Apr 16, 2022 History 563 Commits
.github	.github	Implement browserify build (#488 )	Apr 16, 2022
.husky	.husky	Add Husky pre-commit hook to re-generate README.md on commit (#462 )	Feb 18, 2022
doc	doc	Implement Song#setCapo and Song#setKey (#467 )	Feb 27, 2022
src	src	Implement browserify build (#488 )	Apr 16, 2022
test	test	Extract ChordLyricsPair#transpose (#487 )	Apr 15, 2022
.codeclimate.yml	.codeclimate.yml	Generate default CSS for HTML formatters (#325 )	May 29, 2021
.eslintignore	.eslintignore	Typescript conversion (#480 )	Apr 15, 2022
.eslintrc.js	.eslintrc.js	Typescript conversion (#480 )	Apr 15, 2022
.gitignore	.gitignore	Implement browserify build (#488 )	Apr 16, 2022
.parcelrc	.parcelrc	Typescript conversion (#480 )	Apr 15, 2022
LICENSE	LICENSE	Add license	Aug 20, 2017
README.md	README.md	Typescript conversion (#480 )	Apr 15, 2022
jest.config.js	jest.config.js	Typescript conversion (#480 )	Apr 15, 2022
jsdoc2md.json	jsdoc2md.json	Typescript conversion (#480 )	Apr 15, 2022
package.json	package.json	6.2.0	Apr 16, 2022
tsconfig.json	tsconfig.json	Implement browserify build (#488 )	Apr 16, 2022
yarn.lock	yarn.lock	Bump @typescript-eslint/parser from 5.18.0 to 5.19.0 (#484 )	Apr 16, 2022

ChordChartJS

A JavaScript library for parsing and formatting chord sheets

Contents

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

Installation

ChordSheetJS is on npm, to install run:

npm install chordsheetjs

Load with import:

import ChordSheetJS from 'chordsheetjs';

or require():

var ChordSheetJS = require('chordsheetjs').default;

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

✔️ = supported

🕑 = will be supported in a future version

✖️ = currently no plans to support it in the near future

Meta-data directives

Directive	Support
title (short: t)	✔️
subtitle	✔️
artist	✔️
composer	✔️
lyricist	✔️
copyright	✔️
album	✔️
year	✔️
key	✔️
time	✔️
tempo	✔️
duration	✔️
capo	✔️
meta	✔️

Formatting directives

Directive	Support
comment (short: c)	✔️
comment_italic (short: ci)	✖️
comment_box (short: cb)	✖️
chorus	✖️
image	✖️

Environment directives

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	✖️

Chord diagrams

Directive	Support
define	✖️
chord	✖️

Fonts, sizes and colours

Directive	Support
textfont	🕑
textsize	🕑
textcolour	🕑
chordfont	🕑
chordsize	🕑
chordcolour	🕑
tabfont	✖️
tabsize	✖️
tabcolour	✖️

Output related directives

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)	✖️

Custom extensions

Directive	Support
x_	✔️

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. 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: bettermusic#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>
- ~~.metaData ⇒~~
- .clone() ⇒ Song
- .setCapo(capo) ⇒ Song
- .setKey(key) ⇒ 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.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.setCapo(capo) ⇒ `Song`

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

the value for capo in the 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.setKey(key) ⇒ `Song`

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

the value for key in the 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
key	`string`	The new key.

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() ⇒ 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() ⇒ `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. 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

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. 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: bettermusic#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

License

martijnversluis/ChordSheetJS

Folders and files

Latest commit

History

Repository files navigation

ChordChartJS

Installation

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.metaData ⇒

song.clone() ⇒ Song

song.setCapo(capo) ⇒ Song

song.setKey(key) ⇒ Song

Tag

tag.name : string

tag.originalName : string

tag.value : string | null

tag.hasValue() ⇒ boolean

tag.isRenderable() ⇒ boolean

tag.isMetaTag() ⇒ boolean

tag.clone() ⇒ Tag

ChordProFormatter

chordProFormatter.format(song) ⇒ string

Formatter

new Formatter([configuration])

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.clone() ⇒ `Song`

song.setCapo(capo) ⇒ `Song`

song.setKey(key) ⇒ `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() ⇒ `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`

TITLE : `string`

TRANSPOSE : `string`

NEW_KEY : `string`

defaultCss ⇒ `string`

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