gwutilz/gwencoder/docs/guides/TROUBLESHOOTING.md

Troubleshooting Guide

Common issues and solutions for GWEncoder.

Installation Issues

FFmpeg Not Found

Error:

❌ FFmpeg: Not available

Solution:

1. Install FFmpeg for your system:
   • Linux: sudo apt install ffmpeg (Debian/Ubuntu) or sudo yum install ffmpeg (RHEL/CentOS)
   • macOS: brew install ffmpeg
   • Windows: Download from ffmpeg.org
2. Ensure FFmpeg is in your PATH
3. Verify installation: ffmpeg -version

FFprobe Not Found

Error:

❌ FFprobe: Not available

Solution:

• FFprobe is typically included with FFmpeg
• If missing, install FFmpeg (see above)
• Verify: ffprobe -version

ccextractor Not Found

Warning:

⚠️  ccextractor not available in PATH, skipping CC extraction

Solution:

• This is optional - CC extraction will be skipped if ccextractor is unavailable
• To enable CC extraction:
  • Linux: sudo apt install ccextractor or compile from source
  • macOS: brew install ccextractor
  • Windows: Download from ccextractor.org
• Verify: ccextractor -version

Encoding Issues

Odd Video Height Error

Error:

Error: Source Height must be even for YUV_420 colorspace

Solution:

• Automatically handled - GWEncoder detects and adjusts odd heights
• The height is automatically rounded to the nearest even number
• No user action required

Unsupported Streams in MKV

Warning:

⚠️  Filtered X unsupported stream(s) for MKV compatibility

Solution:

• Automatically handled - Unsupported streams are filtered for MKV output
• Streams like EIA-608, CC_DEC, tx3g are incompatible with MKV
• Container is automatically switched to MP4 if needed
• No user action required

Container Switch Notification

Message:

📦 Switching to MP4 container for compatibility (Apple/broadcast streams detected)

Explanation:

• GWEncoder automatically switches to MP4 when:
  • Input is Apple/broadcast format (MP4/MOV)
  • Unsupported subtitle streams are detected
• This prevents muxing errors
• No user action required

Encoding Fails with "Stream map matches no streams"

Error:

Stream map '' matches no streams

Solution:

• Usually caused by missing audio streams
• GWEncoder handles this automatically with optional mapping (-map 0:a?)
• If issue persists, check input file with: ffprobe input.mp4

Low Encoding Speed

Issue: Encoding is very slow

Solutions:

1. Use faster preset:

   ./gwencoder --fast --av1-preset 12
   

2. Disable advanced features:

   ./gwencoder --fast --av1-disable-tf --av1-disable-scd --av1-disable-aq
   

3. Use hardware acceleration (if available):

   ./gwencoder --fast --nvhevc
   

4. Use lower quality:

   ./gwencoder --fast --av1-crf 35
   

Audio Issues

Opus Incompatible Layout

Warning:

🔊 Converting incompatible layout to stereo for Opus compatibility

Explanation:

• Some channel layouts are incompatible with Opus
• GWEncoder automatically converts to stereo
• No user action required

Audio Codec Mismatch

Issue: Audio codec doesn't match container

Solution:

• GWEncoder automatically selects compatible codec:
  • MP4 → AAC
  • MKV/WEBM → Opus
• Force specific codec if needed:

  ./gwencoder --fast --audio-codec aac  # Force AAC
  ./gwencoder --fast --audio-codec opus # Force Opus
  

Subtitle Issues

Subtitle Extraction Fails

Issue: Subtitles not extracted

Solutions:

1. Check if subtitles exist in input:

   ffprobe -v error -select_streams s -show_entries stream=codec_name input.mp4
   

2. Ensure extraction flag is set:

   ./gwencoder --fast --extract-subs
   

3. Check file permissions in output directory

Subtitle Conversion Issues

Issue: Subtitles not converted to SRT

Solutions:

