scribecast 0.1.0__py3-none-any.whl

vidkit_core/export.py

@@ -0,0 +1,126 @@
+"""vqkit.export — multi-aspect / gif / thumbnail / manifest export (distribution axis).
+
+Council EARS#2 (reflowed aspect MP4s) + EARS#4 (MP4 + GIF + thumbnail + subtitle + JSON
+manifest). Two aspect paths:
+  - reframe_ffmpeg(): fast crop/pad a 16:9 master into 9:16 / 1:1 (works on ANY video)
+  - true reflow (re-render at target frame dims) is exposed via render.render_scene with
+    --resolution; aspect-aware scenes use config.frame_width/height. ffmpeg path is the
+    default (deterministic, no re-render cost); reflow is opt-in for hero pieces.
+All deterministic via ffmpeg. Manifest carries duration/fps/res/sha256 for regression.
+"""
+from __future__ import annotations
+import hashlib
+import json
+import subprocess
+from dataclasses import dataclass, asdict
+from pathlib import Path
+
+ASPECTS = {
+    "16:9": (1920, 1080),
+    "9:16": (1080, 1920),
+    "1:1": (1080, 1080),
+}
+
+
+def _run(cmd: list[str], timeout: int = 300):
+    p = subprocess.run(cmd, capture_output=True, text=True, timeout=timeout)
+    if p.returncode != 0:
+        raise RuntimeError(f"ffmpeg failed (exit {p.returncode}):\n{p.stderr[-1000:]}")
+    return p
+
+
+def sha256(path: str) -> str:
+    h = hashlib.sha256()
+    with open(path, "rb") as f:
+        for chunk in iter(lambda: f.read(65536), b""):
+            h.update(chunk)
+    return h.hexdigest()
+
+
+def reframe(master: str, aspect: str, out_path: str, mode: str = "pad") -> str:
+    """Reframe a master video to a target aspect. mode='pad' (letterbox, no content loss)
+    or 'crop' (fill, edge loss). Default pad — safest, never drops content."""
+    if aspect not in ASPECTS:
+        raise ValueError(f"unknown aspect {aspect}; valid: {list(ASPECTS)}")
+    w, h = ASPECTS[aspect]
+    Path(out_path).parent.mkdir(parents=True, exist_ok=True)
+    if mode == "pad":
+        vf = (f"scale={w}:{h}:force_original_aspect_ratio=decrease,"
+              f"pad={w}:{h}:(ow-iw)/2:(oh-ih)/2:color=0x0E1116")
+    else:  # crop-to-fill
+        vf = (f"scale={w}:{h}:force_original_aspect_ratio=increase,"
+              f"crop={w}:{h}")
+    cmd = ["ffmpeg", "-y", "-i", master, "-vf", vf]
+    # preserve audio if present
+    cmd += ["-c:a", "copy", out_path]
+    _run(cmd)
+    return out_path
+
+
+def gif(master: str, out_path: str, fps: int = 12, width: int = 640,
+        start: float = 0.0, duration: float | None = None) -> str:
+    """High-quality GIF via palettegen/paletteuse (2-pass). For embeds/previews."""
+    Path(out_path).parent.mkdir(parents=True, exist_ok=True)
+    palette = str(Path(out_path).with_suffix(".palette.png"))
+    seek = ["-ss", str(start)] + (["-t", str(duration)] if duration else [])
+    vf = f"fps={fps},scale={width}:-1:flags=lanczos"
+    try:
+        _run(["ffmpeg", "-y", *seek, "-i", master, "-vf", f"{vf},palettegen=stats_mode=diff", palette])
+        _run(["ffmpeg", "-y", *seek, "-i", master, "-i", palette,
+              "-lavfi", f"{vf}[x];[x][1:v]paletteuse=dither=bayer", out_path])
+    finally:
+        Path(palette).unlink(missing_ok=True)   # review P2-C: clean up even if pass 2 fails
+    return out_path
+
+
+def thumbnail(master: str, out_path: str, at: float = 1.0) -> str:
+    """Extract a hero frame as PNG at timestamp `at` seconds."""
+    Path(out_path).parent.mkdir(parents=True, exist_ok=True)
+    _run(["ffmpeg", "-y", "-ss", str(at), "-i", master, "-frames:v", "1", out_path])
+    return out_path
+
+
+@dataclass
+class Manifest:
+    name: str
+    master: str
+    duration: float
+    fps: float
+    width: int
+    height: int
+    sha256: str
+    aspects: dict
+    gif: str | None
+    thumbnail: str | None
+    subtitle: str | None
+
+
+def export_bundle(master: str, name: str, out_dir: str,
+                  aspects: list[str] | None = None, subtitle: str | None = None,
+                  make_gif: bool = True, make_thumb: bool = True) -> dict:
+    """Produce the full distribution bundle: aspect variants + gif + thumbnail + manifest.
+    Returns the manifest dict (also written to <out_dir>/<name>.manifest.json)."""
+    from .render import ffprobe
+    out = Path(out_dir); out.mkdir(parents=True, exist_ok=True)
+    probe = ffprobe(master)
+
+    aspect_paths = {}
+    for a in (aspects or ["16:9", "9:16", "1:1"]):
+        safe = a.replace(":", "x")
+        aspect_paths[a] = reframe(master, a, str(out / f"{name}_{safe}.mp4"))
+
+    gif_path = gif(master, str(out / f"{name}.gif")) if make_gif else None
+    # midpoint hero frame (review P2-B): clamp to the video length, NOT to 1.0s — the old
+    # min(1.0, ...) pinned every >2s video's thumbnail to second 1.
+    thumb_at = max(0.1, min(probe.duration - 0.1, probe.duration / 2)) if probe.duration > 0.2 else 0.1
+    thumb_path = thumbnail(master, str(out / f"{name}_thumb.png"), at=thumb_at) if make_thumb else None
+
+    man = Manifest(
+        name=name, master=master, duration=probe.duration, fps=probe.fps,
+        width=probe.width, height=probe.height, sha256=sha256(master),
+        aspects=aspect_paths, gif=gif_path, thumbnail=thumb_path, subtitle=subtitle,
+    )
+    man_path = out / f"{name}.manifest.json"
+    with open(man_path, "w") as f:        # review P2-D: context manager, no truncate-on-error
+        json.dump(asdict(man), f, indent=2)
+    return asdict(man)

