scribecast 0.1.0__py3-none-any.whl

scribecast/__init__.py

@@ -0,0 +1,32 @@
+"""scribecast — turn any note (from gbrain, PraxVault, ksum, a file, stdin, or several merged)
+into a narrated video, using vidkit as the render+narration engine.
+
+Three interfaces over ONE importable core:
+  - library:  from scribecast import render_note, resolve, recommend_engine
+  - CLI:      scribecast render <ref> [--engine ...] [--voice ...] [-o out.mp4]
+  - MCP:      python -m scribecast.mcp   (stdio JSON-RPC: render_note_video, list_voices, ...)
+
+scribecast IMPORTS vidkit (vidkit_core) — it never shells out to a vendored copy. Note SOURCES
+are resolved by calling the existing local CLIs (gbrain/ksum/praxvault-ask) as subprocess for
+READING note text only; that is resolution, not the shell-glue-engine anti-pattern.
+"""
+__version__ = "0.1.0"
+
+from .config import Config, load_config
+from .resolver import resolve, ResolverError
+from .selector import recommend_engine, ENGINES
+
+__all__ = [
+    "__version__",
+    "Config", "load_config",
+    "resolve", "ResolverError",
+    "recommend_engine", "ENGINES",
+    "render_note",
+]
+
+
+def render_note(*args, **kwargs):
+    """Lazy proxy to scribecast.pipeline.render_note (keeps `import scribecast` light —
+    the pipeline imports vidkit which pulls ffmpeg-dependent modules)."""
+    from .pipeline import render_note as _render_note
+    return _render_note(*args, **kwargs)

scribecast/cli.py

