124 lines
5.0 KiB
Markdown
124 lines
5.0 KiB
Markdown
# Advanced Crop Detection Script
|
|
|
|
This Python script provides a robust and intelligent way to detect the correct crop values for video files. It goes far beyond a simple `ffmpeg-cropdetect` wrapper by using parallel processing and a series of smart heuristics to provide accurate and reliable recommendations, even for complex videos with mixed aspect ratios.
|
|
|
|
## Key Features
|
|
|
|
- **Parallel Processing**: Analyzes video segments in parallel to significantly speed up the detection process on multi-core systems.
|
|
- **Smart Aspect Ratio Snapping**: Automatically "snaps" detected crop values to known cinematic standards (e.g., 1.85:1, 2.39:1, 16:9, 4:3), correcting for minor detection errors.
|
|
- **Mixed Aspect Ratio Detection**: Intelligently identifies videos that switch aspect ratios (e.g., IMAX scenes in a widescreen movie) and warns the user against applying a single, destructive crop.
|
|
- **Credits & Logo Filtering**: Automatically detects and ignores crop values that only appear in the first or last 5% of the video, preventing opening logos or closing credits from influencing the result.
|
|
- **Luma Verification**: Performs a second analysis pass on frames with unidentified aspect ratios. If a frame is too dark, the detection is discarded as unreliable, preventing false positives from dark scenes.
|
|
- **Sanity Checks**: Provides context-aware warnings, such as when it suggests cropping a 4:3 video into a widescreen format.
|
|
- **"No Crop" Logic**: If a video is overwhelmingly detected as not needing a crop (>95% of samples), it will confidently recommend leaving it as is, ignoring insignificant variations.
|
|
- **User-Friendly Output**: Uses color-coded text to make recommendations and warnings easy to read at a glance.
|
|
|
|
## Prerequisites
|
|
|
|
1. **Python 3**: The script is written for Python 3.
|
|
2. **FFmpeg**: Both `ffmpeg` and `ffprobe` must be installed and accessible in your system's `PATH`. The script will check for these on startup.
|
|
|
|
## Installation
|
|
|
|
No complex installation is required. Simply save the script as `cropdetect.py` and ensure it is executable.
|
|
|
|
## Usage
|
|
|
|
Run the script from your terminal, passing the path to the video file as an argument.
|
|
|
|
### Basic Usage
|
|
|
|
```bash
|
|
python cropdetect.py "path/to/your/video.mkv"
|
|
```
|
|
|
|
### Options
|
|
|
|
- `-j, --jobs`: Specify the number of parallel processes to use for analysis. By default, it uses half of your available CPU cores.
|
|
```bash
|
|
# Use 8 parallel jobs
|
|
python cropdetect.py "path/to/video.mkv" --jobs 8
|
|
```
|
|
- `-i, --interval`: Set the time interval (in seconds) between video samples. A smaller interval is more thorough but slower. The default is 30 seconds.
|
|
```bash
|
|
# Analyze the video every 15 seconds
|
|
python cropdetect.py "path/to/video.mkv" --interval 15
|
|
```
|
|
|
|
## Example Output
|
|
|
|
### Confident Crop Recommendation
|
|
|
|
For a standard widescreen movie, the output will be clear and simple.
|
|
|
|
```
|
|
--- Prerequisite Check ---
|
|
All required tools found.
|
|
|
|
Video properties: 3840x2160, 7588.66s. Analyzing with up to 16 parallel jobs...
|
|
|
|
--- Starting Analysis ---
|
|
Analyzing Segments: 252/252 completed...
|
|
|
|
--- Final Verdict ---
|
|
--- Credits/Logo Detection ---
|
|
Ignoring 55 crop value(s) that appear only in the first/last 5% of the video.
|
|
|
|
--- Luma Verification ---
|
|
Verifying scenes: 97/97 completed...
|
|
Ignoring 347 detections that occurred in very dark scenes.
|
|
|
|
Analysis complete.
|
|
The video consistently uses the 'Widescreen (Flat)' aspect ratio.
|
|
Recommended crop filter: -vf crop=3840:2080:0:40
|
|
```
|
|
|
|
### Mixed Aspect Ratio Warning
|
|
|
|
For a movie with changing aspect ratios, the script will advise against cropping.
|
|
|
|
```
|
|
--- Prerequisite Check ---
|
|
All required tools found.
|
|
|
|
Video properties: 1920x1080, 3640.90s. Analyzing with up to 16 parallel jobs...
|
|
|
|
--- Starting Analysis ---
|
|
Analyzing Segments: 121/121 completed...
|
|
|
|
--- Final Verdict ---
|
|
--- Credits/Logo Detection ---
|
|
Ignoring 15 crop value(s) that appear only in the first/last 5% of the video.
|
|
|
|
--- Luma Verification ---
|
|
Verifying scenes: 121/121 completed...
|
|
Ignoring 737 detections that occurred in very dark scenes.
|
|
|
|
--- WARNING: Potentially Mixed Aspect Ratios Detected! ---
|
|
The dominant aspect ratio is 'Widescreen (Scope)' (crop=1920:808:0:136), found in 96.2% of samples.
|
|
However, other significantly different aspect ratios were also detected, although less frequently.
|
|
|
|
Recommendation: Manually check the video before applying a single crop.
|
|
You can review the next most common detections below:
|
|
- 'Fullscreen (4:3)' (crop=1440:1080:240:0) was detected 69 time(s) (3.8%).
|
|
```
|
|
|
|
### No Crop Needed
|
|
|
|
For a video that is already perfectly formatted (e.g., a 4:3 TV show), the script will recommend doing nothing.
|
|
|
|
```
|
|
--- Prerequisite Check ---
|
|
All required tools found.
|
|
|
|
Video properties: 768x576, 1770.78s. Analyzing with up to 16 parallel jobs...
|
|
|
|
--- Starting Analysis ---
|
|
Analyzing Segments: 58/58 completed...
|
|
|
|
--- Final Verdict ---
|
|
Analysis complete.
|
|
The video is overwhelmingly 'Fullscreen (4:3)' and does not require cropping.
|
|
Minor aspect ratio variations were detected but are considered insignificant due to their low frequency.
|
|
Recommendation: No crop needed.
|
|
``` |