frederikikemmer/MediaLyze: Self-Hosted Media Analysis with ffprobe

frederikemmer/MediaLyze: Self-Hosted Media Analysis with ffprobe

Managing large self-hosted media libraries creates a visibility problem. You have terabytes of video files across multiple storage systems—local NAS, SMB shares, Docker^{↗ Bright Coding Blog} volumes—but no systematic way to understand what's actually in your collection. Technical metadata like codec distribution, bitrate patterns, subtitle coverage, and quality metrics remain buried inside individual files. Developers and media server operators need read-only analysis tools that respect existing infrastructure without demanding cloud dependencies or write access to precious archives. MediaLyze, an open-source project by Frederik Emmer, addresses this gap directly.

What is frederikemmer/MediaLyze?

MediaLyze is a self-hosted media library analysis platform designed specifically for large video collections. Built around ffprobe—the metadata extraction utility from the FFmpeg project—it scans libraries and surfaces technical metadata through a FastAPI-powered backend and React^{↗ Bright Coding Blog}-based web interface. The project is actively maintained, with its most recent commit dated July 11, 2026, and has accumulated 460 GitHub stars alongside 11 forks.

The tool occupies a specific niche in the self-hosted tooling ecosystem: read-only technical analysis without playback, scraping, or file modification capabilities. This design choice matters for operators who need inventory visibility but cannot risk any tool touching file contents or metadata. MediaLyze is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0), reflecting its open-source commitment and copyleft protections.

Frederik Emmer distributes MediaLyze through multiple deployment paths: a single-container Docker deployment with SQLite, native desktop applications packaged via Electron for Windows, macOS, and Linux, and a local development stack. This flexibility distinguishes it from tools that force either server-only or desktop-only workflows. The project has received external recognition from selfh.st and the YouTube channel ServersatHome, indicating growing awareness in the self-hosting community.

Key Features

ffprobe-Powered Analysis Engine: At its core, MediaLyze leverages ffprobe to extract comprehensive technical metadata from video files. This includes codec information, stream details, subtitle tracks, and quality-relevant metrics. Using ffprobe rather than custom parsers ensures compatibility with virtually all common media formats while benefiting from FFmpeg's extensive maintenance and format support.

Incremental Scanning with Change Detection: The scanner uses path + size + mtime for incremental scans, avoiding full re-scans of unchanged files. This optimization proves essential for large collections where complete rescans would consume excessive I/O and time.

Historical Analysis and Visualization: MediaLyze tracks metrics over time and presents them through multiple chart types. The dashboard supports historical views, enabling operators to observe trends like codec migration, bitrate changes, or collection growth patterns.

Normalized Data Model: The system normalizes formats, streams, subtitles, scan jobs, and quality scores into a consistent schema. This normalization enables reliable filtering, comparison, and reporting across heterogeneous source material.

Content Recognition: Beyond flat file lists, MediaLyze recognizes shows, seasons, and bonus content structures. This semantic layer transforms raw file inventories into organized library views that match how users actually think about their collections.

