ChordSketch

A Rust implementation of the ChordPro and iReal Pro chord chart formats. It reads ChordPro files (parse to a structured AST, render to plain text, HTML, and PDF), parses irealb:// URLs, renders iReal Pro charts to SVG / PNG / PDF, and converts between ChordPro and iReal Pro.

ChordSketch is not a drop-in replacement for the Perl ChordPro implementation. It parses every directive that ChordPro R6.101.0 does except six obsolete ones, but its output is not identical to Perl's and it offers fewer output formats. See Known Deviations for the list.

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.

• ChordPro format parser with zero external dependencies in the core crate. Parses the directives of ChordPro R6.101.0 except six obsolete ones (details)
• 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
• Audible preview in the React components: with chord audio switched on, click a chord diagram to hear the voicing it draws; click the {key} chip to hear the scale and tonic chord, or the {tempo} chip for a metronome

• 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).
• URL constructs handled: (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.

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:

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

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/. The app is not yet signed or notarized, so macOS blocks its first launch; see Desktop application for how to open it.

Desktop app, built on your machine (formula, macOS only):

brew install --formula koedame/tap/chordsketch-desktop
cp -R "$(brew --prefix chordsketch-desktop)/ChordSketch.app" /Applications/

This compiles the app from the release source instead of downloading the prebuilt .dmg, so it differs from the cask in four ways: the build takes about 10 minutes, it needs the Xcode Command Line Tools (xcode-select --install), /Applications/ gets the app only when you run the cp line yourself, and macOS does not block its first launch because no quarantined download is involved.

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

The Chocolatey community repository reviews each new version by hand, so choco install can install an older release than the other channels. The package page shows the current version.

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 or the build-it-yourself formula under ### Homebrew (macOS / Linux) above.

On Windows the installer also registers a File Explorer preview handler, so .cho / .chopro / .crd / .chordpro files render in Explorer's preview pane.

The app checks for updates when it starts and every 24 hours while it runs. The check is one ordinary HTTPS GET request for https://raw.githubusercontent.com/koedame/chordsketch/desktop-updater-manifest/latest.json; it carries no identifier, no document content, and not even your app or OS version (the request header names only the updater library), but GitHub sees your IP address like any web server does. If a newer version exists, the app shows its release notes and installs it only after you accept. The Flatpak build never checks (the store delivers updates). To stop the automatic check, turn off Help → Check for Updates Automatically; the choice is kept between launches. Help → Check for Updates Now still checks when you ask for it. See Privacy.

The macOS app is not yet signed or notarized by Apple, so Gatekeeper blocks its first launch whether you installed it with the Homebrew cask or downloaded the .dmg from a GitHub Release. (The chordsketch-desktop formula builds the app locally, so it is not quarantined and needs none of the steps below.) Homebrew leaves the quarantine flag on cask downloads so that Gatekeeper still makes its own checks. Do one of the following once, after installing:

• Clear the quarantine flag:

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

• Or try to open the app once, then go to System Settings → Privacy & Security and choose "Open Anyway".

Apple Developer ID signing + notarization (so neither step is 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).

The libraries the .AppImage carries (webkit2gtk, GTK, GLib and what they need, mostly LGPL) are listed with their versions, source packages and license texts in usr/share/doc/chordsketch-desktop/bundled-libraries.txt inside the image; each desktop release publishes the same file as chordsketch-desktop-linux-bundled-libraries.txt.

# 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
• TRADEMARK.md
• CHANGELOG.md

ChordSketch collects nothing: there is no telemetry, analytics, crash reporting, or account, and the documents you edit never leave your device. The playground parses and renders in your browser (WebAssembly); the command-line tool, the libraries, and the editor integrations do their work locally.

These are the only network connections ChordSketch itself makes, and what the other side can see:

Installing ChordSketch through a package manager, cargo, or npm contacts that registry, not ChordSketch.

When a change adds a connection, it updates this section in the same pull request.

ChordSketch has two layers, split by directory. The licence text is in each directory, so a package you download carries its own copy.

@chordsketch/react and the other published libraries are MIT, so you can embed them in a closed-source product. The desktop app, the playground and the iReal Pro editor are AGPL-3.0-only: code copied from them into another program has to follow that licence. GitHub shows the repository as MIT because it reads only the root LICENSE.

Third-party dependency notices are in NOTICE and THIRD_PARTY_LICENSES.md. They ship with the CLI archives, container images, the desktop app, the VS Code extension, the wasm and napi npm packages, and the PyPI, RubyGems, Maven, and Swift packages — see ADR-0085.

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.

ChordPro is the name of a file format and of its reference program by The ChordPro Team; iReal Pro is a product of Technimo LLC; MusicXML is published by the W3C Music Notation Community Group; Bravura is a font by Steinberg Media Technologies GmbH. These names belong to their owners. ChordSketch is not affiliated with or endorsed by any of them. They appear here only to say which formats and fonts ChordSketch reads, writes or embeds.