chordsketch

ChordSketch Python bindings — parse and render ChordPro and iReal Pro chord charts 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).

On Debian / Ubuntu the system Python refuses pip install outside a virtual environment (externally-managed-environment); create one first: python3 -m venv .venv && . .venv/bin/activate.

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, None, None)
text = chordsketch.parse_and_render_text(source, None, None)
pdf  = chordsketch.parse_and_render_pdf(source, None, None)   # bytes

print(chordsketch.version())

API

The tables below cover every function in crates/ffi/src/chordsketch.udl (UniFFI's namespace chordsketch { ... } block is the authoritative export surface for all language bindings).

Render-function parameters

parse_and_render_* functions all accept the same three arguments:

Basic rendering

Body-only HTML and stylesheet

Captured warnings

iReal Pro conversion

output of convert_irealb_to_chordpro_text is the rendered text representation of the converted song (chordsketch-render-text output), not raw ChordPro source. Each warnings entry is a "<kind>: <message>" string (kind is lossy-drop, approximated, or unsupported).

result = chordsketch.convert_chordpro_to_irealb("{title: Test}\n[C]Hello")
print(result.output)    # "irealb://..."
print(result.warnings)  # ["lossy-drop: lyrics are dropped", ...]

text = chordsketch.convert_irealb_to_chordpro_text(result.output)
print(text.output)

The *_with_warnings variants return the render warnings (transpose saturation, chorus recall limits, {columns} clamp, etc.) as a list alongside the output instead of forwarding them to sys.stderr / NSLog / System.err / $stderr. Use them when embedding ChordSketch in an app that needs to surface warnings in the UI or aggregate them. See #1827.

Validation

errors = chordsketch.validate(source)  # list[ValidationError] — empty if clean
for e in errors:
    print(f"line {e.line}, column {e.column}: {e.message}")

Chord diagrams

StaffNote exposes letter: str ("A"–"G"), accidental: int (signed semitone offset from the letter, -3..=3), octave: int (scientific-pitch-notation octave, middle C = C4), and midi: int (absolute MIDI note number).

Utility

print(chordsketch.version())  # e.g. "0.3.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 three variants:

• NoSongsFound — the input produced no parseable songs (rare with lenient parsing)
• InvalidConfig(reason) — the config_json argument is not a known preset and not valid RRJSON, or transpose is outside the i8 range, or chord_diagram_svg was called with an unsupported instrument
• ConversionFailed(reason) — a ChordPro ↔ iReal Pro conversion failed (convert_chordpro_to_irealb, convert_irealb_to_chordpro_text, render_ireal_*, parse_irealb, serialize_irealb)

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://koedame.github.io/chordsketch/
• Issues: https://github.com/koedame/chordsketch/issues

License

MIT