git:20260926.1d01494 to git:20260926.4fa1459

---

name: song-analysis

description: Use when a song recording has to become tempo, time signature, key, stems, a bass line, chords per bar, lyric timing, a drum-pattern read, or a chord+lyric chart for a band — including songs in odd or unknown meters.

---

# Song Analysis — recording → bars, chords, lyrics, chart

Song-agnostic pipeline, validated over many real projects (dream pop, Greek laiko, punk

reinterpretations, drone/devotional). Works for any song, genre, key or meter.

**References (read on demand):**

- `references/meter-detection.md` — how the meter sweep works, reading its output, calibration

- `references/chart-and-lyrics.md` — chart structure, the lyric-placement rules, HTML output

- `references/drum-pattern-analysis.md` — kick/snare pattern reading; optional ADTOF

- `references/modal-theory.md` — the 7 modes and the mode test, power chords, Byzantine ≠ Phrygian

- `references/lead-and-keys-extraction.md` — isolated guitar/piano lines via `htdemucs_6s`

## Inputs

1. **Audio file** — mp3/wav of the song (full mix).

2. **Lyrics** — canonical text from an official source. Section labels (Verse, Chorus,

Bridge…) come from this, not from the analyzer.

## Tool per step

|---|---|---|

```

major/minor keys, and its probability is not a confidence on modal or drone material (a

```bash

```

**Cells.** Everything downstream (bass, chords, lyrics, chart) is keyed by `(bar, cell)`,

one cell per group in `grouping`: 4/4 → 2+2 (the familiar half-bars), 3/4 → one cell,

6/8 → 3+3, 11/8 as 6+5 → two unequal cells. Never split an odd bar at its midpoint.

`bass-transcribe` skill); basic-pitch only if the part is polyphonic. Then total each

pitch class's sounding time per `(bar, cell)` → `analysis/bass_per_cell.json`.

**Spell pitch classes from the key signature.** Flats for flat and neutral keys; sharps

for sharp keys — in F♯ minor a flat table writes the tonic `G♭m` and the dominant `D♭7`.

- Sub-0.5 s detections are noisy; ≥ 0.7 s sustained notes are usually right.

- Bass pedals, walks, sits on 3rds/5ths — it's a *clue* to the root, not the chord.

- **Bass enters late** in most songs: find the entry bar and ignore everything before it

(stem bleed).

```bash

```

Map each word to a bar:

```python

def locate(t, downbeats, beats_per_bar): # from foundation.json — never assume 4

for i in range(len(downbeats)-1):

if downbeats[i] <= t < downbeats[i+1]:

return (i+1, (t - downbeats[i]) / (downbeats[i+1] - downbeats[i]) * beats_per_bar)

return None

```

For each canonical lyric line, find its first bar via the word timings + `locate()`.

Section boundaries = where each labelled section's first line lands. Automatic

segmentation can *suggest* boundaries, never decide them: `as_seg` (barwise CBM, fed this

song's own bars, `penalty_weight=0`) hit 80% of lyric-anchored boundaries within ±1 bar on

```bash

<lv-venv>/bin/python scripts/lv_chords.py <song.mp3> --foundation analysis/foundation.json \

--compare analysis/chord_proposal.json --out analysis/chords_lv.json

```

Read `references/chart-and-lyrics.md` before building the chart. Core invariants:

- One row per section; parallel sections get identical row splits.

- Chart bar = audio bar. A virtual bar only where the audio has none (e.g. a rubato hold

the beat tracker skipped) — and mark it.

- Chord dict keyed by `(bar, cell)`.

- **Lyric phrases anchor at the chord they resolve INTO** (Rule 1 — the big one).

- Output: single self-contained HTML, print-friendly, harmonic-notes block at the bottom.

## Hard rules — the cardinal traps

### Trap 1 — A bass walk is one chord or two; the upper voicing decides

Bass moving within a bar (`C → A♭`) has two readings, and both are common: one held chord

over a moving bass (`Cm/A♭`, or a drone with a walking bass), or **two chords**

(`Cm → A♭`). The bass alone can't tell them apart, and a bass-constrained matcher follows

the bass, so it reports two chords either way. Look above the bass:

- **Re-attack** — a new voicing struck where the bass moves = two chords.

- **Register-pooled chroma** — pool chroma per cell in the chord instrument's register

(high-pass above ~165 Hz). The pitch-class set changes with the bass = two chords; it

stays put = one chord over a moving bass.

### Trap 2 — "Minor key" ≠ minor chords

Key estimators report the **melody's mode**, not chord quality. Many songs put major

triads under a minor melody — the bittersweet sound. Never propagate the key label to

chord quality; test each chord (major vs minor third, `chord-proposal.md`). Modal songs

often pivot between relative major and minor — label the key as a pair (`E♭ / Cm`).

### Trap 3 — The meter you never tested for looks like no meter at all

An odd cycle folded onto the wrong period gives a **flat** profile, not a low one — 11

folded onto 2, 3, 4 or 6 smears to near-uniform. Uniform contrast everywhere means the

right period hasn't been tested yet, never "no time signature". Assume odd meters are

live (`references/meter-detection.md`).

**Verify with a player.** Automated signals are wrong ~30% of the time on modal-mixture

songs. A musician who knows the song is ground truth — plan a verification pass before

declaring the chart done.

## Lessons learned

1. Trust the user's ear over any analyzer. Ask them to count — a player's count settles

in seconds what a sweep can only rank.

2. Never hand an analyzer a candidate list it can't say "none of these" to — a constrained

`beats_per_bar` and a key-gated major bias both produced confident wrong answers that

survived every downstream check.

3. Chord-recognition tools are starting points, never ground truth.

4. Whisper timing is precise; musical placement is not strict timing (Rule 1).

5. `basic-pitch` duplicates notes at exact octaves and invents low-register content the

stem doesn't contain. Floor it at the instrument's range (C3 for a piano out of

`other.wav`) before pushing anything to Ableton.

6. Each chart correction touches ~3 places (chord dict, row layout, cascading lyrics).

7. Mirror parallel sections visually; overlay section-boundary pickups in the same cell.