ffmpeg-video-editor

内容来源：SKILL.md（标准 Skill 格式） · 原始地址 · 查看安装指南

原始内容

---
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)
ffmpeg -i video.mp4 -vf "ass=subs.ass" out.mp4
```

## Speed Change

```bash
# 2× speed (video + audio)
ffmpeg -i in.mp4 -vf "setpts=0.5*PTS" -af "atempo=2.0" out.mp4

# 0.5× speed (half speed)
ffmpeg -i in.mp4 -vf "setpts=2.0*PTS" -af "atempo=0.5" out.mp4

# >4×: chain atempo (max 2.0 per filter)
ffmpeg -i in.mp4 -vf "setpts=0.25*PTS" -af "atempo=2.0,atempo=2.0" out.mp4

# <0.5×: chain atempo (min 0.5 per filter)
ffmpeg -i in.mp4 -vf "setpts=4.0*PTS" -af "atempo=0.5,atempo=0.5" out.mp4
```

## Reverse

```bash
ffmpeg -i in.mp4 -vf "reverse" -af "areverse" out.mp4
```

## Transitions (xfade)

```bash
# Dissolve between two clips (1s overlap at t=5)
ffmpeg -i a.mp4 -i b.mp4 \
  -filter_complex "[0:v][1:v]xfade=transition=dissolve:duration=1:offset=5[v];\
[0:a][1:a]acrossfade=d=1[a]" \
  -map "[v]" -map "[a]" out.mp4
```

See `references/TRANSITIONS.md` for all 40+ xfade transition types.

## Audio: Volume & Normalization

```bash
# Adjust volume
ffmpeg -i in.mp4 -af "volume=1.5" out.mp4

# EBU R128 normalization (two-pass)
scripts/normalize-audio.sh in.mp4 out.mp4

# One-pass loudnorm
ffmpeg -i in.mp4 -af "loudnorm=I=-16:TP=-1.5:LRA=11" out.mp4
```

## Audio: Fade In/Out

```bash
# Fade in 2s at start, fade out 3s before end (total 60s)
ffmpeg -i in.mp4 -af "afade=t=in:d=2,afade=t=out:st=57:d=3" out.mp4
```

## Mix / Combine Audio

```bash
# Mix two audio streams
ffmpeg -i video.mp4 -i music.mp3 \
  -filter_complex "[0:a][1:a]amix=inputs=2:duration=first:weights=1 0.3[a]" \
  -map 0:v -map "[a]" -c:v copy out.mp4
```

## Color Grading

```bash
# Brightness/Contrast/Saturation
ffmpeg -i in.mp4 -vf "eq=brightness=0.05:contrast=1.2:saturation=1.3" out.mp4

# Hue shift
ffmpeg -i in.mp4 -vf "hue=h=30:s=1.1" out.mp4

# Apply 3D LUT (.cube)
ffmpeg -i in.mp4 -vf "lut3d=file=lut.cube" out.mp4

# Apply Hald CLUT PNG
ffmpeg -i in.mp4 -i lut.png \
  -filter_complex "[0:v][1:v]haldclut" out.mp4
```

## Chroma Key / Green Screen

```bash
# chromakey (color + similarity + blend)
ffmpeg -i foreground.mp4 -i background.mp4 \
  -filter_complex "[0:v]chromakey=0x00FF00:0.3:0.2[fg];\
[1:v][fg]overlay" out.mp4

# colorkey (simpler, exact color)
ffmpeg -i in.mp4 -vf "colorkey=green:0.3:0.2" out.mp4
```

## Frame Rate Conversion

```bash
# Convert to 30fps
ffmpeg -i in.mp4 -vf "fps=30" out.mp4

# Use motion interpolation (minterpolate)
ffmpeg -i in.mp4 -vf "minterpolate=fps=60:mi_mode=mci" out.mp4
```

## Extract Frames / Create Slideshow

```bash
# Extract one frame per second as PNG
ffmpeg -i in.mp4 -vf "fps=1" frames/%04d.png

