Video Compressor

View saved version →

---
name: video-compression
description: >-
  Compress video files to a much smaller size without visible quality loss, using HEVC
  and ffmpeg (or macOS avconvert), with verification and the original left untouched.
  Use when the user asks to compress, shrink, reduce, or resize a video, make a video
  smaller, fit it under a size limit (Discord, WhatsApp, email, Slack), re-encode iPhone
  or screen recordings, convert to HEVC or H.264, batch-compress a folder of clips, or
  free up disk space taken by videos. Also use for questions about video bitrate,
  HEVC versus H.264, or why a video file is so large. Skips files that are already
  efficient, so a re-encode never makes a file bigger.
---

# Video Compression

Compress videos with a script that decides first, encodes second, and verifies the result. The original file is never modified,
moved or deleted. The output is a new file named `<name>.compressed.mp4` next to the source (or in `--out-dir`).

The script is `scripts/video_compress.py` in this skill folder. It uses only the Python 3 standard library and prints compact JSON.
Add `--human` after the subcommand for readable text. Quote paths, because they often contain spaces. The commands below use the
script path relative to this skill folder. Use its absolute path when your working directory is somewhere else.

## Step 1: Check what this environment can do

```bash
python3 scripts/video_compress.py doctor
```

| Tier | What is available | What you can do |
| --- | --- | --- |
| 1 | Local machine with `ffmpeg` and `ffprobe` | Everything below. |
| 1b | macOS with only `/usr/bin/avconvert` | Four fixed presets. No size targets, no `--compat`. |
| 2 | `ffmpeg` without `ffprobe` (hosted sandbox) | Compress short clips only (120 seconds, 450 MB). Limited probe detail. |
| 3 | No encoder | Advisor mode: run `advise` and give the user exact commands. |

`doctor` never installs anything. If the tier is 3 and the user wants files compressed here, show the `install_hints` and ask first.
`--allow-download` fetches a static ffmpeg into the skill folder with pip, only when the user agrees.

## Step 2: Probe, plan, run, verify

```bash
python3 scripts/video_compress.py probe "clip.mov"
python3 scripts/video_compress.py plan "clip.mov" --preset balanced
python3 scripts/video_compress.py run "clip.mov" --preset balanced
```

- `probe` reports codec, display resolution, rotation, frame rate, bitrate, HDR, audio and warnings.
- `plan` decides per file whether compression is worthwhile and estimates the result. Show it to the user for large batches.
- `run` encodes, verifies automatically and deletes a failed output. It also accepts a folder (`--recursive` for subfolders).
- `verify ORIGINAL OUTPUT` repeats the checks on its own: duration, audio, frame rate, resolution and that the file is smaller.

Report the `summary` and any skipped files with their reasons. Do not describe a skipped file as a failure. A file at 5 Mbps
HEVC is already efficient, and skipping it is the correct result.

## Choosing options

| User wants | Use |
| --- | --- |
| Smaller, same look (default) | `--preset balanced` |
| Best quality, only clearly oversized files | `--preset premium` or `high` |
| Smallest file, softer picture is fine | `--preset max-saving` |
| Fit under a limit | `--target discord`, `--target whatsapp`, `--target email`, `--target slack` or `--target-mb 25` |
| Plays on old TVs, browsers or editors | `--compat` (H.264, larger) |
| Leave HDR clips alone | `--hdr skip` |
| Output elsewhere | `--out-dir DIR` |

Preset and skip rules are in `references/presets.md`. Platform limits and their sources are in `references/platform-limits.md`.

## Rules for the agent

- Ask before compressing more than a handful of files, and before using `--allow-download`.
- Never delete the original yourself. If the user wants it gone after checking the result, let them do it or ask explicitly.
- A `skipped` file is not an error. Explain the reason in one line.
- K

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 11 — file references are metadata, not package contents.