_ _            ___
  _ __ ___  ___ _ __ (_) |_ ___  ___|_  )
 | '_ ` _ \/ __| '_ \| | __/ _ \/ __/ / /
 | | | | | \__ \ |_) | | ||  __/\__ \/ /_
 |_| |_| |_|___/ .__/|_|\__\___||___/___|
               |_|

🚀 Why msprites2?

msprites2 is the fastest, most feature-rich Python library for creating video thumbnail sprite sheets and WebVTT files. Built for modern video platforms, ML pipelines, and content creators who demand performance and flexibility.

⚡ Lightning Fast Performance

🎯 Perfect For

• 📺 Video Platforms → Netflix-style scrubbing previews
• 🤖 AI/ML Pipelines → Real-time neural processing
• 🎨 Content Creators → Automated thumbnail generation
• 🌐 Web Developers → Modern video player interfaces

✨ Features at a Glance

🏃‍♂️ Quick Start

3 Lines to Video Thumbnails

from msprites2 import MontageSprites

# Generate sprite sheet + WebVTT in seconds! 🚀
sprite = MontageSprites.from_media("video.mp4", "thumbnails/", "sprite.jpg", "timeline.webvtt")

That's it! You'll get:

• 📸 sprite.jpg → Beautiful thumbnail grid
• 📝 timeline.webvtt → Perfect video player integration (WebVTT spec)
• 📁 thumbnails/ → Individual frames for processing

🛠️ Installation

Option 1: One-Line Install (Recommended)

# Modern Python package manager
uv add msprites2

# Traditional pip
pip install msprites2

Option 2: System Dependencies

sudo apt update && sudo apt install -y ffmpeg imagemagick
pip install msprites2

brew install ffmpeg imagemagick
pip install msprites2

# Install via chocolatey
choco install ffmpeg imagemagick
pip install msprites2

✅ Verify Installation

import msprites2
print(f"🎉 msprites2 ready!")

🎙️ Audio Transcription (Optional)

Generate WebVTT captions from video audio using Whisper AI:

# Install with transcription support
pip install msprites2[transcription]

# Or install all AI features
pip install msprites2[ai]

📖 Usage Examples

🎬 Basic Sprite Generation

from msprites2 import MontageSprites

# Create sprites from video
sprite = MontageSprites("movie.mp4", "frames/")
sprite.generate_thumbs()           # Extract frames
sprite.generate_sprite("grid.jpg")  # Create sprite sheet  
sprite.generate_webvtt("timeline.vtt") # Generate WebVTT

⚡ Parallel Processing (2x Faster)

from msprites2 import MontageSprites

# Parallel extraction for long videos
sprite = MontageSprites("long_video.mp4", "output/")
sprite.generate_thumbs(parallel=True)  # 🚀 Parallel mode!

# One-liner with parallel processing
MontageSprites.from_media(
    video_path="video.mp4",
    thumbnail_dir="thumbs/", 
    sprite_file="sprite.jpg",
    webvtt_file="timeline.vtt",
    parallel=True  # 🔥 Unleash the power!
)

🧠 AI/ML Stream Processing

from msprites2 import MontageSprites

def neural_style_transfer(frame_path, frame_num):
    """Apply AI processing to each frame"""
    styled_frame = ai_model.process(frame_path)
    return f"styled_{frame_num:04d}.jpg"

# Stream frames to your AI model in real-time! 🤖
sprite = MontageSprites("video.mp4", "frames/")
for styled_path, frame_num in sprite.extract_streaming(neural_style_transfer):
    print(f"🎨 Styled frame {frame_num}: {styled_path}")

🎙️ Audio Transcription & Captions

NEW in v0.11.0! Generate WebVTT captions from video audio using Whisper AI:

from msprites2 import transcribe_video

# One-liner: transcribe video → WebVTT captions
segments = transcribe_video(
    "video.mp4",
    "captions.vtt",
    model_size="base",  # tiny, base, small, medium, large-v3
    language="en"       # or None for auto-detect
)

print(f"✅ Generated {len(segments)} caption segments!")

Advanced Usage:

from msprites2 import AudioTranscriber

