Media Scanning

Luminarr uses ffprobe to inspect the actual video stream in each file, going beyond filename-based quality detection to verify codec, resolution, and HDR metadata directly from the container.

Overview

What the scanner does

Release names can lie. A file named Movie.2160p.BluRay.x265 might actually be a 1080p upscale encoded with x264. The media scanner eliminates this ambiguity by reading the actual video stream metadata from the file.

Video codec

Reads the codec ID directly from the container: hevc, avc, av1, vp9, etc.

Resolution

Reads the actual encoded width and height. Detects upscales that claim 4K but have native 1080p content.

HDR format

Reads color_transfer and side data to distinguish HDR10, Dolby Vision, HLG, and HDR10+.

Data Collected

What gets scanned

For each movie file, ffprobe extracts the following fields and stores them in the database. These values power the {MediaInfo ...} naming tokens and inform upgrade decisions.

Field	Example values	Used for
Video codec	`hevc`, `avc`, `av1`	Naming token, upgrade scoring
Resolution	3840×2160, 1920×1080	Quality confirmation, naming
HDR format	HDR10, Dolby Vision, HLG, HDR10+	HDR flag on quality profile
Bit depth	8-bit, 10-bit	Informational display
Color space	bt709, bt2020nc	HDR detection support
Audio codec	dts, eac3, aac, truehd	Informational display on movie detail

Requirements

Setup

Media scanning requires ffprobe (part of the FFmpeg suite) to be available on the system PATH. Luminarr detects it automatically at startup.

Docker users: FFmpeg is included in the official Luminarr Docker image. No additional setup is needed.

Installing FFmpeg

            Linux (Debian / Ubuntu)
          
sudo apt update && sudo apt install -y ffmpeg

            macOS (Homebrew)
          
brew install ffmpeg

            Docker (already included)
          
# No action needed — ffprobe is bundled in the luminarr/luminarr image
docker pull ghcr.io/luminarr/luminarr:latest

After installing, restart Luminarr. The System page will show ffprobe available in the status panel once it is detected.

Usage

Using the scanner

The scanner runs automatically on each file at import time when ffprobe is available. For files already in your library, you can trigger a scan manually.

The movie detail page shows a scan status indicator next to each file entry: Scanned or Not scanned.
Click Scan on an individual file to run ffprobe on that file immediately.
Use the Scan All button in Settings → Media Scanning to queue a full library scan — files are processed in the background without blocking the UI.

Scanning large libraries can take several minutes. Each file requires a brief ffprobe invocation. Progress is visible on the System → Tasks panel while the scan is running.

After scanning

Once a file is scanned, its detected quality data overrides the filename-parsed values for display and upgrade decisions. If the scanned resolution differs from what the release name claimed, Luminarr updates the file's stored quality accordingly.