scribecast 0.1.0__py3-none-any.whl

scribecast/selector.py

@@ -0,0 +1,113 @@
+"""scribecast.selector — recommend a render engine from note context, but the USER always wins.
+
+The recommendation is a transparent heuristic (no hard LLM dependency): it scores the note text
+for math/formula/code density (-> manim), web/React/interaction language (-> remotion), and
+defaults to hyperframes (fast, clean HTML/CSS) otherwise. An optional LLM recommender can be
+plugged in later, but the heuristic is always available.
+
+USER-WINS CONTRACT (AC7): if the user supplies an explicit engine choice, choose() returns it
+unchanged — the recommendation is advisory only and never overrides an explicit choice.
+"""
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+
+from .logging_setup import get_logger
+_log = get_logger(__name__)
+
+ENGINES = ("hyperframes", "manim", "remotion")
+DEFAULT_ENGINE = "hyperframes"
+
+
+@dataclass
+class Recommendation:
+    engine: str
+    reason: str
+    scores: dict[str, int]
+
+
+# Signal patterns (case-insensitive, counted as weighted hits).
+# STRONG math signals only — bare prose words like "proof" or "graph" are too ambiguous and
+# caused false manim recommendations on plain notes. Require LaTeX/symbols/explicit math terms.
+_MATH = re.compile(
+    r"(\\frac|\\sum|\\int|\\sqrt|\\alpha|\\beta|\\theta|\$\$|"
+    r"\b(eigenvalue|eigenvector|derivative|integral|theorem|matrix multiplication|"
+    r"big-?o notation|time complexity|gradient descent|linear algebra|calculus)\b)", re.I)
+# code fences / clear code constructs (not bare punctuation that prose also uses)
+_CODE = re.compile(r"```|\bdef \w+\(|\bclass \w+[:(]|\bfunction \w+\(|=>\s|\bimport \w+", re.M)
+_WEB = re.compile(
+    r"\b(react|component|usestate|useeffect|tailwind|css animation|transition|"
+    r"parallax|landing page|web app|frontend|scroll-?triggered)\b", re.I)
+
+
+def recommend_engine(text: str) -> Recommendation:
+    """Heuristic engine recommendation from note text. Always returns one of ENGINES."""
+    t = text or ""
+    math_hits = len(_MATH.findall(t)) + len(_CODE.findall(t))
+    web_hits = len(_WEB.findall(t))
+
+    scores = {
+        "manim": math_hits,
+        "remotion": web_hits,
+        "hyperframes": 1,  # baseline bias toward the fast clean default
+    }
+
+    # Decide: strongest signal wins; ties / no-signal -> default.
+    if math_hits >= 2 and math_hits >= web_hits:
+        return Recommendation(
+            "manim", f"math/algorithm/formula density is high ({math_hits} signals) — "
+                     f"Manim renders equations & step-by-step motion best.", scores)
+    if web_hits >= 2 and web_hits > math_hits:
+        return Recommendation(
+            "remotion", f"web/React/interaction language detected ({web_hits} signals) — "
+                        f"Remotion suits component-driven motion.", scores)
+    return Recommendation(
+        DEFAULT_ENGINE, "no strong math or web signal — HyperFrames (fast, clean HTML/CSS) "
+                        "is the sensible default for general notes.", scores)
+
+
+def choose(text: str, user_choice: str | None = None) -> tuple[str, Recommendation]:
+    """Return (engine, recommendation). USER-WINS: an explicit user_choice is returned as the
+    engine even if it differs from the recommendation; the recommendation is still computed and
+    returned (advisory/transparency)."""
+    rec = recommend_engine(text)
+    if user_choice:
+        uc = user_choice.strip().lower()
+        if uc not in ENGINES:
+            raise ValueError(f"unknown engine '{user_choice}'. Choose one of: {', '.join(ENGINES)}")
+        return uc, rec      # user choice wins, recommendation kept for transparency
+    return rec.engine, rec
+
+
+def resolve_engine(text: str, user_choice: str | None = None,
+                   config_engine: str | None = None) -> tuple[str, Recommendation]:
+    """THE single engine-selection contract. Precedence (first that applies):
+
+        1. explicit user_choice  (CLI --engine / lib arg)          — user always wins
+        2. config_engine         (config file / env) IF the user set it to a non-default value
+        3. heuristic recommendation from the note text
+
+    Returns (engine, recommendation). The recommendation is ALWAYS computed and returned for
+    transparency, regardless of which layer won. This is the ONLY place precedence lives —
+    callers (pipeline, cli, mcp) must not re-implement it.
+
+    `config_engine` is treated as "set by the user" only when it differs from the built-in default
+    ("hyperframes"); a config still on the default defers to the recommendation so a math note
+    auto-routes to manim unless the user explicitly pinned an engine.
+    """
+    rec = recommend_engine(text)
+    # 1. explicit user choice wins
+    if user_choice:
+        uc = user_choice.strip().lower()
+        if uc not in ENGINES:
+            raise ValueError(f"unknown engine '{user_choice}'. Choose one of: {', '.join(ENGINES)}")
+        return uc, rec
+    # 2. config engine, only if the user moved it off the default
+    if config_engine and config_engine.strip().lower() != DEFAULT_ENGINE:
+        ce = config_engine.strip().lower()
+        if ce not in ENGINES:
+            raise ValueError(f"unknown engine '{config_engine}'. Choose one of: {', '.join(ENGINES)}")
+        return ce, rec
+    # 3. heuristic recommendation
+    return rec.engine, rec

