compress-video - SKILL.md Agent Skill

name: compress-video description: > This skill should be used when the user asks to "compress this video", "reduce file size", "make this video smaller", "optimize for web", "shrink this video", "compress to under X MB", "reduce bitrate", "make it smaller without losing quality", "encode with H.265", or "re-encode this video". allowed-tools: - Bash(ffprobe:) - Bash(ffmpeg:) - AskUserQuestion

Video Compress

Compress a video using quality-based (CRF) or size-based (2-pass) encoding.

Process

1. Obtain input file

If the user did not provide a file path, ask for it with AskUserQuestion before proceeding.

2. Probe the source

ffprobe -v quiet -print_format json -show_streams -show_format "$INPUT"

Extract: duration (seconds), file size (bytes), existing video codec, audio bitrate. If ffprobe fails (file not found, not a valid video), report the error and stop — do not attempt encoding.

3. Determine mode from user intent

CRF mode (quality-based): user says "without losing quality", "good quality", "make it smaller", or gives no size target
2-pass mode (size-based): user specifies a target ("under 50MB", "around 20MB", "fit on X")

4. Choose codec

H.264 is the safe default: universally device-compatible and fast to encode. Use H.265 only when the size reduction justifies the slower encode time and narrower device support.

H.265 / libx265: target is ≤50% of original size, or user asks for "maximum compression" / "HEVC"
H.264 / libx264: otherwise — faster encode, wider device compatibility, safe default

5. Construct command

CRF mode:

ffmpeg -i "$INPUT" -c:v libx264 -crf 23 -c:a copy -movflags +faststart "$OUTPUT"
# CRF scale: 18=near-lossless, 23=default quality, 28=aggressive (visible loss)
# -movflags +faststart moves moov atom to front — enables progressive web playback

2-pass mode — calculate video bitrate first:

python3 ${CLAUDE_PLUGIN_ROOT}/skills/compress-video/scripts/calc_bitrate.py "$INPUT" --target-mb "$TARGET_MB"
# Outputs: VIDEO_BITRATE_KBPS (integer)
# Formula: (target_mb * 8192 / duration_s) - audio_bitrate_kbps
# Typical audio budget: 128 kbps
# Exit 1 = target too small (bitrate would go negative); report the error and ask for a larger target before retrying.

# Pass 1 — video analysis only, no output file:
ffmpeg -y -i "$INPUT" -c:v libx264 -b:v ${VIDEO_BITRATE_KBPS}k -pass 1 -an -f null /dev/null

# Pass 2 — final encode with audio:
ffmpeg -i "$INPUT" -c:v libx264 -b:v ${VIDEO_BITRATE_KBPS}k -pass 2 \
  -c:a aac -b:a 128k -movflags +faststart "$OUTPUT"

6. Confirm with user

Show: input file size, chosen codec, mode (CRF value or calculated bitrate), output path. Wait for approval before running.

7. Run and report

After completion: input size → output size, compression ratio (e.g., "73.2 MB → 18.4 MB, 75% reduction").

Key Decisions

In CRF mode, use -c:a copy to preserve audio losslessly. In 2-pass mode, audio must be re-encoded (AAC 128k) because pass 1 is video-only — no audio stream is processed.
If input is already H.264 and the user only wants to trim or remux, recommend convert-video with -c copy instead — instant and lossless.
For H.265 output, substitute libx265 and add -tag:v hvc1 for Apple device compatibility.
Clean up ffmpeg2pass-0.log and ffmpeg2pass-0.log.mbtree after 2-pass encoding completes.