ChordPro file format parser and renderer

Navigation

Verified details

These details have been verified by PyPI
Project links
GitHub Statistics
Maintainers
Avatar for koedame from gravatar.com koedame

Unverified details

These details have not been verified by PyPI
Meta
  • License: MIT License (MIT)
  • Author: koedame
  • Tags chordpro , music , chord , parser , lyrics , rust , uniffi
  • Requires: Python >=3.8
Classifiers
Report project as malware

Project description

ChordSketch

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

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

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:

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; must fit in i8 (-128..=127). Out-of-range values raise ChordSketchError.InvalidConfig. None defaults to 0.

Basic rendering

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

Body-only HTML and stylesheet

Function Returns Description
parse_and_render_html_body(input, config_json, transpose) str Body-only <div class="song">…</div> HTML fragment with no <!DOCTYPE> / <html> / <head> / <title> / embedded <style> — pair with render_html_css when the host supplies its own document envelope
render_html_css() str Canonical chord-over-lyrics CSS that parse_and_render_html embeds inside <style> (byte-stable; safe to hash for cache-busting)
render_html_css_with_config_json(config_json) str Variant of render_html_css that honours settings.wraplines from the supplied config (when wraplines is false, .line emits flex-wrap: nowrap)

Captured warnings

Function Returns Description
parse_and_render_text_with_warnings(input, config_json, transpose) TextRenderWithWarnings { output: str, warnings: list[str] } Plain text + captured warnings
parse_and_render_html_with_warnings(input, config_json, transpose) TextRenderWithWarnings { output: str, warnings: list[str] } HTML + captured warnings
parse_and_render_pdf_with_warnings(input, config_json, transpose) PdfRenderWithWarnings { output: bytes, warnings: list[str] } PDF + captured warnings
parse_and_render_html_body_with_warnings(input, config_json, transpose) TextRenderWithWarnings { output: str, warnings: list[str] } Body-only HTML fragment + captured warnings (body counterpart to parse_and_render_html_with_warnings)

iReal Pro conversion

Function Returns Description
convert_chordpro_to_irealb(input) ConversionWithWarnings { output: str, warnings: list[str] } Convert ChordPro source to an irealb:// URL (lossy — drops lyrics, fonts, capo)
convert_irealb_to_chordpro_text(input) ConversionWithWarnings { output: str, warnings: list[str] } Convert an irealb:// URL to rendered ChordPro text
render_ireal_svg(input) str (SVG document) Render an irealb:// URL as an iReal Pro-style SVG chart
render_ireal_png(input) bytes (PNG byte stream) Render an irealb:// URL as a PNG image (300 DPI default, A4-equivalent canvas)
render_ireal_pdf(input) bytes (PDF byte stream) Render an irealb:// URL as a single-page A4 PDF document
parse_irealb(input) str (JSON) Parse an irealb:// URL into AST-shaped JSON (mirrors IrealSong)
serialize_irealb(input) str (URL) Serialize an AST-shaped JSON string back into an irealb:// URL (round-trips with parse_irealb)

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

Function Returns Description
validate(input) list[ValidationError] ({ line: int, column: int, message: str }, line / column one-based) Validate ChordPro input and return any parse errors as structured records (empty list if clean). Mirrors the WASM validate shape and the NAPI ValidationError[] interface. 
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

Function Returns Description
chord_diagram_svg(chord, instrument) str | None (SVG markup) Render a chord diagram as inline SVG. instrument is case-insensitive: "guitar", "ukulele" (alias "uke"), or "piano" (aliases "keyboard", "keys"). Returns None when the chord is not in the built-in voicing database; raises ChordSketchError.InvalidConfig on unknown instrument.

Utility

Function Returns Description
version() str Library version string 
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

License

MIT

Project details

Verified details

These details have been verified by PyPI
Project links
GitHub Statistics
Maintainers
Avatar for koedame from gravatar.com koedame

Unverified details

These details have not been verified by PyPI
Meta
  • License: MIT License (MIT)
  • Author: koedame
  • Tags chordpro , music , chord , parser , lyrics , rust , uniffi
  • Requires: Python >=3.8