scribecast-0.1.0.dist-info/METADATA

@@ -0,0 +1,155 @@
+Metadata-Version: 2.4
+Name: scribecast
+Version: 0.1.0
+Summary: Turn any note into a narrated video. scribecast façade + vidkit engine (HyperFrames / Manim / Remotion), edge-tts narration, ffmpeg mux. CLI + library + MCP server.
+Author: Prax
+License: MIT
+Project-URL: Homepage, https://github.com/praxstack/vidkit
+Project-URL: Repository, https://github.com/praxstack/vidkit
+Project-URL: Issues, https://github.com/praxstack/vidkit/issues
+Keywords: video,notes,narration,edge-tts,manim,remotion,hyperframes,ffmpeg,mcp,obsidian
+Classifier: Development Status :: 3 - Alpha
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Topic :: Multimedia :: Video
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Provides-Extra: narrate
+Requires-Dist: edge-tts>=6.1; extra == "narrate"
+Provides-Extra: manim
+Requires-Dist: manim>=0.18; extra == "manim"
+Requires-Dist: numpy>=1.24; extra == "manim"
+Requires-Dist: pillow>=10.0; extra == "manim"
+Provides-Extra: all
+Requires-Dist: edge-tts>=6.1; extra == "all"
+Requires-Dist: manim>=0.18; extra == "all"
+Requires-Dist: numpy>=1.24; extra == "all"
+Requires-Dist: pillow>=10.0; extra == "all"
+Provides-Extra: test
+Requires-Dist: pytest>=7; extra == "test"
+Requires-Dist: pytest-xdist>=3; extra == "test"
+Requires-Dist: coverage>=7; extra == "test"
+
+# scribecast
+
+Turn any note — from gbrain, PraxVault, ksum, a file, stdin, or several **merged** — into a
+**narrated video**. scribecast is the façade; **vidkit** is the engine. Both ship in ONE
+pip-installable, delete-proof wheel (this repo).
+
+```
+note ref ──► resolver ──► script (cards) ──► render (engine) ──► narrate (edge-tts) ──► mux ──► mp4
+             gbrain/vault/                    hyperframes/                              (vidkit, video
+             ksum/file/stdin/merge            manim/remotion                            duration authoritative)
+```
+
+scribecast **imports vidkit** (`from vidkit_core import ...`) — it never shells out to a vendored
+copy. Note sources are read by calling the existing local CLIs (gbrain/ksum/praxvault-ask) as
+subprocess *for note resolution only*.
+
+## Install (delete-proof wheel — NOT editable)
+```bash
+pip install .                 # ships vidkit_core + vqkit + scribecast in one wheel
+pip install .[narrate]        # + edge-tts narration
+pip install .[manim]          # + manim engine (heavy, opt-in)
+pip install .[all]            # narrate + manim
+pip install .[test]           # pytest + pytest-xdist + coverage (for the test suite)
+```
+After install you can delete this source dir — the `scribecast` and `vidkit` CLIs keep working
+(verified by the delete-proof scenario; see `scenarios/run_scenarios.py::s10_delete_proof`).
+The Remotion engine additionally needs Node.js + the `remotion_kit` (with `npm install` run).
+
+## Use — three interfaces, one core
+
+**CLI (humans, Raycast, scripts):**
+```bash
+scribecast render file:notes.md -o out.mp4              # render a file note
+scribecast render gbrain:two-brain-architecture          # render a gbrain page
+scribecast render file:a.md --merge file:b.md file:c.md  # merge notes into one video
+scribecast render file:n.md --engine manim --voice en-GB-RyanNeural
+scribecast render file:n.md --engine remotion            # 1080p React/Remotion engine
+scribecast recommend file:n.md       # advisory engine pick (user always decides)
+scribecast sources                   # list note sources + availability
+scribecast config                    # effective config + where each value came from
+scribecast -v render file:n.md       # -v = INFO logs, -vv = DEBUG (to stderr)
+```
+
+**Library (Python):**
+```python
+from scribecast import render_note, resolve, recommend_engine
+res = render_note("file:notes.md", out="out.mp4")        # -> RenderResult(output, engine, duration, ...)
+text = resolve(["gbrain:slug-a", "file:b.md"])           # merge
+rec  = recommend_engine(text)                            # advisory
+```
+
+**MCP (any agent — Claude/Hermes/Cursor/workers):**
+```bash
+python -m scribecast.mcp        # stdio JSON-RPC: render_note_video, recommend_engine, list_sources, list_voices
+```
+Zero mcp-sdk dependency (minimal stdio JSON-RPC) so it installs with the base wheel. Logs go to
+stderr (stdout is the JSON-RPC transport).
+
+**Obsidian plugin** (`obsidian-plugin/`): render the *current note* from inside Obsidian. It is a
+thin consumer of the installed `scribecast` CLI (no vendoring). Commands: "Render active note to
+video", "Recommend engine for active note"; settings for binary path / engine / voice / output dir.
+Build: `cd obsidian-plugin && npm install && npm run build`, then copy `manifest.json` + `main.js`
+into `<vault>/.obsidian/plugins/scribecast/`.
+
+## Logging
+The package uses the stdlib `logging` framework with library-correct discipline: importing
+scribecast is silent (a `NullHandler` is attached), so it never pollutes a host application's
+output. Logging is enabled by the entry points:
+- CLI: `-v` (INFO) / `-vv` (DEBUG) — records go to stderr.
+- MCP: always configured to stderr on server start.
+- env: `SCRIBECAST_LOG_LEVEL=DEBUG|INFO|WARNING|ERROR`.
+Every important path logs: note resolution (+ subprocess run/timeout/failure), engine selection,
+each render stage (script → render → narrate → mux → probe → done), and MCP tool dispatch + errors.
+
+## Configurable (flag > env > config-file > default)
+- config file: `$SCRIBECAST_CONFIG` or `~/.scribecast/config.toml`
+- env: `SCRIBECAST_ENGINE`, `SCRIBECAST_VOICE`, `SCRIBECAST_SOURCE`, `SCRIBECAST_OUT_DIR`, ...
+- flags: `--engine --voice --source -o ...`
+- `scribecast config` shows the effective value AND which layer set it.
+
+## Engine selection — recommend, never decide
+The selector RECOMMENDS one of `hyperframes | manim | remotion` from note content (math/LaTeX →
+manim, web/React → remotion, else hyperframes). **The user's explicit `--engine` always wins** —
+the recommendation is advisory and is always shown for transparency. (Heuristic today; an LLM
+recommender can be added without changing the user-wins contract.)
+
+## Default engine: `hyperframes` (cards)
+The default renderer builds titled text cards with Pillow → an ffmpeg image-sequence mp4 → narration
+→ mux. Needs only Pillow + ffmpeg (no browser, no Manim). All three engines work:
+- **hyperframes** (default, dep-light): Pillow text-cards → ffmpeg, 1280×720.
+- **manim** (opt-in `[manim]`): cinematic via `vqkit.CinematicScene` (MovingCameraScene + MathTex), 1280×720. Math/LaTeX spans render as real equations; prose renders as Text.
+- **remotion** (opt-in): React/Remotion `ScribecastCards` composition (spring entrances, gradient), 1920×1080. Needs Node + `remotion_kit`. License-gated for orgs > 3 (Remotion License v1).
+
+A forced `--engine` that lacks its dependency raises a clear error — never a silent fallback.
+
+## Sources
+| source | how | tool |
+|---|---|---|
+| `file` | read a local path | — |
+| `stdin` | piped text | — |
+| `gbrain` | `gbrain get <slug>` | gbrain |
+| `vault` | `praxvault-ask <query>` | praxvault-ask |
+| `ksum` | `ksum <url\|file> --no-save` | ksum |
+| `openmemory` | `openmemory get <id>` | openmemory (optional) |
+| `merge` | multiple refs → one video | — |
+
+A missing source tool raises a clear `ResolverError` (never silent-empty).
+
+## Tests
+```bash
+pytest -q                     # 126 fast unit tests in ~1s (real-render tests deselected)
+pytest -q --run-slow          # full 163 tests incl. real manim/remotion/ffmpeg renders
+pytest -q --run-slow -n auto  # full set in parallel (pytest-xdist)
+coverage run --source=scribecast -m pytest --run-slow && coverage report   # 100% (692/692)
+python scenarios/run_scenarios.py   # 10 realistic end-to-end scenarios (pass/fail + evidence)
+python scenarios/benchmark.py       # per-engine timing baseline -> scenarios/baseline.json
+```
+Real-render tests are auto-marked `slow` (see `tests/conftest.py`) and deselected by default for a
+fast dev loop; `--run-slow` runs them and the coverage gate enforces 100%. The mux-truncation
+regression test (`tests/test_mux_no_truncation.py`) proves a short narration never truncates a
+longer video — the bug this project fixed.

