watch-video-mcp 0.2.0__tar.gz

watch_video_mcp-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Marwan Mahmoud
+
+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.

watch_video_mcp-0.2.0/PKG-INFO

@@ -0,0 +1,200 @@
+Metadata-Version: 2.4
+Name: watch-video-mcp
+Version: 0.2.0
+Summary: MCP server and Claude skill that let an AI watch videos: timestamped transcript plus scene-selected keyframes, from local files or any yt-dlp URL.
+Author: Marwan Mahmoud
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/marwanm7moud/watch-video
+Project-URL: Issues, https://github.com/marwanm7moud/watch-video/issues
+Keywords: mcp,claude,video,transcription,keyframes,yt-dlp,parakeet,whisper
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Multimedia :: Video
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: mcp>=1.2
+Requires-Dist: yt-dlp
+Requires-Dist: numpy
+Requires-Dist: pillow
+Requires-Dist: onnx-asr[cpu,hub]>=0.10
+Provides-Extra: whisper
+Requires-Dist: faster-whisper>=1.0; extra == "whisper"
+Provides-Extra: ocr
+Requires-Dist: rapidocr-onnxruntime>=1.3; extra == "ocr"
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Dynamic: license-file
+
+# watch-video
+
+<!-- mcp-name: io.github.marwanm7moud/watch-video -->
+
+Let Claude (or any MCP client) **watch a video**. Give it a local file or a URL (YouTube and 1,500+
+other sites via yt-dlp) and it gets a timestamped transcript plus a handful of scene-selected
+keyframes, then drills into exact frames only when needed. No cloud transcription, no API keys.
+
+```text
+> Watch https://www.youtube.com/watch?v=jNQXAC9IVRw and tell me what he says about the elephants.
+
+$ video-cli overview https://www.youtube.com/watch?v=jNQXAC9IVRw --max-frames 8
+# Me at the zoo
+duration: 00:19
+transcript: platform-subs:en, language=en, 6 segments, took 0.4s
+keyframes: 3 scene-selected at 00:00, 00:05, 00:11
+total time: 6.7s
+
+## Transcript
+[00:01] All right, so here we are, in front of the elephants
+[00:05] the cool thing about these guys is that they have really... really really long trunks and that's cool
+[00:16] and that's pretty much all there is to say
+IMAGE: ~/.cache/video_mcp/Youtube_jNQXAC9IVRw/sheets_8/sheet_01.jpg
+
+Claude: He stands in front of the elephants (00:01) and says the cool thing about them is
+their really long trunks (00:05). That is the whole video (00:16).
+```
+
+## Why this one
+
+| | watch-video | Cloud video APIs (e.g. Gemini) | Transcript-only tools |
+|---|---|---|---|
+| Sees the screen (code, slides, charts, UI) | Yes: keyframes, hi-res frames, OCR | Yes | No |
+| Runs locally, nothing uploaded | Yes | No: the video goes to the provider | Varies |
+| API key or account | None | Required, billed per use | Varies |
+| Videos without captions | Local Parakeet / Whisper | Yes | Often fails |
+| Token cost of the visual pass | ~20 frames per contact sheet (cost of ~1.5 images) | Billed by video length | None (no visuals) |
+| Private recordings (meetings, bug repros) | Safe: never leave the machine | Uploaded | Varies |
+
+It ships as two parts:
+
+- **`video` MCP server** with six tools (below).
+- **`watch-video` skill** that teaches Claude the cheap-first workflow: overview, then frames, then ranges.
+
+## How it works
+
+| Step | What happens |
+|---|---|
+| Transcript | Platform subtitles if the video has them (seconds), else **Parakeet TDT 0.6B v3** (int8, CPU, 25 European languages), else **faster-whisper large-v3-turbo** (other languages, GPU or `language="auto"`). |
+| Keyframes | Decodes *only* keyframes at thumbnail size, drops repeats and static slides, then fills the largest time gaps. The selection adapts to how much the video changes (screencast vs. action). |
+| Contact sheets | Labelled frames tiled into grids: about 20 frames for the token cost of 1.5 full frames. Black bars are cropped automatically. |
+| Drill-down | `get_frames` seeks to exact timestamps at 1280 px (readable code and charts). For URLs it seeks into the stream without downloading the whole video. |
+
+Everything is cached under `~/.cache/video_mcp`, so repeat calls are instant.
+
+Measured on a mid-range CPU (i5-11400, no GPU): 35.7-minute local video overview in about 2.6 minutes;
+YouTube video with subtitles in about 7 seconds; a drill-down frame in about 0.5 seconds.
+
+## Install
+
+Requirements: Python 3.10+ and [ffmpeg](https://ffmpeg.org/download.html) (including `ffprobe`) on your PATH.
+
+### Claude Code: one command (plugin)
+
+Installs the MCP server and the skill together. Needs [uv](https://docs.astral.sh/uv/) for `uvx`.
+
+```text
+/plugin marketplace add marwanm7moud/watch-video
+/plugin install watch-video@watch-video
+```
+
+### Any agent: package, server, skill
+
+```bash
+pipx install watch-video-mcp          # or: uv tool install watch-video-mcp / pip install watch-video-mcp
+# optional extras: Whisper (non-European languages / GPU) and OCR (on-screen text as text)
+pipx install "watch-video-mcp[whisper,ocr]"
+# latest from GitHub instead of PyPI:
+pip install git+https://github.com/marwanm7moud/watch-video
+```
+
+No install needed to try the CLI: `uvx --from watch-video-mcp video-cli hw`.
+
+Install ffmpeg with `winget install Gyan.FFmpeg` (Windows), `brew install ffmpeg` (macOS) or
+`sudo apt install ffmpeg` (Linux). The first transcription downloads the Parakeet model (about 650 MB).
+
+### Register the MCP server
+
+Claude Code:
+
+```bash
+claude mcp add video --scope user -- video-mcp
+```
+
+Claude Desktop (`claude_desktop_config.json`) or any other MCP client:
+
+```json
+{ "mcpServers": { "video": { "command": "video-mcp" } } }
+```
+
+If `video-mcp` is not on your PATH, use the full path to the executable or `python -m video_mcp.server`.
+
+### Install the skill
+
+The skill works with or without the MCP server: it falls back to `video-cli` and installs it on first use.
+Copy the skill folder so your agent knows when and how to use the tools:
+
+```bash
+# macOS / Linux
+mkdir -p ~/.claude/skills && cp -r skills/watch-video ~/.claude/skills/
+# Windows (PowerShell)
+Copy-Item -Recurse skills\watch-video $HOME\.claude\skills\
+```
+
+Then ask Claude: *"Watch https://youtu.be/... and summarize it"*, or *"At what point do they explain the stop-loss, and what does the chart show then?"*
+
+## Tools
+
+| Tool | Use |
+|---|---|
+| `video_overview(source, max_frames=40, ocr=False)` | Start here: metadata, chapters, full transcript, contact sheets. `ocr=True` adds on-screen text. |
+| `get_frames(source, timestamps, hi_res=True)` | Exact frames (`"12:30"`, `"1:02:05"` or seconds), up to 20. |
+| `scan_range(source, start, end, count=12)` | Evenly spaced frames in one sheet, to follow motion or a demo. |
+| `get_transcript(source, start, end)` | Transcript slice. |
+| `search_transcript(source, query)` | Timestamped hits for any of the words, exact phrase first; plus on-screen text after an `ocr=True` overview. |
+| `check_hardware()` | Detected tools, GPU and the transcription profile in use. |
+
+## Command line
+
+The same operations work without MCP:
+
+```bash
+video-cli overview video.mp4 --max-frames 16
+video-cli overview demo.mp4 --ocr          # also read code/slides on screen
+video-cli frames https://youtu.be/... 12:30 13:05
+video-cli range video.mp4 10:00 10:30 --count 12
+video-cli search video.mp4 "stop loss"
+video-cli hw
+```
+
+## Configuration
+
+| Variable | Default | Effect |
+|---|---|---|
+| `VIDEO_MCP_CACHE` | `~/.cache/video_mcp` | Cache directory (delete it to reclaim space). |
+| `VIDEO_MCP_LANG` | `en` | Default transcription language; `auto` detects it with Whisper. |
+| `VIDEO_MCP_THREADS` | `4` (CPU) | Threads for CPU transcription. |
+| `VIDEO_MCP_AVX512` | unset | Set to `1` to let Whisper use AVX-512 (faster, but a very heavy sustained load). |
+
+On CPU the server runs below normal priority, one heavy job at a time, with Whisper held to AVX2, so a
+long transcription does not freeze your desktop.
+
+## Limitations
+
+- English is assumed unless you pass `language`. Parakeet covers 25 European languages on CPU (`language="de"`,
+  `"fr"`, `"es"`, ...). Other languages (Arabic, Chinese, Japanese, Hindi, ...) need Whisper, which is slow on CPU.
+- Frames are sampled, not every frame is analysed; the transcript can mishear names and terms. The skill tells
+  Claude to cite timestamps and confirm exact on-screen text with a hi-res frame.
+- Use it only on videos you are allowed to access and process; respect each site's terms and copyright.
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+ruff check .
+pytest
+```
+
+## License
+
+MIT. See [LICENSE](LICENSE).

watch_video_mcp-0.2.0/README.md

@@ -0,0 +1,171 @@
+# watch-video
+
+<!-- mcp-name: io.github.marwanm7moud/watch-video -->
+
+Let Claude (or any MCP client) **watch a video**. Give it a local file or a URL (YouTube and 1,500+
+other sites via yt-dlp) and it gets a timestamped transcript plus a handful of scene-selected
+keyframes, then drills into exact frames only when needed. No cloud transcription, no API keys.
+
+```text
+> Watch https://www.youtube.com/watch?v=jNQXAC9IVRw and tell me what he says about the elephants.
+
+$ video-cli overview https://www.youtube.com/watch?v=jNQXAC9IVRw --max-frames 8
+# Me at the zoo
+duration: 00:19
+transcript: platform-subs:en, language=en, 6 segments, took 0.4s
+keyframes: 3 scene-selected at 00:00, 00:05, 00:11
+total time: 6.7s
+
+## Transcript
+[00:01] All right, so here we are, in front of the elephants
+[00:05] the cool thing about these guys is that they have really... really really long trunks and that's cool
+[00:16] and that's pretty much all there is to say
+IMAGE: ~/.cache/video_mcp/Youtube_jNQXAC9IVRw/sheets_8/sheet_01.jpg
+
+Claude: He stands in front of the elephants (00:01) and says the cool thing about them is
+their really long trunks (00:05). That is the whole video (00:16).
+```
+
+## Why this one
+
+| | watch-video | Cloud video APIs (e.g. Gemini) | Transcript-only tools |
+|---|---|---|---|
+| Sees the screen (code, slides, charts, UI) | Yes: keyframes, hi-res frames, OCR | Yes | No |
+| Runs locally, nothing uploaded | Yes | No: the video goes to the provider | Varies |
+| API key or account | None | Required, billed per use | Varies |
+| Videos without captions | Local Parakeet / Whisper | Yes | Often fails |
+| Token cost of the visual pass | ~20 frames per contact sheet (cost of ~1.5 images) | Billed by video length | None (no visuals) |
+| Private recordings (meetings, bug repros) | Safe: never leave the machine | Uploaded | Varies |
+
+It ships as two parts:
+
+- **`video` MCP server** with six tools (below).
+- **`watch-video` skill** that teaches Claude the cheap-first workflow: overview, then frames, then ranges.
+
+## How it works
+
+| Step | What happens |
+|---|---|
+| Transcript | Platform subtitles if the video has them (seconds), else **Parakeet TDT 0.6B v3** (int8, CPU, 25 European languages), else **faster-whisper large-v3-turbo** (other languages, GPU or `language="auto"`). |
+| Keyframes | Decodes *only* keyframes at thumbnail size, drops repeats and static slides, then fills the largest time gaps. The selection adapts to how much the video changes (screencast vs. action). |
+| Contact sheets | Labelled frames tiled into grids: about 20 frames for the token cost of 1.5 full frames. Black bars are cropped automatically. |
+| Drill-down | `get_frames` seeks to exact timestamps at 1280 px (readable code and charts). For URLs it seeks into the stream without downloading the whole video. |
+
+Everything is cached under `~/.cache/video_mcp`, so repeat calls are instant.
+
+Measured on a mid-range CPU (i5-11400, no GPU): 35.7-minute local video overview in about 2.6 minutes;
+YouTube video with subtitles in about 7 seconds; a drill-down frame in about 0.5 seconds.
+
+## Install
+
+Requirements: Python 3.10+ and [ffmpeg](https://ffmpeg.org/download.html) (including `ffprobe`) on your PATH.
+
+### Claude Code: one command (plugin)
+
+Installs the MCP server and the skill together. Needs [uv](https://docs.astral.sh/uv/) for `uvx`.
+
+```text
+/plugin marketplace add marwanm7moud/watch-video
+/plugin install watch-video@watch-video
+```
+
+### Any agent: package, server, skill
+
+```bash
+pipx install watch-video-mcp          # or: uv tool install watch-video-mcp / pip install watch-video-mcp
+# optional extras: Whisper (non-European languages / GPU) and OCR (on-screen text as text)
+pipx install "watch-video-mcp[whisper,ocr]"
+# latest from GitHub instead of PyPI:
+pip install git+https://github.com/marwanm7moud/watch-video
+```
+
+No install needed to try the CLI: `uvx --from watch-video-mcp video-cli hw`.
+
+Install ffmpeg with `winget install Gyan.FFmpeg` (Windows), `brew install ffmpeg` (macOS) or
+`sudo apt install ffmpeg` (Linux). The first transcription downloads the Parakeet model (about 650 MB).
+
+### Register the MCP server
+
+Claude Code:
+
+```bash
+claude mcp add video --scope user -- video-mcp
+```
+
+Claude Desktop (`claude_desktop_config.json`) or any other MCP client:
+
+```json
+{ "mcpServers": { "video": { "command": "video-mcp" } } }
+```
+
+If `video-mcp` is not on your PATH, use the full path to the executable or `python -m video_mcp.server`.
+
+### Install the skill
+
+The skill works with or without the MCP server: it falls back to `video-cli` and installs it on first use.
+Copy the skill folder so your agent knows when and how to use the tools:
+
+```bash
+# macOS / Linux
+mkdir -p ~/.claude/skills && cp -r skills/watch-video ~/.claude/skills/
+# Windows (PowerShell)
+Copy-Item -Recurse skills\watch-video $HOME\.claude\skills\
+```
+
+Then ask Claude: *"Watch https://youtu.be/... and summarize it"*, or *"At what point do they explain the stop-loss, and what does the chart show then?"*
+
+## Tools
+
+| Tool | Use |
+|---|---|
+| `video_overview(source, max_frames=40, ocr=False)` | Start here: metadata, chapters, full transcript, contact sheets. `ocr=True` adds on-screen text. |
+| `get_frames(source, timestamps, hi_res=True)` | Exact frames (`"12:30"`, `"1:02:05"` or seconds), up to 20. |
+| `scan_range(source, start, end, count=12)` | Evenly spaced frames in one sheet, to follow motion or a demo. |
+| `get_transcript(source, start, end)` | Transcript slice. |
+| `search_transcript(source, query)` | Timestamped hits for any of the words, exact phrase first; plus on-screen text after an `ocr=True` overview. |
+| `check_hardware()` | Detected tools, GPU and the transcription profile in use. |
+
+## Command line
+
+The same operations work without MCP:
+
+```bash
+video-cli overview video.mp4 --max-frames 16
+video-cli overview demo.mp4 --ocr          # also read code/slides on screen
+video-cli frames https://youtu.be/... 12:30 13:05
+video-cli range video.mp4 10:00 10:30 --count 12
+video-cli search video.mp4 "stop loss"
+video-cli hw
+```
+
+## Configuration
+
+| Variable | Default | Effect |
+|---|---|---|
+| `VIDEO_MCP_CACHE` | `~/.cache/video_mcp` | Cache directory (delete it to reclaim space). |
+| `VIDEO_MCP_LANG` | `en` | Default transcription language; `auto` detects it with Whisper. |
+| `VIDEO_MCP_THREADS` | `4` (CPU) | Threads for CPU transcription. |
+| `VIDEO_MCP_AVX512` | unset | Set to `1` to let Whisper use AVX-512 (faster, but a very heavy sustained load). |
+
+On CPU the server runs below normal priority, one heavy job at a time, with Whisper held to AVX2, so a
+long transcription does not freeze your desktop.
+
+## Limitations
+
+- English is assumed unless you pass `language`. Parakeet covers 25 European languages on CPU (`language="de"`,
+  `"fr"`, `"es"`, ...). Other languages (Arabic, Chinese, Japanese, Hindi, ...) need Whisper, which is slow on CPU.
+- Frames are sampled, not every frame is analysed; the transcript can mishear names and terms. The skill tells
+  Claude to cite timestamps and confirm exact on-screen text with a hi-res frame.
+- Use it only on videos you are allowed to access and process; respect each site's terms and copyright.
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+ruff check .
+pytest
+```
+
+## License
+
+MIT. See [LICENSE](LICENSE).

watch_video_mcp-0.2.0/pyproject.toml

@@ -0,0 +1,51 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "watch-video-mcp"
+version = "0.2.0"
+description = "MCP server and Claude skill that let an AI watch videos: timestamped transcript plus scene-selected keyframes, from local files or any yt-dlp URL."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.10"
+authors = [{ name = "Marwan Mahmoud" }]
+keywords = ["mcp", "claude", "video", "transcription", "keyframes", "yt-dlp", "parakeet", "whisper"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Operating System :: OS Independent",
+    "Topic :: Multimedia :: Video",
+]
+dependencies = [
+    "mcp>=1.2",
+    "yt-dlp",
+    "numpy",
+    "pillow",
+    "onnx-asr[cpu,hub]>=0.10",
+]
+
+[project.optional-dependencies]
+whisper = ["faster-whisper>=1.0"]
+ocr = ["rapidocr-onnxruntime>=1.3"]
+dev = ["pytest>=8", "ruff"]
+
+[project.urls]
+Homepage = "https://github.com/marwanm7moud/watch-video"
+Issues = "https://github.com/marwanm7moud/watch-video/issues"
+
+[project.scripts]
+video-mcp = "video_mcp.server:main"
+video-cli = "video_mcp.cli:main"
+
+[tool.setuptools]
+packages = ["video_mcp"]
+
+[tool.ruff]
+line-length = 120
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "W"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

watch_video_mcp-0.2.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

watch_video_mcp-0.2.0/tests/test_frames.py

@@ -0,0 +1,66 @@
+import subprocess
+
+import numpy as np
+import pytest
+from PIL import Image
+
+from video_mcp import frames as fr
+from video_mcp.hw import find_bin
+
+
+def test_select_picks_changes_and_respects_budget():
+    # 30 keyframes: three visually distinct "slides", each repeated 10 times
+    thumbs = [np.full((fr.THUMB, fr.THUMB), v, np.int16) for v in (0, 120, 240) for _ in range(10)]
+    frames = [(float(i * 10), t) for i, t in enumerate(thumbs)]
+    picked = fr.select(frames, 300, max_frames=6)
+    assert picked[0] == 0
+    assert {0.0, 100.0, 200.0} <= set(picked)
+    assert len(picked) <= 6
+
+
+def test_select_empty():
+    assert fr.select([], 10) == []
+
+
+@pytest.fixture(scope="module")
+def clip(tmp_path_factory):
+    try:
+        ffmpeg = find_bin("ffmpeg")
+    except FileNotFoundError:
+        pytest.skip("ffmpeg not installed")
+    path = tmp_path_factory.mktemp("clip") / "clip.mp4"
+    subprocess.run([ffmpeg, "-v", "error", "-y", "-f", "lavfi", "-i", "testsrc=size=320x240:rate=10:duration=6",
+                    "-g", "10", "-pix_fmt", "yuv420p", str(path)], check=True)
+    return str(path)
+
+
+def test_scan_extract_and_contact_sheet(clip, tmp_path):
+    kf = fr.scan_keyframes(clip)
+    assert len(kf) >= 5
+    out = fr.extract(clip, [0, 2.5, 5], str(tmp_path / "f"), long_side=256)
+    assert len(out) == 3
+    assert max(Image.open(out[0][1]).size) == 256
+    sheets = fr.contact_sheets(out, str(tmp_path / "s"))
+    assert len(sheets) == 1
+
+
+def test_is_sparse():
+    assert fr.is_sparse(2, 600, 40)  # 10-min screencast with 2 keyframes
+    assert not fr.is_sparse(3, 19, 8)  # short clip: few keyframes are fine
+    assert not fr.is_sparse(60, 600, 40)
+
+
+def test_sparse_keyframes_fall_back_to_timed_samples(tmp_path):
+    try:
+        ffmpeg = find_bin("ffmpeg")
+    except FileNotFoundError:
+        pytest.skip("ffmpeg not installed")
+    path = str(tmp_path / "long_gop.mp4")
+    # one keyframe for the whole 60 s clip, like a screen recording
+    subprocess.run([ffmpeg, "-v", "error", "-y", "-f", "lavfi", "-i", "testsrc=size=160x120:rate=5:duration=60",
+                    "-g", "9999", "-keyint_min", "9999", "-sc_threshold", "0", "-pix_fmt", "yuv420p", path],
+                   check=True)
+    assert len(fr.scan_keyframes(path)) <= 2
+    frames = fr.scan(path, 60, 40)
+    assert len(frames) >= 20
+    assert len(fr.select(frames, 60, max_frames=10)) >= 5

watch_video_mcp-0.2.0/tests/test_ocr.py

@@ -0,0 +1,24 @@
+import pytest
+from PIL import Image, ImageDraw
+
+from video_mcp import ocr
+
+
+def test_new_lines_drops_repeats_and_empty_frames():
+    per = [(0, ["Title", "intro"]), (5, ["Title", "intro"]), (10, ["Title", "step 1"]), (15, [])]
+    assert ocr.new_lines(per) == [(0, ["Title", "intro"]), (10, ["step 1"])]
+
+
+def test_format_ocr_truncates():
+    out = ocr.format_ocr([(0, ["x" * 50]), (60, ["y" * 50])], limit=60)
+    assert out.startswith("[00:00] ")
+    assert "truncated" in out
+
+
+@pytest.mark.skipif(not ocr.available(), reason="rapidocr not installed")
+def test_reads_text_from_image(tmp_path):
+    p = tmp_path / "s.png"
+    im = Image.new("RGB", (900, 200), "white")
+    ImageDraw.Draw(im).text((20, 40), "def hello(name):", fill="black")
+    im.save(p)
+    assert any("hello" in ln.replace(" ", "") for ln in ocr._read(str(p)))

watch_video_mcp-0.2.0/tests/test_text.py

@@ -0,0 +1,60 @@
+import json
+from types import SimpleNamespace
+
+import pytest
+
+from video_mcp.core import parse_ts, search_transcript
+from video_mcp.source import is_url
+from video_mcp.transcribe import as_text, fmt_ts
+
+
+@pytest.mark.parametrize("raw,expected", [("90", 90), ("1:30", 90), ("1:02:05", 3725), (12.5, 12.5), (" 0:10 ", 10)])
+def test_parse_ts(raw, expected):
+    assert parse_ts(raw) == expected
+
+
+@pytest.mark.parametrize("secs,expected", [(0, "00:00"), (65, "01:05"), (3725, "1:02:05")])
+def test_fmt_ts(secs, expected):
+    assert fmt_ts(secs) == expected
+
+
+def test_is_url():
+    assert is_url("https://youtu.be/abc")
+    assert is_url("HTTP://example.com/v.mp4")
+    assert not is_url(r"C:\videos\clip.mp4")
+
+
+def test_as_text_merges_close_fragments_only():
+    segs = [{"start": 0, "end": 1, "text": "hello"}, {"start": 1.2, "end": 2, "text": "world"},
+            {"start": 10, "end": 11, "text": "later"}]
+    assert as_text(segs) == "[00:00] hello world\n[00:10] later"
+
+
+def _fake_video(monkeypatch, tmp_path, texts):
+    segs = [{"start": i * 5, "end": i * 5 + 4, "text": t} for i, t in enumerate(texts)]
+    monkeypatch.setattr("video_mcp.core.get_video", lambda src: SimpleNamespace(dir=str(tmp_path)))
+    monkeypatch.setattr("video_mcp.core.transcribe", lambda v: {"segments": segs})
+
+
+def test_search_transcript_matches_any_word(monkeypatch, tmp_path):
+    _fake_video(monkeypatch, tmp_path, ["intro", "buy gold", "outro"])
+    out = search_transcript("x", "GOLD silver")["text"]
+    assert out.startswith("1 hits")
+    assert "[00:05] buy gold" in out
+    assert search_transcript("x", "nothing")["text"] == "no hits for 'nothing'"
+
+
+def test_search_transcript_ranks_exact_phrase_first(monkeypatch, tmp_path):
+    texts = ["stop here", "a", "b", "loss only", "c", "d", "set the stop loss now", "e", "f", "stop and loss"]
+    _fake_video(monkeypatch, tmp_path, texts)
+    out = search_transcript("x", "Stop  Loss", context=0)["text"]
+    order = [out.index(t) for t in ["stop loss now", "stop and loss", "stop here", "loss only"]]
+    assert order == sorted(order)
+
+
+def test_search_transcript_includes_cached_ocr(monkeypatch, tmp_path):
+    _fake_video(monkeypatch, tmp_path, ["intro"])
+    (tmp_path / "ocr.json").write_text(json.dumps({"65.00": ["Error: disk full"], "3.00": ["Welcome"]}))
+    out = search_transcript("x", "error")["text"]
+    assert "no hits for 'error'" in out
+    assert "## On screen (OCR keyframes)\n[01:05] Error: disk full" in out

watch_video_mcp-0.2.0/video_mcp/__init__.py

@@ -0,0 +1,14 @@
+"""video_mcp: let Claude "watch" videos via transcripts + smart keyframes."""
+import os
+
+__version__ = "0.2.0"
+
+# HF's Xet transfer can stall model downloads on some networks; plain HTTPS is reliable.
+os.environ.setdefault("HF_HUB_DISABLE_XET", "1")
+os.environ.setdefault("HF_HUB_DISABLE_PROGRESS_BARS", "1")
+
+# AVX-512 int8 on all cores is the heaviest load a desktop CPU can run (big power/heat spikes,
+# and it destabilised at least one machine), so CTranslate2 is held to AVX2 unless
+# VIDEO_MCP_AVX512=1. Must be set before ctranslate2 is imported.
+if os.environ.get("VIDEO_MCP_AVX512") != "1":
+    os.environ.setdefault("CT2_FORCE_CPU_ISA", "AVX2")