scribecast 0.1.0__py3-none-any.whl

vqkit/__init__.py

@@ -0,0 +1,36 @@
+"""vqkit — cinematic Manim video toolkit. Makes every video cinematic-by-default.
+
+Council-locked design (2026-06-15, think-max+deep unanimous): a reusable production
+toolkit (NOT a fixed gallery), with 4-layer deterministic tests (render/bbox/audio/pHash,
+NO vision-model). Built by refactoring FROM the 3 concrete example scenes.
+
+The manim-dependent scene classes (CinematicScene, Cinematic3DScene, tex_or_text) are
+LAZY (PEP 562 __getattr__) so the manim-free submodules — audio, export, layout, phash,
+render — import without manim installed. `import vqkit; vqkit.audio` works with zero
+heavy deps; `from vqkit import CinematicScene` triggers the manim import on demand
+(install via `pip install vidkit[manim]`).
+"""
+from .theme import DEFAULT_THEME, Theme, Palette, Type, Timing, Cam, RRF_K
+
+__version__ = "0.1.0"
+__all__ = [
+    "CinematicScene", "Cinematic3DScene", "tex_or_text",
+    "DEFAULT_THEME", "Theme", "Palette", "Type", "Timing", "Cam", "RRF_K",
+]
+
+# Lazy manim-dependent exports — only imported when actually accessed, so the
+# renderer-agnostic submodules stay importable without manim.
+_LAZY = {
+    "CinematicScene": ("vqkit.scene", "CinematicScene"),
+    "tex_or_text": ("vqkit.scene", "tex_or_text"),
+    "Cinematic3DScene": ("vqkit.scene3d", "Cinematic3DScene"),
+}
+
+
+def __getattr__(name: str):  # PEP 562
+    target = _LAZY.get(name)
+    if target is None:
+        raise AttributeError(f"module 'vqkit' has no attribute {name!r}")
+    import importlib
+    mod = importlib.import_module(target[0])
+    return getattr(mod, target[1])

vqkit/audio.py

