Metadata-Version: 2.4
Name: vexy-vid
Version: 1.0.1
Summary: High-performance video cropping and trimming CLI tool with automatic detection
Project-URL: Homepage, https://github.com/vexyart/vexy-vid
Project-URL: Repository, https://github.com/vexyart/vexy-vid
Project-URL: Issues, https://github.com/vexyart/vexy-vid/issues
Author-email: "Fontlab Ltd." <support@fontlab.com>
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: cli,crop,ffmpeg,trim,video
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: Apache Software 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
Requires-Python: >=3.10
Requires-Dist: av>=12.0.0
Requires-Dist: ffmpeg-python>=0.2.0
Requires-Dist: fire
Requires-Dist: loguru>=0.7.0
Requires-Dist: numba>=0.59.0
Requires-Dist: numpy>=1.26.0
Requires-Dist: opencv-python>=4.9.0
Requires-Dist: psutil>=5.9.0
Requires-Dist: rich>=13.0.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: ruff>=0.6.0; extra == 'dev'
Description-Content-Type: text/markdown

# vexy-vid

High-performance video cropping and trimming CLI tool with automatic detection.

## Features

- **Crop** — crop video to specific dimensions with alignment control
- **Trim** — remove edges from video (like reversed CSS padding)
- **Scale** — resize video after cropping/trimming
- Automatic letterbox (black bar) detection and removal
- Automatic subtitle region detection and removal
- Hardware-accelerated encoding with automatic fallback
- PyAV-based frame extraction (50-100% faster than OpenCV)
- Numba-optimized pixel analysis (10-50x speedup)
- Parallel frame processing with buffer pooling

## Requirements

- Python 3.10+
- **ffmpeg** binary installed on your system (`brew install ffmpeg` / `apt install ffmpeg`)

> **Note:** ffmpeg is a system dependency and cannot be installed via pip. All other dependencies are installed automatically.

## Installation

```bash
# Install with uv (recommended)
uv pip install vexy-vid

# Or with pip
pip install vexy-vid

# Development install
uv pip install -e ".[dev]"
```

## Usage

### Crop — crop to specific dimensions

```bash
# Crop to exact pixels
vexy-vid crop --crop 1280x720 --input video.mp4

# Crop to aspect ratio
vexy-vid crop --crop 16:9 --Halign 0 --Valign 100 --input video.mp4

# Crop to percentage
vexy-vid crop --crop 50%x50% --input video.mp4

# Crop and scale
vexy-vid crop --crop 16:9 --scale 1920x1080 --input video.mp4
```

### Trim — remove edges

```bash
# Remove pixels from edges
vexy-vid trim --top 100 --bottom 50 --input video.mp4

# Remove percentage from sides
vexy-vid trim --left 10% --right 10% --input video.mp4

# Auto-detect and remove letterbox bars
vexy-vid trim --Letterbox --input video.mp4

# Auto-detect and remove subtitle region
vexy-vid trim --subtitles --bottom 20 --input video.mp4

# Trim and scale
vexy-vid trim --Letterbox --scale 1920x1080 --input video.mp4
```

### Common flags

| Flag | Description |
|------|-------------|
| `--input` / `-i` | Input video path (or pipe via stdin) |
| `--output` / `-o` | Output video path (auto-generated if omitted) |
| `--quality` / `-q` | Encoding quality: 0 (fast), 1 (balanced), 2 (quality) |
| `--verbose` / `-v` | Enable verbose logging |

### Size spec formats (for `--crop` and `--scale`)

| Format | Example | Description |
|--------|---------|-------------|
| `WxH` | `1280x720` | Exact pixel dimensions |
| `W:H` | `16:9` | Aspect ratio |
| `P%xP%` | `50%x50%` | Percentage of original |
| `Wx` | `1280x` | Width only (height = 100%) |
| `xH` | `x720` | Height only (width = 100%) |
| Mixed | `1280x50%` | Pixels and percentage |

## Performance

Optimizations over the original implementation:

- **PyAV multi-threaded decoding** — 50-100% faster frame extraction
- **Hardware encoder detection** — 300-500% encoding speedup (NVENC, QSV, AMF)
- **Producer-consumer pipeline** — 200-400% parallel processing improvement
- **Buffer pool memory management** — 25-50% reduced allocation overhead
- **Numba SIMD pixel operations** — 10-50x analysis speedup
- **Intelligent caching** — instant reprocessing of identical videos

## License

[Apache License 2.0](LICENSE)