Classifiers

Release history Release notifications | RSS feed

This version

0.5.0

0.4.0

0.3.0

0.2.2

0.2.1

0.2.0

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

chordsketch-0.5.0.tar.gz (6.2 MB view details)

Uploaded Source

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

chordsketch-0.5.0-py3-none-win_amd64.whl (7.3 MB view details)

Uploaded Python 3Windows x86-64

chordsketch-0.5.0-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (7.5 MB view details)

Uploaded Python 3manylinux: glibc 2.17+ x86-64

chordsketch-0.5.0-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (7.7 MB view details)

Uploaded Python 3manylinux: glibc 2.17+ ARM64

chordsketch-0.5.0-py3-none-macosx_11_0_arm64.whl (7.5 MB view details)

Uploaded Python 3macOS 11.0+ ARM64

chordsketch-0.5.0-py3-none-macosx_10_12_x86_64.whl (7.4 MB view details)

Uploaded Python 3macOS 10.12+ x86-64

File details

Details for the file chordsketch-0.5.0.tar.gz.

File metadata

  • Download URL: chordsketch-0.5.0.tar.gz
  • Upload date:
  • Size: 6.2 MB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: maturin/1.13.3

File hashes

Hashes for chordsketch-0.5.0.tar.gz
Algorithm Hash digest
SHA256 93f9c942a0b27843ad8a4a088b845f4f026ee757f7ced5b92b8ed9c085d4c080
MD5 8d00213bb7f54794b255dfb0b97c9d9b
BLAKE2b-256 7077b2e151acb574b7dd621dc64b32003dc115448b74704924dc7c9e1605e8c3

See more details on using hashes here.

File details

Details for the file chordsketch-0.5.0-py3-none-win_amd64.whl.

File metadata

File hashes

Hashes for chordsketch-0.5.0-py3-none-win_amd64.whl
Algorithm Hash digest
SHA256 84d314b3b8d3ce720d13a152b07deb77a2b46503e38b3850a310fb321a929c86
MD5 40a8b9a0cfa69e454ee5f57026e2749f
BLAKE2b-256 43fedde5c145f146dd42218651eb88bc0469c31bf55ad186ec2a471dcdea0914

See more details on using hashes here.

File details

Details for the file chordsketch-0.5.0-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for chordsketch-0.5.0-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 7c0ceef773adbf807ac71e723195ee417169fa0e94c3c02666a256d25eba588c
MD5 1b10b311a1dea53ca6e030de71eda8b2
BLAKE2b-256 89c926883af3c3a41c2f70a3be092ba6105965a367006109f2fe51503d07a8e3

See more details on using hashes here.

File details

Details for the file chordsketch-0.5.0-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl.

File metadata

File hashes

Hashes for chordsketch-0.5.0-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 b2cbd383bc07f6769b7d2a955c053b9d0b1d305c74a64a663c35033e96211737
MD5 e9ddc239f176bd98c03b8bd1a167f39a
BLAKE2b-256 71feedc9b8e5cfc921e6ce1d6537b5e1a80b841d54690c91368fc2cd44d9bc7d

See more details on using hashes here.

File details

Details for the file chordsketch-0.5.0-py3-none-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for chordsketch-0.5.0-py3-none-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 2fb20fbd96be711c1dd6c3c29e29041746901d8bba5a2020f5ddf740634444b6
MD5 37de5822de9fda03176163a0297c6d0b
BLAKE2b-256 90e03df36db71f4a6fd8d3be4f90be25e3cb6ba2dadf7b23b5e81ec7e356e0d4

See more details on using hashes here.

File details

Details for the file chordsketch-0.5.0-py3-none-macosx_10_12_x86_64.whl.

File metadata

File hashes

Hashes for chordsketch-0.5.0-py3-none-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 6da16cf26777da318bf3ad744c2d7b68e3a27b69269a88643ef9ab9d34f60bbc
MD5 47313f7a666c40ab08d771c4199be820
BLAKE2b-256 f5d994f7c4ca82f2c207c723d891fc9aace88e1017761e79e58fe4fcdfaff6b6

See more details on using hashes here.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page