Library Doctor pour Jellyfin — guide

Installation

Vous avez besoin de Jellyfin Server 12.2 ou plus récent et d’un compte MediaLab Works avec une licence qui couvre le plugin (un abonnement actif, une licence à vie dans sa période de mises à jour, le pack Jellyfin ou l’essai gratuit de 30 jours).

Depuis votre dépôt de plugins (recommandé). Jellyfin installe ensuite et met à jour le plugin tout seul.

Dans votre compte MediaLab Works, ouvrez Licences → Dépôt de plugins Jellyfin et cliquez sur Créer l’URL du dépôt. Copiez-la : elle est privée (elle contient un token), ne la partagez pas ; vous pouvez la régénérer ou la révoquer à tout moment.
Dans Jellyfin, ouvrez Dashboard → Plugins → Repositories, cliquez sur +, donnez-lui un nom (par exemple MediaLab Works), collez l’adresse et enregistrez.
Dans Dashboard → Plugins → Catalog, cherchez Library Doctor by MediaLab, cliquez sur Install, puis redémarrez Jellyfin.

Le dépôt ne liste que les plugins couverts par vos licences, et uniquement dans les versions qu’elles autorisent. Ses liens de téléchargement sont signés et expirent après quelques heures, donc Jellyfin lit toujours une liste à jour.

Depuis le catalogue public. https://medialab.works/jellyfin/manifest.json liste chaque plugin MediaLab Works publié avec sa version publique ; medialab Server l’ajoute lui-même. Vous pouvez l’ajouter de la même façon pour installer un plugin avant d’avoir une clé : le plugin demande alors la licence, ou démarre l’essai, sur sa page License. Avec une licence à vie dont la période de mises à jour est terminée, restez sur votre dépôt privé, qui propose uniquement les versions que votre licence autorise.

Manuellement, depuis un fichier zip.

Dans Compte → Licences, téléchargez jf-librarydoctor_x.y.z.zip (le SHA-256 du fichier est affiché à côté du bouton).
Extrayez-le dans un nouveau dossier Library Doctor by MediaLab_x.y.z.0 à l’intérieur du dossier des plugins Jellyfin :
- Linux (paquet) : /var/lib/jellyfin/plugins/
- Docker (image officielle) : /config/plugins/ dans le volume de configuration
- Windows : %ProgramData%\Jellyfin\Server\plugins\
Redémarrez Jellyfin.

Activation de la licence

Ouvrez la page du plugin dans Dashboard → Plugins → Library Doctor by MediaLab et cliquez sur License.
Collez votre clé de licence et cliquez sur Activate with key. Le plugin contacte le serveur de licences, lie la clé à ce serveur Jellyfin et affiche la licence comme Active.
Pas encore de clé ? Sur la même page, saisissez votre e-mail et démarrez l’essai gratuit de 30 jours (carte requise, rien à payer aujourd’hui) ou achetez une licence ; le plugin s’active tout seul une fois le paiement effectué.

La licence est vérifiée une fois par jour et à chaque démarrage de Jellyfin. Sans internet, le plugin continue de fonctionner pendant 7 jours après la dernière vérification réussie. Sans licence valide, le plugin arrête son travail et seule sa page License reste fonctionnelle (essai, clé, renouvellement) ; rien n’est supprimé et tout reprend dès que la licence redevient valide. Move license (release this server) sur la même page libère la clé pour un autre serveur.

Mises à jour et retour en arrière

