{"id":30856340,"url":"https://github.com/rsp2k/video-processor","last_synced_at":"2026-06-15T20:31:24.871Z","repository":{"id":313384503,"uuid":"1051140709","full_name":"rsp2k/video-processor","owner":"rsp2k","description":"🎬 Modern Python library for professional video processing with multi-format encoding, thumbnails, and background processing","archived":false,"fork":false,"pushed_at":"2025-09-22T07:19:08.000Z","size":443,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-09-22T09:25:26.241Z","etag":null,"topics":["background-tasks","encoding","ffmpeg","modern-python","procrastinate","python","sprites","thumbnails","uv","video-processing"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/rsp2k.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-05T14:01:42.000Z","updated_at":"2025-09-22T07:19:12.000Z","dependencies_parsed_at":"2025-09-05T18:51:49.267Z","dependency_job_id":null,"html_url":"https://github.com/rsp2k/video-processor","commit_stats":null,"previous_names":["rsp2k/video-processor"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/rsp2k/video-processor","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rsp2k%2Fvideo-processor","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rsp2k%2Fvideo-processor/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rsp2k%2Fvideo-processor/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rsp2k%2Fvideo-processor/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rsp2k","download_url":"https://codeload.github.com/rsp2k/video-processor/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rsp2k%2Fvideo-processor/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34379915,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-15T02:00:07.085Z","response_time":63,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["background-tasks","encoding","ffmpeg","modern-python","procrastinate","python","sprites","thumbnails","uv","video-processing"],"created_at":"2025-09-07T12:01:08.688Z","updated_at":"2026-06-15T20:31:24.859Z","avatar_url":"https://github.com/rsp2k.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n# 🎬 Video Processor\n\n**A Modern Python Library for Professional Video Processing**\n\n[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)\n[![Built with uv](https://img.shields.io/badge/built%20with-uv-green)](https://github.com/astral-sh/uv)\n[![Code style: ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)\n[![Type Checked](https://img.shields.io/badge/type%20checked-mypy-blue)](http://mypy-lang.org/)\n[![Tests](https://img.shields.io/badge/tests-52%20passed-brightgreen)](https://pytest.org/)\n[![Version](https://img.shields.io/badge/version-0.3.0-blue)](https://github.com/your-repo/releases)\n\n*Extracted from the demostar Django application, now a standalone powerhouse for video encoding, thumbnail generation, and sprite creation.*\n\n## 🚀 **LATEST: v0.4.0 - Complete Multimedia Platform!**\n🤖 **AI Analysis** • 🎥 **AV1/HEVC/HDR** • 📡 **Adaptive Streaming** • 🌐 **360° Video Processing** • ✅ **Production Ready**\n\n[📚 **Full Documentation**](docs/) •\n[🚀 Features](#-features) •\n[⚡ Quick Start](#-quick-start) •\n[💻 Examples](#-examples) •\n[🔄 Migration](#-migration-to-v040)\n\n\u003c/div\u003e\n\n---\n\n## 📚 Documentation\n\n### **Complete Documentation Suite Available in [`docs/`](docs/)**\n\n| Documentation | Description |\n|---------------|-------------|\n| **[📖 User Guide](docs/user-guide/)** | Complete getting started guides and feature overviews |\n| **[🔄 Migration](docs/migration/)** | Upgrade instructions and migration guides |\n| **[🛠️ Development](docs/development/)** | Technical implementation details and architecture |\n| **[📋 Reference](docs/reference/)** | API references, roadmaps, and feature lists |\n| **[💻 Examples](docs/examples/)** | 11 comprehensive examples covering all features |\n\n### **Quick Links**\n- **[🚀 NEW_FEATURES_v0.4.0.md](docs/user-guide/NEW_FEATURES_v0.4.0.md)** - Complete v0.4.0 feature overview\n- **[📘 README_v0.4.0.md](docs/user-guide/README_v0.4.0.md)** - Comprehensive getting started guide\n- **[🔄 MIGRATION_GUIDE_v0.4.0.md](docs/migration/MIGRATION_GUIDE_v0.4.0.md)** - Upgrade instructions\n- **[💻 Examples Documentation](docs/examples/README.md)** - Hands-on usage examples\n\n---\n\n## ✨ Features\n\n\u003ctable\u003e\n\u003ctr\u003e\n\u003ctd width=\"50%\"\u003e\n\n### 🎥 **Video Encoding**\n- **Multi-format support**: MP4 (H.264), WebM (VP9), OGV (Theora)\n- **Two-pass encoding** for optimal quality\n- **Professional presets**: Low, Medium, High, Ultra\n- **Customizable bitrates** and quality settings\n\n\u003c/td\u003e\n\u003ctd width=\"50%\"\u003e\n\n### 🖼️ **Thumbnails \u0026 Sprites**\n- **Smart thumbnail extraction** at any timestamp\n- **Seekbar sprite sheets** with WebVTT files\n- **Configurable intervals** and dimensions\n- **Mobile-optimized** output options\n\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd width=\"50%\"\u003e\n\n### ⚡ **Background Processing**\n- **Procrastinate integration** for async tasks\n- **PostgreSQL job queue** management\n- **Scalable worker architecture**\n- **Progress tracking** and error handling\n\n\u003c/td\u003e\n\u003ctd width=\"50%\"\u003e\n\n### 🛠️ **Modern Development**\n- **Type-safe** with full type hints\n- **Pydantic V2** configuration validation\n- **uv** for lightning-fast dependency management\n- **ruff** for code quality and formatting\n\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd colspan=\"2\"\u003e\n\n### 🌐 **360° Video Support** *(Optional)*\n- **Spherical video detection** and metadata extraction\n- **Projection conversions** (equirectangular, cubemap, stereographic)\n- **360° thumbnail generation** with multiple viewing angles\n- **Spatial audio processing** for immersive experiences\n\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003c/table\u003e\n\n---\n\n## 📦 Installation\n\n### Quick Install\n\n```bash\n# Basic installation (standard video processing)\nuv add video-processor\n\n# With 360° video support\nuv add \"video-processor[video-360]\"\n\n# With spatial audio processing  \nuv add \"video-processor[spatial-audio]\"\n\n# Complete 360° feature set\nuv add \"video-processor[video-360-full]\"\n\n# Or using pip\npip install video-processor\npip install \"video-processor[video-360-full]\"\n```\n\n### Optional Features\n\n#### 🌐 360° Video Processing\nFor immersive video processing capabilities:\n- **`video-360`**: Core 360° video processing (py360convert, opencv, numpy, scipy)\n- **`spatial-audio`**: Spatial audio processing (librosa, soundfile)  \n- **`metadata-360`**: Enhanced 360° metadata extraction (exifread)\n- **`video-360-full`**: Complete 360° package (includes all above)\n\n#### 📦 Dependency Details\n```bash\n# Core 360° processing\nuv add \"video-processor[video-360]\"\n# Includes: py360convert, opencv-python, numpy, scipy\n\n# Spatial audio support  \nuv add \"video-processor[spatial-audio]\"\n# Includes: librosa, soundfile\n\n# Complete 360° experience\nuv add \"video-processor[video-360-full]\"\n# Includes: All 360° dependencies + exifread\n```\n\n### ⚡ Procrastinate Migration (2.x → 3.x)\n\nThis library supports both **Procrastinate 2.x** and **3.x** for smooth migration:\n\n#### 🔄 Automatic Version Detection\n```python\nfrom video_processor.tasks.compat import get_version_info, IS_PROCRASTINATE_3_PLUS\n\nversion_info = get_version_info()\nprint(f\"Using Procrastinate {version_info['procrastinate_version']}\")\nprint(f\"Features available: {list(version_info['features'].keys())}\")\n\n# Version-aware setup\nif IS_PROCRASTINATE_3_PLUS:\n    # Use 3.x features like improved performance, graceful shutdown\n    pass\n```\n\n#### 📋 Migration Steps\n1. **Install compatible version**:\n   ```bash\n   uv add \"procrastinate\u003e=3.5.2,\u003c4.0.0\"  # Or keep 2.x support: \"\u003e=2.15.1,\u003c4.0.0\"\n   ```\n\n2. **Apply database migrations**:\n   ```bash\n   # Procrastinate 3.x (two-step process)\n   procrastinate schema --apply --mode=pre    # Before deploying\n   # Deploy new code\n   procrastinate schema --apply --mode=post   # After deploying\n   \n   # Procrastinate 2.x (single step)\n   procrastinate schema --apply\n   ```\n\n3. **Use migration helper**:\n   ```python\n   from video_processor.tasks.migration import migrate_database\n   \n   # Automatic version-aware migration\n   success = await migrate_database(\"postgresql://localhost/mydb\")\n   ```\n\n4. **Update worker configuration**:\n   ```python\n   from video_processor.tasks import get_worker_kwargs\n   \n   # Automatically normalizes options for your version\n   worker_options = get_worker_kwargs(\n       concurrency=4,\n       timeout=5,  # Maps to fetch_job_polling_interval in 3.x\n       remove_error=True,  # Maps to remove_failed in 3.x\n   )\n   ```\n\n#### 🆕 Procrastinate 3.x Benefits\n- **Better performance** with improved job fetching\n- **Graceful shutdown** with `shutdown_graceful_timeout`\n- **Enhanced error handling** and job cancellation\n- **Schema compatibility** improvements (3.5.2+)\n\n### Development Setup\n\n```bash\ngit clone \u003crepository\u003e\ncd video_processor\n\n# Install with all development dependencies\nuv sync --dev\n\n# Install with dev + 360° features\nuv sync --dev --extra video-360-full\n\n# Verify installation\nuv run pytest\n```\n\n---\n\n## 🚀 Quick Start\n\n### Basic Video Processing\n\n```python\nfrom pathlib import Path\nfrom video_processor import VideoProcessor, ProcessorConfig\n\n# 📋 Configure your processor\nconfig = ProcessorConfig(\n    base_path=Path(\"/tmp/video_output\"),\n    output_formats=[\"mp4\", \"webm\"],\n    quality_preset=\"high\"  # 🎯 Professional quality\n)\n\n# 🎬 Initialize and process\nprocessor = VideoProcessor(config)\nresult = processor.process_video(\n    input_path=\"input_video.mp4\",\n    output_dir=\"outputs\"\n)\n\n# 📊 Results\nprint(f\"🎥 Video ID: {result.video_id}\")\nprint(f\"📁 Formats: {list(result.encoded_files.keys())}\")\nprint(f\"🖼️ Thumbnail: {result.thumbnail_file}\")\nprint(f\"🎞️ Sprites: {result.sprite_files}\")\n```\n\n### Async Background Processing\n\n```python\nimport asyncio\nfrom video_processor.tasks import setup_procrastinate\n\nasync def process_in_background():\n    # 🗄️ Connect to PostgreSQL\n    app = setup_procrastinate(\"postgresql://user:pass@localhost/db\")\n    \n    # 📤 Submit job\n    job = await app.tasks.process_video_async.defer_async(\n        input_path=\"/path/to/video.mp4\",\n        output_dir=\"/path/to/output\",\n        config_dict={\"quality_preset\": \"ultra\"}\n    )\n    \n    print(f\"✅ Job queued: {job.id}\")\n\nasyncio.run(process_in_background())\n```\n\n---\n\n## ⚙️ Configuration\n\n### Quality Presets Comparison\n\n\u003cdiv align=\"center\"\u003e\n\n| 🎯 Preset | 📺 Video Bitrate | 🔊 Audio Bitrate | 🎨 CRF | 💡 Best For |\n|-----------|------------------|------------------|---------|-------------|\n| **Low** | 1,000k | 128k | 28 | 📱 Mobile, limited bandwidth |\n| **Medium** | 2,500k | 192k | 23 | 🌐 Standard web delivery |\n| **High** | 5,000k | 256k | 18 | 🎬 High-quality streaming |\n| **Ultra** | 10,000k | 320k | 15 | 🏛️ Archive, professional use |\n\n\u003c/div\u003e\n\n### Advanced Configuration\n\n```python\nfrom video_processor import ProcessorConfig\nfrom pathlib import Path\n\nconfig = ProcessorConfig(\n    # 📂 Storage \u0026 Paths\n    base_path=Path(\"/media/videos\"),\n    storage_backend=\"local\",  # 🔮 S3 coming soon!\n    \n    # 🎥 Video Settings\n    output_formats=[\"mp4\", \"webm\", \"ogv\"],\n    quality_preset=\"ultra\",\n    \n    # 🖼️ Thumbnails \u0026 Sprites\n    thumbnail_timestamp=30,    # 📍 30 seconds in\n    sprite_interval=5.0,       # 🎞️ Every 5 seconds\n    \n    # 🛠️ System\n    ffmpeg_path=\"/usr/local/bin/ffmpeg\"  # 🔧 Custom FFmpeg\n)\n```\n\n---\n\n## 🧪 Testing\n\n### 🎯 **NEW in v0.3.0**: Comprehensive Test Infrastructure\n\nVideo Processor now includes a world-class testing framework with **108+ video fixtures** and **perfect test compatibility**!\n\n#### ⚡ Quick Testing\n```bash\n# Run all tests\nmake test\n\n# Unit tests only (fast)\nuv run pytest tests/unit/\n\n# Integration tests with Docker\nmake test-docker\n\n# Test specific categories\nuv run pytest -m \"smoke\"        # Quick smoke tests\nuv run pytest -m \"edge_cases\"   # Edge case scenarios  \nuv run pytest -m \"codecs\"       # Codec compatibility\n```\n\n#### 🎬 Test Video Fixtures\n\nOur comprehensive test suite includes:\n- **Edge Cases**: Single frame videos, unusual resolutions (16x16, 1920x2), extreme aspect ratios\n- **Multiple Codecs**: H.264, H.265, VP8, VP9, Theora, MPEG4 with various profiles  \n- **Audio Variations**: Mono/stereo, different sample rates, no audio, audio-only files\n- **Visual Patterns**: SMPTE bars, RGB test patterns, YUV test, checkerboard patterns\n- **Motion Tests**: Rotation, camera shake, scene changes, complex motion\n- **Stress Tests**: High complexity scenes, noise patterns, encoding challenges\n\n#### 📊 Test Results\n```bash\n✅ 52 passing tests (0 failures!)\n✅ 108+ test video fixtures  \n✅ Complete Docker integration\n✅ Perfect API compatibility\n```\n\n#### 🐳 Docker Integration Testing\n```bash\n# Complete integration testing environment\nmake test-docker\n\n# Test specific services  \nmake test-db-migration    # Database migration testing\nmake test-worker         # Procrastinate worker testing\nmake clean-docker        # Clean up test environment\n```\n\n#### 🔧 Advanced Testing\n```bash\n# Generate/update test video fixtures\nuv run python tests/fixtures/test_suite_manager.py --setup\n\n# Validate test suite integrity\nuv run python tests/fixtures/test_suite_manager.py --validate\n\n# Generate synthetic videos for edge cases\nuv run python tests/fixtures/generate_synthetic_videos.py\n\n# Download open source test videos\nuv run python tests/fixtures/download_test_videos.py\n```\n\n#### 🎨 Test Categories\n\n| Category | Description | Video Count |\n|----------|-------------|-------------|\n| **smoke** | Quick validation tests | 2 videos |\n| **basic** | Standard functionality | 5 videos |  \n| **codecs** | Format compatibility | 9 videos |\n| **edge_cases** | Boundary conditions | 12+ videos |\n| **stress** | Performance testing | 2+ videos |\n| **full** | Complete test suite | 108+ videos |\n\n---\n\n## 💡 Examples\n\nExplore our comprehensive examples in the [`examples/`](examples/) directory:\n\n### 📝 Available Examples\n\n| Example | Description | Features |\n|---------|-------------|-----------|\n| [`basic_usage.py`](examples/basic_usage.py) | 🎯 Simple synchronous processing | Configuration, encoding, thumbnails |\n| [`async_processing.py`](examples/async_processing.py) | ⚡ Background task processing | Procrastinate, job queuing, monitoring |\n| [`custom_config.py`](examples/custom_config.py) | 🛠️ Advanced configuration scenarios | Quality presets, validation, custom paths |\n| [`docker_demo.py`](examples/docker_demo.py) | 🐳 Complete containerized demo | Docker, PostgreSQL, async workers |\n| [`web_demo.py`](examples/web_demo.py) | 🌐 Flask web interface | Browser-based processing, job submission |\n\n### 🐳 Docker Quick Start\n\nGet up and running in seconds with our complete Docker environment:\n\n```bash\n# Start all services (PostgreSQL, Redis, app, workers)\ndocker-compose up -d\n\n# View logs from the demo application\ndocker-compose logs -f app\n\n# Access web demo at http://localhost:8080\ndocker-compose up demo\n\n# Run tests in Docker\ndocker-compose run test\n\n# Clean up\ndocker-compose down -v\n```\n\n**Services included:**\n- 🗄️ **PostgreSQL** - Database with Procrastinate job queue\n- 🎬 **App** - Main video processor demo\n- ⚡ **Worker** - Background job processor\n- 🧪 **Test** - Automated testing environment\n- 🌐 **Demo** - Web interface for browser-based testing\n\n### 🎬 Real-World Usage Patterns\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003e🏢 Production Video Pipeline\u003c/b\u003e\u003c/summary\u003e\n\n```python\n# Multi-format encoding for video platform\nconfig = ProcessorConfig(\n    base_path=Path(\"/var/media/uploads\"),\n    output_formats=[\"mp4\", \"webm\"],  # Cross-browser support\n    quality_preset=\"high\",\n    sprite_interval=10.0  # Balanced performance\n)\n\nprocessor = VideoProcessor(config)\nresult = processor.process_video(user_upload, output_dir)\n\n# Generate multiple qualities\nfor quality in [\"medium\", \"high\"]:\n    config.quality_preset = quality\n    processor = VideoProcessor(config)\n    # Process to different quality folders...\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003e📱 Mobile-Optimized Processing\u003c/b\u003e\u003c/summary\u003e\n\n```python\n# Lightweight encoding for mobile delivery\nmobile_config = ProcessorConfig(\n    base_path=Path(\"/tmp/mobile_videos\"),\n    output_formats=[\"mp4\"],  # Mobile-friendly format\n    quality_preset=\"low\",    # Reduced bandwidth\n    sprite_interval=15.0     # Fewer sprites\n)\n```\n\n\u003c/details\u003e\n\n---\n\n## 📚 API Reference\n\n### 🎬 VideoProcessor\n\nThe main orchestrator for all video processing operations.\n\n#### 🔧 Methods\n\n```python\n# Process video to all configured formats\nresult = processor.process_video(\n    input_path: Path | str,\n    output_dir: Path | str | None = None,\n    video_id: str | None = None\n) -\u003e VideoProcessingResult\n\n# Encode to specific format\noutput_path = processor.encode_video(\n    input_path: Path,\n    output_dir: Path,\n    format_name: str,\n    video_id: str\n) -\u003e Path\n\n# Generate thumbnail at timestamp\nthumbnail = processor.generate_thumbnail(\n    video_path: Path,\n    output_dir: Path,\n    timestamp: int,\n    video_id: str\n) -\u003e Path\n\n# Create sprite sheet and WebVTT\nsprites = processor.generate_sprites(\n    video_path: Path,\n    output_dir: Path,\n    video_id: str\n) -\u003e tuple[Path, Path]\n```\n\n### ⚙️ ProcessorConfig\n\nType-safe configuration with automatic validation.\n\n#### 📋 Essential Fields\n\n```python\nclass ProcessorConfig:\n    base_path: Path                    # 📂 Base directory\n    output_formats: list[str]          # 🎥 Video formats\n    quality_preset: str                # 🎯 Quality level\n    storage_backend: str               # 💾 Storage type\n    ffmpeg_path: str                   # 🛠️ FFmpeg binary\n    thumbnail_timestamp: int           # 🖼️ Thumbnail position\n    sprite_interval: float             # 🎞️ Sprite frequency\n```\n\n### 📊 VideoProcessingResult\n\nComprehensive result object with all output information.\n\n```python\n@dataclass\nclass VideoProcessingResult:\n    video_id: str                      # 🆔 Unique identifier\n    encoded_files: dict[str, Path]     # 📁 Format → file mapping\n    thumbnail_file: Path | None        # 🖼️ Thumbnail image\n    sprite_files: tuple[Path, Path] | None  # 🎞️ Sprite + WebVTT\n    metadata: VideoMetadata            # 📊 Video properties\n```\n\n---\n\n## 🧪 Development\n\n### 🛠️ Development Commands\n\n```bash\n# 📦 Install dependencies\nuv sync\n\n# 🧪 Run test suite\nuv run pytest -v\n\n# 📊 Test coverage\nuv run pytest --cov=video_processor\n\n# ✨ Code formatting\nuv run ruff format .\n\n# 🔍 Linting\nuv run ruff check .\n\n# 🎯 Type checking\nuv run mypy src/\n```\n\n### 📈 Test Coverage\n\nOur comprehensive test suite covers:\n\n- ✅ **Configuration** validation and type checking\n- ✅ **Path utilities** and file operations  \n- ✅ **FFmpeg integration** and error handling\n- ✅ **Video metadata** extraction\n- ✅ **Background task** processing\n- ✅ **Procrastinate compatibility** (2.x/3.x versions)\n- ✅ **Database migrations** with version detection\n- ✅ **Worker configuration** and option mapping\n- ✅ **360° video processing** (when dependencies available)\n\n```bash\n========================== test session starts ==========================\ntests/test_config.py ✅✅✅✅✅           [15%] \ntests/test_utils.py ✅✅✅✅✅✅✅✅       [30%]\ntests/test_procrastinate_compat.py ✅✅✅✅✅✅✅✅✅✅✅✅✅✅✅✅✅  [85%]\ntests/test_procrastinate_migration.py ✅✅✅✅✅✅✅✅✅✅✅✅✅   [100%]\n\n======================== 43 passed in 0.52s ========================\n```\n\n---\n\n## 📦 Dependencies\n\n### 🎯 Core Dependencies\n\n| Package | Purpose | Why We Use It |\n|---------|---------|---------------|\n| `ffmpeg-python` | FFmpeg integration | 🎬 Professional video processing |\n| `msprites2` | Sprite generation | 🎞️ Seekbar thumbnails (forked for fixes) |\n| `procrastinate` | Background tasks | ⚡ Scalable async processing |\n| `pydantic` | Configuration | ⚙️ Type-safe settings validation |\n| `pillow` | Image processing | 🖼️ Thumbnail manipulation |\n\n### 🔧 Development Tools\n\n| Tool | Purpose | Benefits |\n|------|---------|----------|\n| `uv` | Package management | 🚀 Ultra-fast dependency resolution |\n| `ruff` | Linting \u0026 formatting | ⚡ Lightning-fast code quality |\n| `pytest` | Testing framework | 🧪 Reliable test execution |\n| `mypy` | Type checking | 🎯 Static type analysis |\n| `coverage` | Test coverage | 📊 Quality assurance |\n\n---\n\n## 🌟 Why Video Processor?\n\n\u003cdiv align=\"center\"\u003e\n\n### 🆚 Comparison with Alternatives\n\n| Feature | Video Processor | FFmpeg CLI | moviepy | OpenCV |\n|---------|----------------|------------|---------|--------|\n| **Two-pass encoding** | ✅ | ✅ | ❌ | ❌ |\n| **Multiple formats** | ✅ | ✅ | ✅ | ❌ |\n| **Background processing** | ✅ | ❌ | ❌ | ❌ |\n| **Type safety** | ✅ | ❌ | ❌ | ❌ |\n| **Sprite generation** | ✅ | ❌ | ❌ | ❌ |\n| **Modern Python** | ✅ | N/A | ❌ | ❌ |\n\n\u003c/div\u003e\n\n---\n\n## 📋 Requirements\n\n### 🖥️ System Requirements\n\n- **Python 3.11+** - Modern Python features\n- **FFmpeg** - Video processing engine\n- **PostgreSQL** - Background job processing (optional)\n\n### 🐧 Installation Commands\n\n```bash\n# Ubuntu/Debian\nsudo apt install ffmpeg postgresql-client\n\n# macOS\nbrew install ffmpeg postgresql\n\n# Arch Linux\nsudo pacman -S ffmpeg postgresql\n```\n\n---\n\n## 🤝 Contributing\n\nWe welcome contributions! Here's how to get started:\n\n### 🚀 Quick Contribution Guide\n\n1. **🍴 Fork** the repository\n2. **🌿 Create** a feature branch (`git checkout -b feature/amazing-feature`)\n3. **📝 Make** your changes with tests\n4. **🧪 Test** everything (`uv run pytest`)\n5. **✨ Format** code (`uv run ruff format .`)\n6. **📤 Submit** a pull request\n\n### 🎯 Areas We'd Love Help With\n\n- 🌐 **S3 storage backend** implementation\n- 🎞️ **Additional video formats** (AV1, HEVC)\n- 📊 **Progress tracking** and monitoring\n- 🐳 **Docker integration** examples\n- 📖 **Documentation** improvements\n\n---\n\n## 📜 License\n\nThis project is licensed under the **MIT License** - see the [LICENSE](LICENSE) file for details.\n\n---\n\n## 🎉 Changelog\n\n### 🚀 v0.2.0 - Procrastinate 3.x Migration \u0026 Docker Support\n\n- 🔄 **Procrastinate 3.x compatibility** with backward support for 2.x\n- 🎯 **Automatic version detection** and feature flagging \n- 📋 **Database migration utilities** with pre/post migration support\n- 🐳 **Complete Docker environment** with multi-service orchestration\n- 🌐 **Web demo interface** with Flask-based UI\n- ⚡ **Worker compatibility layer** with unified CLI\n- 🧪 **30+ comprehensive tests** covering all compatibility scenarios\n- 📊 **uv caching optimization** following Docker best practices\n\n### 🌟 v0.1.0 - Initial Release\n\n- ✨ **Multi-format encoding**: MP4, WebM, OGV support\n- 🖼️ **Thumbnail generation** with customizable timestamps\n- 🎞️ **Sprite sheet creation** with WebVTT files\n- ⚡ **Background processing** with Procrastinate integration\n- ⚙️ **Type-safe configuration** with Pydantic V2\n- 🛠️ **Modern tooling**: uv, ruff, pytest integration\n- 📚 **Comprehensive documentation** and examples\n\n---\n\n## 🔄 Migration to v0.4.0\n\n### **Upgrading from Previous Versions**\n\nVideo Processor v0.4.0 maintains **100% backward compatibility** while adding powerful new features:\n\n```python\n# Your existing code continues to work unchanged\nprocessor = VideoProcessor(config)\nresult = await processor.process_video(\"video.mp4\", \"./output/\")\n\n# But now you get additional features automatically:\nif result.is_360_video:\n    print(f\"360° projection: {result.video_360.projection_type}\")\n\nif result.quality_analysis:\n    print(f\"Quality score: {result.quality_analysis.overall_quality:.1f}/10\")\n```\n\n### **New Features Available**\n- **🤖 AI Analysis**: Automatic scene detection and quality assessment\n- **🎥 Modern Codecs**: AV1, HEVC, and HDR support\n- **📡 Streaming**: HLS and DASH adaptive streaming\n- **🌐 360° Processing**: Complete immersive video pipeline\n\n### **Migration Resources**\n- **[📋 Complete Migration Guide](docs/migration/MIGRATION_GUIDE_v0.4.0.md)** - Step-by-step upgrade instructions\n- **[🚀 New Features Overview](docs/user-guide/NEW_FEATURES_v0.4.0.md)** - What's new in v0.4.0\n- **[💻 Updated Examples](docs/examples/README.md)** - New capabilities in action\n\n---\n\n\u003cdiv align=\"center\"\u003e\n\n### 🙋‍♀️ Questions? Issues? Ideas?\n\n**Found a bug?** [Open an issue](https://github.com/your-repo/issues/new/choose)  \n**Have a feature request?** [Start a discussion](https://github.com/your-repo/discussions)  \n**Want to contribute?** Check out our [contribution guide](#-contributing)\n\n---\n\n**Built with ❤️ for the video processing community**\n\n*Making professional video encoding accessible to everyone*\n\n\u003c/div\u003e","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frsp2k%2Fvideo-processor","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frsp2k%2Fvideo-processor","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frsp2k%2Fvideo-processor/lists"}