OpenParable
Skip to content
← Back to skills

Compress Video

Documents
compress-video

Compress Video is an Agent Skill for documents published in the gupsammy/Claudest repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

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".

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/gupsammy/Claudest/blob/HEAD/plugins/claude-content/skills/compress-video/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/compress-video, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

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.