ChordProject Parser

A TypeScript toolkit for parsing, analyzing, transposing, and formatting ChordPro songs. Part of ChordProject.

Install

npm install @chordproject/parser

Parse a song

ChordProParser.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.

Transform and analyze

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.

Format output

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);

ChordPro coverage

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.

Development

Run the demo on http://localhost:8081:

npm install
npm run dev

Run the test suite, or the coverage-enabled CI suite:

npm test
npm run test:ci

Publishing

Publishing 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.

Contributing

Issues and pull requests are welcome. Join the community on Discord.

License

GNU Affero General Public License v3.0