chordlib

Rust helpers to parse, transform, and render chord-and-lyrics songs. The crate understands common formats (ChordPro, Ultimate Guitar tabs) and can render to HTML, ChordPro, or a terminal-friendly view.

Installation

cargo add chordlib

To install the CLI, enable the bin feature (and optionally html for Ultimate Guitar HTML parsing support):

cargo install chordlib --features "bin html"

Library example

use chordlib::inputs::chord_pro;
use chordlib::outputs::FormatRender;

fn main() -> Result<(), chordlib::Error> {
    let song = chord_pro::load_string(r#"
{title: Example Song}
{artist: An Artist}

[C]Line one with [G]chords
[F]Line two keeps the [C]beat
"#)?;

    // Render a terminal-friendly output.
    println!("{}", song.format_render(None, None, None));
    Ok(())
}

CLI quick start

Render a ChordPro/ChordPro-like file to HTML from this repository:

cargo run --features=bin -- path/to/song.wp -o path/to/song.html

Rendered HTML will be written to the path given after -o.

The CLI supports transposition (--key), Nashville notation (--nashville), vowel-based chord shifting (--vowel-move), and output formats including ChordPro (.cp/.wp), HTML, and JSON.

ChordPro I/O supports Nashville number notation for chords: you can load files that use numbers (e.g. [1][4][5], [1m][4][5]) when the key is set with a letter name (e.g. {key: C}). The {key: …} directive must be a letter name, not a number. Use the --nashville flag when writing ChordPro to output chords in Nashville form; the key is always written as a letter (e.g. {key: C}).

To parse an Ultimate Guitar tab from HTML, first obtain the HTML (for example by saving the page in a browser), read it into a string, and then call chordlib::inputs::ultimate_guitar::load_html(&html) from your own code. The library no longer performs live HTTP requests to Ultimate Guitar.

Benchmarks

HTML rendering performance benchmarks are available and require the Rust nightly toolchain because they use the unstable #[bench] harness:

rustup install nightly
cargo +nightly bench --bench html_render_bench

These benchmarks render real-world Worship Pro / ChordPro-style inputs (for example song/jesus_lebt3.wp, which includes a mix of normal and chord-only lines) through the same FormatHTML implementation used by the library and CLI. The crate itself remains fully compatible with stable Rust; only the benchmarks require nightly.

Feature flags

bin: build the chordlib CLI.
html: parse HTML tabs and render HTML output.