# Initialize transcriber with custom settings
transcriber = AudioTranscriber(
    model_size="medium",  # Better accuracy
    device="cuda",        # GPU acceleration (or "cpu")
    compute_type="float16",  # Precision
    language="en"         # Force English
)

# Transcribe with progress tracking
def on_progress(elapsed_time):
    print(f"⏰ Processed {elapsed_time:.1f}s of audio...")

segments = transcriber.transcribe(
    "video.mp4",
    beam_size=5,          # Higher = better quality
    vad_filter=True,      # Skip silence
    progress_callback=on_progress
)

# Save to WebVTT format
transcriber.save_webvtt(segments, "captions.vtt")

Generated WebVTT Output:

WEBVTT

1
00:00:00.000 --> 00:00:02.500
Welcome to our video tutorial.

2
00:00:02.500 --> 00:00:05.000
Today we'll learn about Python programming.

3
00:00:05.000 --> 00:00:08.500
Let's start with the basics!

Use Cases:

• 📝 Accessibility → Auto-generate subtitles for deaf/hard-of-hearing viewers
• 🔍 Search & Indexing → Make video content searchable by speech
• 🌍 Internationalization → Transcribe then translate to other languages
• 📊 Content Analysis → Analyze what's being said in videos

🖼️ Visual Frame Analysis with AI

NEW in v0.12.0! Analyze video frames using Ollama vision models (llava, moondream) to generate visual descriptions:

from msprites2 import VisualAnalyzer

# Initialize with your preferred vision model
analyzer = VisualAnalyzer(
    model="llava:7b",  # or "llava:13b", "moondream"
    ollama_host="https://ollama.l.supported.systems",
    fps=1.0  # Frame rate for timestamp calculation
)

# Analyze extracted frames and generate WebVTT descriptions
descriptions = analyzer.analyze_frames_to_webvtt(
    "frames/",
    "visual_descriptions.vtt",
    max_frames=100  # Optional: limit number of frames
)

print(f"✅ Generated {len(descriptions)} visual descriptions!")

Advanced Usage with Custom Prompts:

from msprites2 import VisualAnalyzer

# Custom analysis prompt
analyzer = VisualAnalyzer(
    model="llava:13b",
    prompt="Describe the main action and emotions in this scene in detail."
)

# Analyze with progress tracking
def on_progress(current, total):
    print(f"🔍 Analyzing frame {current}/{total}...")

descriptions = analyzer.analyze_frames(
    "frames/",
    pattern="*.jpg",
    progress_callback=on_progress
)

# Save to WebVTT with custom cue duration
analyzer.save_webvtt(descriptions, "descriptions.vtt", cue_duration=2.0)

Generated Visual Description WebVTT:

WEBVTT
KIND: descriptions

1
00:00:00.000 --> 00:00:01.000
A person typing on a laptop in a modern office setting.

2
00:00:01.000 --> 00:00:02.000
Close-up of hands gesturing while explaining a concept.

3
00:00:02.000 --> 00:00:03.000
Wide shot of a conference room with people collaborating.

Use Cases:

• ♿ Accessibility → Visual descriptions for blind/low-vision viewers
• 🔍 Content Discovery → Search videos by visual content
• 📊 AI/ML Pipelines → Automated scene understanding
• 🎬 Content Moderation → Detect inappropriate visual content

Installation:

# Install with vision support
pip install msprites2[vision]

# Or install all AI features (transcription + vision)
pip install msprites2[ai]

⚙️ Advanced Configuration

from msprites2.parallel_extractor import ParallelFrameExtractor

# Mobile-optimized thumbnails
mobile_extractor = ParallelFrameExtractor(
    video_path="video.mp4",
    output_dir="mobile_thumbs/",
    width=256,        # Mobile-friendly size
    height=144,       # 16:9 aspect ratio
    ips=2,           # Every 2 seconds
    chunk_duration=5, # 5-second chunks
    max_workers=4    # Optimize for mobile CPUs
)

# 4K High-Quality Sprites
hq_extractor = ParallelFrameExtractor(
    video_path="4k_video.mp4", 
    output_dir="hq_thumbs/",
    width=1920,      # 4K width
    height=1080,     # 4K height  
    ips=0.5,        # Every 0.5 seconds (more frames)
    chunk_duration=15, # Larger chunks for 4K
    max_workers=8    # More workers for heavy processing
)

