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

Chaque bibliothèque auto-hébergée dérive. Un film est ajouté deux fois parce que deux fichiers ont atterri dans des dossiers différents, quelques titres n’ont jamais été identifiés et restent là sans affiche, une copie a été interrompue en cours de route sans que personne ne le remarque, et le disque continue de se remplir. Jellyfin n’offre pas de rapport unique pour tout cela, vous le découvrez donc souvent par hasard. Library Doctor est un plugin Jellyfin qui rassemble ces problèmes sur une seule page d’administration, indique ce que chacun coûte en espace disque et permet de les corriger sans jamais supprimer de fichier.

Ce tutoriel parcourt tout le flux : trouver les jellyfin films en double, traiter les titres non identifiés, vérifier l’intégrité des fichiers, lire le rapport d’espace et utiliser la quarantaine comme filet de sécurité.

Prérequis

• Jellyfin Server 12.2 ou plus récent (Linux, Windows ou Docker).
• Un compte MediaLab Works avec une licence couvrant le plugin (abonnement actif, licence à vie dans sa fenêtre de mise à jour, le bundle Jellyfin, ou l’essai gratuit de 30 jours).
• ffprobe et ffmpeg pour le contrôle d’intégrité — ils sont fournis avec jellyfin-ffmpeg, et le plugin utilise les mêmes chemins que Jellyfin pour le transcodage.
• Un accès en écriture aux dossiers de la bibliothèque pour l’utilisateur Jellyfin, si vous voulez utiliser la quarantaine. Sous Linux, il s’agit généralement de l’utilisateur jellyfin ; dans 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.

Le plugin est open source (GPL-3.0), et le code source de chaque version est disponible dans votre compte.

Étape 1 — Installer et activer

La méthode recommandée est votre dépôt de plugins privé :

1. Dans votre compte MediaLab Works, ouvrez Licences → Dépôt de plugins Jellyfin et cliquez sur Créer une adresse. Copiez-la — elle contient un jeton, gardez-la donc privée.
2. Dans Jellyfin, ouvrez Tableau de bord → Plugins → Dépôts, cliquez sur +, nommez-le (par exemple MediaLab Works), collez l’adresse et enregistrez.
3. Dans Tableau de bord → Plugins → Catalogue, trouvez Library Doctor by MediaLab, cliquez sur Installer, puis redémarrez Jellyfin.

Il existe aussi un catalogue public à l’adresse https://medialab.works/jellyfin/manifest.json, ainsi qu’une installation manuelle par zip si vous préférez. Après le redémarrage, ouvrez la page du plugin sous Tableau de bord → Plugins → Library Doctor by MediaLab, allez dans Licence, collez votre clé et cliquez sur Activer avec la clé. Pas encore de clé ? Démarrez l’essai de 30 jours depuis la même page.

Étape 2 — Ouvrir la page du tableau de bord

Library Doctor apparaît dans le menu du tableau de bord Jellyfin et n’est visible que par les administrateurs. Il n’y a rien à configurer : la page lit vos bibliothèques de films et d’épisodes à chaque ouverture.

En haut, vous obtenez les chiffres : fichiers vidéo, groupes de doublons, espace à récupérer sur les doublons, films non identifiés et taille totale. Considérez cela comme un instantané de la santé de votre bibliothèque avant de toucher à quoi que ce soit.

Étape 3 — Examiner les films et épisodes en double

C’est la partie pour laquelle la plupart des gens viennent. Jellyfin regroupe déjà plusieurs fichiers d’un même film comme versions lorsqu’il les reconnaît, mais quand le même film se trouve dans deux dossiers différents, il devient généralement deux éléments distincts. Library Doctor trouve ces groupes.

• 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 identifiant de métadonnées sont mis en correspondance par titre et année, en ignorant la casse, les accents et la ponctuation. 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 affiche les versions côte à côte — résolution, HDR, codec, débit et taille — avec la meilleure en premier et marquée meilleure (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). Vous voyez aussi l’espace que vous récupéreriez en ne gardant que celle-là.

Vous disposez de deux actions, et aucune ne supprime quoi que ce soit :

• Regrouper comme versions conserve tous les fichiers et les affiche comme versions d’un même titre, en utilisant le regroupement de versions propre à Jellyfin. Aucun fichier n’est déplacé.
• Quarantaine écarte une version plus faible (voir l’étape 6).

Étape 4 — Corriger les films non identifiés

La section Films non identifiés liste les films sans aucun identifiant de métadonnées. Ce sont généralement ceux dont le titre, l’année ou l’affiche sont erronés, et ils ont tendance à manquer dans les collections et les recommandations.

Cliquez sur Ouvrir sur une entrée, puis utilisez Identifier de Jellyfin sur le film pour choisir la bonne correspondance. Il disparaît de la liste la prochaine fois que vous ouvrez la page Library Doctor.

