# ffmpeg-video-processor

> Comprehensive video processing toolkit using FFmpeg. Supports format conversion, resolution adjustment, cropping/trimming, compression optimization, watermarking, and audio extraction. Use when Claude needs to process video files: (1) Convert between formats (MP4, AVI, MOV, MKV, WebM), (2) Adjust resolution/scale videos, (3) Crop or trim video segments, (4) Compress/optimize file size, (5) Add watermarks (image or text), (6) Extract audio or remove audio streams, or (7) Batch process multiple videos.

- Author: Rorance
- Repository: luoz76070-art/my-skill
- Version: 20260122123104
- Stars: 0
- Forks: 0
- Last Updated: 2026-02-06
- Source: https://github.com/luoz76070-art/my-skill
- Web: https://mule.run/skillshub/@@luoz76070-art/my-skill~ffmpeg-video-processor:20260122123104

---

---
name: ffmpeg-video-processor
description: Comprehensive video processing toolkit using FFmpeg. Supports format conversion, resolution adjustment, cropping/trimming, compression optimization, watermarking, and audio extraction. Use when Claude needs to process video files: (1) Convert between formats (MP4, AVI, MOV, MKV, WebM), (2) Adjust resolution/scale videos, (3) Crop or trim video segments, (4) Compress/optimize file size, (5) Add watermarks (image or text), (6) Extract audio or remove audio streams, or (7) Batch process multiple videos.
---

# FFmpeg Video Processor

Complete toolkit for video processing using FFmpeg with automated scripts and command generation.

## Quick Start

Use scripts for common operations or generate FFmpeg commands for complex tasks.

**Convert video format:**
```bash
scripts/convert_video.py input.avi output.mp4
scripts/convert_video.py input.mkv output.mp4 --stream-copy
```

**Adjust resolution:**
```bash
scripts/scale_video.py input.mp4 output.mp4 1920 1080
scripts/scale_video.py input.mp4 output.mp4 1280  # Auto-calculate height
```

**Crop or trim:**
```bash
scripts/crop_trim_video.py input.mp4 output.mp4 --crop-width 640 --crop-height 480 --crop-x 0 --crop-y 0
scripts/crop_trim_video.py input.mp4 output.mp4 --start 30 --duration 60
```

**Compress:**
```bash
scripts/compress_video.py input.mp4 output.mp4 --crf 23
scripts/compress_video.py input.mp4 output.mp4 --bitrate 2000k
```

**Add watermark:**
```bash
scripts/watermark_video.py input.mp4 output.mp4 --image logo.png
scripts/watermark_video.py input.mp4 output.mp4 --text "Copyright"
```

**Extract/Remove audio:**
```bash
scripts/extract_audio.py input.mp4 output.mp3
scripts/extract_audio.py input.mp4 output_noaudio.mp4 --remove-audio --stream-copy
```

**Batch process:**
```bash
scripts/batch_process.py "*.mp4" "compressed_" compress
scripts/batch_process.py "*.mkv" "720p_" scale_720p --parallel 4
```

## When to Use Scripts vs Generate Commands

**Use scripts when:**
- Processing single files with common operations
- User wants immediate execution
- Operations are straightforward (format convert, scale, trim, compress, watermark, extract audio)
- Using batch processing patterns

**Generate FFmpeg commands when:**
- Operations are complex or involve multiple filters
- User wants to preview or customize commands
- Requires specific FFmpeg options not in scripts
- Combining multiple operations in complex ways
- Working with advanced features (filter graphs, complex overlays)

## Script Reference

### convert_video.py

Convert video between formats.

**Basic usage:**
```bash
scripts/convert_video.py input.avi output.mp4
scripts/convert_video.py input.mp4 output.mkv --stream-copy
scripts/convert_video.py input.mov output.mp4 --video-codec libx264 --audio-codec aac
```

**When to use:**
- Simple format conversion
- Container format changes
- Codec specification needed

**Key parameters:**
- `--video-codec`: libx264, libx265, libvpx
- `--audio-codec`: aac, mp3, libopus
- `--stream-copy`: Copy streams without re-encoding (fast, no quality loss)

### scale_video.py

Scale video to different resolutions.

**Basic usage:**
```bash
scripts/scale_video.py input.mp4 output.mp4 1920 1080
scripts/scale_video.py input.mp4 output.mp4 1280  # Auto-height
scripts/scale_video.py input.mp4 output.mp4 854 480 --algorithm lanczos
```

**When to use:**
- Resolution changes
- Downscaling for web/mobile
- Upscaling with quality

**Key parameters:**
- `width`: Output width in pixels
- `height`: Output height (omit to auto-calculate)
- `--algorithm`: lanczos (best), bicubic (default), bilinear, neighbor

### crop_trim_video.py

Crop video frames and/or trim time segments.

**Basic usage:**
```bash
scripts/crop_trim_video.py input.mp4 output.mp4 --crop-width 640 --crop-height 480 --crop-x 0 --crop-y 0
scripts/crop_trim_video.py input.mp4 output.mp4 --start 30 --duration 60
scripts/crop_trim_video.py input.mp4 output.mp4 --crop-width 640 --crop-height 480 --crop-x 0 --crop-y 0 --start 10 --duration 30
```

