ChordSheetJS

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

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

:heavy_check_mark: = supported

:clock2: = will be supported in a future version

:heavy_multiplication_x: = currently no plans to support it in the near future

Meta-data directives

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

Formatting directives

| Directive | Support | |:-------------------------- |:------------------------:| | comment (short: c) | :heavy_check_mark: | | comment_italic (short: ci) | :heavy_multiplication_x: | | comment_box (short: cb) | :heavy_multiplication_x: | | chorus | :heavy_multiplication_x: | | image | :heavy_multiplication_x: |

Environment directives

| Directive | Support | |:---------------------------- |:------------------------:| | start_of_chorus (short: soc) | :heavy_check_mark: | | end_of_chorus (short: eoc) | :heavy_check_mark: | | start_of_verse | :heavy_check_mark: | | end_of_verse | :heavy_check_mark: | | start_of_tab (short: sot) | :heavy_multiplication_x: | | end_of_tab (short: eot) | :heavy_multiplication_x: | | start_of_grid | :heavy_multiplication_x: | | end_of_grid | :heavy_multiplication_x: |

Chord diagrams

| Directive | Support | |:--------- |:------------------------:| | define | :heavy_multiplication_x: | | chord | :heavy_multiplication_x: |

Fonts, sizes and colours

| Directive | Support | |:----------- |:------------------------:| | textfont | :clock2: | | textsize | :clock2: | | textcolour | :clock2: | | chordfont | :clock2: | | chordsize | :clock2: | | chordcolour | :clock2: | | tabfont | :heavy_multiplication_x: | | tabsize | :heavy_multiplication_x: | | tabcolour | :heavy_multiplication_x: |

Output related directives

| Directive | Support | |:------------------------------ |:------------------------:| | new_page (short: np) | :heavy_multiplication_x: | | new_physical_page (short: npp) | :heavy_multiplication_x: | | column_break (short: cb) | :heavy_multiplication_x: | | grid (short: g) | :heavy_multiplication_x: | | no_grid (short: ng) | :heavy_multiplication_x: | | titles | :heavy_multiplication_x: | | columns (short: col) | :heavy_multiplication_x: |

Custom extensions

| Directive | Support | |:--------- |:------------------:| | x_ | :heavy_check_mark: |

API docs

Note: all classes, methods and constants that are documented here can be considered public API and will only be subject to breaking changes between major versions.

Classes

Constants

Functions

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

Line

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

Kind: global class

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

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

The items (ChordLyricsPair or Tag) 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

Paragraph

Represents a paragraph of lines in a chord sheet

Kind: global class

• Paragraph
  • .lines : Array.<Line>
  • .type ⇒ string

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

• Song
  • .lines : Array.<Line>
  • .paragraphs : Array.<Line>
  • .bodyLines ⇒ Array.<Line>
  • .metaData ⇒ object
  • .clone() ⇒ Song

song.lines : Array.<Line>

The Line items of which the song consists

Kind: instance property of Song

song.paragraphs : Array.<Line>

The Paragraph items of which the song consists

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

Returns the song 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
Returns: object - 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.html

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

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

ParserWarning

Represents a parser warning, currently only used by ChordProParser.

Kind: global class

• ParserWarning
  • .message : string
  • .lineNumber : integer
  • .toString() ⇒ string

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

ALBUM : string

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

Kind: global constant

ARTIST : string

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

Kind: global constant

CAPO : string

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

Kind: global constant

COMMENT : string

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

Kind: global constant

COMPOSER : string

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

Kind: global constant

COPYRIGHT : string

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

Kind: global constant

DURATION : string

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

Kind: global constant

END_OF_CHORUS : string

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

Kind: global constant

END_OF_VERSE : string

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

Kind: global constant

KEY : string

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

Kind: global constant

LYRICIST : string

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

Kind: global constant

START_OF_CHORUS : string

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

Kind: global constant

START_OF_VERSE : string

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

Kind: global constant

SUBTITLE : string

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

Kind: global constant

TEMPO : string

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

Kind: global constant

TIME : string

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

Kind: global constant

TITLE : string

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

Kind: global constant

YEAR : string

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

Kind: global constant

parse(chordSheet) ⇒ Song

Parses a chord sheet into a song

Kind: global function
Returns: Song - The parsed song

| Param | Type | Description | | --- | --- | --- | | chordSheet | string | The ChordPro chord sheet |