🎬 Video Processor

A Modern Python Library for Professional Video Processing

Extracted from the demostar Django application, now a standalone powerhouse for video encoding, thumbnail generation, and sprite creation.

Features • Installation • Quick Start • Examples • API Reference

---

✨ Features

🎥 Video Encoding Multi-format support: MP4 (H.264), WebM (VP9), OGV (Theora) Two-pass encoding for optimal quality Professional presets: Low, Medium, High, Ultra Customizable bitrates and quality settings	🖼️ Thumbnails & Sprites Smart thumbnail extraction at any timestamp Seekbar sprite sheets with WebVTT files Configurable intervals and dimensions Mobile-optimized output options
⚡ Background Processing Procrastinate integration for async tasks PostgreSQL job queue management Scalable worker architecture Progress tracking and error handling	🛠️ Modern Development Type-safe with full type hints Pydantic V2 configuration validation uv for lightning-fast dependency management ruff for code quality and formatting

---

📦 Installation

Quick Install

# Using uv (recommended - fastest!)
uv add video-processor

# Or with pip
pip install video-processor

Development Setup

git clone <repository>
cd video_processor

# Install with all development dependencies
uv sync --dev

# Verify installation
uv run pytest

---

🚀 Quick Start

Basic Video Processing

from pathlib import Path
from video_processor import VideoProcessor, ProcessorConfig

# 📋 Configure your processor
config = ProcessorConfig(
    base_path=Path("/tmp/video_output"),
    output_formats=["mp4", "webm"],
    quality_preset="high"  # 🎯 Professional quality
)

# 🎬 Initialize and process
processor = VideoProcessor(config)
result = processor.process_video(
    input_path="input_video.mp4",
    output_dir="outputs"
)

# 📊 Results
print(f"🎥 Video ID: {result.video_id}")
print(f"📁 Formats: {list(result.encoded_files.keys())}")
print(f"🖼️ Thumbnail: {result.thumbnail_file}")
print(f"🎞️ Sprites: {result.sprite_files}")

Async Background Processing

import asyncio
from video_processor.tasks import setup_procrastinate

async def process_in_background():
    # 🗄️ Connect to PostgreSQL
    app = setup_procrastinate("postgresql://user:pass@localhost/db")
    
    # 📤 Submit job
    job = await app.tasks.process_video_async.defer_async(
        input_path="/path/to/video.mp4",
        output_dir="/path/to/output",
        config_dict={"quality_preset": "ultra"}
    )
    
    print(f"✅ Job queued: {job.id}")

asyncio.run(process_in_background())

---

⚙️ Configuration

Quality Presets Comparison

🎯 Preset	📺 Video Bitrate	🔊 Audio Bitrate	🎨 CRF	💡 Best For
Low	1,000k	128k	28	📱 Mobile, limited bandwidth
Medium	2,500k	192k	23	🌐 Standard web delivery
High	5,000k	256k	18	🎬 High-quality streaming
Ultra	10,000k	320k	15	🏛️ Archive, professional use

Advanced Configuration

from video_processor import ProcessorConfig
from pathlib import Path

config = ProcessorConfig(
    # 📂 Storage & Paths
    base_path=Path("/media/videos"),
    storage_backend="local",  # 🔮 S3 coming soon!
    
    # 🎥 Video Settings
    output_formats=["mp4", "webm", "ogv"],
    quality_preset="ultra",
    
    # 🖼️ Thumbnails & Sprites
    thumbnail_timestamp=30,    # 📍 30 seconds in
    sprite_interval=5.0,       # 🎞️ Every 5 seconds
    
    # 🛠️ System
    ffmpeg_path="/usr/local/bin/ffmpeg"  # 🔧 Custom FFmpeg
)

---

💡 Examples

Explore our comprehensive examples in the examples/ directory:

📝 Available Examples

Example	Description	Features
basic_usage.py	🎯 Simple synchronous processing	Configuration, encoding, thumbnails
async_processing.py	⚡ Background task processing	Procrastinate, job queuing, monitoring
custom_config.py	🛠️ Advanced configuration scenarios	Quality presets, validation, custom paths

🎬 Real-World Usage Patterns

🏢 Production Video Pipeline

# Multi-format encoding for video platform
config = ProcessorConfig(
    base_path=Path("/var/media/uploads"),
    output_formats=["mp4", "webm"],  # Cross-browser support
    quality_preset="high",
    sprite_interval=10.0  # Balanced performance
)

processor = VideoProcessor(config)
result = processor.process_video(user_upload, output_dir)

# Generate multiple qualities
for quality in ["medium", "high"]:
    config.quality_preset = quality
    processor = VideoProcessor(config)
    # Process to different quality folders...

📱 Mobile-Optimized Processing

# Lightweight encoding for mobile delivery
mobile_config = ProcessorConfig(
    base_path=Path("/tmp/mobile_videos"),
    output_formats=["mp4"],  # Mobile-friendly format
    quality_preset="low",    # Reduced bandwidth
    sprite_interval=15.0     # Fewer sprites
)

---

📚 API Reference

🎬 VideoProcessor

The main orchestrator for all video processing operations.

🔧 Methods

# Process video to all configured formats
result = processor.process_video(
    input_path: Path | str,
    output_dir: Path | str | None = None,
    video_id: str | None = None
) -> VideoProcessingResult

