MediaLyze tackles a common pain point for anyone managing large personal video collections: how to keep track of detailed metadata and quality insights without re-scanning unchanged files over and over. Its incremental scanning strategy based on path, file size, and modification time hashing is a smart way to avoid redundant analysis, saving time and CPU cycles. Under the hood, it uses ffprobe to extract metadata, but wraps this in a consistent, normalized view accessible via a modern web UI or desktop app.
What MediaLyze does and how it’s built
MediaLyze is a read-only media library analyzer designed specifically for video collections. It scans media files using ffprobe, extracting technical metadata across formats, streams, and subtitles. Rather than focusing on playback or scraping external metadata, it concentrates on giving users clear insights into the media’s technical properties and quality.
The backend is built with FastAPI (Python), providing a RESTful API that serves normalized metadata and quality scores. On the frontend, a React (TypeScript) app offers an interactive web UI with charts and detailed views. For persistence, MediaLyze uses SQLite, which fits well given the read-only, local usage context.
Deployment options include a Docker container with a production-ready docker-compose setup, and native desktop apps packaged with Electron for Windows, macOS, and Linux. The desktop apps can scan local folders directly or mounted network shares, with some limitations on watch mode for network paths.
MediaLyze deliberately avoids playback, editing, or scraping external metadata sources, focusing purely on analysis and visibility. This makes it a specialized tool complementary to media servers or player apps.
Incremental scanning with path, size, and mtime tracking
The standout technical detail is MediaLyze’s incremental scanning mechanism. Instead of blindly reprocessing every file on each scan, it tracks files by a hash composed of their path, size, and modification time (mtime). This means unchanged files are skipped, which is a big win for large media libraries.
This approach is simple but effective. Using path+size+mtime covers most common changes: if a file is moved, its path changes and it gets rescanned; if it’s edited or replaced, size or mtime changes trigger a reanalysis.
The tradeoff is with edge cases where container format changes might not affect size or mtime (e.g., metadata edits inside a file without touching size or mtime). In those rare cases, MediaLyze might miss the update until a manual rescan or database reset.
The code uses APScheduler and watchdog to schedule scans and optionally watch folders for changes, improving the freshness of metadata without constant full rescans.
The metadata normalization across formats and streams is another strength. ffprobe outputs can be verbose and inconsistent across container types. MediaLyze consolidates this into a consistent schema, making the UI and quality scores meaningful and comparable.
How to get started with MediaLyze
MediaLyze provides a production-ready Docker Compose setup for quick deployment. Here is the exact snippet from the README:
services:
medialyze:
image: ghcr.io/frederikemmer/medialyze:latest
container_name: medialyze
ports:
- 8080:8080
environment:
# change to your timezone, e.g. "Europe/Berlin" or "America/New_York"
TZ: UTC
volumes:
- ./config:/config
# use .env or change "./media" to the path of your media directory
- ./media:/media:ro
# additional media mounts, if needed. Extend this pattern if needed:
# /PATH/TO/MEDIA1:/media/MEDIA1:ro
You can extend this with a .env file using docker-compose-ENV.yaml and env.example for environment configuration.
After running the container, open http://localhost:8080 in your browser to access the web UI.
For desktop users, prebuilt Electron apps are available for Windows (.exe), macOS (.dmg), and Linux (AppImage). These run the same FastAPI + React stack locally with a local SQLite database and require ffprobe installed.
The desktop app allows selecting local folders or mounted network shares, with watch mode limited to local paths for real-time updates.
Verdict: who should consider MediaLyze
MediaLyze is a solid choice for enthusiasts or media hoarders who want a detailed, read-only analysis of their video collections. Its incremental scanning makes it practical for large libraries, avoiding repeated heavy ffprobe calls.
The tradeoff is the limited scope: it does not handle playback, metadata scraping from online sources, or file modifications. If you need a full media server experience, this won’t replace Plex, Emby, or Jellyfin. But as a complementary tool focused strictly on technical insight and quality scoring, it’s well executed.
The codebase is clean and the architecture sensible, relying on proven tools like FastAPI, React, SQLite, and ffprobe. The Docker and Electron deployment options offer flexibility for both server and desktop setups.
If you manage large video collections and want a transparent, no-nonsense way to understand their technical state and quality, MediaLyze is worth a look. Just keep in mind the edge cases where container metadata can change without file size or mtime updates, which might require manual intervention.
→ GitHub Repo: frederikemmer/MediaLyze ⭐ 365 · Python