scribecast-0.1.0.dist-info/RECORD

@@ -0,0 +1,35 @@
+scribecast/__init__.py,sha256=NBmab9p5cl5TOVqToTvrP2gQPu9LSUX2zR6V5PWbWw0,1340
+scribecast/cli.py,sha256=dFCv_uNXqfVbe-sqsL5OGN4TPUAGiYGmtmSha16vf_Y,5723
+scribecast/config.py,sha256=jVxTJgE209zPm5iUGQhW29HJPi5-8Pp8RaL_5h2sT1g,5358
+scribecast/logging_setup.py,sha256=_fNxXdocoohe3HbC8w3Y4B447z9ua_nc11gseOthA7g,2066
+scribecast/mcp.py,sha256=mAE-ZvCaENQG_WOZpRcB0bQ6XrxzPP8r0yaLptYEn-o,8223
+scribecast/pipeline.py,sha256=bQiil6x4ie35sWNk9VUqa_uonoCF-63zP4PF87eVYnw,12341
+scribecast/resolver.py,sha256=543PNgPW-mCa-ruJwRoboE8NfFJ2XmGQuqWGwUEGlTU,6318
+scribecast/selector.py,sha256=T9HhTQbjzMfHf0MGJl3C55AMHFkNxj84vY0X43lJpLk,5314
+scribecast/engines/__init__.py,sha256=vyg9-ZIHcYY0im-5kPRieR3hGshTzqL5Lx3gS8y45Dk,889
+scribecast/engines/manim_adapter.py,sha256=IzJCCIu7c1aAceWShfMc-d6_QRYSFINvAYT8lVsQYhY,7534
+scribecast/engines/remotion_adapter.py,sha256=-ymCUADbdeZDnIay1bUBwZ4B4Hs2PsyU7tPZvtazRzQ,5172
+vidkit_core/__init__.py,sha256=XIROT81G1REXWdVEz-4Syc-GlvPVlqdh2bnxBZ3O1RY,1129
+vidkit_core/audio.py,sha256=pEd8Hb8w_TfDCalI1T1bKIgh-PAD2_kENQ9ql5pz9k4,6122
+vidkit_core/cli.py,sha256=IxLXj7E4BWunOBkfimxfW6J3sB2xz6O1T-JBEo1yT5g,4364
+vidkit_core/export.py,sha256=0xzVa5I85bjY2CSsMU07VzZ6J0PvDxSP42teR3Iubs4,5215
+vidkit_core/layout.py,sha256=SY21SkCyppejcm3gjQOCDDp9dUVvY6FQAh-r9j6lf_M,4431
+vidkit_core/phash.py,sha256=GHWf8kkMoK15A0W4YYVcwlu8d3Oh-o5dnMH_q7J1t-g,3322
+vidkit_core/publish.py,sha256=ThHs5QDY-iXCy-0eeXdyWwCHXGNDYBgp5mH9Z7z05Y0,8238
+vidkit_core/render.py,sha256=ZrAiZvQLzOdksD8AZJJ7gexLysT6qdsYnwkWvcFxRW8,2765
+vidkit_core/theme.py,sha256=lipZa8HANFqHYdNLtFxjFYxqsBr3qLWhQpdqE4wjBg0,2567
+vqkit/__init__.py,sha256=Is_I4bwmTTv6EmngzEMxzOEYASMFqmtLaKyhCz0OrCs,1566
+vqkit/audio.py,sha256=uO1A0bh6jXG_XgZmvw0a6aD5H7Qev6TYy_hXjxFTkow,5478
+vqkit/export.py,sha256=0xzVa5I85bjY2CSsMU07VzZ6J0PvDxSP42teR3Iubs4,5215
+vqkit/layout.py,sha256=oNNdu10sCzloP6y02HYGbKt9MxRKsbhK7BXEh_n39Wk,5639
+vqkit/phash.py,sha256=SfGEHmxwUW5HScO49CT-2zqwZJY9u-GTkzR4nqMhGlg,3045
+vqkit/publish.py,sha256=Hy6u2Rsz0T0AY3It-vytY5WEmdFpAyeTKzXCumi5eVA,4432
+vqkit/render.py,sha256=Z5onsHMrGawWCaFXZnDNANmqBHjfOlDkISxdptfUQJc,4088
+vqkit/scene.py,sha256=JGSPrRwkN8typoSoBY4xMHFPkesW55mAEpUTNLdqL9A,9160
+vqkit/scene3d.py,sha256=XbrsqRyYuz9s6qLuJ__2rZS97F9_kzpVaMCEjUWOwtk,4590
+vqkit/theme.py,sha256=lipZa8HANFqHYdNLtFxjFYxqsBr3qLWhQpdqE4wjBg0,2567
+scribecast-0.1.0.dist-info/METADATA,sha256=5WIWhvg79ZvCQy3YsY-PVPyUAvekvhIhHg0UtWbY-xM,8360
+scribecast-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+scribecast-0.1.0.dist-info/entry_points.txt,sha256=glpXY-W-pv0AqB2NkMc3Ke4CFkhLT84IqtjRQQ5egHM,81
+scribecast-0.1.0.dist-info/top_level.txt,sha256=wKAj-1TNYmw2Th4WdOedt9Fz0NecF7mXXbTLqwS6yoY,29
+scribecast-0.1.0.dist-info/RECORD,,

