ai-video-editor

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

原始内容

---
name: ai-video-editor
description: This skill provides AI-powered video editing — transcription with Whisper, intelligent clip selection, highlight reel creation, xfade transitions, audio mixing with music overlay, and multi-platform export for YouTube, LinkedIn, TikTok, Instagram, and Twitter/X. This skill should be used when editing video, creating highlight reels, transcribing audio, cutting clips, adding transitions, mixing audio tracks, or exporting video for social media platforms.
---

# AI Video Editor

AI-powered video editing combining Whisper transcription, intelligent content analysis, and FFmpeg precision editing. Turn long-form footage into polished highlight reels with crossfade transitions, background music, and multi-platform export.

## Essential Principles

### 1. Analyze Before Cutting

Always run `ffprobe` metadata extraction and review transcription before making any cuts. Understand the content, resolution, codec, and framerate first.

```bash
ffprobe -v quiet -print_format json -show_format -show_streams input.mp4
```

### 2. Keyframe-Aligned Cuts

Use re-encoding for frame-accurate cuts. Stream copy (`-c copy`) cuts at the nearest keyframe, producing imprecise edits.

```bash
# Correct: re-encode for precision
ffmpeg -ss 26 -i input.mp4 -t 22 -c:v libx264 -preset medium -crf 18 -c:a aac -b:a 192k -pix_fmt yuv420p clip.mp4

# Wrong: stream copy, imprecise
ffmpeg -ss 26 -i input.mp4 -t 22 -c copy clip.mp4
```

### 3. Non-Destructive Workflow

Never modify source files. All operations produce new output files. Keep intermediates until final export is verified.

### 4. AI Judges Content, FFmpeg Executes

Claude's role is understanding what makes a good clip — energy, key quotes, statistics, audience engagement, narrative arc. FFmpeg handles the mechanical cutting, joining, and encoding.

---

## Quick Start

Fastest path from source video to highlight reel:

1. **Analyze**: `ffprobe -v quiet -print_format json -show_format -show_streams input.mp4`
2. **Extract audio**: `ffmpeg -i input.mp4 -vn -ac 1 -ar 16000 -acodec pcm_s16le audio.wav`
3. **Transcribe**: Run [transcribe.py](https://github.com/aacamara/ai-video-editor/blob/HEAD/scripts/transcribe.py) or use mlx-whisper directly
4. **Read transcript** — Identify 5-7 strongest moments (key stats, quotable lines, emotional peaks)
5. **Cut clips**: Run [extract_clips.py](https://github.com/aacamara/ai-video-editor/blob/HEAD/scripts/extract_clips.py) with a clips JSON config
6. **Build reel**: Run [build_reel.py](https://github.com/aacamara/ai-video-editor/blob/HEAD/scripts/build_reel.py) to concatenate with xfade transitions
7. **Export**: Run [export_platforms.py](https://github.com/aacamara/ai-video-editor/blob/HEAD/scripts/export_platforms.py) for target platform

---

## Workflow Router

Determine the video editing task and follow the appropriate workflow:

| Task | Keywords | Action |
|------|----------|--------|
| Analyze video | "analyze", "metadata", "ffprobe", "info" | Read [ffmpeg-filters.md](https://github.com/aacamara/ai-video-editor/blob/HEAD/references/ffmpeg-filters.md), run [analyze_video.py](https://github.com/aacamara/ai-video-editor/blob/HEAD/scripts/analyze_video.py) |
| Transcribe | "transcribe", "whisper", "transcript", "captions" | Read [transcription-guide.md](https://github.com/aacamara/ai-video-editor/blob/HEAD/references/transcription-guide.md), run [transcribe.py](https://github.com/aacamara/ai-video-editor/blob/HEAD/scripts/transcribe.py) |
| Highlight reel | "highlight", "reel", "summary", "best moments" | Full pipeline: transcribe → analyze → extract → build → export |
| Cut clips | "cut", "clip", "extract", "trim", "segment" | Run [extract_clips.py](https://github.com/aacamara/ai-video-editor/blob/HEAD/scripts/extract_clips.py) |
| Add transitions | "transition", "xfade", "crossfade", "concatenate" | Read [ffmpeg-filters.md](https://github.com/aacamara/ai-video-editor/blob/HEAD/references/ffmpeg-filters.md), run [build_reel.py](https://github.com/aacamara/ai-video-editor/blob/HEAD/scripts/build_reel.py) |
| Mix audio | "audio", "music", "mix", "ducking", "background" | Read [audio-mixing.md](https://github.com/aacamara/ai-video-editor/blob/HEAD/references/audio-mixing.md), run [mix_audio.py](https://github.com/aacamara/ai-video-editor/blob/HEAD/scripts/mix_audio.py) |
| Export for platform | "export", "youtube", "linkedin", "tiktok", "instagram" | Read [platform-export-specs.md](https://github.com/aacamara/ai-video-editor/blob/HEAD/references/platform-export-specs.md), run [export_platforms.py](https://github.com/aacamara/ai-video-editor/blob/HEAD/scripts/export_platforms.py) |

---

## Anti-Patterns

### 1. Stream Copy for Precision Cuts

**Problem**: Using `-c copy` for clip extraction produces cuts at the nearest keyframe, not the requested timestamp.

**Wrong**:
```bash
ffmpeg -ss 133 -i input.mp4 -t 22 -c copy clip.mp4
# Actual cut point may be 1-5 seconds off
```

**Correct**:
```bash
ffmpeg -ss 133 -i input.mp4 -t 22 -c:v libx264 -preset medium -crf 18 -c:a aac -b:a 192k -pix_fmt yuv420p clip.mp4
```

### 2. Seeking After Input

**Problem**: Placing `-ss` after `-i` forces ffmpeg to decode everything up to the seek point.

**Wrong** (slow — decodes 600 seconds of video):
```bash
ffmpeg -i input.mp4 -ss 600 -t 30 -c:v libx264 output.mp4
```

**Correct** (fast — seeks directly):
```bash
ffmpeg -ss 600 -i input.mp4 -t 30 -c:v libx264 output.mp4
```

### 3. Hardcoded Pixel Dimensions

**Problem**: Using `scale=1920:1080` distorts non-16:9 source material.

**Wrong**:
```bash
ffmpeg -i input.mp4 -vf "scale=1920:1080" output.mp4
# Stretches 4:3 or ultrawide content
```

**Correct** (preserves aspect ratio with letterboxing):
```bash
ffmpeg -i input.mp4 -vf "scale=1920:1080:force_original_aspect_ratio=decrease,pad=1920:1080:(ow-iw)/2:(oh-ih)/2" output.mp4
```

### 4. Missing Pixel Format

**Problem**: Omitting `-pix_fmt yuv420p` can produce videos that fail on mobile players, browsers, or social media platforms.

**Correct**: Always include `-pix_fmt yuv420p` for maximum compatibility.

### 5. No Faststart Flag for Web Delivery

**Problem**: Without `-movflags +faststart`, the moov atom is at the end of the file. The entire video must download before playback begins.

**Correct**: Always add `-movflags +faststart` for any video delivered via web or social media.

### 6. Transcribing Full-Quality Audio

**Problem**: Feeding 48kHz stereo WAV to Whisper wastes memory and processing time. Whisper internally downsamples to 16kHz mono.

**Wrong**:
```bash
ffmpeg -i input.mp4 -vn audio.wav  # 48kHz stereo, 4x larger than needed
```

**Correct**:
```bash
ffmpeg -i input.mp4 -vn -ac 1 -ar 16000 -acodec pcm_s16le audio.wav
```

### 7. Cumulative xfade Offset Miscalculation

**Problem**: Using clip start times or simple addition as xfade offsets produces broken transitions. Each crossfade shortens total output duration.

**Wrong**: `offset = clip_start_time` or `offset = sum(all_durations)`

**Correct formula**:
```
offset[0] = duration[0] - crossfade
cumulative = duration[0]
for i in 1..n-1:
    offset[i] = cumulative - crossfade
    cumulative = cumulative + duration[i] - crossfade
```

**Worked example** (7 clips, 0.5s crossfade):
```
Durations: [6, 22, 22, 36, 29, 33, 20]
Offset 1: 6 - 0.5 = 5.5      | cumulative: 27.5
Offset 2: 27.5 - 0.5 = 27.0   | cumulative: 49.0
Offset 3: 49.0 - 0.5 = 48.5   | cumulative: 84.5
Offset 4: 84.5 - 0.5 = 84.0   | cumulative: 113.0
Offset 5: 113.0 - 0.5 = 112.5 | cumulative: 145.5
Offset 6: 145.5 - 0.5 = 145.0 | final duration: 165.0s
```

---

## Platform Export Presets

| Platform | Resolution | Aspect | Max Duration | Codec | Bitrate | Key Flags |
|----------|-----------|--------|-------------|-------|---------|-----------|
| YouTube 4K | 3840x2160 | 16:9 | 12h | H.264 | 35-45 Mbps | CRF 18, +faststart |
| YouTube 1080p | 1920x1080 | 16:9 | 12h | H.264 | 8-12 Mbps | CRF 20, +faststart |
| LinkedIn | 1920x1080 | 16:9 / 1:1 | 10 min | H.264 | 5 Mbps | Max 5GB, captions recommended |
| TikTok | 1080x1920 | 9:16 | 10 min | H.264 | 5-8 Mbps | Vertical, safe zones top/bottom |
| Instagram Reels | 1080x1920 | 9:16 | 90 sec | H.264 | 3.5 Mbps | Cover frame at 0:01 |
| Instagram Feed | 1080x1080 | 1:1 | 60 sec | H.264 | 3.5 Mbps | Square, autoplay muted |
| Twitter/X | 1920x1080 | 16:9 | 2:20 | H.264 | 5 Mbps | Max 512MB |

See [platform-export-specs.md](https://github.com/aacamara/ai-video-editor/blob/HEAD/references/platform-export-specs.md) for complete ffmpeg commands per platform.

---

## Production Checklist

Before exporting final video:

- [ ] Source video analyzed with ffprobe (resolution, codec, framerate, duration confirmed)
- [ ] Audio extracted at 16kHz mono for transcription
- [ ] Transcript reviewed for accuracy (names, technical terms, timestamps)
- [ ] Clip boundaries verified (no mid-word cuts, natural sentence breaks)
- [ ] All clips re-encoded with matching framerate and pixel format (yuv420p)
- [ ] Transitions verified (xfade offsets calculated cumulatively)
- [ ] Audio levels consistent (target -14 LUFS for web, -16 LUFS for broadcast)
- [ ] Background music volume ducked during speech (12-15% of full volume)
- [ ] Output includes `-movflags +faststart`
- [ ] Output verified with ffprobe (correct duration, resolution, codec)

---

## Requirements

```
Prerequisites:
- ffmpeg 5+ with libx264 support (brew install ffmpeg / apt install ffmpeg)
- ffprobe (included with ffmpeg)
- Python 3.10+
- mlx-whisper (Apple Silicon, recommended): pip install mlx-whisper
  OR openai-whisper (NVIDIA GPU): pip install openai-whisper
```

---

## References

- [ffmpeg-filters.md](https://github.com/aacamara/ai-video-editor/blob/HEAD/references/ffmpeg-filters.md) — xfade transitions, audio filters, filter chain syntax, CRF/preset guide
- [transcription-guide.md](https://github.com/aacamara/ai-video-editor/blob/HEAD/references/transcription-guide.md) — Whisper model selection, audio extraction, JSON schema, AI analysis prompts
- [audio-mixing.md](https://github.com/aacamara/ai-video-editor/blob/HEAD/references/audio-mixing.md) — Volume envelopes, loudness standards, music integration, crossfade curves
- [platform-export-specs.md](https://github.com/aacamara/ai-video-editor/blob/HEAD/references/platform-export-specs.md) — Per-platform export commands for YouTube, LinkedIn, TikTok, Instagram, Twitter/X

## Scripts

- [analyze_video.py](https://github.com/aacamara/ai-video-editor/blob/HEAD/scripts/analyze_video.py) — Extract and display video metadata via ffprobe
- [transcribe.py](https://github.com/aacamara/ai-video-editor/blob/HEAD/scripts/transcribe.py) — Extract audio and transcribe with Whisper (word-level timestamps)
- [extract_clips.py](https://github.com/aacamara/ai-video-editor/blob/HEAD/scripts/extract_clips.py) — Cut clips from JSON config with frame-accurate re-encoding
- [build_reel.py](https://github.com/aacamara/ai-video-editor/blob/HEAD/scripts/build_reel.py) — Concatenate clips with xfade/acrossfade transitions
- [mix_audio.py](https://github.com/aacamara/ai-video-editor/blob/HEAD/scripts/mix_audio.py) — Overlay background music with volume envelope
- [export_platforms.py](https://github.com/aacamara/ai-video-editor/blob/HEAD/scripts/export_platforms.py) — Export video optimized for specific platforms

name: ai-video-editor description: This skill provides AI-powered video editing — transcription with Whisper, intelligent clip selection, highlight reel creation, xfade transitions, audio mixing with music overlay, and multi-platform export for YouTube, LinkedIn, TikTok, Instagram, and Twitter/X. This skill should be used when editing video, creating highlight reels, transcribing audio, cutting clips, adding transitions, mixing audio tracks, or exporting video for social media platforms.

AI Video Editor

AI-powered video editing combining Whisper transcription, intelligent content analysis, and FFmpeg precision editing. Turn long-form footage into polished highlight reels with crossfade transitions, background music, and multi-platform export.

Essential Principles

1. Analyze Before Cutting

Always run ffprobe metadata extraction and review transcription before making any cuts. Understand the content, resolution, codec, and framerate first.

ffprobe -v quiet -print_format json -show_format -show_streams input.mp4

2. Keyframe-Aligned Cuts

Use re-encoding for frame-accurate cuts. Stream copy (-c copy) cuts at the nearest keyframe, producing imprecise edits.

# Correct: re-encode for precision
ffmpeg -ss 26 -i input.mp4 -t 22 -c:v libx264 -preset medium -crf 18 -c:a aac -b:a 192k -pix_fmt yuv420p clip.mp4

# Wrong: stream copy, imprecise
ffmpeg -ss 26 -i input.mp4 -t 22 -c copy clip.mp4

3. Non-Destructive Workflow

Never modify source files. All operations produce new output files. Keep intermediates until final export is verified.

4. AI Judges Content, FFmpeg Executes

Claude's role is understanding what makes a good clip — energy, key quotes, statistics, audience engagement, narrative arc. FFmpeg handles the mechanical cutting, joining, and encoding.

Quick Start

Fastest path from source video to highlight reel:

Analyze: ffprobe -v quiet -print_format json -show_format -show_streams input.mp4
Extract audio: ffmpeg -i input.mp4 -vn -ac 1 -ar 16000 -acodec pcm_s16le audio.wav
Transcribe: Run transcribe.py or use mlx-whisper directly
Read transcript — Identify 5-7 strongest moments (key stats, quotable lines, emotional peaks)
Cut clips: Run extract_clips.py with a clips JSON config
Build reel: Run build_reel.py to concatenate with xfade transitions
Export: Run export_platforms.py for target platform

Workflow Router

Determine the video editing task and follow the appropriate workflow:

Task	Keywords	Action
Analyze video	"analyze", "metadata", "ffprobe", "info"	Read ffmpeg-filters.md, run analyze_video.py
Transcribe	"transcribe", "whisper", "transcript", "captions"	Read transcription-guide.md, run transcribe.py
Highlight reel	"highlight", "reel", "summary", "best moments"	Full pipeline: transcribe → analyze → extract → build → export
Cut clips	"cut", "clip", "extract", "trim", "segment"	Run extract_clips.py
Add transitions	"transition", "xfade", "crossfade", "concatenate"	Read ffmpeg-filters.md, run build_reel.py
Mix audio	"audio", "music", "mix", "ducking", "background"	Read audio-mixing.md, run mix_audio.py
Export for platform	"export", "youtube", "linkedin", "tiktok", "instagram"	Read platform-export-specs.md, run export_platforms.py

Anti-Patterns

1. Stream Copy for Precision Cuts

Problem: Using -c copy for clip extraction produces cuts at the nearest keyframe, not the requested timestamp.

Wrong:

ffmpeg -ss 133 -i input.mp4 -t 22 -c copy clip.mp4
# Actual cut point may be 1-5 seconds off

Correct:

ffmpeg -ss 133 -i input.mp4 -t 22 -c:v libx264 -preset medium -crf 18 -c:a aac -b:a 192k -pix_fmt yuv420p clip.mp4

2. Seeking After Input

Problem: Placing -ss after -i forces ffmpeg to decode everything up to the seek point.

Wrong (slow — decodes 600 seconds of video):

ffmpeg -i input.mp4 -ss 600 -t 30 -c:v libx264 output.mp4

Correct (fast — seeks directly):

ffmpeg -ss 600 -i input.mp4 -t 30 -c:v libx264 output.mp4

3. Hardcoded Pixel Dimensions

Problem: Using scale=1920:1080 distorts non-16:9 source material.

Wrong:

ffmpeg -i input.mp4 -vf "scale=1920:1080" output.mp4
# Stretches 4:3 or ultrawide content

Correct (preserves aspect ratio with letterboxing):

ffmpeg -i input.mp4 -vf "scale=1920:1080:force_original_aspect_ratio=decrease,pad=1920:1080:(ow-iw)/2:(oh-ih)/2" output.mp4

4. Missing Pixel Format

Problem: Omitting -pix_fmt yuv420p can produce videos that fail on mobile players, browsers, or social media platforms.

Correct: Always include -pix_fmt yuv420p for maximum compatibility.

5. No Faststart Flag for Web Delivery

Problem: Without -movflags +faststart, the moov atom is at the end of the file. The entire video must download before playback begins.

Correct: Always add -movflags +faststart for any video delivered via web or social media.

6. Transcribing Full-Quality Audio

Problem: Feeding 48kHz stereo WAV to Whisper wastes memory and processing time. Whisper internally downsamples to 16kHz mono.

Wrong:

ffmpeg -i input.mp4 -vn audio.wav  # 48kHz stereo, 4x larger than needed

Correct:

ffmpeg -i input.mp4 -vn -ac 1 -ar 16000 -acodec pcm_s16le audio.wav

7. Cumulative xfade Offset Miscalculation

Problem: Using clip start times or simple addition as xfade offsets produces broken transitions. Each crossfade shortens total output duration.

Wrong: offset = clip_start_time or offset = sum(all_durations)

Correct formula:

offset[0] = duration[0] - crossfade
cumulative = duration[0]
for i in 1..n-1:
    offset[i] = cumulative - crossfade
    cumulative = cumulative + duration[i] - crossfade

Worked example (7 clips, 0.5s crossfade):

Durations: [6, 22, 22, 36, 29, 33, 20]
Offset 1: 6 - 0.5 = 5.5      | cumulative: 27.5
Offset 2: 27.5 - 0.5 = 27.0   | cumulative: 49.0
Offset 3: 49.0 - 0.5 = 48.5   | cumulative: 84.5
Offset 4: 84.5 - 0.5 = 84.0   | cumulative: 113.0
Offset 5: 113.0 - 0.5 = 112.5 | cumulative: 145.5
Offset 6: 145.5 - 0.5 = 145.0 | final duration: 165.0s

Platform Export Presets

Platform	Resolution	Aspect	Max Duration	Codec	Bitrate	Key Flags
YouTube 4K	3840x2160	16:9	12h	H.264	35-45 Mbps	CRF 18, +faststart
YouTube 1080p	1920x1080	16:9	12h	H.264	8-12 Mbps	CRF 20, +faststart
LinkedIn	1920x1080	16:9 / 1:1	10 min	H.264	5 Mbps	Max 5GB, captions recommended
TikTok	1080x1920	9:16	10 min	H.264	5-8 Mbps	Vertical, safe zones top/bottom
Instagram Reels	1080x1920	9:16	90 sec	H.264	3.5 Mbps	Cover frame at 0:01
Instagram Feed	1080x1080	1:1	60 sec	H.264	3.5 Mbps	Square, autoplay muted
Twitter/X	1920x1080	16:9	2:20	H.264	5 Mbps	Max 512MB

See platform-export-specs.md for complete ffmpeg commands per platform.

Production Checklist

Before exporting final video:

Source video analyzed with ffprobe (resolution, codec, framerate, duration confirmed)
Audio extracted at 16kHz mono for transcription
Transcript reviewed for accuracy (names, technical terms, timestamps)
Clip boundaries verified (no mid-word cuts, natural sentence breaks)
All clips re-encoded with matching framerate and pixel format (yuv420p)
Transitions verified (xfade offsets calculated cumulatively)
Audio levels consistent (target -14 LUFS for web, -16 LUFS for broadcast)
Background music volume ducked during speech (12-15% of full volume)
Output includes -movflags +faststart
Output verified with ffprobe (correct duration, resolution, codec)

Requirements

Prerequisites:
- ffmpeg 5+ with libx264 support (brew install ffmpeg / apt install ffmpeg)
- ffprobe (included with ffmpeg)
- Python 3.10+
- mlx-whisper (Apple Silicon, recommended): pip install mlx-whisper
  OR openai-whisper (NVIDIA GPU): pip install openai-whisper

References

ffmpeg-filters.md — xfade transitions, audio filters, filter chain syntax, CRF/preset guide
transcription-guide.md — Whisper model selection, audio extraction, JSON schema, AI analysis prompts
audio-mixing.md — Volume envelopes, loudness standards, music integration, crossfade curves
platform-export-specs.md — Per-platform export commands for YouTube, LinkedIn, TikTok, Instagram, Twitter/X

Scripts

analyze_video.py — Extract and display video metadata via ffprobe
transcribe.py — Extract audio and transcribe with Whisper (word-level timestamps)
extract_clips.py — Cut clips from JSON config with frame-accurate re-encoding
build_reel.py — Concatenate clips with xfade/acrossfade transitions
mix_audio.py — Overlay background music with volume envelope
export_platforms.py — Export video optimized for specific platforms