1. Only text-based subtitles can be converted (ASS, SSA, WebVTT)
2. Image subtitles (PGS, VobSub) are copied, not converted
3. Enable conversion explicitly:

   ./gwencoder --fast --convert-subs-srt
   

Performance Issues

High CPU Usage

Issue: Encoding uses 100% CPU

Explanation:

• This is normal for software encoding
• AV1 encoding is CPU-intensive
• Use hardware acceleration if available (--nvhevc)

Large Output Files

Issue: Output file is larger than input

Solutions:

1. Use higher CRF (lower quality, smaller files):

   ./gwencoder --fast --av1-crf 35
   

2. Use maximum compression mode:

   ./gwencoder --tiny
   

3. Set bitrate cap:

   ./gwencoder --fast --av1-maxrate 5000
   

4. Use lower audio quality:

   ./gwencoder --fast --audio-quality small
   

Slow Encoding Speed

Issue: Encoding takes too long

Solutions:

1. Use faster preset:

   ./gwencoder --fast --av1-preset 12
   

2. Disable quality features:

   ./gwencoder --fast --av1-disable-tf --av1-disable-scd
   

3. Use hardware acceleration:

   ./gwencoder --fast --nvhevc
   

4. Use faster mode:

   ./gwencoder --fast  # Instead of --hq or --slow
   

Quality Issues

Poor Video Quality

Issue: Output quality is too low

Solutions:

1. Use lower CRF (higher quality):

   ./gwencoder --hq --av1-crf 22
   

2. Use slower preset (better quality):

   ./gwencoder --hq --av1-preset 4
   

3. Enable all quality features:

   ./gwencoder --hq  # Don't disable TF/SCD/AQ
   

4. Use high quality mode:

   ./gwencoder --hq  # Or --slow for best quality
   

Poor Audio Quality

Issue: Audio quality is too low

Solutions:

1. Use high quality preset:

   ./gwencoder --fast --audio-quality high
   

2. Set custom bitrate:

   ./gwencoder --fast --audio-bitrate-per-ch 128
   

3. Preserve original channels:

   ./gwencoder --fast --audio-preserve
   

File Format Issues

Unsupported Input Format

Error: File cannot be read

Solution:

• GWEncoder supports: WMV, AVI, MP4, MKV, MPG, TS, WEBM
• Convert unsupported formats first using FFmpeg
• Check file with: ffprobe input.file

Output Format Issues

Issue: Output file doesn't play

Solutions:

1. Try different container:

   ./gwencoder --web  # Uses WEBM
   ./gwencoder --fast # Uses MKV
   

2. Use MP4 for compatibility:

   ./gwencoder --tiny  # Uses MP4
   

3. Check codec compatibility:

   • Use H.264 for maximum compatibility: --x264
   • Use AV1 for modern players (default)

Getting Help

Check System Information

./gwencoder --info

View Help

./gwencoder --help

Check Encoding Statistics

./gwencoder --stats

Enable Verbose Logging

Check log files:

• gwencoder_log.txt - Encoding log
• gwencoder_errors.txt - Error log
• gwencoder_stats.json - Statistics

Debug FFmpeg Command

GWEncoder prints the encoding command. Check the output for the FFmpeg command being used.

Common Error Messages

Error	Cause	Solution
FFmpeg not available	FFmpeg not installed	Install FFmpeg
Source Height must be even	Odd video height	Automatically handled
Stream map matches no streams	Missing streams	Automatically handled
ccextractor not available	ccextractor missing	Install or skip CC extraction
Failed to encode	Encoding error	Check FFmpeg stderr output

Still Having Issues?

1. Check FFmpeg version: ffmpeg -version
2. Check input file: ffprobe input.mp4
3. Review error logs: cat gwencoder_errors.txt
4. Try with minimal options: ./gwencoder --fast input.mp4
5. Check system resources (CPU, memory, disk space)