first commit

README_cropdetect.md

@@ -0,0 +1,76 @@
+# Advanced Crop Detection Script
+
+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 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
+
+- **Python 3**
+- **FFmpeg**: Both `ffmpeg` and `ffprobe` must be installed and in your system's `PATH`.
+
+## Installation
+
+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:
+
+```bash
+python cropdetect.py "path/to/your/video.mkv"
+```
+
+### Options
+
+- `-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:
+
+```
+Recommended crop filter: -vf crop=3840:2080:0:40
+```
+
+### Mixed Aspect Ratio Warning
+
+For a movie with changing aspect ratios:
+
+```
+WARNING: Potentially Mixed Aspect Ratios Detected!
+Recommendation: Manually check the video before applying a single crop.
+```
+
+### No Crop Needed
+
+For a video that is already perfectly formatted:
+
+```
+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.