scribecast 0.1.0__tar.gz

scribecast-0.1.0/PKG-INFO

@@ -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/README-scribecast.md

@@ -0,0 +1,121 @@
+# 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/pyproject.toml

@@ -0,0 +1,52 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "scribecast"
+version = "0.1.0"
+description = "Turn any note into a narrated video. scribecast façade + vidkit engine (HyperFrames / Manim / Remotion), edge-tts narration, ffmpeg mux. CLI + library + MCP server."
+readme = "README-scribecast.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "Prax" }]
+keywords = ["video", "notes", "narration", "edge-tts", "manim", "remotion", "hyperframes", "ffmpeg", "mcp", "obsidian"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "License :: OSI Approved :: MIT License",
+    "Topic :: Multimedia :: Video",
+]
+# vidkit_core is stdlib-only at import time (ffmpeg/ffprobe are external binaries called via
+# subprocess). edge-tts is lazy-imported inside synth_voiceover, so narration is an opt-in extra.
+dependencies = []
+
+[project.urls]
+Homepage = "https://github.com/praxstack/vidkit"
+Repository = "https://github.com/praxstack/vidkit"
+Issues = "https://github.com/praxstack/vidkit/issues"
+
+[project.optional-dependencies]
+# Narration (edge-tts text-to-speech). Lazy-imported; install when you need voiceover.
+narrate = ["edge-tts>=6.1"]
+# Manim engine (vqkit). Heavy; opt-in per the multi-engine design.
+manim = ["manim>=0.18", "numpy>=1.24", "pillow>=10.0"]
+# Everything.
+all = ["edge-tts>=6.1", "manim>=0.18", "numpy>=1.24", "pillow>=10.0"]
+test = ["pytest>=7", "pytest-xdist>=3", "coverage>=7"]
+
+[project.scripts]
+vidkit = "vidkit_core.cli:main"
+scribecast = "scribecast.cli:main"
+
+[tool.setuptools]
+# One wheel ships the renderer-agnostic core + the Manim engine package + the scribecast façade.
+# Asset dirs (hyperframes_kit, remotion_kit, theme, scenes) are NOT Python packages.
+packages = ["vidkit_core", "vqkit", "scribecast", "scribecast.engines"]
+
+[tool.pytest.ini_options]
+# Let pytest import vidkit_core/vqkit from the repo root without an install.
+pythonpath = ["."]
+testpaths = ["tests", "tests_shared"]

scribecast-0.1.0/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-0.1.0/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-0.1.0/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-0.1.0/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: ...