danceflow-stemlab 1.0.0__py3-none-any.whl

stemlab/analysis/harmony.py

@@ -0,0 +1,375 @@
+from __future__ import annotations
+
+import math
+import re
+from collections import Counter
+from pathlib import Path
+from typing import Any
+
+import numpy as np
+
+from stemlab.types import BeatResult
+from stemlab.util import write_json
+
+PITCHES_C = ["C", "C#", "D", "Eb", "E", "F", "F#", "G", "Ab", "A", "Bb", "B"]
+PITCH_TO_PC = {name: i for i, name in enumerate(PITCHES_C)}
+PITCH_TO_PC.update({"Db": 1, "D#": 3, "Gb": 6, "G#": 8, "A#": 10})
+
+# Krumhansl-Schmuckler profiles, C-rooted.
+MAJOR_PROFILE = np.asarray([6.35, 2.23, 3.48, 2.33, 4.38, 4.09, 2.52, 5.19, 2.39, 3.66, 2.29, 2.88], dtype=float)
+MINOR_PROFILE = np.asarray([6.33, 2.68, 3.52, 5.38, 2.60, 3.53, 2.54, 4.75, 3.98, 2.69, 3.34, 3.17], dtype=float)
+
+
+def _find_analysis(vamp_result: dict[str, Any] | None, slug: str) -> dict[str, Any] | None:
+    if not vamp_result:
+        return None
+    for item in vamp_result.get("analyses", []):
+        if item.get("slug") == slug:
+            return item
+    return None
+
+
+def _normalise_chord(label: str) -> str:
+    label = (label or "").strip()
+    if not label:
+        return "N"
+    if label.lower() in {"n", "no chord", "none"}:
+        return "N"
+    return re.sub(r"\s+", "", label)
+
+
+def _chord_root(label: str) -> str | None:
+    m = re.match(r"^([A-Ga-g])([#b]?)", label)
+    if not m:
+        return None
+    return m.group(1).upper() + m.group(2)
+
+
+def _chord_quality(label: str) -> str:
+    lower = label.lower()
+    tail = lower[len(_chord_root(label) or "") :]
+    if "dim" in tail or "°" in tail:
+        return "diminished"
+    if "aug" in tail or "+" in tail:
+        return "augmented"
+    if "sus" in tail:
+        return "suspended"
+    if ":min" in tail or tail.startswith("m") and not tail.startswith("maj"):
+        return "minor"
+    if ":maj" in tail or "maj" in tail:
+        return "major"
+    return "major"
+
+
+def _parse_key(label: Any) -> tuple[int, str] | None:
+    if label is None:
+        return None
+    text = str(label).strip().replace(":", " ")
+    match = re.match(r"^([A-Ga-g])([#b]?)(?:\s+)?(major|minor|maj|min|m)?", text, re.I)
+    if not match:
+        return None
+    root_name = match.group(1).upper() + match.group(2)
+    pc = PITCH_TO_PC.get(root_name)
+    if pc is None:
+        return None
+    mode_raw = (match.group(3) or "major").lower()
+    mode = "minor" if mode_raw in {"minor", "min", "m"} else "major"
+    return pc, mode
+
+
+def _degree_name(interval: int, quality: str) -> str:
+    # Chromatic scale-degree spelling optimized for readable MIR summaries.
+    degree = {
+        0: "I", 1: "bII", 2: "II", 3: "bIII", 4: "III", 5: "IV",
+        6: "#IV", 7: "V", 8: "bVI", 9: "VI", 10: "bVII", 11: "VII",
+    }[interval % 12]
+    if quality == "minor":
+        return degree.lower()
+    if quality == "diminished":
+        return degree.lower() + "°"
+    if quality == "augmented":
+        return degree + "+"
+    if quality == "suspended":
+        return degree + "sus"
+    return degree
+
+
+def _functional_harmony(chords: list[dict[str, Any]], key_label: Any) -> dict[str, Any] | None:
+    parsed = _parse_key(key_label)
+    if not parsed:
+        return None
+    tonic, mode = parsed
+    diatonic_intervals = {0, 2, 4, 5, 7, 9, 11} if mode == "major" else {0, 2, 3, 5, 7, 8, 10}
+    progression = []
+    duration_by_degree: Counter[str] = Counter()
+    roots: list[int] = []
+    for chord in chords:
+        root_name = _chord_root(chord["label"])
+        root = PITCH_TO_PC.get(root_name) if root_name else None
+        if root is None:
+            progression.append({**chord, "degree": None, "diatonic_root": None})
+            continue
+        interval = (root - tonic) % 12
+        quality = _chord_quality(chord["label"])
+        degree = _degree_name(interval, quality)
+        duration_by_degree[degree] += float(chord.get("duration") or 0.0)
+        roots.append(root)
+        progression.append(
+            {
+                **chord,
+                "root": root_name,
+                "quality": quality,
+                "degree": degree,
+                "diatonic_root": interval in diatonic_intervals,
+            }
+        )
+
+    motions = Counter()
+    for a, b in zip(roots, roots[1:]):
+        motions[(b - a) % 12] += 1
+    motion_names = {
+        0: "same root", 1: "up semitone", 2: "up whole tone", 3: "up minor third",
+        4: "up major third", 5: "up fourth / down fifth", 6: "tritone",
+        7: "up fifth / down fourth", 8: "down major third", 9: "down minor third",
+        10: "down whole tone", 11: "down semitone",
+    }
+
+    cadences = []
+    for prev, cur in zip(progression, progression[1:]):
+        a, b = prev.get("degree"), cur.get("degree")
+        if not a or not b:
+            continue
+        a_base = a.replace("°", "").replace("+", "").replace("sus", "").upper()
+        b_base = b.replace("°", "").replace("+", "").replace("sus", "").upper()
+        kind = None
+        if a_base == "V" and b_base == "I":
+            kind = "dominant-tonic"
+        elif a_base == "IV" and b_base == "I":
+            kind = "plagal"
+        elif a_base == "II" and b_base == "V":
+            kind = "predominant-dominant"
+        elif a_base == "BVII" and b_base == "I":
+            kind = "backdoor/modal bVII-I"
+        if kind:
+            cadences.append(
+                {
+                    "type": kind,
+                    "from": prev["label"],
+                    "to": cur["label"],
+                    "time_seconds": float(cur["start"]),
+                }
+            )
+
+    total = sum(float(x.get("duration") or 0.0) for x in progression)
+    tonic_duration = sum(float(x.get("duration") or 0.0) for x in progression if (x.get("root") and PITCH_TO_PC.get(x["root"]) == tonic))
+    dominant_pc = (tonic + 7) % 12
+    dominant_duration = sum(float(x.get("duration") or 0.0) for x in progression if (x.get("root") and PITCH_TO_PC.get(x["root"]) == dominant_pc))
+    valid = [x for x in progression if x.get("diatonic_root") is not None]
+    chromatic = [x for x in valid if not x["diatonic_root"]]
+    return {
+        "key_basis": str(key_label),
+        "mode": mode,
+        "progression": progression,
+        "diatonic_root_share": float((len(valid) - len(chromatic)) / len(valid)) if valid else None,
+        "chromatic_root_events": len(chromatic),
+        "tonic_duration_share": float(tonic_duration / total) if total else None,
+        "dominant_duration_share": float(dominant_duration / total) if total else None,
+        "degree_duration_histogram": [
+            {"degree": degree, "seconds": float(seconds)}
+            for degree, seconds in duration_by_degree.most_common()
+        ],
+        "root_motion": [
+            {"semitones_up_mod12": int(interval), "name": motion_names[interval], "count": int(count)}
+            for interval, count in motions.most_common()
+        ],
+        "cadence_candidates": cadences,
+    }
+
+
+def _duration(event: dict[str, Any]) -> float:
+    start = float(event.get("start") or 0.0)
+    end = event.get("end")
+    if end is None:
+        return 0.0
+    return max(0.0, float(end) - start)
+
+
+def _collapse_progression(events: list[dict[str, Any]]) -> list[dict[str, Any]]:
+    out: list[dict[str, Any]] = []
+    for event in events:
+        label = _normalise_chord(str(event.get("label") or ""))
+        start = float(event.get("start") or 0.0)
+        end = float(event.get("end") or start)
+        if out and out[-1]["label"] == label and abs(out[-1]["end"] - start) < 0.25:
+            out[-1]["end"] = end
+            out[-1]["duration"] = out[-1]["end"] - out[-1]["start"]
+        else:
+            out.append({"label": label, "start": start, "end": end, "duration": max(0.0, end - start)})
+    return out
+
+
+def _ngram_counts(labels: list[str], n: int) -> list[dict[str, Any]]:
+    if len(labels) < n:
+        return []
+    counts = Counter(tuple(labels[i : i + n]) for i in range(len(labels) - n + 1))
+    return [
+        {"progression": list(items), "count": int(count)}
+        for items, count in counts.most_common(12)
+    ]
+
+
+def _beats_per_chord(chords: list[dict[str, Any]], beat_results: list[BeatResult]) -> float | None:
+    grid = next((x for x in beat_results if x.model == "consensus"), None)
+    if grid is None and beat_results:
+        grid = max(beat_results, key=lambda x: len(x.beats))
+    if not grid or len(grid.beats) < 4 or not chords:
+        return None
+    b = np.asarray(grid.beats, dtype=float)
+    counts = []
+    for chord in chords:
+        if chord["label"] == "N":
+            continue
+        c = int(np.sum((b >= chord["start"]) & (b < chord["end"])))
+        if c > 0:
+            counts.append(c)
+    return float(np.median(counts)) if counts else None
+
+
+def _chroma_matrix(vamp_result: dict[str, Any] | None) -> np.ndarray | None:
+    analysis = _find_analysis(vamp_result, "nnls_chroma")
+    if not analysis:
+        return None
+    rows = []
+    for event in analysis.get("events", []):
+        vals = [float(v) for v in event.get("values", [])]
+        if len(vals) >= 12:
+            rows.append(vals[:12])
+    if not rows:
+        return None
+    matrix_a = np.asarray(rows, dtype=float)
+    # NNLS Chroma's bins are A, Bb, B, C, C#, D, Eb, E, F, F#, G, Ab.
+    # Rotate to C, C#, D, Eb, E, F, F#, G, Ab, A, Bb, B.
+    order = [3, 4, 5, 6, 7, 8, 9, 10, 11, 0, 1, 2]
+    return matrix_a[:, order]
+
+
+def _key_candidates(chroma: np.ndarray | None) -> list[dict[str, Any]]:
+    if chroma is None or chroma.size == 0:
+        return []
+    profile = np.nanmean(chroma, axis=0)
+    if not np.any(np.isfinite(profile)) or np.nansum(profile) <= 0:
+        return []
+    profile = np.nan_to_num(profile, nan=0.0)
+    scores: list[tuple[float, str]] = []
+    for root in range(12):
+        for mode, template in (("major", MAJOR_PROFILE), ("minor", MINOR_PROFILE)):
+            rolled = np.roll(template, root)
+            if np.std(profile) == 0 or np.std(rolled) == 0:
+                corr = 0.0
+            else:
+                corr = float(np.corrcoef(profile, rolled)[0, 1])
+            scores.append((corr, f"{PITCHES_C[root]} {mode}"))
+    scores.sort(reverse=True)
+    return [{"key": label, "correlation": score} for score, label in scores[:6]]
+
+
+def _pitch_class_entropy(chroma: np.ndarray | None) -> float | None:
+    if chroma is None or chroma.size == 0:
+        return None
+    p = np.nansum(np.maximum(chroma, 0.0), axis=0)
+    total = float(np.sum(p))
+    if total <= 0:
+        return None
+    p = p / total
+    p = p[p > 0]
+    return float(-np.sum(p * np.log2(p)) / math.log2(12.0))
+
+
+def analyze_harmony(
+    vamp_result: dict[str, Any] | None,
+    beat_results: list[BeatResult],
+    output_dir: Path,
+) -> dict[str, Any]:
+    """Fuse Chordino/NNLS/QM evidence into a higher-level harmonic summary."""
+    output_dir.mkdir(parents=True, exist_ok=True)
+
+    chord_analysis = _find_analysis(vamp_result, "chords")
+    chord_events = list(chord_analysis.get("events", [])) if chord_analysis else []
+    chords = _collapse_progression(chord_events)
+    labels = [item["label"] for item in chords if item["label"] != "N"]
+
+    by_duration: Counter[str] = Counter()
+    for item in chords:
+        by_duration[item["label"]] += float(item["duration"])
+
+    total_duration = sum(by_duration.values())
+    chord_hist = [
+        {
+            "chord": label,
+            "seconds": float(seconds),
+            "share": float(seconds / total_duration) if total_duration > 0 else 0.0,
+        }
+        for label, seconds in by_duration.most_common()
+    ]
+
+    transitions = Counter(zip(labels, labels[1:]))
+    top_transitions = [
+        {"from": a, "to": b, "count": int(count)}
+        for (a, b), count in transitions.most_common(16)
+    ]
+
+    chroma = _chroma_matrix(vamp_result)
+    key_analysis = _find_analysis(vamp_result, "key")
+    vamp_key = None
+    if key_analysis and key_analysis.get("events"):
+        first = key_analysis["events"][0]
+        vamp_key = first.get("label") or (first.get("values") or [None])[0]
+
+    tuning_analysis = _find_analysis(vamp_result, "tuning")
+    tuning_hz = None
+    if tuning_analysis and tuning_analysis.get("events"):
+        vals = tuning_analysis["events"][0].get("values") or []
+        if vals:
+            tuning_hz = float(vals[0])
+
+    tonal_changes = _find_analysis(vamp_result, "tonal_changes")
+    change_times = [
+        float(event.get("start") or 0.0)
+        for event in (tonal_changes.get("events", []) if tonal_changes else [])
+    ]
+
+    key_candidates = _key_candidates(chroma)
+    key_basis = vamp_key or (key_candidates[0]["key"] if key_candidates else None)
+    functional = _functional_harmony(chords, key_basis)
+
+    result = {
+        "source": "StemLab Vamp evidence fusion",
+        "vamp_key": vamp_key,
+        "independent_key_candidates_from_nnls_chroma": key_candidates,
+        "functional_harmony": functional,
+        "tuning_hz": tuning_hz,
+        "pitch_class_entropy_normalized": _pitch_class_entropy(chroma),
+        "tonal_change_times_seconds": change_times,
+        "chords": {
+            "event_count": len(chords),
+            "unique_count": len(set(labels)),
+            "changes_per_minute": (
+                float(60.0 * max(0, len(chords) - 1) / max(1e-9, chords[-1]["end"] - chords[0]["start"]))
+                if len(chords) >= 2
+                else None
+            ),
+            "median_beats_per_chord": _beats_per_chord(chords, beat_results),
+            "duration_histogram": chord_hist,
+            "top_transitions": top_transitions,
+            "top_bigrams": _ngram_counts(labels, 2),
+            "top_trigrams": _ngram_counts(labels, 3),
+            "collapsed_progression": chords,
+        },
+        "method_notes": {
+            "key_fusion": "Reports the QM Vamp key independently from a Krumhansl-Schmuckler correlation over mean NNLS chroma; disagreement is retained rather than hidden.",
+            "harmonic_rhythm": "Median number of consensus/detected beats falling inside non-N chord segments.",
+            "functional_harmony": "Scale-degree, chromatic-root, root-motion and cadence summaries are deterministic derivations relative to the reported key basis, not separate learned labels.",
+        },
+    }
+    write_json(output_dir / "harmony.json", result)
+    return result

