---
description: Use peepshow to extract frames from videos and animated images so you can view them as stills.
alwaysApply: false
---

# peepshow — video → frames

When the user shares a video (`.mp4` `.mov` `.mkv` `.webm` `.avi` `.flv` `.wmv` `.ts` `.mts` `.m2ts` `.3gp` `.ogv`) or animated image (`.gif` `.apng` animated `.webp`) — **including when they just drop the file into the chat** — extract frames and read them as images.

## How

```bash
peepshow "<path-or-url>" --emit json
```

Parse `frames[].path` from the stdout JSON, read each as an image (in order), use `video.tags` for context (title/director/producer/show/etc), and `video.durationSeconds` to estimate per-frame timestamps. Do **not** run on static images — Cursor handles those natively.

## Install

`npm i -g peepshow` — https://www.npmjs.com/package/peepshow. ffmpeg bundled via `ffmpeg-static`, native install optional (faster).

## Flags

`--emit paths|json|markdown|caveman` · `--stats off|short|full` · `--max N` · `--threshold 0..1` · `--fps N` · `--sink <name[:arg]>` · `--gpu auto|off|videotoolbox|cuda|qsv|vaapi|amf|d3d11va` · `--dedup on|auto|off` · `--dedup-distance 0..64` · `--adaptive on|off`

Manifest fields the LLM should read: `extraction.framesDeduped`, `extraction.dedupDistance`, `extraction.motionSignalAvg` (number) + `extraction.motionSignalLevel` (`low`/`medium`/`high`). Default-on dedup is 8×8 perceptual-hash; `--gpu auto` is duration+resolution aware (skips hwaccel on short/low-res clips); `--adaptive on` re-extracts denser when motion is high and there's headroom under `--max`.

## Annotate the report

Every run also writes `report.html` + `manifest.json` into the run's `outputDir`. Once you've understood the frames + transcript, pipe a JSON summary back so the report captures your synthesis:

```bash
echo '{"summary":"<2-4 sentences describing the timeline>","provider":"cursor"}' | peepshow report annotate "$OUTPUT_DIR"
```

`$OUTPUT_DIR` is the JSON payload's `outputDir` field. Whoever opens `report.html` later sees your understanding under "LLM analysis".

## Attach frames back to the workspace

`peepshow video.mp4 --sink ide` auto-detects Cursor and drops frames into `.cursor/attachments/peepshow/<timestamp>/`.