@@ -0,0 +1,145 @@
+"""scribecast CLI — one binary for humans, Raycast, scripts.
+
+  scribecast render <ref> [--source S] [--engine E] [--voice V] [-o out.mp4] [--no-narrate]
+  scribecast resolve <ref> [--source S]            # print resolved note text
+  scribecast recommend <ref> [--source S]          # show engine recommendation (advisory)
+  scribecast sources                               # list note sources + availability
+  scribecast voices                                # list a few common edge-tts voices
+  scribecast config                                # show effective config + provenance
+  scribecast version
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+
+from . import __version__
+from .config import load_config
+from .resolver import resolve, list_sources, ResolverError
+from .selector import choose, ENGINES
+
+
+def _render(a: argparse.Namespace) -> int:
+    from .pipeline import render_note, PipelineError
+    ref = a.ref if not a.merge else [a.ref, *a.merge]
+    try:
+        res = render_note(
+            ref, source=a.source, engine=a.engine, voice=a.voice, out=a.out,
+            narrate=not a.no_narrate, seconds_per_card=a.seconds_per_card,
+        )
+    except (PipelineError, ResolverError) as exc:
+        print(f"scribecast: {type(exc).__name__}: {exc}", file=sys.stderr)
+        return 1
+    print(json.dumps({
+        "output": res.output, "engine": res.engine, "recommended": res.recommendation.engine,
+        "cards": res.cards, "narrated": res.narrated, "duration": res.duration,
+        "notes": res.notes,
+    }, indent=2))
+    return 0
+
+
+def _resolve_cmd(a: argparse.Namespace) -> int:
+    try:
+        ref = a.ref if not a.merge else [a.ref, *a.merge]
+        print(resolve(ref, source=a.source or "file"))
+    except ResolverError as exc:
+        print(f"scribecast: {exc}", file=sys.stderr)
+        return 1
+    return 0
+
+
+def _recommend(a: argparse.Namespace) -> int:
+    try:
+        text = resolve(a.ref, source=a.source or "file")
+    except ResolverError as exc:
+        print(f"scribecast: {exc}", file=sys.stderr)
+        return 1
+    eng, rec = choose(text, user_choice=a.engine)
+    print(json.dumps({
+        "chosen": eng, "recommended": rec.engine, "reason": rec.reason,
+        "scores": rec.scores, "user_override": bool(a.engine),
+    }, indent=2))
+    return 0
+
+
+def _sources(_a: argparse.Namespace) -> int:
+    print(json.dumps(list_sources(), indent=2))
+    return 0
+
+
+def _voices(_a: argparse.Namespace) -> int:
+    common = [
+        "en-US-AriaNeural", "en-US-GuyNeural", "en-GB-RyanNeural", "en-GB-SoniaNeural",
+        "en-IN-NeerjaNeural", "en-IN-PrabhatNeural", "en-AU-NatashaNeural",
+    ]
+    print(json.dumps({"voices": common, "note": "any edge-tts voice id works; "
+                      "run `edge-tts --list-voices` for the full list"}, indent=2))
+    return 0
+
+
+def _config_cmd(_a: argparse.Namespace) -> int:
+    cfg = load_config()
+    print(json.dumps({"config": {k: getattr(cfg, k) for k in
+                                 ("engine", "voice", "source", "out_dir", "aspect", "music")},
+                      "origin": cfg.explain()}, indent=2))
+    return 0
+
+
+def _version(_a: argparse.Namespace) -> int:
+    print(__version__)
+    return 0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(prog="scribecast",
+                                description="Turn any note into a narrated video.")
+    sub = p.add_subparsers(dest="cmd", required=True)
+
+    r = sub.add_parser("render", help="render a note to a narrated video")
+    r.add_argument("ref", help="source:locator or locator (e.g. file:notes.md, gbrain:my-slug)")
+    r.add_argument("--merge", nargs="*", help="additional refs to merge into one video")
+    r.add_argument("--source", help="default source when ref has no prefix")
+    r.add_argument("--engine", choices=ENGINES, help="force engine (user-wins over recommendation)")
+    r.add_argument("--voice", help="edge-tts voice id")
+    r.add_argument("-o", "--out", help="output mp4 path")
+    r.add_argument("--no-narrate", action="store_true", help="skip narration (silent video)")
+    r.add_argument("--seconds-per-card", type=float, default=3.0)
+    r.set_defaults(func=_render)
+
+    rs = sub.add_parser("resolve", help="print resolved note text")
+    rs.add_argument("ref")
+    rs.add_argument("--merge", nargs="*")
+    rs.add_argument("--source")
+    rs.set_defaults(func=_resolve_cmd)
+
+    rc = sub.add_parser("recommend", help="show engine recommendation (advisory)")
+    rc.add_argument("ref")
+    rc.add_argument("--source")
+    rc.add_argument("--engine", choices=ENGINES, help="simulate a user override")
+    rc.set_defaults(func=_recommend)
+
+    sub.add_parser("sources", help="list note sources + availability").set_defaults(func=_sources)
+    sub.add_parser("voices", help="list common edge-tts voices").set_defaults(func=_voices)
+    sub.add_parser("config", help="show effective config + provenance").set_defaults(func=_config_cmd)
+    sub.add_parser("version", help="print version").set_defaults(func=_version)
+    p.add_argument("-v", "--verbose", action="count", default=0,
+                   help="-v for INFO logs, -vv for DEBUG (logs go to stderr)")
+    return p
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    from .logging_setup import configure_logging
+    level = {0: None, 1: "INFO"}.get(args.verbose, "DEBUG")
+    if level is not None:
+        configure_logging(level)
+    try:
+        return args.func(args)
+    except Exception as exc:
+        print(f"scribecast: {type(exc).__name__}: {exc}", file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":  # pragma: no cover
+    raise SystemExit(main())

scribecast/config.py

@@ -0,0 +1,140 @@
+"""scribecast.config — layered configuration.
+
+Precedence (highest wins): explicit flag/kwarg  >  $SCRIBECAST_* env  >  config file  >  default.
+
+Config file: $SCRIBECAST_CONFIG, else ~/.scribecast/config.toml. Parsed read-only (tomllib,
+stdlib on 3.11+; falls back to a tiny parser on 3.10). Missing file = all defaults.
+"""
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field, fields
+from pathlib import Path
+from typing import Any, Mapping
+
+# ---- defaults -------------------------------------------------------------
+_DEFAULTS: dict[str, Any] = {
+    "engine": "hyperframes",          # default render engine
+    "voice": "en-US-AriaNeural",      # default edge-tts voice
+    "source": "file",                 # default resolver source
+    "out_dir": "scribecast-out",      # default output directory
+    "aspect": "16:9",                 # default aspect ratio
+    "music": "",                      # optional background music path
+}
+
+_ENV_PREFIX = "SCRIBECAST_"
+
+
+def _config_path() -> Path:
+    override = os.environ.get("SCRIBECAST_CONFIG")
+    if override:
+        return Path(override).expanduser()
+    return Path.home() / ".scribecast" / "config.toml"
+
+
+def _read_toml(path: Path) -> dict[str, Any]:
+    if not path.is_file():
+        return {}
+    data = path.read_bytes()
+    try:
+        try:
+            import tomllib  # py3.11+
+            return tomllib.loads(data.decode("utf-8"))
+        except ModuleNotFoundError:
+            try:  # pragma: no cover - py3.10 only (3.11+ has tomllib)
+                import tomli  # type: ignore
+                return tomli.loads(data.decode("utf-8"))
+            except ModuleNotFoundError:  # pragma: no cover
+                return _mini_toml(data.decode("utf-8"))
+    except (UnicodeDecodeError, ValueError) as exc:
+        # Malformed config must NOT crash every command — warn to stderr, fall back to defaults.
+        # (tomllib.TOMLDecodeError subclasses ValueError, so this catches it without importing it.)
+        import sys
+        print(f"scribecast: ignoring malformed config at {path}: {exc}", file=sys.stderr)
+        return {}
+
+
+def _mini_toml(text: str) -> dict[str, Any]:
+    """Tiny flat key=value TOML reader (py3.10 fallback; only needs flat string/bool values).
+    Strips inline `#` comments outside quotes; skips [section] headers (flat namespace only)."""
+    out: dict[str, Any] = {}
+    for raw in text.splitlines():
+        line = raw.strip()
+        if not line or line.startswith("#") or line.startswith("["):
+            continue
+        if "=" not in line:
+            continue
+        k, _, v = line.partition("=")
+        k = k.strip()
+        v = v.strip()
+        if v[:1] in ("'", '"'):
+            # quoted value: take through the matching closing quote, ignore any trailing comment
+            q = v[0]
+            end = v.find(q, 1)
+            v = v[1:end] if end > 0 else v[1:]
+        else:
+            # bare value: strip an inline comment
+            v = v.split("#", 1)[0].strip()
+        if v.lower() in ("true", "false"):
+            out[k] = v.lower() == "true"
+        else:
+            out[k] = v
+    return out
+
+
+@dataclass
+class Config:
+    engine: str = _DEFAULTS["engine"]
+    voice: str = _DEFAULTS["voice"]
+    source: str = _DEFAULTS["source"]
+    out_dir: str = _DEFAULTS["out_dir"]
+    aspect: str = _DEFAULTS["aspect"]
+    music: str = _DEFAULTS["music"]
+    # provenance: which layer set each field (for --explain / debugging)
+    _origin: dict[str, str] = field(default_factory=dict, repr=False)
+
+    def explain(self) -> dict[str, str]:
+        """Return {field: layer} showing where each value came from."""
+        return dict(self._origin)
+
+
+def load_config(overrides: dict[str, Any] | None = None,
+                config_path: str | os.PathLike | None = None,
+                env: "Mapping[str, str] | None" = None) -> Config:
+    """Build a Config honoring precedence flag/kwarg > env > file > default.
+
+    overrides: explicit flags/kwargs (None values are ignored, so callers can pass argparse
+               Namespaces straight through without clobbering config with None).
+    """
+    env_map: Mapping[str, str] = os.environ if env is None else env
+    path = Path(config_path).expanduser() if config_path else _config_path()
+
+    file_cfg = _read_toml(path)
+    overrides = overrides or {}
+
+    valid = {f.name for f in fields(Config) if not f.name.startswith("_")}
+    values: dict[str, Any] = {}
+    origin: dict[str, str] = {}
+
+    for key in valid:
+        # default
+        values[key] = _DEFAULTS[key]
+        origin[key] = "default"
+        # file
+        if key in file_cfg and file_cfg[key] is not None:
+            values[key] = file_cfg[key]
+            origin[key] = "file"
+        # env  (use `is not None` for consistency with file/flag layers; an explicitly-set
+        # empty env var overrides rather than being silently dropped)
+        env_key = _ENV_PREFIX + key.upper()
+        if env_map.get(env_key) is not None:
+            values[key] = env_map[env_key]
+            origin[key] = "env"
+        # explicit override (flag/kwarg) — wins, but only if not None
+        if key in overrides and overrides[key] is not None:
+            values[key] = overrides[key]
+            origin[key] = "flag"
+
+    cfg = Config(**values)
+    cfg._origin = origin
+    return cfg

scribecast/engines/__init__.py

@@ -0,0 +1,19 @@
+"""scribecast.engines — opt-in render engine adapters (manim, remotion).
+
+The default 'hyperframes' (Pillow cards) renderer lives in pipeline.py and needs no engine adapter.
+These adapters wrap the heavy, opt-in engines and are imported lazily so the base install stays light.
+
+All engine renderers share the EngineRenderer Protocol below so the pipeline's _render_engine
+dispatch stays honest as engines are added: each is a callable
+    (cards: list[tuple[str, str]], out_path: str, **kw) -> str   # returns the output mp4 path
+and raises a clear <Engine>AdapterError (subclass of RuntimeError) on failure — never a silent
+fallback to a different engine.
+"""
+from __future__ import annotations
+
+from typing import Protocol, runtime_checkable
+
+
+@runtime_checkable
+class EngineRenderer(Protocol):
+    def __call__(self, cards: "list[tuple[str, str]]", out_path: str, **kw) -> str: ...

scribecast/engines/manim_adapter.py

@@ -0,0 +1,156 @@
+"""scribecast.engines.manim_adapter — render a scribecast card script as a CINEMATIC Manim video.
+
+Reuses vqkit.CinematicScene (the council-locked cinematic base: MovingCameraScene + gradient bg +
+theme tokens + title_in/pan_to/spotlight). NOT a static slideshow — each card gets an animated
+reveal, the camera moves between cards, and headings use Write() with a fly-to-edge. Math/LaTeX in
+a card renders via tex_or_text (real MathTex when LaTeX is present, Text fallback otherwise).
+
+This is the opt-in `--engine manim` path. It needs the [manim] extra installed. The default
+hyperframes (Pillow cards) path stays dependency-light.
+
+The scene reads its card script from a JSON file pointed at by $SCRIBECAST_CARDS so the same
+CinematicScene class can render any note (Manim renders by importing a scene file + class name).
+"""
+from __future__ import annotations
+
+import json
+import os
+import re
+import subprocess
+import sys
+import tempfile
+from pathlib import Path
+
+# The scene module written to a temp file and rendered via `manim`. It imports vqkit's cinematic
+# base at render time (inside the manim subprocess), reads cards from $SCRIBECAST_CARDS, and
+# animates them. Kept as a string so the adapter has no import-time manim dependency.
+_SCENE_SRC = r'''
+import json, os, sys
+sys.path.insert(0, os.environ.get("SCRIBECAST_REPO", "."))
+from manim import (Text, VGroup, FadeIn, FadeOut, Write, UP, DOWN, ORIGIN, LEFT)
+from vqkit import CinematicScene, Palette, Type, Timing
+from vqkit.scene import tex_or_text
+
+# Only treat a line as LaTeX when it carries REAL math delimiters ($...$ or a backslash command).
+# Prose like "The integral shrinks" must NOT be compiled as LaTeX (it errors and yields an empty
+# render). When a $...$ span exists we MathTex that span and pass the full line as the plain fallback.
+import re as _re
+_TEX_SPAN = _re.compile(r"\$(.+?)\$|(\\[a-zA-Z]+)")
+
+
+class ScribecastScene(CinematicScene):
+    def story(self):
+        cards = json.load(open(os.environ["SCRIBECAST_CARDS"]))
+        for idx, card in enumerate(cards):
+            title = (card.get("title") or "").strip()
+            body = (card.get("body") or "").strip()
+            if title:
+                self.title_in(title)               # cinematic heading: Write + fly to edge
+            mobs = []
+            y = 1.5
+            for line in [l for l in body.split("\n") if l.strip()][:8]:
+                line = line.strip()
+                m = _TEX_SPAN.search(line)
+                if m:
+                    # real LaTeX present: render the math span via MathTex, prose as plain fallback
+                    latex = (m.group(1) or m.group(2) or line).strip()
+                    m_obj = tex_or_text(latex, line[:70], font_size=Type.BODY)
+                else:
+                    # plain prose -> Text (NEVER feed prose to MathTex)
+                    m_obj = Text(line[:70], font_size=Type.BODY, font=Type.FONT, color=Palette.INK)
+                m_obj.move_to([0, y, 0])
+                mobs.append(m_obj)
+                y -= 0.7
+            if mobs:
+                grp = VGroup(*mobs)
+                # animated reveal (not a static dump): stagger fade-in
+                self.play(*[FadeIn(m, shift=UP * 0.2) for m in mobs], run_time=Timing.WRITE)
+                self.wait(Timing.BEAT)
+                if idx < len(cards) - 1:
+                    self.play(FadeOut(grp), run_time=Timing.FAST)
+        self.wait(Timing.BEAT)
+'''
+
+
+from ..logging_setup import get_logger
+_log = get_logger(__name__)
+
+
+class ManimAdapterError(RuntimeError):
+    pass
+
+
+def render_cards_manim(cards: list[tuple[str, str]], out_path: str, *,
+                       repo_dir: str | None = None, quality: str = "m",
+                       timeout: int = 900) -> str:
+    """Render cards as a cinematic Manim video. Returns out_path.
+
+    cards:    [(title, body)] from scribecast.pipeline.script_from_text.
+    quality:  manim quality flag: l(480p15) m(720p30) h(1080p60). Default m.
+    repo_dir: path to the vidkit/scribecast repo (for `import vqkit`); defaults to the installed
+              package location so it works delete-proof.
+    """
+    try:
+        import manim  # noqa: F401
+    except ImportError as exc:
+        raise ManimAdapterError(
+            "engine 'manim' needs the manim extra: pip install vidkit[manim]"
+        ) from exc
+
+    # locate the INSTALLED vqkit so the manim subprocess imports it regardless of cwd
+    # (delete-proof: this resolves to site-packages when scribecast is wheel-installed, so it
+    # works even with the workspace source deleted). Never fall back to a cwd-relative ".".
+    if repo_dir is None:
+        try:
+            import vqkit
+            repo_dir = str(Path(vqkit.__file__).resolve().parent.parent)
+        except ImportError as exc:  # pragma: no cover - defensive: vqkit ships in the wheel
+            raise ManimAdapterError(
+                "manim engine needs vqkit (ships in the vidkit wheel) but it could not be "
+                "imported. Reinstall: pip install vidkit[manim]."
+            ) from exc
+
+    import shutil
+    work = Path(tempfile.mkdtemp(prefix="scribecast-manim-"))
+    try:
+        scene_file = work / "scribecast_scene.py"
+        scene_file.write_text(_SCENE_SRC)
+        cards_file = work / "cards.json"
+        cards_file.write_text(json.dumps([{"title": t, "body": b} for t, b in cards]))
+
+        fps = {"l": 15, "m": 30, "h": 60, "k": 60}.get(quality, 30)
+        env = dict(os.environ, SCRIBECAST_CARDS=str(cards_file), SCRIBECAST_REPO=repo_dir)
+        media = work / "media"
+        cmd = [sys.executable, "-m", "manim", f"-q{quality}", "--format=mp4", "--fps", str(fps),
+               "--media_dir", str(media), str(scene_file), "ScribecastScene"]
+        _log.info("manim: rendering %d card(s) q=%s", len(cards), quality)
+        proc = subprocess.run(cmd, capture_output=True, text=True, timeout=timeout, env=env)
+        if proc.returncode != 0:
+            raise ManimAdapterError(f"manim render failed (exit {proc.returncode}):\n{proc.stderr[-1500:]}")
+        # locate the newest mp4 manim produced
+        mp4s = list(media.rglob("*.mp4"))
+        if not mp4s:
+            raise ManimAdapterError("manim exited 0 but produced no mp4")
+        newest = max(mp4s, key=lambda p: p.stat().st_mtime)
+        # Guard against "exit 0 but empty render" (a scene error manim swallows): a real card
+        # video is never ~0s. Probe and fail loudly rather than return a blank video.
+        try:
+            from vidkit_core.render import ffprobe
+            dur = ffprobe(str(newest)).duration
+            if dur < 0.5:  # pragma: no cover - defensive: only if manim emits a corrupt 0s file
+                tail = proc.stderr[-1200:] or proc.stdout[-1200:]
+                raise ManimAdapterError(
+                    f"manim produced a {dur:.2f}s (empty) video — the scene likely errored. "
+                    f"Last output:\n{tail}"
+                )
+        except ManimAdapterError:  # pragma: no cover - re-raise guard
+            raise
+        except Exception:  # pragma: no cover - ffprobe present in this env
+            pass  # ffprobe unavailable — fall through to size check
+        Path(out_path).parent.mkdir(parents=True, exist_ok=True)
+        shutil.copy(str(newest), out_path)
+    finally:
+        shutil.rmtree(work, ignore_errors=True)
+    if not Path(out_path).exists() or Path(out_path).stat().st_size == 0:  # pragma: no cover
+        raise ManimAdapterError("manim render produced no usable output")
+    return out_path

scribecast/engines/remotion_adapter.py

@@ -0,0 +1,114 @@
+"""scribecast.engines.remotion_adapter — render a scribecast card script as a Remotion video.
+
+Drives the vendored remotion_kit (React + Remotion 4.x) ScribecastCards composition, passing the
+cards as Remotion inputProps. Cinematic primitives (spring entrances, gradient, continuous fade)
+live in the React composition; this adapter just feeds it data and invokes `npx remotion render`.
+
+NOTE ON LICENSING: Remotion is free for individuals and companies <= 3 people; larger orgs need a
+paid licence (Remotion License v1). The operator explicitly opted into all three engines, so this
+adapter is wired; it is the operator's responsibility to hold a licence if their org exceeds the
+free tier. The adapter never bypasses or misrepresents licensing.
+
+This is the opt-in `--engine remotion` path. It needs Node + the remotion_kit node_modules. The
+default hyperframes (Pillow cards) path stays dependency-light.
+"""
+from __future__ import annotations
+
+import json
+import os
+import shutil
+import subprocess
+import tempfile
+from pathlib import Path
+
+
+from ..logging_setup import get_logger
+_log = get_logger(__name__)
+
+
+class RemotionAdapterError(RuntimeError):
+    pass
+
+
+def _find_remotion_kit() -> Path | None:
+    """Locate the remotion_kit dir. Checks (1) $SCRIBECAST_REMOTION_KIT, (2) alongside the
+    installed vidkit package (delete-proof when the kit ships in the wheel data), (3) the dev repo.
+    Returns None if not found."""
+    cand = []
+    env = os.environ.get("SCRIBECAST_REMOTION_KIT")
+    if env:
+        cand.append(Path(env))
+    try:
+        import vidkit_core
+        repo = Path(vidkit_core.__file__).resolve().parent.parent
+        cand.append(repo / "remotion_kit")
+    except Exception:  # pragma: no cover - vidkit_core importable in this env
+        pass
+    cand.append(Path.cwd() / "remotion_kit")
+    for c in cand:
+        if c and (c / "package.json").is_file() and (c / "src" / "Root.tsx").is_file():
+            return c
+    return None  # pragma: no cover - kit present in this env
+
+
+def render_cards_remotion(cards: list[tuple[str, str]], out_path: str, *,
+                          per_card_seconds: float = 3.0, fps: int = 60,
+                          timeout: int = 900) -> str:
+    """Render cards as a Remotion video. Returns out_path.
+
+    fps defaults to 60 to MATCH the remotion_kit composition (theme.ts FPS=60); the per-card frame
+    count must be computed at the composition's fps or the wall-clock duration is wrong.
+
+    Requires Node (`npx`) + the remotion_kit with node_modules installed. Raises a clear
+    RemotionAdapterError naming the missing piece otherwise (never a silent fallback).
+    """
+    if shutil.which("npx") is None:
+        raise RemotionAdapterError(
+            "engine 'remotion' needs Node.js (npx) on PATH. Install Node, or choose "
+            "--engine hyperframes / --engine manim."
+        )
+    kit = _find_remotion_kit()
+    if kit is None:
+        raise RemotionAdapterError(
+            "remotion_kit not found. Set $SCRIBECAST_REMOTION_KIT to the kit dir, or use another "
+            "engine. (The kit ships in the vidkit repo; a bare wheel install may not include it.)"
+        )
+    if not (kit / "node_modules").is_dir():
+        raise RemotionAdapterError(
+            f"remotion_kit at {kit} has no node_modules — run `npm install` there first "
+            "(Remotion is license-gated for orgs > 3; ensure you hold a licence if required)."
+        )
+
+    per_card_frames = max(1, round(per_card_seconds * fps))
+    props = {"cards": [{"title": t, "body": b} for t, b in cards], "perCard": per_card_frames}
+    work = Path(tempfile.mkdtemp(prefix="scribecast-remotion-"))
+    out_abs = str(Path(out_path).resolve())
+    Path(out_path).parent.mkdir(parents=True, exist_ok=True)
+    try:
+        props_file = work / "props.json"
+        props_file.write_text(json.dumps(props))
+        # remotion render <entry> <composition-id> <output> --props=<file>
+        cmd = ["npx", "remotion", "render", "src/index.ts", "ScribecastCards", out_abs,
+               f"--props={props_file}"]
+        _log.info("remotion: rendering %d card(s) via kit %s", len(cards), kit)
+        proc = subprocess.run(cmd, capture_output=True, text=True, timeout=timeout, cwd=str(kit))
+    finally:
+        shutil.rmtree(work, ignore_errors=True)
+    if proc.returncode != 0:
+        raise RemotionAdapterError(
+            f"remotion render failed (exit {proc.returncode}):\n{proc.stderr[-1500:]}"
+        )
+    if not Path(out_path).exists() or Path(out_path).stat().st_size == 0:  # pragma: no cover
+        raise RemotionAdapterError("remotion render produced no output")
+    # guard the empty-but-exit-0 case
+    try:
+        from vidkit_core.render import ffprobe
+        if ffprobe(out_path).duration < 0.5:  # pragma: no cover - defensive: corrupt 0s output
+            raise RemotionAdapterError(
+                f"remotion produced a near-empty video — composition likely errored.\n{proc.stderr[-1000:]}"
+            )
+    except RemotionAdapterError:  # pragma: no cover - re-raise guard
+        raise
+    except Exception:  # pragma: no cover - ffprobe present
+        pass
+    return out_path

scribecast/logging_setup.py

@@ -0,0 +1,45 @@
+"""scribecast.logging_setup — package logging.
+
+Library best-practice: the package logger has a NullHandler so importing scribecast produces NO
+output unless the application opts in. `configure_logging(level)` (called by the CLI and MCP
+server) attaches a stderr handler. Every important path logs through `get_logger(__name__)`:
+resolution, engine selection, each render stage, narration, mux, MCP tool dispatch, and errors.
+
+Env: SCRIBECAST_LOG_LEVEL (DEBUG/INFO/WARNING/ERROR) overrides the default when configure_logging
+is called without an explicit level.
+"""
+from __future__ import annotations
+
+import logging
+import os
+
+_ROOT = "scribecast"
+
+# Attach a NullHandler once so library use never emits "No handler" warnings or unwanted output.
+logging.getLogger(_ROOT).addHandler(logging.NullHandler())
+
+
+def get_logger(name: str) -> logging.Logger:
+    """Return a child logger under the scribecast namespace (e.g. scribecast.pipeline)."""
+    if name == "__main__" or not name.startswith(_ROOT):
+        name = f"{_ROOT}.{name.rsplit('.', 1)[-1]}"
+    return logging.getLogger(name)
+
+
+def configure_logging(level: str | int | None = None, *, stream=None) -> None:
+    """Attach a stderr StreamHandler to the scribecast logger (idempotent). Called by the CLI/MCP
+    entry points. `level` falls back to $SCRIBECAST_LOG_LEVEL then WARNING."""
+    logger = logging.getLogger(_ROOT)
+    lvl: str | int = level if level is not None else os.environ.get("SCRIBECAST_LOG_LEVEL", "WARNING")
+    if isinstance(lvl, str):
+        lvl = getattr(logging, lvl.upper(), logging.WARNING)
+    logger.setLevel(lvl)
+    # don't double-add a real handler
+    if not any(isinstance(h, logging.StreamHandler) and not isinstance(h, logging.NullHandler)
+               for h in logger.handlers):
+        import sys
+        h = logging.StreamHandler(stream or sys.stderr)
+        h.setFormatter(logging.Formatter("%(asctime)s %(levelname)s %(name)s: %(message)s",
+                                         datefmt="%H:%M:%S"))
+        logger.addHandler(h)
+    logger.propagate = False