Download the PHP package intelektron/chordpro-php without Composer

The chordpro-php library 🎸

A simple tool to parse, transpose & format ChordPro songs with lyrics & chords. Compatible with PHP 8.1 and above.

Forked from https://github.com/nicolaswurtz/chordpro-php by Nicolaz Wurtz, on LGPL-3 license.

The following output formats are currently supported:

• HTML (verses contain blocks with embedded span for aligning chords with lyrics).
• JSON (verses are arrays of chords and lyrics for alignment purposes).
• Plain text (chords are aligned with monospace text thanks to whitespace).

The library provides some extra functionality:

• Tranpose chords by semitones or to the target key.
• Parse and display various chord notations:
  • French (Do, Ré, Mi).
  • German (Fis, a).
  • With UTF characters (A♭, F♯).
• Guess the key of a song.

Installation

Via composer:

Usage

See web/example.php for demo with CSS styling.

Formatting options

Simply give an array with values at true or false for each key/option.

The song key

The key can be set/changed in the following ways:

• Manually, by calling $song->setKey('A').
• By parsing a song with metadata, e.g. {key:A}.
• By transposing the song to another key.

You can get the key by calling:

• $song->getKey() - get the key if it is defined by setKey(), otherwise, use the key from the metadata.
• $song->getMetadataKey() - get the key from the metadata.

If the song has no key defined, there is a possibility to guess it. This feature is experimental and not reliable (20% error rate, tested with ~1000 songs), but can be very useful.

Chord notations

The library supports several chord notations. You can also create your own (by implementing ChordNotationInterface.php. Notations are used for both parsing and formatting. So you can parse a song in German notation and display it as French:

At this point, fis is recognized and saved internally as F#m, and a is saved as Am. Note that you can pass multiple notations to the parser, in order of precedence. This can be useful if you have mixed up chord notations in one song.

Now, to show this song in French:

The UtfChordFormatter provides a nice-looking chords with ♭ and ♯ symbols instead of ASCII characters.

Styling the HTML code

Song lines

Lines are made up of blocks. Each block consists of a text and a chord. The chord has the class chordpro-chord and the text has the class chordpro-text.

A typical line of the song looks like this:

The data-chord attribute stores an English representation of the chord, regardless of the output notation.

Song sections

The ChordPro format allows to organize your songs into sections. The following song fragment:

Will be converted to:

You can use anything in place of foobar. However, the following shortcuts are supported:

• {soc} → {start_of_chorus}
• {eoc} → {end_of_chorus}
• {sov} → {start_of_verse}
• {eov} → {end_of_verse}
• {sob} → {start_of_bridge}
• {eob} → {end_of_bridge}
• {sot} → {start_of_tab}
• {eot} → {end_of_tab}
• {sog} → {start_of_grid}
• {eog} → {end_of_grid}

Metadata

The library reads ChordPro metadata and renders it as HTML in the following way:

Becomes:

The names of metadata are not restricted in any way, however, there are some standard ones described by ChordPro format. The following shortcuts are supported:

• {t} → {title}
• {st} → {subtitle}
• {c} → {comment}
• {ci} → {comment_italic}
• {cb} → {comment_box}

Extensions to ChordPro 6.x

The library provides some non-standard features that can be useful for songbook creators.

Inline chords

If you don't know how to assign the chord to syllables, or it's not important to you, you can use the inline chords assigned to the lyric line:

The chords appear above the line (in the HTML formatter) or to the right (in the monospace formatter).