ChordSketch

A Rust implementation of the ChordPro file format parser and renderer. 100% ChordPro compatible. Supports parsing ChordPro files into a structured AST and rendering to plain text, HTML, and PDF.

Features

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

Try it Online

ChordSketch Playground — try ChordPro rendering directly in your browser, no installation required.

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)

brew tap koedame/tap
brew 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.85 or later.

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

Usage

# Render to plain text (default)
chordsketch song.cho

# Render to HTML
chordsketch -f html song.cho -o song.html

# Render 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 files
chordsketch -f pdf song1.cho song2.cho -o songbook.pdf

Library Usage

The core parser and renderers are available as separate library crates:

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

Workspace Structure

Crate	Description
`chordsketch-core`	Parser, AST, and transforms (zero external dependencies)
`chordsketch-render-text`	Plain text renderer
`chordsketch-render-html`	HTML renderer
`chordsketch-render-pdf`	PDF renderer
`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)
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 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.

License

SDK crates (core, renderers, CLI): MIT

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

chordsketch

Runtime