Metadata-Version: 2.4
Name: amagi-screen
Version: 0.1.0
Summary: Let Claude watch you reproduce a bug: key frames, on-screen text, and a timeline from any screen recording.
Author-email: "AmagiLabs (Amagisolutionsgroup, Inc.)" <dev@amagisolutionsgroup.com>
License: MIT
Project-URL: Homepage, https://github.com/amagilabs/amagi-screen
Project-URL: Source, https://github.com/amagilabs/amagi-screen
Project-URL: Issues, https://github.com/amagilabs/amagi-screen/issues
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pytesseract>=0.3.10
Requires-Dist: Pillow>=10.0.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Dynamic: license-file

# amagi-screen

Send Claude a video of your bug, not a paragraph describing it.

![demo](assets/demo.gif)

amagi-screen turns a screen recording into something Claude can actually
read: it detects every moment the screen changes, saves a frame for each
one, reads any on-screen text with OCR, and flags frames that look like an
error or exception. Everything lands in one `index.md` in timestamp order.

Everything runs locally. There are no API keys and nothing leaves your
machine.

## Install

```
pipx install amagi-screen
```

You also need [ffmpeg](https://ffmpeg.org/) on your PATH. OCR is optional
and needs the [tesseract](https://github.com/tesseract-ocr/tesseract)
binary — without it, amagi-screen still extracts the frame timeline, just
without on-screen text or error flags.

## Usage

```
amagi-screen <recording> [-o OUTDIR] [--threshold 0.12] [--max-frames 60] [--no-ocr]
```

| Option | What it does |
|---|---|
| `-o`, `--outdir` | Where run folders go (default `amagi_screen_out`) |
| `--threshold` | Scene-change sensitivity, 0–1 (default `0.12`; lower catches subtler UI changes) |
| `--max-frames` | Most key frames to keep (default 60) |
| `--no-ocr` | Skip OCR even if tesseract is installed |

Example:

```
amagi-screen ./bug_repro.mp4 -o runs
```

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>/<recording_name>/`:

- `index.md`: the file to read. Each detected frame, in time order, with
  its OCR'd text and a `⚠ possible <word>` flag when the text looks like
  an error, exception, or failure.
- `events.md`: just the flagged frames — usually the fastest way to find
  the moment something broke.
- `frames/`: JPEG frames named `frame_<seconds>s.jpg`, 1280 px wide.
- `metadata.json`: title, source path, duration, frame count, and whether
  OCR ran.

Real output from a 6-second test clip with two scene changes (no tesseract
installed in this run, so no on-screen text — see Limitations):

```markdown
# demo_recording

- Source recording: demo_recording.mp4
- Duration: 00:06
- OCR: unavailable (install tesseract for on-screen text)

## Timeline

**[00:02]** see frame: frames/frame_00002s.jpg

**[00:04]** see frame: frames/frame_00004s.jpg
```

## Use it as a Claude Code skill

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

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

When you paste a screen recording and ask what went wrong, Claude runs
`amagi-screen`, reads `index.md` and `events.md`, and opens the frames it
needs.

## Limitations

- OCR needs tesseract on PATH. Without it, frames still get extracted, but
  there's no on-screen text and no error flagging.
- Scene detection finds a different number of frames depending on how much
  the UI actually changes. A very static recording (one screen, no clicks)
  falls back to a fixed interval sample instead.
- Frames are stills. Fast cursor movement, animation, and quick modal
  flashes between two detected frames are lost.
- `--threshold` needs tuning per app: dense, animated UIs need a higher
  threshold than static dashboards, or you'll get too many near-duplicate
  frames.

## Related AmagiLabs projects

- [amagi-watch](https://github.com/amagilabs/amagi-watch) — give Claude a
  video URL and get back a transcript + key frames.
- [amagi-listen](https://github.com/amagilabs/amagi-listen) — give Claude
  a podcast or meeting recording and get back a chaptered transcript.
- [legal-review-skills](https://github.com/amagilabs/legal-review-skills)
- More tools at [github.com/amagilabs](https://github.com/amagilabs).

If amagi-screen saves you a round trip explaining a bug, a star helps
other people find it.

## Legal

amagi-screen only reads files you point it at. It doesn't upload, store,
or transmit recordings anywhere.

## License

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

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