**When to use:**
- Removing black bars
- Extracting video segments
- Cropping to specific region

**Key parameters:**
- `--crop-width/height/x/y`: All four required for cropping
- `--start`: Start time (seconds or HH:MM:SS)
- `--duration`: Duration in seconds
- `--end`: End time (absolute)

### compress_video.py

Compress video using CRF or bitrate-based methods.

**Basic usage:**
```bash
scripts/compress_video.py input.mp4 output.mp4 --crf 23
scripts/compress_video.py input.mp4 output.mp4 --crf 28
scripts/compress_video.py input.mp4 output.mp4 --bitrate 2000k --two-pass
scripts/compress_video.py input.mp4 output.mp4 --max-size 100M
```

**When to use:**
- Reducing file size
- Optimizing for web/streaming
- Quality vs size control

**Key parameters:**
- `--crf`: 0-51 (lower = better quality, 23 is recommended)
- `--bitrate`: e.g., 2000k, 1500k, 500k
- `--max-size`: e.g., 100M, 50M, 1G
- `--preset`: ultrafast to veryslow (default: medium)
- `--two-pass`: Better compression with bitrate mode

**See:** [references/quality-guide.md](references/quality-guide.md) for detailed CRF and bitrate recommendations

### watermark_video.py

Add image or text watermarks.

**Basic usage:**
```bash
scripts/watermark_video.py input.mp4 output.mp4 --image logo.png
scripts/watermark_video.py input.mp4 output.mp4 --image logo.png --position W-w-10:H-h-10
scripts/watermark_video.py input.mp4 output.mp4 --text "Copyright"
scripts/watermark_video.py input.mp4 output.mp4 --text "Watermark" --color yellow --fontsize 30
```

**When to use:**
- Adding logos/branding
- Copyright notices
- Text overlays

**Key parameters:**
- `--image`: Path to watermark image (PNG with transparency recommended)
- `--text`: Watermark text content
- `--position`: Position (10:10, W-w-10:H-h-10, (W-w)/2:(H-h)/2)
- `--scale`: Scale watermark (100:100, 200:-1)
- `--opacity`: 0.0 to 1.0
- `--color`: Text color (white, yellow, red, etc.)
- `--shadow`: Add shadow to text

### extract_audio.py

Extract audio from video or remove audio.

**Basic usage:**
```bash
scripts/extract_audio.py input.mp4 output.mp3
scripts/extract_audio.py input.mp4 output.mp3 --bitrate 320k
scripts/extract_audio.py input.mp4 output.wav --format wav
scripts/extract_audio.py input.mp4 output_noaudio.mp4 --remove-audio --stream-copy
```

**When to use:**
- Creating audio files
- Removing audio from video
- Converting audio formats

**Key parameters:**
- `--format`: mp3, aac, wav, flac, m4a, ogg, opus
- `--bitrate`: e.g., 192k, 320k
- `--remove-audio`: Remove audio instead of extracting
- `--stream-copy`: Copy video without re-encoding (with --remove-audio)

### batch_process.py

Process multiple files using glob patterns.

**Basic usage:**
```bash
scripts/batch_process.py "*.mp4" "compressed_" compress
scripts/batch_process.py "*.mkv" "720p_" scale_720p
scripts/batch_process.py "*.mp4" "480p_" scale_480p --parallel 4
scripts/batch_process.py "*.mp4" "audio_" extract_audio
scripts/batch_process.py "*.mp4" "compressed_" compress --dry-run
```

**When to use:**
- Processing multiple files
- Batch conversions
- Parallel processing for speed

