video-processor/docs/examples

📚 Examples Documentation

This directory contains comprehensive examples demonstrating all features of the Video Processor v0.4.0.

🚀 Getting Started Examples

basic_usage.py

Start here! Shows the fundamental video processing workflow with the main VideoProcessor class.

# Simple video processing
processor = VideoProcessor(config)
result = await processor.process_video("input.mp4", "./output/")

custom_config.py

Demonstrates advanced configuration options and quality presets.

# Custom configuration for different use cases
config = ProcessorConfig(
    quality_preset="ultra",
    output_formats=["mp4", "av1_mp4"],
    enable_ai_analysis=True
)

🤖 AI-Powered Features

ai_enhanced_processing.py

Complete AI content analysis with scene detection and quality assessment.

# AI-powered content analysis
analysis = await analyzer.analyze_content(video_path)
print(f"Scenes: {analysis.scenes.scene_count}")
print(f"Quality: {analysis.quality_metrics.overall_quality}")

🎥 Advanced Codec Examples

advanced_codecs_demo.py

Demonstrates AV1, HEVC, and HDR processing capabilities.

# Modern codec encoding
config = ProcessorConfig(
    output_formats=["mp4", "av1_mp4", "hevc"],
    enable_av1_encoding=True,
    enable_hdr_processing=True
)

📡 Streaming Examples

streaming_demo.py

Shows how to create adaptive streaming packages (HLS/DASH) for web delivery.

# Create adaptive streaming
streaming_package = await stream_processor.create_adaptive_stream(
    video_path, output_dir, formats=["hls", "dash"]
)

🌐 360° Video Processing

360_video_examples.py

Comprehensive 360° showcase with 7 detailed examples:

1. Basic 360° Analysis - Detect and analyze spherical videos
2. Projection Conversion - Convert between equirectangular, cubemap, etc.
3. Viewport Extraction - Extract flat videos from specific viewing angles
4. Spatial Audio Processing - Handle ambisonic and binaural audio
5. 360° Adaptive Streaming - Viewport-adaptive streaming with bandwidth optimization
6. Batch Processing - Convert multiple projections in parallel
7. Quality Analysis - Assess 360° video quality and get optimization recommendations

video_360_example.py

Focused example showing core 360° processing features.

🐳 Production Deployment

docker_demo.py

Production deployment with Docker containers and environment configuration.

worker_compatibility.py

Distributed processing with Procrastinate workers for scalable deployments.

async_processing.py

Advanced async patterns for high-throughput video processing.

🌐 Web Integration

web_demo.py

Flask web application demonstrating video processing API integration.

# Web API endpoint
@app.post("/process")
async def process_video_api(file: UploadFile):
    result = await processor.process_video(file.path, output_dir)
    return {"status": "success", "formats": list(result.encoded_files.keys())}

🏃‍♂️ Running the Examples

Prerequisites

# Install with all features
uv add video-processor[all]

# Or install specific feature sets
uv add video-processor[ai,360,streaming]

Basic Examples

# Run basic usage example
uv run python examples/basic_usage.py

# Test AI analysis
uv run python examples/ai_enhanced_processing.py

# Try 360° processing
uv run python examples/360_video_examples.py

Advanced Examples

# Set up Docker environment
uv run python examples/docker_demo.py

# Test streaming capabilities
uv run python examples/streaming_demo.py

# Run web demo (requires Flask)
uv add flask
uv run python examples/web_demo.py

🎯 Example Categories

Category	Examples	Features Demonstrated
Basics	basic_usage.py, custom_config.py	Core processing, configuration
AI Features	ai_enhanced_processing.py	Scene detection, quality analysis
Modern Codecs	advanced_codecs_demo.py	AV1, HEVC, HDR processing
Streaming	streaming_demo.py	HLS, DASH adaptive streaming
360° Video	360_video_examples.py, video_360_example.py	Immersive video processing
Production	docker_demo.py, worker_compatibility.py	Deployment, scaling
Integration	web_demo.py, async_processing.py	Web APIs, async patterns

💡 Tips for Learning

1. Start Simple: Begin with basic_usage.py to understand the core concepts
2. Progress Gradually: Move through AI → Codecs → Streaming → 360° features
3. Experiment: Modify the examples with your own video files
4. Check Logs: Enable logging to see detailed processing information
5. Read Comments: Each example includes detailed explanations and best practices

🔧 Troubleshooting

Common Issues

Missing Dependencies

# AI features require OpenCV
pip install opencv-python

# 360° processing needs additional packages
pip install numpy opencv-python

FFmpeg Not Found

# Install FFmpeg (varies by OS)
# Ubuntu/Debian: sudo apt install ffmpeg
# macOS: brew install ffmpeg
# Windows: Download from ffmpeg.org

Import Errors

# Ensure video-processor is installed
uv add video-processor

# For development
uv sync --dev

Getting Help

• Check the migration guide for upgrade instructions
• See user guide for complete feature documentation
• Review development docs for technical implementation details

---

These examples demonstrate the full capabilities of Video Processor v0.4.0 - from simple format conversion to advanced 360° immersive experiences with AI optimization.