Metadata-Version: 2.3
Name: pyautoflip
Version: 0.1.0
Summary: Intelligent video reframing library that automatically crops videos to different aspect ratios while preserving important content using AI
License: MIT
Keywords: video,reframing,cropping,computer-vision,face-detection,object-detection,autoflip,aspect-ratio
Author: Ahmed Hisham
Author-email: a7med.hish@gmail.com
Requires-Python: >=3.10,<3.14
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Multimedia :: Video
Classifier: Topic :: Multimedia :: Video :: Conversion
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Scientific/Engineering :: Image Processing
Requires-Dist: insightface (>=0.7.3,<0.8.0)
Requires-Dist: mediapipe (>=0.10.21,<0.11.0)
Requires-Dist: numpy (>=1.24.0,<2.0.0)
Requires-Dist: onnxruntime (>=1.21.0,<2.0.0)
Requires-Dist: opencv-python (>=4.11.0.86,<5.0.0.0)
Requires-Dist: pillow (>=10.0.0,<11.0.0)
Requires-Dist: scenedetect (>=0.6.6,<0.7.0)
Requires-Dist: scikit-learn (>=1.6.1,<2.0.0)
Requires-Dist: tqdm (>=4.65.0,<5.0.0)
Project-URL: Documentation, https://github.com/AhmedHisham1/pyautoflip#readme
Project-URL: Homepage, https://github.com/AhmedHisham1/pyautoflip
Project-URL: Repository, https://github.com/AhmedHisham1/pyautoflip
Description-Content-Type: text/markdown

# PyAutoFlip

A Python library for saliency-aware video cropping that automatically reframes videos to different aspect ratios while preserving important content.

**Note**: This is a Python implementation inspired by [MediaPipe's AutoFlip](https://github.com/google-ai-edge/mediapipe/blob/master/docs/solutions/autoflip.md). The original MediaPipe AutoFlip solution is no longer actively supported, so this project provides a maintained alternative using similar techniques.

## What it does

PyAutoFlip analyzes videos to identify salient content (faces, objects, motion) and intelligently crops frames to fit target aspect ratios. This is useful for adapting content between different platforms (e.g., landscape videos for portrait social media formats).

## Installation

```bash
# From PyPI
pip install pyautoflip
```

## Quick Start

### Command Line

```bash
# Convert a landscape video to portrait (9:16) 
pyautoflip reframe -i input.mp4 -o output.mp4

# Convert to square format
pyautoflip reframe -i input.mp4 -o output.mp4 --aspect-ratio 1:1

# Enable debug visualizations
pyautoflip reframe -i input.mp4 -o output.mp4 --debug
```

### Python API

```python
from pyautoflip import reframe_video

# Basic usage
reframe_video(
    input_path="input.mp4",
    output_path="output.mp4", 
    target_aspect_ratio="9:16"
)

# With options
reframe_video(
    input_path="input.mp4",
    output_path="output.mp4",
    target_aspect_ratio="1:1",
    motion_threshold=0.3,        # Lower = more stable crops
    padding_method="blur",       # or "solid_color"
    debug_mode=True
)
```

## How it works

1. **Scene Detection**: Identifies scene boundaries in the video
2. **Content Analysis**: Detects faces (InsightFace) and objects (MediaPipe) 
3. **Saliency-aware Cropping**: Determines optimal crop regions based on detected content
4. **Temporal Smoothing**: Applies smooth camera motion or stable crops as appropriate

## Options

- `--aspect-ratio`: Target aspect ratio (e.g., "9:16", "1:1", "4:3")
- `--motion-threshold`: Camera motion sensitivity (0.0 = very stable, 1.0 = allow more motion)
- `--padding-method`: How to handle content that doesn't fit ("blur" or "solid_color")
- `--debug`: Enable debug mode with visualizations and detailed logging

## Requirements

- Python 3.10+
- FFmpeg (for video processing)

### System dependencies

**Ubuntu/Debian:**
```bash
sudo apt-get install ffmpeg libgl1-mesa-glx libglib2.0-0
```

**macOS:**
```bash
brew install ffmpeg
```

## Development

```bash
git clone https://github.com/AhmedHisham1/pyautoflip.git
cd pyautoflip
poetry install
```

## License

MIT License - see LICENSE file for details.

## Acknowledgments

- [MediaPipe AutoFlip](https://github.com/google-ai-edge/mediapipe/blob/master/docs/solutions/autoflip.md) for the original concept and methodology
- [InsightFace](https://github.com/deepinsight/insightface) for face detection
- [MediaPipe](https://github.com/google/mediapipe) for object detection
- [PySceneDetect](https://github.com/Breakthrough/PySceneDetect) for scene analysis

