AI-Media-Gallery: Locally-Hosted Media Gallery with AI Similarity Search

Architecture Overview

graph TB
    subgraph "Frontend Layer"
        Frontend[Next.js Frontend]
    end

    subgraph "API Layer"
        API[FastAPI Backend]
        DR[Directory Router]
        TR[Train Router]
        TAGR[TagRouter]
        FR[File Router]
        SR[Search Router]
    end

    subgraph "Service Layer"
        ES[EmbeddingService]
        RS[RedisService]
        FS[FileService]
        TS[TrainingService]
    end

    subgraph "ML Layer"
        VJEPA[V-JEPA2 Models]
        CL[Classifier Training]
        INF[Inference Pipeline]
    end

    subgraph "Data Layer"
        Redis[(Redis DB)]
        Storage[File System]
        Models[Trained Models]
    end

    subgraph "Redis Storage"
        HNSW[HNSW Vector Indices]
        Meta[File/Directory Metadata]
        Tags[Tag Management]
        FTM[Fine-Tuned Models]
    end

    Frontend --> API

    API --> TR
    API --> FR
    API --> SR
    API --> DR
    API --> TAGR

    TR --> TS
    FR --> FS
    SR --> ES
    DR --> RS
    TAGR --> RS

    TS --> RS
    TS --> CL
    TS --> INF
    ES --> VJEPA
    ES --> RS
    FS --> RS

    CL --> Models
    INF --> VJEPA
    INF --> Models

    RS --> Redis
    FS --> Storage

    Redis --> HNSW
    Redis --> Meta
    Redis --> Tags
    Redis --> FTM

Loading

Application Screenshots & Demos

Main Features

Click to expand

Directory Details

View detailed information and statistics for each directory

Files Gallery

Gallery view of all your media files with metadata

Similarity Search

Find similar images and videos using AI-powered vector search

Feature Demonstrations

Click to expand

Feature Demonstrations

Viewing Local Files

Browse and navigate through your local media library

Similarity Search in Action

Search for visually similar content across your entire media library

Classifier Training

Train custom ML classifiers on your media collection

File Classification

Automatically classify and tag files using trained models

Getting Started (User)

Prerequisites

• Docker and Docker Compose
• Python 3.12+ (for virtual environment - venv)
• ffmpeg 6.1.1+
• make
• git

Quick Start

1. Clone the repository

   git clone https://github.com/emapco/ai-media-gallery.git
   cd ai-media-gallery

2. Install dependencies and build

   make install

   This will:

   • Create a Python virtual environment
   • Build Docker containers
   • Install Python and Node.js dependencies

   Optional GPU Optimization: If you have a GPU that supports Flash Attention, run:

   make install-flash-attn

   • Note that this requires CUDA Toolkit and may take a long time to build.

3. Start the application

   make start

   This starts:

   • Redis database on port 6379
   • Frontend on http://localhost:3000
   • FastAPI backend on http://localhost:7999

4. Stop the application

   make stop

Configuration

Configuration Files

The application can be configured using YAML configuration files in the conf/ directory:

• conf/backend.yaml - Backend service configuration including:

  • V-JEPA2 model settings and embedding parameters
  • HNSW vector index configuration for Redis
  • File service settings (thumbnails, supported formats)
  • Performance tuning (workers, batch sizes)

• conf/classifier.yaml - ML classifier training configuration including:

  • Model architecture and training hyperparameters
  • Data processing settings (video/image formats)
  • Training arguments (epochs, learning rate, optimization)

Environment Variables

Development environment variables in .env:

# Redis Configuration
REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_PORT_TESTING=6378      # Separate port for tests
REDIS_PASSWORD=

# Backend Configuration
BACKEND_LOG_LEVEL=info
BACKEND_WORKERS=2
BACKEND_HOST=localhost
BACKEND_PORT=7999
BACKEND_BASE_URL=http://localhost:7999

# Frontend Configuration
NEXT_PUBLIC_API_URL=http://localhost:7999
NODE_ENV=development

Video Embedding Models

Hugging Face Model	Parameters	Size (GB)
facebook/vjepa2-vitl-fpc64-256	325M	1.3
facebook/vjepa2-vith-fpc64-256	654M	2.6
facebook/vjepa2-vitg-fpc64-256	1.03B	4.1
facebook/vjepa2-vitg-fpc64-384	1.03B	4.1

Getting Started (Development)

Development Environment

1. Install development dependencies

make install-dev

2. Start development server with hot reloading

make dev

This starts:

• Redis database with test data
• Frontend development server with hot reloading on http://localhost:3000
• FastAPI backend with auto-reload on http://localhost:7999

Development Commands

Code Quality

make format    # Format Python (ruff) and TypeScript (prettier) code
make lint      # Run linting checks

Testing

make test      # Run all tests (Python pytest + Jest)
make cov       # Run tests with coverage reports

API Development

make dev-api   # Start API server with hot reloading
make code-gen  # Generate TypeScript API client from OpenAPI spec

Project Structure

• conf/ - Configuration files for backend and ML training
• src/ - Source code directory
  • app/ - Next.js frontend application
  • api/ - FastAPI backend with routers and services
  • components/ - React components for frontend
  • ml/ - Machine learning models and training scripts
  • utils/ - Frontend Utility functions, hooks, and types
• tests/ - Test files for both frontend and backend
• docker/ - Docker configuration files
• models/ - Trained ML models storage
• data/ - Redis data persistence