Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.
Awesome Lists | Featured Topics | Projects
https://github.com/martijnversluis/ChordSheetJS

A JavaScript library for parsing and formatting ChordPro chord sheets
https://github.com/martijnversluis/ChordSheetJS
chord-sheet chordpro chords javascript parsing typescript
Last synced: about 2 months ago
JSON representation
A JavaScript library for parsing and formatting ChordPro chord sheets
Host: GitHub
URL: https://github.com/martijnversluis/ChordSheetJS
Owner: martijnversluis
License: gpl-2.0
Created: 2015-03-19T11:32:09.000Z (over 9 years ago)
Default Branch: master
Last Pushed: 2024-04-30T14:46:19.000Z (5 months ago)
Last Synced: 2024-05-02T00:34:55.278Z (5 months ago)
Topics: chord-sheet, chordpro, chords, javascript, parsing, typescript
Language: TypeScript
Homepage:
Size: 4.3 MB
Stars: 279
Watchers: 7
Forks: 48
Open Issues: 21
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE
Awesome Lists containing this project

README

        # ChordSheetJS [![Code Climate](https://codeclimate.com/github/martijnversluis/ChordSheetJS/badges/gpa.svg)](https://codeclimate.com/github/martijnversluis/ChordSheetJS) [![CI](https://github.com/martijnversluis/ChordSheetJS/actions/workflows/ci.yml/badge.svg)](https://github.com/martijnversluis/ChordSheetJS/actions/workflows/ci.yml?query=branch%3Amaster) [![Release](https://github.com/martijnversluis/ChordSheetJS/actions/workflows/release.yml/badge.svg)](https://github.com/martijnversluis/ChordSheetJS/actions/workflows/release.yml)

A JavaScript library for parsing and formatting chord sheets

**Contents**