**Key parameters:**
- `pattern`: Glob pattern (*.mp4, *.mkv, videos/*.avi)
- `output_prefix`: Prefix for output files
- `operation`: convert, scale_720p, scale_480p, compress, extract_audio, remove_audio
- `--parallel`: Number of parallel processes (default: 1)
- `--dry-run`: Show commands without executing

## Command Generation Patterns

Generate FFmpeg commands directly for complex operations.

### Format Conversion

```bash
ffmpeg -i input.avi output.mp4
ffmpeg -i input.mkv -c copy output.mp4
ffmpeg -i input.mov -c:v libx264 -c:a aac output.mp4
```

### Scaling and Filtering

```bash
ffmpeg -i input.mp4 -vf scale=1920:1080 output.mp4
ffmpeg -i input.mp4 -vf scale=1280:-1:flags=lanczos output.mp4
ffmpeg -i input.mp4 -vf "yadif,scale=1280:720" output.mp4  # Deinterlace + scale
```

### Complex Filters

Combine multiple filters in sequence:

```bash
# Crop, then scale, then trim
ffmpeg -i input.mp4 -vf "crop=iw-20:ih-40:10:20,scale=1280:720" -ss 30 -t 60 output.mp4

# Add multiple overlays
ffmpeg -i input.mp4 -i logo1.png -i logo2.png -filter_complex "[0:v][1:v]overlay=10:10[v1];[v1][2:v]overlay=W-w-10:H-h-10" output.mp4

# Text with fade
ffmpeg -i input.mp4 -vf "drawtext=text='Text':x=10:y=10:enable='between(t,0,5)'" output.mp4
```

### Advanced Watermarking

```bash
# Scaled semi-transparent watermark
ffmpeg -i input.mp4 -i logo.png -filter_complex "[1:v]scale=200:200,format=rgba,colorchannelmixer=aa=0.5[w];[0:v][w]overlay=(W-w)/2:(H-h)/2" output.mp4

# Animated watermark
ffmpeg -i input.mp4 -i logo.png -filter_complex "[1:v]scale=100:100[w];[0:v][w]overlay=x='if(eq(mod(t,5),0),x+1,x)':y=10" output.mp4

# Tiled watermark
ffmpeg -i input.mp4 -i logo.png -filter_complex "overlay=0:0,overlay=W-w:0,overlay=0:H-h,overlay=W-w:H-h" output.mp4
```

### Multi-Track Processing

```bash
# Select specific streams
ffmpeg -i input.mkv -map 0:v:0 -map 0:a:1 output.mp4

# Merge multiple files
ffmpeg -i video1.mp4 -i video2.mp4 -filter_complex "[0:v][1:v]concat=n=2:v=1" output.mp4

# Picture-in-picture
ffmpeg -i main.mp4 -i pip.mp4 -filter_complex "[1:v]scale=320:240[pip];[0:v][pip]overlay=W-w-10:H-h-10" output.mp4
```

### Advanced Compression

```bash
# CRF with maximum bitrate cap
ffmpeg -i input.mp4 -crf 23 -maxrate 5000k -bufsize 10000k output.mp4

# Target specific file size
ffmpeg -i input.mp4 -b:v 2730k -b:a 128k -fs 100M output.mp4

# Tune for specific content
ffmpeg -i input.mp4 -tune film -crf 23 output.mp4
ffmpeg -i input.mp4 -tune animation -crf 20 output.mp4
```

## Advanced Topics

### Chained Operations

Combine multiple operations by running scripts sequentially or using filter chains:

```bash
# Using scripts (sequential, slower but simpler)
scripts/crop_trim_video.py input.mp4 temp.mp4 --crop-width 1920 --crop-height 1080 --crop-x 0 --crop-y 0
scripts/compress_video.py temp.mp4 output.mp4 --crf 23

# Using FFmpeg directly (single pass, faster)
ffmpeg -i input.mp4 -vf "crop=1920:1080:0:0" -crf 23 output.mp4
```

### Batch Operations with Custom Commands

For operations not supported by batch_process.py, use shell loops:

```bash
# Linux/macOS
for f in *.mp4; do
    ffmpeg -i "$f" -vf "crop=iw-20:ih-40:10:20,scale=1280:720" -crf 23 "processed_$f"
done

# Windows
for %f in (*.mp4) do (
    ffmpeg -i "%f" -vf "crop=iw-20:ih-40:10:20,scale=1280:720" -crf 23 "processed_%f"
)
```

### Performance Optimization

- Use `--preset veryslow` for maximum compression (archival)
- Use `--preset ultrafast` for real-time/screen capture
- Use `--parallel N` in batch_process.py for faster batch operations
- Place `-ss` before `-i` for faster seeking (less accurate)
- Use `-c copy` whenever possible to avoid re-encoding

### Common Patterns

```bash
# YouTube upload optimization
ffmpeg -i input.mp4 -crf 20 -preset slow -movflags +faststart output.mp4

# Mobile optimization
ffmpeg -i input.mp4 -vf scale=1280:720 -crf 28 -preset fast -b:a 96k output.mp4

# Email attachment (max 25MB)
ffmpeg -i input.mp4 -crf 32 -preset medium -fs 25M output.mp4

# Remove black bars (auto-detect)
ffmpeg -i input.mp4 -vf cropdetect -f null -
# Then use the detected crop values
ffmpeg -i input.mp4 -vf crop=640:360:0:0 output.mp4
```

## Reference Documentation

- **[ffmpeg-commands.md](references/ffmpeg-commands.md)** - Complete FFmpeg command reference with all operations, parameters, and use cases
- **[quality-guide.md](references/quality-guide.md)** - CRF and bitrate recommendations, preset guide, quality vs size tradeoffs

Load these reference documents when:
- User asks about advanced FFmpeg options
- Need specific FFmpeg filter syntax
- Optimizing for specific use cases (YouTube, mobile, streaming)
- Determining optimal quality settings

## Error Handling

Common FFmpeg errors and solutions:

**"Codec not found"**
- Install FFmpeg with proper codecs
- Check `ffmpeg -codecs` for available codecs

**"Invalid pixel format"**
- Add `-pix_fmt yuv420p` for compatibility
- Check output format requirements

**"File size too large/small"**
- Adjust CRF value (higher = smaller)
- Use `-fs` to limit file size
- Consider lower resolution or bitrate

**"Encoding too slow"**
- Use faster preset (`--preset fast`)
- Consider hardware acceleration
- Lower resolution or quality

**"Audio out of sync"**
- Use `-async 1` to fix sync
- Check input file for issues
- Try re-encoding audio separately