conversion_project/BLACK_FRAME_DETECTION.md

Black Frame Detection Feature

Overview

This feature automatically detects when video encoding produces an output where >95% of all frames are black (indicating total encoding failure) and skips that encode from the queue instead of creating a corrupted file.

How It Works

During Encoding

• Real-time FFmpeg progress monitoring occurs
• (No frame-by-frame analysis during encoding)

After Encoding (Quality Check)

• The BlackFrameAnalyzer analyzes the first 5 minutes of the encoded output
• Uses FFmpeg's blackdetect filter to identify all black frame segments
• Calculates: What percentage of the 5-minute duration is black frames?
• Flagging threshold: >95% black = encoding failure, output is deleted
• Pass threshold: ≤95% black = acceptable (includes legitimate black scenes, credits, transitions)

Queue Behavior

When >95% black frames detected:

• In normal/smart mode: The file is skipped, and processing continues to the next file in queue
• In forced mode (--cq or --bitrate): After max consecutive failures, processing stops
• The corrupted output file is automatically deleted
• A detailed warning is logged to the failure log

Examples

✅ File PASSES (Not Deleted)

• Video with 5-second fade-to-black: ~3% black → PASSES
• Video with black opening credits (20 seconds): ~6% black → PASSES
• Video with multiple scene transitions to black: ~8% black → PASSES

❌ File FAILS (Deleted as Corrupted)

• Video where entire encode is black: 100% black → FAILS
• Video where 98% of frames are black: 98% black → FAILS
• Video with only brief snippets of content: 96% black → FAILS

Implementation Details

Files Modified

core/black_frame_detector.py

• BlackFrameAnalyzer.analyze_output_for_black():
  • Analyzes first 5 minutes of output
  • Accumulates total black frame duration
  • Calculates percentage: (total_black_duration / 300_seconds) * 100
  • Flags if >95% black

core/encode_engine.py

• Calls BlackFrameAnalyzer after encoding completes
• Logs percentage of black frames
• Deletes output if >95% black and raises exception

core/process_manager.py

• Catches BlackFrameDetectionException
• Skips to next file in queue or stops if max consecutive failures

Configuration

Current parameters:

• Sample duration: First 5 minutes (300 seconds) of output analyzed
• Pixel threshold: 95% of pixels must be black to count as a black frame
• Time threshold: Minimum 0.01 seconds to count as black segment
• Corruption threshold: >95% of total duration must be black to flag

Logging

Check logs/conversion.log and logs/failure.log:

# File PASSES - has some black scenes but mostly content
[INFO] Black frame analysis: 8.5% of first 300s is black

# File FAILS - entire encode is black
[WARNING] Output file is 98.3% black frames - ENCODING FAILURE

Why This Approach?

This method detects actual encoding failures (entire video is black) while ignoring:

• ✅ Fade-to-black transitions
• ✅ Black credit sequences
• ✅ Dark scenes
• ✅ Black letterboxing or pillarboxing
• ❌ Only catches: Entire video is black (encoding error)