pat-e/encoding-scripts
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Integration of cropdetec-logic into anime_audio_encoder and tv_audio_encoder. Rewrite of readmes

Browse Source
This commit is contained in:
pat-e
2025-07-20 22:30:45 +02:00
parent ba4eac1775
commit e9352ed6a0
6 changed files with 555 additions and 164 deletions
Download Patch File Download Diff File Expand all files Collapse all files

114
README_cropdetect.md
View File

@@ -1,32 +1,30 @@
# 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.
This Python script (`cropdetect.py`) provides robust, parallelized, and intelligent crop detection for video files. It is much more than a simple wrapper for `ffmpeg-cropdetect`—it uses parallel processing, aspect ratio heuristics, luma verification, and bounding box logic to recommend safe crop values, 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.
- **Parallel Processing:** Analyzes video segments in parallel for speed and reliability.
- **Aspect Ratio Snapping:** Automatically snaps detected crops to known cinematic standards (16:9, 2.39:1, 1.85:1, 4:3, IMAX, etc.), correcting minor detection errors.
- **Mixed Aspect Ratio Handling:** Detects and safely handles videos with changing aspect ratios (e.g., IMAX scenes), recommending a bounding box crop that never cuts into image data.
- **Luma Verification:** Discards unreliable crop detections from very dark scenes using a second analysis pass.
- **Credits/Logo Filtering:** Ignores crops that only appear in the first/last 5% of the video, preventing opening logos or credits from affecting the result.
- **No Crop Recommendation:** If the video is overwhelmingly detected as not needing a crop, the script will confidently recommend leaving it as is.
- **User-Friendly Output:** Color-coded recommendations and warnings for easy review.
- **Safe for Automation:** The recommended crop is always the most outer cropable frame, so no image data is lost—even with variable crops.
## 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.
- **Python 3**
- **FFmpeg**: Both `ffmpeg` and `ffprobe` must be installed and in your system's `PATH`.
## Installation
No complex installation is required. Simply save the script as `cropdetect.py` and ensure it is executable.
Just save the script as `cropdetect.py` and make it executable if needed.
## Usage
Run the script from your terminal, passing the path to the video file as an argument.
### Basic Usage
Run the script from your terminal, passing the path to the video file as an argument:
```bash
python cropdetect.py "path/to/your/video.mkv"
@@ -34,91 +32,45 @@ 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
```
- `-n, --num_workers`: Number of parallel worker threads (default: half your CPU cores).
- `-sct, --significant_crop_threshold`: Percentage a crop must be present to be considered significant (default: 5.0).
- `-mc, --min_crop`: Minimum pixels to crop on any side for it to be considered a major crop (default: 10).
- `--debug`: Enable detailed debug logging.
## Example Output
### Confident Crop Recommendation
For a standard widescreen movie, the output will be clear and simple.
For a standard widescreen movie:
```
--- 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.
For a movie with changing aspect ratios:
```
--- 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.
WARNING: Potentially Mixed Aspect Ratios Detected!
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.
For a video that is already perfectly formatted:
```
--- 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.
```
```
## Integration with Other Scripts
This crop detection logic is now integrated into `anime_audio_encoder.py` and `tv_audio_encoder.py` via the `--autocrop` option. When enabled, those scripts will automatically detect and apply the safest crop to the UTVideo intermediate file, ensuring no image data is lost—even with variable crops.
## Notes
- The script is safe for automation and batch workflows.
- The recommended crop will never cut into the actual image, only remove black bars.
- For complex videos, a bounding box crop is calculated to contain all significant scenes.
- If no crop is needed, none will be applied.