# ๐ฌ 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
|
---
## ๐ฆ Installation
### Quick Install
```bash
# Using uv (recommended - fastest!)
uv add video-processor
# Or with pip
pip install video-processor
```
### Development Setup
```bash
git clone
cd video_processor
# Install with all development dependencies
uv sync --dev
# 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 |
### ๐ฌ 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
```bash
========================== 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
```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.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](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*