Depuis le dépôt : Jellyfin affiche les nouvelles versions dans Dashboard → Plugins et peut mettre à jour le plugin automatiquement ; redémarrez Jellyfin pour charger la nouvelle version.
Depuis la page License du plugin : avec une licence valide, Install update installe la version la plus récente que votre licence autorise et Roll back to x.y.z revient à la version précédente (par exemple si quelque chose a cessé de fonctionner après une mise à jour). Redémarrez Jellyfin après l’une ou l’autre. Les deux paquets sont vérifiés par rapport à la somme de contrôle publiée par le serveur de licences.
Une licence à vie reçoit les versions publiées pendant sa période de mises à jour ; après celle-ci, le plugin continue de fonctionner sur la dernière version qui lui est autorisée.
Après un Roll back to x.y.z, la mise à jour automatique de Jellyfin pour ce plugin est désactivée jusqu’au prochain Install update sur la page License, pour que la tâche planifiée Update Plugins (au démarrage et chaque jour) ne réinstalle pas la version plus récente.
Licence à vie et mises à jour automatiques. Le catalogue public Jellyfin (https://medialab.works/jellyfin/manifest.json) propose toujours la version la plus récente. Quand la période de mises à jour d’une licence à vie est terminée, les versions publiées ensuite ne sont pas licenciées : si les mises à jour automatiques de Jellyfin en installent une, le plugin s’arrête avec « version not licensed » jusqu’à ce que vous reveniez en arrière avec Roll back to x.y.z sur sa page License ou que vous achetiez un pass de mises à jour. Pour l’éviter, ne laissez pas Jellyfin mettre à jour ce plugin automatiquement : ajoutez votre dépôt de plugins privé, qui propose uniquement les versions que votre licence autorise, à la place du catalogue public, ou retirez les déclencheurs de la tâche planifiée Update Plugins dans Dashboard → Scheduled Tasks (cela arrête les mises à jour automatiques pour chaque plugin).

Code source

Le code source GPL-3.0 de chaque version est dans Compte → Licences (Code source), à côté du téléchargement, sous forme d’archive .tar.gz créée depuis le commit exact de cette version.

Configuration

Ouvrez Library Doctor dans le menu du tableau de bord de Jellyfin (réservé aux administrateurs). Il n’y a rien à configurer : la page lit vos bibliothèques de films et d’épisodes à chaque ouverture.

Avant d’utiliser la quarantaine, donnez à Jellyfin un accès en écriture aux dossiers de bibliothèque. La quarantaine crée un dossier .medialab-de-sters (le nom signifie « à supprimer » en roumain) à la racine de chaque dossier de bibliothèque et sort des fichiers de leurs dossiers ; l’utilisateur sous lequel tourne Jellyfin (sous Linux, généralement jellyfin) a donc besoin de la permission en écriture sur les dossiers de bibliothèque et les dossiers qu’ils contiennent. Sous Docker, montez les volumes de médias en lecture-écriture (sans :ro). Tout le reste du plugin ne fait que lire.

Utilisation quotidienne

Les chiffres en haut : fichiers vidéo, groupes de doublons, l’espace à récupérer sur les doublons, les films sans correspondance et la taille totale.
Doublons : chaque groupe affiche les versions, la meilleure d’abord, marquée best (résolution la plus élevée d’abord, puis HDR, puis un codec plus efficace — AV1, HEVC, VP9 — puis le débit).
- Les films sont comparés par leur identifiant TMDb ou IMDb, les épisodes par série, saison et numéro d’épisode.
- Les films sans identifiant TMDb ou IMDb sont comparés par titre et année. Leurs groupes sont marqués by title and year (no metadata id) — check : ouvrez les deux et assurez-vous qu’il s’agit vraiment du même film avant de les regrouper ou d’en mettre un en quarantaine (un remake peut avoir le même titre, et parfois la même année).
- Group as versions conserve tous les fichiers et en fait un seul titre avec un choix de version à la lecture (le regroupement de versions natif de Jellyfin). Aucun fichier n’est déplacé.
- Quarantine, sur une version plus faible, demande une confirmation et déplace ce fichier et ses compagnons en quarantaine (voir ci-dessous).
Films sans correspondance : des films sans identifiant de métadonnées. Cliquez sur Open, puis utilisez Identify dans Jellyfin pour choisir le bon film ; il disparaît de la liste à la prochaine ouverture de la page.
Fichiers manquants, cassés ou tronqués : cliquez sur Check the files. La vérification s’exécute en arrière-plan, fichier par fichier, et affiche sa progression ; sur une grande bibliothèque, elle prend un certain temps et vous pouvez quitter la page. Pour chaque fichier, elle vérifie que le fichier existe, le lit avec ffprobe (30 secondes au maximum), puis décode les 3 dernières secondes de la vidéo avec ffmpeg (60 secondes au maximum). Chaque problème est listé avec sa cause :
- missing from disk ;
- cannot be read, avec l’erreur ;
- no video track : la seule « vidéo » est une image (une jaquette ne compte pas comme de la vidéo), comme dans un fichier d’octets aléatoires ;
- no duration (broken header) ;
- zero duration ;
- the end is missing (incomplete download/copy) : les dernières secondes ne peuvent pas être décodées. Un fichier coupé très près de sa fin (par exemple vers 98 %) peut encore passer, car ses dernières secondes peuvent encore contenir des images décodables.
Le résultat est conservé jusqu’au redémarrage de Jellyfin.
Espace : l’espace par bibliothèque, par résolution et par codec, et les 20 fichiers les plus volumineux qu’aucun utilisateur n’a regardés.

La quarantaine

Ce qui est déplacé : le fichier vidéo et les fichiers du même dossier dont le nom commence par le même nom suivi de . ou - — par exemple Movie (2010).mkv avec Movie (2010).en.srt, Movie (2010).nfo et Movie (2010)-poster.jpg. Les autres fichiers du dossier restent en place.
Où : dans .medialab-de-sters à la racine du dossier de bibliothèque qui contient le fichier, avec les mêmes sous-dossiers (/media/movies/Movie (2010)/Movie (2010).mkv devient /media/movies/.medialab-de-sters/Movie (2010)/Movie (2010).mkv). Si un fichier du même nom est déjà en quarantaine, le nouveau part dans un sous-dossier au nom unique, pour que rien ne soit écrasé.
Si un déplacement échoue en chemin (par exemple si un fichier compagnon ne peut pas être déplacé) : les fichiers déjà déplacés sont remis en place, et une copie laissée dans .medialab-de-sters par un déplacement interrompu entre disques est supprimée, pour que vous ne vous retrouviez jamais avec le même fichier à deux endroits. Si les fichiers ne peuvent pas non plus être remis en place, l’entrée reste dans la liste Quarantine et Restore rapporte ce qui a été déplacé. La page affiche l’erreur.
Après le déplacement, Jellyfin rescanne la bibliothèque et la version mise en quarantaine disparaît de celle-ci ; Jellyfin n’importe pas le dossier .medialab-de-sters.
Restore : la liste Quarantine affiche chaque titre avec ses chemins et sa taille d’origine. Restore remet les fichiers exactement à leur place et rescanne la bibliothèque. Si un fichier est à la fois en quarantaine et à son chemin d’origine (par exemple si vous avez ajouté à nouveau le film), la restauration est refusée et rien n’est touché.
La suppression définitive vous appartient : le plugin ne supprime jamais. Quand vous êtes sûr, supprimez le dossier .medialab-de-sters (ou les fichiers qu’il contient) du disque ; l’espace n’est libéré qu’à ce moment-là.
La liste des fichiers en quarantaine est conservée dans le dossier de données du plugin et survit donc à un redémarrage de Jellyfin. Ne renommez ni ne déplacez le dossier .medialab-de-sters tant que ce qu’il contient peut encore avoir besoin d’être restauré.

Dépannage

Quarantine, Restore ou Group as versions affiche « It could not be done » : le message qui suit donne la raison.
La quarantaine échoue : Jellyfin n’a en général pas d’accès en écriture au dossier de bibliothèque ; voir Configuration. Les fichiers hors des dossiers de vos bibliothèques Jellyfin, et les fichiers déjà dans .medialab-de-sters, sont aussi refusés.
La restauration échoue : un fichier est déjà au chemin d’origine (par exemple si vous avez ajouté à nouveau le film). Déplacez ou supprimez ce fichier, puis restaurez.
Chaque fichier est signalé « cannot be read » : ffprobe est introuvable ; installez jellyfin-ffmpeg et vérifiez son chemin dans Dashboard → Playback → Transcoding.
Un groupe marqué « by title and year — check » contient deux films différents : ne regroupez ni ne mettez rien en quarantaine ; identifiez les deux films dans Jellyfin et, une fois qu’ils ont leurs identifiants TMDb ou IMDb, ils ne sont plus regroupés.
Un film est deux fois dans la bibliothèque mais pas listé parmi les doublons : les deux éléments ont des identifiants différents, ou l’un en a un et pas l’autre (identifiez-le alors).
Un fichier qui ne se lit pas n’est pas signalé : le dommage se situe peut-être au milieu du fichier, ce qui n’est pas vérifié, ou le fichier a été coupé très près de sa fin.