ffmpeg-skill

Edit videos from your terminal with natural language. Cut, merge, compress, subtitle, GIF, watermark, speed, stabilize — just describe what you want.

---

Stop memorizing ffmpeg flags. Just say:

"cut the first 30 seconds of this video"
"merge these 3 clips into one"
"extract the audio as mp3"
"make a GIF from 0:15 to 0:20"
"compress this video to under 10MB"
"add subtitles from this SRT file"
"add a watermark in the bottom-right corner"
"slow motion at 0.5x"
"add 2-second fade in and fade out"

Claude Code translates your intent into the right ffmpeg command — or chains multiple commands for complex edits.

What You Get

18 high-level commands that cover 90% of video editing tasks, plus raw ffmpeg access for the other 10%.

| Command | What it does | |---------|-------------| | info | Duration, resolution, codecs, file size, bitrate | | cut | Extract a segment by start/end time or duration | | merge | Concatenate multiple videos (stream copy or re-encode) | | extract-audio | Rip audio as MP3, AAC, Opus, WAV, FLAC, OGG | | subtitles | Burn SRT subtitles into the video | | resize | Change resolution (auto-scale with -1) | | gif | High-quality two-pass GIF creation | | thumbnail | Extract a single frame as JPG/PNG | | thumbnails | Extract N evenly-spaced frames | | compress | Reduce file size with CRF quality control | | speed | Speed up or slow down (audio pitch preserved) | | watermark | Add image overlay at any corner or center | | text | Burn text with font size, color, position, timing | | convert | Change container/codec (MP4, WebM, MKV, MOV) | | frames | Extract all frames or every Nth frame | | audio-replace | Swap the audio track | | volume | Adjust audio level (multiplier or dB) | | fade | Add fade in/out (video + audio synced) | | stabilize | Fix shaky footage (two-pass vidstab) |

All commands output JSON for easy parsing and chaining.

Quick Start

1. Prerequisites

• ffmpeg installed and on PATH
• Python 3.8+
• Claude Code

# Check ffmpeg
ffmpeg -version

# On Ubuntu/Debian
sudo apt install ffmpeg

# On macOS
brew install ffmpeg

# On Windows
# Download from https://ffmpeg.org/download.html

2. Install

mkdir -p ~/.claude/commands

# Download the skill
curl -o ~/.claude/commands/ffmpeg.md \
  https://raw.githubusercontent.com/MastroMimmo/ffmpeg-skill/main/ffmpeg.md

# Clone the CLI tool
git clone https://github.com/MastroMimmo/ffmpeg-skill.git ~/ffmpeg-skill

Update the script path in ~/.claude/commands/ffmpeg.md:

SCRIPT="~/ffmpeg-skill/scripts/fftools.py"

3. Use

Just talk naturally in Claude Code:

"show me the info for video.mp4"
"trim from 1:30 to 2:45 and save as clip.mp4"
"make a 3-second GIF from the best part"
"compress this 2GB file, I need it under 100MB"
"replace the audio with this soundtrack.mp3"

Examples

Get video info

python3 fftools.py info input.mp4

{
  "file": "input.mp4",
  "streams": [
    {"type": "video", "codec": "h264", "width": 1920, "height": 1080, "fps": 30.0},
    {"type": "audio", "codec": "aac", "sample_rate": "44100", "channels": 2}
  ],
  "format": {
    "duration": 125.5,
    "duration_human": "02:05.50",
    "size_human": "45.2 MB",
    "bit_rate": 2880000
  }
}

Cut + Compress + GIF pipeline

# 1. Extract the best 10 seconds
python3 fftools.py cut input.mp4 clip.mp4 --start 00:01:15 --duration 10

# 2. Compress for sharing
python3 fftools.py compress clip.mp4 clip_small.mp4 --crf 28

# 3. Make a preview GIF
python3 fftools.py gif clip.mp4 preview.gif --fps 12 --width 400

Add subtitles + watermark

# Burn subtitles
python3 fftools.py subtitles input.mp4 subbed.mp4 --srt captions.srt

# Add logo watermark
python3 fftools.py watermark subbed.mp4 final.mp4 --watermark logo.png --position bottom-right

Slow motion + fade

python3 fftools.py speed input.mp4 slowmo.mp4 --factor 0.5
python3 fftools.py fade slowmo.mp4 final.mp4 --fade-in 2 --fade-out 3

Advanced: Raw ffmpeg

The skill also teaches Claude Code raw ffmpeg for complex operations:

• Picture-in-picture — Overlay a small video on a large one
• Side-by-side comparison — Stack two videos horizontally
• Grid/mosaic — 2x2 or 3x3 video grids
• Green screen removal — Chroma key compositing
• Crossfade transitions — Smooth transitions between clips
• Color correction — Brightness, contrast, saturation
• Noise reduction — Audio denoising with FFT
• Timelapse — Image sequence to video
• Video from image + audio — Static image with audio track

CRF Quality Guide

| CRF | Quality | File size | Best for | |-----|---------|-----------|----------| | 18 | Visually lossless | Large | Archival | | 23 | High | Medium | Default | | 28 | Good | Small | Sharing | | 32 | Acceptable | Very small | Social media |

Each +6 roughly halves the file size.

Why a Helper Script?

FFmpeg is incredibly powerful but has a brutal CLI interface. The fftools.py wrapper:

1. Simplifies flags — --start, --end instead of -ss, -to placement order gotchas
2. JSON output — Every command returns structured JSON, not wall-of-text logs
3. Two-pass GIFs — Automatic palette generation for high-quality GIFs
4. Smart codec selection — Picks the right codec based on output extension
5. Size reporting — Compression shows original vs. compressed with % reduction
6. Zero dependencies — Python standard library only

But you're never locked in — the skill also teaches Claude raw ffmpeg for anything the wrapper doesn't cover.

Project Structure

ffmpeg-skill/
├── ffmpeg.md              # Skill file (copy to ~/.claude/commands/)
├── scripts/
│   └── fftools.py         # CLI wrapper — Python stdlib, zero deps
└── README.md

License

MIT — see LICENSE.