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.

Stability

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.

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.

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

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)

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.

MacPorts (macOS)

sudo port install chordsketch

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.88 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.
@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/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

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

Links

• 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

License

SDK crates (core, renderers, CLI): MIT

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