amagi-watch

Give Claude a video URL and get back something it can read: a timestamped transcript and key frames, merged into one markdown file.

Claude can read text and images but can't play a video. amagi-watch turns a video into those two things on your own machine. It downloads the video with yt-dlp, uses the platform's captions when they exist (and transcribes locally with faster-whisper when they don't), pulls key frames with ffmpeg scene detection, and writes an index.md that puts transcript lines and frame references in timestamp order.

Everything runs locally. There are no API keys and nothing goes to a cloud service, apart from yt-dlp downloading the video itself.

Install

pipx install --python 3.12 amagi-watch

You also need these on your PATH:

• yt-dlp
• ffmpeg

Python 3.10 to 3.13. faster-whisper is installed as a dependency, and its audio decoder needs PyAV older than 14, which has no Python 3.14 build. If your default Python is 3.14, keep the --python 3.12 flag (any of 3.10-3.13 works). The first transcription downloads the Whisper model you pick.

Usage

amagi-watch <url> [-o OUTDIR] [--cookies-from-browser chrome] [--model small] [--max-frames 32] [--keep-video]

Examples:

# A public YouTube video
amagi-watch "https://www.youtube.com/watch?v=aqz-KE-bpKQ" -o runs

# A fast, rough pass on a long video
amagi-watch "<url>" --model tiny --max-frames 16

# A site that needs you to be logged in
amagi-watch "<url>" --cookies-from-browser chrome

The last line of stdout is the path to the run folder, so scripts and agents can pick it up.

Output

Each run writes <outdir>/<video_id>_<title>/:

• index.md: the file to read. Transcript lines and frame references in time order.
• transcript.md: the transcript by itself.
• frames/: JPEG key frames named frame_<seconds>s.jpg, 640 px wide.
• metadata.json: title, uploader, duration, description and URL.

Excerpt from a run on Big Buck Bunny (Blender Foundation, CC BY 3.0). The film has no dialogue, so this timeline is all frames:

# Big Buck Bunny 60fps 4K - Official Blender Foundation Short Film

- Source: https://www.youtube.com/watch?v=aqz-KE-bpKQ
- Uploader: Blender
- Duration: 635s
- Transcript source: faster-whisper (small)

## Timeline

> see frame: frames/frame_00000s.jpg

> see frame: frames/frame_00019s.jpg

> see frame: frames/frame_00039s.jpg

When a video has speech, lines like **[00:16]** ... appear between the frames.

Use it as a Claude Code skill

The repo includes a SKILL.md. Copy it into your skills folder:

mkdir -p ~/.claude/skills/amagi-watch
cp SKILL.md ~/.claude/skills/amagi-watch/SKILL.md

When you paste a video link and ask what it says or shows, Claude runs amagi-watch, reads index.md, and opens the frames it needs.

Limitations

• Instagram, TikTok and X often need --cookies-from-browser. Without valid cookies the download fails.
• Whisper on CPU runs at roughly real time or slower with small. Captions are much faster when the platform has them.
• Scene detection finds a different number of frames for each video. If it finds too few or too many, the tool takes frames at a fixed interval instead.
• Frames are stills. Motion, on-screen animation and fast cuts between frames are lost.
• Platform captions are fetched in English only. Whisper detects the spoken language on its own.

Related projects

Other people have tackled the same problem, and their tools may suit you better:

• claude-real-video
• claude-video
• watchvideo

amagi-watch is a single small Python file with no API keys, and its output is one markdown file built for an LLM to read.

Legal

Only download videos you have the right to download. Follow each platform's terms of service and respect copyright. amagi-watch is for personal research and analysis. It doesn't grant rights to any content it processes.

License

MIT. Copyright (c) 2026 AmagiLabs (Amagisolutionsgroup, Inc.). See LICENSE.

Built by AmagiLabs.