ChordSketch

A Rust implementation of the ChordPro and iReal Pro chord chart formats. 100% ChordPro compatible (parse to a structured AST, render to plain text, HTML, and PDF), full irealb:// URL parsing, iReal Pro chart rendering to SVG / PNG / PDF, and bidirectional ChordPro ↔ iReal Pro conversion.

• Full ChordPro format parser with zero external dependencies in the core crate
• Three output formats: plain text, HTML, and PDF
• Chord transposition
• Configuration file system (chordsketch.json)
• Inline markup (bold, italic, etc.)
• Chord diagrams (vertical or horizontal / left-nut orientation for Japanese tablature publishing) and extended {define} directives
• Section environments (verse, chorus, tab, grid, custom)
• Delegate environments (ABC, Lilypond, SVG, textblock)
• Conditional directive selectors (instrument, user)
• Multi-song files ({new_song})
• Font, size, and color directives
• Image directive
• Multi-page PDF with page control

• Full irealb:// URL parser (single-song and multi-song collections) with zero external dependencies in the core crate. Accepts both the canonical 7..=9-field irealb:// shape and the iRealBook 6-field irealbook:// shape (Title=Composer=Style=Key=TimeSig=Music).
• Complete URL grammar coverage: (altchord) substitutions, n no-chord, Kcl / x / r repeat-previous-measure, <text> free-form captions, S segno, Q coda, <D.C.> / <D.S.> / <Fine> macros, repeat / final / double / single barlines, and N-th endings — all attached to the bar in which the marker appears.
• Chart renderer producing SVG, PNG (via resvg), and PDF (via svg2pdf) — 4-bars-per-line grid layout that wraps continuously across section boundaries, repeat / final / double barlines, N-th-ending brackets, section-letter labels, and Bravura SMuFL music symbols (segno, coda). Chord-name typography translates URL-stored shorthand (b→♭, ^→Δ, h→ø, o→°, -→−, #→♯) and stacks multi-alteration extensions (7♭9♯5 → two-line 7♭9 / ♯5). Available as a chordTypography wasm export so React / Svelte / external consumers can drive the same span layout.
• Bidirectional ChordPro ↔ iReal Pro conversion with structured warnings for lossy drops. The iReal → ChordPro bridge handles the new AST fields end-to-end (no_chord → N.C. segment, staff_texts → parenthesised inline text — plain captions verbatim, <Nx> repeat-count overrides as (Nx), and <*XY...> vertical positions surfaced as LossyDrop warnings since ChordPro has no equivalent —, chord.alternate → parenthesised alternate after the primary).
• .irealb (single song) and .irealbook (multi-song collection) file extensions — picked up by the CLI sniff, the desktop OS file associations, and the editor integrations (VS Code, JetBrains, Zed)
• Bar-grid GUI editor (@chordsketch/ui-irealb-editor) with header metadata editing, per-bar popovers, and structural section / bar reordering

ChordSketch Playground — try ChordPro and iReal Pro rendering directly in your browser, no installation required. The format toggle in the header switches between the ChordPro text editor and the iReal Pro bar-grid GUI editor at runtime.

ChordSketch Docs — embedding recipes for @chordsketch/react, per-component API reference, and cross-binding render / transpose guides. The canonical Markdown sources live under docs/sdk/ and the docs site renders them in-place (see ADR-0021).

ChordSketch provides syntax highlighting and Language Server Protocol (LSP) support for multiple editors:

• VS Code / Cursor / Windsurf / VSCodium — install the ChordSketch extension
• JetBrains IDEs (IntelliJ IDEA, PyCharm, WebStorm, etc.) — install the ChordPro plugin
• Zed — install the ChordPro extension from the extensions panel
• Neovim — manual tree-sitter + LSP configuration
• Helix — manual grammar + LSP configuration

See docs/editors.md for detailed setup instructions.

npm install @chordsketch/wasm

See the @chordsketch/wasm README for usage with JavaScript/TypeScript.

Add the tap (required for both the CLI formula and the desktop cask):

brew tap koedame/tap

CLI (formula):

brew install chordsketch

Desktop app (cask, macOS only):

brew install --cask chordsketch

The cask installs ChordSketch.app into /Applications/; Homebrew clears the Gatekeeper quarantine flag automatically on install.

scoop bucket add koedame https://github.com/koedame/scoop-bucket
scoop install chordsketch

winget install koedame.chordsketch

choco install chordsketch

sudo snap install chordsketch

yay -S chordsketch

docker run --rm ghcr.io/koedame/chordsketch --version
docker run --rm -v "$PWD:/data" ghcr.io/koedame/chordsketch /data/song.cho

cargo install chordsketch

Requires Rust 1.85 or later.

git clone https://github.com/koedame/chordsketch.git
cd chordsketch
cargo install --path crates/cli

ChordSketch also ships a native desktop editor (Tauri v2) with live ChordPro preview, syntax highlighting, transpose, file open/save, and PDF / HTML export. Install via the Homebrew cask under ### Homebrew (macOS / Linux) above.

If you instead download the .dmg directly from a GitHub Release (bypassing Homebrew), macOS Gatekeeper will block the unsigned bundle on first open. Clear the flag manually:

xattr -dr com.apple.quarantine /Applications/ChordSketch.app

Apple Developer ID signing + notarization (so the flag is not needed regardless of install path) is tracked in #2075.

# Render a ChordPro file to plain text (default)
chordsketch song.cho

# Render a ChordPro file to HTML
chordsketch -f html song.cho -o song.html

# Render a ChordPro file to PDF
chordsketch -f pdf song.cho -o song.pdf

# Transpose up 2 semitones
chordsketch --transpose 2 song.cho

# Use a custom config file
chordsketch -c myconfig.json song.cho

# Process multiple ChordPro files
chordsketch -f pdf song1.cho song2.cho -o songbook.pdf

# Render an iReal Pro chart from a URL (always emits SVG)
chordsketch 'irealb://%54=…'

# Render an iReal Pro chart from an .irealb file (single song)
chordsketch song.irealb

# Render an iReal Pro chart from an .irealbook file (multi-song collection)
chordsketch songs.irealbook

The core parsers and renderers are available as separate library crates, one set per format. ChordPro:

use chordsketch_chordpro::parser::parse;
use chordsketch_render_text::render_song;

let input = "{title: Amazing Grace}\n{subtitle: Traditional}\n\n[G]Amazing [G7]grace, how [C]sweet the [G]sound";
let song = parse(input).unwrap();
let text = render_song(&song);
println!("{text}");

iReal Pro:

use chordsketch_ireal::parse as parse_ireal;
use chordsketch_render_ireal::{render_svg, RenderOptions};

let url = "irealb://%54=%66==%41%66%72%6F=%43==%31%72%33%34%4C%62%4B%63%75%37,%37%47,%2D%20%3E%43,%44,%37%42,%2D%23%46,%47%7C,%37%44,%41%2D,%45,%2D%45%7C,%37%42,%2D%23%46,%45%2D,%7C%44%3C%34%33%54%7C%43,%44%2D%37,%7C%46,%47%37,%43%20%7C%20==%31%34%30=%33";
let song = parse_ireal(url).expect("valid irealb URL");
let svg = render_svg(&song, &RenderOptions::default());
println!("{svg}");

Use the composite action to render ChordPro files in any GitHub Actions workflow — no Rust toolchain required:

- uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6

- uses: koedame/chordsketch/packages/github-action@action-v1
  id: render
  with:
    input: songs/setlist.cho
    output: dist/setlist.html
    format: html

- uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
  with:
    name: setlist-html
    path: ${{ steps.render.outputs.output-path }}

See docs/github-action.md for full input/output reference and additional examples.

• v0.3.0 — chordsketch-core → chordsketch-chordpro rename

• ChordPro file format specification
• Unified SDK guide (all bindings, task-oriented)
• Editor integration guide
• Configuration guide
• Versioning and release process
• GitHub Action reference
• Architecture decision records
• SECURITY.md
• CHANGELOG.md

SDK crates (core, renderers, CLI): MIT

Future application layer (Forum, Playground, Desktop): AGPL-3.0-only