vidkit_core/layout.py

@@ -0,0 +1,110 @@
+"""vidkit_core.layout — renderer-AGNOSTIC layout geometry + regression (L2 math).
+
+Council-locked: the BBox math, safe-frame check, overlap, snapshot-diff, and golden I/O are
+pure and shared across Manim / Remotion / HyperFrames. The renderer-SPECIFIC part — how you
+OBTAIN a bbox for an element — lives in each kit:
+  - Manim:      mobject.get_left()/get_right()/... (vqkit.layout.bbox_of)
+  - Remotion:   Playwright getBoundingClientRect -> bbox_from_dom_rect()
+  - HyperFrames: native lint/inspect/validate (its own L2, no bbox needed)
+
+This module provides the shared geometry + a DOM-rect adapter so browser renderers feed the
+same diff/regression pipeline as Manim.
+"""
+from __future__ import annotations
+import json
+from dataclasses import dataclass, asdict
+from pathlib import Path
+
+# Manim default frame; browser renderers pass their own frame dims to exceeds_safe_frame().
+FRAME_W = 14.222222
+FRAME_H = 8.0
+SAFE_FRAC = 0.96
+
+
+@dataclass
+class BBox:
+    x0: float; y0: float; x1: float; y1: float
+
+    @property
+    def w(self): return self.x1 - self.x0
+    @property
+    def h(self): return self.y1 - self.y0
+    @property
+    def cx(self): return (self.x0 + self.x1) / 2
+    @property
+    def cy(self): return (self.y0 + self.y1) / 2
+
+    def overlaps(self, other: "BBox", pad: float = 0.0) -> bool:
+        return not (self.x1 + pad <= other.x0 or other.x1 + pad <= self.x0 or
+                    self.y1 + pad <= other.y0 or other.y1 + pad <= self.y0)
+
+
+def bbox_from_dom_rect(rect: dict) -> BBox:
+    """Adapt a Playwright/DOM getBoundingClientRect {x,y,width,height} to a BBox in PIXEL space.
+    For browser renderers (Remotion). Origin top-left, y grows downward — that's fine, the
+    diff/overlap math is origin-agnostic as long as golden + current use the same convention."""
+    x, y, w, h = rect["x"], rect["y"], rect["width"], rect["height"]
+    return BBox(round(float(x), 2), round(float(y), 2),
+                round(float(x + w), 2), round(float(y + h), 2))
+
+
+def exceeds_frame(bb: BBox, frame_w: float, frame_h: float, frac: float = SAFE_FRAC,
+                  origin: str = "center") -> bool:
+    """True if bbox pokes outside the safe area. origin='center' (Manim scene coords) or
+    'topleft' (browser pixel coords)."""
+    if origin == "center":
+        hw, hh = frame_w * frac / 2, frame_h * frac / 2
+        return bb.x0 < -hw or bb.x1 > hw or bb.y0 < -hh or bb.y1 > hh
+    # top-left pixel space: safe area is a centered frac-box of the frame
+    mx, my = frame_w * (1 - frac) / 2, frame_h * (1 - frac) / 2
+    return bb.x0 < mx or bb.x1 > frame_w - mx or bb.y0 < my or bb.y1 > frame_h - my
+
+
+def assert_no_overlap(boxes: dict, pad: float = 0.0, ignore_pairs: set | None = None) -> list[str]:
+    """Return overlapping pairs that should be disjoint. boxes: {key: BBox}. Empty = pass."""
+    ignore_pairs = ignore_pairs or set()
+    keys = list(boxes.keys())
+    out = []
+    for i in range(len(keys)):
+        for j in range(i + 1, len(keys)):
+            ka, kb = keys[i], keys[j]
+            if (ka, kb) in ignore_pairs or (kb, ka) in ignore_pairs:
+                continue
+            if boxes[ka].overlaps(boxes[kb], pad):
+                out.append(f"{ka} overlaps {kb}")
+    return out
+
+
+def snapshot_boxes(boxes: dict) -> dict:
+    """{key: {bbox}} snapshot from a {key: BBox} dict (renderer feeds the boxes)."""
+    return {k: {"bbox": asdict(v)} for k, v in boxes.items()}
+
+
+def diff_snapshot(golden: dict, current: dict, pos_tol: float = 0.15) -> list[str]:
+    """Compare two snapshots; return drift lines. pos_tol in the snapshot's unit (scene or px)."""
+    drift = []
+    gk, ck = set(golden), set(current)
+    for k in gk - ck:
+        drift.append(f"MISSING: {k} present in golden, absent now")
+    for k in ck - gk:
+        drift.append(f"ADDED: {k} present now, absent in golden")
+    for k in gk & ck:
+        gb, cb = golden[k]["bbox"], current[k]["bbox"]
+        for f in ("x0", "y0", "x1", "y1"):
+            if abs(gb[f] - cb[f]) > pos_tol:
+                drift.append(f"DRIFT: {k}.{f} {gb[f]} -> {cb[f]} (>{pos_tol})")
+    return drift
+
+
+def save_golden(snap: dict, path: str):
+    Path(path).parent.mkdir(parents=True, exist_ok=True)
+    with open(path, "w") as f:
+        json.dump(snap, f, indent=2)
+
+
+def load_golden(path: str) -> dict | None:
+    p = Path(path)
+    if not p.exists():
+        return None
+    with open(p) as f:
+        return json.load(f)

