The harmony atlas

The harmony analysis run over the whole song corpus: which progressions the songs use most, a harmonic fingerprint per song, and the songs that share a progression with a given one.

What it is#

Each song is compiled and analysed exactly as the workbench's Lens reads it (volta_ui::harmonymodel::analyse_source: the playback-sidecar compile, the Lens note feed, volta_compiler::harmony_analysis::analyze), so a chord the atlas counts is the chord the harmony lane shows. The counting itself is pure and deterministic (volta_compiler::harmony_atlas).

• Progressions are roman-numeral n-grams of two to four chords. Numerals are key-relative (each chord against the key region in force, declared or detected), keep the chord quality (VImaj7, ivm9, V7), drop inversions, and collapse repeats by scale degree: a run on one degree (i → im7 → im9, an extension a melody note keeps toggling) is one chord, named by the numeral held longest. A chord with no numeral, or more than four beats with no confident chord, breaks the chain. A progression is ranked by how many songs use it, then by total occurrences, so one song's sixty-times loop does not outrank a habit shared by forty songs.
• A fingerprint per song: its keys (most-covering first), chord count, vocabulary (distinct numerals), the share of chords read exactly from a chord or numeral token, duration-weighted mean tension (0..1, the Lens tension) and its top progressions.
• Similar songs: cosine similarity over tf-idf-weighted progression counts (longer progressions weigh more, progressions most songs use weigh least), with the shared progressions behind each score.

Songs that sound no chord (library modules, drum-only sketches) are counted as skipped, not fingerprinted.

Using it#

cargo run --profile fast -p volta-cli --features atlas -- harmony-atlas
volta harmony-atlas --similar afterburn-04-glass-cathedral
volta harmony-atlas --json --top 20 examples/songs/cave-war-*.volta

With no paths it reads examples/songs/. --top N sets the rows per progression length (default 10); --similar <song> takes an id (the path under the folder, without .volta) or a unique suffix. The human output is the top progressions per length and a per-song table; --json prints the same data. The atlas feature is off by default because it links the workbench crate; the plain volta build prints how to enable it.

The MCP harmony_atlas tool reads each server root's examples/songs/: with no arguments the top progressions per length (n narrows to one length, limit sets the rows); song (an id, suffix or path) returns that song's fingerprint and its similar songs; progression ("ii V I", "ii-V-I") returns the songs that use it. The first call compiles every song; the result is cached until a file's size or modification time changes.

The corpus, measured#

A run over examples/songs/ (measured offline as the atlas shipped): 1,224 files, 1,107 analysed, 117 without chords, none failing to compile. The run is bounded by the slowest single compile (a few bowed-string songs take 30–60 s each to type check); wall time was 69–112 s on a heavily loaded ten-core machine, about 250 s of CPU in total.

The corpus is mostly minor-key (791 of the 1,107 songs open in a minor key) and mostly written as notes rather than chord tokens: 118 songs name any chord with a token, and on average 9% of a song's chords are read exactly. Its most widespread progressions:

Reading it: two-chord minor vamps dominate — VImaj7 ↔ ivm9 (in A minor, Fmaj7 ↔ Dm9), i ↔ VImaj7, the Dorian i ↔ IV9 and im9 ↔ IIImaj7; the one widespread four-chord cadence is the minor-key i · VI · III · VII (Am · F · C · G). Cadences lean on the subtonic: VII · i appears in 89 songs, V · i in 60, V7 · i in 39, and the major ii · V · I in one. A song that wants to sound like the corpus vamps on those pairs; one that wants to stand out reaches for a dominant, a borrowed chord or a key change, and harmony_atlas with song shows how close it sits to its neighbours.

Notes & limits#

• Detection reads extensions the voicing implies, so the same pad can read VImaj7 in one song and VImaj9 in another; the degree collapse keeps a run on one degree from fragmenting, but two songs voicing one progression differently still count as two progressions.
• The analysis covers one pass of each song (the Lens window). A song whose form only appears through live launching is read as the Map lays it out.
• Numerals are relative to the key in force, so a modulating song's progressions are counted in each local key, and a song with no confident key reads against its detected one.