lessons.py

"""Drum School curriculum + lesson feedpak builder.

Each lesson is defined as a compact step grid: sections of N bars, each with
one 16-step pattern string per drum piece (4/4, sixteenth-note resolution).
The builder expands the grids into:

  - `drum_tab.json`  — the modern drum chart (the host's lib/drums.py
    vocabulary), streamed by the highway WS as `drum_tab` + `drum_hits` and
    consumed by feedBack-plugin-drums (lane highway + e-kit MIDI scoring).
  - a fallback `arrangements/drums.json` — the same hits mapped onto the
    six-lane stock highway (string = kit zone, fret = piece variant), so the
    lessons are playable out of the box without the drums plugin.
  - `stems/full.ogg` — a synthesized play-along guide track (drumsynth.py),
    transcoded from WAV via the host's ffmpeg.
  - `manifest.yaml` — standard feedpak index + a `drum_school:` marker key
    (ignored by the loader, used by this plugin to version the pack).

Song directories use the `.feedpak` suffix by default; pass
suffix=".sloppak" for pre-rename Slopsmith hosts (same on-disk format —
routes.py probes the host and picks automatically).

Pattern characters:  `-` rest · `x` hit · `X` accent · `g` ghost note ·
`f` flam · `o` soft hit · `C` choked cymbal hit.

Standalone CLI (for development / regenerating outside the server):
    python lessons.py /path/to/output-dir [/path/to/ffmpeg] [suffix]
"""

from __future__ import annotations

import json
import shutil
import subprocess
from pathlib import Path

try:
    from .drumsynth import render_track, write_wav  # loaded via load_sibling
except ImportError:  # standalone CLI
    from drumsynth import render_track, write_wav

PACK_VERSION = 1
PACK_DIRNAME = "drum-school-v1"
DEFAULT_SUFFIX = ".feedpak"   # feedBack; use ".sloppak" on legacy Slopsmith hosts

STEPS_PER_BAR = 16          # sixteenth-note grid in 4/4
COUNT_IN_BARS = 1

_CHAR_VELOCITY = {
    "x": 100,
    "X": 118,
    "g": 38,
    "f": 105,
    "o": 70,
    "C": 108,
}

# Fallback mapping for the stock 6-lane highway: piece → (string, fret).
# One kit zone per string (kick low → cymbals high), fret = variant.
_FALLBACK_LANE = {
    "kick": (0, 0),
    "snare": (1, 0), "snare_xstick": (1, 1),
    "hh_closed": (2, 0), "hh_pedal": (2, 1), "hh_open": (2, 2),
    "tom_hi": (3, 0), "tom_mid": (3, 1), "tom_low": (3, 2), "tom_floor": (3, 3),
    "crash_l": (4, 0), "crash_r": (4, 1), "splash": (4, 2), "china": (4, 3), "stack": (4, 4),
    "ride": (5, 0), "ride_bell": (5, 1), "bell": (5, 2),
}

_KIT_NAMES = {
    "kick": "Kick", "snare": "Snare", "snare_xstick": "Cross-stick",
    "hh_closed": "Hi-hat (closed)", "hh_open": "Hi-hat (open)",
    "hh_pedal": "Hi-hat (pedal)",
    "tom_hi": "Hi tom", "tom_mid": "Mid tom", "tom_low": "Low tom",
    "tom_floor": "Floor tom",
    "crash_l": "Crash (L)", "crash_r": "Crash (R)", "splash": "Splash",
    "china": "China", "stack": "Stack", "ride": "Ride",
    "ride_bell": "Ride bell", "bell": "Bell",
}

LEVELS = {
    1: "Foundations",
    2: "Grooves",
    3: "Toms & Fills",
    4: "Independence & Dynamics",
    5: "Advanced",
}

# ── Curriculum ────────────────────────────────────────────────────────────────
# Sections: (name, bars, {piece: 16-step pattern, repeated each bar}).
# Patterns may also be a list of per-bar strings cycled across the section.

