quickframe 0.1.0

Lightning-fast video frame extraction tool - Part of QuickKit

quickframe

Lightning-fast video frame extraction tool - Part of QuickKit

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

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)

pip install quickframe

From source

git clone https://github.com/quickkit/quickframe.git
cd quickframe
pip install -e .

Using Poetry (development)

poetry install
poetry shell

Usage

Quick Start (Command-line)

# 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

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

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

# 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

poetry run python quickframe.py video.mp4

Run installed command

poetry run quickframe video.mp4
# or after 'poetry shell':
quickframe video.mp4

Build and publish

# 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 | 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

Visit the QuickKit organization for more tools.

Documentation

• Homepage: https://quickkit.github.io/quickframe
• Repository: 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 file for details

Author

LoboGuardian 🐺

• Email: [e-mail]
• GitHub: @loboguardian