Étape 5 — Lancer le contrôle d’intégrité et lire le rapport d’espace

Cliquez sur Vérifier les fichiers. Le contrôle s’exécute en arrière-plan, fichier par fichier, et affiche sa progression ; sur une grande bibliothèque, cela prend du temps et vous pouvez quitter la page. Il est uniquement à la demande — il n’y a pas d’analyses planifiées.

Pour chaque fichier de film et d’épisode, il signale les fichiers :

• absents du disque ;
• illisibles, avec l’erreur ;
• sans véritable piste vidéo (par exemple un fichier d’octets aléatoires dans lequel ffprobe devine une image) ;
• sans durée (un en-tête cassé) ou de durée nulle ;
• tronqués : les 3 dernières secondes sont décodées, et un fichier dont la fin ne peut pas être décodée est signalé comme un téléchargement ou une copie incomplets.

Soyez conscient des limites : un fichier coupé très près de sa fin peut encore avoir des images décodables dans ses dernières secondes et passer, les dommages au milieu d’un fichier ne sont pas recherchés, et un .ts tronqué ne peut pas être détecté car aucune durée n’y est stockée.

En dessous, le rapport d’espace vous donne 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. Cette dernière liste est souvent la plus utile lorsqu’il vous faut de la place pour quelque chose de nouveau.

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

Lorsque vous cliquez sur Quarantaine sur une version et confirmez, le plugin déplace le fichier vidéo et les fichiers adjacents qui partagent son nom — sous-titres, .nfo, images comme Movie.srt, Movie.en.srt, Movie.nfo, 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 le dossier se trouve dans le même dossier de bibliothèque, il est normalement sur le même disque, et le déplacement est donc instantané. Jellyfin 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é (à cause des permissions, par exemple), les fichiers déjà déplacés sont remis en place et rien ne reste en arrière ; si la remise en place n’est pas possible non plus, l’entrée reste dans la liste de quarantaine pour que vous puissiez la restaurer. Les fichiers hors des dossiers de bibliothèque, ainsi que les fichiers déjà dans un dossier .medialab-de-sters, sont refusés.

La liste Quarantaine affiche chaque titre déplacé avec son emplacement d’origine et sa taille. Restaurer remet les fichiers exactement là où ils étaient et relance l’analyse ; l’opération est refusée, sans rien toucher, si un fichier est à la fois en quarantaine et de retour à son emplacement d’origine. Le plugin n’écrase ni ne supprime jamais un fichier — une fois que vous êtes sûr, vous supprimez vous-même le dossier .medialab-de-sters du disque.

Conseils et dépannage

• La quarantaine ne fait rien. Vérifiez que l’utilisateur Jellyfin peut écrire dans les dossiers de bibliothèque et que les volumes Docker ne sont pas montés en :ro. Tous les rapports fonctionnent sans accès en écriture ; seul le déplacement échoue.
• Un groupe de doublons semble erroné. S’il est marqué par titre et année, vérifiez les deux entrées avant de regrouper ou de mettre en quarantaine — des remakes peuvent partager un titre, et parfois une année.
• Le contrôle prend du temps. C’est normal sur une grande bibliothèque ; il s’exécute en arrière-plan et vous pouvez quitter la page. Les résultats sont conservés en mémoire uniquement, ils ne persistent donc pas entre les redémarrages.
• Confidentialité. Il n’y a aucun contact externe en dehors du client de licence, et aucune recherche de métadonnées en ligne : les doublons et les titres non identifiés sont calculés à partir des identifiants que votre serveur stocke déjà. Le contrôle des fichiers exécute ffprobe du serveur localement. Après un déplacement ou une restauration en quarantaine, le plugin lance l’analyse régulière de la bibliothèque, qui peut contacter les fournisseurs de métadonnées configurés sur votre serveur — c’est le comportement du serveur, pas celui du plugin.

Conclusion

L’hygiène d’une bibliothèque consiste surtout à voir les problèmes avant qu’ils ne grossissent. Library Doctor vous offre une page pour les films et épisodes en double, les titres non identifiés, les fichiers manquants ou corrompus et l’endroit où va réellement l’espace — et il corrige les choses en regroupant ou en déplaçant des fichiers dans une quarantaine que vous pouvez restaurer, jamais en supprimant. Installez-le depuis votre dépôt de plugins, lancez le contrôle une fois, et gardez la page dans votre routine de maintenance mensuelle. La page produit Library Doctor présente la liste complète des fonctionnalités, le guide utilisateur détaille l’installation et l’usage quotidien, et le changelog montre ce qui a changé dans chaque version. Des questions ? La base de connaissances, la FAQ et la page de contact sont les points de départ.