winget install --id=koedame.chordsketch -e ChordSketch is a Rust implementation of the ChordPro file format parser and renderer. It is 100% ChordPro compatible and supports parsing ChordPro files into a structured AST and rendering them to plain text, HTML, or PDF. The CLI tool reads .cho files and writes the chosen output format to stdout or a file, with optional chord transposition and configuration overrides.
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.
{define} directives{new_song})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).(altchord) substitutions, n
no-chord, Kcl / x / r repeat-previous-measure, free-form captions, `S` segno, `Q` coda, / / macros, repeat / final / double / single barlines, and
N-th endings — all attached to the bar in which the marker
appears.b→♭, ^→Δ, h→ø, o→°, -→−, #→♯) and stacks
multi-alteration extensions ( → two-line ).
Available as a wasm export so React / Svelte /
external consumers can drive the same span layout.7♭9♯57♭9 / ♯5chordTypographyno_chord → N.C. segment,
text_comment → parenthesised inline text, 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)@chordsketch/ui-irealb-editor) with header
metadata editing, per-bar popovers, and structural section / bar
reorderingChordSketch 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 provides syntax highlighting and Language Server Protocol (LSP) support for multiple editors:
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}");
| 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 |
| 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-web | packages/ui-web | Framework-agnostic editor + preview UI shared by the playground and the desktop app |
@chordsketch/ui-irealb-editor | packages/ui-irealb-editor | Bar-grid GUI editor for iReal Pro charts; pluggable into @chordsketch/ui-web |
@chordsketch/react | packages/react | React component library |
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 |
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.
SDK crates (core, renderers, CLI): MIT
Future application layer (Forum, Playground, Desktop): AGPL-3.0-only