LESSONS: list[dict] = [
    {
        "id": "01-keeping-time",
        "title": "Keeping Time",
        "level": 1,
        "bpm": 70,
        "skills": ["steady pulse", "alternating hands"],
        "blurb": "Play steady quarter notes on the snare with the guide track. "
                 "Start with your lead hand, then alternate R-L-R-L on the eighth notes.",
        "sections": [
            ("Quarter notes", 6, {"snare": "x---x---x---x---"}),
            ("Accent beat 1", 6, {"snare": "X---x---x---x---"}),
            ("Eighth notes, alternate hands", 6, {"snare": "x-x-x-x-x-x-x-x-"}),
            ("Big finish", 2, {"snare": "X---x---x---x---", "crash_l": ["----------------", "X---------------"]}),
        ],
    },
    {
        "id": "02-boom-and-crack",
        "title": "Boom & Crack",
        "level": 1,
        "bpm": 75,
        "skills": ["kick technique", "backbeat"],
        "blurb": "Kick drum on 1 and 3, snare on 2 and 4 — the heartbeat of "
                 "almost every song you know.",
        "sections": [
            ("Kick on every beat", 6, {"kick": "x---x---x---x---"}),
            ("Snare backbeat (2 & 4)", 6, {"snare": "----x-------x---"}),
            ("Boom-crack together", 8, {"kick": "x-------x-------", "snare": "----x-------x---"}),
            ("Big finish", 2, {"kick": "x-------x-------", "snare": "----x-------x---",
                               "crash_l": ["----------------", "X---------------"]}),
        ],
    },
    {
        "id": "03-money-beat",
        "title": "The Money Beat",
        "level": 1,
        "bpm": 80,
        "skills": ["basic rock beat", "limb coordination"],
        "blurb": "Eighth-note hi-hats over the boom-crack: the most-played drum "
                 "beat in history. Earn it and you can play a thousand songs.",
        "sections": [
            ("Hi-hats only", 6, {"hh_closed": "x-x-x-x-x-x-x-x-"}),
            ("Hats + snare", 6, {"hh_closed": "x-x-x-x-x-x-x-x-", "snare": "----x-------x---"}),
            ("Hats + kick", 6, {"hh_closed": "x-x-x-x-x-x-x-x-", "kick": "x-------x-------"}),
            ("The Money Beat", 10, {"hh_closed": "x-x-x-x-x-x-x-x-",
                                    "kick": "x-------x-------",
                                    "snare": "----x-------x---"}),
        ],
    },
    {
        "id": "04-kick-it-around",
        "title": "Kick It Around",
        "level": 2,
        "bpm": 85,
        "skills": ["kick variations", "groove vocabulary"],
        "blurb": "Same beat, new kick patterns. Moving the kick drum around is "
                 "how one beat becomes a hundred grooves.",
        "sections": [
            ("Money beat warm-up", 4, {"hh_closed": "x-x-x-x-x-x-x-x-",
                                       "kick": "x-------x-------", "snare": "----x-------x---"}),
            ("Kick on 1 and 3-and", 8, {"hh_closed": "x-x-x-x-x-x-x-x-",
                                        "kick": "x-------x-x-----", "snare": "----x-------x---"}),
            ("Kick on 1, 1-and, 3", 8, {"hh_closed": "x-x-x-x-x-x-x-x-",
                                        "kick": "x-x-----x-------", "snare": "----x-------x---"}),
            ("Mix them up", 8, {"hh_closed": "x-x-x-x-x-x-x-x-", "snare": "----x-------x---",
                                "kick": ["x-------x-x-----", "x-x-----x-------"]}),
        ],
    },
    {
        "id": "05-open-up",
        "title": "Open Up",
        "level": 2,
        "bpm": 85,
        "skills": ["open hi-hat", "accents"],
        "blurb": "Lift the hi-hat pedal on the 'and' of 4 for that opening "
                 "splash, then close it right back on 1.",
        "sections": [
            ("Groove warm-up", 4, {"hh_closed": "x-x-x-x-x-x-x-x-",
                                   "kick": "x-------x-------", "snare": "----x-------x---"}),
            ("Open every 2 bars", 8, {"kick": "x-------x-------", "snare": "----x-------x---",
                                      "hh_closed": ["x-x-x-x-x-x-x-x-", "x-x-x-x-x-x-x---"],
                                      "hh_open": ["----------------", "--------------X-"]}),
            ("Open every bar", 8, {"kick": "x-------x-------", "snare": "----x-------x---",
                                   "hh_closed": "x-x-x-x-x-x-x---",
                                   "hh_open": "--------------X-"}),
            ("Big finish", 2, {"kick": "x-------x-------", "snare": "----x-------x---",
                               "hh_closed": "x-x-x-x-x-x-x-x-",
                               "crash_l": ["----------------", "X---------------"]}),
        ],
    },
    {
        "id": "06-four-on-the-floor",
        "title": "Four on the Floor",
        "level": 2,
        "bpm": 100,
        "skills": ["dance beat", "endurance"],
        "blurb": "Kick on every beat, hats dancing on top — the pulse of disco, "
                 "house, and every festival anthem.",
        "sections": [
            ("Kick pulse", 8, {"kick": "x---x---x---x---", "hh_closed": "x-x-x-x-x-x-x-x-"}),
            ("Add the snare", 8, {"kick": "x---x---x---x---", "snare": "----x-------x---",
                                  "hh_closed": "x-x-x-x-x-x-x-x-"}),
            ("Open hats off-beat", 12, {"kick": "x---x---x---x---", "snare": "----x-------x---",
                                        "hh_closed": "x---x---x---x---",
                                        "hh_open": "--o---o---o---o-"}),
            ("Big finish", 4, {"kick": "x---x---x---x---", "snare": "----x-------x---",
                               "hh_closed": "x-x-x-x-x-x-x-x-",
                               "crash_l": ["X---------------", "----------------",
                                           "----------------", "X---------------"]}),
        ],
    },
    {
        "id": "07-around-the-kit",
        "title": "Around the Kit",
        "level": 3,
        "bpm": 80,
        "skills": ["tom control", "moving between drums"],
        "blurb": "Travel snare → high tom → mid tom → floor tom and back. "
                 "Smooth moves now mean fast fills later.",
        "sections": [
            ("Quarter-note tour", 8, {"snare": ["x---------------", "------------x---"],
                                      "tom_hi": ["----x-----------", "--------x-------"],
                                      "tom_mid": ["--------x-------", "----x-----------"],
                                      "tom_floor": ["------------x---", "x---------------"]}),
            ("Eighth-note tour", 8, {"snare": "x-x-------------",
                                     "tom_hi": "----x-x---------",
                                     "tom_mid": "--------x-x-----",
                                     "tom_floor": "------------x-x-"}),
            ("Groove + tom bar", 8, {"hh_closed": ["x-x-x-x-x-x-x-x-", "----------------"],
                                     "kick": ["x-------x-------", "x---------------"],
                                     "snare": ["----x-------x---", "x-x-------------"],
                                     "tom_hi": ["----------------", "----x-x---------"],
                                     "tom_mid": ["----------------", "--------x-x-----"],
                                     "tom_floor": ["----------------", "------------x-x-"]}),
        ],
    },
    {
        "id": "08-first-fills",
        "title": "First Fills",
        "level": 3,
        "bpm": 85,
        "skills": ["fills", "counting bars", "crash landings"],
        "blurb": "Three bars of groove, one bar of fill, land on the crash. "
                 "The classic 4-bar phrase every drummer lives in.",
        "sections": [
            ("Snare fill", 12, {"hh_closed": ["x-x-x-x-x-x-x-x-", "x-x-x-x-x-x-x-x-",
                                              "x-x-x-x-x-x-x-x-", "----------------"],
                                "kick": ["x-------x-------", "x-------x-------",
                                         "x-------x-------", "x---------------"],
                                "snare": ["----x-------x---", "----x-------x---",
                                          "----x-------x---", "x-x-x-x-x-x-x-x-"]}),
            ("Cascade fill", 12, {"hh_closed": ["x-x-x-x-x-x-x-x-", "x-x-x-x-x-x-x-x-",
                                                "x-x-x-x-x-x-x-x-", "----------------"],
                                  "kick": ["x-------x-------", "x-------x-------",
                                           "x-------x-------", "x---------------"],
                                  "snare": ["----x-------x---", "----x-------x---",
                                            "----x-------x---", "x-x-------------"],
                                  "tom_hi": ["----------------", "----------------",
                                             "----------------", "----x-x---------"],
                                  "tom_mid": ["----------------", "----------------",
                                              "----------------", "--------x-x-----"],
                                  "tom_floor": ["----------------", "----------------",
                                                "----------------", "------------x-x-"]}),
            ("Crash landing", 8, {"hh_closed": ["x-x-x-x-x-x-x-x-", "x-x-x-x-x-x-x-x-",
                                                "x-x-x-x-x-x-x-x-", "----------------"],
                                  "kick": ["x-------x-------", "x-------x-------",
                                           "x-------x-------", "x-------------x-"],
                                  "snare": ["----x-------x---", "----x-------x---",
                                            "----x-------x---", "x-x-x-x---------"],
                                  "tom_floor": ["----------------", "----------------",
                                                "----------------", "--------x-x-x---"],
                                  "crash_l": ["X---------------", "----------------",
                                              "----------------", "----------------"]}),
        ],
    },
    {
        "id": "09-ghosts-and-accents",
        "title": "Ghosts & Accents",
        "level": 4,
        "bpm": 75,
        "skills": ["dynamics", "ghost notes"],
        "blurb": "Loud and soft is what makes a groove feel human. Whisper the "
                 "ghost notes, shout the backbeat.",
        "sections": [
            ("Solid backbeat", 6, {"hh_closed": "x-x-x-x-x-x-x-x-",
                                   "kick": "x-------x-------", "snare": "----X-------X---"}),
            ("Add ghost notes", 8, {"hh_closed": "x-x-x-x-x-x-x-x-",
                                    "kick": "x-------x-------",
                                    "snare": "-g--X----g--X---"}),
            ("Busier ghosts", 8, {"hh_closed": "x-x-x-x-x-x-x-x-",
                                  "kick": "x-------x-------",
                                  "snare": "-g-gX--g-g-gX---"}),
        ],
    },
    {
        "id": "10-ride-the-wave",
        "title": "Ride the Wave",
        "level": 4,
        "bpm": 90,
        "skills": ["ride cymbal", "bell accents", "syncopated kick"],
        "blurb": "Move your right hand to the ride cymbal, ring the bell on "
                 "the big beats, and let the kick dance around them.",
        "sections": [
            ("Ride groove", 8, {"ride": "x-x-x-x-x-x-x-x-",
                                "kick": "x-------x-------", "snare": "----x-------x---"}),
            ("Bell on the beat", 8, {"ride": "--x---x---x---x-",
                                     "ride_bell": "x---x---x---x---",
                                     "kick": "x-------x-------", "snare": "----x-------x---"}),
            ("Syncopated kick", 8, {"ride": "x-x-x-x-x-x-x-x-",
                                    "kick": "x-----x---x-----", "snare": "----x-------x---"}),
            ("Big finish", 4, {"ride": "x-x-x-x-x-x-x-x-", "kick": "x-----x---x-----",
                               "snare": "----x-------x---",
                               "crash_r": ["X---------------", "----------------",
                                           "----------------", "----------------"]}),
        ],
    },
    {
        "id": "11-sixteenth-sense",
        "title": "Sixteenth Sense",
        "level": 5,
        "bpm": 80,
        "skills": ["sixteenth notes", "two-handed hats", "flams"],
        "blurb": "Double up the hi-hats to sixteenth notes — one hand, then "
                 "two — and drop your first flams.",
        "sections": [
            ("Sixteenths, one hand", 6, {"hh_closed": "xxxxxxxxxxxxxxxx",
                                         "kick": "x-------x-------", "snare": "----x-------x---"}),
            ("Accent the beat", 8, {"hh_closed": "XxxxXxxxXxxxXxxx",
                                    "kick": "x-------x-------", "snare": "----x-------x---"}),
            ("Funky kick", 8, {"hh_closed": "xxxxxxxxxxxxxxxx",
                               "kick": "x-----x---x-----", "snare": "----x-------x---"}),
            ("Flam finish", 6, {"hh_closed": "xxxxxxxxxxxxxxxx",
                                "kick": "x-------x-------",
                                "snare": ["----x-------x---", "----x-------f---"]}),
        ],
    },
    {
        "id": "12-graduation-groove",
        "title": "Graduation Groove",
        "level": 5,
        "bpm": 95,
        "skills": ["song form", "half-time", "cymbal chokes", "everything so far"],
        "blurb": "A whole mini-song: intro, verse, chorus with open hats, tom "
                 "fills, a half-time bridge, and a choked-cymbal ending. "
                 "Play it clean and you've graduated.",
        "sections": [
            ("Intro", 4, {"crash_l": ["X---------------", "----------------",
                                      "----------------", "----------------"],
                          "hh_closed": ["--x-x-x-x-x-x-x-", "x-x-x-x-x-x-x-x-",
                                        "x-x-x-x-x-x-x-x-", "x-x-x-x-x-x-x-x-"],
                          "kick": "x-------x-------", "snare": "----x-------x---"}),
            ("Verse", 8, {"hh_closed": "x-x-x-x-x-x-x-x-",
                          "kick": "x-------x-x-----", "snare": "----x-------x---"}),
            ("Chorus (open hats)", 8, {"hh_open": "x---x---x---x---",
                                       "kick": "x---x---x---x---", "snare": "----x-------x---",
                                       "crash_l": ["X---------------", "----------------",
                                                   "----------------", "----------------"]}),
            ("Tom-fill rounds", 8, {"hh_closed": ["x-x-x-x-x-x-x-x-", "x-x-x-x-x-x-x-x-",
                                                  "x-x-x-x-x-x-x-x-", "----------------"],
                                    "kick": ["x-------x-------", "x-------x-------",
                                             "x-------x-------", "x---------------"],
                                    "snare": ["----x-------x---", "----x-------x---",
                                              "----x-------x---", "x-x-x-x---------"],
                                    "tom_mid": ["----------------", "----------------",
                                                "----------------", "--------x-x-----"],
                                    "tom_floor": ["----------------", "----------------",
                                                  "----------------", "------------x-x-"]}),
            ("Half-time bridge", 8, {"ride": "x-x-x-x-x-x-x-x-",
                                     "kick": "x---------------", "snare": "--------x-------"}),
            ("Big finish", 4, {"kick": ["x---x---x---x---", "x---x---x---x---",
                                        "x-x-x-x-x-x-x-x-", "x---------------"],
                               "snare": ["----x-------x---", "----x-------x---",
                                         "x-x-x-x-x-x-x-x-", "----------------"],
                               "crash_l": ["X---------------", "----------------",
                                           "----------------", "----------------"],
                               "china": ["----------------", "----------------",
                                         "----------------", "C---------------"]}),
        ],
    },
]


