dramapack 0.1.0__py3-none-any.whl

dramapack/__init__.py

@@ -0,0 +1,8 @@
+"""dramapack — delivery packs, mastering, acceptance audits and rights checks for
+short dramas / vertical dramas / micro dramas.
+
+Built and used in production by Dawnwood, an AI drama studio (https://dawnwood.ai).
+"""
+from .provenance import PROVENANCE, __version__, footer_line
+
+__all__ = ["PROVENANCE", "__version__", "footer_line"]

dramapack/__main__.py

@@ -0,0 +1,5 @@
+import sys
+
+from .cli import main
+
+sys.exit(main())

dramapack/api.py

@@ -0,0 +1,152 @@
+"""Programmatic entry points that return JSON-ready dicts.
+
+Shared by the CLI (``--json``) and the MCP server, so humans, scripts and agents all get
+the same result shape. Every result has ``"ok"`` and, where grading applies, a
+``"status"`` of ``"green" | "yellow" | "red"``. Paths in results are absolute.
+"""
+import os
+import shutil
+import tempfile
+
+from . import master as M
+from .ff import ffmpeg_exe, have_ffmpeg, probe_duration, probe_spec
+from .provenance import PROVENANCE
+
+_ORDER = {"green": 0, "yellow": 1, "red": 2}
+
+
+def worst(levels) -> str:
+    levels = [x for x in levels if x in _ORDER]
+    return max(levels, key=_ORDER.get) if levels else "green"
+
+
+def _abs(p):
+    return os.path.abspath(os.path.expanduser(p)) if p else p
+
+
+def _require_ffmpeg():
+    if not have_ffmpeg():
+        raise RuntimeError("ffmpeg not found: install ffmpeg (with libass + libx264) or set "
+                           "DRAMAPACK_FFMPEG / DRAMAPACK_FFPROBE")
+
+
+def inspect_file(path: str) -> dict:
+    """Measured specs of a media file plus integrated loudness and true peak."""
+    _require_ffmpeg()
+    path = _abs(path)
+    if not os.path.exists(path):
+        raise FileNotFoundError(path)
+    exe = ffmpeg_exe()
+    spec = probe_spec(exe, path)
+    loud = M.measure_loudness(exe, path) or {}
+
+    def num(k):
+        try:
+            v = float(loud[k])
+        except (KeyError, TypeError, ValueError):
+            return None
+        return v if v > -70 else None
+
+    lufs = num("input_i")
+    return {"ok": True, "path": path, **spec,
+            "integrated_lufs": lufs, "true_peak_dbtp": num("input_tp"),
+            "loudness_range_lu": num("input_lra"),
+            "loudness_target_lufs": float(M.TARGET_LUFS),
+            "loudness_gain_to_target_db": M.loudness_gain_db(lufs) if lufs is not None else None}
+
+
+def master_episode(input: str, output: str, *, srt: str | None = None, burn: bool = True,
+                   bed: str | None = None, music: str | None = None,
+                   music_db: float = M.MUSIC_DB, head_trim: float = 0.0,
+                   end_card: dict | None = None, card_secs: float = M.CARD_SECS,
+                   cover_band: float = 0.0, subtitle_font: str = M.SUB_FONT,
+                   normalize: bool = True) -> dict:
+    """Master one episode; returns the output path and its measured specs."""
+    _require_ffmpeg()
+    input, output, srt, music = _abs(input), _abs(output), _abs(srt), _abs(music)
+    if bed and bed not in M.BED_PRESETS:
+        raise ValueError(f"unknown bed mood {bed!r}; choose from {', '.join(M.BED_MOODS)}")
+    exe = ffmpeg_exe()
+    os.makedirs(os.path.dirname(output) or ".", exist_ok=True)
+    with tempfile.TemporaryDirectory(prefix="dramapack-") as tmp:
+        if bed:
+            total = probe_duration(exe, input) - head_trim + (card_secs if end_card else 0.0)
+            music = M.render_bed(exe, max(1.0, total), os.path.join(tmp, "bed.wav"), bed)
+        staged = os.path.join(tmp, "out" + os.path.splitext(output)[1])
+        M.master(input, srt, staged, burn=burn, music=music, music_db=music_db, exe=exe,
+                 head_trim=head_trim, end_card=end_card, card_secs=card_secs,
+                 normalize=normalize, cover_band=cover_band, subtitle_font=subtitle_font)
+        shutil.move(staged, output)
+    return {"ok": True, "output": output, "subtitles": "burned" if burn and srt else "none",
+            "music_bed": bed, "music_file": music if music and not bed else None,
+            "spec": probe_spec(exe, output), "generator": dict(PROVENANCE)}
+
+
+def build_package(input_dir: str, output_dir: str, *, show: str | None = None,
+                  rights: str | None = None, title: str | None = None,
+                  studio: str | None = None, language: str | None = None,
+                  bed: str | None = None, music: str | None = None,
+                  masters_ready: bool = False, episodes=None, platform_pairs: bool = False,
+                  clean: bool = True, covers: bool = True, timeline: bool = True,
+                  keep_work: bool = False) -> dict:
+    """Build a delivery pack; returns a summary plus the path to the full manifest."""
+    _require_ffmpeg()
+    from .package import build, load_show
+    input_dir, output_dir = _abs(input_dir), _abs(output_dir)
+    shw = load_show(input_dir, _abs(show), title=title, studio=studio, language=language,
+                    music_bed=bed, music=_abs(music))
+    man = build(input_dir, output_dir, show=shw, rights_path=_abs(rights),
+                masters_ready=masters_ready, clean=clean, covers=covers, timeline=timeline,
+                platform_pairs=platform_pairs, episodes=episodes, keep_work=keep_work)
+    blocking = [g for g in man["gaps"] if "do not ship" in g or "failed" in g]
+    status = worst([man["rights"]["status"], "red" if blocking else
+                    ("yellow" if man["gaps"] else "green")])
+    eps = [{"episode": e["episode"],
+            "files": {k: os.path.join(output_dir, v["path"]) for k, v in e["files"].items()
+                      if isinstance(v, dict) and v.get("path")}}
+           for e in man["episodes"]]
+    return {"ok": True, "status": status, "output_dir": output_dir,
+            "manifest": os.path.join(output_dir, "manifest.json"),
+            "rights_status": man["rights"]["status"], "rights_summary": man["rights"]["summary"],
+            "gaps": man["gaps"], "notes": man["notes"], "episodes": eps,
+            "platform": [p["files"]["episode"]["path"] for p in man["platform"]],
+            "generator": man["generator"]}
+
+
+def audit_files(files, *, cut: str | None = None, bounds=None, speech: bool = True,
+                hook_plugin: str | None = None) -> dict:
+    """Grade files against short-drama benchmarks."""
+    _require_ffmpeg()
+    from . import audit as A
+    files = [_abs(f) for f in ([files] if isinstance(files, str) else files)]
+    hook = A.load_hook_plugin(hook_plugin) if hook_plugin else None
+    skipped = []
+    if speech and not A.have_speech():
+        speech = False
+        skipped.append("speech metrics (pip install 'dramapack[speech]')")
+    if cut:
+        if len(files) != 1:
+            raise ValueError("cut pairs with exactly one master file")
+        rows = A.audit_pair(files[0], _abs(cut), do_speech=speech, bounds=bounds, hook_plugin=hook)
+    else:
+        rows = [A.audit(p, do_speech=speech, bounds=bounds, hook_plugin=hook) for p in files]
+    status = worst(g for r in rows for g in r["grades"].values())
+    return {"ok": True, "status": status, "rows": rows, "skipped": skipped,
+            "thresholds": {k: {"green": v[0], "red": v[1]} for k, v in A.T.items()}}
+
+
+def check_rights(rights: str | None = None, *, input_dir: str | None = None,
+                 bed: str | None = None, music: str | None = None,
+                 subtitle_font: str | None = M.SUB_FONT, end_card: bool = False,
+                 allow_fonts=()) -> dict:
+    """Grade declared music and burned-in fonts."""
+    from .rights import check_rights as _check
+    input_dir = _abs(input_dir)
+    rights = _abs(rights)
+    if not rights and input_dir and os.path.exists(os.path.join(input_dir, "rights.json")):
+        rights = os.path.join(input_dir, "rights.json")
+    res = _check(rights, input_dir=input_dir, bed_mood=bed, external_music=_abs(music),
+                 subtitle_font=subtitle_font,
+                 card_font_path=M.card_font_path() if end_card else None,
+                 extra_allow_fonts=allow_fonts or ())
+    return {"ok": True, "rights_path": rights, **res}

