# 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)