@chordsketch/wasm

ChordSketch compiled to WebAssembly — parse and render ChordPro and iReal Pro chord charts in the browser or in Node.js with the same package.

Installation

Replace VERSION with the current version from the badge above.

npm install '@chordsketch/wasm@VERSION'

Usage

The package ships two builds under one name and uses Node's conditional exports to pick the right one for the runtime:

| Runtime | Build | Init required? | |---|---|---| | Browser (Vite, webpack, native ESM) | wasm-pack --target web | Yes — await init() | | Node.js (≥ 20) | wasm-pack --target nodejs | No — auto-loaded synchronously |

Browser

import init, {
  render_html,
  render_text,
  validate,
  version,
} from '@chordsketch/wasm';

// Browsers must initialize the WASM module first.
await init();

const chordpro = `{title: Amazing Grace}
{key: G}

[G]Amazing [G7]grace, how [C]sweet the [G]sound`;

const errors = validate(chordpro); // [] if valid
const html = render_html(chordpro);
const text = render_text(chordpro);
console.log(version());

Node.js

// No init() — the wasm-pack nodejs build auto-loads the .wasm file
// synchronously when the module is imported.
import {
  render_html,
  render_text,
  validate,
  version,
} from '@chordsketch/wasm';

const chordpro = `{title: Amazing Grace}
{key: G}

[G]Amazing [G7]grace, how [C]sweet the [G]sound`;

const errors = validate(chordpro); // [] if valid
const html = render_html(chordpro);
const text = render_text(chordpro);
console.log(version());

PDF / PNG export (separate package)

PDF (render_pdf) and iReal Pro PNG / PDF (renderIrealPng / renderIrealPdf) live in the sister package @chordsketch/wasm-export. It bundles the same lean API plus the resvg / svg2pdf / fontdb transitive dependency tree required for rasterisation and PDF emission, so it weighs ~25× more than this package (~10 MB raw vs ~400 KB). Install it on the side and dynamic-import it only when the user actually triggers an export:

const { render_pdf } = await import('@chordsketch/wasm-export');
const pdfBytes = render_pdf(chordpro); // Uint8Array

Rendering with options (both runtimes)

// Browser
import init, { render_html_with_options } from '@chordsketch/wasm';
await init();

// Node.js
import { render_html_with_options } from '@chordsketch/wasm';

const html = render_html_with_options(input, {
  transpose: 2,        // semitone offset (any integer; renderer reduces mod 12)
  config: 'ukulele',   // preset name or inline RRJSON config
});

API

Basic rendering

| Function | Input | Output | |----------|-------|--------| | render_html(input) | ChordPro string | HTML string | | render_text(input) | ChordPro string | Plain text string |

For render_pdf (ChordPro → PDF) use @chordsketch/wasm-export.

Rendering with options

| Function | Input | Output | |----------|-------|--------| | render_html_with_options(input, options) | ChordPro string + options | HTML string | | render_text_with_options(input, options) | ChordPro string + options | Plain text string |

For render_pdf_with_options use @chordsketch/wasm-export.

iReal Pro conversion

| Function | Input | Output | |----------|-------|--------| | convertChordproToIrealb(input) | ChordPro source | { output: string, warnings: string[] } — output is an irealb:// URL | | convertIrealbToChordproText(input) | irealb:// URL | { output: string, warnings: string[] } — output is rendered ChordPro text | | renderIrealSvg(input) | irealb:// URL | string — full SVG document (iReal Pro-style chart) | | parseIrealb(input) | irealb:// URL or irealbook:// URL | string — AST-shaped JSON mirroring IrealSong. Accepts both the canonical 7..=9-field irealb:// shape and the iRealBook 6-field irealbook:// shape (Title=Composer=Style=Key=TimeSig=Music). | | (iReal PNG / PDF rendering moved to @chordsketch/wasm-export) | | | | serializeIrealb(input) | AST-shaped JSON | string — irealb:// URL (round-trips with parseIrealb) | | chordTypography(chordJson) | AST-shaped chord JSON ({root, quality, bass, alternate?}) | string — JSON {spans: [{kind, text}, ...]} matching the iReal Pro engraved-chart convention. The renderer emits Root + Accidental + Extension + Slash + Bass span kinds; URL-stored quality shorthand (b/#/^/h/o/-) translates to typeset glyphs (♭/♯/Δ/ø/°/−); two-or-more-alteration extensions stack vertically via a \| separator (7♭9♯5 → 7♭9\|♯5). |

convertChordproToIrealb is lossy: lyrics, fonts / colours, and capo are dropped because iReal has no surface for them. Each drop appears in warnings as a "<kind>: <message>" string (kind is lossy-drop, approximated, or unsupported).

convertIrealbToChordproText returns the chordsketch-render-text rendering of the converted song, not raw ChordPro source — there is no source emitter yet.

import { convertChordproToIrealb, convertIrealbToChordproText } from '@chordsketch/wasm';

const { output: url, warnings } = convertChordproToIrealb('{title: Test}\n[C]Hello');
console.log(url);       // "irealb://..."
console.log(warnings);  // ["lossy-drop: lyrics are dropped", ...]

const { output: text } = convertIrealbToChordproText(url);
console.log(text);

Options

interface RenderOptions {
  transpose?: number;  // Semitone offset (any integer in i8 range; renderer reduces mod 12), default 0
  config?: string;     // Preset name ("guitar", "ukulele") or inline RRJSON
}

Validation

| Function | Input | Output | |----------|-------|--------| | validate(input) | ChordPro string | ValidationError[] — parse errors (empty if valid) |

Each ValidationError is {line, column, message} with one-based line and column numbers. Matches the NAPI (@chordsketch/node) binding.

Utility

| Function | Output | |----------|--------| | version() | Library version string |

Building from source

# From the repository root
cd packages/npm && npm run build

License

MIT