@@ -0,0 +1,132 @@
+"""vqkit.audio — voiceover mux, music ducking, LUFS mastering, SRT generation.
+
+Council EARS#3: WHEN a scene declares a voiceover, system SHALL mux audio + generate
+SRT + ducked music, LUFS in [-16,-14]. All via ffmpeg (no external API).
+
+Pipeline:
+  voiceover.mp3 + [music.mp3] + video.mp4
+    -> sidechaincompress (duck music under VO) -> amix -> loudnorm (-14 LUFS) -> mux
+SRT: built from a list of (start, end, text) cues OR auto-timed from VO segment durations.
+"""
+from __future__ import annotations
+import json
+import subprocess
+from dataclasses import dataclass
+from pathlib import Path
+
+
+@dataclass
+class Cue:
+    start: float
+    end: float
+    text: str
+
+
+def measure_lufs(audio_or_video: str) -> float | None:
+    """Integrated LUFS via ffmpeg loudnorm print_format=json. None if no audio/parse fails.
+
+    Robust parse (review P2-A): ffmpeg logs more lines after the loudnorm JSON, so the naive
+    'last {...}' slice breaks on any trailing brace. We anchor on the loudnorm block by matching
+    a flat JSON object that contains "input_i". Distinguishes parse-fail from genuine no-audio
+    is best-effort; both return None but we log which."""
+    try:
+        proc = subprocess.run(
+            ["ffmpeg", "-i", str(audio_or_video), "-af",
+             "loudnorm=I=-14:TP=-1.5:LRA=11:print_format=json", "-f", "null", "-"],
+            capture_output=True, text=True, timeout=300)
+    except subprocess.TimeoutExpired:
+        return None
+    err = proc.stderr
+    import re
+    m = re.search(r'\{[^{}]*"input_i"[^{}]*\}', err)
+    if not m:
+        return None
+    try:
+        data = json.loads(m.group(0))
+        return float(data.get("input_i", 0.0))
+    except Exception:
+        return None
+
+
+def srt_from_cues(cues: list[Cue], out_path: str) -> str:
+    """Write a .srt subtitle file from cues. Returns the path."""
+    def ts(s: float) -> str:
+        h = int(s // 3600); m = int((s % 3600) // 60)
+        sec = s % 60
+        return f"{h:02d}:{m:02d}:{sec:06.3f}".replace(".", ",")
+    lines = []
+    for i, c in enumerate(cues, 1):
+        lines += [str(i), f"{ts(c.start)} --> {ts(c.end)}", c.text, ""]
+    Path(out_path).parent.mkdir(parents=True, exist_ok=True)
+    Path(out_path).write_text("\n".join(lines), encoding="utf-8")
+    return out_path
+
+
+def auto_cues_from_segments(segments: list[tuple[str, float]], gap: float = 0.15) -> list[Cue]:
+    """Build cues from [(text, duration)] segments laid end-to-end with a small gap."""
+    cues, t = [], 0.0
+    for text, dur in segments:
+        cues.append(Cue(t, t + dur, text))
+        t += dur + gap
+    return cues
+
+
+def mux(video: str, voiceover: str | None = None, music: str | None = None,
+        out_path: str = "out_audio.mp4", target_lufs: float = -14.0,
+        music_gain_db: float = -18.0, timeout: int = 300) -> str:
+    """Mux audio onto video. If both VO + music: duck music under VO via sidechaincompress,
+    mix, loudnorm to target_lufs. If only one source: loudnorm + mux. Returns out_path.
+
+    Deterministic: no model, pure ffmpeg. Never silently drops audio — raises on ffmpeg error.
+    """
+    Path(out_path).parent.mkdir(parents=True, exist_ok=True)
+    if not voiceover and not music:
+        raise ValueError("mux() needs at least a voiceover or music track")
+
+    if voiceover and music:
+        # [1]=VO [2]=music ; duck music by VO envelope, mix, normalize
+        fc = (
+            "[2:a]volume=" + str(music_gain_db) + "dB[mbed];"
+            "[mbed][1:a]sidechaincompress=threshold=0.05:ratio=8:attack=20:release=300[ducked];"
+            "[1:a][ducked]amix=inputs=2:duration=longest:dropout_transition=0[mix];"
+            f"[mix]loudnorm=I={target_lufs}:TP=-1.5:LRA=11[aout]"
+        )
+        cmd = ["ffmpeg", "-y", "-i", video, "-i", voiceover, "-i", music,
+               "-filter_complex", fc, "-map", "0:v", "-map", "[aout]",
+               "-c:v", "copy", "-c:a", "aac", "-b:a", "192k", "-shortest", out_path]
+    else:
+        track = voiceover or music
+        fc = f"[1:a]loudnorm=I={target_lufs}:TP=-1.5:LRA=11[aout]"
+        cmd = ["ffmpeg", "-y", "-i", video, "-i", track,
+               "-filter_complex", fc, "-map", "0:v", "-map", "[aout]",
+               "-c:v", "copy", "-c:a", "aac", "-b:a", "192k", "-shortest", out_path]
+
+    proc = subprocess.run(cmd, capture_output=True, text=True, timeout=timeout)
+    if proc.returncode != 0:
+        raise RuntimeError(f"audio mux failed (exit {proc.returncode}):\n{proc.stderr[-1200:]}")
+    if not Path(out_path).exists() or Path(out_path).stat().st_size == 0:
+        raise RuntimeError("audio mux produced no output")
+    return out_path
+
+
+def synth_voiceover(text: str, out_path: str, voice: str = "en-US-AriaNeural",
+                    timeout: int = 120) -> str:
+    """Synthesize narration with edge-TTS (free, no key, good quality). Returns path.
+    Falls back through edge -> gTTS if edge unavailable."""
+    Path(out_path).parent.mkdir(parents=True, exist_ok=True)
+    try:
+        import edge_tts, asyncio
+        async def _go():
+            await edge_tts.Communicate(text, voice).save(out_path)
+        asyncio.run(_go())
+        if Path(out_path).exists() and Path(out_path).stat().st_size > 0:
+            return out_path
+    except Exception:
+        pass
+    # fallback: gTTS
+    try:
+        from gtts import gTTS
+        gTTS(text=text, lang="en").save(out_path)
+        return out_path
+    except Exception as e:
+        raise RuntimeError(f"no TTS backend available: {e}")

vqkit/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)

vqkit/layout.py

