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.
ChordSketch is pre-1.0 and still in a validation phase. Until 1.0.0
ships, any release may break compatibility — public API items, rendered
output, CLI flags, binding surfaces, and the minimum supported Rust
version can all change in a 0.x bump, without a deprecation cycle.
Breaking changes are named in the CHANGELOG, and larger
ones get a guide under docs/migration/. Pin an exact
version if you depend on this crate today. The full policy is in
Versioning and release process.
{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 (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.no_chord → N.C. segment,
staff_texts → parenthesised inline text — plain captions
verbatim, `` 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)@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.
The same engine embedded through each UI package, one editable page per
binding: Vue and
Svelte. The ChordPro
playground above is the @chordsketch/react surface
(ADR-0053).
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:
See docs/editors.md for detailed setup instructions.
Install the /chordpro skill, which drives the CLI from natural language:
/plugin marketplace add koedame/chordsketch
/plugin install chordsketch@chordsketch
See packages/claude-code-plugin for what it covers.
The chordsketch binary is also a
Model Context Protocol server, so an
assistant that speaks MCP can render, parse, validate and tidy charts by
calling tools instead of shelling out. Point the client at the mcp
subcommand:
{
"mcpServers": {
"chordsketch": {
"command": "chordsketch",
"args": ["mcp"]
}
}
}
See docs/sdk/tasks/mcp.md for the tool list and what the server deliberately leaves to the CLI.
npm install @chordsketch/wasm
See the @chordsketch/wasm README for usage with JavaScript/TypeScript.
React, Vue and Svelte bindings that embed the ChordPro preview and editor:
npm install @chordsketch/react react react-dom
npm install @chordsketch/vue vue
npm install @chordsketch/svelte svelte
The wasm-free design-system primitives (buttons, cards, badges, form controls) ship on their own:
npm install @chordsketch/react-ui react react-dom
Usage lives in each package's README: @chordsketch/react, @chordsketch/vue, @chordsketch/svelte, @chordsketch/react-ui.
CLI (formula):
brew install --formula koedame/tap/chordsketch
Desktop app (cask, macOS only):
brew install --cask koedame/tap/chordsketch
The cask installs ChordSketch.app into /Applications/; Homebrew
clears the Gatekeeper quarantine flag automatically on install.
Both commands name the tap in full so that Homebrew taps koedame/tap
on demand and trusts just that one formula or cask; Homebrew 6.0.0 and
later refuse to load anything from an untrusted third-party tap. The
tap ships the CLI and the desktop app under the same chordsketch
name, so --formula and --cask say which of the two to install;
without either flag Homebrew picks the formula and warns that the name
was ambiguous.
sudo port install chordsketch
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.88 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.
All three bundles need glibc 2.35 or newer. Where they differ is webkit2gtk 4.1.
The .deb and the .rpm take it from the distribution, so they
install only where the distribution packages it: Ubuntu 22.04 and later
and Debian 12 and later (libwebkit2gtk-4.1-0), Fedora
(webkit2gtk4.1), and RHEL 10 / Rocky 10 / AlmaLinux 10 with EPEL
enabled (webkit2gtk4.1). Debian 11 and RHEL 8 / 9 — Rocky and
AlmaLinux included, with or without EPEL — package webkit2gtk 4.0 only,
so neither bundle can be installed there at any glibc version. In
practice the .rpm is a Fedora channel that also serves RHEL 10.
The .AppImage carries its own webkit2gtk 4.1 and asks the
distribution for nothing, but the glibc floor still applies: it runs on
RHEL 10 (glibc 2.39) and not on RHEL 8 (2.28) or RHEL 9 (2.34). RHEL 8
and 9 therefore have no desktop bundle in any format. The CLI is the
option there — it has no such constraint, running on glibc 2.18+ with
no system dependencies
(ADR-0056,
ADR-0057).
# 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 |
chordsketch-mcp | Model Context Protocol server (served by chordsketch mcp) |
| 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 / instead. |
@chordsketch/react | packages/react | React component library — embeds ChordPro and iReal Pro editors + previews in a few lines of React. |
@chordsketch/vue | packages/vue | Vue 3 component library — the same ChordPro preview, editor, chord diagrams, transpose control and PDF export, as Composition-API components. |
@chordsketch/svelte | packages/svelte | Svelte 5 component library — the same ChordPro preview, editor, chord diagrams, transpose control and PDF export, as runes-based components. |
@chordsketch/react-ui | packages/react-ui | Wasm-free React design-system primitives (buttons, cards, badges, form controls) for building app chrome around the editor. |
@chordsketch/chordpro-lite | packages/chordpro-lite | Dependency-free ChordPro helpers — format detection, lyric extraction, preview sampling — for consumers that must sniff or index a chart before loading the engine. |
@chordsketch/wasm-export | packages/npm-export | npm WASM package with the PDF / PNG export surface; loaded on demand by the export components. |
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 |
| Claude Code plugin | packages/claude-code-plugin | /chordpro skill for Claude Code, installed from this repository as a plugin marketplace |
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
The licences above cover the code, not the name. Describing, packaging, and building on ChordSketch never needs permission; naming your own product ChordSketch does. Forks are welcome and must rename — see TRADEMARK.md.