A Modern Python Library for Professional Video Processing

Python 3.11+ Built with uv Code style: ruff Type Checked Tests Version

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

🤖 AI Analysis • 🎥 AV1/HEVC/HDR • 📡 Adaptive Streaming • 🌐 360° Video Processing • ✅ Production Ready

📚 Full Documentation • 🚀 Features • ⚡ Quick Start • 💻 Examples • 🔄 Migration

📚 Documentation

Complete Documentation Suite Available in docs/

Quick Links

✨ Features

📦 Installation

Quick Install

# Basic installation (standard video processing)
uv add video-processor
# With 360° video support
uv add "video-processor[video-360]"
# With spatial audio processing 
uv add "video-processor[spatial-audio]"
# Complete 360° feature set
uv add "video-processor[video-360-full]"
# Or using pip
pip install video-processor
pip install "video-processor[video-360-full]"

Optional Features

🌐 360° Video Processing

📦 Dependency Details

# Core 360° processing
uv add "video-processor[video-360]"
# Includes: py360convert, opencv-python, numpy, scipy
# Spatial audio support 
uv add "video-processor[spatial-audio]"
# Includes: librosa, soundfile
# Complete 360° experience
uv add "video-processor[video-360-full]"
# Includes: All 360° dependencies + exifread

⚡ Procrastinate Migration (2.x → 3.x)

🔄 Automatic Version Detection

from video_processor.tasks.compat import get_version_info, IS_PROCRASTINATE_3_PLUS
version_info = get_version_info()
print(f"Using Procrastinate {version_info['procrastinate_version']}")
print(f"Features available: {list(version_info['features'].keys())}")
# Version-aware setup
if IS_PROCRASTINATE_3_PLUS:
 # Use 3.x features like improved performance, graceful shutdown
 pass

📋 Migration Steps

🆕 Procrastinate 3.x Benefits

Development Setup

git clone <repository>
cd video_processor
# Install with all development dependencies
uv sync --dev
# Install with dev + 360° features
uv sync --dev --extra video-360-full
# 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

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
)

🧪 Testing

🎯 NEW in v0.3.0: Comprehensive Test Infrastructure

⚡ Quick Testing

# Run all tests
make test
# Unit tests only (fast)
uv run pytest tests/unit/
# Integration tests with Docker
make test-docker
# Test specific categories
uv run pytest -m "smoke" # Quick smoke tests
uv run pytest -m "edge_cases" # Edge case scenarios 
uv run pytest -m "codecs" # Codec compatibility

🎬 Test Video Fixtures

📊 Test Results

✅ 52 passing tests (0 failures!)
✅ 108+ test video fixtures 
✅ Complete Docker integration
✅ Perfect API compatibility

🐳 Docker Integration Testing

# Complete integration testing environment
make test-docker
# Test specific services 
make test-db-migration # Database migration testing
make test-worker # Procrastinate worker testing
make clean-docker # Clean up test environment

🔧 Advanced Testing

# Generate/update test video fixtures
uv run python tests/fixtures/test_suite_manager.py --setup
# Validate test suite integrity
uv run python tests/fixtures/test_suite_manager.py --validate
# Generate synthetic videos for edge cases
uv run python tests/fixtures/generate_synthetic_videos.py
# Download open source test videos
uv run python tests/fixtures/download_test_videos.py

🎨 Test Categories

💡 Examples

📝 Available Examples

🐳 Docker Quick Start

# Start all services (PostgreSQL, Redis, app, workers)
docker-compose up -d
# View logs from the demo application
docker-compose logs -f app
# Access web demo at http://localhost:8080
docker-compose up demo
# Run tests in Docker
docker-compose run test
# Clean up
docker-compose down -v

🎬 Real-World Usage Patterns

📚 API Reference

🎬 VideoProcessor

🔧 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

📋 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

@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

========================== test session starts ==========================
tests/test_config.py ✅✅✅✅✅ [15%] 
tests/test_utils.py ✅✅✅✅✅✅✅✅ [30%]
tests/test_procrastinate_compat.py ✅✅✅✅✅✅✅✅✅✅✅✅✅✅✅✅✅ [85%]
tests/test_procrastinate_migration.py ✅✅✅✅✅✅✅✅✅✅✅✅✅ [100%]
======================== 43 passed in 0.52s ========================

📦 Dependencies

🎯 Core Dependencies

🔧 Development Tools

🌟 Why Video Processor?

📋 Requirements

🖥️ System Requirements

🐧 Installation Commands

# Ubuntu/Debian
sudo apt install ffmpeg postgresql-client
# macOS
brew install ffmpeg postgresql
# Arch Linux
sudo pacman -S ffmpeg postgresql

🤝 Contributing

🚀 Quick Contribution Guide

🎯 Areas We'd Love Help With

📜 License

🎉 Changelog

🚀 v0.2.0 - Procrastinate 3.x Migration & Docker Support

🌟 v0.1.0 - Initial Release

🔄 Migration to v0.4.0

Upgrading from Previous Versions

# Your existing code continues to work unchanged
processor = VideoProcessor(config)
result = await processor.process_video("video.mp4", "./output/")
# But now you get additional features automatically:
if result.is_360_video:
 print(f"360° projection: {result.video_360.projection_type}")
if result.quality_analysis:
 print(f"Quality score: {result.quality_analysis.overall_quality:.1f}/10")

New Features Available

Migration Resources

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