# @chordsketch/wasm
[ChordSketch](https://github.com/koedame/chordsketch) compiled to
WebAssembly — parse and render [ChordPro](https://www.chordpro.org/) and
[iReal Pro](https://www.irealpro.com/) chord charts in the browser **or**
in Node.js with the same package.
## Installation
[](https://www.npmjs.com/package/@chordsketch/wasm)
Replace `VERSION` with the current version from the badge above.
```bash
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
```js
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
```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`](https://www.npmjs.com/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:
```js
const { render_pdf } = await import('@chordsketch/wasm-export');
const pdfBytes = render_pdf(chordpro); // Uint8Array
```
### Rendering with options (both runtimes)
```js
// 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 `": "` 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.
```js
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
```ts
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
```bash
# From the repository root
cd packages/npm && npm run build
```
## License
MIT