chordlang

Live demo: borkxs.github.io/chordlang · npm @chordlang/*

CI · Pages deploy · Releases

chordlang is three related pieces for properly engraved jazz harmony:

• ChordFont — an OpenType font that shapes ASCII chord symbols via ligatures
• Charts — a text format (.cfmd) for lead-sheet chord changes
• Graphs — Graphviz DOT files (.cfgv) for harmonic progressions

Plain text in, engraved output out — no CSS superscript hacks.

Cmaj7 Dm7b5 F#m7 G13 Bb7

Install from npm

All packages are published at 0.1.1 under the @chordlang scope:

Package	Role
@chordlang/parser	.cfmd chart grammar → AST
@chordlang/chord	chord-symbol normalizer
@chordlang/render	AST → engraved HTML + chart.css
@chordlang/font	ChordFont TTF (OFL)
@chordlang/graph	Graphviz DOT → styled SVG
@chordlang/cli	chordlang <mode> file.cfmd (ast, canonical, html)

npm install @chordlang/parser @chordlang/chord @chordlang/render @chordlang/font
# optional: graphs + CLI
npm install @chordlang/graph @chordlang/cli

Minimal HTML pipeline:

import { parseChart } from "@chordlang/parser";
import { normalize } from "@chordlang/chord";
import { renderChartToHTML } from "@chordlang/render";
import "@chordlang/render/chart.css";
// @font-face ChordFont from @chordlang/font/ChordProof.ttf

Quick start

make setup     # install (pnpm) + Playwright chromium
make dev       # live playground — type text, watch it engrave
make test      # vitest across packages
make previews  # regenerate docs/assets/ preview images
make help      # every target, self-documented

Preview images are committed PNGs, not live GitHub renders — see docs/readme-previews.md for when to re-run and commit.

ChordFont

An OpenType font that engraves single-line jazz chord symbols from plain ASCII via GSUB ligatures — the shaping engine does the work, no JavaScript at render time. Outlines derived from Petaluma (OFL). Build and spec: packages/font/.

Source (examples/font/readme-symbols.txt):

Cmaj7 Dm7b5 F#m7 G13 Bb7

Charts

Lead-sheet chord changes in .cfmd — a Peggy grammar for structure, ChordFont for symbols. Commas subdivide a bar into equal beat-slots; % repeats the previous bar; [A] marks a form section. Grammar IS the spec: packages/parser/src/chart.peggy.

Source (examples/charts/blues-in-f.cfmd):

{title: F Blues}
{key: F}
| F7 | Bb7 | F7 | Cm7,F7 |
| Bb7 | % | F7 | Am7b5,D7 |
| Gm7 | C7 | F7,D7 | Gm7,C7 |

More charts in examples/charts/ · live edit with make dev.

Graphs

Harmonic progressions as standard Graphviz DOT in .cfgv. Node labels use fontname="ChordFont"; chordlang post-styles the SVG.

Source (examples/graphs/ii-v-i-chain.cfgv):

digraph {
  rankdir=LR;
  graph [bgcolor="transparent" pad=0.4];
  node [shape=plaintext fontname="ChordFont" fontsize=36];
  edge [color="#6f6a5e" penwidth=1.4 arrowsize=0.7];

  Am7 -> D7 -> Gmaj7 -> Cmaj7 -> "F#m7b5" -> B7 -> Em7;
}

More graphs in examples/graphs/ · HTML gallery with make graphs.

Beyond Graphviz — free integrations

Graphviz needed zero chordlang code: it shapes text with HarfBuzz, so the font engraves the symbols itself. The same is true of any tool with a modern text stack — verified so far: XeLaTeX / LuaLaTeX (fontspec), Typst, LilyPond (chord symbols above real staves), LibreOffice Writer (type Cmaj7, watch it engrave live), Inkscape, GIMP, Qt, Pango, and ffmpeg drawtext (video overlays). Install the TTF at the OS level and it shows up in every native app's font menu. Runnable sources in examples/integrations/; recipes and gotchas in docs/font-integrations.md.

Prior art

“Chord chart” here means lead-sheet chord changes — the bar-grid notation musicians use in Real Book charts, iReal Pro, ChordPro, and similar tools. chordlang borrows structure conventions from that world (design references only; no code imported — see ADR-001):

Convention	Familiar from
| bar | bar | grid	lead sheets / fake books
Cm7,F7 — comma subdivides a bar into equal beats	QuickChords, iReal Pro
{title: …} metadata directives	ChordPro
[A] form-section labels	iReal Pro
% repeats the previous bar	iReal Pro

What is not borrowed: symbol engraving. Most web renderers fake chord typography with HTML/CSS; chordlang types ASCII and lets ChordFont shape it via OpenType ligatures.

Dependencies

Component	Role	License
tonal	chord-symbol parsing / normalization	MIT
Petaluma	glyph outlines for ChordFont	OFL
Peggy	chart grammar → parser	MIT
Graphviz	.cfgv harmonic graph layout	EPL
fonttools, uharfbuzz, cu2qu	ChordFont build + shaping tests	MIT / Apache / MIT

Dev-only: Playwright (README preview screenshots), Vite (playground).

Related

• CHANGELOG.md — release history (v0.1.0, v0.1.1)
• DECISIONS.md — architecture notes (grammar spec, tonal wrapper, rendering split)
• CODEBASE.md — package map and data flow
• PUBLISH_CHECKLIST.md — post-launch polish and release housekeeping
• docs/readme-previews.md — regenerating README preview PNGs
• examples/README.md — editing .cfmd / .cfgv sources

Topics: chord-charts, lead-sheet, jazz, chord-symbols, open-type, graphviz.

chordlang and ChordFont are project names for this open-source work. They are not affiliated with or endorsed by iReal Pro, Hal Leonard, or other commercial chart products cited as design references.

Layout

examples/           .cfmd / .cfgv / .txt sources + manifest
docs/assets/        committed preview PNGs (make previews)
packages/chord      normalize(symbol) → canonical struct
packages/parser     Peggy chart grammar → AST (grammar IS the spec)
packages/graph      Graphviz DOT → styled SVG for .cfgv graphs
packages/render     AST + chart.css → engraved HTML
packages/font       ChordFont OpenType build (Python)
packages/cli        chordlang <ast|canonical|html> file.cfmd
apps/playground     live preview (src-aliased packages)
tools/corpus        stub: McGill/Weimar frequency mining (future)