scribecast-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

scribecast-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+scribecast = scribecast.cli:main
+vidkit = vidkit_core.cli:main

scribecast-0.1.0.dist-info/top_level.txt

@@ -0,0 +1,3 @@
+scribecast
+vidkit_core
+vqkit

vidkit_core/__init__.py

@@ -0,0 +1,21 @@
+"""vidkit_core — renderer-agnostic video toolkit core.
+
+Shared across Manim (vqkit), Remotion (remotion_kit), and HyperFrames (hyperframes_kit).
+Everything here operates on an OUTPUT MP4 + ffprobe + ffmpeg — zero renderer dependency.
+Council-locked 2026-06-15 (extract-by-addition; the seam was empirically proven).
+
+Modules:
+  render  — Probe + ffprobe (mp4 introspection) + render_cli (generic CLI driver)
+  audio   — synth_voiceover, mux (VO+music-duck+LUFS), srt_from_cues, measure_lufs
+  export  — reframe (16:9/9:16/1:1), gif, thumbnail, export_bundle->manifest(sha256)
+  phash   — dHash keyframe perceptual-hash regression (L4)
+  layout  — BBox geometry + bbox_from_dom_rect + diff_snapshot (L2 math, renderer feeds boxes)
+  publish — armed-but-inert social lever (never posts autonomously)
+  theme   — design tokens (palette/type/timing)
+"""
+from . import render, audio, export, phash, layout, publish, theme
+from .render import Probe, ffprobe, render_cli
+
+__version__ = "0.1.0"
+__all__ = ["render", "audio", "export", "phash", "layout", "publish", "theme",
+           "Probe", "ffprobe", "render_cli"]