# Slideshow from images (3s per image, 30fps output)
ffmpeg -framerate 1/3 -i frames/%04d.png -c:v libx264 -r 30 out.mp4
```

## Stacking / Grid Layout

```bash
# Side by side (hstack)
ffmpeg -i a.mp4 -i b.mp4 -filter_complex "[0:v][1:v]hstack=inputs=2" out.mp4

# Top-bottom (vstack)
ffmpeg -i a.mp4 -i b.mp4 -filter_complex "[0:v][1:v]vstack=inputs=2" out.mp4

# 2×2 grid (xstack)
ffmpeg -i a.mp4 -i b.mp4 -i c.mp4 -i d.mp4 \
  -filter_complex "[0:v][1:v][2:v][3:v]xstack=inputs=4:layout=0_0|w0_0|0_h0|w0_h0" out.mp4
```

## Hardware-Accelerated Encoding

```bash
# NVIDIA NVENC H.264
ffmpeg -hwaccel cuda -i in.mp4 -c:v h264_nvenc -preset p4 -cq 23 out.mp4

# Apple VideoToolbox H.265
ffmpeg -i in.mp4 -c:v hevc_videotoolbox -q:v 60 out.mp4

# Intel QuickSync H.264
ffmpeg -hwaccel qsv -i in.mp4 -c:v h264_qsv -global_quality 23 out.mp4
```

See `references/HARDWARE-ACCEL.md` for full GPU encoding guide.

## Encoding Presets (assets/preset-profiles.json)

When the task maps to a named use case below, read `assets/preset-profiles.json`
and use the `example` field as the ready-made ffmpeg command.

| Profile                  | Codec     | CRF | Use Case              |
|--------------------------|-----------|-----|-----------------------|
| web-optimized            | H.264     | 23  | Browser streaming     |
| high-quality             | H.264     | 18  | Archive / master      |
| social-media-vertical    | H.264     | 23  | 9:16 TikTok/Reels     |
| social-media-square      | H.264     | 23  | 1:1 Instagram         |
| fast-preview             | H.264     | 28  | Proxy / review        |
| lossless-intermediate    | FFV1      | —   | Post-production store |

## Multi-Stream Filter Graph Pattern

```bash
ffmpeg \
  -i input_video.mp4 \
  -i overlay.png \
  -i audio_bed.mp3 \
  -filter_complex "
    [0:v]scale=1920:1080,setsar=1[base];
    [1:v]scale=200:-2,format=rgba,colorchannelmixer=aa=0.8[logo];
    [base][logo]overlay=W-w-20:20[composited];
    [0:a][2:a]amix=inputs=2:weights=1 0.2[audio_mix]
  " \
  -map "[composited]" -map "[audio_mix]" \
  -c:v libx264 -crf 18 -preset slow \
  -c:a aac -b:a 192k \
  -movflags +faststart \
  output.mp4
```

## Common Options Reference

| Flag              | Meaning                                      |
|-------------------|----------------------------------------------|
| `-ss`             | Seek/start time (before `-i` = fast seek)    |
| `-to`             | End time (absolute)                          |
| `-t`              | Duration                                     |
| `-c copy`         | Stream copy (no re-encode)                   |
| `-crf`            | Constant Rate Factor (lower = better)        |
| `-preset`         | Encoder speed/quality tradeoff               |
| `-movflags +faststart` | Move moov atom to front (web streaming) |
| `-vf`             | Video filter chain                           |
| `-af`             | Audio filter chain                           |
| `-filter_complex` | Multi-input/output filter graph              |
| `-map`            | Select output streams explicitly             |
| `-an`             | Drop audio                                   |
| `-vn`             | Drop video                                   |
| `-y`              | Overwrite output without prompt              |

## Debugging Tips

```bash
# Dry-run: print filter graph without encoding
ffmpeg -i in.mp4 -vf "scale=1280:-2" -f null -

