ChordSketch

May 30, 2026 · View on GitHub

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.

Features

ChordPro

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

iReal Pro

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

Try it Online

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.

Documentation

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

Editor Integration

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.

Installation

npm (WASM)

npm install @chordsketch/wasm

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

Homebrew (macOS / Linux)

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 (Windows)

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

winget (Windows)

winget install koedame.chordsketch

Chocolatey (Windows)

choco install chordsketch

Snap (Linux)

sudo snap install chordsketch

AUR (Arch Linux)

yay -S chordsketch

Docker

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

From crates.io

cargo install chordsketch

From source

Requires Rust 1.85 or later.

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

Desktop application

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.

Usage

# 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

Library Usage

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}");

Workspace Structure

Crate	Description
`chordsketch-chordpro`	ChordPro parser, AST, and transforms (zero external dependencies)
`chordsketch-render-text`	ChordPro plain text renderer
`chordsketch-render-html`	ChordPro HTML renderer
`chordsketch-render-pdf`	ChordPro PDF renderer
`chordsketch-ireal`	iReal Pro AST and `irealb://` URL parser / serializer (zero external dependencies)
`chordsketch-render-ireal`	iReal Pro chart renderer (SVG / PNG / PDF)
`chordsketch-convert`	Bidirectional ChordPro ↔ iReal Pro converter
`chordsketch-convert-musicxml`	MusicXML ↔ ChordPro bidirectional converter
`chordsketch-wasm`	WebAssembly bindings via wasm-bindgen
`chordsketch-ffi`	UniFFI bindings for Python, Ruby, Swift, and Kotlin
`chordsketch-napi`	Native Node.js addon via napi-rs
`chordsketch`	Command-line tool
`chordsketch-lsp`	Language Server Protocol server

Packages

Package	Path	Description
`@chordsketch/wasm`	`packages/npm`	npm WASM package with TypeScript types
`@chordsketch/node`	`crates/napi`	Native Node.js addon (prebuilt binaries, no Rust required)
`@chordsketch/ui-irealb-editor`	`packages/ui-irealb-editor`	Internal. Bar-grid GUI editor for iReal Pro charts; co-designed with the playground. External integrators should use `@chordsketch/react`'s `<IrealBarGrid>` / `<IrealProEditor>` instead.
`@chordsketch/react`	`packages/react`	React component library — embeds ChordPro and iReal Pro editors + previews in a few lines of React.
Python `chordsketch`	`crates/ffi`	Python package via UniFFI + maturin
Swift `ChordSketch`	`packages/swift`	Swift package with XCFramework
Kotlin `chordsketch`	`packages/kotlin`	Kotlin/JVM package via JNI
Ruby `chordsketch`	`packages/ruby`	Ruby gem via UniFFI
VS Code extension	`packages/vscode-extension`	Syntax highlighting, live preview, and LSP integration
JetBrains plugin	`packages/jetbrains-plugin`	TextMate syntax highlighting for JetBrains IDEs
Zed extension	`packages/zed-extension`	Tree-sitter highlighting and LSP for Zed
`tree-sitter-chordpro`	`packages/tree-sitter-chordpro`	Tree-sitter grammar for ChordPro
GitHub Action	`packages/github-action`	Composite action for rendering ChordPro in CI
Playground	`packages/playground`	Browser-based ChordPro and iReal Pro editor and renderer

GitHub Actions

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.

Migration Guides

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

License

SDK crates (core, renderers, CLI): MIT

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