vidkit_core/audio.py

@@ -0,0 +1,139 @@
+"""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.
+        # apad pads the mixed audio with silence so it is never SHORTER than the video;
+        # -shortest then trims the (now longer-or-equal) audio back to the video length.
+        # Without apad, a short VO + bare -shortest would truncate the VIDEO to the audio
+        # length (the 78.7s->23s narration-truncation bug). Video duration is authoritative.
+        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,apad[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
+        # apad pads audio with trailing silence to >= video length; -shortest trims it back
+        # to exactly the video length. This guarantees the OUTPUT keeps the full video and is
+        # never truncated to a shorter narration track (the -shortest truncation bug).
+        fc = f"[1:a]loudnorm=I={target_lufs}:TP=-1.5:LRA=11,apad[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}")

vidkit_core/cli.py

@@ -0,0 +1,133 @@
+"""vidkit CLI — one installed binary for the renderer-agnostic video toolkit.
+
+Exposes the vidkit_core operations so consumers call ONE installed `vidkit` command
+instead of vendoring/shelling a copy. Subcommands:
+  probe      ffprobe an mp4 (duration, dims, fps, has_audio)
+  narrate    synth_voiceover via edge-tts (needs `pip install vidkit[narrate]`)
+  mux        mux voiceover/music onto a video (the apad/-shortest-fixed path)
+  reframe    reframe to 16:9 / 9:16 / 1:1
+  gif        master mp4 -> gif
+  thumbnail  grab a thumbnail frame
+  version    print vidkit version
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+
+
+def _probe(args: argparse.Namespace) -> int:
+    from vidkit_core.render import ffprobe
+    p = ffprobe(args.path)
+    out = {
+        "path": args.path,
+        "duration": getattr(p, "duration", None),
+        "width": getattr(p, "width", None),
+        "height": getattr(p, "height", None),
+        "fps": getattr(p, "fps", None),
+        "has_audio": getattr(p, "has_audio", None),
+    }
+    print(json.dumps(out, indent=2))
+    return 0
+
+
+def _narrate(args: argparse.Namespace) -> int:
+    from vidkit_core.audio import synth_voiceover
+    out = synth_voiceover(args.text, args.out, voice=args.voice)
+    print(out)
+    return 0
+
+
+def _mux(args: argparse.Namespace) -> int:
+    from vidkit_core.audio import mux
+    out = mux(args.video, voiceover=args.voiceover, music=args.music, out_path=args.out)
+    print(out)
+    return 0
+
+
+def _reframe(args: argparse.Namespace) -> int:
+    from vidkit_core.export import reframe
+    out = reframe(args.master, args.aspect, args.out, mode=args.mode)
+    print(out)
+    return 0
+
+
+def _gif(args: argparse.Namespace) -> int:
+    from vidkit_core.export import gif
+    out = gif(args.master, args.out, fps=args.fps, width=args.width)
+    print(out)
+    return 0
+
+
+def _thumbnail(args: argparse.Namespace) -> int:
+    from vidkit_core.export import thumbnail
+    out = thumbnail(args.master, args.out, at=args.at)
+    print(out)
+    return 0
+
+
+def _version(_args: argparse.Namespace) -> int:
+    from vidkit_core import __version__
+    print(__version__)
+    return 0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(prog="vidkit", description="Renderer-agnostic video toolkit.")
+    sub = p.add_subparsers(dest="cmd", required=True)
+
+    sp = sub.add_parser("probe", help="ffprobe an mp4")
+    sp.add_argument("path")
+    sp.set_defaults(func=_probe)
+
+    sn = sub.add_parser("narrate", help="synth voiceover (edge-tts; needs vidkit[narrate])")
+    sn.add_argument("text")
+    sn.add_argument("-o", "--out", default="voiceover.mp3")
+    sn.add_argument("--voice", default="en-US-AriaNeural")
+    sn.set_defaults(func=_narrate)
+
+    sm = sub.add_parser("mux", help="mux voiceover/music onto a video (video duration authoritative)")
+    sm.add_argument("video")
+    sm.add_argument("--voiceover")
+    sm.add_argument("--music")
+    sm.add_argument("-o", "--out", default="out_audio.mp4")
+    sm.set_defaults(func=_mux)
+
+    sr = sub.add_parser("reframe", help="reframe to 16:9 / 9:16 / 1:1")
+    sr.add_argument("master")
+    sr.add_argument("aspect", choices=["16:9", "9:16", "1:1"])
+    sr.add_argument("-o", "--out", default="reframed.mp4")
+    sr.add_argument("--mode", default="pad", choices=["pad", "crop"])
+    sr.set_defaults(func=_reframe)
+
+    sg = sub.add_parser("gif", help="master mp4 -> gif")
+    sg.add_argument("master")
+    sg.add_argument("-o", "--out", default="out.gif")
+    sg.add_argument("--fps", type=int, default=12)
+    sg.add_argument("--width", type=int, default=640)
+    sg.set_defaults(func=_gif)
+
+    st = sub.add_parser("thumbnail", help="grab a thumbnail frame")
+    st.add_argument("master")
+    st.add_argument("-o", "--out", default="thumb.png")
+    st.add_argument("--at", type=float, default=1.0)
+    st.set_defaults(func=_thumbnail)
+
+    sv = sub.add_parser("version", help="print vidkit version")
+    sv.set_defaults(func=_version)
+
+    return p
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    try:
+        return args.func(args)
+    except Exception as exc:  # surface real errors, non-zero exit
+        print(f"vidkit: {type(exc).__name__}: {exc}", file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())