vidkit_core/phash.py

@@ -0,0 +1,89 @@
+"""vqkit.phash — L4 keyframe perceptual-hash regression (the NARROW pixel check).
+
+Council L4: pHash on 3-5 KEYFRAMES ONLY, generous Hamming tolerance (>=6) — catches gross
+visual regressions (black frame, totally wrong layout) without the antialiasing/font-drift
+false-positives that killed golden-frame-as-primary. L2 bbox is the primary mechanism; this
+is the backstop. Pure Pillow, deterministic.
+"""
+from __future__ import annotations
+import json
+import subprocess
+from pathlib import Path
+
+# PIL (Pillow) is lazy-imported so `import vidkit_core` works without it. Pillow is only
+# needed when you actually compute perceptual hashes — install via `pip install vidkit[manim]`
+# (the extra that bundles pillow) or `pip install pillow`.
+def _require_pil():
+    try:
+        from PIL import Image
+        return Image
+    except ImportError as exc:  # pragma: no cover
+        raise RuntimeError(
+            "phash needs Pillow. Install it: pip install pillow  (or pip install vidkit[manim])"
+        ) from exc
+
+
+def _dhash(img, hash_size: int = 8) -> int:
+    """Difference hash (dHash) — robust to scale/brightness, sensitive to structure.
+    `img` is a PIL.Image.Image."""
+    Image = _require_pil()
+    img = img.convert("L").resize((hash_size + 1, hash_size), Image.LANCZOS)
+    bits = 0
+    idx = 0
+    px = img.load()
+    for y in range(hash_size):
+        for x in range(hash_size):
+            bits |= (1 if px[x, y] < px[x + 1, y] else 0) << idx
+            idx += 1
+    return bits
+
+
+def hamming(a: int, b: int) -> int:
+    return bin(a ^ b).count("1")
+
+
+def extract_frame(video: str, at: float, out_png: str) -> str:
+    Path(out_png).parent.mkdir(parents=True, exist_ok=True)
+    subprocess.run(["ffmpeg", "-y", "-ss", str(at), "-i", video, "-frames:v", "1", out_png],
+                   capture_output=True, check=True, timeout=60)   # review P3: timeout
+    return out_png
+
+
+def keyframe_hashes(video: str, timestamps: list[float], work_dir: str) -> dict:
+    """Return {timestamp: dhash} for the given keyframes. Keys normalized to 3dp so int/float
+    callers don't desync golden vs current (review P3)."""
+    Image = _require_pil()
+    out = {}
+    for i, t in enumerate(timestamps):
+        png = extract_frame(video, t, str(Path(work_dir) / f"kf_{i}.png"))
+        with Image.open(png) as im:        # review P3: close the PIL handle
+            out[f"{float(t):.3f}"] = _dhash(im)
+    return out
+
+
+def save_golden(hashes: dict, path: str):
+    Path(path).parent.mkdir(parents=True, exist_ok=True)
+    with open(path, "w") as f:
+        json.dump(hashes, f, indent=2)
+
+
+def load_golden(path: str) -> dict | None:
+    p = Path(path)
+    if not p.exists():
+        return None
+    with open(p) as f:
+        return json.load(f)
+
+
+def compare(golden: dict, current: dict, tolerance: int = 6) -> list[str]:
+    """Return drift lines for keyframes whose Hamming distance exceeds tolerance.
+    tolerance>=6 per council (avoids AA/font-hint false positives)."""
+    drift = []
+    for ts, gh in golden.items():
+        if ts not in current:
+            drift.append(f"MISSING keyframe {ts}")
+            continue
+        d = hamming(int(gh), int(current[ts]))
+        if d > tolerance:
+            drift.append(f"keyframe {ts}: Hamming {d} > {tolerance} (gross visual change)")
+    return drift

