talkthrough 0.1.0__py3-none-any.whl

talkthrough/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

talkthrough/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+main()

talkthrough/capture.py

@@ -0,0 +1,344 @@
+"""Capture a page into a folder: page.png (the whole page), boxes.json (its sections), page.txt, page.json."""
+import asyncio
+import base64
+import io
+import json
+import os
+import platform
+import re
+import shutil
+import socket
+import subprocess
+import sys
+import tempfile
+import time
+import urllib.parse
+import urllib.request
+from pathlib import Path
+
+from PIL import Image
+
+Image.MAX_IMAGE_PIXELS = None
+
+
+def find_chrome():
+    if os.environ.get("CHROME"):
+        return os.environ["CHROME"]
+    candidates = {
+        "Darwin": ["/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
+                   "/Applications/Chromium.app/Contents/MacOS/Chromium",
+                   "/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge"],
+        "Windows": [r"C:\Program Files\Google\Chrome\Application\chrome.exe",
+                    r"C:\Program Files (x86)\Google\Chrome\Application\chrome.exe",
+                    r"C:\Program Files (x86)\Microsoft\Edge\Application\msedge.exe"],
+    }.get(platform.system(), [])
+    for c in candidates:
+        if os.path.exists(c):
+            return c
+    for name in ("google-chrome", "google-chrome-stable", "chromium", "chromium-browser", "chrome", "msedge"):
+        p = shutil.which(name)
+        if p:
+            return p
+    sys.exit("No Chrome, Chromium or Edge found. Install one, or set CHROME=/path/to/browser.")
+
+
+BOXES_JS = r"""
+(() => {
+  const sel = 'h1,h2,h3,header,section,article,figure,svg,table,pre,img,canvas,blockquote,ol,ul,p,details,' +
+              '[class*=slide],[class*=card],[class*=tile],[class*=callout],[class*=seg],[class*=diagram],[class*=box],' +
+              'aside,[class*=good],[class*=warn],[class*=note],[class*=tip],[class*=info],[class*=alert],[class*=panel]';
+  const seen = new Set(), out = [];
+  for (const el of document.querySelectorAll(sel)) {
+    if (el.closest('svg') && el.tagName.toLowerCase() !== 'svg') continue;
+    const r = el.getBoundingClientRect();
+    if (r.width < 80 || r.height < 24) continue;
+    const st = getComputedStyle(el);
+    if (st.visibility === 'hidden' || st.display === 'none' || +st.opacity === 0) continue;
+    const x = Math.round(r.left + scrollX), y = Math.round(r.top + scrollY);
+    const key = [x, y, Math.round(r.width), Math.round(r.height)].join(',');
+    if (seen.has(key)) continue;
+    seen.add(key);
+    let depth = 0; for (let p = el.parentElement; p; p = p.parentElement) depth++;
+    const text = (el.innerText || el.textContent || '').replace(/\s+/g, ' ').trim().slice(0, 140);
+    out.push({tag: el.tagName.toLowerCase(), cls: (el.getAttribute('class') || '').slice(0, 60),
+              rect: [x, y, Math.round(r.width), Math.round(r.height)], depth, text});
+    if (out.length >= 600) break;
+  }
+  return out;
+})()
+"""
+
+FREEZE_JS = r"""
+(() => {
+  const target = location.hash ? document.getElementById(decodeURIComponent(location.hash.slice(1))) : null;
+  if (target) {
+    if (target.tagName === 'DETAILS') target.open = true;
+    for (let d = target.closest('details'); d; d = d.parentElement && d.parentElement.closest('details')) d.open = true;
+  }
+  const s = document.createElement('style');
+  s.textContent = '*,*::before,*::after{animation:none!important;transition:none!important;caret-color:transparent!important}';
+  document.head.appendChild(s);
+  for (const el of document.querySelectorAll('*')) {
+    const p = getComputedStyle(el).position;
+    if (p === 'fixed') el.style.setProperty('display', 'none', 'important');
+    else if (p === 'sticky') el.style.position = 'static';
+  }
+  return true;
+})()
+"""
+
+
+# ---------- capture (Chrome over the DevTools protocol) ----------
+
+class CDP:
+    def __init__(self, ws):
+        self.ws, self.n, self.events = ws, 0, []
+
+    async def call(self, method, **params):
+        self.n += 1
+        mid = self.n
+        await self.ws.send(json.dumps({"id": mid, "method": method, "params": params}))
+        while True:
+            msg = json.loads(await self.ws.recv())
+            if msg.get("id") == mid:
+                if "error" in msg:
+                    raise RuntimeError(f"{method}: {msg['error']}")
+                return msg.get("result", {})
+            self.events.append(msg)
+
+    async def wait_event(self, name, timeout=30):
+        end = time.time() + timeout
+        while time.time() < end:
+            if any(e.get("method") == name for e in self.events):
+                return
+            try:
+                msg = json.loads(await asyncio.wait_for(self.ws.recv(), timeout=1))
+                self.events.append(msg)
+            except asyncio.TimeoutError:
+                pass
+        raise TimeoutError(name)
+
+    async def js(self, expr):
+        r = await self.call("Runtime.evaluate", expression=expr, returnByValue=True, awaitPromise=True)
+        return r.get("result", {}).get("value")
+
+
+def _free_port():
+    with socket.socket() as s:
+        s.bind(("127.0.0.1", 0))
+        return s.getsockname()[1]
+
+
+async def _capture(url, width, scale):
+    import websockets
+    port = _free_port()
+    profile = tempfile.mkdtemp(prefix="walkthrough-chrome-")
+    proc = subprocess.Popen([find_chrome(), "--headless=new", f"--remote-debugging-port={port}", f"--user-data-dir={profile}",
+                             "--hide-scrollbars", "--no-first-run", "--no-default-browser-check", "about:blank"],
+                            stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
+    try:
+        ws_url = None
+        for _ in range(100):
+            try:
+                targets = json.load(urllib.request.urlopen(f"http://127.0.0.1:{port}/json/list", timeout=1))
+                ws_url = next(t["webSocketDebuggerUrl"] for t in targets if t.get("type") == "page")
+                break
+            except Exception:
+                time.sleep(0.1)
+        if not ws_url:
+            sys.exit("The browser did not start. Set CHROME=/path/to/browser.")
+        async with websockets.connect(ws_url, max_size=None) as ws:
+            c = CDP(ws)
+            await c.call("Page.enable")
+            await c.call("Emulation.setDeviceMetricsOverride", width=width, height=1200,
+                         deviceScaleFactor=scale, mobile=False)
+            await c.call("Page.navigate", url=url)
+            await c.wait_event("Page.loadEventFired")
+            for _ in range(30):
+                title = await c.js("document.title + ' ' + (document.body ? document.body.innerText.slice(0, 200) : '')")
+                if not re.search(r"just a moment|checking your browser|attention required|verify you are human",
+                                 title or "", re.I):
+                    break
+                await asyncio.sleep(1)
+            else:
+                print("warning: the page still shows a bot check; capture a saved copy instead", file=sys.stderr)
+            await c.js("document.fonts ? document.fonts.ready.then(() => true) : true")
+            await asyncio.sleep(0.8)
+            await c.js(FREEZE_JS)
+            await asyncio.sleep(0.3)
+            height = int(await c.js("Math.ceil(document.documentElement.scrollHeight)"))
+            boxes = [b for b in await c.js(BOXES_JS) if b["rect"][1] + b["rect"][3] <= height + 2]
+            text = await c.js("document.body.innerText")
+            title = await c.js("document.title")
+            bg = await c.js("getComputedStyle(document.body).backgroundColor")
+            await c.call("Emulation.setDeviceMetricsOverride", width=width, height=min(height, 8000),
+                         deviceScaleFactor=scale, mobile=False)
+            await asyncio.sleep(0.3)
+            page = Image.new("RGB", (width * scale, height * scale), "white")
+            tile = 3000
+            for y in range(0, height, tile):
+                h = min(tile, height - y)
+                shot = await c.call("Page.captureScreenshot", format="png", captureBeyondViewport=True,
+                                    clip={"x": 0, "y": y, "width": width, "height": h, "scale": 1})
+                im = Image.open(io.BytesIO(base64.b64decode(shot["data"]))).convert("RGB")
+                page.paste(im, (0, y * scale))
+            try:
+                await c.call("Browser.close")
+            except Exception:
+                pass
+    finally:
+        proc.terminate()
+        try:
+            proc.wait(timeout=5)
+        except subprocess.TimeoutExpired:
+            proc.kill()
+        shutil.rmtree(profile, ignore_errors=True)
+
+    meta = {"url": url, "title": title, "width": width, "height": height, "scale": scale, "bg": bg, "kind": "html"}
+    return page, text, meta, boxes
+
+
+PDF_GAP = 24
+
+
+def _profile(mask, box, axis):
+    """Which rows (axis=0) or columns (axis=1) of box contain ink."""
+    x0, y0, x1, y1 = box
+    region = mask.crop(box)
+    size = (1, y1 - y0) if axis == 0 else (x1 - x0, 1)
+    return [v > 0 for v in region.resize(size, Image.Resampling.BOX).getdata()]
+
+
+def _runs(ink, min_gap):
+    """Spans of ink separated by at least min_gap empty cells."""
+    spans, start, gap = [], None, 0
+    for i, on in enumerate(ink):
+        if on:
+            if start is None:
+                start = i
+            gap = 0
+            end = i + 1
+        elif start is not None:
+            gap += 1
+            if gap >= min_gap:
+                spans.append((start, end))
+                start = None
+    if start is not None:
+        spans.append((start, end))
+    return spans
+
+
+def _xy_cut(mask, box, depth, out, gap_y=10, gap_x=14):
+    """Recursive whitespace cut: bands of content, then columns inside a band. Records every node."""
+    x0, y0, x1, y1 = box
+    rows = _runs(_profile(mask, box, 0), 1)
+    cols = _runs(_profile(mask, box, 1), 1)
+    if not rows or not cols:
+        return
+    box = x0 + cols[0][0], y0 + rows[0][0], x0 + cols[-1][1], y0 + rows[-1][1]
+    x0, y0, x1, y1 = box
+    if x1 - x0 >= 40 and y1 - y0 >= 12:
+        out.append((box, depth))
+    if depth >= 4:
+        return
+    bands = _runs(_profile(mask, box, 0), gap_y)
+    if len(bands) > 1:
+        for a, b in bands:
+            _xy_cut(mask, (x0, y0 + a, x1, y0 + b), depth + 1, out, gap_y, gap_x)
+        return
+    columns = _runs(_profile(mask, box, 1), gap_x)
+    if len(columns) > 1:
+        for a, b in columns:
+            _xy_cut(mask, (x0 + a, y0, x0 + b, y1), depth + 1, out, gap_y, gap_x)
+
+
+def _undouble(word):
+    """Outlined SVG text often extracts with every glyph twice ("TTHHEE"); collapse such words."""
+    if len(word) >= 4 and len(word) % 2 == 0 and all(word[i] == word[i + 1] for i in range(0, len(word), 2)):
+        return word[::2]
+    return word
+
+
+def _ink_mask(img, bg):
+    """White where the page differs from its background colour."""
+    from PIL import ImageChops
+    diff = ImageChops.difference(img, Image.new("RGB", img.size, bg)).convert("L")
+    return diff.point(lambda v: 255 if v > 18 else 0)
+
+
+def capture_pdf(path, out, scale, name=None):
+    import pypdfium2 as pdfium
+    pdf = pdfium.PdfDocument(str(path))
+    sizes = [pdf[i].get_size() for i in range(len(pdf))]
+    width = int(max(s[0] for s in sizes)) + 2 * PDF_GAP
+    height = int(sum(s[1] for s in sizes) + PDF_GAP * (len(sizes) + 1))
+    sheet = Image.new("RGB", (width * scale, height * scale), (232, 232, 235))
+    boxes, texts, y = [], [], PDF_GAP
+    for i in range(len(pdf)):
+        page = pdf[i]
+        pw, ph = sizes[i]
+        x = (width - pw) / 2
+        img = page.render(scale=scale).to_pil().convert("RGB")
+        sheet.paste(img, (int(x * scale), int(y * scale)))
+        tp = page.get_textpage()
+        text = tp.get_text_range()
+        texts.append(f"--- page {i + 1} ---\n{text}")
+        boxes.append({"tag": "page", "cls": f"page {i + 1}", "rect": [round(x), round(y), round(pw), round(ph)],
+                      "depth": 0, "text": " ".join(text.split())[:140]})
+        small = img.resize((round(pw), round(ph)), Image.Resampling.BOX)
+        bg = max(small.getcolors(small.width * small.height), key=lambda c: c[0])[1]
+        nodes = []
+        _xy_cut(_ink_mask(small, bg), (0, 0, small.width, small.height), 1, nodes)
+        seen = set()
+        for (bx0, by0, bx1, by1), depth in nodes:
+            if (bx0, by0, bx1, by1) in seen or (bx1 - bx0) * (by1 - by0) > 0.9 * pw * ph:
+                continue
+            seen.add((bx0, by0, bx1, by1))
+            bt = " ".join(_undouble(w) for w in tp.get_text_bounded(bx0, ph - by1, bx1, ph - by0).split())
+            boxes.append({"tag": "region", "cls": f"page {i + 1}", "depth": depth, "text": bt[:140],
+                          "rect": [round(x + bx0), round(y + by0), bx1 - bx0, by1 - by0]})
+        y += ph + PDF_GAP
+    title = (pdf.get_metadata_dict().get("Title") or "").strip() or re.sub(r"[-_]+", " ", name or Path(path).stem)
+    meta = {"url": Path(path).resolve().as_uri(), "title": title, "width": width, "height": height,
+            "scale": scale, "bg": "rgb(232, 232, 235)", "kind": "pdf", "pages": len(pdf)}
+    return sheet, "\n\n".join(texts), meta, boxes
+
+
+def _remote_pdf(url):
+    """Download url to a temp file if it serves a PDF (arXiv's /pdf/ links have no .pdf suffix), else None."""
+    req = urllib.request.Request(url, headers={"User-Agent": "talkthrough"})
+    with urllib.request.urlopen(req, timeout=60) as r:
+        if "pdf" not in (r.headers.get("Content-Type") or "").lower() and not url.lower().split("?")[0].endswith(".pdf"):
+            return None
+        fd, tmp = tempfile.mkstemp(suffix=".pdf", prefix="talkthrough-")
+        with os.fdopen(fd, "wb") as f:
+            shutil.copyfileobj(r, f)
+    return Path(tmp)
+
+
+def capture(src, out, width=820, scale=2):
+    out = Path(out)
+    src = str(src)
+    if not re.match(r"^(https?|file):", src) and not Path(src).exists():
+        sys.exit(f"no such file: {src}")
+    if src.startswith("file:") and not Path(urllib.request.url2pathname(src[5:].split("#")[0])).exists():
+        sys.exit(f"no such file: {src}")
+    remote_pdf = _remote_pdf(src) if re.match(r"^https?:", src) else None
+    if remote_pdf:
+        name = urllib.parse.unquote(src.split("?")[0].rstrip("/").rsplit("/", 1)[-1])
+        page, text, meta, boxes = capture_pdf(remote_pdf, out, scale, name=re.sub(r"\.pdf$", "", name, flags=re.I))
+        meta["url"] = src
+        remote_pdf.unlink()
+    elif src.lower().endswith(".pdf") and not src.startswith("file:"):
+        page, text, meta, boxes = capture_pdf(src, out, scale)
+    else:
+        url = src if re.match(r"^(https?|file):", src) else Path(src).resolve().as_uri()
+        page, text, meta, boxes = asyncio.run(_capture(url, width, scale))
+    for i, b in enumerate(boxes):
+        b["id"] = f"b{i}"
+    out.mkdir(parents=True, exist_ok=True)
+    page.save(out / "page.png")
+    (out / "page.txt").write_text(text or "")
+    (out / "page.json").write_text(json.dumps(meta, indent=1))
+    (out / "boxes.json").write_text(json.dumps(boxes, indent=1, ensure_ascii=False))
+    return meta, boxes

talkthrough/cli.py

@@ -0,0 +1,200 @@
+"""talkthrough: turn an HTML page or a PDF into a narrated walkthrough video of itself."""
+import argparse
+import json
+import os
+import platform
+import plistlib
+import shutil
+import subprocess
+import sys
+import tempfile
+import webbrowser
+from pathlib import Path
+
+from . import __version__
+
+
+def _job_path(folder):
+    return Path(folder) / "shots.json"
+
+
+def cmd_capture(a):
+    from .capture import capture
+    meta, boxes = capture(a.page, a.out, a.width, a.scale)
+    print(f"captured {meta['title']!r}: {meta['width']}x{meta['height']} css px at {meta['scale']}x, "
+          f"{len(boxes)} boxes -> {a.out}")
+
+
+def _need_planner():
+    try:
+        import anthropic  # noqa: F401
+    except ImportError:
+        sys.exit("planning needs the anthropic package: pip install "
+                 "'talkthrough[plan] @ git+https://github.com/amishah1998/talkthrough'")
+    if not (os.environ.get("ANTHROPIC_API_KEY") or os.environ.get("ANTHROPIC_AUTH_TOKEN")):
+        sys.exit("planning needs ANTHROPIC_API_KEY. Without one, ask Claude Code for the video (the plugin plans "
+                 "it for you), or run capture, write shots.json yourself, then preview and render.")
+
+
+def cmd_plan(a):
+    _need_planner()
+    from .plan import plan
+    shots = plan(a.dir, seconds=a.seconds, model=a.model, extra=a.note or "")
+    job = {"format": a.format, "tts": a.tts, "shots": shots}
+    _job_path(a.dir).write_text(json.dumps(job, indent=1, ensure_ascii=False))
+    print(f"{len(shots)} shots -> {_job_path(a.dir)}")
+
+
+def cmd_preview(a):
+    from .render import preview
+    preview(a.dir)
+
+
+def _mac_default_browser():
+    """Bundle id of the app that handles https links, or None if the user never changed it (Safari)."""
+    prefs = Path.home() / "Library/Preferences/com.apple.LaunchServices/com.apple.launchservices.secure.plist"
+    try:
+        handlers = plistlib.loads(prefs.read_bytes()).get("LSHandlers", [])
+    except (OSError, plistlib.InvalidFileException):
+        return None
+    for scheme in ("https", "http"):
+        for h in handlers:
+            if h.get("LSHandlerURLScheme") == scheme and h.get("LSHandlerRoleAll"):
+                return h["LSHandlerRoleAll"]
+    return None
+
+
+def open_in_browser(video):
+    """Play the finished video in the default web browser.
+
+    On macOS a plain open hands an .mp4 to QuickTime, so the browser is looked up and named explicitly."""
+    video = Path(video).resolve()
+    if platform.system() == "Darwin":
+        bundle = _mac_default_browser()
+        args = ["open", "-b", bundle, str(video)] if bundle else ["open", "-a", "Safari", str(video)]
+        if subprocess.run(args, capture_output=True).returncode == 0:
+            return
+    if not webbrowser.open(video.as_uri()):
+        print(f"could not open a browser; the video is at {video}", file=sys.stderr)
+
+
+def cmd_render(a):
+    from .render import render
+    out = render(a.dir, a.out, quality="share" if a.share else None, speed=a.speed)
+    if a.open:
+        open_in_browser(out)
+
+
+def cmd_make(a):
+    _need_planner()
+    from .capture import capture
+    from .plan import plan
+    from .render import preview, render
+    folder = Path(a.keep) if a.keep else Path(tempfile.mkdtemp(prefix="talkthrough-"))
+    capture(a.page, folder, a.width, a.scale)
+    shots = plan(folder, seconds=a.seconds, model=a.model, extra=a.note or "")
+    _job_path(folder).write_text(json.dumps({"format": a.format, "tts": a.tts, "shots": shots}, indent=1,
+                                            ensure_ascii=False))
+    preview(folder)
+    out = Path(a.out) if a.out else Path.cwd() / (Path(a.page).stem + "-walkthrough.mp4")
+    render(folder, out, quality="share" if a.share else None, speed=a.speed)
+    if not a.keep:
+        shutil.rmtree(folder, ignore_errors=True)
+    if a.open:
+        open_in_browser(out)
+
+
+def cmd_doctor(a):
+    from .capture import find_chrome
+    ok = True
+
+    def row(name, good, note):
+        nonlocal ok
+        ok &= good or name.startswith("(optional)")
+        print(f"  {'ok ' if good else '-- '} {name}: {note}")
+
+    print(f"talkthrough {__version__} on {platform.system()}")
+    try:
+        row("browser", True, find_chrome())
+    except SystemExit as e:
+        row("browser", False, str(e))
+    row("ffmpeg", bool(shutil.which("ffmpeg")), shutil.which("ffmpeg") or "install ffmpeg")
+    row("ffprobe", bool(shutil.which("ffprobe")), shutil.which("ffprobe") or "comes with ffmpeg")
+    from .voice import ORDER, kokoro_available
+    voices = [name for name, env in ORDER if os.environ.get(env)]
+    if kokoro_available():
+        voices.append("kokoro (local)")
+    if platform.system() == "Darwin" and shutil.which("say"):
+        voices.append("say (macOS)")
+    row("voice", bool(voices), ", ".join(voices) or "none: set CARTESIA_API_KEY, ELEVENLABS_API_KEY or OPENAI_API_KEY, "
+        "or pip install 'talkthrough[local] @ git+https://github.com/amishah1998/talkthrough'")
+    try:
+        import anthropic  # noqa: F401
+        has_sdk = True
+    except ImportError:
+        has_sdk = False
+    auto = has_sdk and bool(os.environ.get("ANTHROPIC_API_KEY") or os.environ.get("ANTHROPIC_AUTH_TOKEN"))
+    row("(optional) auto-plan", auto, "ready" if auto else
+        "needs pip install 'talkthrough[plan] @ git+https://github.com/amishah1998/talkthrough' and ANTHROPIC_API_KEY; not needed when an agent writes shots.json")
+    sys.exit(0 if ok else 1)
+
+
+def main(argv=None):
+    ap = argparse.ArgumentParser(prog="talkthrough", description=__doc__)
+    ap.add_argument("--version", action="version", version=__version__)
+    sub = ap.add_subparsers(dest="cmd", required=True)
+
+    def capture_args(p):
+        p.add_argument("--width", type=int, default=820, help="viewport width in css px for HTML (default 820)")
+        p.add_argument("--scale", type=int, default=2, help="capture pixel density (default 2)")
+
+    def plan_args(p):
+        p.add_argument("--seconds", type=int, default=90, help="target length (default 90)")
+        p.add_argument("--format", default="portrait", choices=["portrait", "landscape", "square"])
+        p.add_argument("--tts", default="auto", choices=["auto", "cartesia", "elevenlabs", "openai", "kokoro", "say"])
+        p.add_argument("--model", default="claude-opus-5", help="Claude model that plans the shots")
+        p.add_argument("--note", help="extra direction for the planner, e.g. 'focus on the pricing table'")
+
+    p = sub.add_parser("capture", help="screenshot the page and list its sections")
+    p.add_argument("page", help=".html, .pdf, or an http(s) URL")
+    p.add_argument("--out", required=True, help="work folder")
+    capture_args(p)
+    p.set_defaults(fn=cmd_capture)
+
+    p = sub.add_parser("plan", help="let Claude write shots.json for a captured page")
+    p.add_argument("dir")
+    plan_args(p)
+    p.set_defaults(fn=cmd_plan)
+
+    p = sub.add_parser("preview", help="one spotlighted frame per shot, as preview.png")
+    p.add_argument("dir")
+    p.set_defaults(fn=cmd_preview)
+
+    p = sub.add_parser("render", help="voice, camera and captions into an MP4")
+    p.add_argument("dir")
+    p.add_argument("--out")
+    p.add_argument("--share", action="store_true", help="smaller file for chat apps (about half the size)")
+    p.add_argument("--speed", type=float, help="voice pace, e.g. 1.25 or 1.5 (default 1.0)")
+    p.add_argument("--open", action="store_true", help="play the video in your web browser when it is done")
+    p.set_defaults(fn=cmd_render)
+
+    p = sub.add_parser("make", help="capture, plan, preview and render in one go")
+    p.add_argument("page")
+    p.add_argument("--out", help="output .mp4 (default: <page>-walkthrough.mp4)")
+    p.add_argument("--keep", help="keep the work folder here")
+    p.add_argument("--share", action="store_true", help="smaller file for chat apps (about half the size)")
+    p.add_argument("--speed", type=float, help="voice pace, e.g. 1.25 or 1.5 (default 1.0)")
+    p.add_argument("--open", action="store_true", help="play the video in your web browser when it is done")
+    capture_args(p)
+    plan_args(p)
+    p.set_defaults(fn=cmd_make)
+
+    p = sub.add_parser("doctor", help="check what is installed")
+    p.set_defaults(fn=cmd_doctor)
+
+    a = ap.parse_args(argv)
+    a.fn(a)
+
+
+if __name__ == "__main__":
+    main()

talkthrough/local_voice.py

@@ -0,0 +1,46 @@
+"""The free local voice: Kokoro-82M (Apache-2.0 weights) through kokoro-onnx. No torch, no GPU.
+The model is downloaded once into the user cache folder."""
+import os
+import sys
+import urllib.request
+from pathlib import Path
+
+RELEASE = "https://github.com/thewh1teagle/kokoro-onnx/releases/download/model-files-v1.0/"
+FILES = {"model": "kokoro-v1.0.onnx", "voices": "voices-v1.0.bin"}
+_engine = None
+
+
+def cache_dir():
+    base = os.environ.get("TALKTHROUGH_CACHE") or os.environ.get("XDG_CACHE_HOME") or Path.home() / ".cache"
+    d = Path(base) / "talkthrough" / "kokoro"
+    d.mkdir(parents=True, exist_ok=True)
+    return d
+
+
+def _fetch(name):
+    path = cache_dir() / name
+    if path.exists() and path.stat().st_size > 0:
+        return path
+    print(f"downloading {name} (one time) ...", file=sys.stderr, flush=True)
+    tmp = path.with_suffix(".part")
+    urllib.request.urlretrieve(RELEASE + name, tmp)
+    tmp.rename(path)
+    return path
+
+
+def engine():
+    global _engine
+    if _engine is None:
+        from kokoro_onnx import Kokoro
+        _engine = Kokoro(str(_fetch(FILES["model"])), str(_fetch(FILES["voices"])))
+    return _engine
+
+
+def speak(text, voice, speed, wav, sample_rate):
+    import soundfile as sf
+    samples, sr = engine().create(text, voice=voice, speed=speed, lang="en-us")
+    tmp = Path(wav).with_suffix(".raw.wav")
+    sf.write(tmp, samples, sr)
+    from .voice import _ffmpeg
+    _ffmpeg("-i", tmp, "-ar", sample_rate, "-ac", 1, wav)
+    tmp.unlink()