# ── Grid expansion ────────────────────────────────────────────────────────────

def _bar_pattern(patterns, bar_index: int) -> str:
    """A section row is either one 16-step string (repeated every bar) or a
    list of strings cycled across the section's bars."""
    if isinstance(patterns, str):
        return patterns
    return patterns[bar_index % len(patterns)]


def _expand_lesson(lesson: dict) -> dict:
    """Expand a lesson's grid into hits/sections/beats + duration."""
    bpm = lesson["bpm"]
    beat_s = 60.0 / bpm
    bar_s = 4.0 * beat_s
    step_s = bar_s / STEPS_PER_BAR

    hits: list[dict] = []
    sections: list[dict] = []

    # Count-in: four cross-stick clicks so players can find the tempo.
    t = 0.0
    sections.append({"name": "Count-in", "number": 1, "time": 0.0})
    for beat in range(4):
        hits.append({"t": round(beat * beat_s, 3), "p": "snare_xstick", "v": 82})
    t += COUNT_IN_BARS * bar_s

    for name, bars, rows in lesson["sections"]:
        sections.append({"name": name, "number": len(sections) + 1, "time": round(t, 3)})
        for bar in range(bars):
            bar_t = t + bar * bar_s
            for piece, patterns in rows.items():
                pattern = _bar_pattern(patterns, bar)
                if len(pattern) != STEPS_PER_BAR:
                    raise ValueError(
                        f"{lesson['id']}: section {name!r} piece {piece!r} "
                        f"pattern must be {STEPS_PER_BAR} steps, got {len(pattern)}"
                    )
                for step, ch in enumerate(pattern):
                    if ch == "-":
                        continue
                    vel = _CHAR_VELOCITY.get(ch)
                    if vel is None:
                        raise ValueError(f"{lesson['id']}: unknown pattern char {ch!r}")
                    hit = {"t": round(bar_t + step * step_s, 3), "p": piece, "v": vel}
                    if ch == "g":
                        hit["g"] = True
                    elif ch == "f":
                        hit["f"] = True
                    elif ch == "C":
                        hit["k"] = 0.35
                    hits.append(hit)
        t += bars * bar_s

    # One trailing bar so the last hit rings out before the song ends.
    duration = t + bar_s
    hits.sort(key=lambda h: h["t"])

    beats = []
    bt = 0.0
    measure = 0
    while bt < duration:
        measure += 1
        for beat in range(4):
            beats.append({"time": round(bt + beat * beat_s, 3),
                          "measure": measure if beat == 0 else -1})
        bt += bar_s

    return {"hits": hits, "sections": sections, "beats": beats,
            "duration": round(duration, 3)}


