barmark
Musicians have written chord charts in plain text for decades: a row of bars between pipes, a chord or two in each, a heading for the verse. People read them easily. Machines do not, because the conventions are ambiguous in exactly the places that matter. Does an empty cell mean silence or the same chord again? Does "x 2" repeat the last chord or the whole line? barmark answers those questions in a written grammar, so a chart means the same thing to a band, a parser and a renderer.
A barmark file is a markdown file with the extension .chart.md, so any markdown tool shows it sensibly on day one. The barmark package parses a chart into bars in play order, sections, key, meter and tempo, and line-numbered diagnostics; it never throws, prints charts back in a canonical spelling, and converts chord symbols to and from Harte labels. @barmark/render turns a chart into a clean, evenly spaced bar grid, either as server-rendered HTML that needs no browser JavaScript or as the <barmark-chart> web component.
barmark was extracted from the chart parser in Stem Shovel, our music collaboration app, and its rules were checked by our stem-bench studies against real recordings. The grammar is a v0.1 draft, open for review. The code is MIT licensed, and the specification will be published under CC-BY 4.0.
bun add barmark @barmark/renderGitHub →npm: barmark →npm: @barmark/render →
What It Does
- A written grammar for the plain-text bar grid, with each trap documented
- parseChart never throws: broken lines are reported with line numbers and the rest still reads
- A canonical printer that changes spelling and layout only, never meaning
- Harte chord labels in both directions, checked against the McGill Billboard and Isophonics Beatles datasets
- @barmark/render: HTML with Declarative Shadow DOM, or the <barmark-chart> web component, with light and dark themes and screen-reader support