plex-media-doctor

Scan your media library for corrupt files, low quality media, missing subtitles, and files that will transcode on specific devices — all in one command.

python3 plex_doctor.py --source /path/to/media

Works on raw files. No Plex API needed, no Docker, no Plex even running. Just ffprobe and Python.

---

The problem it solves

You have hundreds (or thousands) of media files. Right now you have no idea:

• Are any files corrupt? — you find out mid-movie when playback freezes
• What quality is everything? — which files are still 720p or have garbage bitrates?
• Will it transcode? — your Roku can't play DTS audio, so every DTS file triggers a CPU-melting transcode you don't notice until buffering starts
• Which files are missing subtitles? — you don't know until your parents are watching a film with mumbled dialogue at midnight

This script answers all four questions in one pass.

---

Features

• Corrupt file detection — runs ffprobe error detection on every file; flags truncated, partially-downloaded, or unreadable media
• Resolution & codec breakdown — instant overview of your library: how many files at 4K, 1080p, 720p; which codecs (H.264, HEVC, etc.)
• Quality warnings — flags files below 720p or below 1.5 Mbps bitrate
• Subtitle coverage audit — checks for external subtitle files (.srt, .ass, .sub, .vtt) and embedded subtitle streams
• Device direct-play compatibility — 7 built-in device profiles tell you exactly which files will transcode and why
• CSV/JSON export — pipe the results into spreadsheets, scripts, or dashboards
• Progress indicator — see scan progress across large libraries
• Zero dependencies beyond ffprobe — pure Python standard library

---

Device profiles included

Device	Notes
Roku	No DTS audio support — high transcode rate for DTS files
Apple TV 4K	Best compatibility. DTS and TrueHD passthrough
Chromecast / Google TV	No DTS support
Amazon Fire TV Stick 4K	Supports DTS. Most content direct plays
NVIDIA Shield TV	Direct plays nearly everything
iPhone / iPad	No DTS audio support
Web Browser	No HEVC, no DTS, no AC3. Highest transcode rate

---

Install

# ffprobe is part of ffmpeg — you probably already have it
brew install ffmpeg     # macOS
sudo apt install ffmpeg # Linux

No pip install needed. Pure Python 3.8+ standard library.

---

Usage

Full health scan (all checks)

python3 plex_doctor.py --source /path/to/Movies

Check which files will transcode on your Roku

python3 plex_doctor.py --source /path/to/Movies --device roku

Check compatibility on multiple devices

python3 plex_doctor.py --source /path/to/Movies --device roku chromecast browser

Check against ALL devices

python3 plex_doctor.py --source /path/to/Movies --all-devices

Only check for corrupt files

python3 plex_doctor.py --source /path/to/Movies --check corrupt

Only check for missing subtitles

python3 plex_doctor.py --source /path/to/Movies --check subtitles

Run specific checks together

python3 plex_doctor.py --source /path/to/Movies --check corrupt quality

Export to CSV

python3 plex_doctor.py --source /path/to/Movies --csv report.csv

Opens in Excel, Google Sheets, etc. Great for sorting/filtering a large library.

Export to JSON

python3 plex_doctor.py --source /path/to/Movies --json > report.json

Combine everything

python3 plex_doctor.py \
  --source /mnt/media \
  --device roku appletv browser \
  --csv report.csv

---

Example output

Scanning 847 video file(s) in: /mnt/media/Movies

================================================================
  plex-media-doctor — Library Health Report
================================================================

  LIBRARY OVERVIEW
  Files : 847
  Size  : 4,218.3 GB
  Resolution breakdown:
       4K    142  ██████████████
    1080p    583  ██████████████████████████████████████████
     720p    104  ██████████
     480p     18  ██

  Video codecs:
      hevc    401
      h264    438
      mpeg4      8
  Audio codecs:
       aac    312
       ac3    245
       dts    189
      eac3     76
     flac     25

  CORRUPT FILES
    ❌ 3 corrupt file(s) found:
      ❌  The.Matrix.1999.mkv
          Invalid NAL unit size (2048 > 1422)
      ❌  Inception.2010.avi
          ffprobe timed out (possible severe corruption)
      ❌  old_movie_rip.mpg
          Invalid data found when processing input

  SUBTITLE COVERAGE
    With subtitles    : 612 (72%)
    Without subtitles : 235
    (Too many to list — 235 files. Use --json or --csv for full list.)

  QUALITY WARNINGS
    18 file(s) below 720p:
      ⚠️   old_documentary.avi  (640x480, mpeg4)
      ⚠️   home_video_2005.wmv  (320x240, wmv)
      ... and 16 more
    ✅ All files have healthy bitrates.

  DEVICE COMPATIBILITY

    Roku
      Direct Play : 658/847 (78%)
      Note: Roku does NOT support DTS audio — will transcode to AC3/AAC.
      ⚠️  Audio codec 'dts' not supported (needs transcode to AAC/AC3) (189 files)
          The.Dark.Knight.2008.mkv
          Interstellar.2014.mkv
          Dune.2021.mkv
          ... and 186 more

    Web Browser (Chrome/Firefox/Edge)
      Direct Play : 287/847 (34%)
      Note: No HEVC, no DTS, no AC3 in most browsers. High transcode rate.
      ⚠️  Video codec 'hevc' not supported (needs transcode to H.264/HEVC) (401 files)
      ⚠️  Audio codec 'dts' not supported (needs transcode to AAC/AC3) (189 files)
      ⚠️  Audio codec 'ac3' not supported (needs transcode to AAC/AC3) (245 files)

    Apple TV 4K
      Direct Play : 839/847 (99%)
      Note: Best compatibility. Supports DTS and TrueHD passthrough.
      ⚠️  Video codec 'mpeg4' not supported (needs transcode to H.264/HEVC) (8 files)

================================================================
VERDICT
  ⚠️  21 issue(s) found — see details above.
================================================================

---

All flags

Flag	Short	Default	Description
--source	-s	(required)	Path to your media library
--check	-c	all checks	Which checks: corrupt, quality, subtitles
--device	-d	none	Device profiles: roku, appletv, chromecast, firetv, browser, shield, ios
--all-devices		False	Check against all 7 device profiles
--json		False	Output full report as JSON
--csv		—	Export report to a CSV file
--no-colour		False	Disable coloured output

---

What each check does

Check	What it catches
corrupt	Truncated files, partially downloaded files, broken containers, unreadable streams
quality	Files below 720p resolution, files below 1.5 Mbps bitrate
subtitles	Files missing both external (.srt, .ass, etc.) and embedded subtitle streams

Device compatibility is a separate flag (--device) and runs independently of --check.

---

Supported file types

.mkv .mp4 .avi .mov .m4v .wmv .flv .ts .m2ts .mpg .mpeg .webm

---

Tips

• Scan your whole library periodically — new downloads can be corrupt, especially from automated tools
• DTS is the #1 transcode trigger — if most of your library transcodes on Roku/Chromecast, DTS audio is almost always the reason. Consider re-encoding audio to AC3
• CSV export + spreadsheet sorting — export to CSV, open in Excel/Sheets, sort by resolution or bitrate to find upgrade candidates
• Run before adding to Plex — catch corrupt files before they hit your library, not when someone hits play
• Pairs with media-library-renamer — fix naming with media-library-renamer, fix everything else with this tool

---

License

MIT — free to use, modify, and distribute.

---

Contributing

Issues and PRs welcome. If you have a device profile to add (LG WebOS TV, Samsung Tizen, Xbox, PlayStation, etc.), open a PR with the codec/container/resolution specs and I'll include it.