v0.3.1

The agent skill now writes out a song's chords, and installs into other agents too.

uv tool install --upgrade "chordotomy[model]"   # or pip install -U "chordotomy[model]"
npx skills add zeikar/chordotomy                # the skill, for Claude Code, Codex, Cursor and others

Everything still runs locally; your audio never leaves your machine.

What's new

• extract-chords replaces explain-harmony. Hand it a recording, a YouTube link or a .chords.json and it writes out the key and a timed chord chart; it explains the harmony when you ask. In the Claude Code plugin it is /chordotomy:extract-chords.
• skills.sh. npx skills add zeikar/chordotomy installs the skill for agents other than Claude Code. Installed that way, it runs this release through uvx with the model extra, or the DSP engine where torch has no build, as on an Intel Mac.
• Viewer. The big chord name keeps its descenders (the g of E♭aug is no longer clipped).
• PyPI. The description and keywords name chord recognition, key changes and the lv-chordia model, and the README is shorter, with install details moved to docs/install.md.

The timeline JSON is still schema 11, and the chord and beat scores are unchanged from 0.3.0.

v0.3.0

chordotomy now follows a song through its key changes, and a timeline can say where its recording came from.

uv tool install --upgrade "chordotomy[model]"   # or pip install -U "chordotomy[model]"
chordotomy analyze song.mp3 --source-url "https://www.youtube.com/watch?v=..."

Everything still runs locally; your audio never leaves your machine.

What's new

• Key regions. A song that changes key is split into regions, and every numeral, role and function is read in its own region's key. adrenaline!!!'s E → G → E → G → E → F now comes out as the song goes, where 0.2.0 read all of it in G major. The regions come from the chords alone, so editing a chord in the viewer moves them too. --key still analyzes the whole song in one key. docs/harmony.md has the rules, and docs/decisions.md the songs behind the penalty.
• --source-url. analyze stores the web page a recording came from in the JSON, and the viewer links to it. The CLI never fetches it.
• Viewer. Chords are named and spelled in their key region, and the key changes are listed. A timeline opened without its recording plays its chords alone. Corrections can add a ninth (Cadd9, Cmadd9).
• Bass (model engine). In band mixes, a root sounding below a bass inversion no longer wins over the inversion lv-chordia's bass head is sure of, so a D/F♯ stays D/F♯. The dataset scores are unchanged.
• Claude Code plugin. The explain-harmony skill takes a YouTube link (anything yt-dlp reads). It runs yt-dlp through uvx, so only ffmpeg has to be installed, and it explains key changes.
• Evaluation, for development. chordotomy evaluate --cache keeps the slow stages between runs, and chordotomy evaluate local <folder> scores your own recordings against chord charts you type in.

Breaking: the timeline JSON is schema 11

0.2.0 wrote schema 8.

• 9 added source.url.
• 10 added the key regions, and made numeral, role, function and target relative to the region containing the segment.
• 11 renamed key to global_key and keys to key_regions, and added the maj(9) and min(9) qualities with the add9 numeral. No recognizer writes them; they come only from corrections.

The viewer still opens schema 4 to 10 and saves 11. Anything else that reads the JSON should follow docs/timeline-json.md.

The chord and beat scores are unchanged from 0.2.0 on both engines.

v0.2.0

chordotomy is now on PyPI, and the model engine finds the beats with Beat This!.

uv tool install "chordotomy[model]"   # or pip install "chordotomy[model]"
chordotomy analyze song.mp3           # writes song.chords.json

Without [model] you get the DSP engine only. Everything still runs locally; your audio never leaves your machine.

What's new

• On PyPI. Install with uv tool install, pipx or pip instead of cloning the repository.
• Better beats for the model engine. Its beat grid now comes from Beat This! (Foscarin, Schlüter and Widmer, ISMIR 2024; code and weights MIT), whose beat activation feeds librosa's one-tempo tracker. The DSP engine keeps librosa's grid, so the two engines' beats can differ for the same file.
• chordotomy fetch-weights. Beat This!'s weights (81 MB) are downloaded on the first model-engine run into ~/.cache/chordotomy and checked against a pinned SHA-256 on every load. This command fetches them ahead of time. Without network and without the file, analyze stops with an error that names the fix; it never falls back silently.

Accuracy (model engine)

	before	now
Tiny AAM majmin / sevenths	0.934 / 0.898	0.950 / 0.914
GuitarSet majmin / sevenths	0.872 / 0.819	0.900 / 0.847
Beat F, Tiny AAM / GuitarSet	0.827 / 0.517	0.896 / 0.919

GuitarSet is in Beat This!'s training data, so its row is scored with the fold checkpoints, each take by the checkpoint that did not train on it. The DSP engine's scores are unchanged. These are development numbers, not a benchmark claim; docs/ARCHITECTURE.md has every column and its caveats.

The JSON format is unchanged (schema 8).

chordotomy 0.1.0

The first tagged release of chordotomy: give it a recording and it finds the chords on the beat, labels them with Roman numerals, and highlights the moves worth noticing. Everything runs locally; your audio never leaves your machine.

What's in it

• Chords on the beat: major, minor, dominant 7th, major 7th, minor 7th, half-diminished 7th, diminished 7th, sus4, 7sus4, augmented, diminished triad, sus2 and minor 6th, with N for no chord.
• Two engines: the lv-chordia model (Jiang, Chen, Li and Xia, ISMIR 2019; MIT code and weights) with uv sync --extra model, or chordotomy's own DSP front end without it.
• Key and Roman numerals with figured bass; secondary dominants, secondary leading-tone chords and borrowed chords are labeled.
• Bass and inversions: slash chords from the bass note, with a weak bass outside the chord shown at root position rather than as a doubtful slash chord.
• A viewer at https://zeikar.dev/chordotomy/ that plays the recording with its chords, plays the chords to check them by ear, and lets you correct and enter chords. It reads your files in the browser and uploads nothing.
• A Claude Code plugin with the explain-harmony skill, which explains the highlighted moves from the chord timeline.
• A documented JSON format (schema 8), described in docs/ARCHITECTURE.md.

Accuracy

Scored with mir_eval by chordotomy evaluate, duration-weighted:

	root	majmin	sevenths
Tiny AAM, lv-chordia model	0.939	0.934	0.898
Tiny AAM, DSP front end	0.842	0.803	0.768
GuitarSet, lv-chordia model	0.827	0.872	0.819
GuitarSet, DSP front end	0.722	0.696	0.583

Development numbers, not a benchmark claim; docs/ARCHITECTURE.md has every column and its caveats.

Install

git clone https://github.com/zeikar/chordotomy && cd chordotomy
uv sync --extra model          # or plain `uv sync` for the DSP only
uv run chordotomy analyze song.mp3