ttlequals0/pixelprobe repository overview

⁠PixelProbe

Find corrupted media files before they ruin your day. PixelProbe scans video, image, and audio libraries using FFmpeg, ImageMagick, and PIL, then shows you exactly what's broken.

⁠What it does

• Scans video files (MP4, MKV, AVI, MOV, ProRes, MXF, and more) with FFmpeg deep analysis
• Validates images (JPEG, PNG, TIFF, WebP, HEIC, plus RAW formats from Canon, Nikon, Sony, Fujifilm, etc.)
• Checks audio files (MP3, FLAC, WAV, AAC, DSD, Dolby/DTS)
• 92 file formats total across video, image, and audio
• Tested with libraries of 1M+ files and individual files over 50GB

⁠What you get

• Web UI with dark/light themes, mobile support, and in-browser media preview
• Scheduled scans via cron expressions or simple intervals
• Parallel scanning with configurable worker threads (10-24 recommended)
• Real-time progress tracking with ETA
• REST API with OpenAPI/Swagger docs
• Multi-user auth with role-based access and API tokens
• Trend analytics, PDF/JSON exports, and audit logging
• Healthcheck.io integration for monitoring

⁠Quick start

Create a .env file:

SECRET_KEY=generate-a-long-random-string-here
MEDIA_PATH=/path/to/your/media

Create a docker-compose.yml:

services:
  postgres:
    image: postgres:15-alpine
    environment:
      POSTGRES_DB: pixelprobe
      POSTGRES_USER: pixelprobe
      POSTGRES_PASSWORD: changeme
    volumes:
      - postgres_data:/var/lib/postgresql/data

  redis:
    image: redis:7-alpine

  pixelprobe:
    image: ttlequals0/pixelprobe:latest
    environment:
      SECRET_KEY: ${SECRET_KEY}
      POSTGRES_HOST: postgres
      POSTGRES_PASSWORD: changeme
      CELERY_BROKER_URL: redis://redis:6379/0
      CELERY_RESULT_BACKEND: redis://redis:6379/0
      SCAN_PATHS: /media
      MAX_WORKERS: 10
    volumes:
      - ${MEDIA_PATH}:/media:ro
    ports:
      - "5000:5000"
    depends_on:
      - postgres
      - redis

  celery-worker:
    image: ttlequals0/pixelprobe:latest
    command: python celery_worker.py
    environment:
      SECRET_KEY: ${SECRET_KEY}
      POSTGRES_HOST: postgres
      POSTGRES_PASSWORD: changeme
      CELERY_BROKER_URL: redis://redis:6379/0
      CELERY_RESULT_BACKEND: redis://redis:6379/0
      SCAN_PATHS: /media
      MAX_WORKERS: 10
    volumes:
      - ${MEDIA_PATH}:/media:ro
    depends_on:
      - postgres
      - redis

volumes:
  postgres_data:

Then:

docker-compose up -d

Open http://localhost:5000⁠ and create your admin account through the first-run setup wizard.

⁠Architecture

Four containers, each with a single job:

The app and worker share the same image. The worker runs python celery_worker.py instead of Gunicorn.

⁠Environment variables

Required:

Tuning:

Scheduling:

Filtering:

Other:

⁠Multiple media directories

Mount each directory separately and list them in SCAN_PATHS:

environment:
  SCAN_PATHS: /movies,/tv-shows,/music
volumes:
  - /mnt/movies:/movies:ro
  - /mnt/tv-shows:/tv-shows:ro
  - /mnt/music:/music:ro

⁠User permissions

The app and celery-worker containers must run as the same user, and that user needs read access to your media files. Add this to both services:

user: "1000:1000"  # Match your host user's UID:GID

⁠Links

• GitHub⁠
• Documentation⁠
• API Reference⁠
• Docker Setup Guide⁠
• Configuration Guide⁠
• Changelog⁠

⁠License

MIT