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

Python 3: The script is written for Python 3.
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

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.
```
# 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.
```
# 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.

5.0 KiB Raw Permalink Blame History