vidkit_core/publish.py

@@ -0,0 +1,185 @@
+"""vidkit_core.publish — post a rendered video to X/Twitter.
+
+SAFETY BOUNDARY (operator constraint, SOUL §5): publish() defaults to dry_run=True and never
+sends on its own. The REAL send path (send_to_x) is fully implemented but requires (a) an
+explicit confirm token AND (b) four OAuth 1.0a user-context credentials in the environment.
+With both present it WILL post — that's the wired state the user authorized 2026-06-15. The
+agent still drafts the tweet text and gets human approval on the exact text before calling it.
+
+X video posting needs OAuth 1.0a user context (bearer tokens can't post media). The flow is:
+chunked media upload (INIT/APPEND/FINALIZE on upload.twitter.com) -> poll processing ->
+create tweet with the media_id (api.twitter.com/2/tweets).
+"""
+from __future__ import annotations
+import json
+import os
+import time
+from dataclasses import dataclass, asdict
+from pathlib import Path
+
+# X (Twitter) media limits as of 2026 (video): <=512MB, <=140s for most accounts.
+MAX_VIDEO_BYTES = 512 * 1024 * 1024
+MAX_VIDEO_SECONDS = 140
+REQUIRED_TOKEN = "I-EXPLICITLY-AUTHORIZE-THIS-PUBLIC-POST"
+
+# OAuth 1.0a user-context credential env vars (standard tweepy/twurl names).
+X_CRED_VARS = ("X_CONSUMER_KEY", "X_CONSUMER_SECRET", "X_ACCESS_TOKEN", "X_ACCESS_TOKEN_SECRET")
+
+
+def x_credentials() -> dict | None:
+    """Return the 4 OAuth1 creds from env, or None if any is missing."""
+    vals = {k: os.environ.get(k) for k in X_CRED_VARS}
+    return vals if all(vals.values()) else None
+
+
+@dataclass
+class PostPayload:
+    text: str
+    media_path: str
+    alt_text: str
+    media_bytes: int
+    media_seconds: float
+    within_limits: bool
+    limit_notes: list
+
+
+def compose(video_path: str, text: str, alt_text: str = "") -> PostPayload:
+    """Build + validate a post payload from a rendered video. No network."""
+    from .render import ffprobe
+    p = Path(video_path)
+    notes = []
+    if not p.exists():
+        return PostPayload(text, video_path, alt_text, 0, 0.0, False, ["media file not found"])
+    size = p.stat().st_size
+    probe = ffprobe(video_path)
+    if size > MAX_VIDEO_BYTES:
+        notes.append(f"video {size/1e6:.1f}MB > 512MB limit")
+    if probe.duration > MAX_VIDEO_SECONDS:
+        notes.append(f"video {probe.duration:.0f}s > {MAX_VIDEO_SECONDS}s limit")
+    if len(text) > 280:
+        notes.append(f"caption {len(text)} chars > 280")
+    if not alt_text:
+        notes.append("no alt-text (accessibility)")
+    within = not [n for n in notes if "limit" in n or ">" in n]
+    return PostPayload(text, video_path, alt_text, size, probe.duration, within, notes)
+
+
+def send_to_x(payload: PostPayload, timeout: int = 300) -> dict:
+    """REAL send: chunked video upload (OAuth1) -> tweet with media. Requires the 4 X_* creds
+    AND the `requests` + `requests_oauthlib` packages. Returns {ok, tweet_id, url} or {ok:False,
+    error}. Caller (publish) gates this behind dry_run=False + confirm token. No autonomous use."""
+    creds = x_credentials()
+    if not creds:
+        return {"ok": False, "error": f"missing X creds: {[k for k in X_CRED_VARS if not os.environ.get(k)]}"}
+    try:
+        import requests
+        from requests_oauthlib import OAuth1
+    except ImportError as e:
+        return {"ok": False, "error": f"pip install requests requests_oauthlib ({e})"}
+
+    auth = OAuth1(creds["X_CONSUMER_KEY"], creds["X_CONSUMER_SECRET"],
+                  creds["X_ACCESS_TOKEN"], creds["X_ACCESS_TOKEN_SECRET"])
+    UPLOAD = "https://upload.twitter.com/1.1/media/upload.json"
+    total = os.path.getsize(payload.media_path)
+
+    # 1. INIT
+    r = requests.post(UPLOAD, auth=auth, timeout=timeout, data={
+        "command": "INIT", "media_type": "video/mp4", "total_bytes": total,
+        "media_category": "tweet_video"})
+    if r.status_code >= 300:
+        return {"ok": False, "error": f"INIT failed {r.status_code}: {r.text[:200]}"}
+    media_id = r.json()["media_id_string"]
+
+    # 2. APPEND (chunked, 4MB segments)
+    seg, CHUNK = 0, 4 * 1024 * 1024
+    with open(payload.media_path, "rb") as f:
+        while True:
+            chunk = f.read(CHUNK)
+            if not chunk:
+                break
+            ra = requests.post(UPLOAD, auth=auth, timeout=timeout,
+                               data={"command": "APPEND", "media_id": media_id, "segment_index": seg},
+                               files={"media": chunk})
+            if ra.status_code >= 300:
+                return {"ok": False, "error": f"APPEND seg {seg} failed {ra.status_code}: {ra.text[:200]}"}
+            seg += 1
+
+    # 3. FINALIZE + poll processing
+    rf = requests.post(UPLOAD, auth=auth, timeout=timeout,
+                       data={"command": "FINALIZE", "media_id": media_id})
+    if rf.status_code >= 300:
+        return {"ok": False, "error": f"FINALIZE failed {rf.status_code}: {rf.text[:200]}"}
+    info = rf.json().get("processing_info", {})
+    waited = 0
+    while info.get("state") in ("pending", "in_progress"):
+        wait = min(info.get("check_after_secs", 5), 15)
+        time.sleep(wait); waited += wait
+        if waited > timeout:
+            return {"ok": False, "error": "media processing timed out"}
+        rs = requests.get(UPLOAD, auth=auth, timeout=timeout,
+                          params={"command": "STATUS", "media_id": media_id})
+        info = rs.json().get("processing_info", {})
+    if info.get("state") == "failed":
+        return {"ok": False, "error": f"media processing failed: {info}"}
+
+    # 3b. alt-text (accessibility) — best-effort
+    if payload.alt_text:
+        try:
+            requests.post("https://upload.twitter.com/1.1/media/metadata/create.json", auth=auth,
+                          timeout=timeout, json={"media_id": media_id,
+                          "alt_text": {"text": payload.alt_text[:1000]}})
+        except Exception:
+            pass
+
+    # 4. create tweet
+    rt = requests.post("https://api.twitter.com/2/tweets", auth=auth, timeout=timeout,
+                       json={"text": payload.text, "media": {"media_ids": [media_id]}})
+    if rt.status_code >= 300:
+        return {"ok": False, "error": f"tweet create failed {rt.status_code}: {rt.text[:200]}"}
+    tid = rt.json().get("data", {}).get("id")
+    return {"ok": True, "tweet_id": tid, "url": f"https://x.com/i/status/{tid}" if tid else None}
+
+
+def publish(payload: PostPayload, dry_run: bool = True, confirm: str = "") -> dict:
+    """Publish to X. DEFAULT dry_run=True -> never sends, returns the would-post plan.
+
+    To actually send, ALL must hold: dry_run=False AND confirm==REQUIRED_TOKEN AND the 4 X_*
+    OAuth1 creds in env. When all three are satisfied this CALLS send_to_x and really posts
+    (the user-authorized wired state, 2026-06-15). Without the token or creds it blocks safely.
+    """
+    plan = {
+        "would_post": {
+            "text": payload.text,
+            "media": payload.media_path,
+            "alt_text": payload.alt_text,
+            "media_bytes": payload.media_bytes,
+            "media_seconds": round(payload.media_seconds, 1),
+        },
+        "within_limits": payload.within_limits,
+        "limit_notes": payload.limit_notes,
+    }
+    if dry_run:
+        plan["status"] = "DRY_RUN — nothing sent"
+        return plan
+    if confirm != REQUIRED_TOKEN:
+        plan["status"] = "BLOCKED — missing explicit confirm token (no post sent)"
+        return plan
+    if not payload.within_limits:
+        plan["status"] = "BLOCKED — media exceeds X limits (no post sent)"
+        return plan
+    if not x_credentials():
+        plan["status"] = (f"BLOCKED — X credentials not in env ({', '.join(X_CRED_VARS)}). "
+                          "No post sent.")
+        return plan
+    # All gates passed: token + within-limits + creds present -> REAL post (user-authorized).
+    result = send_to_x(payload)
+    plan["status"] = "POSTED" if result.get("ok") else f"SEND_FAILED — {result.get('error')}"
+    plan["result"] = result
+    return plan
+
+
+def dry_run_report(video_path: str, text: str, alt_text: str = "") -> str:
+    """Convenience: compose + dry-run publish, return a readable report."""
+    payload = compose(video_path, text, alt_text)
+    plan = publish(payload, dry_run=True)
+    return json.dumps(plan, indent=2)

