Library Doctor for Emby — guide

Installation

You need Emby Server 4.10.1 or newer.

1. Sign in to your MediaLab Works account, open Licenses and download the plugin DLL (available on an active subscription, a lifetime license within its update window, or during the free 30-day trial).
2. Copy the DLL into the Emby plugins folder and restart Emby Server:
   • Linux (package): /var/lib/emby/plugins/
   • Docker: the plugins folder inside your Emby config volume
   • Windows: %AppData%\Emby-Server\programdata\plugins\
3. Open Library Doctor in the Emby dashboard menu and click License. Paste your license key and activate it, or enter your e-mail to start the free 30-day trial or buy a license. The plugin contacts the license server, binds the key to this Emby server and shows the license as Active.

The license is checked once a day (and at every Emby start). Without internet the plugin keeps working for 7 days after the last successful check; after that it is stopped until it can check again.

License

Without a valid license the plugin is stopped: no report is shown, no file check runs and nothing can be moved or restored; only the License page keeps working (there you can start the trial, buy, enter the key or update). Nothing is deleted: the files in quarantine stay where they are and can be restored as soon as the license is valid again.

With a valid license, the same page can install an update or roll back to the previous version if an update causes trouble. Restart Emby after either.

Configuration

Open Library Doctor in the Emby dashboard menu (administrators only). There is nothing to set up: the page reads your movie and episode libraries each time it opens.

Before using the quarantine, give Emby write access to the library folders. The quarantine creates a .medialab-de-sters (Romanian for “to delete”) folder at the root of each library folder and moves files out of their folders, so the user Emby runs as (on Linux usually emby) needs write permission on the library folders and the folders inside them. In Docker, mount the media volumes read-write (without :ro). Everything else in the plugin only reads.

Daily use

1. The numbers at the top: video files, duplicate groups, the space to reclaim from duplicates, unmatched movies and the total size.

2. Duplicates: each group shows the versions, the best one first and marked best (higher resolution first, then HDR, then a more efficient codec — AV1, HEVC, VP9 — then bitrate).

   • Movies are compared by their TMDb or IMDb id, episodes by series, season and episode number.
   • Movies without a TMDb or IMDb id are compared by title and year. Their groups are marked by title and year (no metadata id) — check: open both and make sure they really are the same movie before you quarantine one (a remake can have the same title, and sometimes the same year).
   • Files that Emby already shows as versions of one title count as one item and are not reported as duplicates.
   • Quarantine, on a weaker version, asks for confirmation and moves that file and its companions to quarantine (see below).

3. Unmatched movies: movies with no metadata id. Click Open, then use Identify in Emby to pick the right movie; it disappears from the list the next time you open the page.

4. Missing, broken or truncated files: click Check the files. The check runs in the background, file by file, and shows its progress; on a large library it takes a while and you can leave the page. For each file it checks that the file exists, reads it with Emby's ffprobe (at most 30 seconds) and then decodes the last 3 seconds of the video with Emby's ffmpeg (at most 60 seconds). Each problem is listed with its cause:

   • missing from disk;
   • cannot be read, with the error;
   • no video track: the only "video" is an image (cover art does not count as video), as in a file of random bytes;
   • no duration (broken header);
   • zero duration;
   • the end is missing (incomplete download/copy): the last seconds cannot be decoded. A file cut off very close to its end (for example at about 98%) may still pass, because its last seconds can still contain decodable frames.

   The result is kept until Emby restarts.

5. Space: the space by library, by resolution and by codec, and the 20 largest files no user has watched.

The quarantine

• What is moved: the video file and the files in the same folder whose name starts with the same name followed by . or - — for example Movie (2010).mkv with Movie (2010).en.srt, Movie (2010).nfo and Movie (2010)-poster.jpg. Other files in the folder stay where they are.
• Where: into .medialab-de-sters at the root of the library folder that holds the file, with the same sub-folders (/media/movies/Movie (2010)/Movie (2010).mkv goes to /media/movies/.medialab-de-sters/Movie (2010)/Movie (2010).mkv). If a file of the same name is already in quarantine, the new one goes into a sub-folder with a unique name, so nothing is overwritten.
• If a move fails half-way (for example one companion file cannot be moved): the files already moved are put back, and a copy left behind in .medialab-de-sters by an interrupted move between disks is removed, so you never end up with the same file in two places. If the files cannot be put back either, the entry stays in the Quarantine list and Restore brings back what was moved. The page shows the error.
• After the move the plugin starts a library rescan, so the quarantined version disappears from Emby (Emby does not scan the hidden .medialab-de-sters folder, which stays inside the library folder). If Emby ever lists the file with its new path inside .medialab-de-sters, Emby has scanned the quarantine folder: the plugin does not quarantine such a file again; restore it, or delete the folder from disk once you are sure.
• Restore: the Quarantine list shows each title with its original paths and size. Restore moves the files back exactly where they were and rescans the library. If a file is both in quarantine and at its original path (for example you added the movie again), the restore is refused and nothing is touched.
• Final deletion is yours: the plugin never deletes. When you are sure, delete the .medialab-de-sters folder (or the files in it) from disk; the space is freed only then.
• The list of quarantined files is kept in the plugin's data folder, so it survives an Emby restart. Do not rename or move the .medialab-de-sters folder while something in it may still need restoring.

Troubleshooting

• Quarantine shows "It could not be done": the message after it gives the reason. Usually Emby has no write access to the library folder; see Configuration. Files outside the folders of your Emby libraries, and files already in .medialab-de-sters, are also refused.
• Restore shows "It could not be done": a file is already at the original path (for example you added the movie again). Move or delete that file, then restore.
• A group marked "by title and year — check" holds two different movies: do not quarantine anything; identify both movies in Emby, and once they have their TMDb or IMDb ids they are no longer grouped.
• A movie is in the library twice but not listed under duplicates: the two items have different ids, or one has an id and the other has none (then identify it), or Emby already shows them as versions of one title.
• A file that does not play is not reported: the damage may be in the middle of the file, which is not checked, or the file was cut off very close to its end.