Emby Curator – safe duplicate cleanup, metadata localization and library audits (Docker / Python CLI)

[Barlog9511 17]

Hi all,

Emby Curator is a free, open-source command-line tool (Apache-2.0) that keeps an Emby library tidy from the outside, through the Emby API. It started as a fork of troy_'s emby-dedupe (thread here), which has been inactive since 2024. I have been running it against my own library, about 8,100 films and 2,600 series, since early 2026 and rewrote most of it along the way. Credit to Troy Kelly for the original idea and codebase.

What it does

• Duplicate cleanup (dedupe). Finds items that share a provider id (IMDb, TMDb, TVDb), ranks the copies, keeps the best one and, only with --doit, deletes the rest. Every run is a dry run unless you say otherwise, and it writes an HTML report with the reason for each keep and delete.
• Quality ranking that answers "which copy is better". Resolution is scored on the 16:9 frame, so a letterboxed file does not beat a cropped one of the same picture. HDR and Dolby Vision count only when the video stream says so, never the filename. Bitrate is judged per resolution class, audio by channels and by the languages you list with --lang-prio. Single-layer Dolby Vision Profile 5 files (the "green/pink" ones on non-DV players) are ranked below a clean HDR10 copy, and the report flags them.
• Deletion guards. Emby's delete removes the item's folder, not just the file. The tool refuses any delete that would take the kept copy's folder with it, holds pairs it cannot prove are the same content (different season folders, unknown runtime, a frame comparison that did not run), and holds a copy with an untagged audio track when the kept copy lacks one of your priority languages, so a dub is never deleted by accident. These guards exist because each of those cases happened on my library first.
• Genres (genres audit / normalize / fix / origin). Reports genre health, merges variant names, fills missing genres from TMDb/OMDb, and can tag Czech/Slovak productions with their own genre.
• Descriptions (descriptions fill). Localized overview, tagline and title (Slovak/Czech today, the lookup is TMDb-based) and missing production years.
• ČSFD (csfd fill / people). For titles TMDb/TVDb/IMDb cannot identify, fills only empty fields from csfd.sk, with an optional AI-assisted match that is review-only by default. Mostly relevant to Czech and Slovak libraries.
• Library audits. cleanup lists stale unwatched items with a rating-decay rule so classics stay; missing-episodes lists gaps per series; check tells a downloader whether a candidate file would actually be an upgrade over what the library already has.

What it deliberately does not do

• It never touches files or Emby directly except through the documented API calls, and never writes unless --doit is given.
• It does not try to decide whether two different provider ids are the same film. Matching is by provider id only.
• It is not a plugin; it runs on any machine that can reach the server, on a schedule or by hand.

Install

Docker (amd64, arm64):

docker pull ghcr.io/barlog951/emby-curator:latest
docker run --rm ghcr.io/barlog951/emby-curator:latest \
  --host http://your-emby:8096 --api-key YOUR_KEY --library "Movies" dedupe

Python 3.12+:

pip install emby-curator
emby-curator --host http://your-emby:8096 --api-key YOUR_KEY --library "Movies" dedupe

Add --doit only after you have read the dry-run report. Back up your Emby data first, as with any tool that deletes.

Project

• GitHub: https://github.com/Barlog951/emby-curator (README, full option reference, changelog)
• PyPI: https://pypi.org/project/emby-curator/
• Current release 3.4.6. About 1,800 automated tests run on every change; CI publishes the Docker image and the PyPI package from tagged releases.

Where I would like your input: cases where the quality ranking picks the copy you would not have kept, and libraries in languages other than Czech/Slovak/English, where I have no data of my own. Issues on GitHub or replies here both work.