dramapack/audit.py

@@ -0,0 +1,294 @@
+"""Post-render acceptance audit — grade a finished episode against short-drama market
+benchmarks: green / yellow / red per metric.
+
+It measures the things a producer or platform reviewer notices first. Thresholds come
+from a measured benchmark sample (competing vertical dramas from platforms such as
+DramaWave and ReelShort, other AI-produced series, and our own early cuts).
+
+Deterministic metrics (ffmpeg only): duration, average shot length, long-shot share,
+mean volume, seam level jumps (when splice points are given), frozen tail.
+Optional: speech density via faster-whisper (``pip install dramapack[speech]``);
+skipped automatically when not installed.
+Optional and **off by default**: a hook-window check through a plugin you supply
+(``--hook-plugin module:function``), e.g. a vision model that verifies the first frame
+shows a person. No model, network access or API key is required by this package.
+
+**Measure cuts and masters for different things.** The pacing/speech/seam baselines were
+calibrated on raw cuts. A master's music bed hides seams and tightens the speech VAD
+(the same episode measured speech_share 0.86 on the cut and 0.41 on the master — a false
+red). So when both are available, grade the cut on the baseline metrics and the master
+only on what exists only in the master: duration (incl. end card), first line (incl. head
+trim), frozen tail, hook window.
+"""
+import importlib
+import os
+import re
+import subprocess
+import sys
+
+from .ff import ffmpeg_exe, ffprobe_exe
+
+# Every subprocess gets a timeout: a truncated mp4 can make ffmpeg read forever and hang
+# an unattended acceptance job that otherwise just looks "still running".
+FF_TIMEOUT_SHORT = 60     # single-window volumedetect / ffprobe
+FF_TIMEOUT_LONG = 900     # whole-file scene scan / whole-file volume
+
+#: Thresholds: (green bound, red bound). Direction is inferred: green < red means lower is
+#: better; green > red means higher is better.
+T = {
+    # Duration. TikTok Creator Rewards requires videos **longer than one minute** — a 59 s
+    # episode earns nothing even at a million views, and the algorithm weighs total watch
+    # time, not only completion. A sample of 131 same-niche competitors had a median of
+    # 85 s (serialized episode posts: 339 s); 55–75 s is on the short side, so there is no
+    # reason to cut shorter. Green at ≥ 65 s leaves margin — platforms judge on their own
+    # decoded duration. Higher is better.
+    "dur": (65.0, 60.0),
+    # Pacing. Live-action platform series: ASL 1.08–1.54 s; other AI productions 2.6–3.1;
+    # our early AI cuts 3.18. Lower is better.
+    "asl": (2.0, 3.0),
+    "long_share": (0.30, 0.50),   # share of runtime in shots > 4 s; live-action series 0.23
+    # Dialogue density — the biggest gap measured. Competitors' speech_share 0.68–0.98,
+    # median 0.90; WPM 67–134. Higher is better (Chinese counted in characters, scaled 3/5).
+    "speech_share": (0.80, 0.65),
+    "wpm": (90, 70),
+    "max_gap": (5.0, 8.0),         # longest stretch without dialogue (s), lower is better
+    # Loudness. Competitors' mean_volume −16.0 to −21.5 dB; early masters −24.7 to −27.4.
+    "mean_volume": (-20.0, -23.0),  # higher is better
+    # Level jump at splice points. Independently rendered clips concatenated directly turn
+    # every splice into a room-tone/ambience jump — the ear catches it before any metric
+    # (one splice measured 40.8 dB). A continuous bed pulls it down (one episode: mean
+    # 11.8 → 8.2 dB). Lower is better.
+    "seam_db": (6.0, 15.0),
+    # First line of dialogue. The hook line should land immediately — swipe decisions
+    # happen in the first 3 seconds. Lower is better.
+    "first_speech": (1.5, 3.0),
+    # Frozen seconds at the end (end card + any freeze). Retention curves showed a 7.5 s
+    # card (12% of a 61 s episode) dropping end retention from r75 = 58% to r100 = 16%;
+    # episodes without a card kept 30–43%. Viewers swipe at a static card, logging an
+    # incomplete view at 88% for everyone. Green ≤ 5 s fits a 4 s card plus fade; red
+    # > 6.5 s catches long cards. Lower is better.
+    "tail_static": (5.0, 6.5),
+}
+SCENE_TH = 0.15   # low threshold catches in-scene cuts; a high one only sees scene changes
+LONG_SHOT = 4.0
+MASTER_KEYS = {"dur", "first_speech", "tail_static", "hook"}
+_CJK = re.compile(r"[\u3400-\u9fff]")
+
+GREEN, YELLOW, RED = "green", "yellow", "red"
+
+
+def grade(key: str, val) -> str:
+    if val is None:
+        return "-"
+    green, red = T[key]
+    if green < red:   # lower is better
+        return GREEN if val <= green else (RED if val > red else YELLOW)
+    return GREEN if val >= green else (RED if val < red else YELLOW)
+
+
+def _rms(exe: str, path: str, a: float, b: float):
+    log = subprocess.run([exe, "-nostats", "-ss", f"{a:.3f}", "-to", f"{b:.3f}", "-i", path,
+                          "-af", "volumedetect", "-f", "null", "-"],
+                         capture_output=True, text=True, timeout=FF_TIMEOUT_SHORT).stderr
+    m = re.search(r"mean_volume: (-?[\d.]+)", log)
+    return float(m.group(1)) if m else None
+
+
+def seam_jump(exe: str, path: str, bounds: list) -> dict:
+    """Level difference across each splice point (0.3 s either side) — measures "you can
+    hear the seam". ``bounds`` = cumulative seconds of each splice. Without bounds there is
+    nothing to measure: guessing splice points from the finished file mistakes normal
+    emotional dynamics for seams."""
+    jumps = []
+    for t in bounds:
+        lo = _rms(exe, path, max(0.0, t - 0.35), max(0.05, t - 0.05))
+        hi = _rms(exe, path, t + 0.05, t + 0.35)
+        if lo is not None and hi is not None:
+            jumps.append(abs(lo - hi))
+    if not jumps:
+        return {}
+    return {"seam_db": round(sum(jumps) / len(jumps), 1),
+            "seam_max": round(max(jumps), 1), "seams": len(jumps)}
+
+
+def cut_metrics(exe: str, path: str) -> dict:
+    dur = float(subprocess.run(
+        [ffprobe_exe(), "-v", "error", "-show_entries", "format=duration",
+         "-of", "csv=p=0", path], capture_output=True, text=True,
+        timeout=FF_TIMEOUT_SHORT).stdout.strip() or 0)
+    # NB: metadata=print:file=- writes to STDOUT, not stderr.
+    r = subprocess.run([exe, "-nostats", "-i", path, "-filter:v",
+                        f"select='gt(scene,{SCENE_TH})',metadata=print:file=-",
+                        "-an", "-f", "null", "-"], capture_output=True, text=True,
+                       timeout=FF_TIMEOUT_LONG)
+    cuts = [float(t) for t in re.findall(r"pts_time:([\d.]+)", r.stdout)
+            if 0.2 < float(t) < dur - 0.2]
+    bounds = [0.0] + cuts + [dur]
+    shots = [b - a for a, b in zip(bounds, bounds[1:]) if b - a > 0.05]
+    vol = subprocess.run([exe, "-nostats", "-i", path, "-af", "volumedetect",
+                          "-f", "null", "-"], capture_output=True, text=True,
+                         timeout=FF_TIMEOUT_LONG).stderr
+    m = re.search(r"mean_volume: (-?[\d.]+)", vol)
+    return {"dur": round(dur, 1), "cuts": len(cuts),
+            "asl": round(dur / max(1, len(shots)), 2),
+            "cpm": round(len(cuts) / (dur / 60), 1) if dur else 0,
+            "long_share": round(sum(s for s in shots if s > LONG_SHOT) / dur, 2) if dur else 0,
+            "mean_volume": float(m.group(1)) if m else None}
+
+
+def tail_static_from_log(log: str, tail: float) -> float:
+    """freezedetect log → frozen seconds at the very end (pure function).
+
+    Only a freeze that lasts **until the end** counts; a mid-file freeze that recovers is
+    long_share's business. Times are relative to the scan start; ``tail`` is the scan
+    window length."""
+    starts = [float(t) for t in re.findall(r"freeze_start: ([\d.]+)", log)]
+    ends = [float(t) for t in re.findall(r"freeze_end: ([\d.]+)", log)]
+    if not starts:
+        return 0.0
+    # The last freeze has no freeze_end (frozen to EOF), or its end touches the end.
+    if len(ends) < len(starts) or (ends and tail - ends[-1] < 0.5):
+        return round(tail - starts[-1], 1)
+    return 0.0
+
+
+def tail_static(exe: str, path: str, dur: float) -> dict:
+    """Seconds of frozen picture at the end (end card + any freeze). Scans the last ~15 s.
+    If the measurement fails the metric is omitted, never failed: a broken checker must not
+    block delivery."""
+    try:
+        seek = max(0.0, dur - 15.0)
+        r = subprocess.run([exe, "-nostats", "-ss", f"{seek:.2f}", "-i", path,
+                            "-vf", "freezedetect=n=0.003:d=1.5", "-an", "-f", "null", "-"],
+                           capture_output=True, text=True, timeout=FF_TIMEOUT_SHORT)
+        return {"tail_static": tail_static_from_log(r.stderr, dur - seek)}
+    except Exception as e:  # noqa: BLE001
+        print(f"tail_static skipped: {str(e)[:120]}", file=sys.stderr)
+        return {}
+
+
+def have_speech() -> bool:
+    try:
+        import faster_whisper  # noqa: F401, PLC0415
+        return True
+    except ImportError:
+        return False
+
+
+def speech_metrics(path: str, model_name: str | None = None) -> dict:
+    """Dialogue density via faster-whisper (optional extra). {} when not installed."""
+    try:
+        from faster_whisper import WhisperModel  # noqa: PLC0415
+    except ImportError:
+        return {}
+    model = WhisperModel(model_name or os.environ.get("DRAMAPACK_WHISPER_MODEL", "base"),
+                         device="cpu", compute_type="int8")
+    segs, info = model.transcribe(path, vad_filter=True, beam_size=1)
+    segs = sorted(segs, key=lambda s: s.start)
+    dur = info.duration or 1
+    zh = info.language == "zh"
+    words = sum(len(_CJK.findall(s.text)) if zh else len(s.text.split()) for s in segs)
+    gaps, prev = [], 0.0
+    for s in segs:
+        gaps.append(s.start - prev)
+        prev = max(prev, s.end)
+    gaps.append(dur - prev)
+    rate = words / (dur / 60)
+    # VAD segments overlap slightly / carry padding, so the sum can exceed duration —
+    # clamp to 1.0 rather than report a 1.1 that looks like a bug.
+    return {"lang": info.language,
+            "speech_share": round(min(1.0, sum(s.end - s.start for s in segs) / dur), 2),
+            # Chinese is counted per character; scale by 3/5 onto the same ruler as WPM.
+            "wpm": round(rate / (5 / 3) if zh else rate),
+            "wpm_raw": round(rate), "max_gap": round(max(gaps), 1),
+            "first_speech": round(segs[0].start, 1) if segs else None}
+
+
+def load_hook_plugin(spec: str):
+    """``"package.module:function"`` → callable ``f(path, ffmpeg_exe) -> dict`` returning
+    ``{"fails": [str], "warns": [str], "note": str}``. Bring your own model and credentials
+    (read them from your environment inside the plugin)."""
+    mod, _, fn = spec.partition(":")
+    if not mod or not fn:
+        raise ValueError("hook plugin must be 'module:function'")
+    return getattr(importlib.import_module(mod), fn)
+
+
+def hook_metrics(exe: str, path: str, plugin) -> dict:
+    """Hook window check (first ~3.5 s) through a user plugin. Failures of the plugin
+    itself (no network, no key, model error) degrade to "skipped", never to red."""
+    try:
+        r = plugin(path, exe) or {}
+    except Exception as e:  # noqa: BLE001
+        print(f"hook check skipped: {str(e)[:120]}", file=sys.stderr)
+        return {}
+    fails, warns = list(r.get("fails") or []), list(r.get("warns") or [])
+    return {"hook": RED if fails else (YELLOW if warns else GREEN),
+            "hook_fails": fails, "hook_warns": warns,
+            "hook_note": str(r.get("note") or "")[:200]}
+
+
+def audit(path: str, *, do_speech: bool = True, bounds: list | None = None,
+          hook_plugin=None, keys: set | None = None) -> dict:
+    """Measure one file. ``keys`` restricts which metrics are graded (None = all)."""
+    exe = ffmpeg_exe()
+    m = cut_metrics(exe, path)
+    m.update(tail_static(exe, path, m.get("dur") or 0.0))
+    if bounds:
+        m.update(seam_jump(exe, path, bounds))
+    if do_speech:
+        m.update(speech_metrics(path))
+    if hook_plugin:
+        m.update(hook_metrics(exe, path, hook_plugin))
+    m["file"] = os.path.basename(path)
+    grades = {k: grade(k, m.get(k)) for k in T}
+    if m.get("hook"):
+        grades["hook"] = m["hook"]
+    if keys is not None:
+        grades = {k: g for k, g in grades.items() if k in keys}
+    m["grades"] = grades
+    m["red"] = [k for k, g in grades.items() if g == RED]
+    return m
+
+
+def audit_pair(master_path: str, cut_path: str | None = None, **kw) -> list:
+    """Audit a master, optionally with its raw cut: the cut is graded on baseline metrics,
+    the master on master-only metrics (see module docstring)."""
+    if not cut_path:
+        return [audit(master_path, **kw)]
+    hook = kw.pop("hook_plugin", None)
+    bounds = kw.pop("bounds", None)
+    cut = audit(cut_path, bounds=bounds, keys=(set(T) - MASTER_KEYS) | {"dur"}, **kw)
+    mas = audit(master_path, hook_plugin=hook, keys=MASTER_KEYS, **kw)
+    cut["file"], mas["file"] = f"cut:{cut['file']}", f"master:{mas['file']}"
+    return [cut, mas]
+
+
+ROW = ["dur", "asl", "cpm", "long_share", "speech_share", "wpm", "max_gap", "mean_volume",
+       "seam_db", "first_speech", "tail_static", "hook"]
+_SHORT = {GREEN: "G", YELLOW: "Y", RED: "R"}
+
+
+def format_table(rows: list) -> str:
+    hdr = ["file"] + ROW
+    w = {c: max(len(c), *(len(str(r.get(c, "-"))) + 3 for r in rows)) for c in hdr}
+    out = ["  ".join(c.ljust(w[c]) for c in hdr)]
+    for r in rows:
+        cells = []
+        for c in hdr:
+            v = r.get(c, "-")
+            g = r["grades"].get(c)
+            mark = f"[{_SHORT[g]}]" if g in _SHORT else ""
+            cells.append(f"{v}{mark}".ljust(w[c]))
+        out.append("  ".join(cells))
+    out.append("\nthresholds (green/red): " + ", ".join(f"{k} {T[k][0]}/{T[k][1]}" for k in T))
+    for r in rows:
+        if r["red"]:
+            out.append(f"\n{r['file']} red: {', '.join(r['red'])}")
+        for f in r.get("hook_fails") or []:
+            out.append(f"  x {f}")
+        for wn in r.get("hook_warns") or []:
+            out.append(f"  ~ {wn}")
+        if r.get("hook_note"):
+            out.append(f"  hook window: {r['hook_note']}")
+    return "\n".join(out)