- [Installation](#installation)

- [How to ...?](#how-to-)

- [Supported ChordPro directives](#supported-chordpro-directives)

- [API docs](#api-docs)

- [Contributing](CONTRIBUTING.md)

## Installation

### Package managers

`ChordSheetJS` is on npm, to install run:

```bash

npm install chordsheetjs

```

Load with `import`:

```javascript

import ChordSheetJS from 'chordsheetjs';

```

or `require()`:

```javascript

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](https://github.com/martijnversluis/ChordSheetJS/releases/latest):

```html

// ChordSheetJS is available in global namespace now

const parser = new ChordSheetJS.ChordProParser();

```

## How to ...?

### Parse chord sheet

#### Regular chord sheets

```javascript

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

```javascript

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

```javascript

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

```javascript

const formatter = new ChordSheetJS.TextFormatter();

const disp = formatter.format(song);

```

#### HTML format

##### Table-based layout

```javascript

const formatter = new ChordSheetJS.HtmlTableFormatter();

const disp = formatter.format(song);

```

##### Div-based layout

```javascript

const formatter = new ChordSheetJS.HtmlDivFormatter();

const disp = formatter.format(song);

```

#### Chord pro format

```javascript

const formatter = new ChordSheetJS.ChordProFormatter();

const disp = formatter.format(song);

```

### Serialize/deserialize

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

```javascript

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:

```javascript

HtmlTableFormatter.cssString();

// .paragraph {

//   margin-bottom: 1em;

// }

HtmlTableFormatter.cssString('.chordSheetViewer');

// .chordSheetViewer .paragraph {

//   margin-bottom: 1em;

// }

HtmlTableFormatter.cssObject();

// '.paragraph': {

//   marginBottom: '1em'

// }

```

### Parsing and modifying chords

```javascript

import { Chord } from 'chordsheetjs';

```

#### Parse

```javascript

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

```

Parse numeric chords (Nashville system):

```javascript

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

```

#### Display with #toString

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

```javascript

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

chord.toString(); // --> "Ebsus4/Bb"

```

#### Clone

```javascript

var chord2 = chord.clone();

```

#### Normalize

Normalizes keys B#, E#, Cb and Fb to C, F, B and E

```javascript

const chord = Chord.parse('E#/B#');

normalizedChord = chord.normalize();

normalizedChord.toString(); // --> "F/C"

```

#### ~~Switch modifier~~

***Deprecated***

Convert # to b and vice versa

```javascript

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)

```javascript

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

const chord2 = chord.useModifier('#');

chord2.toString(); // --> "D#/A#"

```

```javascript

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

const chord2 = chord.useModifier('b');

chord2.toString(); // --> "Eb/Bb"

```

#### Transpose up

```javascript

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

const chord2 = chord.transposeUp();

chord2.toString(); // -> "E/B"

```

#### Transpose down

```javascript

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

const chord2 = chord.transposeDown();

chord2.toString(); // -> "D/A"

```

#### Transpose

```javascript

const chord = Chord.parse('C/E');

const chord2 = chord.transpose(4);

chord2.toString(); // -> "E/G#"

```

```javascript

const chord = Chord.parse('C/E');

const chord2 = chord.transpose(-4);

chord2.toString(); // -> "Ab/C"

```

#### Convert numeric chord to chord symbol

```javascript

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.

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

| end_of_tab (short: eot)      | :heavy_check_mark:       |

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

| textsize    | :heavy_check_mark:       |

| textcolour  | :heavy_check_mark:       |

| chordfont   | :heavy_check_mark:       |

| chordsize   | :heavy_check_mark:       |

| chordcolour | :heavy_check_mark:       |

| 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



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.

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

    * [new ChordLyricsPair(chords, lyrics, annotation)](#new_ChordLyricsPair_new)

    * [.chords](#ChordLyricsPair+chords) : string

    * [.lyrics](#ChordLyricsPair+lyrics) : string

    * [.annotation](#ChordLyricsPair+annotation) : string

    * [.isRenderable()](#ChordLyricsPair+isRenderable) ⇒ boolean

    * [.clone()](#ChordLyricsPair+clone) ⇒ [ChordLyricsPair](#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)  



### chordLyricsPair.lyrics : string

The lyrics


**Kind**: instance property of [ChordLyricsPair](#ChordLyricsPair)  



### chordLyricsPair.annotation : string

The annotation


**Kind**: instance property of [ChordLyricsPair](#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)  



### chordLyricsPair.clone() ⇒ [ChordLyricsPair](#ChordLyricsPair)

Returns a deep copy of the ChordLyricsPair, useful when programmatically transforming a song


**Kind**: instance method of [ChordLyricsPair](#ChordLyricsPair)  



## Comment

Represents a comment. See https://www.chordpro.org/chordpro/chordpro-file-format-specification/#overview


**Kind**: global class  

* [Comment](#Comment)

    * [.isRenderable()](#Comment+isRenderable) ⇒ boolean

    * [.clone()](#Comment+clone) ⇒ [Comment](#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)  



### comment.clone() ⇒ [Comment](#Comment)

Returns a deep copy of the Comment, useful when programmatically transforming a song


**Kind**: instance method of [Comment](#Comment)  



## Line

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


**Kind**: global class  

* [Line](#Line)

    * [.isEmpty()](#Line+isEmpty) ⇒ boolean

    * [.addItem(item)](#Line+addItem)

    * [.hasRenderableItems()](#Line+hasRenderableItems) ⇒ boolean

    * [.clone()](#Line+clone) ⇒ [Line](#Line)

    * [.isBridge()](#Line+isBridge) ⇒ boolean

    * [.isChorus()](#Line+isChorus) ⇒ boolean

    * [.isGrid()](#Line+isGrid) ⇒ boolean

    * [.isTab()](#Line+isTab) ⇒ boolean

    * [.isVerse()](#Line+isVerse) ⇒ boolean

    * ~~[.hasContent()](#Line+hasContent) ⇒ boolean~~



### line.isEmpty() ⇒ boolean

Indicates whether the line contains any items


**Kind**: instance method of [Line](#Line)  



### line.addItem(item)

Adds an item ([ChordLyricsPair](#ChordLyricsPair) or [Tag](#Tag)) to the line


**Kind**: instance method of [Line](#Line)  

| Param | Type | Description |

| --- | --- | --- |

| item | [ChordLyricsPair](#ChordLyricsPair) \| [Tag](#Tag) | 
The item to be added
 |



### line.hasRenderableItems() ⇒ boolean

Indicates whether the line contains items that are renderable


**Kind**: instance method of [Line](#Line)  



### line.clone() ⇒ [Line](#Line)

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


**Kind**: instance method of [Line](#Line)  



### line.isBridge() ⇒ boolean

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


**Kind**: instance method of [Line](#Line)  



### line.isChorus() ⇒ boolean

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


**Kind**: instance method of [Line](#Line)  



### line.isGrid() ⇒ boolean

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


**Kind**: instance method of [Line](#Line)  



### line.isTab() ⇒ boolean

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


**Kind**: instance method of [Line](#Line)  



### line.isVerse() ⇒ boolean

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


**Kind**: instance method of [Line](#Line)  



### ~~line.hasContent() ⇒ boolean~~

***Deprecated***

Indicates whether the line contains items that are renderable. Please use [hasRenderableItems](hasRenderableItems)


**Kind**: instance method of [Line](#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](#Metadata)

    * [.get(prop)](#Metadata+get) ⇒ Array.<String> \| String

    * [.clone()](#Metadata+clone) ⇒ [Metadata](#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](#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](#Metadata)

Returns a deep clone of this Metadata object


**Kind**: instance method of [Metadata](#Metadata)  

**Returns**: [Metadata](#Metadata) - 
the cloned Metadata object  



## Paragraph

Represents a paragraph of lines in a chord sheet


**Kind**: global class  

* [Paragraph](#Paragraph)

    * [.contents](#Paragraph+contents) ⇒ string

    * [.label](#Paragraph+label) ⇒ string \| null

    * [.type](#Paragraph+type) ⇒ string

    * [.isLiteral()](#Paragraph+isLiteral) ⇒ boolean

    * [.hasRenderableItems()](#Paragraph+hasRenderableItems) ⇒ boolean



### paragraph.contents ⇒ string

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


**Kind**: instance property of [Paragraph](#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)  



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



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

**See**: [contents](contents)  



### paragraph.hasRenderableItems() ⇒ boolean

Indicates whether the paragraph contains lines with renderable items.


**Kind**: instance method of [Paragraph](#Paragraph)  

**See**: [Line.hasRenderableItems](Line.hasRenderableItems)  



## Song

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


**Kind**: global class  

* [Song](#Song)

    * [new Song(metadata)](#new_Song_new)

    * [.bodyLines](#Song+bodyLines) ⇒ [Array.<Line>](#Line)

    * [.bodyParagraphs](#Song+bodyParagraphs) ⇒ [Array.<Paragraph>](#Paragraph)

    * [.paragraphs](#Song+paragraphs) : [Array.<Paragraph>](#Paragraph)

    * [.expandedBodyParagraphs](#Song+expandedBodyParagraphs) : [Array.<Paragraph>](#Paragraph)

    * [.clone()](#Song+clone) ⇒ [Song](#Song)

    * [.setKey(key)](#Song+setKey) ⇒ [Song](#Song)

    * [.setCapo(capo)](#Song+setCapo) ⇒ [Song](#Song)

    * [.transpose(delta, [options])](#Song+transpose) ⇒ [Song](#Song)

    * [.transposeUp([options])](#Song+transposeUp) ⇒ [Song](#Song)

    * [.transposeDown([options])](#Song+transposeDown) ⇒ [Song](#Song)

    * [.changeKey(newKey)](#Song+changeKey) ⇒ [Song](#Song)

    * [.changeMetadata(name, value)](#Song+changeMetadata)

    * [.mapItems(func)](#Song+mapItems) ⇒ [Song](#Song)

    * [.mapLines(func)](#Song+mapLines) ⇒ [Song](#Song)



### new Song(metadata)

Creates a new {Song} instance


| Param | Type | Description |

| --- | --- | --- |

| metadata | Object \| [Metadata](#Metadata) | 
predefined metadata
 |



### song.bodyLines ⇒ [Array.<Line>](#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](#Song)  

**Returns**: [Array.<Line>](#Line) - 
The song body lines  



### song.bodyParagraphs ⇒ [Array.<Paragraph>](#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](#Song)  

**See**: [bodyLines](bodyLines)  



### song.paragraphs : [Array.<Paragraph>](#Paragraph)

The [Paragraph](#Paragraph) items of which the song consists


**Kind**: instance property of [Song](#Song)  



### song.expandedBodyParagraphs : [Array.<Paragraph>](#Paragraph)

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


**Kind**: instance property of [Song](#Song)  



### song.clone() ⇒ [Song](#Song)

Returns a deep clone of the song


**Kind**: instance method of [Song](#Song)  

**Returns**: [Song](#Song) - 
The cloned song  



### song.setKey(key) ⇒ [Song](#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](#Song)  

**Returns**: [Song](#Song) - 
The changed song
  

| Param | Type | Description |

| --- | --- | --- |

| key | number \| null | 
the key. Passing null will:
  remove the current key from [metadata](metadata)
 remove any key directive
 
 |



### song.setCapo(capo) ⇒ [Song](#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](#Song)  

**Returns**: [Song](#Song) - 
The changed song
  

| Param | Type | Description |

| --- | --- | --- |

| capo | number \| null | 
the capo. Passing null will:
  remove the current key from [metadata](metadata)
 remove any capo directive
 
 |



### song.transpose(delta, [options]) ⇒ [Song](#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](#Song)  

**Returns**: [Song](#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](#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](#Song)  

**Returns**: [Song](#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](#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](#Song)  

**Returns**: [Song](#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](#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](#Song)  

**Returns**: [Song](#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](#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](#Song)

Change the song contents inline. Return a new [Item](Item) to replace it. Return null to remove it.


**Kind**: instance method of [Song](#Song)  

**Returns**: [Song](#Song) - 
the changed song
  

| Param | Type | Description |

| --- | --- | --- |

| func | MapItemsCallback | 
the callback function
 |

**Example**  

```js

// transpose all chords:

song.mapItems((item) => {

  if (item instanceof ChordLyricsPair) {

    return item.transpose(2, 'D');

  }

  return item;

});

```



### song.mapLines(func) ⇒ [Song](#Song)

Change the song contents inline. Return a new [Line](#Line) to replace it. Return null to remove it.


**Kind**: instance method of [Song](#Song)  

**Returns**: [Song](#Song) - 
the changed song
  

| Param | Type | Description |

| --- | --- | --- |

| func | MapLinesCallback | 
the callback function
 |

**Example**  

```js

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

    * [.name](#Tag+name) : string

    * [.originalName](#Tag+originalName) : string

    * [.value](#Tag+value) : string

    * [.hasValue()](#Tag+hasValue) ⇒ boolean

    * [.isRenderable()](#Tag+isRenderable) ⇒ boolean

    * [.hasRenderableLabel()](#Tag+hasRenderableLabel)

    * [.isMetaTag()](#Tag+isMetaTag) ⇒ boolean

    * [.clone()](#Tag+clone) ⇒ [Tag](#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)  



### tag.originalName : string

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


**Kind**: instance property of [Tag](#Tag)  



### tag.value : string

The tag value


**Kind**: instance property of [Tag](#Tag)  



### tag.hasValue() ⇒ boolean

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


**Kind**: instance method of [Tag](#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)  



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



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



### tag.clone() ⇒ [Tag](#Tag)

Returns a clone of the tag.


**Kind**: instance method of [Tag](#Tag)  

**Returns**: [Tag](#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](#ChordProFormatter)  

**Returns**: string - 
The ChordPro string
  

| Param | Type | Description |

| --- | --- | --- |

| song | [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](#ChordsOverWordsFormatter)  

**Returns**: string - 
the chord sheet
  

| Param | Type | Description |

| --- | --- | --- |

| song | [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](#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](#HtmlFormatter)

    * [.cssObject](#HtmlFormatter+cssObject) ⇒ Object.<string, Object.<string, string>>

    * [.format(song)](#HtmlFormatter+format) ⇒ string

    * [.cssString(scope)](#HtmlFormatter+cssString) ⇒ 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](#HtmlFormatter)  

**Returns**: Object.<string, Object.<string, string>> - 
the CSS object  



### htmlFormatter.format(song) ⇒ string

Formats a song into HTML.


**Kind**: instance method of [HtmlFormatter](#HtmlFormatter)  

**Returns**: string - 
The HTML string
  

| Param | Type | Description |

| --- | --- | --- |

| song | [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](#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](#TextFormatter)  

**Returns**: string - 
the chord sheet
  

| Param | Type | Description |

| --- | --- | --- |

| song | [Song](#Song) | 
The song to be formatted
 |



## ChordProParser

Parses a ChordPro chord sheet


**Kind**: global class  

* [ChordProParser](#ChordProParser)

    * [.warnings](#ChordProParser+warnings) : [Array.<ParserWarning>](#ParserWarning)

    * [.parse(chordSheet, options)](#ChordProParser+parse) ⇒ [Song](#Song)



### chordProParser.warnings : [Array.<ParserWarning>](#ParserWarning)

All warnings raised during parsing the chord sheet


**Kind**: instance property of [ChordProParser](#ChordProParser)  



### chordProParser.parse(chordSheet, options) ⇒ [Song](#Song)

Parses a ChordPro chord sheet into a song


**Kind**: instance method of [ChordProParser](#ChordProParser)  

**Returns**: [Song](#Song) - 
The parsed song  

**See**: https://peggyjs.org/documentation.html#using-the-parser  

| Param | Type | Default | Description |

| --- | --- | --- | --- |

| chordSheet | string |  | 
the ChordPro chord sheet |

| options | ChordProParserOptions |  | Parser options. |

| options.softLineBreaks | ChordProParserOptions.softLineBreaks | false | If true, a backslash followed by * a space is treated as a soft line break
 |



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

    * [new ChordSheetParser([options])](#new_ChordSheetParser_new)

    * [.parse(chordSheet, [options])](#ChordSheetParser+parse) ⇒ [Song](#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](#Song)

Parses a chord sheet into a song


**Kind**: instance method of [ChordSheetParser](#ChordSheetParser)  

**Returns**: [Song](#Song) - 
The parsed song
  

| Param | Type | Default | Description |

| --- | --- | --- | --- |

| chordSheet | string |  | 
The ChordPro chord sheet |

| [options] | Object | {} | Optional parser options |

| [options.song] | [Song](#Song) |  | The [Song](#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](#ChordsOverWordsParser)

    * [.warnings](#ChordsOverWordsParser+warnings) : [Array.<ParserWarning>](#ParserWarning)

    * [.parse(chordSheet, options)](#ChordsOverWordsParser+parse) ⇒ [Song](#Song)



### chordsOverWordsParser.warnings : [Array.<ParserWarning>](#ParserWarning)

All warnings raised during parsing the chord sheet


**Kind**: instance property of [ChordsOverWordsParser](#ChordsOverWordsParser)  



### chordsOverWordsParser.parse(chordSheet, options) ⇒ [Song](#Song)

Parses a chords over words sheet into a song


**Kind**: instance method of [ChordsOverWordsParser](#ChordsOverWordsParser)  

**Returns**: [Song](#Song) - 
The parsed song  

**See**: https://peggyjs.org/documentation.html#using-the-parser  

| Param | Type | Default | Description |

| --- | --- | --- | --- |

| chordSheet | string |  | 
the chords over words sheet |

| options | ChordsOverWordsParserOptions |  | Parser options. |

| options.softLineBreaks | ChordsOverWordsParserOptions.softLineBreaks | false | If true, a backslash followed by a space is treated as a soft line break
 |



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

**Returns**: string - 
The string warning  



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

    * _instance_

        * [.clone()](#Chord+clone) ⇒ [Chord](#Chord)

        * [.toChordSymbol([referenceKey])](#Chord+toChordSymbol) ⇒ [Chord](#Chord)

        * [.toChordSymbolString([referenceKey])](#Chord+toChordSymbolString) ⇒ string

        * [.isChordSymbol()](#Chord+isChordSymbol) ⇒ boolean

        * [.toChordSolfege([referenceKey])](#Chord+toChordSolfege) ⇒ [Chord](#Chord)

        * [.toChordSolfegeString([referenceKey])](#Chord+toChordSolfegeString) ⇒ string

        * [.isChordSolfege()](#Chord+isChordSolfege) ⇒ boolean

        * [.toNumeric([referenceKey])](#Chord+toNumeric) ⇒ [Chord](#Chord)

        * [.toNumeral([referenceKey])](#Chord+toNumeral) ⇒ [Chord](#Chord)

        * [.toNumeralString([referenceKey])](#Chord+toNumeralString) ⇒ string

        * [.isNumeric()](#Chord+isNumeric) ⇒ boolean

        * [.toNumericString([referenceKey])](#Chord+toNumericString) ⇒ string

        * [.isNumeral()](#Chord+isNumeral) ⇒ boolean

        * [.toString([configuration])](#Chord+toString) ⇒ string

        * [.normalize([key], [options])](#Chord+normalize) ⇒ [Chord](#Chord)

        * [.useModifier(newModifier)](#Chord+useModifier) ⇒ [Chord](#Chord)

        * [.transposeUp()](#Chord+transposeUp) ⇒ [Chord](#Chord)

        * [.transposeDown()](#Chord+transposeDown) ⇒ [Chord](#Chord)

        * [.transpose(delta)](#Chord+transpose) ⇒ [Chord](#Chord)

    * _static_

        * [.parse(chordString)](#Chord.parse) ⇒ [Chord](#Chord) \| null



### chord.clone() ⇒ [Chord](#Chord)

Returns a deep copy of the chord


**Kind**: instance method of [Chord](#Chord)  



### chord.toChordSymbol([referenceKey]) ⇒ [Chord](#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](#Chord)  

**Returns**: [Chord](#Chord) - 
the chord symbol
  

| Param | Type | Default | Description |

| --- | --- | --- | --- |

| [referenceKey] | [Key](#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](#Chord)  

**Returns**: string - 
the chord symbol string  

**See**: {toChordSymbol}  

| Param | Type | Default | Description |

| --- | --- | --- | --- |

| [referenceKey] | [Key](#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)  



### chord.toChordSolfege([referenceKey]) ⇒ [Chord](#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](#Chord)  

**Returns**: [Chord](#Chord) - 
the chord solfege
  

| Param | Type | Default | Description |

| --- | --- | --- | --- |

| [referenceKey] | [Key](#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](#Chord)  

**Returns**: string - 
the chord solfege string  

**See**: {toChordSolfege}  

| Param | Type | Default | Description |

| --- | --- | --- | --- |

| [referenceKey] | [Key](#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)  



### chord.toNumeric([referenceKey]) ⇒ [Chord](#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](#Chord)  

**Returns**: [Chord](#Chord) - 
the numeric chord
  

| Param | Type | Default | Description |

| --- | --- | --- | --- |

| [referenceKey] | [Key](#Key) \| string \| null |  | 
the reference key. The key is required when converting a chord symbol
 |



### chord.toNumeral([referenceKey]) ⇒ [Chord](#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](#Chord)  

**Returns**: [Chord](#Chord) - 
the numeral chord
  

| Param | Type | Default | Description |

| --- | --- | --- | --- |

| [referenceKey] | [Key](#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](#Chord)  

**Returns**: string - 
the numeral chord string  

**See**: {toNumeral}  

| Param | Type | Default | Description |

| --- | --- | --- | --- |

| [referenceKey] | [Key](#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)  



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

**Returns**: string - 
the numeric chord string  

**See**: {toNumeric}  

| Param | Type | Default | Description |

| --- | --- | --- | --- |

| [referenceKey] | [Key](#Key) \| string \| null |  | 
the reference key. The key is required when converting a chord symbol
 |



### chord.isNumeral() ⇒ boolean

Determines whether the chord is a numeral


**Kind**: instance method of [Chord](#Chord)  



### chord.toString([configuration]) ⇒ string

Converts the chord to a string, eg Esus4/G# or 1sus4/#3


**Kind**: instance method of [Chord](#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 # (sharp) look like ♯ and b (flat) look like ♭
 |



### chord.normalize([key], [options]) ⇒ [Chord](#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](#Chord)  

**Returns**: [Chord](#Chord) - 
the normalized chord
  

| Param | Type | Default | Description |

| --- | --- | --- | --- |

| [key] | [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](#Chord)

Switches to the specified modifier


**Kind**: instance method of [Chord](#Chord)  

**Returns**: [Chord](#Chord) - 
the new, changed chord
  

| Param | Description |

| --- | --- |

| newModifier | 
the modifier to use: '#' or 'b'
 |



### chord.transposeUp() ⇒ [Chord](#Chord)

Transposes the chord up by 1 semitone. Eg. A becomes A#, Eb becomes E


**Kind**: instance method of [Chord](#Chord)  

**Returns**: [Chord](#Chord) - 
the new, transposed chord  



### chord.transposeDown() ⇒ [Chord](#Chord)

Transposes the chord down by 1 semitone. Eg. A# becomes A, E becomes Eb


**Kind**: instance method of [Chord](#Chord)  

**Returns**: [Chord](#Chord) - 
the new, transposed chord  



### chord.transpose(delta) ⇒ [Chord](#Chord)

Transposes the chord by the specified number of semitones


**Kind**: instance method of [Chord](#Chord)  

**Returns**: [Chord](#Chord) - 
the new, transposed chord
  

| Param | Description |

| --- | --- |

| delta | 
de number of semitones
 |



### Chord.parse(chordString) ⇒ [Chord](#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](#Chord)  

| Param | Description |

| --- | --- |

| chordString | 
the chord string, eg Esus4/G# or 1sus4/#3.
 |



## ChordSheetSerializer

Serializes a song into een plain object, and deserializes the serialized object back into a [Song](#Song)


**Kind**: global class  

* [ChordSheetSerializer](#ChordSheetSerializer)

    * [.serialize()](#ChordSheetSerializer+serialize) ⇒

    * [.deserialize(serializedSong)](#ChordSheetSerializer+deserialize) ⇒ [Song](#Song)



### chordSheetSerializer.serialize() ⇒

Serializes the chord sheet to a plain object, which can be converted to any format like JSON, XML etc

Can be deserialized using [deserialize](deserialize)


**Kind**: instance method of [ChordSheetSerializer](#ChordSheetSerializer)  

**Returns**: 
object A plain JS object containing all chord sheet data  



### chordSheetSerializer.deserialize(serializedSong) ⇒ [Song](#Song)

Deserializes a song that has been serialized using [serialize](serialize)


**Kind**: instance method of [ChordSheetSerializer](#ChordSheetSerializer)  

**Returns**: [Song](#Song) - 
The deserialized song
  

| Param | Type | Description |

| --- | --- | --- |

| serializedSong | object | 
The serialized song
 |



## Key

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

The only function considered public API is Key.distance


**Kind**: global class  



### Key.distance(oneKey, otherKey) ⇒ number

Calculates the distance in semitones between one key and another.


**Kind**: static method of [Key](#Key)  

**Returns**: number - 
the distance in semitones
  

| Param | Type | Description |

| --- | --- | --- |

| oneKey | [Key](#Key) \| string | 
the key |

| otherKey | [Key](#Key) \| string | the other key
 |



## ALBUM : string

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


**Kind**: global constant  



## ARRANGER : string

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


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

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


**Kind**: global constant  



## END\_OF\_BRIDGE : string

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


**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\_GRID : string

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


**Kind**: global constant  



## END\_OF\_LY : string

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


**Kind**: global constant  



## END\_OF\_TAB : string

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


**Kind**: global constant  



## END\_OF\_VERSE : string

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


**Kind**: global constant  



## KEY : string

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


**Kind**: global constant  



## \_KEY : string

_Key meta directive. Reflects the key as transposed by the capo value

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  



## SORTTITLE : string

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


**Kind**: global constant  



## START\_OF\_ABC : string

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


**Kind**: global constant  



## START\_OF\_BRIDGE : string

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


**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\_GRID : string

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


**Kind**: global constant  



## START\_OF\_LY : string

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


**Kind**: global constant  



## START\_OF\_TAB : string

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


**Kind**: global constant  



## START\_OF\_VERSE : string

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


**Kind**: global constant  



## SUBTITLE : string

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


**Kind**: global constant  



## TEMPO : string

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


**Kind**: global constant  



## TIME : string

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


**Kind**: global constant  



## TITLE : string

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


**Kind**: global constant  



## TRANSPOSE : string

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


**Kind**: global constant  



## NEW\_KEY : string

New Key meta directive. See: https://github.com/PraiseCharts/ChordChartJS/issues/53


**Kind**: global constant  



## YEAR : string

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


**Kind**: global constant  



## CHORDFONT : string

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


**Kind**: global constant  



## CHORDSIZE : string

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


**Kind**: global constant  



## CHORDCOLOUR : string

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


**Kind**: global constant  



## TEXTFONT : string

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


**Kind**: global constant  



## TEXTSIZE : string

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


**Kind**: global constant  



## TEXTCOLOUR : string

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


**Kind**: global constant  



## TITLEFONT : string

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


**Kind**: global constant  



## TITLESIZE : string

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


**Kind**: global constant  



## TITLECOLOUR : string

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


**Kind**: global constant  



## CHORUS : string

Chorus directive. Support repeating an earlier defined section.

See https://www.chordpro.org/chordpro/directives-env_chorus/


**Kind**: global constant  



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


**Kind**: global constant  

**See**: https://github.com/bettermusic/ChordSheetJS/issues/352  



## BRIDGE : string

Used to mark a paragraph as bridge


**Kind**: global constant  



## CHORUS : string

Used to mark a paragraph as chorus


**Kind**: global constant  



## GRID : string

Used to mark a paragraph as grid


**Kind**: global constant  



## INDETERMINATE : string

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


**Kind**: global constant  



## NONE : string

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


**Kind**: global constant  



## TAB : string

Used to mark a paragraph as tab


**Kind**: global constant  



## VERSE : string

Used to mark a paragraph as verse


**Kind**: global constant  



## LILYPOND : string

Used to mark a section as Lilypond notation


**Kind**: global constant  



## ABC : string

Used to mark a section as ABC music notation


**Kind**: global constant  



## scopedCss(scope) ⇒ string

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



## scopedCss(scope) ⇒ string

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



## getCapos(key) ⇒ Object.<string, string>

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](#Key) \| string | 
The key to get capos for
 |



## getKeys(key) ⇒ Array.<string>

Returns applicable keys to transpose to from the provided key


**Kind**: global function  

**Returns**: Array.<string> - 
The available keys
  

| Param | Type | Description |

| --- | --- | --- |

| key | [Key](#Key) \| string | 
The key to get keys for
 |