Trouver les films en double, titres non identifiés et fichiers corrompus dans Emby

Si vous faites tourner un serveur Emby depuis quelques années, vous connaissez la sensation : le même film apparaît deux fois, une affiche manque, un fichier qui passait très bien le mois dernier s’arrête à mi-chemin, et le disque se remplit de choses que personne ne regarde. Emby lui-même ne propose aucun rapport pour tout cela. Library Doctor est un plugin qui trouve ces problèmes, montre ce que chacun coûte en espace disque, et permet de les régler sans jamais supprimer un fichier. Ce tutoriel parcourt toute la routine, des films en double à une quarantaine réversible, pour celles et ceux qui administrent leurs propres serveurs.

Prérequis

• Emby Server 4.10.1 ou plus récent, sous Linux, Windows ou Docker.
• Pour le contrôle des fichiers : rien à installer. Le plugin utilise les ffprobe et ffmpeg fournis avec Emby.
• Pour la quarantaine : l’utilisateur Emby doit avoir l’accès en écriture aux dossiers de bibliothèque. Sous Linux, il s’agit généralement de l’utilisateur emby ; sous Docker, les volumes média ne doivent pas être montés en lecture seule (pas de :ro). Sans accès en écriture, tous les rapports fonctionnent toujours ; seule la quarantaine ne peut pas déplacer de fichiers.
• Une clé de licence, un abonnement actif, une licence à vie dans sa fenêtre de mise à jour, ou l’essai gratuit de 30 jours. Sans licence valide, le plugin est arrêté : pas de rapport, pas de contrôle des fichiers, pas de déplacement.

Étape 1 — Installer et activer

1. Connectez-vous à votre compte MediaLab Works, ouvrez Licences et téléchargez la DLL du plugin.
2. Copiez la DLL dans le dossier des plugins d’Emby et redémarrez Emby Server :
   • Linux (paquet) : /var/lib/emby/plugins/
   • Docker : le dossier plugins dans votre volume de configuration Emby
   • Windows : %AppData%\Emby-Server\programdata\plugins\
3. Ouvrez Library Doctor dans le menu du tableau de bord Emby et cliquez sur Licence. Collez votre clé et activez-la, ou saisissez votre e-mail pour démarrer l’essai. Le plugin contacte le serveur de licences, lie la clé à ce serveur et affiche la licence comme Active.

La licence est vérifiée une fois par jour et à chaque démarrage d’Emby. Sans internet, le plugin continue de fonctionner pendant 7 jours après la dernière vérification réussie. La même page permet d’installer une mise à jour ou de revenir à la version précédente ; redémarrez Emby dans les deux cas.

Étape 2 — Lire les chiffres d’en-tête

Ouvrez Library Doctor dans le tableau de bord (administrateurs uniquement). Il n’y a rien à configurer : la page lit vos bibliothèques de films et d’épisodes à chaque ouverture. En haut, vous obtenez le nombre de fichiers vidéo, les groupes de doublons, l’espace à récupérer sur les doublons, les films non identifiés et la taille totale. Servez-vous-en comme d’un indicateur de santé rapide avant d’entrer dans le détail.

Étape 3 — Doublons : savoir ce qu’Emby regroupe déjà

Avant de commencer à déplacer des fichiers, une distinction importante. Emby regroupe les fichiers d’un même film comme versions uniquement lorsqu’ils se trouvent dans le même dossier avec des noms correspondants ; ils apparaissent alors comme un choix de version à la lecture et ne sont pas signalés comme doublons par le plugin. Deux fichiers du même film dans des dossiers différents deviennent deux éléments distincts, et c’est ce que Library Doctor trouve.

• Les films sont mis en correspondance par leur identifiant TMDb ou IMDb.
• Les épisodes sont mis en correspondance par série, saison et numéro d’épisode.
• Les films sans aucun des deux identifiants sont mis en correspondance par titre (en ignorant la casse, les accents et la ponctuation) et par année. Ces groupes sont marqués par titre et année (sans identifiant de métadonnées) — vérifier, car deux films différents peuvent partager un titre et une année. Ouvrez les deux avant d’agir.

Chaque groupe montre les versions côte à côte — résolution, HDR, codec, débit et taille — avec la meilleure en premier et marquée best (d’abord la résolution la plus élevée, puis le HDR, puis un codec plus efficace comme AV1, HEVC ou VP9, puis le débit), ainsi que l’espace que vous récupéreriez en ne gardant que celle-là. Si vous êtes sur Emby 4.10 et que des copies de même TMDb ont été regroupées automatiquement, elles peuvent encore apparaître comme doublons tant que vous ne les avez pas fusionnées ; c’est une limitation connue, pas un bug du rapport.

Étape 4 — Films non identifiés

La section Unmatched movies liste les films sans aucun identifiant de métadonnées. Cela signifie généralement un titre ou une année erronés, une affiche manquante, et un film qui n’apparaît jamais dans les collections ni les recommandations. Cliquez sur Open, puis utilisez Identify dans Emby pour choisir le bon film. Il disparaît de la liste à la prochaine ouverture de la page.

Étape 5 — Contrôler les fichiers manquants, illisibles et tronqués