# Encode to specific format
output_path = processor.encode_video(
    input_path: Path,
    output_dir: Path,
    format_name: str,
    video_id: str
) -> Path

# Generate thumbnail at timestamp
thumbnail = processor.generate_thumbnail(
    video_path: Path,
    output_dir: Path,
    timestamp: int,
    video_id: str
) -> Path

# Create sprite sheet and WebVTT
sprites = processor.generate_sprites(
    video_path: Path,
    output_dir: Path,
    video_id: str
) -> tuple[Path, Path]

⚙️ ProcessorConfig

Type-safe configuration with automatic validation.

📋 Essential Fields

class ProcessorConfig:
    base_path: Path                    # 📂 Base directory
    output_formats: list[str]          # 🎥 Video formats
    quality_preset: str                # 🎯 Quality level
    storage_backend: str               # 💾 Storage type
    ffmpeg_path: str                   # 🛠️ FFmpeg binary
    thumbnail_timestamp: int           # 🖼️ Thumbnail position
    sprite_interval: float             # 🎞️ Sprite frequency

📊 VideoProcessingResult

Comprehensive result object with all output information.

@dataclass
class VideoProcessingResult:
    video_id: str                      # 🆔 Unique identifier
    encoded_files: dict[str, Path]     # 📁 Format → file mapping
    thumbnail_file: Path | None        # 🖼️ Thumbnail image
    sprite_files: tuple[Path, Path] | None  # 🎞️ Sprite + WebVTT
    metadata: VideoMetadata            # 📊 Video properties

---

🧪 Development

🛠️ Development Commands

# 📦 Install dependencies
uv sync

# 🧪 Run test suite
uv run pytest -v

# 📊 Test coverage
uv run pytest --cov=video_processor

# ✨ Code formatting
uv run ruff format .

# 🔍 Linting
uv run ruff check .

# 🎯 Type checking
uv run mypy src/

📈 Test Coverage

Our comprehensive test suite covers:

• ✅ Configuration validation and type checking
• ✅ Path utilities and file operations
• ✅ FFmpeg integration and error handling
• ✅ Video metadata extraction
• ✅ Background task processing

========================== test session starts ==========================
tests/test_config.py ✅✅✅✅         [33%]
tests/test_utils.py ✅✅✅✅✅✅✅✅   [100%]

======================== 12 passed in 0.11s ========================

---

📦 Dependencies

🎯 Core Dependencies

Package	Purpose	Why We Use It
ffmpeg-python	FFmpeg integration	🎬 Professional video processing
msprites2	Sprite generation	🎞️ Seekbar thumbnails (forked for fixes)
procrastinate	Background tasks	⚡ Scalable async processing
pydantic	Configuration	⚙️ Type-safe settings validation
pillow	Image processing	🖼️ Thumbnail manipulation

🔧 Development Tools

Tool	Purpose	Benefits
uv	Package management	🚀 Ultra-fast dependency resolution
ruff	Linting & formatting	⚡ Lightning-fast code quality
pytest	Testing framework	🧪 Reliable test execution
mypy	Type checking	🎯 Static type analysis
coverage	Test coverage	📊 Quality assurance

---

🌟 Why Video Processor?

🆚 Comparison with Alternatives

Feature	Video Processor	FFmpeg CLI	moviepy	OpenCV
Two-pass encoding	✅	✅	❌	❌
Multiple formats	✅	✅	✅	❌
Background processing	✅	❌	❌	❌
Type safety	✅	❌	❌	❌
Sprite generation	✅	❌	❌	❌
Modern Python	✅	N/A	❌	❌

---

📋 Requirements

🖥️ System Requirements

• Python 3.11+ - Modern Python features
• FFmpeg - Video processing engine
• PostgreSQL - Background job processing (optional)

🐧 Installation Commands

# Ubuntu/Debian
sudo apt install ffmpeg postgresql-client

# macOS
brew install ffmpeg postgresql

# Arch Linux
sudo pacman -S ffmpeg postgresql

---

🤝 Contributing

We welcome contributions! Here's how to get started:

🚀 Quick Contribution Guide

1. 🍴 Fork the repository
2. 🌿 Create a feature branch (git checkout -b feature/amazing-feature)
3. 📝 Make your changes with tests
4. 🧪 Test everything (uv run pytest)
5. ✨ Format code (uv run ruff format .)
6. 📤 Submit a pull request

🎯 Areas We'd Love Help With

• 🌐 S3 storage backend implementation
• 🎞️ Additional video formats (AV1, HEVC)
• 📊 Progress tracking and monitoring
• 🐳 Docker integration examples
• 📖 Documentation improvements

---

📜 License

This project is licensed under the MIT License - see the LICENSE file for details.

---

🎉 Changelog

🌟 v0.1.0 - Initial Release

• ✨ Multi-format encoding: MP4, WebM, OGV support
• 🖼️ Thumbnail generation with customizable timestamps
• 🎞️ Sprite sheet creation with WebVTT files
• ⚡ Background processing with Procrastinate
• ⚙️ Type-safe configuration with Pydantic V2
• 🛠️ Modern tooling: uv, ruff, pytest integration
• 📚 Comprehensive documentation and examples

---

🙋‍♀️ Questions? Issues? Ideas?

Found a bug? Open an issue
Have a feature request? Start a discussion
Want to contribute? Check out our contribution guide

---

Built with ❤️ for the video processing community

Making professional video encoding accessible to everyone