Debug FFmpeg Skill
Troubleshoot FFmpeg-related issues in the video processing pipeline.
What This Skill Does
This skill helps diagnose and fix FFmpeg integration problems through systematic debugging:
- Verify FFmpeg Installation: Check if FFmpeg is accessible and version
- Test FFmpeg Commands: Run diagnostic commands to validate functionality
- Analyze Video Files: Inspect video file properties, codecs, and streams
- Debug Processing Errors: Identify specific issues in video/audio extraction
- Provide Solutions: Offer concrete fixes for common FFmpeg problems
Diagnostic Steps
When invoked, this skill follows this troubleshooting workflow:
1. Verify FFmpeg Accessibility
ffmpeg -version
Check for:
- FFmpeg version and build date
- Configuration flags and enabled libraries
- Supported codecs and formats
2. Inspect Video File Properties
For a given video file:
ffmpeg -i <video_file>
This reveals:
- Container format (MP4, MKV, AVI, etc.)
- Video codec (H.264, H.265, VP9, etc.)
- Audio codec (AAC, MP3, Opus, etc.)
- Duration, bitrate, resolution
- Stream mapping and metadata
3. Test Audio Extraction
Verify audio can be extracted properly:
ffmpeg -i <video_file> -vn -acodec pcm_s16le -ar 16000 -ac 1 test_output.wav
Parameters:
-vn: No video (audio only)-acodec pcm_s16le: 16-bit PCM audio-ar 16000: 16kHz sample rate (Whisper compatible)-ac 1: Mono audio
4. Test Video Stream Extraction
Check if video streams can be extracted:
ffmpeg -i <video_file> -an -vcodec copy test_output.mp4
5. Review Processing Logs
Check application logs for FFmpeg errors:
- Console output from
python cli.py process
- Log files in the project directory
- Error messages in transcription pipeline
Common Issues and Solutions
FFmpeg Not Found
Symptoms:
- "FFmpeg command not found"
- "No such file or directory"
- Pipeline fails at audio extraction
Solutions:
- Verify FFmpeg is in system PATH:
which ffmpeg (Linux/Mac) or where ffmpeg (Windows)
- Check FFmpeg installation:
ffmpeg -version
- Install/reinstall FFmpeg if missing
- Use absolute path in configuration
Audio Extraction Fails
Symptoms:
- Empty or corrupt audio files
- "Invalid data found when processing input"
- Zero-byte output files
Solutions:
- Check if video has audio stream:
ffmpeg -i <video> 2>&1 | grep Audio
- Try different audio codec: Use
-acodec libmp3lame instead of PCM
- Verify video file isn't corrupted: Play in media player
- Check disk space and permissions
Memory Issues
Symptoms:
- Process killed or crashes
- "Out of memory" errors
- System becomes unresponsive
Solutions:
- Process shorter video segments
- Reduce audio quality: Use
-ar 8000 instead of 16000
- Close other applications
- Monitor with
top or Task Manager
Codec Compatibility
Symptoms:
- "Unknown codec" errors
- "Encoder not found"
- Unsupported format messages
Solutions:
- Update FFmpeg to latest version
- Check codec support:
ffmpeg -codecs | grep <codec_name>
- Use compatible codecs: H.264 for video, AAC for audio
- Re-encode video if necessary
Encoding Errors
Symptoms:
- "Conversion failed" messages
- Corrupted output files
- Mismatched audio/video sync
Solutions:
- Specify output format explicitly:
-f wav
- Use safe encoder options:
-strict -2
- Check input file integrity
- Try copying stream without re-encoding:
-c copy
Advanced Debugging
Get Detailed Stream Information
ffprobe -v error -show_streams -show_format <video_file>
Test Specific Stream
ffmpeg -i <video> -map 0:a:0 output.wav # Extract first audio stream
ffmpeg -i <video> -map 0:v:0 output.mp4 # Extract first video stream
Enable Verbose Logging
ffmpeg -v verbose -i <input> <output>
MCP Tool Integration
Use mcp__videochunking-dev__check_pipeline_health to verify FFmpeg is properly installed and accessible before debugging.
Output
This skill provides:
- FFmpeg version and capabilities report
- Complete video file analysis (codecs, streams, metadata)
- Specific error messages with technical context
- Step-by-step recommended fixes
- Command examples for manual testing and validation
- Links to FFmpeg documentation for advanced issues
