The Modern Media Health & Sync Manager for Plex, Emby, and Jellyfin.
Omniscan bridges the gap between your media files and your media server. It monitors your filesystem for changes, validates file integrity, and triggers targeted library scans only when necessary.
- 🕸️ Modern Web Dashboard: A beautiful, responsive UI to monitor your media health in real-time.
- 🏥 Health & Integrity Check: Detects corrupt files, 0-byte placeholders, and incomplete downloads before they ruin movie night.
- ⚡ Smart Webhook Triggers: Seamless integration with Sonarr and Radarr. It intelligently debounces hundreds of incoming requests into efficient, sequential scans.
- 📁 File Browser: Explore your mounted media folders and trigger manual scans for specific directories directly from the UI.
- 📜 Live Logs: Watch real-time logs via WebSocket (with polling fallback) to debug issues instantly.
- 🔔 Discord Notifications: Get beautiful summary reports of added, deleted, and corrupt content.
- 🐳 Docker Ready: Built for containerized environments.
- Create a
docker-compose.ymlfile:
version: "3.8"
services:
omniscan:
image: ghcr.io/drondeseries/omniscan:latest
container_name: omniscan
restart: unless-stopped
ports:
- "8085:8000"
environment:
- PUID=1000
- PGID=1000
- TZ=America/New_York
volumes:
- ./config:/app/config
- /mnt/media:/media:ro # Mount your media read-only-
Start the container:
docker-compose up -d
-
Access the Dashboard: Open
http://<your-ip>:8085in your browser. Default login:admin/ (password generated in logs on first run).
- Clone the repo:
git clone https://github.com/drondeseries/omniscan.git cd omniscan - Install dependencies:
pip install -r requirements.txt
- Run the application:
python omniscan.py
You can configure everything directly from the Web UI > Settings tab.
- Plex: Enter your Plex URL (e.g.,
http://192.168.1.50:32400) and Token. - Emby/Jellyfin: Select your server type, enter the URL and API Key.
- Scan Paths: The local paths inside the container (e.g.,
/media/movies) that Omniscan should watch. - Debounce: Time (in seconds) to wait for file operations to settle before triggering a scan (default: 10s).
- Workers: Number of parallel threads for file hashing and verification.
Omniscan creates a unified webhook endpoint to handle high-volume imports from Sonarr, Radarr, or Autoscan without crashing your server.
Endpoint: POST http://<omniscan-ip>:8085/api/webhook
- Go to Settings > Connect.
- Click + and choose Webhook.
- Name: Omniscan
- Webhook URL:
http://<your-omniscan-ip>:8085/api/webhook - Method: POST
- Triggers: Check
On Download,On Upgrade,On Rename. - Save.
Omniscan automatically parses payloads from common tools. You can also send a generic request:
{
"path": "/media/movies/Avatar (2009)"
}The Live Logs tab connects via WebSocket. If you are behind a reverse proxy (Nginx/Cloudflare) and WebSockets fail, Omniscan automatically falls back to HTTP polling.
If a file is marked Corrupt, it usually means:
- The file size is 0 bytes.
- The file header/footer is missing (incomplete download).
ffprobefailed to read metadata.
Click on the Corrupt box in the Dashboard to see a filtered history of failed files.
We welcome contributions! Please open an issue or submit a PR.
- Fork the Project
- Create your Feature Branch (
git checkout -b feature/AmazingFeature) - Commit your Changes (
git commit -m 'Add some AmazingFeature') - Push to the Branch (
git push origin feature/AmazingFeature) - Open a Pull Request
Distributed under the MIT License. See LICENSE for more information.
- Pukabyte/rescan - The original project that inspired the logic for missing file detection.
- PlexAPI - Powering the deep integration with Plex servers.
- FastAPI - The high-performance framework behind the Web UI.
- Chart.js - For the beautiful health visualization charts.
- Tailwind CSS - For the modern, responsive dashboard design.