chordsketch 0.2.2

ChordPro file format parser and renderer

chordsketch

ChordSketch Python bindings — parse and render ChordPro files from Python via native Rust extensions generated by UniFFI.

Native extension — no pure-Python fallback. The library compiles to a platform wheel; prebuilt wheels for common platforms are published to PyPI so no Rust toolchain is needed to install.

Installation

pip install chordsketch

Requires Python 3.8+ (CPython or PyPy).

Quick Start

import chordsketch

source = """{title: Amazing Grace}
{key: G}

[G]Amazing [G7]grace, how [C]sweet the [G]sound"""

html = chordsketch.parse_and_render_html(source)
text = chordsketch.parse_and_render_text(source)
pdf  = chordsketch.parse_and_render_pdf(source)   # bytes

print(chordsketch.version())

API

Rendering

All render functions accept the same three arguments:

Parameter	Type	Description
input	str	ChordPro source text
config_json	str | None	Preset name ("guitar", "ukulele") or inline RRJSON; None for defaults
transpose	int | None	Semitone offset (-128..127); None defaults to 0

Function	Returns	Description
parse_and_render_text(input, config_json, transpose)	str	Plain text output
parse_and_render_html(input, config_json, transpose)	str	Full HTML document
parse_and_render_pdf(input, config_json, transpose)	bytes	Raw PDF bytes

Validation

errors = chordsketch.validate(source)  # list[str] — empty if clean
for msg in errors:
    print(msg)

Utility

print(chordsketch.version())  # e.g. "0.2.0"

Options

# Transpose up 2 semitones with the ukulele preset
html = chordsketch.parse_and_render_html(source, "ukulele", 2)

# Inline RRJSON configuration
html = chordsketch.parse_and_render_html(
    source,
    '{"settings": {"notation": "solfege"}}',
    None,
)

Error handling

Functions raise chordsketch.ChordSketchError on invalid configuration:

try:
    html = chordsketch.parse_and_render_html(source, "{ bad json !!!", None)
except chordsketch.ChordSketchError as e:
    print(e)

ChordSketchError has two variants:

• NoSongsFound — the input produced no parseable songs (rare with lenient parsing)
• InvalidConfig — the config_json argument is not a known preset and not valid RRJSON

Parse errors in the ChordPro input are not raised — the renderer is lenient and produces a best-effort result. Call validate() to surface diagnostics.

Links

• Project: https://github.com/koedame/chordsketch
• Playground: https://chordsketch.koeda.me
• Issues: https://github.com/koedame/chordsketch/issues

License

MIT