# Extract with progress tracking
def progress_callback(completed, total):
    print(f"Progress: {completed}/{total} chunks ({completed/total*100:.1f}%)")

frame_count = hq_extractor.extract_parallel()
print(f"🎉 Extracted {frame_count} high-quality frames!")

📊 Performance Deep Dive

🏃‍♂️ When to Use Parallel Processing

📈 Real Benchmark Results

Our comprehensive benchmarking shows:

• I/O Bound: Video extraction is primarily disk-limited, not CPU-limited
• Sweet Spot: Parallel processing shines with videos >5 minutes
• ML Power: Streaming processing enables real-time neural networks
• Memory Efficient: Process frames without loading entire video into memory

# Run your own benchmarks
python benchmark_performance.py your_video.mp4 --duration 60

# Results example:
🎬 Benchmarking msprites2 performance
📹 Video: test_video.mp4 (60s, 15.2MB, h264)

🔄 Sequential: 122 frames in 0.65s (188 fps)
⚡ Parallel (8 workers): 144 frames in 0.99s (146 fps) 
🚀 Speedup: 0.7x (overhead dominates for short videos)

💡 Recommendation: Use sequential for videos <5 minutes

🌟 Who's Using msprites2?

Production deployments: Video platforms, content management systems, AI research labs, streaming services

🎯 Output Examples

📸 Generated Sprite Sheet

Your sprite sheet will look like this professional grid:

[🖼️ thumbnail] [🖼️ thumbnail] [🖼️ thumbnail] [🖼️ thumbnail]
[🖼️ thumbnail] [🖼️ thumbnail] [🖼️ thumbnail] [🖼️ thumbnail]  
[🖼️ thumbnail] [🖼️ thumbnail] [🖼️ thumbnail] [🖼️ thumbnail]

📝 Generated WebVTT

WEBVTT

00:00:00.000 --> 00:00:01.000
sprite.jpg#xywh=0,0,512,288

00:00:01.000 --> 00:00:02.000
sprite.jpg#xywh=512,0,512,288

00:00:02.000 --> 00:00:03.000
sprite.jpg#xywh=1024,0,512,288

Perfect for modern video players like Video.js, Plyr, or custom HTML5 implementations!

🧪 Development & Testing

🚀 Modern Development Stack

• Package Manager: uv (blazing fast!)
• Code Quality: ruff (all-in-one linter + formatter)
• Testing: pytest (comprehensive test suite)
• Type Safety: Full type hints with mypy support

🛠️ Development Setup

# Clone and setup (modern way)
git clone https://github.com/rsp2k/msprites2.git
cd msprites2
uv sync --extra dev

# Run tests  
uv run pytest tests/ -v

# Code quality checks
uv run ruff check .
uv run ruff format .

# Performance benchmarks
uv run python benchmark_performance.py

# Traditional Python setup
git clone https://github.com/rsp2k/msprites2.git
cd msprites2
python -m venv venv
source venv/bin/activate  # or `venv\Scripts\activate` on Windows
pip install -e .[dev]

# Run full test suite
pytest tests/ -v --cov=msprites2

✅ Test Coverage

• 16/16 parallel processing tests pass
• 19/19 core functionality tests pass
• Full integration test coverage
• Performance benchmarks included
• Error handling thoroughly tested

🤝 Contributing

We ❤️ contributions! msprites2 is community-driven and welcomes developers of all skill levels.

🌟 Hall of Fame

🎯 Good First Issues

Perfect for newcomers:

• 📝 Documentation improvements
• 🧪 Additional test cases
• 🐛 Bug fixes
• ✨ Feature enhancements

🚀 Contribution Levels

📬 Get Involved

• 💬 Discussions: GitHub Discussions
• 🐛 Bug Reports: Issue Tracker
• 📖 Wiki: Project Wiki
• 📧 Email: ryan@supported.systems

📄 License

MIT License - see LICENSE file for details.

Free for commercial use ✅ No attribution required ✅ Modify as needed ✅