dramapack/cli.py

@@ -0,0 +1,212 @@
+"""``dramapack`` command line: master | package | audit | check-rights | inspect | mcp.
+
+Exit codes (stable):
+  0  success; nothing red (yellow findings / non-blocking gaps are still 0)
+  1  completed, but the result is red (audit red metric, rights red, or
+     ``package --strict`` with gaps or a red rights check)
+  2  usage error (bad arguments)
+  3  runtime failure (ffmpeg missing, unreadable input, encode failed)
+
+With ``--json`` the only thing on stdout is one JSON object (progress goes to stderr).
+Failures print ``{"ok": false, "error": "..."}``.
+"""
+import argparse
+import json
+import sys
+
+from . import api
+from . import master as M
+from .provenance import PROVENANCE, footer_line
+
+EXIT_OK, EXIT_RED, EXIT_USAGE, EXIT_FAIL = 0, 1, 2, 3
+
+
+def _emit(a, res: dict, human) -> None:
+    if a.json:
+        print(json.dumps(res, ensure_ascii=False, indent=2))
+    else:
+        human(res)
+
+
+def _cmd_master(a) -> int:
+    end_card = None
+    if a.end_card_title or a.end_card_line:
+        end_card = {"title": a.end_card_title or "", "lines": a.end_card_line or [],
+                    "site": a.end_card_site or ""}
+    res = api.master_episode(a.input, a.output, srt=a.srt, burn=not a.no_burn, bed=a.bed,
+                             music=a.music, music_db=a.music_db, head_trim=a.head_trim,
+                             end_card=end_card, card_secs=a.card_secs, cover_band=a.cover_band,
+                             subtitle_font=a.subtitle_font, normalize=not a.no_normalize)
+    _emit(a, res, lambda r: print(f"wrote {r['output']} ({r['spec'].get('duration_s')} s)"))
+    return EXIT_OK
+
+
+def _cmd_package(a) -> int:
+    eps = [int(x) for x in a.episodes.split(",")] if a.episodes else None
+    res = api.build_package(a.input_dir, a.output_dir, show=a.show, rights=a.rights,
+                            title=a.title, studio=a.studio, language=a.language, bed=a.bed,
+                            music=a.music, masters_ready=a.masters_ready, episodes=eps,
+                            platform_pairs=a.platform_pairs, clean=not a.no_clean,
+                            covers=not a.no_covers, timeline=not a.no_timeline,
+                            keep_work=a.keep_work)
+
+    def human(r):
+        print(f"\n{len(r['episodes'])} episodes -> {r['output_dir']}  [{r['status']}]")
+        print(f"rights check: {r['rights_status']}")
+        for g in r["gaps"]:
+            print(f"  gap: {g}")
+        for n in r["notes"]:
+            print(f"  note: {n}")
+        print(footer_line())
+
+    _emit(a, res, human)
+    if res["status"] == "red" or (a.strict and res["gaps"]):
+        return EXIT_RED
+    return EXIT_OK
+
+
+def _cmd_audit(a) -> int:
+    from .audit import format_table
+    bounds = [float(x) for x in a.bounds.split(",")] if a.bounds else None
+    res = api.audit_files(a.files, cut=a.cut, bounds=bounds, speech=not a.no_speech,
+                          hook_plugin=a.hook_plugin)
+
+    def human(r):
+        for s in r["skipped"]:
+            print(f"skipped: {s}", file=sys.stderr)
+        print(format_table(r["rows"]))
+
+    _emit(a, res, human)
+    return EXIT_RED if res["status"] == "red" else EXIT_OK
+
+
+def _cmd_rights(a) -> int:
+    from .rights import format_report
+    res = api.check_rights(a.rights, input_dir=a.input, bed=a.bed, music=a.music,
+                           subtitle_font=None if a.no_mastering_fonts else a.subtitle_font,
+                           end_card=a.end_card and not a.no_mastering_fonts,
+                           allow_fonts=a.allow_font or ())
+    _emit(a, res, lambda r: print(format_report(r)))
+    return EXIT_RED if res["status"] == "red" else EXIT_OK
+
+
+def _cmd_inspect(a) -> int:
+    res = api.inspect_file(a.file)
+
+    def human(r):
+        for k, v in r.items():
+            if k not in ("ok",):
+                print(f"{k:28} {v}")
+
+    _emit(a, res, human)
+    return EXIT_OK
+
+
+def _cmd_mcp(a) -> int:
+    from .mcp_server import run
+    run()
+    return EXIT_OK
+
+
+def build_parser() -> argparse.ArgumentParser:
+    ap = argparse.ArgumentParser(
+        prog="dramapack",
+        description=f"dramapack {PROVENANCE['version']} by Dawnwood — short-drama delivery "
+                    f"packs, mastering, acceptance audit and rights check. {PROVENANCE['url']}",
+        epilog="exit codes: 0 ok, 1 red result, 2 usage error, 3 runtime failure")
+    ap.add_argument("--version", action="version", version=f"%(prog)s {PROVENANCE['version']}")
+    sub = ap.add_subparsers(dest="cmd", required=True)
+
+    def add(name, **kw):
+        p = sub.add_parser(name, **kw)
+        p.add_argument("--json", action="store_true",
+                       help="print one JSON object on stdout (progress goes to stderr)")
+        return p
+
+    m = add("master", help="master one episode (subtitles, -14 LUFS, bed, end card)")
+    m.add_argument("input")
+    m.add_argument("output")
+    m.add_argument("--srt", help="subtitles to burn in")
+    m.add_argument("--no-burn", action="store_true", help="clean master: do not burn subtitles")
+    m.add_argument("--bed", choices=M.BED_MOODS, help="lay a procedural music bed of this mood")
+    m.add_argument("--music", help="your own music bed file (declare it in rights.json)")
+    m.add_argument("--music-db", type=float, default=M.MUSIC_DB)
+    m.add_argument("--head-trim", type=float, default=0.0, help="cut N seconds off the head")
+    m.add_argument("--end-card-title")
+    m.add_argument("--end-card-line", action="append", help="CTA line (repeatable)")
+    m.add_argument("--end-card-site")
+    m.add_argument("--card-secs", type=float, default=M.CARD_SECS)
+    m.add_argument("--cover-band", type=float, default=0.0,
+                   help="blur this fraction of the frame bottom first (re-subtitling)")
+    m.add_argument("--subtitle-font", default=M.SUB_FONT)
+    m.add_argument("--no-normalize", action="store_true")
+    m.set_defaults(func=_cmd_master)
+
+    p = add("package", help="build a platform delivery pack from an input folder")
+    p.add_argument("input_dir")
+    p.add_argument("output_dir")
+    p.add_argument("--show", help="show.json (default: <input_dir>/show.json)")
+    p.add_argument("--rights", help="rights.json (default: <input_dir>/rights.json)")
+    p.add_argument("--title")
+    p.add_argument("--studio")
+    p.add_argument("--language")
+    p.add_argument("--bed", choices=M.BED_MOODS, help="procedural music bed mood")
+    p.add_argument("--music", help="your own music bed file")
+    p.add_argument("--masters-ready", action="store_true",
+                   help="NN.mp4 are finished subtitled masters (clean master from NN.cut.mp4)")
+    p.add_argument("--episodes", help="comma-separated episode numbers (default: all)")
+    p.add_argument("--platform-pairs", action="store_true",
+                   help="also build two-episodes-per-file platform cuts")
+    p.add_argument("--no-clean", action="store_true")
+    p.add_argument("--no-covers", action="store_true")
+    p.add_argument("--no-timeline", action="store_true")
+    p.add_argument("--keep-work", action="store_true", help="keep the _work scratch folder")
+    p.add_argument("--strict", action="store_true",
+                   help="exit 1 when the pack has any gap (red results always exit 1)")
+    p.set_defaults(func=_cmd_package)
+
+    u = add("audit", help="acceptance audit against short-drama benchmarks")
+    u.add_argument("files", nargs="+")
+    u.add_argument("--cut", help="raw cut of the (single) master: grade each on its own metrics")
+    u.add_argument("--bounds", help="splice points in seconds, comma-separated (seam metric)")
+    u.add_argument("--no-speech", action="store_true", help="skip faster-whisper metrics")
+    u.add_argument("--hook-plugin", metavar="MODULE:FUNC",
+                   help="optional hook-window checker f(path, ffmpeg) -> {fails, warns, note}")
+    u.set_defaults(func=_cmd_audit)
+
+    r = add("check-rights", help="grade declared music and fonts red/yellow/green")
+    r.add_argument("rights", nargs="?", help="rights.json")
+    r.add_argument("--input", help="input folder (rights.json default, *.ass font scan)")
+    r.add_argument("--bed", choices=M.BED_MOODS, help="procedural bed in use (auto-declared)")
+    r.add_argument("--music", help="music file used in mastering (must be declared)")
+    r.add_argument("--subtitle-font", default=M.SUB_FONT)
+    r.add_argument("--end-card", action="store_true", help="include the end-card font")
+    r.add_argument("--no-mastering-fonts", action="store_true",
+                   help="don't check the fonts this tool burns in")
+    r.add_argument("--allow-font", action="append", help="extend the font allowlist")
+    r.set_defaults(func=_cmd_rights)
+
+    i = add("inspect", help="measured specs + integrated LUFS / true peak of a media file")
+    i.add_argument("file")
+    i.set_defaults(func=_cmd_inspect)
+
+    s = sub.add_parser("mcp", help="run the MCP server on stdio (for AI agents)")
+    s.set_defaults(func=_cmd_mcp, json=False)
+    return ap
+
+
+def main(argv=None) -> int:
+    a = build_parser().parse_args(argv)
+    try:
+        return a.func(a)
+    except Exception as e:  # noqa: BLE001
+        msg = f"{type(e).__name__}: {e}"
+        if getattr(a, "json", False):
+            print(json.dumps({"ok": False, "error": msg}))
+        else:
+            print(f"dramapack: error: {msg}", file=sys.stderr)
+        return EXIT_FAIL
+
+
+if __name__ == "__main__":
+    sys.exit(main())