stemlab/analysis/lyrics.py

@@ -0,0 +1,293 @@
+from __future__ import annotations
+import re
+from collections import Counter, defaultdict
+from pathlib import Path
+from typing import Any
+
+import numpy as np
+
+from stemlab.util import write_json
+
+WORD_RE = re.compile(r"[A-Za-zÀ-ÖØ-öø-ÿ0-9]+(?:['’][A-Za-zÀ-ÖØ-öø-ÿ]+)?")
+VOWELS = set("AEIOU")
+STOPWORDS = {
+    "a", "an", "and", "are", "as", "at", "be", "been", "but", "by", "for", "from",
+    "had", "has", "have", "he", "her", "him", "his", "i", "if", "in", "into", "is", "it",
+    "its", "me", "my", "no", "not", "of", "on", "or", "our", "out", "she", "so", "that",
+    "the", "their", "them", "then", "there", "they", "this", "to", "up", "us", "was", "we",
+    "were", "what", "when", "where", "who", "will", "with", "you", "your", "just", "while",
+}
+
+
+def _words(text: str) -> list[str]:
+    return [m.group(0).lower().replace("’", "'") for m in WORD_RE.finditer(text)]
+
+
+def _normalise_line(line: str) -> str:
+    return " ".join(_words(line))
+
+
+def _cmu() -> dict[str, list[list[str]]] | None:
+    try:
+        import cmudict
+
+        raw = cmudict.dict()
+        return {str(k).lower(): list(v) for k, v in raw.items()}
+    except Exception:
+        return None
+
+
+def _phones(word: str, dictionary: dict[str, list[list[str]]] | None) -> list[str] | None:
+    if not dictionary:
+        return None
+    variants = dictionary.get(word.lower())
+    return variants[0] if variants else None
+
+
+def _syllable_count_word(word: str, dictionary: dict[str, list[list[str]]] | None) -> int:
+    phones = _phones(word, dictionary)
+    if phones:
+        return max(1, sum(any(ch.isdigit() for ch in p) for p in phones))
+    cleaned = re.sub(r"[^a-z]", "", word.lower())
+    if not cleaned:
+        return 0
+    groups = re.findall(r"[aeiouy]+", cleaned)
+    count = len(groups)
+    if cleaned.endswith("e") and count > 1 and not cleaned.endswith(("le", "ye")):
+        count -= 1
+    return max(1, count)
+
+
+def _rhyme_key(word: str, dictionary: dict[str, list[list[str]]] | None) -> str:
+    phones = _phones(word, dictionary)
+    if phones:
+        # Keep the final stressed vowel and everything after it. If stress is
+        # absent, fall back to the final vowel nucleus.
+        idx = None
+        for i in range(len(phones) - 1, -1, -1):
+            if "1" in phones[i] or "2" in phones[i]:
+                idx = i
+                break
+        if idx is None:
+            for i in range(len(phones) - 1, -1, -1):
+                if phones[i] and phones[i][0] in VOWELS:
+                    idx = i
+                    break
+        if idx is not None:
+            return " ".join(re.sub(r"\d", "", p) for p in phones[idx:])
+    # Orthographic fallback keeps the analysis useful for names/out-of-vocab words.
+    cleaned = re.sub(r"[^a-z]", "", word.lower())
+    return cleaned[-3:] if len(cleaned) >= 3 else cleaned
+
+
+def _line_records(lyrics: str, timing: list[dict[str, Any]] | None) -> list[dict[str, Any]]:
+    lines = [line.strip() for line in lyrics.splitlines() if line.strip()]
+    timed_by_norm: dict[str, list[dict[str, Any]]] = defaultdict(list)
+    for item in timing or []:
+        timed_by_norm[_normalise_line(str(item.get("text") or ""))].append(item)
+
+    seen: Counter[str] = Counter()
+    records = []
+    for index, line in enumerate(lines):
+        norm = _normalise_line(line)
+        occurrence = seen[norm]
+        seen[norm] += 1
+        candidates = timed_by_norm.get(norm, [])
+        t = candidates[occurrence] if occurrence < len(candidates) else None
+        words = _words(line)
+        records.append(
+            {
+                "index": index,
+                "text": line,
+                "normalised": norm,
+                "words": words,
+                "end_word": words[-1] if words else "",
+                "start": float(t.get("start")) if t and t.get("start") is not None else None,
+                "end": float(t.get("end")) if t and t.get("end") is not None else None,
+            }
+        )
+    return records
+
+
+def _rhyme_analysis(records: list[dict[str, Any]], dictionary) -> dict[str, Any]:
+    key_to_letter: dict[str, str] = {}
+    alphabet = "ABCDEFGHIJKLMNOPQRSTUVWXYZ"
+    classes: dict[str, list[int]] = defaultdict(list)
+    scheme: list[str] = []
+
+    for rec in records:
+        end_word = rec["end_word"]
+        key = _rhyme_key(end_word, dictionary) if end_word else ""
+        rec["rhyme_key"] = key
+        if not key:
+            scheme.append("-")
+            continue
+        if key not in key_to_letter:
+            n = len(key_to_letter)
+            key_to_letter[key] = alphabet[n] if n < len(alphabet) else f"R{n + 1}"
+        letter = key_to_letter[key]
+        scheme.append(letter)
+        classes[key].append(rec["index"])
+
+    repeated_classes = [
+        {
+            "rhyme": key,
+            "scheme": key_to_letter[key],
+            "line_indexes": indexes,
+            "end_words": [records[i]["end_word"] for i in indexes],
+        }
+        for key, indexes in classes.items()
+        if len(indexes) >= 2
+    ]
+    repeated_classes.sort(key=lambda x: (-len(x["line_indexes"]), x["scheme"]))
+
+    # Consecutive-line rhyme density is a useful simple signal for pop/rap writing.
+    adjacent = 0
+    adjacent_matches = 0
+    for a, b in zip(records, records[1:]):
+        if a.get("rhyme_key") and b.get("rhyme_key"):
+            adjacent += 1
+            adjacent_matches += int(a["rhyme_key"] == b["rhyme_key"])
+
+    return {
+        "scheme": " ".join(scheme),
+        "classes": repeated_classes,
+        "unique_rhyme_classes": len(classes),
+        "adjacent_end_rhyme_rate": float(adjacent_matches / adjacent) if adjacent else None,
+    }
+
+
+def _internal_rhyme_density(records: list[dict[str, Any]], dictionary) -> float | None:
+    comparisons = 0
+    matches = 0
+    for rec in records:
+        words = rec["words"]
+        if len(words) < 3:
+            continue
+        keys = [_rhyme_key(word, dictionary) for word in words]
+        end_key = keys[-1]
+        for key in keys[:-1]:
+            if not key or not end_key:
+                continue
+            comparisons += 1
+            matches += int(key == end_key)
+    return float(matches / comparisons) if comparisons else None
+
+
+def _key_terms(words: list[str]) -> list[dict[str, Any]]:
+    terms = [w for w in words if len(w) >= 3 and w not in STOPWORDS and not w.isdigit()]
+    counts = Counter(terms)
+    return [{"term": term, "count": int(count)} for term, count in counts.most_common(24)]
+
+
+def _ngrams(words: list[str], n: int) -> list[dict[str, Any]]:
+    if len(words) < n:
+        return []
+    counts = Counter(tuple(words[i : i + n]) for i in range(len(words) - n + 1))
+    return [
+        {"phrase": " ".join(items), "count": int(count)}
+        for items, count in counts.most_common(20)
+        if count >= 2 and not all(word in STOPWORDS for word in items)
+    ]
+
+
+def _delivery(records: list[dict[str, Any]], dictionary) -> dict[str, Any]:
+    timed = []
+    for rec in records:
+        if rec["start"] is None or rec["end"] is None or rec["end"] <= rec["start"]:
+            continue
+        syllables = sum(_syllable_count_word(w, dictionary) for w in rec["words"])
+        duration = rec["end"] - rec["start"]
+        timed.append(
+            {
+                "line_index": rec["index"],
+                "start": rec["start"],
+                "end": rec["end"],
+                "words": len(rec["words"]),
+                "syllables": syllables,
+                "words_per_second": len(rec["words"]) / duration,
+                "syllables_per_second": syllables / duration,
+            }
+        )
+    if not timed:
+        return {"timed_lines": [], "median_words_per_second": None, "median_syllables_per_second": None}
+    return {
+        "timed_lines": timed,
+        "median_words_per_second": float(np.median([x["words_per_second"] for x in timed])),
+        "median_syllables_per_second": float(np.median([x["syllables_per_second"] for x in timed])),
+        "peak_syllables_per_second": float(max(x["syllables_per_second"] for x in timed)),
+    }
+
+
+def analyze_lyrics(
+    lyrics: str,
+    output_dir: Path,
+    *,
+    timing: list[dict[str, Any]] | None = None,
+    source: str = "canonical",
+) -> dict[str, Any]:
+    """Analyse rhyme, repetition, prosody, lexical variety and timed delivery."""
+    output_dir.mkdir(parents=True, exist_ok=True)
+    dictionary = _cmu()
+    records = _line_records(lyrics, timing)
+    all_words = [word for rec in records for word in rec["words"]]
+    normal_lines = [rec["normalised"] for rec in records if rec["normalised"]]
+    line_counts = Counter(normal_lines)
+
+    syllables_per_line = [
+        sum(_syllable_count_word(word, dictionary) for word in rec["words"])
+        for rec in records
+    ]
+    for rec, syllables in zip(records, syllables_per_line):
+        rec["syllables"] = syllables
+
+    rhyme = _rhyme_analysis(records, dictionary)
+    rhyme["internal_end_rhyme_density"] = _internal_rhyme_density(records, dictionary)
+
+    result = {
+        "source": source,
+        "text": lyrics,
+        "line_count": len(records),
+        "word_count": len(all_words),
+        "unique_word_count": len(set(all_words)),
+        "type_token_ratio": float(len(set(all_words)) / len(all_words)) if all_words else None,
+        "mean_words_per_line": float(np.mean([len(rec["words"]) for rec in records])) if records else None,
+        "median_syllables_per_line": float(np.median(syllables_per_line)) if syllables_per_line else None,
+        "repetition": {
+            "repeated_lines": [
+                {"line": line, "count": int(count)}
+                for line, count in line_counts.most_common()
+                if count >= 2
+            ],
+            "top_bigrams": _ngrams(all_words, 2),
+            "top_trigrams": _ngrams(all_words, 3),
+        },
+        "rhyme": rhyme,
+        "lexical": {
+            "key_terms": _key_terms(all_words),
+        },
+        "delivery": _delivery(records, dictionary),
+        "lines": records,
+        "method_notes": {
+            "phonetics": "CMU Pronouncing Dictionary when available, with an orthographic fallback for names and out-of-vocabulary words.",
+            "rhyme": "End-rhyme class uses the final stressed vowel nucleus and following phonemes; this is a useful signal, not a complete theory of slant rhyme.",
+        },
+    }
+    write_json(output_dir / "lyrics.json", result)
+    return result
+
+
+def transcript_to_lyrics(whisper_result: dict[str, Any] | None) -> tuple[str, list[dict[str, Any]]]:
+    """Produce a line-like text/timing representation when canonical lyrics are absent."""
+    if not whisper_result:
+        return "", []
+    segments = whisper_result.get("segments") or []
+    text_lines = []
+    timing = []
+    for seg in segments:
+        text = str(seg.get("text") or "").strip()
+        if not text:
+            continue
+        text_lines.append(text)
+        timing.append({"start": seg.get("start"), "end": seg.get("end"), "text": text})
+    return "\n".join(text_lines), timing