ffmpeg-graceful-degradation

FFmpeg Graceful Degradation

When processing videos with ffmpeg, encoding failures are common due to codec availability, library version mismatches, or system configuration issues. This skill provides a systematic fallback strategy to ensure video processing completes successfully.

Overview

The pattern involves: (1) probing encoder availability upfront, (2) testing on a short clip before batch processing, (3) progressive fallback through copy mode, alternative codecs, and finally moviepy, (4) using moviepy as a reliable bundled alternative.

Step 1: Probe Encoder Availability

Before any encoding work, check what encoders are available:

ffmpeg -encoders | grep -E "libx264|libopenh264|mpeg4"

Expected output shows which encoders are present:

• libx264 - Preferred H.264 encoder (may be missing)
• libopenh264 - Alternative H.264 (often has library issues)
• mpeg4 - Universal fallback (always available)

Step 2: Test Encoding on Single Short Clip

Never start batch processing without validation. Extract and test a short segment:

# Extract 5-second test clip
ffmpeg -y -i input.mp4 -ss 0 -t 5 -c copy test_clip.mp4

# Attempt encode with preferred codec
ffmpeg -y -i test_clip.mp4 -c:v libx264 -preset fast test_output.mp4

Check the exit code and output for errors. Common failures:

• libopenh264.so: wrong ELF class
• Encoder libx264 not found
• Library version mismatches

Step 3: Progressive Fallback Strategy

If the preferred encoder fails, try these fallbacks in order:

Fallback A: Copy Mode (No Re-encoding)

ffmpeg -y -i input.mp4 -c:v copy -c:a copy output.mp4

Fast, lossless, but doesn't change codec/format.

Fallback B: MPEG4 Codec

ffmpeg -y -i input.mp4 -c:v mpeg4 -q:v 3 -c:a copy output.mp4

Universal compatibility, larger file sizes, always available.

Fallback C: Install MoviePy (Bundles Working FFmpeg)

pip install moviepy

Then use Python instead of raw ffmpeg:

from moviepy.editor import VideoFileClip, concatenate_videoclips

# Single clip processing
clip = VideoFileClip("input.mp4")
clip.write_videofile("output.mp4", codec="libx264")

# Concatenate multiple clips
clips = [VideoFileClip(f) for f in clip_files]
final = concatenate_videoclips(clips)
final.write_videofile("output.mp4", codec="libx264")