Metadata-Version: 2.4
Name: amagi-watch
Version: 0.1.1
Summary: Let Claude watch videos: transcript + key frames from any URL, fully local.
Author-email: "AmagiLabs (Amagisolutionsgroup, Inc.)" <dev@amagisolutionsgroup.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/amagilabs/amagi-watch
Project-URL: Source, https://github.com/amagilabs/amagi-watch
Project-URL: Issues, https://github.com/amagilabs/amagi-watch/issues
Keywords: claude,claude-code,video,transcript,whisper,yt-dlp,ffmpeg,llm
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Multimedia :: Video
Classifier: Topic :: Utilities
Requires-Python: <3.14,>=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: faster-whisper>=1.0.0
Requires-Dist: av<14,>=11
Dynamic: license-file

# 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](https://github.com/yt-dlp/yt-dlp)
- [ffmpeg](https://ffmpeg.org/)

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]
```

| Option | What it does |
|---|---|
| `-o`, `--outdir` | Where run folders go (default `amagi_watch_out`) |
| `--cookies-from-browser` | Browser to borrow login cookies from (for example `chrome`), for sites that need a login |
| `--model` | faster-whisper size: `tiny`, `base`, `small` (default), `medium`, `large-v3` |
| `--max-frames` | Most key frames to keep (default 32) |
| `--keep-video` | Keep the downloaded video (deleted by default) |

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:

```markdown
# 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](https://github.com/HUANGCHIHHUNGLeo/claude-real-video)
- [claude-video](https://github.com/bradautomates/claude-video)
- [watchvideo](https://github.com/charlesdove977/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](LICENSE).

Built by [AmagiLabs](https://amagilabs.ai).
