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

Line

Represents a line in a chord sheet, consisting of items of type ChordLyricsPair or Tag

Metadata

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

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

See 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

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

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

Constants

ALBUM : string

Album meta directive. See https://www.chordpro.org/chordpro/directives-album/

ARTIST : string

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

CAPO : string

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

COMMENT : string

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

COMPOSER : string

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

COPYRIGHT : string

Copyright meta directive. See https://www.chordpro.org/chordpro/directives-copyright/

DURATION : string

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

END_OF_CHORUS : string

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

END_OF_TAB : string

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

END_OF_VERSE : string

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

KEY : 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/

LYRICIST : string

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

START_OF_CHORUS : string

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

START_OF_TAB : string

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

START_OF_VERSE : string

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

SUBTITLE : string

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

TEMPO : string

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

TIME : string

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

TITLE : string

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

TRANSPOSE : string

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

NEW_KEY : string

New Key meta directive. See: bettermusic#53

YEAR : string

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

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

VERSE : string

Used to mark a paragraph as verse

CHORUS : string

Used to mark a paragraph as chorus

NONE : string

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

INDETERMINATE : string

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

TAB : string

Used to mark a paragraph as tab

Functions

scopedCss(scope) ⇒ string

Generates basic CSS, scoped within the provided selector, to use with output generated by HtmlTableFormatter

parseChord(chordString) ⇒ null | Chord

Tries to parse a chord string into a chord

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

Line

Represents a line in a chord sheet, consisting of items of type ChordLyricsPair or Tag

Kind: global class

• Line
  • .items : Array.<(ChordLyricsPair|Tag|Comment)>
  • .type : string
  • .isEmpty() ⇒ boolean
  • .addItem(item)
  • .hasRenderableItems() ⇒ boolean
  • .clone() ⇒ Line
  • .isVerse() ⇒ boolean
  • .isChorus() ⇒ boolean
  • .hasContent() ⇒ boolean

line.items : Array.<(ChordLyricsPair|Tag|Comment)>

The items (ChordLyricsPair or Tag or Comment) of which the line consists

Kind: instance property of Line

line.type : string

The line type, This is set by the ChordProParser when it read tags like {start_of_chorus} or {start_of_verse} Values can be VERSE, CHORUS or NONE

Kind: instance property of Line

line.isEmpty() ⇒ boolean

Indicates whether the line contains any items

Kind: instance method of Line

line.addItem(item)

Adds an item (ChordLyricsPair or Tag) to the line

Kind: instance method of Line

Param	Type	Description
item	ChordLyricsPair | Tag	The item to be added

line.hasRenderableItems() ⇒ boolean

Indicates whether the line contains items that are renderable

Kind: instance method of Line

line.clone() ⇒ Line

Returns a deep copy of the line and all of its items

Kind: instance method of Line

line.isVerse() ⇒ boolean

Indicates whether the line type is VERSE

Kind: instance method of Line

line.isChorus() ⇒ boolean

Indicates whether the line type is CHORUS

Kind: instance method of Line

line.hasContent() ⇒ boolean

Deprecated

Indicates whether the line contains items that are renderable. Please use hasRenderableItems

Kind: instance method of Line

Metadata

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

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

See 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
  • .lines : Array.<Line>
  • .type ⇒ string
  • .hasRenderableItems() ⇒ boolean

paragraph.lines : Array.<Line>

The Line items of which the paragraph consists

Kind: instance property of Paragraph

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

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)
  • .lines : Array.<Line>
  • .paragraphs : Array.<Paragraph>
  • .metadata : 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.lines : Array.<Line>

The Line items of which the song consists

Kind: instance property of Song

song.paragraphs : Array.<Paragraph>

The Paragraph items of which the song consists

Kind: instance property of Song

song.metadata : Metadata

The song's metadata. When there is only one value for an entry, the value is a string. Else, the value is an array containing all unique values for the entry.

Kind: instance property of Song

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

Tag

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

Kind: global class

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

tag.name : string

The tag full name. When the original tag used the short name, name will return the full name.

Kind: instance property of Tag

tag.originalName : string

The original tag name that was used to construct the tag.

Kind: instance property of Tag

tag.value : string | null

The tag value

Kind: instance property of Tag

tag.hasValue() ⇒ boolean

Checks whether the tag value is a non-empty string.

Kind: instance method of Tag

tag.isRenderable() ⇒ boolean

Checks whether the tag is usually rendered inline. It currently only applies to comment tags.

Kind: instance method of Tag

tag.isMetaTag() ⇒ boolean

Checks whether the tag is either a standard meta tag or a custom meta directive ({x_some_name})

Kind: instance method of Tag

tag.clone() ⇒ Tag

Returns a clone of the tag.

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

ChordProFormatter

Formats a song into a ChordPro chord sheet

Kind: global class

• ChordProFormatter
  • new ChordProFormatter(options)
  • .format(song) ⇒ string

new ChordProFormatter(options)

Instantiate

Param	Type	Description
options	Object	options
options.evaluate	boolean	Whether or not to evaluate meta expressions. For more info about meta expression, see: https://bit.ly/2SC9c2u

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

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

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

Example:

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

For a CSS string see 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

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 For a CSS string see 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	Description
options	Object	options
options.preserveWhitespace	boolean	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	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
  • .message : string
  • .lineNumber : number
  • .column : number
  • .toString() ⇒ string

parserWarning.message : string

The warning message

Kind: instance property of ParserWarning

parserWarning.lineNumber : number

The chord sheet line number on which the warning occurred

Kind: instance property of ParserWarning

parserWarning.column : number

The chord sheet column on which the warning occurred

Kind: instance property of ParserWarning

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

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

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

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

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

Param	Type	Description
serializedSong	object	The serialized song

ALBUM : string

Album meta directive. See https://www.chordpro.org/chordpro/directives-album/

Kind: global constant

ARTIST : string

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

Kind: global constant

CAPO : string

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

Kind: global constant

COMMENT : string

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

Kind: global constant

COMPOSER : string

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

Kind: global constant

COPYRIGHT : string

Copyright meta directive. See https://www.chordpro.org/chordpro/directives-copyright/

Kind: global constant

DURATION : string

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

Kind: global constant

END_OF_CHORUS : string

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

Kind: global constant

END_OF_TAB : string

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

Kind: global constant

END_OF_VERSE : string

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

Kind: global constant

KEY : string

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

Kind: global constant

_KEY : string

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

Kind: global constant

LYRICIST : string

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

Kind: global constant

START_OF_CHORUS : string

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

Kind: global constant

START_OF_TAB : string

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

Kind: global constant

START_OF_VERSE : string

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

Kind: global constant

SUBTITLE : string

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

Kind: global constant

TEMPO : string

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

Kind: global constant

TIME : string

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

Kind: global constant

TITLE : string

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

Kind: global constant

TRANSPOSE : string

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

Kind: global constant

NEW_KEY : string

New Key meta directive. See: bettermusic#53

Kind: global constant

YEAR : string

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

Kind: global constant

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

Kind: global constant

VERSE : string

Used to mark a paragraph as verse

Kind: global constant

CHORUS : string

Used to mark a paragraph as chorus

Kind: global constant

NONE : string

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

Kind: global constant

INDETERMINATE : string

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

Kind: global constant

TAB : string

Used to mark a paragraph as tab

Kind: global constant

scopedCss(scope) ⇒ string

Generates basic CSS, scoped within the provided selector, to use with output generated by HtmlTableFormatter

Kind: global function
Returns: string - the CSS string

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

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