@@ -0,0 +1,140 @@
+"""vqkit.layout — deterministic mobject-bbox layout assertions (L2 test layer).
+
+Council L2 (primary regression mechanism): at named checkpoints, snapshot
+{mobject: bbox, z, opacity} and assert geometric invariants — NO vision model.
+  - no mobject exceeds the safe frame
+  - no overlap between sibling mobjects that should be disjoint
+  - snapshot -> JSON for golden-diff regression (survives color/AA drift)
+"""
+from __future__ import annotations
+import json
+from dataclasses import dataclass, asdict
+from pathlib import Path
+
+
+# Manim default frame (config.frame_width/height); safe area = 92% (title/action safe)
+FRAME_W = 14.222222
+FRAME_H = 8.0
+SAFE_FRAC = 0.96  # mobjects must stay within 96% of frame (small bleed tolerance)
+
+
+@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_of(mobj) -> BBox:
+    """Bounding box of a manim mobject in scene coordinates (deterministic).
+    Raises ValueError on an empty mobject (review P1-2): an empty VGroup/VMobject collapses
+    to (0,0,0,0) at the origin, which would silently pass safe-frame/overlap checks. A layout
+    test wants that flagged, not waved through."""
+    if hasattr(mobj, "family_members_with_points") and not mobj.family_members_with_points():
+        raise ValueError("empty mobject has no bounding box (no points)")
+    left = mobj.get_left()[0]; right = mobj.get_right()[0]
+    bottom = mobj.get_bottom()[1]; top = mobj.get_top()[1]
+    return BBox(round(float(left), 3), round(float(bottom), 3),
+                round(float(right), 3), round(float(top), 3))
+
+
+def exceeds_safe_frame(bb: BBox, frac: float = SAFE_FRAC) -> bool:
+    """True if the bbox pokes outside the safe frame area."""
+    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
+
+
+def assert_within_frame(mobjects: dict, frac: float = SAFE_FRAC) -> list[str]:
+    """Return list of mobject-keys that breach the safe frame. Empty = pass."""
+    breaches = []
+    for key, mobj in mobjects.items():
+        try:
+            bb = bbox_of(mobj)
+        except ValueError as e:
+            breaches.append(f"{key}: {e}")   # empty mobject is a layout defect, flag it (P1-2)
+            continue
+        if exceeds_safe_frame(bb, frac):
+            breaches.append(f"{key} breaches safe-frame: bbox=({bb.x0},{bb.y0})-({bb.x1},{bb.y1})")
+    return breaches
+
+
+def assert_no_overlap(mobjects: dict, pad: float = 0.0,
+                      ignore_pairs: set | None = None) -> list[str]:
+    """Return list of overlapping sibling pairs that should be disjoint. Empty = pass."""
+    ignore_pairs = ignore_pairs or set()
+    keys = list(mobjects.keys())
+    overlaps = []
+    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 bbox_of(mobjects[ka]).overlaps(bbox_of(mobjects[kb]), pad):
+                overlaps.append(f"{ka} overlaps {kb}")
+    return overlaps
+
+
+def snapshot(mobjects: dict) -> dict:
+    """{key: {bbox, opacity}} snapshot for golden-diff regression.
+    An empty mobject records {bbox: None, error: ...} rather than crashing the snapshot (P1-2)."""
+    snap = {}
+    for key, mobj in mobjects.items():
+        try:
+            bb = bbox_of(mobj)
+            bbox_d = asdict(bb)
+        except ValueError as e:
+            snap[key] = {"bbox": None, "opacity": None, "error": str(e)}
+            continue
+        try:
+            op = float(getattr(mobj, "fill_opacity", None) or mobj.get_fill_opacity())
+        except Exception:
+            op = None
+        snap[key] = {"bbox": bbox_d, "opacity": op}
+    return snap
+
+
+def diff_snapshot(golden: dict, current: dict, pos_tol: float = 0.15,
+                  opacity_tol: float = 0.1) -> list[str]:
+    """Compare two snapshots; return drift lines. pos_tol in scene units, opacity_tol 0..1.
+    Compares opacity too (review P3-2) so an opacity regression — e.g. a winner that fails to
+    highlight, or losers that fail to dim (P1-1) — is caught, not just position drift."""
+    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})")
+        go, co = golden[k].get("opacity"), current[k].get("opacity")
+        if go is not None and co is not None and abs(go - co) > opacity_tol:
+            drift.append(f"DRIFT: {k}.opacity {go} -> {co} (>{opacity_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)

vqkit/phash.py

@@ -0,0 +1,84 @@
+"""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 lazy-imported (see vidkit_core/phash.py) so vqkit's manim-free parts import without it.
+def _require_pil():
+    try:
+        from PIL import Image
+        return Image
+    except ImportError as exc:
+        raise RuntimeError('phash needs Pillow: pip install pillow (or vidkit[manim])') from exc
+
+
+def _dhash(img, hash_size: int = 8) -> int:
+    """Difference hash (dHash). `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

vqkit/publish.py

@@ -0,0 +1,102 @@
+"""vqkit.publish — auto-publish-to-X lever. ARMED but DRY-RUN ONLY by default.
+
+HARD SAFETY BOUNDARY (operator constraint, SOUL §5, SPEC §6.2):
+This module NEVER sends a public post on its own. publish() defaults to dry_run=True and
+REQUIRES an explicit confirm token to actually send. Even with the token, sending is gated
+behind a function the agent will not call without explicit user "go". The build is complete
+and verifiable; firing is a human decision.
+
+Composes: a video bundle (from export.export_bundle) + caption + alt-text -> a ready-to-post
+payload. Verifies the media exists and is within X's limits. In dry-run, prints exactly what
+WOULD be posted. Real send path is stubbed with a refusal unless confirm == REQUIRED_TOKEN
+AND a real X credential is wired (neither is, by design).
+"""
+from __future__ import annotations
+import json
+import os
+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"
+
+
+@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 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 a wired
+    X credential. The credential is intentionally NOT wired here -> even a fully-authorized
+    call returns a structured 'blocked: no credential' rather than posting. This is the
+    armed-but-safe state: everything is built and validated; the human fires it elsewhere.
+    """
+    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
+    # Real send path — intentionally not wired. Requires X API credential the user must
+    # provide + an explicit go. We refuse rather than post autonomously.
+    cred = os.environ.get("VQKIT_X_BEARER")
+    if not cred:
+        plan["status"] = ("ARMED but BLOCKED — no X credential wired (VQKIT_X_BEARER unset). "
+                          "Posting is a human action; this module will not post autonomously.")
+        return plan
+    plan["status"] = ("REFUSED — autonomous public posting is disabled by design. "
+                      "Even with token+credential, a human must invoke the send path explicitly.")
+    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)