Plan Guard pour Jellyfin — guide

Installation

Pour l’instant, vous avez besoin de medialab Server (la variante MediaLab de Jellyfin 12.2 ; la version actuelle ne se charge pas dans l’image Docker Jellyfin 12.2 officielle) 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.

1. 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.
2. Dans Jellyfin, ouvrez Dashboard → Plugins → Repositories, cliquez sur +, donnez-lui un nom (par exemple MediaLab Works), collez l’adresse et enregistrez.
3. Dans Dashboard → Plugins → Catalog, cherchez Plan Guard 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.

1. Dans Compte → Licences, téléchargez jf-planguard_x.y.z.zip (le SHA-256 du fichier est affiché à côté du bouton).
2. Extrayez-le dans un nouveau dossier Plan Guard 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\
3. Redémarrez Jellyfin.

Activation de la licence

1. Ouvrez la page du plugin dans Dashboard → Plugins → Plan Guard by MediaLab et cliquez sur License.
2. 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.
3. 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 retour en arrière, si votre dépôt de plugins est ajouté dans Jellyfin, la tâche planifiée Update Plugins de Jellyfin (au démarrage et chaque jour) installe à nouveau la version la plus récente. Pour rester un certain temps sur la version précédente, retirez les déclencheurs de cette tâche dans Dashboard → Scheduled Tasks et remettez-les en place plus tard.

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 Plan Guard dans le menu du tableau de bord de Jellyfin. La page comporte six onglets : Active streams, Profiles, Users, Sharing, Log et Settings.

1. Profiles : cliquez sur Add profile et réglez, pour chaque profil (0 signifie aucune limite) :
   • le nombre de simultaneous streams ;
   • la qualité at home et away from home, en Mbit/s ;
   • la maximum resolution ;
   • si la video conversion (transcodage) est autorisée, et si la 4K conversion est autorisée (la plus coûteuse pour le serveur) ;
   • combien d’devices in 30 days un compte peut utiliser avant que cela compte comme un signal de partage ;
   • avec Cashier, la formule Cashier liée.
2. Users : choisissez le profil de chaque utilisateur et le profile for everyone else (ou aucune limite). Les administrateurs ne sont jamais limités.
3. Formules Cashier (facultatif) : avec Cashier installé et With Cashier installed: the profile follows the paid plan activé, les abonnés reçoivent le profil lié à leur formule (ou la limite d’appareils de la formule), et Plan Guard prend en charge l’arrêt des lectures.
4. Settings → enforcement :
   • Automatically stop playback that breaks the profile (désactivé : journal uniquement) ;
   • Seconds between message and stop (10 par défaut) ;
   • Sign out devices that ignore stop (activé par défaut) : l’utilisateur doit se reconnecter sur cet appareil ;
   • Block the device after signing it out (désactivé par défaut).
5. Settings → shared accounts : activez Detect shared accounts, puis choisissez what happens below the threshold : notifier uniquement (journal d’activité, valeur par défaut), notifier et envoyer un message à l’utilisateur, notifier et forcer une nouvelle connexion, ou notifier et bloquer l’appareil le plus récent. Vous pouvez aussi régler le seuil du score (50 par défaut), la vitesse de « impossible travel » (500 km/h par défaut) et combien de réseaux différents en un jour comptent comme un signal (5 par défaut).

Utilisation quotidienne

• Quand un utilisateur démarre une lecture au-dessus de la limite de flux, Jellyfin la refuse avant qu’elle ne commence. La qualité est plafonnée au démarrage, au débit du profil pour le domicile ou le déplacement.
• Pendant la lecture, Plan Guard vérifie chaque flux environ toutes les 10 secondes. Une lecture qui enfreint le profil reçoit un message, puis une commande d’arrêt ; si elle continue, son transcodage est terminé sur le serveur et l’appareil est déconnecté.
• Active streams affiche qui regarde quoi, la qualité, d’où et avec quel profil, avec un bouton Stop et un message facultatif pour l’utilisateur.
• Sharing affiche un score de confiance par compte (100 = propre) sur les 30 derniers jours, avec les signaux et les lieux derrière lui. Les alertes vont aussi dans le journal d’activité de Jellyfin, au maximum une fois par jour et par compte.
• Log affiche chaque action de Plan Guard et pourquoi elle a été faite.

Comment les lecteurs réagissent

• Les lecteurs sans contrôle à distance, comme Infuse, Kodi et DLNA, ignorent les commandes d’arrêt ; Plan Guard déconnecte donc l’appareil à la place (si Sign out devices that ignore stop est activé).
• Les lecteurs qui continuent à lire après la commande d’arrêt voient leur transcodage terminé sur le serveur, puis ils sont déconnectés.
• La liste complète des clients et de la réaction de chacun sera ajoutée après les tests.

Ce qu’il envoie, où

Les localisations sont résolues sur votre serveur, depuis les bases gratuites DB-IP Lite City et ASN, téléchargées depuis download.db-ip.com tant que la détection des comptes partagés est active, puis téléchargées de nouveau au démarrage quand elles ont plus de 35 jours. Si Access Log ou Security Notifications conservent déjà une base de localisation, Plan Guard la réutilise ; l’onglet Sharing indique celle en cours d’utilisation. Rien concernant vos utilisateurs n’est envoyé nulle part ; seule la vérification de licence atteint medialab.works.

Géolocalisation IP par DB-IP (CC BY 4.0).

Dépannage

• « Geolocation is not available yet » : les bases DB-IP Lite sont encore en cours de téléchargement ; le serveur doit joindre download.db-ip.com en HTTPS.
• Un utilisateur en données mobiles ou sur un VPN ressemble à un compte partagé : cela peut arriver ; gardez l’action sur Notify only, ou augmentez le réglage de réseaux par jour.
• Cashier est installé mais les profils ne suivent pas les formules : vérifiez que la licence de Cashier est active et à jour ; l’onglet Users indique l’état du lien.