To help you get started, we've collected the most common ways that chordsheetjs is being used within popular public projects.

ChordSheetJS

A JavaScript library for parsing and formatting chord sheets

Contents

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

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:

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.ChordsOverWordsParser();
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}

{start_of_chorus: Chorus}
Let it [Am]be, let it [C/G]be, let it [F]be, let it [C]be
[C]Whisper words of [G]wisdom, let it [F]be [C/E] [Dm] [C]
{end_of_chorus}`.substring(1);

const parser = new ChordSheetJS.ChordProParser();
const song = parser.parse(chordSheet);

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

Parse

const chord = Chord.parse('Ebsus4/Bb');

Parse numeric chords (Nashville system):

const chord = Chord.parse('b1sus4/#3');

Display with #toString

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

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

Switch modifier

Deprecated

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

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

Transpose up

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

Transpose down

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

Transpose

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

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

Convert numeric chord to chord symbol

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

Supported ChordPro directives

All directives are parsed and are added to Song.metadata. The list below indicates whether formatters actually use those to change the generated output.

✔️ = supported

🕑 = will be supported in a future version

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

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](#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

ChordsOverWordsFormatter

Formats a song into a plain text 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

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

ChordSheetParser is deprecated, please use ChordsOverWordsParser.

ChordsOverWordsParser aims to support any kind of chord, whereas ChordSheetParser lacks support for many variations. Besides that, some chordpro feature have been ported back to ChordsOverWordsParser, which adds some interesting functionality.

ChordsOverWordsParser

Parses a chords over words sheet into a song

It support "regular" chord sheets:

       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

Additionally, some chordpro features have been "ported back". For example, you can use chordpro directives:

{title: Let it be}
{key: C}
Chorus 1:
       Am
Let it be

For convenience, you can leave out the brackets:

title: Let it be
Chorus 1:
       Am
Let it be

You can even use a markdown style frontmatter separator to separate the header from the song:

title: Let it be
key: C
---
Chorus 1:
       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

ChordsOverWordsParser is the better version of ChordSheetParser, which is deprecated.

ParserWarning

Represents a parser warning, currently only used by ChordProParser.

PegBasedParser

Parses a chords over words sheet

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)

Key

Represents a key, such as Eb (symbol), #3 (numeric) or VII (numeral).

The only function considered public API is Key.distance

Constants

ALBUM : string

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

ARRANGER : string

Arranger meta directive. See https://chordpro.org/chordpro/directives-arranger/

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_ABC : string

End of ABC music notation section See https://chordpro.org/chordpro/directives-env_abc/

END_OF_BRIDGE : string

End of bridge directive. See https://chordpro.org/chordpro/directives-env_bridge/

END_OF_CHORUS : string

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

END_OF_GRID : string

End of grid directive. See https://www.chordpro.org/chordpro/directives-env_grid/

END_OF_LY : string

End of Lilypond music notation section See https://chordpro.org/chordpro/directives-env_ly/

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. Reflects the key as transposed by the capo value See https://www.chordpro.org/chordpro/directives-key/

LYRICIST : string

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

SORTTITLE : string

Sorttitle meta directive. See https://chordpro.org/chordpro/directives-sorttitle/

START_OF_ABC : string

Start of ABC music notation section See https://chordpro.org/chordpro/directives-env_abc/

START_OF_BRIDGE : string

Start of bridge directive. See https://chordpro.org/chordpro/directives-env_bridge/

START_OF_CHORUS : string

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

START_OF_GRID : string

Start of grid directive. See https://www.chordpro.org/chordpro/directives-env_grid/

START_OF_LY : string

Start of Lilypond music notation section See https://chordpro.org/chordpro/directives-env_ly/

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: https://github.com/PraiseCharts/ChordChartJS/issues/53

YEAR : string

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

CHORDFONT : string

Chordfont directive. See https://www.chordpro.org/chordpro/directives-props_chord_legacy/

CHORDSIZE : string

Chordfont directive. See https://www.chordpro.org/chordpro/directives-props_chord_legacy/

CHORDCOLOUR : string

Chordfont directive. See https://www.chordpro.org/chordpro/directives-props_chord_legacy/

TEXTFONT : string

Chordfont directive. See https://www.chordpro.org/chordpro/directives-props_text_legacy/

TEXTSIZE : string

Chordfont directive. See https://www.chordpro.org/chordpro/directives-props_text_legacy/

TEXTCOLOUR : string

Chordfont directive. See https://www.chordpro.org/chordpro/directives-props_text_legacy/

TITLEFONT : string

Chordfont directive. See https://www.chordpro.org/chordpro/directives-props_title_legacy/

TITLESIZE : string

Chordfont directive. See https://www.chordpro.org/chordpro/directives-props_title_legacy/

TITLECOLOUR : string

Chordfont directive. See https://www.chordpro.org/chordpro/directives-props_title_legacy/

CHORUS : string

Chorus directive. Support repeating an earlier defined section. See https://www.chordpro.org/chordpro/directives-env_chorus/

CHORD_STYLE : string

Chord type directive. Determines the type of chords used in the rendered chord sheet. Possible values are 'solfege', 'symbol', 'numeral' and 'number'

BRIDGE : string

Used to mark a paragraph as bridge

CHORUS : string

Used to mark a paragraph as chorus

GRID : string

Used to mark a paragraph as grid

INDETERMINATE : string

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

NONE : string

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

TAB : string

Used to mark a paragraph as tab

VERSE : string

Used to mark a paragraph as verse

LILYPOND : string

Used to mark a section as Lilypond notation

ABC : string

Used to mark a section as ABC music notation

Functions

scopedCss(scope) ⇒ string

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

scopedCss(scope) ⇒ string

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

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, annotation)
  • .chords : string
  • .lyrics : string
  • .annotation : string
  • .isRenderable() ⇒ boolean
  • .clone() ⇒ ChordLyricsPair

new ChordLyricsPair(chords, lyrics, annotation)

Initialises a ChordLyricsPair

Param	Type	Default	Description
chords	string		The chords
lyrics	string | null	null	The lyrics
annotation	string | null	null	The annotation

chordLyricsPair.chords : string

The chords

Kind: instance property of ChordLyricsPair

chordLyricsPair.lyrics : string

The lyrics

Kind: instance property of ChordLyricsPair

chordLyricsPair.annotation : string

The annotation

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
  • .isEmpty() ⇒ boolean
  • .addItem(item)
  • .hasRenderableItems() ⇒ boolean
  • .clone() ⇒ Line
  • .isBridge() ⇒ boolean
  • .isChorus() ⇒ boolean
  • .isGrid() ⇒ boolean
  • .isTab() ⇒ boolean
  • .isVerse() ⇒ boolean
  • .hasContent() ⇒ boolean

line.isEmpty() ⇒ boolean

Indicates whether the line contains any items

Kind: instance method of Line

line.addItem(item)

Adds an item ([ChordLyricsPair](#ChordLyricsPair) or [Tag](#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.isBridge() ⇒ boolean

Indicates whether the line type is [BRIDGE](#BRIDGE)

Kind: instance method of Line

line.isChorus() ⇒ boolean

Indicates whether the line type is [CHORUS](#CHORUS)

Kind: instance method of Line

line.isGrid() ⇒ boolean

Indicates whether the line type is [GRID](#GRID)

Kind: instance method of Line

line.isTab() ⇒ boolean

Indicates whether the line type is [TAB](#TAB)

Kind: instance method of Line

line.isVerse() ⇒ boolean

Indicates whether the line type is [VERSE](#VERSE)

Kind: instance method of Line

line.hasContent() ⇒ boolean

Deprecated

Indicates whether the line contains items that are renderable. Please use [hasRenderableItems](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](#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 well 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
  • .contents ⇒ string
  • .label ⇒ string | null
  • .type ⇒ string
  • .isLiteral() ⇒ boolean
  • .hasRenderableItems() ⇒ boolean

paragraph.contents ⇒ string

Returns the paragraph contents as one string where lines are separated by newlines

Kind: instance property of Paragraph

paragraph.label ⇒ string | null

Returns the label of the paragraph. The label is the value of the first section delimiter tag in the first line.

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](#INDETERMINATE)

Kind: instance property of Paragraph

paragraph.isLiteral() ⇒ boolean

Indicates whether the paragraph only contains literals. If true, [contents](contents) can be used to retrieve the paragraph contents as one string where lines are separated by newlines.

Kind: instance method of Paragraph
See: contents

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>
  • .expandedBodyParagraphs : Array.<Paragraph>
  • .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.expandedBodyParagraphs : Array.<Paragraph>

The body paragraphs of the song, with any {chorus} tag expanded into the targeted chorus

Kind: instance property of Song

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

Tag

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

Kind: global class

• Tag
  • .name : string
  • .originalName : string
  • .value : string
  • .hasValue() ⇒ boolean
  • .isRenderable() ⇒ boolean
  • .hasRenderableLabel()
  • .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

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.hasRenderableLabel()

Check whether this tag's label (if any) should be rendered, as applicable to tags like start_of_verse and start_of_chorus. See https://chordpro.org/chordpro/directives-env_chorus/, https://chordpro.org/chordpro/directives-env_verse/, https://chordpro.org/chordpro/directives-env_bridge/, https://chordpro.org/chordpro/directives-env_tab/

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

ChordsOverWordsFormatter

Formats a song into a plain text chord sheet

Kind: global class

chordsOverWordsFormatter.format(song) ⇒ string

Formats a song into a plain text chord sheet

Kind: instance method of ChordsOverWordsFormatter
Returns: string -

the chord sheet

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
[configuration.key]	Key | string		The key to use for rendering. The chord sheet will be transposed from the song's original key (as indicated by the {key} directive) to the specified key. Note that transposing will only work if the original song key is set.
[configuration.expandChorusDirective]	boolean	false	Whether or not to expand {chorus} directives by rendering the last defined chorus inline after the directive.
[configuration.useUnicodeModifiers]	boolean	false	Whether or not to use unicode flat and sharp symbols.
[configuration.normalizeChords]	boolean	true	Whether or not to automatically normalize chords

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

HtmlFormatter

Acts as a base class for HTML formatters

Kind: global class

• HtmlFormatter
  • .cssObject ⇒ Object.<string, Object.<string, string>>
  • .format(song) ⇒ string
  • .cssString(scope) ⇒ string

htmlFormatter.cssObject ⇒ Object.<string, Object.<string, string>>

Basic CSS, in object style à la useStyles, to use with the HTML output For a CSS string see [cssString](cssString)

Example:

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

Kind: instance property of HtmlFormatter
Returns: Object.<string, Object.<string, string>> -

the CSS object

htmlFormatter.format(song) ⇒ string

Formats a song into HTML.

Kind: instance method of HtmlFormatter
Returns: string -

The HTML string

Param	Type	Description
song	Song	The song to be formatted

htmlFormatter.cssString(scope) ⇒ string

Generates basic CSS, optionally scoped within the provided selector, to use with the HTML output

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

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

Kind: instance method of HtmlFormatter
Returns: string -

the CSS string

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

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

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

Deprecated

Parses a normal chord sheet

ChordSheetParser is deprecated, please use ChordsOverWordsParser.

ChordsOverWordsParser aims to support any kind of chord, whereas ChordSheetParser lacks support for many variations. Besides that, some chordpro feature have been ported back to ChordsOverWordsParser, which adds some interesting functionality.

Kind: global class

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

new ChordSheetParser([options])

Instantiate a chord sheet parser ChordSheetParser is deprecated, please use ChordsOverWordsParser.

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

ChordsOverWordsParser

Parses a chords over words sheet into a song

It support "regular" chord sheets:

       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

Additionally, some chordpro features have been "ported back". For example, you can use chordpro directives:

{title: Let it be}
{key: C}
Chorus 1:
       Am
Let it be

For convenience, you can leave out the brackets:

title: Let it be
Chorus 1:
       Am
Let it be

You can even use a markdown style frontmatter separator to separate the header from the song:

title: Let it be
key: C
---
Chorus 1:
       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

ChordsOverWordsParser is the better version of ChordSheetParser, which is deprecated.

Kind: global class

chordsOverWordsParser.parse(chordsOverWordsSheet) ⇒ Song

Parses a chords over words sheet into a song

Kind: instance method of ChordsOverWordsParser
Returns: Song -

The parsed song

Param	Type	Description
chordsOverWordsSheet	string	the chords over words sheet

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

PegBasedParser

Parses a chords over words sheet

Kind: global class

pegBasedParser.warnings : Array.<ParserWarning>

All warnings raised during parsing the chord sheet

Kind: instance property of PegBasedParser

UltimateGuitarParser

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

Kind: global class

new UltimateGuitarParser([options])

Instantiate a chord sheet parser

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

Chord

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

Kind: global class

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

chord.clone() ⇒ Chord

Returns a deep copy of the chord

Kind: instance method of Chord

chord.toChordSymbol([referenceKey]) ⇒ 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
[referenceKey]	Key | string | null		the reference key. The key is required when converting a numeric or numeral.

chord.toChordSymbolString([referenceKey]) ⇒ 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
[referenceKey]	Key | string | null		the reference key. The key is required when converting a numeric or numeral.

chord.isChordSymbol() ⇒ boolean

Determines whether the chord is a chord symbol

Kind: instance method of Chord

chord.toChordSolfege([referenceKey]) ⇒ Chord

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

Kind: instance method of Chord
Returns: Chord -

the chord solfege

Param	Type	Default	Description
[referenceKey]	Key | string | null		the reference key. The key is required when converting a numeric or numeral.

chord.toChordSolfegeString([referenceKey]) ⇒ string

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

Kind: instance method of Chord
Returns: string -

the chord solfege string

See: {toChordSolfege}

Param	Type	Default	Description
[referenceKey]	Key | string | null		the reference key. The key is required when converting a numeric or numeral.

chord.isChordSolfege() ⇒ boolean

Determines whether the chord is a chord solfege

Kind: instance method of Chord

chord.toNumeric([referenceKey]) ⇒ 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
[referenceKey]	Key | string | null		the reference key. The key is required when converting a chord symbol

chord.toNumeral([referenceKey]) ⇒ 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
[referenceKey]	Key | string | null		the reference key. The key is required when converting a chord symbol

chord.toNumeralString([referenceKey]) ⇒ 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
[referenceKey]	Key | string | null		the reference key. The key is required when converting a chord symbol

chord.isNumeric() ⇒ boolean

Determines whether the chord is numeric

Kind: instance method of Chord

chord.toNumericString([referenceKey]) ⇒ 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
[referenceKey]	Key | string | null