Jellyfin Quick Connect : se connecter sur la TV avec un QR code et une validation sur mobile

Si vous faites tourner Jellyfin pour un foyer, vous connaissez déjà le pire moment de la soirée : quelqu'un ouvre l'application sur la TV, l'écran de connexion s'affiche et il faut saisir un mot de passe à la télécommande. Flèches, clavier à l'écran, un caractère de travers, on recommence. C'est la raison la plus fréquente pour laquelle on vous demande de « juste les connecter » sur votre serveur.

Jellyfin embarque déjà son propre Quick Connect : l'application sur la TV affiche un code à 6 chiffres, et un utilisateur connecté l'approuve ailleurs. La difficulté, c'est où : retrouver cet écran au fond des réglages de Jellyfin sur un téléphone n'a rien d'évident pour la plupart des gens. Quick Connect by MediaLab place une courte page sur le téléphone avec un QR code devant ce parcours, plus un écran avec code et QR pour les navigateurs de TV. Ce tutoriel détaille l'installation, la configuration et l'aide à apporter à vos utilisateurs quand quelque chose ne fonctionne pas.

Ce que cela résout

Le plugin s'appuie sur le Quick Connect natif de Jellyfin et ne le remplace pas. Les codes sont créés et expirés par Jellyfin lui-même ; le plugin ne fait que les approuver. Cela a une conséquence pratique que j'apprécie en auto-hébergement : si vous retirez un jour le plugin, aucun compte n'est bloqué, car les mots de passe restent exactement tels que Jellyfin les gère. Il n'y a volontairement aucun code à usage unique à saisir à la place du mot de passe (contrairement à la version Emby du produit) — chaque connexion passe par le Quick Connect de Jellyfin.

Ce que vous obtenez :