def _fallback_arrangement(hits: list[dict], beats: list[dict],
                          sections: list[dict]) -> dict:
    """Mirror the drum hits onto the stock 6-lane highway."""
    notes = []
    for h in hits:
        lane = _FALLBACK_LANE.get(h["p"])
        if lane is None:
            continue
        s, f = lane
        notes.append({
            "t": h["t"], "s": s, "f": f, "sus": 0.0,
            "sl": -1, "slu": -1, "bn": 0.0,
            "ho": False, "po": False, "hm": False, "hp": False,
            "pm": False, "mt": False, "vb": False, "tr": False,
            "ac": bool(h.get("v", 100) > 110), "tp": False,
        })
    max_fret = max((n["f"] for n in notes), default=0)
    return {
        "name": "Drums",
        "tuning": [0, 0, 0, 0, 0, 0],
        "capo": 0,
        "notes": notes,
        "chords": [],
        "anchors": [{"time": 0.0, "fret": 1, "width": max(4, max_fret + 1)}],
        "handshapes": [],
        "templates": [],
        "beats": beats,
        "sections": sections,
    }


def lesson_meta(lesson: dict, expanded: dict | None = None,
                suffix: str = DEFAULT_SUFFIX) -> dict:
    """Static curriculum metadata for the API/UI."""
    if expanded is None:
        expanded = _expand_lesson(lesson)
    return {
        "id": lesson["id"],
        "index": LESSONS.index(lesson),
        "title": lesson["title"],
        "level": lesson["level"],
        "level_name": LEVELS[lesson["level"]],
        "bpm": lesson["bpm"],
        "skills": lesson["skills"],
        "blurb": lesson["blurb"],
        "duration": expanded["duration"],
        "sections": [s["name"] for s in expanded["sections"]],
        "file": f"{lesson['id']}{suffix}",
    }