Cliquez sur Check the files. Le contrôle s’exécute en arrière-plan, fichier par fichier, avec un indicateur de progression ; sur une grande bibliothèque, cela prend du temps et vous pouvez quitter la page. Pour chaque film et épisode, le plugin vérifie que le fichier existe, le lit avec le ffprobe d’Emby (30 secondes au maximum), puis décode les 3 dernières secondes de la vidéo avec le ffmpeg d’Emby (60 secondes au maximum). Chaque problème est listé avec sa cause :

• missing from disk
• cannot be read, avec l’erreur
• no video track : le seul « vidéo » est une image, comme dans un fichier d’octets aléatoires
• no duration (broken header)
• zero duration
• the end is missing (incomplete download or copy) : les dernières secondes ne peuvent pas être décodées

Deux limites assumées : un fichier coupé très près de sa fin (par exemple à environ 98 %) peut encore passer, car ses dernières secondes contiennent des images décodables, et les dommages au milieu d’un fichier ne sont pas recherchés. Un .ts tronqué ne peut pas être détecté, car il ne stocke pas de durée. Les résultats sont conservés en mémoire jusqu’au redémarrage d’Emby. Le contrôle ne s’exécute qu’à la demande ; il n’y a pas d’analyses planifiées.

Étape 6 — Le rapport d’espace

La section Space affiche le total, puis l’espace par bibliothèque, par résolution (4K, 1080p, 720p, SD) et par codec vidéo, ainsi que les 20 plus gros fichiers qu’aucun utilisateur n’a regardés. C’est la page la plus utile avant une mise à niveau de disque : elle vous dit si votre problème vient de quelques énormes remux 4K ou d’une longue traîne de fichiers 720p que personne n’ouvre.

Étape 7 — Mettre en quarantaine plutôt que supprimer

Lorsque vous cliquez sur Quarantine sur une version plus faible (et confirmez), le plugin déplace le fichier vidéo et les fichiers voisins qui partagent son nom — sous-titres, .nfo, images comme Movie.srt, Movie.en.srt, Movie.nfo et Movie-poster.jpg — dans un dossier nommé .medialab-de-sters à la racine du dossier de bibliothèque qui les contient, en conservant leurs sous-dossiers. Comme ce dossier se trouve dans le même dossier de bibliothèque, il est normalement sur le même disque et le déplacement est instantané. Emby relance ensuite l’analyse de la bibliothèque.

Le déplacement est enregistré avant que le moindre fichier ne soit touché. Si un fichier ne peut pas être déplacé (par exemple à cause des permissions), les fichiers déjà déplacés sont remis en place et aucune copie ne reste ; si la remise en place est elle aussi impossible, l’entrée reste dans la liste Quarantine pour que vous puissiez la restaurer. La liste affiche chaque titre déplacé avec son emplacement d’origine et sa taille. Restore remet les fichiers exactement là où ils étaient et relance l’analyse ; il refuse, sans rien toucher, si un fichier est à la fois en quarantaine et de retour à son emplacement d’origine. Les fichiers hors des dossiers de bibliothèque, et ceux déjà dans .medialab-de-sters, sont refusés.

Le plugin n’écrase ni ne supprime jamais un fichier. Quand vous êtes sûr, vous supprimez vous-même le dossier .medialab-de-sters du disque ; l’espace n’est libéré qu’à ce moment-là. La liste est stockée dans le dossier de données du plugin, elle survit donc à un redémarrage d’Emby — ne renommez pas et ne déplacez pas le dossier de quarantaine tant que son contenu peut encore avoir besoin d’être restauré.

Conseils et dépannage

• La quarantaine indique « It could not be done » : le message qui suit en donne la raison. Le plus souvent, Emby n’a pas l’accès en écriture au dossier de bibliothèque. Vérifiez le propriétaire et les permissions sous Linux, et assurez-vous que les volumes Docker ne sont pas montés avec :ro.
• La restauration indique « It could not be done » : un fichier se trouve déjà à l’emplacement d’origine, par exemple parce que vous avez ajouté le film de nouveau. La restauration refuse plutôt que d’écraser.
• Un fichier en quarantaine apparaît dans Emby avec son nouveau chemin : Emby a analysé le dossier de quarantaine. Le plugin ne remettra pas un tel fichier en quarantaine ; restaurez-le, ou supprimez le dossier une fois que vous êtes sûr.
• Aucune requête en ligne : les doublons et les titres non identifiés sont calculés à partir des identifiants que votre serveur stocke déjà. Le seul contact externe est le client de licence. Après un déplacement ou une restauration en quarantaine, le plugin lance l’analyse de bibliothèque habituelle, qui peut contacter les fournisseurs de métadonnées configurés sur votre serveur.
• Emby Web uniquement pour la page d’administration. Le travail se fait sur le serveur ; les applications et les téléviseurs n’en voient que le résultat.

Conclusion

L’hygiène d’une bibliothèque n’est pas un nettoyage ponctuel, c’est une routine. Ouvrez la page, jetez un œil aux chiffres, traitez les doublons et les titres non identifiés, lancez le contrôle des fichiers après de gros imports, et consultez le rapport d’espace avant d’acheter un autre disque. Comme la quarantaine ne fait que déplacer des fichiers à l’intérieur du dossier de bibliothèque et les remet en place en un clic, vous pouvez être décisif sans avoir peur. Le parcours complet se trouve dans le guide utilisateur, l’historique des versions dans le changelog, et la page produit sur Library Doctor. Si quelque chose se comporte bizarrement, la base de connaissances et la FAQ sont l’étape suivante, et vous pouvez toujours nous contacter.