A photomosaic video generator that creates artistic mosaic videos from images. Transform any photo into a stunning mosaic built from thousands of tiny component images, and watch the process as an animated video.

• 5 Output Modes: Satisfying/ASMR video, Timelapse video, Comparison video, Static image, Video-to-video mosaic
• 7 Animation Types: drop-in, fade-in, slide-in, pop, scale-up, rotate-in, none
• 6 Placement Algorithms: row-by-row, column-by-column, random, spiral, center-out, diagonal
• 8 Video Presets: Short, Standard, Satisfying, Timelapse, Instagram Reel, TikTok, 4K Showcase, Quick Demo
• Aspect Ratio Support: 16:9, 9:16, 1:1 with edge-extend, blur, or color fill
• Progress Indicators: 6 themes (modern, neon, ocean, minimal, fire, glass)
• Audio Support: Background music and sound effects
• Text Overlays: Titles, subtitles, captions with custom fonts

pip install mosavid

# Create a satisfying mosaic video
mosavid satisfying -i examples/1.jpg -o output.mp4

# Quick test (5-10 second low-res video)
mosavid quick-test -i examples/1.jpg

pip install mosavid

git clone https://github.com/aliyilmazco/mosavid.git
cd mosavid
pip install -e .

git clone https://github.com/aliyilmazco/mosavid.git
cd mosavid
pip install -e ".[dev]"

Tiles are placed one-by-one with smooth animations:

mosavid satisfying \
  --input examples/1.jpg \
  --output mosaic.mp4 \
  --animation drop_in \
  --order spiral \
  --tiles-per-second 5 \
  --stride 10

Fast-forwarded mosaic construction in a target duration:

mosavid timelapse \
  --input examples/1.jpg \
  --output timelapse.mp4 \
  --duration 30 \
  --order row_by_row \
  --adaptive  # slow start, accelerating speed

Before/after comparison with transitions:

mosavid comparison \
  --input examples/1.jpg \
  --output comparison.mp4 \
  --style wipe \
  --hold-time 3 \
  --transition-time 2

Styles: wipe, fade, slide, slider, side_by_side

Use pre-optimized configurations for specific platforms:

mosavid preset \
  --input examples/1.jpg \
  --preset short

Generate a mosaic image without video:

mosavid image \
  --input examples/1.jpg \
  --output mosaic.png \
  --stride 10

Convert each frame of a video into a mosaic:

mosavid video \
  --input video.mp4 \
  --output mosaic_video.mp4 \
  --stride 10 \
  --overlay-ratio 0.2  # show original in corner

mosavid quick-test -i examples/1.jpg

mosavid list-options

The project includes a pool of 1,500+ face images in the face/ directory. You can use your own tile pool:

mosavid satisfying -i examples/1.jpg --pool /path/to/your/images

Your component images directory should contain .jpg or .png files. For best results:

• Use at least 100+ images for variety
• All images will be resized to stride x stride pixels
• More diverse colors in your pool = better mosaic quality

mosavid/
├── core/                 # Mosaic engine
│   ├── component_loader  # Image pool loading & caching
│   ├── tile_matcher      # Color-based tile matching
│   ├── mosaic_engine     # Tile placement algorithms
│   └── aspect_ratio_handler
├── generators/           # Video generators
│   ├── base_generator    # Abstract base class
│   ├── satisfying_generator  # ASMR-style videos
│   ├── timelapse_generator   # Speed-up videos
│   └── comparison_generator  # Before/after videos
├── effects/              # Visual effects
│   ├── animations        # Tile animations & easing
│   ├── progress_indicator    # Progress bar themes
│   ├── text_overlay      # Text rendering
│   └── transitions       # Video transitions
├── audio/                # Audio management
│   ├── audio_manager     # Background music
│   └── sound_effects     # Tile placement sounds
└── config/               # Configuration
    ├── settings          # Defaults & constants
    └── presets           # Platform presets

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

This project is licensed under the MIT License - see the LICENSE file for details.