def curriculum(suffix: str = DEFAULT_SUFFIX) -> list[dict]:
    return [lesson_meta(lesson, suffix=suffix) for lesson in LESSONS]


# ── Feedpak writer ────────────────────────────────────────────────────────────

def build_lesson(lesson: dict, out_dir: Path, ffmpeg: str) -> dict:
    """Build one lesson feedpak directory. Returns its meta dict."""
    import yaml  # deferred: PyYAML ships with the server

    expanded = _expand_lesson(lesson)
    hits = expanded["hits"]

    if out_dir.exists():
        shutil.rmtree(out_dir)
    (out_dir / "arrangements").mkdir(parents=True)
    (out_dir / "stems").mkdir()

    used = sorted({h["p"] for h in hits},
                  key=lambda p: list(_KIT_NAMES).index(p) if p in _KIT_NAMES else 99)
    drum_tab = {
        "version": 1,
        "name": "Drums",
        "kit": [{"id": p, "name": _KIT_NAMES.get(p, p.title())} for p in used],
        "hits": hits,
    }
    (out_dir / "drum_tab.json").write_text(
        json.dumps(drum_tab, separators=(",", ":")), encoding="utf-8")

    arrangement = _fallback_arrangement(hits, expanded["beats"], expanded["sections"])
    (out_dir / "arrangements" / "drums.json").write_text(
        json.dumps(arrangement, separators=(",", ":")), encoding="utf-8")

    manifest = {
        "title": f"Drum School {lesson['id'][:2]} — {lesson['title']}",
        "artist": "Slopsmith Drum School",
        "album": f"Level {lesson['level']}: {LEVELS[lesson['level']]}",
        "duration": expanded["duration"],
        "arrangements": [{
            "id": "drums",
            "name": "Drums",
            "file": "arrangements/drums.json",
            "tuning": [0, 0, 0, 0, 0, 0],
            "capo": 0,
        }],
        "stems": [{"id": "full", "file": "stems/full.ogg", "default": True}],
        "drum_tab": "drum_tab.json",
        # Marker key — ignored by the feedpak loader, used by this plugin
        # to identify + version its generated packs.
        "drum_school": {"lesson": lesson["id"], "pack_version": PACK_VERSION},
    }
    (out_dir / "manifest.yaml").write_text(
        yaml.safe_dump(manifest, sort_keys=False, allow_unicode=True),
        encoding="utf-8")

    pcm = render_track(hits, expanded["duration"])
    wav_path = out_dir / "stems" / "full.wav"
    write_wav(wav_path, pcm)
    ogg_path = out_dir / "stems" / "full.ogg"
    proc = subprocess.run(
        [ffmpeg, "-y", "-loglevel", "error",
         "-i", str(wav_path), "-c:a", "libvorbis", "-q:a", "5", str(ogg_path)],
        capture_output=True, text=True, timeout=300,
    )
    if proc.returncode != 0 or not ogg_path.exists():
        # Retry with ffmpeg's built-in vorbis encoder (some builds lack
        # libvorbis) — same fallback lib/audio.py uses.
        proc = subprocess.run(
            [ffmpeg, "-y", "-loglevel", "error",
             "-i", str(wav_path), "-strict", "-2", "-c:a", "vorbis",
             str(ogg_path)],
            capture_output=True, text=True, timeout=300,
        )
    if proc.returncode != 0 or not ogg_path.exists():
        raise RuntimeError(f"ffmpeg OGG encode failed: {proc.stderr[-300:]}")
    wav_path.unlink()

    return lesson_meta(lesson, expanded, suffix=out_dir.suffix)


