A JavaScript library for parsing and formatting chord sheets
Contents
ChordSheetJS
is on npm, to install run:
npm install chordsheetjs
Load with import
:
import ChordSheetJS from 'chordsheetjs';
or require()
:
var ChordSheetJS = require('chordsheetjs').default;
If you're not using a build tool, you can download and use the bundle.js
from the
latest release:
<script src="bundle.js"></script>
<script>
// ChordSheetJS is available in global namespace now
const parser = new ChordSheetJS.ChordProParser();
</script>
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);
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);
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);
const formatter = new ChordSheetJS.TextFormatter();
const disp = formatter.format(song);
const formatter = new ChordSheetJS.HtmlTableFormatter();
const disp = formatter.format(song);
const formatter = new ChordSheetJS.HtmlDivFormatter();
const disp = formatter.format(song);
const formatter = new ChordSheetJS.ChordProFormatter();
const disp = formatter.format(song);
Chord sheets (Song
s) 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);
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'
// }
import { Chord } from 'chordsheetjs';
const chord = Chord.parse('Ebsus4/Bb');
Parse numeric chords (Nashville system):
const chord = Chord.parse('b1sus4/#3');
Use #toString() to convert the chord to a chord string (eg Dsus/F#)
const chord = Chord.parse('Ebsus4/Bb');
chord.toString(); // --> "Ebsus4/Bb"
var chord2 = chord.clone();
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"
Deprecated
Convert # to b and vice versa
const chord = parseChord('Eb/Bb');
const chord2 = chord.switchModifier();
chord2.toString(); // --> "D#/A#"
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"
const chord = Chord.parse('Eb/Bb');
const chord2 = chord.transposeUp();
chord2.toString(); // -> "E/B"
const chord = Chord.parse('Eb/Bb');
const chord2 = chord.transposeDown();
chord2.toString(); // -> "D/A"
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"
const numericChord = Chord.parse('2/4');
const chordSymbol = numericChord.toChordSymbol('E');
chordSymbol.toString(); // -> "F#/A"
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
Directive | Support |
---|---|
title (short: t) | โ๏ธ |
subtitle | โ๏ธ |
artist | โ๏ธ |
composer | โ๏ธ |
lyricist | โ๏ธ |
copyright | โ๏ธ |
album | โ๏ธ |
year | โ๏ธ |
key | โ๏ธ |
time | โ๏ธ |
tempo | โ๏ธ |
duration | โ๏ธ |
capo | โ๏ธ |
meta | โ๏ธ |
Directive | Support |
---|---|
comment (short: c) | โ๏ธ |
comment_italic (short: ci) | โ๏ธ |
comment_box (short: cb) | โ๏ธ |
chorus | โ๏ธ |
image | โ๏ธ |
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 | โ๏ธ |
Directive | Support |
---|---|
define | โ๏ธ |
chord | โ๏ธ |
Directive | Support |
---|---|
textfont | โ๏ธ |
textsize | โ๏ธ |
textcolour | โ๏ธ |
chordfont | โ๏ธ |
chordsize | โ๏ธ |
chordcolour | โ๏ธ |
tabfont | โ๏ธ |
tabsize | โ๏ธ |
tabcolour | โ๏ธ |
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) | โ๏ธ |
Directive | Support |
---|---|
x_ | โ๏ธ |
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.
- ChordSheetSerializer
Serializes a song into een plain object, and deserializes the serialized object back into a [Song](#Song)
- 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/
- Chord
Represents a Chord, consisting of a root, suffix (quality) and bass
- 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
- Key
Represents a key, such as Eb (symbol), #3 (numeric) or VII (numeral).
The only function considered public API is
Key.distance
- ChordProParser
Parses a ChordPro chord sheet
ChordSheetParserParses 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 ofChordSheetParser
, 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)
- 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: bettermusic#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
- 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
Serializes a song into een plain object, and deserializes the serialized object back into a [Song](#Song)
Kind: global class
Serializes the chord sheet to a plain object, which can be converted to any format like JSON, XML etc Can be deserialized using [deserialize](deserialize)
Kind: instance method of ChordSheetSerializer
Returns:
object A plain JS object containing all chord sheet data
chordSheetSerializer.deserialize(serializedSong) โ Song
Deserializes a song that has been serialized using [serialize](serialize)
Kind: instance method of ChordSheetSerializer
Returns: Song
-
The deserialized song
Param | Type | Description |
---|---|---|
serializedSong | object |
The serialized song |
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
Initialises a ChordLyricsPair
Param | Type | Default | Description |
---|---|---|---|
chords | string |
The chords |
|
lyrics | string | null |
null |
The lyrics |
annotation | string | null |
null |
The annotation |
The chords
Kind: instance property of ChordLyricsPair
The lyrics
Kind: instance property of ChordLyricsPair
The annotation
Kind: instance property of ChordLyricsPair
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
Represents a comment. See https://www.chordpro.org/chordpro/chordpro-file-format-specification/#overview
Kind: global class
- Comment
- .isRenderable() โ
boolean
- .clone() โ
Comment
- .isRenderable() โ
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
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
- .isEmpty() โ
Indicates whether the line contains any items
Kind: instance method of Line
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 |
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
Indicates whether the line type is [BRIDGE](#BRIDGE)
Kind: instance method of Line
Indicates whether the line type is [CHORUS](#CHORUS)
Kind: instance method of Line
Indicates whether the line type is [GRID](#GRID)
Kind: instance method of Line
Indicates whether the line type is [TAB](#TAB)
Kind: instance method of Line
Indicates whether the line type is [VERSE](#VERSE)
Kind: instance method of Line
Deprecated
Indicates whether the line contains items that are renderable. Please use [hasRenderableItems](hasRenderableItems)
Kind: instance method of Line
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
- .get(prop) โ
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
Represents a paragraph of lines in a chord sheet
Kind: global class
- Paragraph
- .contents โ
string
- .label โ
string
|null
- .type โ
string
- .isLiteral() โ
boolean
- .hasRenderableItems() โ
boolean
- .contents โ
Returns the paragraph contents as one string where lines are separated by newlines
Kind: instance property of Paragraph
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
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
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
Indicates whether the paragraph contains lines with renderable items.
Kind: instance method of Paragraph
See: Line.hasRenderableItems
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
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
|
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
|
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. |
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
isnull
it will act as a delete, any directive matchingname
will be removed.
Kind: instance method of Song
Param | Type | Description |
---|---|---|
name | string |
The directive name |
value | string | null |
The value to set, or |
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;
});
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
- .name :
The tag full name. When the original tag used the short name, name
will return the full name.
Kind: instance property of Tag
The original tag name that was used to construct the tag.
Kind: instance property of Tag
The tag value
Kind: instance property of Tag
Checks whether the tag value is a non-empty string.
Kind: instance method of Tag
Checks whether the tag is usually rendered inline. It currently only applies to comment tags.
Kind: instance method of Tag
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
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
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
- .clone() โ
- static
- .parse(chordString) โ
Chord
|null
- .parse(chordString) โ
- instance
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. |
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. |
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. |
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. |
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 |
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 |
Determines whether the chord is numeric
Kind: instance method of Chord
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 |
|
the reference key. The key is required when converting a chord symbol |
Determines whether the chord is a numeral
Kind: instance method of Chord
Converts the chord to a string, eg Esus4/G#
or 1sus4/#3
Kind: instance method of Chord
Returns: string
-
the chord string
Param | Type | Default | Description |
---|---|---|---|
[configuration] | Object |
{} |
options |
[configuration.useUnicodeModifier] | boolean |
false |
Whether or not to use unicode modifiers. This will make |
chord.normalize([key], [options]) โ Chord
Normalizes the chord root and bass notes:
- Fab becomes Mi
- Dob becomes Si
- Si# becomes Do
- Mi# becomes Fa
- 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 if normalizeSuffix
is true
.
For example, sus2
becomes 2
, sus4
becomes sus
.
All suffix normalizations can be found in src/normalize_mappings/suffix-mapping.txt
.
When the chord is minor, bass notes are normalized off of the relative major
of the root note. For example, Em/A#
becomes Em/Bb
.
Kind: instance method of Chord
Returns: Chord
-
the normalized chord
Param | Type | Default | Description |
---|---|---|---|
[key] | Key | string |
|
the key to normalize to |
[options] | Object |
{} |
options |
[options.normalizeSuffix] | boolean |
true |
whether to normalize the chord suffix after transposing |
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: |
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) โ Chord
| null
Tries to parse a chord string into a chord
Any leading or trailing whitespace is removed first, so a chord like \n E/G# \r
is valid.
Kind: static method of Chord
Param | Description |
---|---|
chordString | the chord string, eg |
Formats a song into a ChordPro chord sheet
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 |
Formats a song into a plain text chord sheet
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 |
Base class for all formatters, taking care of receiving a configuration wrapping that inside a Configuration object
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 |
[configuration.expandChorusDirective] | boolean |
false |
Whether or not to expand |
[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 |
Formats a song into HTML. It uses DIVs to align lyrics with chords, which makes it useful for responsive web pages.
Acts as a base class for HTML formatters
Kind: global class
- HtmlFormatter
- .cssObject โ
Object.<string, Object.<string, string>>
- .format(song) โ
string
- .cssString(scope) โ
string
- .cssObject โ
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
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 |
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 |
Formats a song into HTML. It uses TABLEs to align lyrics with chords, which makes the HTML for things like PDF conversion.
Formats a song into a plain text chord sheet
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 |
Represents a key, such as Eb (symbol), #3 (numeric) or VII (numeral).
The only function considered public API is Key.distance
Calculates the distance in semitones between one key and another.
Kind: static method of Key
Returns: number
-
the distance in semitones
Param | Type | Description |
---|---|---|
oneKey | Key | string |
the key |
otherKey | Key | string |
the other key |
Parses a ChordPro chord sheet
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 |
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
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 |
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.
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 |
Represents a parser warning, currently only used by ChordProParser.
Returns a stringified version of the warning
Kind: instance method of ParserWarning
Returns: string
-
The string warning
Parses a chords over words sheet
pegBasedParser.warnings : Array.<ParserWarning>
All warnings raised during parsing the chord sheet
Kind: instance property of PegBasedParser
Parses an Ultimate Guitar chord sheet with metadata Inherits from [ChordSheetParser](#ChordSheetParser)
Instantiate a chord sheet parser
Param | Type | Default | Description |
---|---|---|---|
[options] | Object |
{} |
options |
[options.preserveWhitespace] | boolean |
true |
whether to preserve trailing whitespace for chords |
Album meta directive. See https://www.chordpro.org/chordpro/directives-album/
Arranger meta directive. See https://chordpro.org/chordpro/directives-arranger/
Artist meta directive. See https://www.chordpro.org/chordpro/directives-artist/
Capo meta directive. See https://www.chordpro.org/chordpro/directives-capo/
Comment directive. See https://www.chordpro.org/chordpro/directives-comment/
Composer meta directive. See https://www.chordpro.org/chordpro/directives-composer/
Copyright meta directive. See https://www.chordpro.org/chordpro/directives-copyright/
Duration meta directive. See https://www.chordpro.org/chordpro/directives-duration/
End of ABC music notation section See https://chordpro.org/chordpro/directives-env_abc/
End of bridge directive. See https://chordpro.org/chordpro/directives-env_bridge/
End of chorus directive. See https://www.chordpro.org/chordpro/directives-env_chorus/
End of grid directive. See https://www.chordpro.org/chordpro/directives-env_grid/
End of Lilypond music notation section See https://chordpro.org/chordpro/directives-env_ly/
End of tab directive. See https://www.chordpro.org/chordpro/directives-env_tab/
End of verse directive. See https://www.chordpro.org/chordpro/directives-env_verse/
Key meta directive. See https://www.chordpro.org/chordpro/directives-key/
_Key meta directive. Reflects the key as transposed by the capo value See https://www.chordpro.org/chordpro/directives-key/
Lyricist meta directive. See https://www.chordpro.org/chordpro/directives-lyricist/
Sorttitle meta directive. See https://chordpro.org/chordpro/directives-sorttitle/
Start of ABC music notation section See https://chordpro.org/chordpro/directives-env_abc/
Start of bridge directive. See https://chordpro.org/chordpro/directives-env_bridge/
Start of chorus directive. See https://www.chordpro.org/chordpro/directives-env_chorus/
Start of grid directive. See https://www.chordpro.org/chordpro/directives-env_grid/
Start of Lilypond music notation section See https://chordpro.org/chordpro/directives-env_ly/
Start of tab directive. See https://www.chordpro.org/chordpro/directives-env_tab/
Start of verse directive. See https://www.chordpro.org/chordpro/directives-env_verse/
Subtitle meta directive. See https://www.chordpro.org/chordpro/directives-subtitle/
Tempo meta directive. See https://www.chordpro.org/chordpro/directives-tempo/
Time meta directive. See https://www.chordpro.org/chordpro/directives-time/
Title meta directive. See https://www.chordpro.org/chordpro/directives-title/
Transpose meta directive. See: https://www.chordpro.org/chordpro/directives-transpose/
New Key meta directive. See: bettermusic#53
Year meta directive. See https://www.chordpro.org/chordpro/directives-year/
Chordfont directive. See https://www.chordpro.org/chordpro/directives-props_chord_legacy/
Chordfont directive. See https://www.chordpro.org/chordpro/directives-props_chord_legacy/
Chordfont directive. See https://www.chordpro.org/chordpro/directives-props_chord_legacy/
Chordfont directive. See https://www.chordpro.org/chordpro/directives-props_text_legacy/
Chordfont directive. See https://www.chordpro.org/chordpro/directives-props_text_legacy/
Chordfont directive. See https://www.chordpro.org/chordpro/directives-props_text_legacy/
Chordfont directive. See https://www.chordpro.org/chordpro/directives-props_title_legacy/
Chordfont directive. See https://www.chordpro.org/chordpro/directives-props_title_legacy/
Chordfont directive. See https://www.chordpro.org/chordpro/directives-props_title_legacy/
Chorus directive. Support repeating an earlier defined section. See https://www.chordpro.org/chordpro/directives-env_chorus/
Chord type directive. Determines the type of chords used in the rendered chord sheet. Possible values are 'solfege', 'symbol', 'numeral' and 'number'
Kind: global constant
See: bettermusic#352
Used to mark a paragraph as bridge
Used to mark a paragraph as chorus
Used to mark a paragraph as grid
Used to mark a paragraph as containing lines with both verse and chorus type
Used to mark a paragraph as not containing a line marked with a type
Used to mark a paragraph as tab
Used to mark a paragraph as verse
Used to mark a section as Lilypond notation
Used to mark a section as ABC music notation
Generates basic CSS, scoped within the provided selector, to use with output generated by [HtmlTableFormatter](#HtmlTableFormatter)
Kind: global function
Returns: string
-
the CSS string
Param | Description |
---|---|
scope | the CSS scope to use, for example |
Generates basic CSS, scoped within the provided selector, to use with output generated by [HtmlTableFormatter](#HtmlTableFormatter)
Kind: global function
Returns: string
-
the CSS string
Param | Description |
---|---|
scope | the CSS scope to use, for example |
Returns applicable capos for the provided key
Kind: global function
Returns: Object.<string, string>
-
The available capos, where the keys are capo numbers and the values are the effective key for that capo.
Param | Type | Description |
---|---|---|
key | Key | string |
The key to get capos for |
Returns applicable keys to transpose to from the provided key
Kind: global function
Returns: Array.<string>
-
The available keys
Param | Type | Description |
---|---|---|
key | Key | string |
The key to get keys for |