Video Compress To Size
Compresses a single video file to stay under a user-specified max file size using FFmpeg. Prefers GPU encoders (NVENC / AMF / QSV) with VBR bitrate targeting; falls back to CPU two-pass H.264/HEVC. Use when the user wants to compress video, reduce video file size, shrink MP4/MKV/MOV under N MB, GPU encode, NVENC compress, or re-encode a clip to a size limit.
Get the complete skill folder, including its scripts and reference files.
When to use this skill
Use Video Compress To Size when an AI agent needs a reusable SKILL.md workflow for this job: Compresses a single video file to stay under a user-specified max file size using FFmpeg. Prefers GPU encoders (NVENC / AMF / QSV) with VBR bitrate targeting; falls back to CPU two-pass H.264/HEVC. Use when the user wants to compress video, reduce video file size, shrink MP4/MKV/MOV under N MB, GPU encode, NVENC compress, or re-encode a clip to a size limit.
When not to use it
Skip Video Compress To Size when the task is outside the coding category, or when a more specific skill in this directory already covers the same workflow with clearer triggers.
How to install
Where will you use it?
mkdir -p ~/.claude/skills/video-compress-to-size # Save SKILL.md to ~/.claude/skills/video-compress-to-size/SKILL.md
- Claude Code personal install: place the skill and its bundled files at ~/.claude/skills/video-compress-to-size/SKILL.md. For a shared project, commit the folder at .claude/skills/video-compress-to-size/ instead.
- Current Claude Code detects SKILL.md changes in watched directories during the session. If you just created a top-level skills directory, run /reload-skills. Check that the skill is listed before testing its trigger.
- For Claude chat or Cowork in the Desktop app, manage uploaded skills in Customize > Skills; copying files into a local Claude Code folder is not a Desktop install. Other agents may use different install locations.
Full install guide for Claude, Cursor, and Codex →
Try a starter prompt
After installing the skill, paste this starter prompt into your agent to verify it triggers on a small task.
Use the Video Compress To Size skill for this task: Use Video Compress To Size when this documented workflow matches the task. Confirm any required inputs or files before making changes.
What supports this recommendation?
70/100 provisional content score. This measures documentation, practical detail and source signals. It is not a measured task success rate or a security certification.
- Documentation
- 77/100
- Practical detail
- 68/100
- Source evidence
- 61/100
- Source signals
- 72/100
Model compatibility evidence
- claudeuntested
No model-specific signal or recorded compatibility test was found.
- chatgptuntested
No model-specific signal or recorded compatibility test was found.
- geminiuntested
No model-specific signal or recorded compatibility test was found.
- copilotuntested
No model-specific signal or recorded compatibility test was found.
- llamauntested
No model-specific signal or recorded compatibility test was found.
- perplexityuntested
No model-specific signal or recorded compatibility test was found.
- mistraluntested
No model-specific signal or recorded compatibility test was found.
- grokuntested
No model-specific signal or recorded compatibility test was found.
Inferred compatibility is based on content signals. Check the app, its available tools and setup requirements before running a skill.
What this skill does
# Video Compress To Size
Re-encode a supported video so the output is **at or under** a given max file size.
**Default:** probe and use a GPU encoder when available (NVIDIA NVENC → AMD AMF → Intel QSV), single-pass VBR. If no GPU works, fall back to **CPU two-pass** (`libx264` / `libx265`).
## Rules
When this skill applies, read and follow [skill-dependency-manager](../skill-dependency-manager.md) — run scripts as documented, install missing tools into `.dependency/`.
- Run `compress.py` through **`.dependency/python/python.exe`**. Never use host `python` / `ffmpeg`. - **Never overwrite sources.** Outputs go under `video-compress-to-size/`. - Use the bundled script — do not hand-write equivalent FFmpeg commands. - **One file per run** — pass `--video` with a single file; repeat for each clip in a batch.
## Quick Start
```bash .dependency/python/python .ai/video-compress-to-size/compress.py --video path/to/clip.mp4 --max-size 50MB ```
Bare numbers mean **MB** (`--max-size 50` ≡ `50MB`):
```bash .dependency/python/python .ai/video-compress-to-size/compress.py --video assets/intro.mp4 --max-size 50 ```
Example:
``` assets/video/intro.mp4 → assets/video/video-compress-to-size/intro.mp4 ```
Force CPU (slow, more precise two-pass):
```bash .dependency/python/python .ai/video-compress-to-size/compress.py --video clip.mp4 --max-size 50MB --cpu ```
## Size Syntax
| Input | Meaning | |-------|---------| | `50` / `50MB` / `50M` | 50 mebibytes (1024² bytes) | | `500KB` / `500K` | 500 kibibytes | | `1GB` / `1G` | 1 gibibyte | | `52428800B` | exact bytes |
`--max-size` is **required**.
## Format Defaults
| Setting | Default | Notes | |---------|---------|-------| | Encoder | GPU first | `h264_nvenc` → `h264_amf` → `h264_qsv` → `libx264` | | HEVC | `--hevc` | Same order with `hevc_*` / `libx265` | | Container | `.mp4` | Always MP4 | | Audio | AAC 128k | Lowered automatically on tiny budgets | | Preset | `medium` | Mapped (e.g. NVENC `p4`); override with `--preset` | | Already under limit | Skipped | `[skip] … (already under limit)` | | Safety margin | GPU ~90% / CPU ~92% | Headroom for mux / VBR overshoot |
## Common Flags
`--video` · `--max-size` · `-o` / `--output` · `--audio-bitrate` · `--preset` · `--hevc` · `--cpu`
Custom output path:
```bash .dependency/python/python .ai/video-compress-to-size/compress.py --video clip.mp4 --max-size 50MB -o out/clip.mp4 ```
**Never overwrite source files.** Input must be a single video file (`--video`), not a directory. Supported inputs: `.mp4`, `.mkv`, `.mov`, `.avi`, `.webm`, `.wmv`, `.flv`, `.m4v`, `.mpeg`, `.mpg`, `.ts`, `.mts`, `.m2ts`, `.3gp`, `.ogv`.
## Agent Notes
1. Use the bundled script, not hand-written `ffmpeg` commands. 2. Always pass `--max-size` from the user (ask if missing). Prefer their unit wording; bare numbers are MB. 3. **Prefer GPU** — do not pass `--cpu` unless the user asks or GPU encode fails. 4. Do **not** downscale or change fps unless the user asks. 5. Sources already ≤ max size are skipped. 6. Tell the user where `video-compress-to-size/` files are; they swap assets manually when ready. 7. Missing Python/FFmpeg → populate `.dependency/` per skill-dependency-manager, retry same command. 8. Pipeline details: [reference.md](reference.md)
## Tests
From repo root:
```bash .dependency/python/python .ai/video-compress-to-size/test_compress.py ```
Manual CLI examples: [cli/video-compress-to-size.md](../../../cli/video-compress-to-size.md)
Intended uses
- Use Video Compress To Size when this documented workflow matches the task.
Implementation notes
- Review the source instructions and adapt inputs before running the workflow.
Try it, then tell us how it went
A copied prompt does not tell us whether the task worked. Report your result after checking the output. We collect your tool and outcome, never your files or prompt.