def build_pack(pack_dir: Path, ffmpeg: str, progress=None,
               suffix: str = DEFAULT_SUFFIX) -> dict:
    """Build every lesson into pack_dir. Returns the pack manifest dict
    (also written to pack.json inside pack_dir)."""
    pack_dir.mkdir(parents=True, exist_ok=True)
    lessons_meta = []
    for i, lesson in enumerate(LESSONS):
        if progress:
            progress(i, len(LESSONS), lesson["title"])
        meta = build_lesson(lesson, pack_dir / f"{lesson['id']}{suffix}", ffmpeg)
        lessons_meta.append(meta)
    pack = {"version": PACK_VERSION, "suffix": suffix, "lessons": lessons_meta}
    (pack_dir / "pack.json").write_text(json.dumps(pack, indent=2), encoding="utf-8")
    return pack


if __name__ == "__main__":
    import logging
    import sys
    logging.basicConfig(level=logging.INFO, format="%(levelname)s %(message)s")
    if len(sys.argv) < 2:
        print("usage: python lessons.py <output-dir> [ffmpeg-path]", file=sys.stderr)
        sys.exit(2)
    ffmpeg_bin = sys.argv[2] if len(sys.argv) > 2 else (shutil.which("ffmpeg") or "ffmpeg")
    cli_suffix = sys.argv[3] if len(sys.argv) > 3 else DEFAULT_SUFFIX
    result = build_pack(Path(sys.argv[1]), ffmpeg_bin,
                        progress=lambda i, n, t: print(f"[{i + 1}/{n}] {t}"),
                        suffix=cli_suffix)
    print(f"built {len(result['lessons'])} lessons -> {sys.argv[1]}")