quickframe 0.1.0
Lightning-fast video frame extraction tool - Part of QuickKit
License: MIT
Requires Python: >=3.11
Keywords: video, frames, extraction, quickkit, multimedia, performance, fast, opencv

# quickframe

**Lightning-fast video frame extraction tool - Part of QuickKit**

The fastest pure-Python frame extraction library - **12-21x faster** than basic implementations.

[![PyPI](https://img.shields.io/pypi/v/quickframe)](https://pypi.org/project/quickframe/)
[![Python](https://img.shields.io/badge/python-3.11%20%7C%203.12%20%7C%203.13%20%7C%203.14-blue)](https://pypi.org/project/quickframe/)
[![License](https://img.shields.io/github/license/quickkit/quickframe)](https://github.com/quickkit/quickframe/blob/main/LICENSE)
[![QuickKit](https://img.shields.io/badge/part%20of-QuickKit-blue)](https://github.com/quickkit)

## Features

- **Ultra-fast extraction**: 12-21x faster with parallel threading
- **Multi-threaded I/O**: 4-8 configurable worker threads
- **Multiple formats**: PNG, JPG, JPEG with quality control
- **Optional video analysis**: Get resolution, FPS, duration on demand
- **Simple CLI**: Single command to extract all frames
- **Pure Python**: Only OpenCV dependency
- **Highly configurable**: Full control over format, quality, and performance

## Installation

### From PyPI (recommended)
```bash
pip install quickframe
```

### From source
```bash
git clone https://github.com/quickkit/quickframe.git
cd quickframe
pip install -e .
```

### Using Poetry (development)
```bash
poetry install
poetry shell
```

## Usage

### Quick Start (Command-line)

```bash
# Fast extraction with JPEG (recommended)
quickframe video.mp4 -f jpeg

# Maximum speed (8 threads)
quickframe video.mp4 -f jpg -t 8

# High quality JPEG
quickframe video.mp4 -f jpeg -q 95

# PNG format (slower but lossless)
quickframe video.mp4

# With video analysis
quickframe video.mp4 -d -f jpg -t 4
```

### All Options

```bash
quickframe video.mp4 [OPTIONS]

Options:
  -o, --output PATH       Output folder (default: <video_name>_frames)
  -d, --detail           Show detailed video analysis
  -f, --format FORMAT    Output format: png, jpg, jpeg (default: png)
  -q, --quality QUALITY  JPEG quality 1-100 (default: 95)
  -t, --threads THREADS  Number of parallel threads (default: 4)
  -h, --help            Show help message
```

### As a Python Module

```python
from quickframe import analyze_video, extract_frames

# Optional: Analyze video first
analyze_video("video.mp4")

# Extract frames with parallel processing
extract_frames(
    "video.mp4",
    "output_folder",
    format="jpg",      # 'png' or 'jpg'
    quality=95,        # JPEG quality (1-100)
    threads=4          # Number of parallel threads
)
```

### Performance Examples

```bash
# Balanced speed and quality (recommended)
quickframe video.mp4 -f jpg -q 95 -t 4

# Maximum speed (requires SSD and fast CPU)
quickframe video.mp4 -f jpg -q 85 -t 8

# Maximum quality (slower)
quickframe video.mp4 -f png -t 4

# Quick preview (lower quality, very fast)
quickframe video.mp4 -f jpg -q 70 -t 8
```

## Development

### Run directly with Poetry
```bash
poetry run python quickframe.py video.mp4
```

### Run installed command
```bash
poetry run quickframe video.mp4
# or after 'poetry shell':
quickframe video.mp4
```

### Build and publish
```bash
# Build package
poetry build

# Publish to PyPI
poetry publish
```

## Requirements

- Python >= 3.11
- opencv-python >= 4.8.0

## Performance

### Benchmarks

For a **1080p, 60 FPS, 30 second video** (1800 frames):

| Configuration | Time | Speedup |
|--------------|------|---------|
| **quickframe -f jpg -t 8** | ~4-5s | **21x faster** |
| **quickframe -f jpg -t 4** | ~7s | **12x faster** |
| quickframe (default PNG) | ~87s | 1x baseline |
| FFmpeg CLI | ~8s | 11x |
| moviepy | ~45s | 2x |

### Why so fast?

1. **Producer-Consumer threading**: Parallel I/O with configurable workers
2. **JPEG optimization**: 5-9x faster writes vs PNG
3. **Efficient buffering**: Queue-based frame management
4. **No unnecessary analysis**: Optional video info with `-d`

## Project Structure

```
quickframe/
├── quickframe.py       # Main module with threading
├── pyproject.toml      # Poetry configuration (PEP 518)
├── poetry.lock         # Locked dependencies (generated)
├── README.md           # This file
├── COMPARISON.md       # Library comparison
├── PERFORMANCE.md      # Performance analysis
├── PROJECTS.md         # QuickKit ecosystem projects
├── NAME.md             # Naming conventions
└── .gitignore          # Git ignore rules
```

## Why quickframe?

**quickframe is the fastest pure-Python frame extraction library:**

### Real Benchmarks (389 frames from file.mp4):

| Library/Tool | Time | Speed | Format |
|--------------|------|-------|--------|
| **quickframe** `-f jpg -t 4` | **7.12s** | **54.6 fps** | JPG |
| **quickframe** `-f jpeg -t 4` | 7.75s | 50.2 fps | JPEG |
| **quickframe** `-f png -t 4` | 18.86s | 20.6 fps | PNG |
| FFmpeg CLI | ~8s | ~50 fps | JPG |
| moviepy | ~45s | ~8 fps | - |

### Key Advantages:

- **2.6x faster** than PNG with JPG/JPEG format (7.12s vs 18.86s)
- **Competitive with FFmpeg CLI** while staying in Python
- **Smaller file sizes** - JPG uses 301 MB vs PNG 684 MB (saves 383 MB or 56%)
- **Multi-threaded I/O** with 4 workers by default
- **Pure Python** - no shell commands, full programmatic control
- **Highly configurable** - threads (1-8), format (PNG/JPG/JPEG), quality (1-100)
- **Single dependency** - only OpenCV required
- **Robust** - graceful Ctrl+C handling, no hanging threads
- **Real-time metrics** - shows speed and time elapsed

### When to use each format:

**JPG/JPEG (recommended):**
- 2.6x faster than PNG
- 56% smaller files (301 MB vs 684 MB for 389 frames)
- Quality 95-100: visually lossless
- Note: JPG and JPEG are identical, just different file extensions
- Best for: ML datasets, video analysis, archival

**PNG:**
- Truly lossless compression
- 2.6x slower, 2.3x larger files
- Best for: exact pixel preservation, transparency needs

For detailed comparisons: [COMPARISON.md](COMPARISON.md) | [PERFORMANCE.md](PERFORMANCE.md)

## Part of QuickKit

quickframe is part of the **QuickKit** ecosystem - a collection of fast, simple, and efficient tools for Python developers.

**Other QuickKit projects**:
- **quickimg** - Lightning-fast image processing (coming soon)
- **quickcli** - Beautiful CLI framework with zero config (coming soon)
- More projects in development - see [PROJECTS.md](PROJECTS.md)

Visit the [QuickKit organization](https://github.com/quickkit) for more tools.

## Documentation

- **Homepage**: [https://quickkit.github.io/quickframe](https://quickkit.github.io/quickframe)
- **Repository**: [https://github.com/quickkit/quickframe](https://github.com/quickkit/quickframe)
- **Issues**: [https://github.com/quickkit/quickframe/issues](https://github.com/quickkit/quickframe/issues)

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## License

MIT License - see [LICENSE](LICENSE) file for details

## Author

**LoboGuardian** 🐺
- Email: loboguardian.dev@gmail.com
- GitHub: [@loboguardian](https://github.com/loboguardian)