vidkit_core/render.py

@@ -0,0 +1,68 @@
+"""vidkit_core.render — renderer-AGNOSTIC mp4 introspection + generic CLI render driver.
+
+Probe + ffprobe are pure (any mp4). render_cli() is a generic subprocess driver that each kit
+calls with its own command (manim / npx remotion render / npx hyperframes render), then locates
+the produced mp4 and returns a Probe. No renderer assumptions in core.
+"""
+from __future__ import annotations
+import json
+import subprocess
+from dataclasses import dataclass
+from pathlib import Path
+
+
+@dataclass
+class Probe:
+    path: str
+    exists: bool
+    size: int
+    duration: float
+    fps: float
+    width: int
+    height: int
+    has_audio: bool
+
+    @property
+    def ok(self) -> bool:
+        return self.exists and self.size > 0 and self.duration > 0
+
+
+def ffprobe(path: str) -> Probe:
+    """Introspect an mp4 via ffprobe. Deterministic, no vision model. Timeout-guarded."""
+    p = Path(path)
+    if not p.exists():
+        return Probe(path, False, 0, 0.0, 0.0, 0, 0, False)
+    try:
+        proc = subprocess.run(
+            ["ffprobe", "-v", "error", "-print_format", "json",
+             "-show_format", "-show_streams", str(p)],
+            capture_output=True, text=True, timeout=30)
+        out = proc.stdout
+    except subprocess.TimeoutExpired:
+        return Probe(path, True, p.stat().st_size, 0.0, 0.0, 0, 0, False)
+    meta = json.loads(out or "{}")
+    dur = float(meta.get("format", {}).get("duration", 0) or 0)
+    vid = next((s for s in meta.get("streams", []) if s.get("codec_type") == "video"), {})
+    aud = any(s.get("codec_type") == "audio" for s in meta.get("streams", []))
+    rfr = vid.get("r_frame_rate", "0/1")
+    try:
+        num, den = rfr.split("/"); fps = float(num) / float(den) if float(den) else 0.0
+    except Exception:
+        fps = 0.0
+    return Probe(path, True, p.stat().st_size, dur, fps,
+                 int(vid.get("width", 0)), int(vid.get("height", 0)), aud)
+
+
+def render_cli(cmd: list[str], cwd: str, out_glob: str, search_dir: str,
+               timeout: int = 600) -> Probe:
+    """Generic CLI render driver: run `cmd` in cwd, then locate the newest mp4 matching out_glob
+    under search_dir, return its Probe. Each kit supplies its own command + glob.
+    Raises RuntimeError on non-zero exit or no output (no silent failure)."""
+    proc = subprocess.run(cmd, capture_output=True, text=True, timeout=timeout, cwd=cwd)
+    if proc.returncode != 0:
+        raise RuntimeError(f"render failed (exit {proc.returncode}):\n{proc.stderr[-1500:]}")
+    candidates = list(Path(search_dir).rglob(out_glob))
+    if not candidates:
+        raise RuntimeError(f"render exit 0 but no {out_glob} found under {search_dir}")
+    newest = max(candidates, key=lambda p: (p.stat().st_mtime, str(p)))
+    return ffprobe(str(newest))

