ChordSketch Docs

ChordSketch SDK Guide

A unified entry point for using ChordSketch from any language or runtime. Pick a starting point that fits how you are integrating:

I want to do a specific thing

Each task page shows the same operation across every binding, so you can copy the snippet that matches your stack.

I know my language already

Language / runtime Package Per-package README (full reference)
Rust chordsketch-chordpro (parser/AST) + -render-text / -render-html / -render-pdf docs.rs/chordsketch-chordpro
Browser / Deno / Node ESM @chordsketch/wasm packages/npm/README.md
Node.js native addon @chordsketch/node crates/napi/README.md
Python chordsketch (UniFFI) crates/ffi/README.md
Swift ChordSketch (Swift Package + XCFramework) packages/swift/README.md
Kotlin / JVM me.koeda:chordsketch packages/kotlin/README.md
Ruby chordsketch packages/ruby/README.md
CLI / shell scripts chordsketch binary main README.md Installation section + chordsketch --help

The per-package READMEs are L2-quality (per .claude/rules/package-documentation.md) — install command, full API table, options. They are kept current with each release, so this guide intentionally does not duplicate them for binding-specific details. Cross-link to the relevant task page above when you need the same operation across multiple bindings (e.g. matching desktop and web renderings).

I want UI components

  • React: @chordsketch/react — published, includes both the ChordPro and iReal Pro embedding surfaces. v0.2.0 brings the iReal Pro surface to parity with the private @chordsketch/ui-irealb-editor: interactive bar grid, structural editing, keyboard navigation, and popover-based per-bar chord editing. See the Embed ChordPro and iReal Pro in a React app recipe guide.
  • Vue: @chordsketch/vue — the ChordPro surface as Vue 3 Composition-API components, with the same prop names, defaults and class vocabulary as the React package. See the Embed ChordPro in a Vue app recipe guide. The iReal Pro surface and the AST-walker interaction props are React-only.
  • Svelte: @chordsketch/svelte — the same ChordPro surface as Svelte 5 runes-based components, with the same prop names, defaults and class vocabulary as the React package. See the Embed ChordPro in a Svelte app recipe guide, and packages/svelte/README.md for the full API table. The iReal Pro surface and the AST-walker interaction props are React-only.
  • Other frameworks are tracked under #2039.

How the SDK fits together

ChordSketch is a Rust workspace at the bottom — chordsketch-chordpro parses ChordPro source into an AST, then the three renderer crates (chordsketch-render-{text,html,pdf}) walk the AST to produce output. Every other binding is a thin wrapper that exposes the same Rust API surface in idiomatic form for its host language:

           ┌──────────────────────────────────────────┐
           │  chordsketch-chordpro (parser + AST)     │
           │  chordsketch-render-{text,html,pdf}      │
           └──────────────────────────────────────────┘
                                ▲
       ┌──────────────┬─────────┴─────┬──────────────┐
       │              │               │              │
  chordsketch    chordsketch-    chordsketch-    chordsketch-
  (CLI binary)   wasm            napi            ffi (UniFFI)
                 (browser /      (Node.js              │
                 ESM)            native)               ▼
                                              ┌──────────────────┐
                                              │ Python  (PyPI)   │
                                              │ Swift   (XCFwk)  │
                                              │ Kotlin  (Maven)  │
                                              │ Ruby    (Gems)   │
                                              └──────────────────┘

chordsketch-ffi is the single UniFFI shared library that backs all four of the Python, Swift, Kotlin, and Ruby distributions. The per-language packages (pip install chordsketch, me.koeda:chordsketch, gem install chordsketch, the Swift package) each ship a thin language-binding layer on top of the same crates/ffi artefact — there is no separate chordsketch-ruby crate.

Because every binding wraps the same parser and renderers, the output of parseAndRenderHtml(input) (or its language-specific equivalent) is byte-identical across hosts for any given input. PRs that introduce per-binding output drift are caught by the fix-propagation rule (.claude/rules/fix-propagation.md).

Status

This guide is being written incrementally. Six task pages are landed. Two are per-operation (render, transpose) and cover every existing binding (Rust, WASM, NAPI, CLI, Python, Swift, Kotlin, Ruby); three are per-framework (embed-react, embed-vue, embed-svelte) and cover the UI component packages; one (mcp) covers the tool surface an AI assistant calls. Future additions will track new bindings and new operations as they are exposed:

  • AST-direct parse + traversal: the Rust crate exposes the AST as a host object graph, @chordsketch/wasm exposes it as JSON through parseChordpro (which is what @chordsketch/react's useChordproAst decodes), and the MCP server exposes it as the parse_chordpro tool. The NAPI and UniFFI bindings still expose the parser only via the parse_and_render_* one-shot. When AST projection lands there too, a tasks/parse.md page will be added.
  • Serialise back to ChordPro: not currently exposed by any binding. Tracked as part of the v0.3.0 multi-format track (#2050).
  • Static-site rendering: the canonical Markdown under docs/sdk/ is also rendered by the docs site at chordsketch.koeda.me/docs (ADR-0021). Both surfaces consume the same source — edits here propagate to both on the next deploy.
  • Live demos: each framework recipe has an editable page beside the docs — Vue, Svelte, and the ChordPro playground for React (ADR-0053).

If you find a gap, please file an issue.