# ๐ฌ Video Processor
**A Modern Python Library for Professional Video Processing**
[](https://www.python.org/downloads/)
[](https://github.com/astral-sh/uv)
[](https://github.com/astral-sh/ruff)
[](http://mypy-lang.org/)
[](https://pytest.org/)
*Extracted from the demostar Django application, now a standalone powerhouse for video encoding, thumbnail generation, and sprite creation.*
[Features](#-features) โข
[Installation](#-installation) โข
[Quick Start](#-quick-start) โข
[Examples](#-examples) โข
[API Reference](#-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
|
|
### ๐ **360ยฐ Video Support** *(Optional)*
- **Spherical video detection** and metadata extraction
- **Projection conversions** (equirectangular, cubemap, stereographic)
- **360ยฐ thumbnail generation** with multiple viewing angles
- **Spatial audio processing** for immersive experiences
|
---
## ๐ฆ Installation
### Quick Install
```bash
# 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
For immersive video processing capabilities:
- **`video-360`**: Core 360ยฐ video processing (py360convert, opencv, numpy, scipy)
- **`spatial-audio`**: Spatial audio processing (librosa, soundfile)
- **`metadata-360`**: Enhanced 360ยฐ metadata extraction (exifread)
- **`video-360-full`**: Complete 360ยฐ package (includes all above)
#### ๐ฆ Dependency Details
```bash
# 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)
This library supports both **Procrastinate 2.x** and **3.x** for smooth migration:
#### ๐ Automatic Version Detection
```python
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
1. **Install compatible version**:
```bash
uv add "procrastinate>=3.5.2,<4.0.0" # Or keep 2.x support: ">=2.15.1,<4.0.0"
```
2. **Apply database migrations**:
```bash
# Procrastinate 3.x (two-step process)
procrastinate schema --apply --mode=pre # Before deploying
# Deploy new code
procrastinate schema --apply --mode=post # After deploying
# Procrastinate 2.x (single step)
procrastinate schema --apply
```
3. **Use migration helper**:
```python
from video_processor.tasks.migration import migrate_database
# Automatic version-aware migration
success = await migrate_database("postgresql://localhost/mydb")
```
4. **Update worker configuration**:
```python
from video_processor.tasks import get_worker_kwargs
# Automatically normalizes options for your version
worker_options = get_worker_kwargs(
concurrency=4,
timeout=5, # Maps to fetch_job_polling_interval in 3.x
remove_error=True, # Maps to remove_failed in 3.x
)
```
#### ๐ Procrastinate 3.x Benefits
- **Better performance** with improved job fetching
- **Graceful shutdown** with `shutdown_graceful_timeout`
- **Enhanced error handling** and job cancellation
- **Schema compatibility** improvements (3.5.2+)
### Development Setup
```bash
git clone
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
```python
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
```python
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
```python
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/`](examples/) directory:
### ๐ Available Examples
| Example | Description | Features |
|---------|-------------|-----------|
| [`basic_usage.py`](examples/basic_usage.py) | ๐ฏ Simple synchronous processing | Configuration, encoding, thumbnails |
| [`async_processing.py`](examples/async_processing.py) | โก Background task processing | Procrastinate, job queuing, monitoring |
| [`custom_config.py`](examples/custom_config.py) | ๐ ๏ธ Advanced configuration scenarios | Quality presets, validation, custom paths |
| [`docker_demo.py`](examples/docker_demo.py) | ๐ณ Complete containerized demo | Docker, PostgreSQL, async workers |
| [`web_demo.py`](examples/web_demo.py) | ๐ Flask web interface | Browser-based processing, job submission |
### ๐ณ Docker Quick Start
Get up and running in seconds with our complete Docker environment:
```bash
# 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
```
**Services included:**
- ๐๏ธ **PostgreSQL** - Database with Procrastinate job queue
- ๐ฌ **App** - Main video processor demo
- โก **Worker** - Background job processor
- ๐งช **Test** - Automated testing environment
- ๐ **Demo** - Web interface for browser-based testing
### ๐ฌ Real-World Usage Patterns
๐ข Production Video Pipeline
```python
# 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
```python
# 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
```python
# 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
```python
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.
```python
@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
```bash
# ๐ฆ 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
- โ
**Procrastinate compatibility** (2.x/3.x versions)
- โ
**Database migrations** with version detection
- โ
**Worker configuration** and option mapping
- โ
**360ยฐ video processing** (when dependencies available)
```bash
========================== 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
| 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
```bash
# 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](LICENSE) file for details.
---
## ๐ Changelog
### ๐ v0.2.0 - Procrastinate 3.x Migration & Docker Support
- ๐ **Procrastinate 3.x compatibility** with backward support for 2.x
- ๐ฏ **Automatic version detection** and feature flagging
- ๐ **Database migration utilities** with pre/post migration support
- ๐ณ **Complete Docker environment** with multi-service orchestration
- ๐ **Web demo interface** with Flask-based UI
- โก **Worker compatibility layer** with unified CLI
- ๐งช **30+ comprehensive tests** covering all compatibility scenarios
- ๐ **uv caching optimization** following Docker best practices
### ๐ 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 integration
- โ๏ธ **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](https://github.com/your-repo/issues/new/choose)
**Have a feature request?** [Start a discussion](https://github.com/your-repo/discussions)
**Want to contribute?** Check out our [contribution guide](#-contributing)
---
**Built with โค๏ธ for the video processing community**
*Making professional video encoding accessible to everyone*