vidkit_core/theme.py

@@ -0,0 +1,72 @@
+"""vqkit.theme — design tokens for cinematic Manim videos.
+
+Single source of truth for color/typography/timing/layout, extracted from the
+anti-ppt-cinematic-playbook. Every scene imports from here so videos share a
+visual language (playbook principle: "cohesive visual language across scenes").
+"""
+from __future__ import annotations
+from dataclasses import dataclass, field
+
+
+# ── Palette (Neon-Tech base from the playbook, dark bg + high-contrast accents) ──
+class Palette:
+    BG = "#0E1116"          # near-black, maximizes contrast (playbook principle 11)
+    BG_GRADIENT_TOP = "#141925"
+    BG_GRADIENT_BOTTOM = "#0A0C10"
+    PRIMARY = "#58A6FF"     # blue — primary concept
+    SECONDARY = "#4ECDC4"   # teal — secondary
+    ACCENT = "#FFD93D"      # yellow — attention/highlight
+    WIN = "#6BCB77"         # green — success/winner
+    DANGER = "#FF6B6B"      # red — error/emphasis
+    FUSE = "#A78BFA"        # violet — synthesis
+    INK = "#E6E9EF"         # default text
+    MUTED = "#9AA3B2"       # context text
+    DIM = 0.18              # opacity for de-emphasized (spotlight losers)
+    CONTEXT = 0.4           # opacity for context layer
+    GRID = 0.15             # opacity for structural (axes/grid)
+
+
+# ── Typography (Menlo mono — Pango kerning-safe per playbook) ──
+class Type:
+    FONT = "Menlo"          # mono: zero kerning bugs (playbook font rule)
+    TITLE = 48
+    H1 = 36
+    H2 = 28
+    BODY = 22
+    LABEL = 19
+    SMALL = 16
+    MIN = 18                # min readable size at -ql (playbook)
+
+
+# ── Timing (breathing room — playbook principle 8) ──
+class Timing:
+    BEAT = 0.6              # pause after a minor reveal
+    HOLD = 1.5              # pause after a key reveal (playbook minimum)
+    LONG_HOLD = 2.0         # pause after the payoff
+    WRITE = 1.2             # text write run_time
+    MOVE = 1.4              # camera move run_time
+    FAST = 0.6
+
+
+# ── Camera framing (frame default width = 14.222) ──
+class Cam:
+    FULL_W = 14.222
+    WIDE_W = 16.0           # pan-out to show more
+    ZOOM_W = 7.0            # framed zoom (incl. labels)
+    TIGHT_W = 4.8           # ~3x magnification
+
+
+# ── RRF / fusion constant (used by the example scenes) ──
+RRF_K = 60
+
+
+@dataclass
+class Theme:
+    """Bundled theme passed to CinematicScene; override per-video for brand variants."""
+    palette: type = field(default=Palette)
+    type: type = field(default=Type)
+    timing: type = field(default=Timing)
+    cam: type = field(default=Cam)
+
+
+DEFAULT_THEME = Theme()