Flexible Ignore Patterns: Glob-based ignore rules—such as *.nfo or */Extras/*—filter out non-media files and directories. Built-in defaults cover common system files (.DS_Store, @eaDir, .deletedByTMM, *.part), with an option to disable these defaults via environment variable.

Multi-Platform Desktop Packaging: Electron-based desktop builds provide native applications for macOS Apple Silicon (.dmg), Linux (.AppImage), and Windows (.exe). These run the identical FastAPI + React stack locally, with direct filesystem and network path access including Windows UNC paths.

Configurable Scan Performance: The UI exposes separate limits for per-scan analysis workers and parallel library scans, allowing throughput tuning without configuration file edits.

Use Cases

NAS and Media Server Auditing: Self-hosting operators running Plex, Jellyfin, or Emby often lack visibility into codec uniformity across their libraries. MediaLyze provides the technical inventory to identify which files need transcoding optimization, which lack subtitle tracks, or which use outdated codecs—without modifying anything.

Pre-Migration Assessment: Before moving terabytes between storage systems or re-encoding collections, administrators need accurate technical profiles. MediaLyze's historical tracking and comparison views support data-driven migration planning.

Quality Consistency Monitoring: Collections accumulated over years typically show codec drift—H.264 alongside H.265, varying bitrates, inconsistent audio formats. MediaLyze surfaces these patterns through its charting system, enabling targeted normalization decisions.

Remote Library Inspection: The Docker deployment model allows technical stakeholders to assess media collections without direct filesystem access. Mounting media read-only into the container maintains security boundaries while providing full analytical visibility.

Desktop-First Small Collections: For users with single-workstation collections or SMB-mounted shares, the desktop application eliminates server infrastructure. Direct folder selection and scheduled scans (with watch mode for local paths) provide lightweight automation.

Installation & Setup

Docker Compose Deployment

MediaLyze provides a production-ready Docker Compose configuration. Create your environment and deploy:

# Copy example environment file
cp docker/env.example .env

# Start with production compose
docker compose -f docker-compose.yaml up -d

The compose file structure:

services:
  medialyze:
    image: ghcr.io/frederikemmer/medialyze:latest
    container_name: medialyze
    ports:
      - "${HOST_PORT:-8080}:8080"
    environment:
      TZ: UTC
    volumes:
      - ./config:/config
      - ./media:/media:ro

Key volume mounts: ./config persists application data and SQLite database; ./media:/media:ro mounts your media read-only. The ro flag is intentional and recommended—MediaLyze requires no write access to analyze files. Access the application at http://localhost:8080 or your configured HOST_PORT.

For environments needing .env support, extend with docker-compose-ENV.yaml and reference docker/env.example for available variables.

Desktop Installation

Download platform-specific releases directly:

Desktop behavior differs from server mode: local folders are selected through OS dialogs, mounted NAS/SMB paths are accessible (including Windows UNC paths like \\server\share\videos), and watch mode operates only on local paths with network locations falling back to scheduled scans.

Local Development

For contributors or customizers, the development stack uses separate backend and frontend processes:

# Backend setup
python3 -m venv .venv
source .venv/bin/activate
pip install -e .[dev]
uvicorn backend.app.main:app --reload --port 8080

# Frontend setup
cd frontend
npm install
npm run dev

The Vite dev server proxies /api to http://127.0.0.1:8080. Combined startup scripts handle coordination:

# macOS/Linux
./scripts/dev-local.sh

# Windows PowerShell
.\scripts\dev-local.ps1

These scripts expect .venv with dependencies installed, frontend/node_modules populated, and a valid MEDIA_ROOT directory (defaulting to Desktop if unset).

Real Code Examples

MediaLyze's documentation emphasizes operational configuration over API code samples. The following examples reflect the actual documented interfaces.

Docker Compose with Custom Media Paths

The standard compose supports multiple media mounts through pattern extension:

services:
  medialyze:
    image: ghcr.io/frederikemmer/medialyze:latest
    container_name: medialyze
    ports:
      - "${HOST_PORT:-8080}:8080"
    environment:
      TZ: UTC
    volumes:
      - ./config:/config
      - ./media:/media:ro
      # Extended pattern for additional libraries
      - /PATH/TO/MEDIA0:/media/MEDIA0:ro
      - /PATH/TO/MEDIA1:/media/MEDIA1:ro

This pattern enables unified analysis across physically separated storage without requiring merged filesystem views on the host.

Environment-Based Configuration

The docker-compose-ENV.yaml variant loads variables from .env:

# .env contents
HOST_PORT=9090
PUID=1000
PGID=1000
TZ=Europe/Berlin

Setting PUID and PGID together ensures the container runtime matches host ownership for shared-folder scenarios. Both must be set or both left unset—partial configuration maintains default root runtime.

Development Server Startup

The backend development^{↗ Bright Coding Blog} server with auto-reload:

uvicorn backend.app.main:app --reload --port 8080

The --reload flag enables automatic restart on code changes during development. Production deployments should omit this, using the containerized path instead.

Desktop Build Pipeline

For packaging native applications:

# Prepare backend environment
python3 -m venv .venv
source .venv/bin/activate
pip install -e .[dev]

# Build frontend assets
cd frontend
npm install
npm run build

# Package desktop application
cd ../desktop
npm install
npm run dev

Local desktop development requires ffprobe in PATH; packaged builds bundle the binary. See docs/build_desktop.md for complete packaging instructions.

Advanced Usage & Best Practices

Read-Only Mount Enforcement: Always mount media volumes with :ro in production. MediaLyze's design guarantees no file modification, but explicit read-only mounts provide defense in depth against container misconfiguration.

Reverse Proxy TLS Termination: The container serves plain HTTP internally. Expose to networks only through reverse proxies (nginx, Traefik, Caddy) that handle TLS termination. The documentation explicitly notes this expectation rather than bundling certificate management.

SMB/NAS Architecture: For network-attached storage, mount shares on the Docker host first, then bind-mount the host path into the container. This avoids SMB client complexity inside the container and leverages host-level caching and authentication. Desktop applications can select these paths directly.

Ignore Pattern Optimization: Review built-in ignore defaults against your collection structure. The DISABLE_DEFAULT_IGNORE_PATTERNS=true environment variable provides escape hatching, but most users benefit from the preloaded patterns. Custom globs should target normalized relative paths within each library root.

Scan Worker Tuning: The UI-based scan performance controls allow empirical optimization. Start conservative with worker counts, monitor system I/O saturation, and increase parallelism gradually. Separate limits for analysis workers and parallel library scans prevent resource contention between deep file inspection and broad library enumeration.

Telemetry Considerations: MediaLyze includes opt-in telemetry with documented payload contracts in docs/telemetry.md. The MEDIALYZE_TELEMETRY_DISABLED=true environment variable forces telemetry off and locks the UI toggle, useful for privacy-sensitive deployments. The default ingest endpoint can be overridden via MEDIALYZE_TELEMETRY_ENDPOINT.

Comparison with Alternatives

Tautulli serves Plex operators specifically, tracking playback and user behavior rather than file technical metadata. Bazarr actively modifies libraries by downloading subtitles, placing it in a different operational category. MediaInfo provides similar ffprobe-adjacent metadata extraction but lacks MediaLyze's library management, historical tracking, and web interface. MediaLyze's distinctive position combines read-only safety, self-contained deployment, and collection-scale analysis with trend visualization.

FAQ

Does MediaLyze modify my media files? No. The tool is explicitly read-only and designed to never write to analyzed files or directories.

What media formats are supported? Any format ffprobe can parse, which covers virtually all common video containers and codecs.

Can I run this on ARM64? Desktop builds include macOS Apple Silicon. Docker deployments should verify ffprobe binary availability for target architectures.

How does licensing affect commercial use? AGPL-3.0 requires source disclosure for network use. Review the license terms for your deployment context.

Is authentication built in? The README notes "bring your own auth (for now)," indicating current reliance on external authentication layers like reverse proxy auth.

Can I analyze multiple separate media locations? Yes. Extend the Docker Compose volume mounts or select multiple folders in the desktop application.

What happens if ffprobe encounters a corrupt file? The scanner handles individual file failures gracefully; corrupt files are logged and skipped without halting the scan job.

Conclusion

MediaLyze fills a precise need in self-hosted infrastructure: technical visibility into large media collections without operational risk. Its read-only design, ffprobe-based analysis engine, and flexible deployment options—single-container Docker or cross-platform desktop applications—make it suitable for operators who prioritize data safety and infrastructure simplicity over feature breadth. The 460-star project under active development by Frederik Emmer offers particular value to NAS administrators, media server operators, and quality-conscious collectors who need systematic metadata analysis without cloud dependencies or file modification capabilities.

For developers interested in contributing, the project welcomes pull requests with guidelines in CONTRIBUTING.md. The AGPL-3.0 license ensures derivative work remains open. Explore the repository, download a release, or deploy via Docker to assess how MediaLyze fits your media infrastructure needs.

Get started: https://github.com/frederikemmer/MediaLyze