claude-video-transcode

claude-video-transcode — Codec Conversion and Compression

Pre-Flight

1. Run bash scripts/preflight.sh "$INPUT" "$OUTPUT"
2. Run bash scripts/detect_gpu.sh to determine available encoders
3. Run bash scripts/estimate_size.sh "$INPUT" for large files
4. Analyze input: ffprobe -v error -print_format json -show_format -show_streams "$INPUT"

Codec Selection Guide

Goal	Codec	Encoder (GPU)	Encoder (CPU)	CRF/CQ
Best compression (modern)	AV1	av1_nvenc -cq 30	libsvtav1 -crf 28	28-32
Maximum compatibility	H.264	h264_nvenc -cq 21	libx264 -crf 20	18-23
Good compression + compat	H.265	hevc_nvenc -cq 26	libx265 -crf 24	22-28
Web browsers	VP9	N/A	libvpx-vp9 -crf 30	25-35
Professional editing	ProRes	N/A	prores_ks -profile:v 3	N/A
Professional editing	DNxHR	N/A	dnxhd -profile:v dnxhr_hq	N/A
No re-encode needed	Copy	-c copy	-c copy	N/A

CRF equivalence: x264 CRF 23 ≈ x265 CRF 28 ≈ SVT-AV1 CRF 30 (similar visual quality, decreasing file size). Each ±6 CRF roughly doubles or halves the bitrate.

Common Operations

Simple Compression (H.264, CPU)

ffmpeg -n -i "$INPUT" -c:v libx264 -crf 20 -preset medium -pix_fmt yuv420p \
  -c:a aac -b:a 192k -movflags +faststart "$OUTPUT"

GPU-Accelerated (NVENC)

H.264 NVENC:

ffmpeg -n -hwaccel cuda -hwaccel_output_format cuda -i "$INPUT" \
  -c:v h264_nvenc -preset p5 -tune hq -rc constqp -cq 21 \
  -spatial-aq 1 -temporal-aq 1 -rc-lookahead 32 \
  -c:a aac -b:a 192k -movflags +faststart "$OUTPUT"

H.265 NVENC:

ffmpeg -n -hwaccel cuda -hwaccel_output_format cuda -i "$INPUT" \
  -c:v hevc_nvenc -preset p5 -tune hq -rc constqp -cq 26 \
  -spatial-aq 1 -temporal-aq 1 -rc-lookahead 32 \
  -tag:v hvc1 -c:a aac -b:a 192k -movflags +faststart "$OUTPUT"

AV1 NVENC (RTX 40/50 series):

ffmpeg -n -hwaccel cuda -hwaccel_output_format cuda -i "$INPUT" \
  -c:v av1_nvenc -preset p5 -tune hq -rc constqp -cq 30 \
  -c:a aac -b:a 192k -movflags +faststart "$OUTPUT"

AV1 Software (best compression, slow)

ffmpeg -n -i "$INPUT" -c:v libsvtav1 -crf 28 -preset 6 -pix_fmt yuv420p10le \
  -svtav1-params tune=0 -c:a libopus -b:a 128k "$OUTPUT"

Two-Pass Encoding (target specific bitrate)

# Pass 1
ffmpeg -y -i "$INPUT" -c:v libx264 -b:v 5M -pass 1 -passlogfile /tmp/ffmpeg2pass \
  -an -f null /dev/null

# Pass 2
ffmpeg -n -i "$INPUT" -c:v libx264 -b:v 5M -pass 2 -passlogfile /tmp/ffmpeg2pass \
  -c:a aac -b:a 192k -movflags +faststart "$OUTPUT"

rm -f /tmp/ffmpeg2pass-0.log /tmp/ffmpeg2pass-0.log.mbtree

Container Remux (no re-encode)

# MKV to MP4
ffmpeg -n -i input.mkv -c copy -movflags +faststart output.mp4

# MP4 to MKV
ffmpeg -n -i input.mp4 -c copy output.mkv

# Any to WebM (requires VP9/AV1 video + Opus/Vorbis audio — may need re-encode)
ffmpeg -n -i input.mp4 -c:v libvpx-vp9 -crf 30 -b:v 0 -row-mt 1 \
  -c:a libopus -b:a 128k output.webm

GPU Fallback Pattern

# Try GPU first, fall back to CPU
ffmpeg -n -hwaccel cuda -hwaccel_output_format cuda -i "$INPUT" \
  -c:v h264_nvenc -preset p5 -tune hq -rc constqp -cq 21 \
  -c:a aac -b:a 192k -movflags +faststart "$OUTPUT" 2>/dev/null || \
ffmpeg -n -i "$INPUT" \
  -c:v libx264 -crf 20 -preset medium \
  -c:a aac -b:a 192k -movflags +faststart "$OUTPUT"

Batch Transcoding

# Process all MKV files in a directory
for f in /path/to/input/*.mkv; do
  ffmpeg -n -hwaccel cuda -i "$f" \
    -c:v h264_nvenc -preset p5 -cq 21 \
    -c:a aac -b:a 192k -movflags +faststart \
    "/path/to/output/$(basename "${f%.mkv}.mp4")"
done

NVENC Presets

Preset	Speed	Quality	Use Case
p1	Fastest	Lowest	Preview/drafts
p3	Fast	Good	Quick exports
p4-p5	Balanced	Very good	General use (recommended)
p6-p7	Slow	Best	Final delivery

NVENC supports up to 8 concurrent encoding sessions on consumer GPUs.

Container Compatibility

Container	Video Codecs	Audio Codecs	Notes
MP4	H.264, H.265, AV1	AAC, AC3, MP3	Always add -movflags +faststart
MKV	Everything	Everything	Most flexible container
WebM	VP8, VP9, AV1	Vorbis, Opus	Web-optimized
MOV	ProRes, H.264, H.265	AAC, PCM	Apple/editing workflows
AVI	H.264, MPEG-4	MP3, PCM	Legacy, avoid for new content

Quality Optimization Tips

• Always use -pix_fmt yuv420p for maximum compatibility (unless 10-bit needed)
• Always add -movflags +faststart for MP4 output (moves metadata to beginning for streaming)
• Use -tag:v hvc1 for H.265 in MP4 (required for Apple device playback)
• Stream copy (-c copy) when only changing container — instant, lossless
• CRF mode is almost always better than target bitrate -- let the encoder decide

Reference

Load references/transcode.md for codec comparison tables, two-pass encoding recipes, and container compatibility matrix.