ffmpeg-video-editor

The saved excerpt is a snapshot from when this skill was listed. The external source remains the complete and most current version.

---
name: ffmpeg-video-editor
version: 1.0.0
description: >
  A complete FFmpeg-powered video editing agent. Use this skill whenever the
  user wants to do anything with video or audio files — trimming, cutting,
  transcoding, resizing, concatenating, adding subtitles, overlaying images or
  text, applying color grades or LUTs, normalizing audio levels, creating
  transitions, green-screen compositing, frame extraction, slideshows, or
  exporting for social media (TikTok, Reels, YouTube). Also use it for codec
  questions (H.264, H.265, VP9, AV1, ProRes, FFV1), hardware-accelerated
  encoding (NVIDIA NVENC, Intel QSV, VAAPI, Apple VideoToolbox), and any
  ffmpeg or ffprobe command construction. Even if the user just says "convert
  this video" or "make it smaller" or "add my logo" — reach for this skill.
  Reference documents in references/ cover filters, codecs, transitions, and
  hardware acceleration. Helper scripts in scripts/ handle probing,
  concatenation, and normalization.
author: ffmpeg-video-editor contributors
license: MIT
requirements:
  - ffmpeg >= 6.0
  - ffprobe >= 6.0
tags:
  - video
  - audio
  - ffmpeg
  - transcoding
  - editing
  - color-grading
  - normalization
---

# FFmpeg Video Editor Agent Skill

You are an expert FFmpeg operator. Use this skill to answer any video/audio
editing request by constructing correct `ffmpeg` command lines. Always probe
input files first, then select the appropriate operation category below.

## Probe Input Files

Run `scripts/probe.sh <file>` (make executable first with `chmod +x scripts/*.sh` if needed), or inspect manually:

```bash
ffprobe -v error -show_streams -show_format -of json input.mp4
```

## Trim / Cut

```bash
# Fast stream-copy trim (no re-encode)
ffmpeg -ss 00:01:00 -to 00:02:30 -i input.mp4 -c copy out.mp4

# Precise trim (re-encode around keyframes)
ffmpeg -ss 00:01:00 -i input.mp4 -t 90 -c:v libx264 -crf 18 -c:a aac out.mp4
```

## Transcode

```bash
# H.264 web-safe (pix_fmt ensures broad player compatibility)
ffmpeg -i input.mp4 -c:v libx264 -crf 23 -preset slow \
  -pix_fmt yuv420p -c:a aac -b:a 128k -movflags +faststart out.mp4

# H.265 (smaller files)
ffmpeg -i input.mp4 -c:v libx265 -crf 28 -preset slow \
  -pix_fmt yuv420p -c:a aac -b:a 128k out.mp4

# VP9 for web
ffmpeg -i input.mp4 -c:v libvpx-vp9 -crf 33 -b:v 0 \
  -c:a libopus -b:a 128k out.webm

# AV1 (best compression)
ffmpeg -i input.mp4 -c:v libaom-av1 -crf 35 -cpu-used 4 \
  -c:a libopus -b:a 128k out.mkv
```

See `references/CODECS.md` for full codec comparison.

## Concatenate Files

```bash
# Using helper script
scripts/concat.sh out.mp4 clip1.mp4 clip2.mp4 clip3.mp4

# Manual concat demuxer
printf "file 'a.mp4'\nfile 'b.mp4'\n" > list.txt
ffmpeg -f concat -safe 0 -i list.txt -c copy out.mp4
```

## Scale / Resize

```bash
# Scale to 1920×1080, keep aspect ratio, pad to fill
ffmpeg -i in.mp4 -vf "scale=1920:1080:force_original_aspect_ratio=decrease,\
pad=1920:1080:(ow-iw)/2:(oh-ih)/2:black" out.mp4

# Scale by width only (auto height)
ffmpeg -i in.mp4 -vf "scale=1280:-2" out.mp4
```

## Crop

```bash
# Crop 640×360 starting at (100,50)
ffmpeg -i in.mp4 -vf "crop=640:360:100:50" out.mp4

# Center crop to 1:1 square
ffmpeg -i in.mp4 -vf "crop=min(iw\,ih):min(iw\,ih)" out.mp4
```

## Overlay / Watermark

```bash
# Overlay image (top-right, 10px margin)
ffmpeg -i video.mp4 -i logo.png \
  -filter_complex "[0:v][1:v] overlay=W-w-10:10" out.mp4

# PiP: small video on top of main
ffmpeg -i main.mp4 -i pip.mp4 \
  -filter_complex "[1:v]scale=320:-2[small];[0:v][small]overlay=W-w-10:H-h-10" out.mp4
```

## Draw Text / Titles

```bash
ffmpeg -i in.mp4 -vf \
  "drawtext=text='My Title':fontfile=/usr/share/fonts/truetype/dejavu/DejaVuSans.ttf\
:fontsize=48:fontcolor=white:x=(w-text_w)/2:y=(h-text_h)/2\
:shadowx=2:shadowy=2" out.mp4
```

## Burn Subtitles

```bash
# SRT subtitles (re-encode required)
ffmpeg -i video.mp4 -vf "subtitles=subs.srt" out.mp4

# ASS/SSA subtitles (preserves styling)
ffmpe