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

0.5.0

This version

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.4.0.tar.gz (6.0 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.4.0-py3-none-win_amd64.whl (8.1 MB view details)

Uploaded Python 3Windows x86-64

chordsketch-0.4.0-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (8.5 MB view details)

Uploaded Python 3manylinux: glibc 2.17+ x86-64

chordsketch-0.4.0-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (8.4 MB view details)

Uploaded Python 3manylinux: glibc 2.17+ ARM64

chordsketch-0.4.0-py3-none-macosx_11_0_arm64.whl (8.2 MB view details)

Uploaded Python 3macOS 11.0+ ARM64

chordsketch-0.4.0-py3-none-macosx_10_12_x86_64.whl (8.3 MB view details)

Uploaded Python 3macOS 10.12+ x86-64

File details

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

File metadata

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

File hashes

Hashes for chordsketch-0.4.0.tar.gz
Algorithm Hash digest
SHA256 d2d7d1da1437dd2c85734c6d2c0ef1c62f87c182613107528674ef3edc89fa8c
MD5 e15ebd2fa0539a4dd115f079580d4d03
BLAKE2b-256 b79a77fc1227d67dda841ac786f63124f710ad80dadd7ae2d7b109550e2653d1

See more details on using hashes here.

File details

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

File metadata

File hashes

Hashes for chordsketch-0.4.0-py3-none-win_amd64.whl
Algorithm Hash digest
SHA256 fbbee5b68ddd9ce2d6a334d3f1e282a72f579f3b47f861bf840d0f71abc7a3ee
MD5 8d26dbd5ab86bb59501c29d901b504c0
BLAKE2b-256 18d4ff1c43d17e373a9638985037600b62a06277e89a29085b30d01eff4567cc

See more details on using hashes here.

File details

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

File metadata

File hashes

Hashes for chordsketch-0.4.0-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 1b5cbf1fd6eea3d2a5d2bc3d26ffd2b1d2f60cac1e30bef46b8a8f307d00bd69
MD5 abdfa0c393b6a94a13293c3a468341da
BLAKE2b-256 b153066eaf8bdcfd3108e7c377b49929f54d7dad21464f5ac910131f1560f761

See more details on using hashes here.

File details

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

File metadata

File hashes

Hashes for chordsketch-0.4.0-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 d09c0e249491f2030e21f0733492d7634b8cfdd4bf4b575ec51f50e4a2bf2475
MD5 5f4126a6e4a94c09954a4b4789be8c6e
BLAKE2b-256 ceea85556ca91f20f213ca9ab06a454f4a509229ff2612e1b3edfbdf3a0e93af

See more details on using hashes here.

File details

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

File metadata

File hashes

Hashes for chordsketch-0.4.0-py3-none-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 a1e52114df655e53362172aa3a70974409604570b822755f29eed2ea81097666
MD5 22faeb9e88d2ed02cfa0813ec0584465
BLAKE2b-256 ac734d3eaf5b0c236710dcd56328cf762dc01bde05ca7482c243e64b918c5bd3

See more details on using hashes here.

File details

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

File metadata

File hashes

Hashes for chordsketch-0.4.0-py3-none-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 75755200ee362f2e91e33feff816af3e75c1f2bac0e594f9357095453196f7ef
MD5 1930d0b97ab08e382bb463b429fd581b
BLAKE2b-256 3d355cee9a181c33a52206e5a8caa0f4bcc6d0be2b2f39c04b6310fa6de27eac

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