84 lines
3.2 KiB
Markdown
84 lines
3.2 KiB
Markdown
# 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)
|