Media Viewer

A lightweight, containerized, single-user web application for browsing and viewing images and videos from a mounted directory.

Screenshots

Desktop Experience

Gallery browsing, lightbox viewer, and favorites

Full-text search with tag filtering

Mobile Experience

Responsive mobile interface with selection mode and bulk operations

Biometric authentication with passkeys (WebAuthn)

Features

• Browse folders and files with thumbnail previews
• Lightbox viewer with swipe/keyboard navigation
• Windows Media Player playlist support (.wpl)
• Automatic video transcoding with optional GPU acceleration (NVIDIA/Intel/AMD)
• Full-text fuzzy search with tag support
• Tag files for organization
• Pin favorites to the home page
• Passkey (WebAuthn) authentication with biometric support
• Progressive Web App (PWA) for mobile
• Prometheus metrics for monitoring

Documentation

Full documentation is available at: https://djryanj.github.io/media-viewer/

• Quick Start Guide
• Installation
• Configuration
• User Guide
• API Documentation
• Development Guide
• Performance Profiling
• Monitoring & Performance Testing

AI Disclosure

See: AI.md.

Quick Start

Docker Compose (Recommended)

Create a docker-compose.yml file:

version: '3.8'

services:
    media-viewer:
        image: ghcr.io/djryanj/media-viewer:latest # Use :latest-nvidia for NVIDIA GPUs
        ports:
            - '8080:8080'
            - '9090:9090'
        volumes:
            - /path/to/your/media:/media:ro
            - media-cache:/cache
            - media-database:/database
        environment:
            - MEDIA_DIR=/media
            - CACHE_DIR=/cache
            - DATABASE_DIR=/database
            - PORT=8080
            - METRICS_PORT=9090
            - METRICS_ENABLED=true
            - INDEX_INTERVAL=30m
            - MEMORY_RATIO=0.75 # Recommended: Adaptive GC with 0.16% CPU overhead
            # - GOGC=150  # Alternative for non-containerized deployments
            # - GPU_ACCEL=auto  # Optional: auto (default), nvidia, vaapi, videotoolbox, or none
            # - INDEX_WORKERS=3  # Optional: Set to 3 for NFS mounts, 8-16 for fast local storage
            # - TRANSCODER_LOG_DIR=/logs/transcoder  # Optional: Enable to save FFmpeg logs
        restart: unless-stopped

volumes:
    media-cache:
    media-database:

Update /path/to/your/media to point to your media directory, then start:

docker-compose up -d

Open http://localhost:8080 in your browser. On first run, you'll be prompted to create a user account.

Docker CLI

docker run -d \
  --name media-viewer \
  -p 8080:8080 \
  -v /path/to/your/media:/media:ro \
  -v media-cache:/cache \
  -v media-database:/database \
  ghcr.io/djryanj/media-viewer:latest

Supported Formats

Images: jpg, jpeg, png, gif, bmp, webp, svg, ico, tiff, heic, heif, avif, jxl, raw, cr2, nef, arw, dng

Videos: mp4, mkv, avi, mov, wmv, flv, webm, m4v, mpeg, mpg, 3gp, ts (automatic transcoding for browser compatibility)

Playlists: Windows Media Player (.wpl)

Installation

Pull from GitHub Container Registry:

# Standard Alpine-based image (VA-API support for Intel/AMD GPUs)
docker pull ghcr.io/djryanj/media-viewer:latest

# NVIDIA-optimized Debian-based image (NVIDIA NVENC support)
docker pull ghcr.io/djryanj/media-viewer:latest-nvidia

Image Flavors

Two image variants are available:

Standard Image (Alpine)

• Supports Intel/AMD GPU acceleration (VA-API) on amd64
• Smaller image size (~150MB)
• Use for Intel Quick Sync, AMD GPUs, or CPU-only transcoding
• Does not support NVIDIA GPUs

NVIDIA Image (Debian)

• Supports NVIDIA GPU acceleration (NVENC)
• Debian-based for glibc compatibility with NVIDIA drivers
• Larger image size (~300MB)
• Use for NVIDIA GPUs only
• Does not support Intel/AMD VA-API

See GPU Support Documentation for details.

Available Tags

Tag	Description
latest	Latest stable release (Alpine-based)
latest-nvidia	Latest stable release (NVIDIA-optimized)
v1.0.0	Specific version (Alpine-based)
v1.0.0-nvidia	Specific version (NVIDIA-optimized)
v1.0	Latest patch version of 1.0.x
v1.0-nvidia	Latest patch of 1.0.x (NVIDIA)
sha-abc1234	Specific commit build

Build from Source

git clone https://github.com/djryanj/media-viewer.git
cd media-viewer
make setup
make build
./media-viewer

See the Development Guide for details.

License

MIT License