# Benchmark encode speed
ffmpeg -benchmark -i in.mp4 -c:v libx264 -f null -

# Show available encoders
ffmpeg -encoders | grep -E "^.V|^.A"

# Show filter options
ffmpeg -help filter=loudnorm
```

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:

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

Trim / Cut

# 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

# 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

# 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

# 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

# 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

# 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

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

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

# ASS/SSA subtitles (preserves styling)
ffmpeg -i video.mp4 -vf "ass=subs.ass" out.mp4

Speed Change

# 2× speed (video + audio)
ffmpeg -i in.mp4 -vf "setpts=0.5*PTS" -af "atempo=2.0" out.mp4

# 0.5× speed (half speed)
ffmpeg -i in.mp4 -vf "setpts=2.0*PTS" -af "atempo=0.5" out.mp4

# >4×: chain atempo (max 2.0 per filter)
ffmpeg -i in.mp4 -vf "setpts=0.25*PTS" -af "atempo=2.0,atempo=2.0" out.mp4

# <0.5×: chain atempo (min 0.5 per filter)
ffmpeg -i in.mp4 -vf "setpts=4.0*PTS" -af "atempo=0.5,atempo=0.5" out.mp4

Reverse

ffmpeg -i in.mp4 -vf "reverse" -af "areverse" out.mp4

Transitions (xfade)

# Dissolve between two clips (1s overlap at t=5)
ffmpeg -i a.mp4 -i b.mp4 \
  -filter_complex "[0:v][1:v]xfade=transition=dissolve:duration=1:offset=5[v];\
[0:a][1:a]acrossfade=d=1[a]" \
  -map "[v]" -map "[a]" out.mp4

See references/TRANSITIONS.md for all 40+ xfade transition types.

Audio: Volume & Normalization

# Adjust volume
ffmpeg -i in.mp4 -af "volume=1.5" out.mp4

# EBU R128 normalization (two-pass)
scripts/normalize-audio.sh in.mp4 out.mp4

# One-pass loudnorm
ffmpeg -i in.mp4 -af "loudnorm=I=-16:TP=-1.5:LRA=11" out.mp4

Audio: Fade In/Out

# Fade in 2s at start, fade out 3s before end (total 60s)
ffmpeg -i in.mp4 -af "afade=t=in:d=2,afade=t=out:st=57:d=3" out.mp4

Mix / Combine Audio

# Mix two audio streams
ffmpeg -i video.mp4 -i music.mp3 \
  -filter_complex "[0:a][1:a]amix=inputs=2:duration=first:weights=1 0.3[a]" \
  -map 0:v -map "[a]" -c:v copy out.mp4

Color Grading

# Brightness/Contrast/Saturation
ffmpeg -i in.mp4 -vf "eq=brightness=0.05:contrast=1.2:saturation=1.3" out.mp4

# Hue shift
ffmpeg -i in.mp4 -vf "hue=h=30:s=1.1" out.mp4

# Apply 3D LUT (.cube)
ffmpeg -i in.mp4 -vf "lut3d=file=lut.cube" out.mp4

# Apply Hald CLUT PNG
ffmpeg -i in.mp4 -i lut.png \
  -filter_complex "[0:v][1:v]haldclut" out.mp4

Chroma Key / Green Screen

# chromakey (color + similarity + blend)
ffmpeg -i foreground.mp4 -i background.mp4 \
  -filter_complex "[0:v]chromakey=0x00FF00:0.3:0.2[fg];\
[1:v][fg]overlay" out.mp4

# colorkey (simpler, exact color)
ffmpeg -i in.mp4 -vf "colorkey=green:0.3:0.2" out.mp4

Frame Rate Conversion

# Convert to 30fps
ffmpeg -i in.mp4 -vf "fps=30" out.mp4

# Use motion interpolation (minterpolate)
ffmpeg -i in.mp4 -vf "minterpolate=fps=60:mi_mode=mci" out.mp4

Extract Frames / Create Slideshow

# Extract one frame per second as PNG
ffmpeg -i in.mp4 -vf "fps=1" frames/%04d.png

# Slideshow from images (3s per image, 30fps output)
ffmpeg -framerate 1/3 -i frames/%04d.png -c:v libx264 -r 30 out.mp4

Stacking / Grid Layout

# Side by side (hstack)
ffmpeg -i a.mp4 -i b.mp4 -filter_complex "[0:v][1:v]hstack=inputs=2" out.mp4

# Top-bottom (vstack)
ffmpeg -i a.mp4 -i b.mp4 -filter_complex "[0:v][1:v]vstack=inputs=2" out.mp4

# 2×2 grid (xstack)
ffmpeg -i a.mp4 -i b.mp4 -i c.mp4 -i d.mp4 \
  -filter_complex "[0:v][1:v][2:v][3:v]xstack=inputs=4:layout=0_0|w0_0|0_h0|w0_h0" out.mp4

Hardware-Accelerated Encoding

# NVIDIA NVENC H.264
ffmpeg -hwaccel cuda -i in.mp4 -c:v h264_nvenc -preset p4 -cq 23 out.mp4

# Apple VideoToolbox H.265
ffmpeg -i in.mp4 -c:v hevc_videotoolbox -q:v 60 out.mp4

# Intel QuickSync H.264
ffmpeg -hwaccel qsv -i in.mp4 -c:v h264_qsv -global_quality 23 out.mp4

See references/HARDWARE-ACCEL.md for full GPU encoding guide.

Encoding Presets (assets/preset-profiles.json)

When the task maps to a named use case below, read assets/preset-profiles.json and use the example field as the ready-made ffmpeg command.

Profile	Codec	CRF	Use Case
web-optimized	H.264	23	Browser streaming
high-quality	H.264	18	Archive / master
social-media-vertical	H.264	23	9:16 TikTok/Reels
social-media-square	H.264	23	1:1 Instagram
fast-preview	H.264	28	Proxy / review
lossless-intermediate	FFV1	—	Post-production store

Multi-Stream Filter Graph Pattern

ffmpeg \
  -i input_video.mp4 \
  -i overlay.png \
  -i audio_bed.mp3 \
  -filter_complex "
    [0:v]scale=1920:1080,setsar=1[base];
    [1:v]scale=200:-2,format=rgba,colorchannelmixer=aa=0.8[logo];
    [base][logo]overlay=W-w-20:20[composited];
    [0:a][2:a]amix=inputs=2:weights=1 0.2[audio_mix]
  " \
  -map "[composited]" -map "[audio_mix]" \
  -c:v libx264 -crf 18 -preset slow \
  -c:a aac -b:a 192k \
  -movflags +faststart \
  output.mp4

Common Options Reference

Flag	Meaning
`-ss`	Seek/start time (before `-i` = fast seek)
`-to`	End time (absolute)
`-t`	Duration
`-c copy`	Stream copy (no re-encode)
`-crf`	Constant Rate Factor (lower = better)
`-preset`	Encoder speed/quality tradeoff
`-movflags +faststart`	Move moov atom to front (web streaming)
`-vf`	Video filter chain
`-af`	Audio filter chain
`-filter_complex`	Multi-input/output filter graph
`-map`	Select output streams explicitly
`-an`	Drop audio
`-vn`	Drop video
`-y`	Overwrite output without prompt

Debugging Tips

# Dry-run: print filter graph without encoding
ffmpeg -i in.mp4 -vf "scale=1280:-2" -f null -

# Benchmark encode speed
ffmpeg -benchmark -i in.mp4 -c:v libx264 -f null -

# Show available encoders
ffmpeg -encoders | grep -E "^.V|^.A"

# Show filter options
ffmpeg -help filter=loudnorm