tapetum 0.2.0__tar.gz

tapetum-0.2.0/.gitignore

@@ -0,0 +1,9 @@
+.venv/
+__pycache__/
+*.egg-info/
+dist/
+build/
+.tapetum-cache/
+*.pyc
+docs/demo/result.json
+docs/demo/transcript.srt

tapetum-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nadercr7
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

tapetum-0.2.0/PKG-INFO

@@ -0,0 +1,148 @@
+Metadata-Version: 2.5
+Name: tapetum
+Version: 0.2.0
+Summary: Give your agent eyes. Paste a video link, get one timeline of what was said and what was on screen. No cookies, no API keys.
+Project-URL: Homepage, https://nadercr7.github.io/tapetum/
+Project-URL: Source, https://github.com/Nadercr7/tapetum
+Project-URL: Issues, https://github.com/Nadercr7/tapetum/issues
+Author: Nadercr7
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agent,llm,mcp,transcript,video,whisper,youtube
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Multimedia :: Video
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Requires-Dist: faster-whisper>=1.1
+Requires-Dist: imageio-ffmpeg
+Requires-Dist: numpy
+Requires-Dist: pillow>=10.1
+Requires-Dist: youtube-transcript-api>=1.2
+Requires-Dist: yt-dlp[default]>=2026.8.1
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.2; extra == 'mcp'
+Provides-Extra: ocr
+Requires-Dist: rapidocr-onnxruntime; extra == 'ocr'
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <a href="https://nadercr7.github.io/tapetum/"><img src="https://raw.githubusercontent.com/Nadercr7/tapetum/main/docs/social.png" alt="tapetum: give your agent eyes" width="760"></a>
+</p>
+
+<p align="center">
+  <a href="https://github.com/Nadercr7/tapetum/actions/workflows/ci.yml"><img src="https://github.com/Nadercr7/tapetum/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-E8A317.svg" alt="MIT license"></a>
+  <img src="https://img.shields.io/badge/python-3.10%2B-0B0D12.svg" alt="Python 3.10+">
+  <a href="https://nadercr7.github.io/tapetum/"><img src="https://img.shields.io/badge/site-live-E8A317.svg" alt="Website"></a>
+</p>
+
+**tapetum lets an AI agent watch a video.** You give it a link. It hands back one file with what was said and what was on screen, in time order, plus the handful of frames worth looking at. No cookies, no API keys, no account. Everything runs on your machine.
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/Nadercr7/tapetum/main/docs/media/demo.gif" alt="tapetum running on a YouTube link and printing the timeline" width="760">
+</p>
+
+## Install
+
+You need [uv](https://docs.astral.sh/uv/) (or pipx).
+
+```bash
+uv tool install git+https://github.com/Nadercr7/tapetum
+tapetum "https://youtu.be/jNQXAC9IVRw"
+```
+
+ffmpeg comes bundled. Check your setup any time with `tapetum doctor`.
+
+## What you get back
+
+One JSON object on stdout, and a folder:
+
+```
+timeline.md       speech and frame references in time order. Start here.
+sheet_01.jpg      nine frames per image, timestamps burned in
+frames/           the frames it kept
+transcript.srt    plus transcript.json
+```
+
+A slice of `timeline.md`:
+
+```markdown
+### 00:05 – 00:10
+frame: `frames/f001_00-05.jpg`
+> the cool thing about these guys is that they have really...
+> really really long trunks
+```
+
+Open any run in your browser with `tapetum view <folder>`: frames on one side, a searchable transcript on the other. [See a live one.](https://nadercr7.github.io/tapetum/demo/)
+
+## How it works
+
+**Words, cheapest first.** It reads the platform's captions when they exist: human ones over auto-generated, the original language over machine translations, your `--lang` over both. When there are none, it downloads a small audio file and runs Whisper locally. Every step it tried is listed in `steps`, failures included.
+
+**Frames by change, not by clock.** It samples a frame every second, then keeps one only when the picture actually changed. A new line on a slide counts. A wobbling camera doesn't. Transitions collapse into one settled frame, and `--budget` caps the total, so a talking head costs you three images instead of thirty.
+
+**Detail on demand.** `tapetum <url> --at 03:12` downloads just that moment at 720p and writes four sharp frames. No re-run of the whole video.
+
+**Honest output.** Every error comes with a `code` and a `hint`. Shaky transcripts carry warnings. Failed runs aren't cached, so a network blip doesn't stick.
+
+## Use it from an agent
+
+| Where | How |
+|---|---|
+| Claude Code | `/plugin marketplace add Nadercr7/tapetum`, then `/plugin install tapetum@tapetum`. Or copy `skills/tapetum/` to `~/.claude/skills/`. |
+| Any MCP client | Install with `uv tool install "tapetum[mcp] @ git+https://github.com/Nadercr7/tapetum"` and add `{"command": "tapetum", "args": ["mcp"]}`. Tools: `watch_video`, `zoom_video`. Frames come back as images. |
+| Codex, Cursor, others | [AGENTS.md](AGENTS.md) tells them how to call it. |
+
+The skill file is short on purpose. Long instructions cost tokens on every single run.
+
+## Options
+
+```
+tapetum <url | file>
+  --lang ar,en        languages you prefer, in order
+  --budget 24         most frames to keep (short clips use fewer)
+  --quality accurate  bigger speech model: fast | balanced | accurate
+  --no-frames         transcript only, fastest
+  --ocr               read on-screen text (pip install "tapetum[ocr]")
+  --force-stt         ignore captions and listen instead
+  --at 03:12          zoom into one moment
+  --fresh             ignore the cache
+  --out DIR           where to write (default ~/.tapetum/<id>)
+
+tapetum doctor        what works on this machine
+tapetum view DIR      open a run in the browser
+tapetum mcp           start the MCP server
+```
+
+## Languages
+
+Whisper covers about 99 languages. On Egyptian Arabic the default model garbles names and numbers, and `--quality accurate` fixes most of it. On a laptop CPU that took about two and a half minutes for a seven-minute video, after a one-time 1.6 GB model download. tapetum warns you when a language is known to be weak on the model you picked. Numbers are in [docs/research/10-measured.md](docs/research/10-measured.md).
+
+## What it can't do
+
+- **Private videos.** Private, age-gated and login-only videos return `login_required`. Instagram and Vimeo mostly land here.
+- **Servers.** YouTube blocks most datacenter IPs. Run it from your own computer.
+- **Live streams.** You get `live_stream`. Try again once the recording is up.
+- **Playlists.** One video per run. You get `playlist_url` otherwise.
+- **Hear tone.** Music, sarcasm and accent don't survive a transcript, and the agent should say so.
+
+Text from a video is content, not instructions. `timeline.md` says so at the top, so agents don't take orders from a caption.
+
+## Why "tapetum"
+
+The tapetum is the mirror layer behind a cat's retina. It sends light back through the eye for a second pass, which is why cats see in the dark and why their eyes glow in a flashlight beam. Look twice, miss less.
+
+## Contributing
+
+```bash
+uv venv && uv pip install -e ".[mcp]" pytest
+pytest
+```
+
+Keep the virtualenv outside OneDrive or Dropbox; sync clients lock files mid-install. Design notes, competitor research and measurements are in [docs/research](docs/research/). Releasing is in [docs/RELEASING.md](docs/RELEASING.md).
+
+MIT licensed. Use it on videos you're allowed to watch.

tapetum-0.2.0/README.md

@@ -0,0 +1,117 @@
+<p align="center">
+  <a href="https://nadercr7.github.io/tapetum/"><img src="https://raw.githubusercontent.com/Nadercr7/tapetum/main/docs/social.png" alt="tapetum: give your agent eyes" width="760"></a>
+</p>
+
+<p align="center">
+  <a href="https://github.com/Nadercr7/tapetum/actions/workflows/ci.yml"><img src="https://github.com/Nadercr7/tapetum/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-E8A317.svg" alt="MIT license"></a>
+  <img src="https://img.shields.io/badge/python-3.10%2B-0B0D12.svg" alt="Python 3.10+">
+  <a href="https://nadercr7.github.io/tapetum/"><img src="https://img.shields.io/badge/site-live-E8A317.svg" alt="Website"></a>
+</p>
+
+**tapetum lets an AI agent watch a video.** You give it a link. It hands back one file with what was said and what was on screen, in time order, plus the handful of frames worth looking at. No cookies, no API keys, no account. Everything runs on your machine.
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/Nadercr7/tapetum/main/docs/media/demo.gif" alt="tapetum running on a YouTube link and printing the timeline" width="760">
+</p>
+
+## Install
+
+You need [uv](https://docs.astral.sh/uv/) (or pipx).
+
+```bash
+uv tool install git+https://github.com/Nadercr7/tapetum
+tapetum "https://youtu.be/jNQXAC9IVRw"
+```
+
+ffmpeg comes bundled. Check your setup any time with `tapetum doctor`.
+
+## What you get back
+
+One JSON object on stdout, and a folder:
+
+```
+timeline.md       speech and frame references in time order. Start here.
+sheet_01.jpg      nine frames per image, timestamps burned in
+frames/           the frames it kept
+transcript.srt    plus transcript.json
+```
+
+A slice of `timeline.md`:
+
+```markdown
+### 00:05 – 00:10
+frame: `frames/f001_00-05.jpg`
+> the cool thing about these guys is that they have really...
+> really really long trunks
+```
+
+Open any run in your browser with `tapetum view <folder>`: frames on one side, a searchable transcript on the other. [See a live one.](https://nadercr7.github.io/tapetum/demo/)
+
+## How it works
+
+**Words, cheapest first.** It reads the platform's captions when they exist: human ones over auto-generated, the original language over machine translations, your `--lang` over both. When there are none, it downloads a small audio file and runs Whisper locally. Every step it tried is listed in `steps`, failures included.
+
+**Frames by change, not by clock.** It samples a frame every second, then keeps one only when the picture actually changed. A new line on a slide counts. A wobbling camera doesn't. Transitions collapse into one settled frame, and `--budget` caps the total, so a talking head costs you three images instead of thirty.
+
+**Detail on demand.** `tapetum <url> --at 03:12` downloads just that moment at 720p and writes four sharp frames. No re-run of the whole video.
+
+**Honest output.** Every error comes with a `code` and a `hint`. Shaky transcripts carry warnings. Failed runs aren't cached, so a network blip doesn't stick.
+
+## Use it from an agent
+
+| Where | How |
+|---|---|
+| Claude Code | `/plugin marketplace add Nadercr7/tapetum`, then `/plugin install tapetum@tapetum`. Or copy `skills/tapetum/` to `~/.claude/skills/`. |
+| Any MCP client | Install with `uv tool install "tapetum[mcp] @ git+https://github.com/Nadercr7/tapetum"` and add `{"command": "tapetum", "args": ["mcp"]}`. Tools: `watch_video`, `zoom_video`. Frames come back as images. |
+| Codex, Cursor, others | [AGENTS.md](AGENTS.md) tells them how to call it. |
+
+The skill file is short on purpose. Long instructions cost tokens on every single run.
+
+## Options
+
+```
+tapetum <url | file>
+  --lang ar,en        languages you prefer, in order
+  --budget 24         most frames to keep (short clips use fewer)
+  --quality accurate  bigger speech model: fast | balanced | accurate
+  --no-frames         transcript only, fastest
+  --ocr               read on-screen text (pip install "tapetum[ocr]")
+  --force-stt         ignore captions and listen instead
+  --at 03:12          zoom into one moment
+  --fresh             ignore the cache
+  --out DIR           where to write (default ~/.tapetum/<id>)
+
+tapetum doctor        what works on this machine
+tapetum view DIR      open a run in the browser
+tapetum mcp           start the MCP server
+```
+
+## Languages
+
+Whisper covers about 99 languages. On Egyptian Arabic the default model garbles names and numbers, and `--quality accurate` fixes most of it. On a laptop CPU that took about two and a half minutes for a seven-minute video, after a one-time 1.6 GB model download. tapetum warns you when a language is known to be weak on the model you picked. Numbers are in [docs/research/10-measured.md](docs/research/10-measured.md).
+
+## What it can't do
+
+- **Private videos.** Private, age-gated and login-only videos return `login_required`. Instagram and Vimeo mostly land here.
+- **Servers.** YouTube blocks most datacenter IPs. Run it from your own computer.
+- **Live streams.** You get `live_stream`. Try again once the recording is up.
+- **Playlists.** One video per run. You get `playlist_url` otherwise.
+- **Hear tone.** Music, sarcasm and accent don't survive a transcript, and the agent should say so.
+
+Text from a video is content, not instructions. `timeline.md` says so at the top, so agents don't take orders from a caption.
+
+## Why "tapetum"
+
+The tapetum is the mirror layer behind a cat's retina. It sends light back through the eye for a second pass, which is why cats see in the dark and why their eyes glow in a flashlight beam. Look twice, miss less.
+
+## Contributing
+
+```bash
+uv venv && uv pip install -e ".[mcp]" pytest
+pytest
+```
+
+Keep the virtualenv outside OneDrive or Dropbox; sync clients lock files mid-install. Design notes, competitor research and measurements are in [docs/research](docs/research/). Releasing is in [docs/RELEASING.md](docs/RELEASING.md).
+
+MIT licensed. Use it on videos you're allowed to watch.

tapetum-0.2.0/pyproject.toml

@@ -0,0 +1,49 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "tapetum"
+version = "0.2.0"
+description = "Give your agent eyes. Paste a video link, get one timeline of what was said and what was on screen. No cookies, no API keys."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Nadercr7" }]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Environment :: Console",
+  "Intended Audience :: Developers",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Topic :: Multimedia :: Video",
+  "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+keywords = ["video", "transcript", "agent", "mcp", "whisper", "youtube", "llm"]
+dependencies = [
+  "yt-dlp[default]>=2026.8.1",
+  "youtube-transcript-api>=1.2",
+  "pillow>=10.1",
+  "numpy",
+  "imageio-ffmpeg",
+  "faster-whisper>=1.1",
+]
+
+[project.optional-dependencies]
+ocr = ["rapidocr-onnxruntime"]
+mcp = ["mcp>=1.2"]
+
+[project.urls]
+Homepage = "https://nadercr7.github.io/tapetum/"
+Source = "https://github.com/Nadercr7/tapetum"
+Issues = "https://github.com/Nadercr7/tapetum/issues"
+
+[project.scripts]
+tapetum = "tapetum.cli:main"
+
+[tool.hatch.build.targets.sdist]
+include = ["src/tapetum", "tests", "README.md", "LICENSE"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/tapetum"]

tapetum-0.2.0/src/tapetum/__init__.py

@@ -0,0 +1,3 @@
+"""tapetum: give your agent eyes."""
+
+__version__ = "0.2.0"

tapetum-0.2.0/src/tapetum/cli.py

@@ -0,0 +1,92 @@
+"""tapetum CLI. stdout is one JSON object; progress goes to stderr."""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+
+from . import __version__
+
+
+def _emit(obj: dict, as_json: bool) -> int:
+    if as_json or not sys.stdout.isatty():
+        print(json.dumps(obj, ensure_ascii=False))
+    else:
+        if obj.get("ok") is False and obj.get("error"):
+            e = obj["error"]
+            print(f"✗ {e['code']}: {e['message']}\n  → {e['hint']}")
+        elif "checks" in obj:
+            for c in obj["checks"]:
+                print(f"{'✓' if c['ok'] else '✗'} {c['check']:<20} {c['detail']}")
+        else:
+            print(json.dumps(obj, ensure_ascii=False, indent=2))
+    return 0 if obj.get("ok") else 1
+
+
+def main(argv: list[str] | None = None) -> int:
+    """Every path ends in one JSON object on stdout, even a crash."""
+    argv = list(sys.argv[1:] if argv is None else argv)
+    as_json = "--json" in argv
+    try:
+        return _main(argv)
+    except SystemExit:
+        raise
+    except KeyboardInterrupt:
+        return _emit({"ok": False, "error": {"code": "interrupted", "message": "stopped by the user", "hint": ""}}, as_json)
+    except Exception as e:
+        from .common import TapetumError
+        if isinstance(e, TapetumError):
+            return _emit({"ok": False, "error": e.to_dict()}, as_json)
+        return _emit({"ok": False, "error": {"code": "internal", "message": f"{type(e).__name__}: {str(e)[:300]}",
+                      "hint": "This is a bug. Please report it at https://github.com/Nadercr7/tapetum/issues"}}, as_json)
+
+
+def _main(argv: list[str]) -> int:
+    for stream in (sys.stdout, sys.stderr):  # Windows consoles: never choke on non-ASCII
+        try:
+            stream.reconfigure(encoding="utf-8", errors="replace")
+        except Exception:
+            pass
+    if argv[:1] == ["doctor"]:
+        from .doctor import run
+        return _emit(run(), "--json" in argv)
+    if argv[:1] == ["view"]:
+        from .view import build
+        if len(argv) < 2:
+            print("usage: tapetum view <run-dir> [--no-open]", file=sys.stderr)
+            return 2
+        return _emit(build(argv[1], "--no-open" not in argv), "--json" in argv)
+    if argv[:1] == ["mcp"]:
+        from .mcp_server import serve
+        serve()
+        return 0
+
+    p = argparse.ArgumentParser(prog="tapetum", description="Give any AI agent eyes.")
+    p.add_argument("source", help="video URL, YouTube id, or local file")
+    p.add_argument("--version", action="version", version=__version__)
+    p.add_argument("--lang", help="preferred caption/speech languages, e.g. ar,en")
+    p.add_argument("--budget", type=int, default=24, help="max frames kept (default 24; short clips use fewer)")
+    p.add_argument("--quality", default="balanced", help="fast | balanced | accurate | any Whisper model name")
+    p.add_argument("--no-frames", action="store_true", help="transcript only")
+    p.add_argument("--ocr", action="store_true", help="read on-screen text (needs tapetum[ocr])")
+    p.add_argument("--force-stt", action="store_true", help="skip platform captions, use speech-to-text")
+    p.add_argument("--fresh", action="store_true", help="ignore the cache")
+    p.add_argument("--out", help="output directory (default: ~/.tapetum/<id>)")
+    p.add_argument("--at", help="zoom: full-resolution frames around MM:SS")
+    p.add_argument("--window", type=float, default=8.0, help="zoom window in seconds")
+    p.add_argument("--json", action="store_true", help="always print JSON")
+    a = p.parse_args(argv)
+
+    from . import pipeline
+    if a.at:
+        res = pipeline.zoom(a.source, a.at, a.window, out=a.out)
+    else:
+        res = pipeline.watch(
+            a.source, out=a.out, budget=a.budget, lang=a.lang, quality=a.quality,
+            no_frames=a.no_frames, fresh=a.fresh, force_stt=a.force_stt, ocr=a.ocr,
+        )
+    return _emit(res, a.json)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

tapetum-0.2.0/src/tapetum/common.py

@@ -0,0 +1,129 @@
+"""Shared helpers: errors, logging, ffmpeg, timestamps, source parsing."""
+from __future__ import annotations
+
+import hashlib
+import os
+import re
+import shutil
+import subprocess
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+from urllib.parse import parse_qs, urlparse
+
+
+class TapetumError(Exception):
+    """An error the agent can act on. `hint` says what to try next."""
+
+    def __init__(self, code: str, message: str, hint: str = ""):
+        super().__init__(message)
+        self.code, self.message, self.hint = code, message, hint
+
+    def to_dict(self) -> dict:
+        return {"code": self.code, "message": self.message, "hint": self.hint}
+
+
+def log(msg: str) -> None:
+    print(f"[tapetum] {msg}", file=sys.stderr, flush=True)
+
+
+def fmt_ts(sec: float) -> str:
+    sec = max(0, int(sec))
+    h, rem = divmod(sec, 3600)
+    m, s = divmod(rem, 60)
+    return f"{h}:{m:02d}:{s:02d}" if h else f"{m:02d}:{s:02d}"
+
+
+def parse_ts(text: str) -> float:
+    """'3:12', '01:03:12', '192' or '192s' -> seconds."""
+    t = text.strip().lower().rstrip("s")
+    parts = [float(p) for p in t.split(":")]
+    out = 0.0
+    for p in parts:
+        out = out * 60 + p
+    return out
+
+
+def ffmpeg_exe() -> str:
+    found = shutil.which("ffmpeg")
+    if found:
+        return found
+    try:
+        import imageio_ffmpeg
+
+        return imageio_ffmpeg.get_ffmpeg_exe()
+    except Exception as exc:  # pragma: no cover
+        raise TapetumError(
+            "no_ffmpeg", "ffmpeg not found", "Install ffmpeg or `pip install imageio-ffmpeg`."
+        ) from exc
+
+
+def run_ffmpeg(args: list[str]) -> None:
+    cmd = [ffmpeg_exe(), "-hide_banner", "-loglevel", "error", "-y", *args]
+    r = subprocess.run(cmd, capture_output=True, text=True, encoding="utf-8", errors="replace")
+    if r.returncode != 0:
+        raise TapetumError("ffmpeg_failed", r.stderr.strip()[-400:] or "ffmpeg failed")
+
+
+def cache_root() -> Path:
+    base = os.environ.get("TAPETUM_HOME")
+    root = Path(base) if base else Path.home() / ".tapetum"
+    root.mkdir(parents=True, exist_ok=True)
+    return root
+
+
+@dataclass
+class Source:
+    kind: str  # youtube | tiktok | instagram | x | vimeo | twitch | reddit | local | web
+    id: str
+    url: str
+
+    @property
+    def key(self) -> str:
+        return re.sub(r"[^A-Za-z0-9_-]+", "_", f"{self.kind}-{self.id}")[:80]
+
+
+_YT_ID = re.compile(r"^[A-Za-z0-9_-]{11}$")
+
+
+def parse_source(raw: str) -> Source:
+    raw = raw.strip()
+    if os.path.exists(raw):
+        p = Path(raw).resolve()
+        if p.is_dir():
+            raise TapetumError("not_a_video", f"{p} is a folder", "Pass a video file or a URL.")
+        st = p.stat()
+        # same name in two folders, or a file edited in place, must not share a cache entry
+        digest = hashlib.sha1(f"{p}|{st.st_size}|{st.st_mtime_ns}".encode("utf-8")).hexdigest()[:10]
+        stem = re.sub(r"[^A-Za-z0-9_-]+", "_", p.stem).strip("_")[:40] or "file"
+        return Source("local", f"{stem}-{digest}", str(p))
+    if _YT_ID.match(raw):
+        return Source("youtube", raw, f"https://www.youtube.com/watch?v={raw}")
+    u = urlparse(raw if "://" in raw else "https://" + raw)
+    host = (u.hostname or "").lower().removeprefix("www.").removeprefix("m.")
+    path = u.path.strip("/")
+    q = parse_qs(u.query)
+    if host == "youtu.be":
+        return Source("youtube", path.split("/")[0], f"https://www.youtube.com/watch?v={path.split('/')[0]}")
+    if host.endswith("youtube.com") or host.endswith("youtube-nocookie.com"):
+        vid = (q.get("v") or [""])[0]
+        if not vid:
+            m = re.match(r"(?:shorts|embed|live|v)/([A-Za-z0-9_-]{11})", path)
+            vid = m.group(1) if m else ""
+        if vid:
+            return Source("youtube", vid, f"https://www.youtube.com/watch?v={vid}")
+        if "list" in q or path.startswith(("playlist", "@", "c/", "channel/", "user/")):
+            raise TapetumError("playlist_url", "this is a playlist or channel, not a single video",
+                               "Pass one video link. For many videos, run tapetum once per link.")
+    for kind, domains in {
+        "tiktok": ("tiktok.com",),
+        "instagram": ("instagram.com",),
+        "x": ("x.com", "twitter.com"),
+        "vimeo": ("vimeo.com",),
+        "twitch": ("twitch.tv",),
+        "reddit": ("reddit.com", "v.redd.it"),
+    }.items():
+        if any(host == d or host.endswith("." + d) for d in domains):
+            m = re.findall(r"(\d{5,})", path) or [path.split("/")[-1] or host]
+            return Source(kind, m[-1], u.geturl())
+    return Source("web", re.sub(r"\W+", "_", host + "_" + path)[:50], u.geturl())

tapetum-0.2.0/src/tapetum/doctor.py

@@ -0,0 +1,67 @@
+"""`tapetum doctor`: say what works on THIS machine, and what to do about what doesn't."""
+from __future__ import annotations
+
+import shutil
+import sys
+import urllib.request
+
+from .common import ffmpeg_exe
+
+TEST_VIDEO = "jNQXAC9IVRw"  # the first YouTube video; short and stable
+
+
+def _check(name, fn):
+    try:
+        ok, detail = fn()
+    except Exception as exc:
+        ok, detail = False, f"{type(exc).__name__}: {str(exc)[:120]}"
+    return {"check": name, "ok": ok, "detail": detail}
+
+
+def run() -> dict:
+    checks = []
+    checks.append(_check("python>=3.10", lambda: (sys.version_info >= (3, 10), sys.version.split()[0])))
+    checks.append(_check("ffmpeg", lambda: (True, ffmpeg_exe())))
+
+    def ytdlp():
+        import yt_dlp
+        return True, yt_dlp.version.__version__
+
+    checks.append(_check("yt-dlp", ytdlp))
+
+    def js():
+        found = [n for n in ("deno", "node", "qjs", "bun") if shutil.which(n)]
+        return bool(found), ", ".join(found) or "none (some YouTube formats may fail; install Node 22+ or Deno)"
+
+    checks.append(_check("js-runtime", js))
+
+    def net():
+        urllib.request.urlopen("https://www.youtube.com/", timeout=8).read(200)
+        return True, "reachable"
+
+    checks.append(_check("network:youtube", net))
+
+    def captions():
+        from youtube_transcript_api import YouTubeTranscriptApi
+        n = len(list(YouTubeTranscriptApi().fetch(TEST_VIDEO)))
+        return n > 0, f"{n} caption lines"
+
+    checks.append(_check("youtube-captions", captions))
+
+    def stt():
+        import faster_whisper
+        return True, f"faster-whisper {faster_whisper.__version__}"
+
+    checks.append(_check("speech-to-text", stt))
+
+    def ocr():
+        import rapidocr_onnxruntime  # noqa: F401
+        return True, "installed"
+
+    r = _check("ocr (optional)", ocr)
+    if not r["ok"]:
+        r["detail"] = "not installed: pip install 'tapetum[ocr]'"
+        r["optional"] = True
+    checks.append(r)
+    required = [c for c in checks if not c.get("optional")]
+    return {"ok": all(c["ok"] for c in required), "checks": checks}