Compress Video
- 34 installs
- 269 repo stars
- Updated June 11, 2026
- gupsammy/claudest
Compress-video is an agent skill that calculates FFmpeg 2-pass video bitrates from a target file size in MB using ffprobe and a Python CLI.
About
Compress-video packages a small Python utility for solo builders who ship screen recordings, trailers, or tutorial footage and need predictable file sizes. Given an input path and `--target-mb`, it probes duration via ffprobe, subtracts the audio bitrate budget (default 128 kbps), and prints the recommended video bitrate in kilobits per second for two-pass FFmpeg `-b:v`. Diagnostics on stderr help verify duration and budget math when encodes overshoot or undershoot targets. The skill assumes FFmpeg/ffprobe are installed locally and fits terminal-driven agent sessions where the coder shells out to encoding pipelines. It is not a full GUI compressor or cloud transcoder—it is a precise bitrate calculator glue step before you run ffmpeg commands.
- Python helper calc_bitrate.py outputs integer -b:v kbps on stdout for FFmpeg
- Uses ffprobe JSON for duration and stream/format introspection
- --target-mb required budget with optional --audio-kbps (default 128)
- stderr carries source info and budget breakdown for debugging passes
- Designed for 2-pass FFmpeg encoding workflows
Compress Video by the numbers
- 34 all-time installs (skills.sh)
- Ranked #949 of 1,335 Generative Media skills by installs in the Skillselion catalog
- Security screen: LOW risk (skills.sh audit)
- Data as of Aug 4, 2026 (Skillselion catalog sync)
npx skills add https://github.com/gupsammy/claudest --skill compress-videoAdd your badge
Show developers this skill is listed on Skillselion. Paste this into your README.
| Installs | 34 |
|---|---|
| repo stars | ★ 269 |
| Security audit | 3 / 3 scanners passed |
| Last updated | June 11, 2026 |
| Repository | gupsammy/claudest ↗ |
What it does
Compute FFmpeg 2-pass video bitrates from a target output size in MB using ffprobe duration and configurable audio kbps.
Who is it for?
Best when you're automating trailer or demo exports with FFmpeg and target exact upload limits.
Skip if: Users without ffprobe/ffmpeg installed or anyone needing one-click cloud transcoding without shell tools.
When should I use this skill?
User needs video bitrate for 2-pass FFmpeg encoding given input file and --target-mb (optional --audio-kbps).
What you get
You get an integer kbps video bitrate on stdout ready to plug into FFmpeg while stderr explains the size budget split.
- Integer kbps value for FFmpeg -b:v
- stderr diagnostic budget breakdown
By the numbers
- Default audio budget: 128 kbps
Files
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 playback2-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 copyto 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-videowith-c copyinstead — instant and lossless. - For H.265 output, substitute
libx265and add-tag:v hvc1for Apple device compatibility. - Clean up
ffmpeg2pass-0.logandffmpeg2pass-0.log.mbtreeafter 2-pass encoding completes.
#!/usr/bin/env python3
"""
Calculate recommended video bitrate for 2-pass FFmpeg encoding.
Usage:
calc_bitrate.py <input_file> --target-mb <float> [--audio-kbps <int>]
Output (stdout): integer kbps for use as -b:v value
Diagnostics (stderr): source info and budget breakdown
"""
from __future__ import annotations
import argparse
import json
import subprocess
import sys
def get_file_info(path: str) -> dict:
result = subprocess.run(
["ffprobe", "-v", "quiet", "-print_format", "json",
"-show_streams", "-show_format", path],
capture_output=True, text=True,
)
if result.returncode != 0:
print(f"Error: ffprobe failed:\n{result.stderr}", file=sys.stderr)
sys.exit(1)
return json.loads(result.stdout)
def main() -> None:
parser = argparse.ArgumentParser(
description="Calculate video bitrate for 2-pass FFmpeg encoding"
)
parser.add_argument("input_file", help="Input video file path")
parser.add_argument("--target-mb", type=float, required=True,
help="Target output file size in MB")
parser.add_argument("--audio-kbps", type=int, default=128,
help="Audio bitrate budget in kbps (default: 128)")
args = parser.parse_args()
info = get_file_info(args.input_file)
duration_s = float(info["format"].get("duration", 0))
if duration_s <= 0:
print("Error: could not determine video duration", file=sys.stderr)
sys.exit(1)
# total_kbps = (target_mb * 8192) / duration_s
# 1 MB = 8 Mbit = 8192 kbit
total_kbps = (args.target_mb * 8192) / duration_s
video_kbps = int(total_kbps - args.audio_kbps)
current_mb = float(info["format"].get("size", 0)) / (1024 * 1024)
print(f"Source: {current_mb:.1f} MB, {duration_s:.1f}s", file=sys.stderr)
print(
f"Budget: {args.target_mb} MB → {total_kbps:.0f} kbps total "
f"→ {video_kbps} kbps video + {args.audio_kbps} kbps audio",
file=sys.stderr,
)
if video_kbps <= 0:
print(
f"Error: target {args.target_mb} MB is too small — only "
f"{total_kbps:.0f} kbps total, which is less than the "
f"{args.audio_kbps} kbps audio budget.",
file=sys.stderr,
)
sys.exit(1)
# stdout: just the integer for clean shell capture
# e.g.: VIDEO_KBPS=$(python3 calc_bitrate.py video.mp4 --target-mb 50)
print(video_kbps)
if __name__ == "__main__":
main()
Related skills
Remotion Best PracticesGet Remotion-specific coding guidance that prevents common video rendering mistakes when creating animated React videos.451k4.2k
Ai Video GenerationGenerate videos using 40+ AI models including Veo, Seedance, and others via inference.sh442k665Ai Image GenerationGenerate images using 50+ AI models including FLUX, Gemini, and Replicate via inference.sh441k665Ai Avatar VideoGenerate videos featuring AI avatars for product demos, tutorials, marketing, or explainers441k665Remotion RenderRender videos programmatically using React components and Remotion framework441k665
Remotion RenderGenerate high-quality MP4 videos from React code using Remotion inside an AI coding agent.363k665How it compares
Use as a bitrate math helper ahead of raw FFmpeg CLI—not a replacement for HandBrake presets or hosted media APIs.
FAQ
Who is compress-video for?
Developers and content-focused developers who encode video locally with FFmpeg and want agent-assisted size targeting.
When should I use compress-video?
During Ship when tuning perf before release assets go live, and during Grow when recompressing course or marketing clips to platform size limits.
Is compress-video safe to install?
It runs ffprobe via subprocess on paths you provide; review the Security Audits panel on this page and avoid pointing it at untrusted files on shared machines.