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