/video-edit

name: claude-video-edit
description: >
  Video editing operations using FFmpeg: trimming, cutting, splitting, concatenation,
  speed changes, cropping, scaling, rotation, overlays, picture-in-picture, green screen
  removal, video stabilization, transitions, fades, privacy blur, LUT color grading, and
  motion tracking text. Use when user says "trim", "cut", "split", "merge", "concat",
  "speed up", "slow down", "crop", "scale", "rotate", "overlay", "watermark", "pip",
  "green screen", "stabilize", "transition", "fade", "blur face", "privacy", "censor",
  "LUT", "color grade", or "tracking text".
allowed-tools:
  - Bash
  - Read
  - Write

claude-video-edit — Video Editing Operations

Pre-Flight

Before every operation that writes a file: 1. Run `bash scripts/preflight.sh "$INPUT" "$OUTPUT"` 2. If it fails, stop and report the error to the user 3. For encoding operations, run `bash scripts/detect_gpu.sh` to choose encoder

Operations

Trimming

**Lossless trim** (keyframe-aligned, instant, no re-encode):

ffmpeg -n -ss HH:MM:SS -i "$INPUT" -t DURATION -c copy "$OUTPUT"

Note: `-ss` BEFORE `-i` for fast seeking. Duration in seconds or HH:MM:SS.

**Frame-accurate trim** (re-encodes, precise to any frame):

ffmpeg -n -i "$INPUT" -ss HH:MM:SS -t DURATION -c:v libx264 -crf 20 -c:a aac "$OUTPUT"

Note: `-ss` AFTER `-i` for frame accuracy. Use when precision matters.

**Remove first/last N seconds**:

• Remove first 10s: `-ss 10 -c copy`
• Remove last 10s: get duration with ffprobe, then trim to `duration - 10`

Splitting

**Split at specific time**:

ffmpeg -n -i "$INPUT" -t 60 -c copy part1.mp4
ffmpeg -n -i "$INPUT" -ss 60 -c copy part2.mp4

**Split into equal segments**:

ffmpeg -n -i "$INPUT" -f segment -segment_time 300 -c copy -reset_timestamps 1 "segment_%03d.mp4"

**Split at scene boundaries** (load `references/analyze.md` for PySceneDetect):

scenedetect -i "$INPUT" detect-adaptive -t 3.0 split-video

Concatenation

**Same codec (no re-encode)**:

printf "file '%s'\n" file1.mp4 file2.mp4 file3.mp4 > /tmp/concat_list.txt
ffmpeg -n -f concat -safe 0 -i /tmp/concat_list.txt -c copy "$OUTPUT"
rm /tmp/concat_list.txt

**Different codecs (re-encodes)**:

ffmpeg -n -i file1.mp4 -i file2.mp4 -filter_complex "[0:v][0:a][1:v][1:a]concat=n=2:v=1:a=1" "$OUTPUT"

Speed Changes

**Speed up 2x** (with audio pitch correction):

ffmpeg -n -i "$INPUT" -vf "setpts=0.5*PTS" -af "atempo=2.0" "$OUTPUT"

**Slow down 0.5x**:

ffmpeg -n -i "$INPUT" -vf "setpts=2.0*PTS" -af "atempo=0.5" "$OUTPUT"

**Speed factors**: For `atempo`, valid range is 0.5–100.0. For extreme changes, chain: `atempo=2.0,atempo=2.0` = 4x.

**Frame interpolation slow-motion** (AI-generated intermediate frames):

ffmpeg -n -i "$INPUT" -vf "minterpolate=fps=60:mi_mode=mci:mc_mode=aobmc:vsbmc=1" "$OUTPUT"

Warning: Very slow (~0.05x realtime). Best for short clips.

Cropping, Scaling, Rotation

**Crop** (width:height:x:y):

ffmpeg -n -i "$INPUT" -vf "crop=640:480:100:50" "$OUTPUT"

**Scale** (keep aspect ratio, even dimensions):

ffmpeg -n -i "$INPUT" -vf "scale=1280:-2:flags=lanczos" "$OUTPUT"

**Scale to exact size with padding** (letterbox):

ffmpeg -n -i "$INPUT" -vf "scale=1920:1080:force_original_aspect_ratio=decrease,pad=1920:1080:(ow-iw)/2:(oh-ih)/2:black" "$OUTPUT"

**Rotate** 90° clockwise: `-vf "transpose=1"` **Rotate** 90° counter-clockwise: `-vf "transpose=2"` **Rotate** 180°: `-vf "transpose=1,transpose=1"` **Arbitrary angle**: `-vf "rotate=PI/6:fillcolor=black"` **Flip** horizontal: `-vf "hflip"` | Vertical: `-vf "vflip"`

Overlays and Watermarks

**Image watermark** (bottom-right with 10px margin):

ffmpeg -n -i "$INPUT" -i logo.png -filter_complex "overlay=W-w-10:H-h-10" "$OUTPUT"

**Picture-in-picture** (small video in corner):

ffmpeg -n -i "$INPUT" -i pip.mp4 -filter_complex "[1:v]scale=320:180[pip];[0:v][pip]overlay=10:10" "$OUTPUT"

**Text overlay**:

ffmpeg -n -i "$INPUT" -vf "drawtext=text='My Title':fontsize=48:fontcolor=white:x=(w-tw)/2:y=50:fontfile=/usr/share/fonts/truetype/dejavu/DejaVuSans-Bold.ttf:box=1:boxcolor=black@0.5:boxborderw=8" "$OUTPUT"

**Timed text** (show between 5s and 15s):

-vf "drawtext=text='Hello':enable='between(t,5,15)':fontsize=36:fontcolor=white:x=10:y=10"

Green Screen (Chromakey)

ffmpeg -n -i greenscreen.mp4 -i background.mp4 -filter_complex \
  "[0:v]chromakey=0x00FF00:0.1:0.2[fg];[1:v][fg]overlay" "$OUTPUT"

Adjust color hex, similarity (0.1), and blend (0.2) for best results.

Video Stabilization

Two-pass process using vidstab:

# Pass 1: Analyze motion
ffmpeg -i "$INPUT" -vf vidstabdetect=shakiness=5:accuracy=15:result=/tmp/transforms.trf -f null -

# Pass 2: Apply stabilization + sharpening
ffmpeg -n -i "$INPUT" -vf "vidstabtransform=smoothing=10:input=/tmp/transforms.trf,unsharp=5:5:0.8:5:5:0.3" "$OUTPUT"

rm /tmp/transforms.trf

`shakiness` 1-10 (how shaky is source), `smoothing` (higher = smoother camera, may crop edges).

Transitions

**Cross-fade between two clips** (44+ transition types available):

ffmpeg -n -i first.mp4 -i second.mp4 -filter_complex \
  "xfade=transition=fade:duration=2:offset=5" "$OUTPUT"

**Available xfade transitions**: fade, dissolve, wipeleft, wiperight, wipeup, wipedown, slideleft, slideright, slideup, slidedown, circlecrop, rectcrop, distance, fadeblack, fadewhite, radial, smoothleft, smoothright, smoothup, smoothdown, circleopen, circleclose, vertopen, vertclose, horzopen, horzclose, diagtl, diagtr, diagbl, diagbr, hlslice, hrslice, vuslice, vdslice, pixelize, squeezeh, squeezev, zoomin, fadegrays, wipetl, wipetr, wipebl, wipebr, coverleft, coverright, coverup, coverdown, revealleft, revealright, revealup, revealdown.

**Fade in/out**:

# Fade in first 2 seconds
ffmpeg -n -i "$I