• Une page sur le téléphone (/Connect/Page sur l'adresse de votre Jellyfin) avec un QR code qui approuve le code Quick Connect de n'importe quelle application Jellyfin : Android TV, Fire TV, webOS, Tizen, Roku, iOS ou Jellyfin Web.
• Une page écran pour les navigateurs de TV (/Connect/Screen) qui affiche le code et un QR code menant à la page du téléphone ; après approbation, elle se connecte ensuite à Jellyfin Web d'elle-même.
• Un panneau d'administration dans le tableau de bord Jellyfin avec l'état de Quick Connect, les paramètres et les approbations récentes.

Prérequis

• Jellyfin Server 12.2 ou plus récent (Linux, Windows ou Docker).
• Quick Connect activé dans Jellyfin (Tableau de bord → Général). La page du plugin affiche son état et peut l'activer pour vous.
• Un compte MediaLab Works avec une licence qui couvre le plugin — un abonnement actif, une licence à vie dans sa fenêtre de mises à jour, le bundle Jellyfin, ou l'essai gratuit de 30 jours.

Étape 1 — Installer le plugin

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

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 ; vous pouvez la régénérer ou la révoquer à tout moment.
2. Dans Jellyfin, ouvrez Tableau de bord → Plugins → Dépôts, cliquez sur +, donnez-lui un nom (par exemple MediaLab Works), collez l'adresse et enregistrez.
3. Dans Tableau de bord → Plugins → Catalogue, trouvez Quick Connect by MediaLab, cliquez sur Installer, puis redémarrez Jellyfin.

Depuis le catalogue public. https://medialab.works/jellyfin/manifest.json liste chaque plugin MediaLab Works publié avec sa build publique. Ajoutez-le de la même façon si vous voulez installer avant d'avoir une clé ; le plugin demande alors la licence, ou démarre l'essai, sur sa page Licence.

Manuellement, depuis un zip. Téléchargez jf-quickconnect_x.y.z.zip depuis Compte → Licences (le SHA-256 est affiché à côté du bouton), extrayez-le dans un nouveau dossier Quick Connect by MediaLab_x.y.z.0 dans le dossier des plugins Jellyfin — /var/lib/jellyfin/plugins/ pour une installation par paquet sous Linux, /config/plugins/ dans le volume de configuration de l'image Docker officielle, %ProgramData%\Jellyfin\Server\plugins\ sous Windows — et redémarrez Jellyfin.

Étape 2 — Activer la licence

1. Ouvrez Tableau de bord → Plugins → Quick Connect by MediaLab et cliquez sur Licence.
2. Collez votre clé de licence et cliquez sur Activer avec la clé. Le plugin contacte le serveur de licences, lie la clé à ce serveur et affiche la licence comme Active.
3. Pas encore de clé ? Sur la même page, saisissez votre e-mail pour démarrer l'essai gratuit de 30 jours, ou achetez une licence ; le plugin s'active de lui-même 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 7 jours après la dernière vérification réussie. Si vous changez de serveur, Déplacer la licence (libérer ce serveur) sur la même page libère la clé.

Étape 3 — Vérifier que Quick Connect est activé

Ouvrez Quick Connect dans le menu du tableau de bord Jellyfin. Le premier panneau indique si le Quick Connect de Jellyfin est activé. S'il indique qu'il est désactivé, cliquez sur Activer Quick Connect (ou faites-le dans Tableau de bord → Général). Tant qu'il est désactivé, les applications Jellyfin ne peuvent pas du tout demander de codes : c'est donc la première chose à vérifier quand un utilisateur signale un problème.

Étape 4 — Choisir vos paramètres

Dans le même panneau :

• Les pages téléphone et écran sont actives — votre interrupteur principal pour les pages propres au plugin.
• Approbation depuis le téléphone avec identifiant + mot de passe également — utile pour les téléphones où Jellyfin n'est pas connecté. Désactivez-la si vous voulez que les approbations viennent uniquement d'un téléphone qui a déjà une session Jellyfin.
• Les comptes administrateurs ne peuvent pas approuver via la page téléphone — désactivé par défaut ; à activer si vous voulez que les comptes administrateurs restent en dehors du parcours de connexion TV.

Sous Comment l'utiliser, vous trouverez les deux adresses sur votre serveur : la page du téléphone (/Connect/Page) et la page écran (/Connect/Screen). Partagez l'adresse de la page du téléphone avec vos utilisateurs, ou placez son QR code à côté de la TV. Le parcours complet est décrit dans le guide utilisateur.

Étape 5 — Montrer à vos utilisateurs comment cela marche

Dans une application Jellyfin sur la TV (Android TV, Fire TV, webOS, Tizen, Roku et les autres) : choisissez Quick Connect sur l'écran de connexion. L'application affiche un code à 6 chiffres.

Dans un navigateur de TV : ouvrez la page écran. Elle affiche le code et un QR code qui mène à la page du téléphone.

Sur le téléphone : scannez le QR code ou ouvrez la page du téléphone, saisissez le code s'il n'est pas déjà rempli, puis approuvez en un geste en tant qu'utilisateur Jellyfin déjà connecté sur le téléphone, ou avec un identifiant et un mot de passe. La TV se connecte d'elle-même.

Pas encore de compte ? Avec Registration installé, la page du téléphone affiche un lien pour en créer un — pratique quand une nouvelle personne rejoint le foyer et que vous ne voulez pas non plus lui faire traverser un clavier de TV.

Points de sécurité à connaître

• Les codes sont ceux de Jellyfin : Jellyfin les crée et ils expirent d'eux-mêmes. Le plugin ne fait que les approuver.
• 10 tentatives erronées (codes ou mots de passe incorrects) depuis une même adresse en 10 minutes bloquent celle-ci pendant 10 minutes.
• Les comptes désactivés sont refusés, et en option les comptes administrateurs ne peuvent pas approuver via la page du téléphone.
• Les pages téléphone et écran sont servies avec une politique de sécurité du contenu stricte et n'envoient pas de référent.
• Chaque approbation est journalisée avec l'utilisateur, l'adresse et le mode d'approbation ; le panneau liste les approbations récentes.

Côté données : les QR codes sont générés sur le serveur, et les pages écran et téléphone ne chargent que les fichiers du plugin. Les codes en attente vivent en mémoire ; state/approvals.json conserve les 500 dernières approbations (heure, utilisateur, appareil, application, IP, méthode). Les mots de passe et les jetons ne sont jamais envoyés à des tiers. Après la connexion, la TV ou le navigateur est redirigé vers l'adresse définie par l'administrateur (par défaut : l'interface web du serveur), et le jeton de session est écrit dans le stockage du navigateur avant la redirection, jamais placé dans l'URL. Les adresses locale et externe sont en HTTPS uniquement.

Astuces et dépannage

« Quick Connect is not available on this server. » Activez Quick Connect dans Jellyfin (le panneau a un bouton pour cela) et vérifiez que la licence du plugin est active.

« The code is not valid or has expired. » Vérifiez les chiffres sur la TV ; les codes de Jellyfin expirent au bout d'un moment. Demandez-en un nouveau à l'application.

« Too many attempts. » Attendez 10 minutes. Le blocage est par adresse, donc un NAT partagé peut toucher plusieurs utilisateurs à la fois — si cela arrive souvent, vérifiez si quelqu'un saisit régulièrement le mauvais code plutôt que de supposer que le plugin est cassé.

Une licence à vie et les mises à jour automatiques. Le catalogue public propose toujours la version la plus récente. Quand la fenêtre de mises à jour d'une licence à vie est terminée, les versions publiées après ne sont pas couvertes : si les mises à jour automatiques de plugins de Jellyfin en installent une, le plugin s'arrête avec « version not licensed » jusqu'à ce que vous utilisiez Revenir à x.y.z sur sa page Licence ou achetiez un accès aux mises à jour. Pour l'éviter, utilisez votre dépôt privé, qui ne propose que les versions autorisées par votre licence, ou retirez les déclencheurs de la tâche planifiée Update Plugins dans Tableau de bord → Tâches planifiées (cela arrête les mises à jour automatiques pour tous les plugins).

Quelque chose a cassé après une mise à jour. Sur la page Licence, Revenir à x.y.z installe la version précédente ; redémarrez Jellyfin ensuite. Cela désactive la mise à jour automatique de Jellyfin pour le plugin jusqu'à la prochaine Installer la mise à jour, afin que la tâche quotidienne ne ramène pas la version plus récente.

Couverture des clients. Le parcours écran et téléphone a été émulé dans Chrome avec un User-Agent Philips NETTV (25/25) mais n'a pas été testé sur des TV physiques. L'approbation des codes depuis les applications Quick Connect natives a été simulée via l'API avec le client « Jellyfin Android TV » ; les vrais Android TV, Swiftfin, Findroid, Kodi/JellyCon, Infuse et Streamyfin n'ont pas été testés. Si un client particulier se comporte mal, c'est un retour utile — dites-le-nous.

Conclusion

Saisir un mot de passe à la télécommande est une friction que vous pouvez supprimer sans rien affaiblir : les codes restent ceux de Jellyfin, les mots de passe restent ceux de Jellyfin, et le plugin rend simplement l'étape d'approbation évidente. Installez-le depuis votre dépôt privé, activez Quick Connect dans le tableau de bord, décidez si les approbations depuis le téléphone peuvent utiliser identifiant + mot de passe, et placez l'adresse de la page du téléphone là où vos utilisateurs la trouveront. Plus de détails sur la page produit, le journal des modifications pour les notes de version et de code source, et notre base de connaissances et FAQ pour le reste de la pile.