A TypeScript toolkit for parsing, analyzing, transposing, and formatting ChordPro songs. Part of ChordProject.
npm install @chordproject/parserChordProParser.parse() converts ChordPro source into a structured Song. The parser keeps
diagnostics on the parser instance so applications can show warnings beside the source or
translate them for their own UI.
import { ChordProParser, HtmlFormatter } from '@chordproject/parser';
const parser = new ChordProParser();
const song = parser.parse(`{title: Amazing Grace}
{key: G}
[G]Amazing [C]grace`);
const html = new HtmlFormatter().format(song);
const warnings = parser.warnings;Warnings expose a human-readable message, source lineNumber, stable code, and any
interpolation params. Use code and params instead of message when building localized
diagnostics.
Transposer returns a transformed song without mutating the original. transpose() moves the
song up or down one semitone; decapo() converts capo chord shapes to sounding pitches, while
applyCapo() transposes down and sets a capo.
import { ChordProParser, MusicTheoryHelper, Transposer } from '@chordproject/parser';
const song = new ChordProParser().parse('{key: G}\n[G]Amazing grace');
const upOneSemitone = Transposer.transpose(song, 'up');
const soundingPitches = Transposer.decapo(song);
const chordTones = MusicTheoryHelper.getChordTones('G'); // ['G', 'B', 'D']MusicTheoryHelper also provides key and enharmonic helpers for applications that need to
reason about notes and chord spelling.
The package includes ChordProFormatter, HtmlFormatter, and TextFormatter. All formatters
accept optional FormatterSettings; settings can also be changed after construction.
import { FormatterSettings, HtmlFormatter } from '@chordproject/parser';
const settings = new FormatterSettings();
settings.showChords = false;
settings.showTabs = true;
settings.showMetadata = false;
const formatter = new HtmlFormatter(settings);
const html = formatter.format(song);The parser builds structured song, section, lyric, chord, tab, and metadata models. It handles
common metadata directives, chord-and-lyric lines, section blocks, tab blocks, chord definitions,
comments, and custom metadata, and reports malformed or unsupported input through warnings.
The package also exports the underlying song and music models for applications that need to
inspect or compose parsed content.
Run the demo on http://localhost:8081:
npm install
npm run devRun the test suite, or the coverage-enabled CI suite:
npm test
npm run test:ciPublishing uses npm Trusted Publishing from GitHub Actions; no npm token is stored in GitHub.
In npm package settings, add a GitHub Actions trusted publisher for organization chordproject,
repository chordproject-parser, and workflow file publish.yml. After merging a version bump,
run npm run release for a patch, or npm run release:minor / npm run release:major. These
commands run CI tests, bump the version, commit and tag it, then push; GitHub Actions publishes
to npmjs.org using OIDC. For the already-prepared first release 1.2.0, run npm run release:current once instead of bumping again. The tag must match package.json.
Issues and pull requests are welcome. Join the community on Discord.