Crop Video GUI

A powerful cross-platform video cropping tool with batch processing

---

Overview

Crop Video GUI is a professional desktop application for batch video cropping with an interactive visual interface. Select crop boundaries once for each video, then let the app automatically process your entire batch with GPU acceleration support.

Key Features

• Two-Phase Workflow - Select crop boundaries for all videos first, then batch encode without interruption
• Visual Crop Selection - Interactive preview with rulers, crosshairs, and real-time boundary markers
• Batch Processing - Process multiple videos in one session with consistent settings
• GPU Acceleration - Automatic detection and use of NVIDIA NVENC, AMD AMF, or Intel Quick Sync
• Target Resolution - Optional zoom-to-fit scaling to any target resolution
• Multiple Formats - Supports MP4, MKV, WebM, AVI, MOV, FLV, and WMV
• Session Memory - Remembers your last input/output directories
• Progress Tracking - Real-time ffmpeg progress with time estimates
• Resume Capability - Skip problematic videos and resume from where you left off
• Crop Blueprints - Save crop measurements for later use

Platform Support

• Windows - Pre-built executables available for download
• macOS/Linux - Run from source (Python 3.10+ required)

Download

Get the latest release:

• Windows (EXE) - Download CropVideoGUI-windows.zip

Installation

Windows:

1. Download CropVideoGUI-windows.zip
2. Extract the ZIP file
3. Run CropVideoGUI.exe

macOS: macOS users can run the application directly from source:

git clone https://github.com/cosmicpush/crop-video-gui.git
cd crop-video-gui
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
python3 crop_gui.py

Requirements:

• ffmpeg and ffprobe must be installed on your system
  • Windows: Download from ffmpeg.org
  • macOS: brew install ffmpeg (for running from source)

How to Use

Step 1: Select Directories

1. Choose your Input Directory containing video files
2. Choose an Output Directory for cropped videos
3. (Optional) Set a Target Resolution like 1920x1080

Step 2: Crop Selection Phase

1. Click Start Processing
2. For each video, a preview window will open:
   • Left-click → Set top boundary
   • Right-click → Set bottom boundary
   • A key → Set left boundary
   • D key → Set right boundary
   • Enter → Confirm and move to next video
   • Esc → Cancel

Step 3: Batch Encoding

• After all crop boundaries are selected, the app automatically encodes all videos
• Monitor progress in the status log
• All videos will be processed with your selected crop areas

Controls

Action	Control
Set Top Boundary	Left Mouse Click
Set Bottom Boundary	Right Mouse Click
Set Left Boundary	A Key
Set Right Boundary	D Key
Confirm Selection	Enter
Cancel	Esc
Stop Processing	Stop Button

Development Setup

Prerequisites

• Python 3.10 or higher
• ffmpeg and ffprobe in system PATH

Installation

# Clone the repository
git clone https://github.com/cosmicpush/crop-video-gui.git
cd crop-video-gui

# Create virtual environment
python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install --upgrade pip
pip install -r requirements.txt

Run the Application

python crop_gui.py

Run Tests

python -m unittest tests.test_build_filter_string

Building from Source

Local Build

You can build the application locally on any platform:

# Clone the repository
git clone https://github.com/cosmicpush/crop-video-gui.git
cd crop-video-gui

# Install dependencies
pip install -r requirements.txt
pip install pyinstaller  # For creating executables

# Build the executable (optional)
pyinstaller --clean --noconfirm --name CropVideoGUI --onefile --windowed --icon=assets/logo.png crop_gui.py

Automated Releases

The project includes GitHub Actions for automated Windows builds:

1. Create a version tag:

   git tag v1.0.0
   git push origin v1.0.0

2. GitHub Actions automatically:

   • Converts assets/logo.png to Windows ICO format
   • Builds Windows EXE with embedded icon
   • Publishes release with the Windows binary

GPU Support

The app automatically detects and uses hardware encoders:

• NVIDIA - NVENC (h264_nvenc)
• AMD - AMF (h264_amf)
• Intel - Quick Sync (h264_qsv)

Enable GPU acceleration in the GUI for faster encoding. Falls back to CPU (libx264) if no GPU is detected.

Technical Details

Architecture

• GUI Framework - Tkinter (cross-platform)
• Video Processing - OpenCV (frame extraction)
• Encoding - ffmpeg (batch encoding)
• Language - Python 3.10+

Workflow

1. Boundary Collection Phase - Extract middle frame, user selects crop area, store coordinates
2. Encoding Phase - Apply stored crop coordinates using ffmpeg filters
3. Progress Monitoring - Parse ffmpeg output for real-time progress updates

ffmpeg Filter Chain

crop=W:H:X:Y → scale=TARGET_W:TARGET_H:force_original_aspect_ratio=increase → crop=TARGET_W:TARGET_H

Troubleshooting

Issue: App won't open on macOS Solution: Right-click the app and select "Open" to bypass Gatekeeper

Issue: No GPU detected Solution: Install GPU-enabled ffmpeg build for your platform

Issue: ffmpeg not found Solution: Ensure ffmpeg is installed and in your system PATH

Contributing

Contributions are welcome! Please:

• Fork the repository
• Create a feature branch
• Add tests for new functionality
• Submit a pull request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Credits

Developed with:

• Python
• OpenCV
• ffmpeg
• PyInstaller

---

Enjoy faster, cleaner video crops!