Automate Media Quality Checks for Plex
A Plex library with thousands of files inevitably contains quality problems — corrupt files, truncated downloads, wrong codecs, missing audio tracks, absent subtitles, or files that do not match their reported quality. Manual checking is impossible at scale. Automated quality validation scans your entire library, identifies problems, and optionally fixes them. This guide covers the tools and scripts for automated media quality assurance.
Types of Quality Problems
Media files can fail in several ways:
- Corruption: Damaged data that causes playback errors, visual artifacts, or crashes. Often caused by incomplete downloads, disk errors, or failed transfers.
- Truncation: Files that end prematurely — the download completed but the file is shorter than expected.
- Wrong codec: Files encoded in codecs that some Plex clients cannot direct play, forcing server transcoding.
- Missing tracks: No audio track, missing subtitle track, or only a foreign-language audio track without the expected primary language.
- Quality mismatch: Files labeled as 1080p that are actually upscaled 720p, or files with bitrates too low for their resolution.
Tdarr Health Checks
Tdarr is primarily a media conversion tool, but its health check plugins are equally valuable for quality validation without conversion.
How Health Checks Work
Tdarr scans your library directories and runs each file through a chain of plugins. Health check plugins examine file properties and flag issues without modifying the file. Failed files are reported in the Tdarr dashboard for review.
Useful Health Check Plugins
- File integrity check: Runs FFmpeg decode on the file to detect corruption. If FFmpeg encounters errors during decode, the file is flagged.
- Duration validation: Compares the file duration against expected values. Catches truncated files.
- Codec validation: Checks that video and audio codecs match your requirements. Flags files with incompatible codecs.
- Resolution validation: Verifies the actual video resolution matches the expected quality level. Catches mislabeled files.
- Audio track check: Verifies the presence of required audio tracks (English audio, AAC fallback track, etc.).
Setting Up Tdarr for Health Checks
- Install Tdarr (Docker or native) and point it at your Plex library directories.
- Create a library in Tdarr and add your media paths.
- Configure a plugin stack with health check plugins only (no conversion plugins).
- Run the initial scan. Tdarr catalogs every file and runs it through the health check chain.
- Review the results in the Tdarr dashboard. Files that fail any check appear in the error queue.
FFprobe Scripting
FFprobe (included with FFmpeg) extracts detailed information about media files in a machine-readable format. It is the foundation for custom quality validation scripts.
Basic FFprobe Commands
Get complete file information in JSON format:
ffprobe -v quiet -print_format json -show_format -show_streams input.mkv
This returns detailed data about every stream in the file: codec, resolution, bitrate, duration, language tags, and more.
Building a Validation Script
A quality validation script walks your library directory, runs FFprobe on each file, and checks the results against your requirements:
- Scan for all media files in the library directories.
- Run FFprobe on each file to extract stream information.
- Check video codec, resolution, and bitrate against minimum thresholds.
- Check audio tracks for required languages and codecs.
- Check subtitle tracks for required languages.
- Log failures with the specific problem and file path.
- Generate a summary report with total files scanned, passed, and failed.
Common Validation Rules
- Minimum bitrate: Flag files with video bitrate below a threshold relative to their resolution. A 1080p file at 1 Mbps is likely poor quality.
- Required audio: Every file must have at least one audio track in the library's primary language.
- Codec allowlist: Only allow specific video codecs (H.264, HEVC, AV1) and flag others for conversion.
- Container check: Flag non-MKV containers that may have compatibility issues.
Corrupt File Detection
FFmpeg Decode Test
The most reliable corruption test is a full decode pass through FFmpeg:
ffmpeg -v error -i input.mkv -f null -
This decodes the entire file without writing output. Any decoding errors are printed to stderr. A clean file produces no output. A corrupt file produces error messages identifying the type and location of corruption.
Partial Decode
Full decode tests are slow for large files. For faster scanning, decode only the first and last few minutes of each file — corruption is most common at the beginning (bad headers) and end (truncated downloads).
Automated Corruption Scanning
Schedule a corruption scan to run weekly during off-peak hours. The script should:
- Scan all files in the library.
- Run the FFmpeg decode test on each file.
- Log any files with errors.
- Optionally send a notification with the results.
Audio Track Verification
Verify that every file has the audio tracks your users expect:
- Primary language: Every file should have an audio track in the library's primary language (usually English).
- Compatible codec: At least one audio track should be in a universally compatible codec (AAC or EAC3) for clients that cannot decode lossless audio.
- Channel count: Flag files with only stereo audio when surround is expected (or vice versa).
Subtitle Verification
Check subtitle availability for each file:
- Verify at least one subtitle track exists in the preferred language.
- Check subtitle format — SRT preferred over PGS (image-based subtitles force video transcoding).
- Cross-reference with Bazarr to identify files where subtitle downloads failed.
Reporting
Summary Reports
Generate weekly quality reports that include:
- Total files scanned and percentage passing all checks.
- Files with corruption errors (highest priority for replacement).
- Files with missing audio or subtitle tracks.
- Files with codecs that frequently trigger transcoding.
- Storage usage by quality level.
Integration With Monitoring
Send quality scan results to your monitoring stack. Tautulli can display custom scripts' output. Discord or Slack webhooks provide real-time notifications for critical failures like newly detected corruption.
Troubleshooting
False Positive Corruption
- Some files produce FFmpeg warnings that are not actual corruption — minor header issues or non-standard but playable formats. Filter out known benign warnings in your scripts.
- Test flagged files by playing them in Plex or VLC before deleting. Automated tests can be overly sensitive.
Scans Are Too Slow
- Use partial decode (first and last 2 minutes) instead of full decode for initial screening.
- Run scans in parallel across multiple CPU cores.
- Skip files that have not changed since the last scan by checking modification timestamps.