Video Navigator Guide

Your agent for video processing and editing workflows — covering format conversion, transcoding, cutting, concatenation, and video optimization using FFmpeg and related tools.

When to Use This Agent

Choose Video Navigator Guide when:

• Converting between video formats (MP4, MKV, WebM, MOV)
• Transcoding video for web, mobile, or streaming platforms
• Cutting, trimming, and concatenating video segments
• Adding subtitles, watermarks, or overlays to video
• Optimizing video for specific platforms (YouTube, Vimeo, social media)

Consider alternatives when:

• You need audio-only processing — use an Audio Mixer agent
• You need social media clip creation — use a Social Media Clip agent
• You need real-time video streaming architecture — use a streaming agent

Quick Start

Copy
# .claude/agents/video-navigator.yml
name: Video Navigator Guide
model: claude-sonnet
tools:
  - Read
  - Write
  - Edit
  - Bash
  - Glob
  - Grep
description: Video processing agent for format conversion, transcoding, editing, and platform optimization using FFmpeg

Example invocation:

claude "Convert our 4K recording to web-optimized MP4 — H.264 at 1080p, AAC audio, with a 5-second fade-in and burned-in SRT subtitles"

Core Concepts

Common FFmpeg Video Operations

Copy
# Convert to web-optimized MP4
ffmpeg -i input.mov -c:v libx264 -preset medium -crf 23 \
  -c:a aac -b:a 128k -movflags +faststart output.mp4

# Scale to 1080p maintaining aspect ratio
ffmpeg -i input.mp4 -vf "scale=1920:-2" -c:a copy output.mp4

# Cut without re-encoding (fast, keyframe-aligned)
ffmpeg -i input.mp4 -ss 00:01:00 -to 00:05:00 -c copy output.mp4

# Concatenate multiple videos
ffmpeg -f concat -safe 0 -i filelist.txt -c copy output.mp4

# Add burned-in subtitles
ffmpeg -i input.mp4 -vf "subtitles=subs.srt" output.mp4

Video Codec Comparison

Codec	Quality	Speed	Compatibility	Use Case
H.264	Good	Fast	Universal	Web, mobile, streaming
H.265/HEVC	Better	Slow	Modern devices	4K, storage-constrained
VP9	Better	Slow	Web browsers	YouTube, WebM
AV1	Best	Very slow	Newer browsers	Future-proof streaming

Configuration

Parameter	Description	Default
codec	Video codec (h264, h265, vp9, av1)	h264
preset	Encoding speed/quality trade-off	medium
crf	Constant Rate Factor quality (0-51, lower=better)	23
resolution	Output resolution	source
audio_codec	Audio codec (aac, opus, copy)	aac

Best Practices

1. Use -movflags +faststart for web video. This flag moves the video metadata (moov atom) to the beginning of the file, enabling streaming playback before the full download completes. Without it, the browser must download the entire file before playback starts.

2. Choose CRF (quality-based) encoding over fixed bitrate. CRF gives consistent visual quality regardless of scene complexity. CRF 23 is the H.264 default — lower values (18-20) produce higher quality at larger file sizes. Use fixed bitrate only when file size must be predictable.

3. Use -preset to balance encoding speed and compression. Slower presets (slow, veryslow) produce smaller files at the same quality. For real-time or batch processing, medium is a good balance. For archive encoding where time isn't critical, use slow.

4. Copy streams when possible to avoid re-encoding. When cutting, concatenating, or changing containers without modifying video/audio content, use -c copy to stream-copy without quality loss. Re-encoding is only needed when changing resolution, codec, or applying filters.

5. Test encoding settings on a 30-second sample first. Encode a short clip with your settings before processing a 2-hour file. This catches setting errors quickly and lets you compare quality/size trade-offs without waiting for a full encode.

Common Issues

Video plays in some players but not others. Incompatible codec/container combinations cause this. H.264 in MP4 is the most universally compatible. Use -c:v libx264 -profile:v high -level 4.1 for maximum compatibility. Check that the pixel format is yuv420p (not yuv444p).

Cut video has audio sync issues. When using -ss after -i (slow seek), audio and video may desync at the cut point. Use -ss before -i for fast keyframe-seeking, or use -async 1 to force audio resync.

Output file is much larger than expected. The default CRF and preset may produce larger files than needed. Increase CRF value (e.g., 28 for acceptable web quality), use a slower preset, or reduce resolution. Two-pass encoding (-pass 1 / -pass 2) gives better size-to-quality ratio for target bitrate encoding.