Metadata-Version: 2.4
Name: mediacrop
Version: 4.3.0
Summary: A CLI tool featuring a localhost web interface for visually determining FFmpeg crop coordinates of any media file.
Home-page: https://github.com/mallikmusaddiq1/mediacrop
Author: Mallik Mohammad Musaddiq
Author-email: mallikmusaddiq1@gmail.com
License: MIT
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Multimedia :: Video
Classifier: Topic :: Multimedia :: Graphics :: Editors
Classifier: Topic :: Utilities
Requires-Python: >=3.7
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: license
Dynamic: license-file
Dynamic: requires-python
Dynamic: summary

# ✂️ MediaCrop - The Visual FFmpeg Crop Tool

[![Python Version](https://img.shields.io/badge/python-3.7%2B-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![PyPI version](https://badge.fury.io/py/mediacrop.svg)](https://pypi.org/project/mediacrop/)
[![Downloads](https://static.pepy.tech/badge/mediacrop)](https://pepy.tech/project/mediacrop)
[![Last Commit](https://img.shields.io/github/last-commit/mallikmusaddiq1/mediacrop.svg)](https://github.com/mallikmusaddiq1/mediacrop/commits/main)
[![Stars](https://img.shields.io/github/stars/mallikmusaddiq1/mediacrop.svg)](https://github.com/mallikmusaddiq1/mediacrop/stargazers)
[![Instagram](https://img.shields.io/badge/Instagram-%40musaddiq.x7-E4405F?logo=instagram&logoColor=white)](https://instagram.com/musaddiq.x7)

---

## 🧩 Overview

**MediaCrop** is a modern, lightweight, web-based utility that eliminates the guesswork from cropping media using **FFmpeg**. It offers a clean, intuitive visual interface to obtain precise crop coordinates for any video, image, or audio file. Simply drag, resize, or type in coordinates to instantly generate your perfect FFmpeg crop string.

The tool launches a local web server and automatically opens a sleek, responsive browser interface, complete with **Light & Dark themes**, ensuring a fast, enjoyable, and efficient experience tailored to your preferences.

---

## 📖 The Story Behind MediaCrop

Working with **FFmpeg** provides immense power, but it is rarely intuitive—especially when identifying accurate **crop coordinates**. Traditionally, this process involved a tedious, repetitive cycle:

1. Opening the file in a media player.
2. Estimating coordinates visually by trial and error.
3. Running the FFmpeg command to test the crop.
4. Reviewing the result and iterating on the coordinates.

This endless loop consumed valuable time and energy. **MediaCrop** was created to break this cycle, offering a **visual, drag-and-drop, and type-in solution** that delivers command-line-ready FFmpeg filter strings instantly. No more trial and error. No more frustration. Just **precision made effortless**.

---

## ✨ Key Features

| Category          | Feature                          | Description                                                                 |
|-------------------|----------------------------------|-----------------------------------------------------------------------------|
| **Interface & UX** | 🌌 **Light & Dark Themes**       | Switch seamlessly between themes, with preferences automatically saved in your browser. |
|                   | 🖼️ **Resizable Live Preview**    | Real-time preview in a floating window that is movable, resizable via 8 handles, and supports pinch-to-zoom gestures. |
|                   | 📱 **Responsive Design**         | Automatically adapts to all screen sizes—desktop, tablet, and mobile devices. |
|                   | 🖐️ **Native Touch Experience**   | Advanced touch gestures for resizing, dragging, and zooming, with disabled browser context menus for an immersive, app-like feel. |
|                   | 🔔 **Custom Notifications**      | Clean, modern notifications appear on save actions, replacing intrusive browser alerts. |
| **Media Handling**| ⏯️ **Full Video Controls**       | Comprehensive controls including play/pause, seek bar, playback speed adjustment, time display, and volume/mute options. |
|                   | 🎵 **Broad Format Support**      | Previews a wide range of image, video, and audio formats, with graceful fallbacks for unsupported files. |
| **Precision Tools**| 📊 **Bi-directional Info Panel** | Displays and accepts coordinates; type exact 'Preview' (scaled) or 'Actual' (native) values for pixel-perfect precision. |
|                   | 📐 **Aspect Ratio Presets**      | Select standard ratios like *16:9, 4:3, 9:16, 1:1* or input a custom ratio. |
|                   | 🔒 **Keep Aspect Ratio Toggle**  | Dedicated checkbox to lock the crop box's aspect ratio during resizing. |
|                   | 🔎 **Media Zoom**                | Zoom in/out precisely using the mouse wheel or pinch gestures directly on the media. |
|                   | ⌨️ **Keyboard Controls**         | Nudge the crop box with Arrow Keys (10px steps) or fine-tune with Shift + Arrow Keys (1px steps). |
|                   | 🔧 **Quick Tools & Context Menu**| Instantly center, toggle grid, or reset via the sidebar or right-click context menu. |
| **System**        | ⚙️ **Zero Dependencies**         | Runs entirely on Python’s standard library—no additional installations required. |
|                   | 🔌 **Smart Port Detection**      | Automatically selects an available port if the default (8000) is occupied. |
|                   | 💻 **Advanced Cross-Platform**   | Fully compatible with Windows, macOS, and Linux, including explicit auto-open support for Termux and WSL environments. |
|                   | 🛡️ **Robust CLI**                | Powered by `argparse` for standardized, reliable command-line help (`-h`) and version (`--version`) flags. |

---

## 🖼️ Screenshots

A modern interface available in both light and dark themes, optimized for every device.

![MediaCrop Desktop Screenshot](Screenshots/Screenshot-1080x1968.png)
![MediaCrop Desktop Screenshot](Screenshots/Screenshot-1080x1968-2.png)

---

### 🧠 Supported Preview Formats

**MediaCrop** computes coordinates for **any file readable by FFmpeg**, with native in-browser previews for:

* **Images:** JPG, PNG, WEBP, AVIF, GIF, BMP, SVG, ICO, HEIC, TIFF, JXL
* **Videos:** MP4, WEBM, MOV, OGV
* **Audio:** MP3, WAV, FLAC, OGG, M4A, AAC, OPUS

---

## ⚙️ Installation

Requires **Python 3.7+**.

### Option 1: Install from PyPI (Recommended)

```bash
pip install mediacrop
```

### Option 2: Install from Source

```bash
# Clone the repository
git clone https://github.com/mallikmusaddiq1/mediacrop.git

# Navigate into the project directory
cd mediacrop

# Install the package locally
pip install .
```

---

## 🚀 Usage

Run the command below in your terminal:

```bash
mediacrop "/path/to/your/mediafile.mp4"
```

> **Note:** Always enclose file paths containing spaces in quotes.
> 
> * The tool automatically launches in your default browser at `http://127.0.0.1:8000`.
> * Adjust the crop box visually, apply aspect ratios, or type exact coordinates into the sidebar.
> * Click 💾 **Save Coordinates** to confirm.
>   * The FFmpeg crop string appears in your terminal.
>   * Press `Ctrl + C` in the terminal to stop the server.

### 🕹️ Command-Line Options

| Option            | Alias     | Description                                                                 |
|-------------------|-----------|-----------------------------------------------------------------------------|
| `media_file`      |           | Path to the video or image file. (Required)                                 |
| `--port <port>`   | `-p <port>` | Specify a custom server port (default: 8000).                               |
| `--host <host>`   |           | Specify a host address (default: 127.0.0.1).                                |
| `--verbose`       | `-v`      | Enable detailed logs for debugging.                                         |
| `--version`       |           | Show program's version number and exit.                                     |
| `--help`          | `-h`      | Show this help message and exit.                                            |

### 🎬 Using the Output with FFmpeg

MediaCrop produces a command-line-ready crop filter string, such as:

```
crop=1280:720:320:180
```

Apply it directly in your FFmpeg command:

```bash
ffmpeg -i input.mp4 -vf "crop=1280:720:320:180" output_cropped.mp4
```

---

## ⌨️ Controls & Shortcuts

| Action                  | Control                          |
|-------------------------|----------------------------------|
| Move Crop Box           | Click + Drag / Arrow Keys        |
| Fine Move (1px)         | Shift + Arrow Keys               |
| Resize Crop Box         | Drag Edges/Corners / Pinch (Touch) |
| Set Coordinates Manually| Type values into 'Preview' or 'Actual' sidebar inputs. |
| Zoom Media View         | Mouse Wheel / Pinch (Touch) on media |
| Resize Preview Window   | Drag 8 handles on preview / Pinch (Touch) on preview |
| Fullscreen Preview      | Long-Press on Live Preview Window |
| Toggle Grid             | G Key                            |
| Center Crop Box         | C Key                            |
| Save Coordinates        | Enter Key                        |
| Toggle Help Panel       | ? Key / Esc to Close             |
| Access Quick Tools      | Right-Click on Crop Box          |

---

## 🤝 Contributing

Contributions are warmly welcomed! Whether you fix bugs, add features, or improve documentation—your input helps make MediaCrop even better.

### How to Contribute

* Fork this repository.
* Create a new branch for your update:
  ```bash
  git checkout -b feature/your-feature-name
  ```
* Commit your changes with a clear, descriptive message.
* Open a Pull Request.

If you find this project valuable, please star ⭐ it on GitHub to support future development!

---

## 👨‍💻 Author

**Name:** Mallik Mohammad Musaddiq  
**Email:** [mallikmusaddiq1@gmail.com](mailto:mallikmusaddiq1@gmail.com)  
**GitHub:** [mallikmusaddiq1](https://github.com/mallikmusaddiq1)  
**Project Repo:** [mallikmusaddiq1/mediacrop](https://github.com/mallikmusaddiq1/mediacrop)  
**Instagram:** [@musaddiq.x7](https://instagram.com/musaddiq.x7)

---

## 📄 License

This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for full details.
