@samiam21/chordsheetjs

A JavaScript library for parsing and formatting chord sheets


Keywords
javascript, parsing, chords, chordpro, chord-sheet
License
ISC
Install
npm install @samiam21/chordsheetjs@4.1.1

Documentation

ChordSheetJS Build Status npm version Code Climate

A JavaScript library for parsing and formatting chord sheets

Contents

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

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

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

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

YEAR : string

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

ChordLyricsPair

Represents a chord with the corresponding (partial) lyrics

Kind: global class

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

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

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

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>

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

Song

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

Kind: global class

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

Tag

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

Kind: global class

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

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

TextFormatter

Formats a sonf 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>

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

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

The warning message

Kind: instance property of ParserWarning

parserWarning.lineNumber : integer

The chord sheet line number 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

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

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

YEAR : string

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

Kind: global constant