Conectare rapidă Jellyfin pe televizor: cod QR și aprobare de pe telefon

Dacă administrezi Jellyfin pentru o gospodărie, știi deja care e cea mai neplăcută parte a serii: cineva deschide aplicația pe televizor, apare ecranul de autentificare și trebuie tastată o parolă de pe telecomandă. Taste cu săgeți, tastatură pe ecran, un caracter greșit, de la capăt. E cel mai frecvent motiv pentru care oamenii te roagă să îi „autentifici tu” pe serverul tău.

Jellyfin are deja propria funcție Quick Connect: aplicația de pe televizor afișează un cod din 6 cifre, iar un utilizator autentificat îl aprobă în altă parte. Partea incomodă este unde — să găsești acel ecran adânc în setările Jellyfin de pe un telefon nu e evident pentru majoritatea oamenilor. Conectare rapidă de la MediaLab pune în fața acestui flux o pagină scurtă de telefon cu cod QR, plus un ecran cu cod și cod QR pentru browserele televizoarelor. Acest tutorial parcurge instalarea, configurarea și modul în care îți ajuți utilizatorii când ceva nu funcționează.

Ce rezolvă

Plugin-ul se bazează pe funcția Quick Connect nativă din Jellyfin și nu o înlocuiește. Codurile sunt create și expirate de Jellyfin însuși; plugin-ul doar le aprobă. Asta are o consecință practică ce îmi place ca self-hoster: dacă vreodată elimini plugin-ul, niciun cont nu rămâne blocat, pentru că parolele rămân exact așa cum le gestionează Jellyfin. Intenționat nu există un cod de unică folosință tastat în locul parolei (spre deosebire de versiunea pentru Emby a produsului) — fiecare autentificare trece prin Quick Connect-ul propriu al Jellyfin.

Ce obții:

• O pagină de telefon (/Connect/Page pe adresa ta Jellyfin) cu cod QR care aprobă codul Quick Connect al oricărei aplicații Jellyfin: Android TV, Fire TV, webOS, Tizen, Roku, iOS sau Jellyfin Web.
• O pagină de ecran pentru browserele televizoarelor (/Connect/Screen) care afișează codul și un cod QR ce duce la pagina de telefon; după aprobare se autentifică singură în Jellyfin Web.
• Un panou de administrare în dashboard-ul Jellyfin cu starea Quick Connect, setările și aprobările recente.

Cerințe preliminare

• Jellyfin Server 12.2 sau mai nou (Linux, Windows sau Docker).
• Quick Connect pornit în Jellyfin (Dashboard → General). Pagina plugin-ului arată starea și îl poate porni pentru tine.
• Un cont MediaLab Works cu o licență care acoperă plugin-ul — un abonament activ, o licență pe viață în fereastra sa de actualizare, pachetul Jellyfin sau perioada de probă gratuită de 30 de zile.

Pasul 1 — Instalează plugin-ul

Din depozitul tău privat (recomandat). Jellyfin va instala și actualiza apoi plugin-ul singur.

1. În contul tău MediaLab Works deschide Licenses → Jellyfin plugin repository și apasă Create address. Copiaz-o — conține un token, așa că păstreaz-o privată; o poți regenera sau revoca oricând.
2. În Jellyfin deschide Dashboard → Plugins → Repositories, apasă +, dă-i un nume (de exemplu MediaLab Works), lipește adresa și salvează.
3. În Dashboard → Plugins → Catalog găsește Quick Connect by MediaLab, apasă Install, apoi repornește Jellyfin.

Din catalogul public. https://medialab.works/jellyfin/manifest.json listează fiecare plugin MediaLab Works publicat, cu build-ul său public. Adaugă-l la fel dacă vrei să instalezi înainte de a avea o cheie; plugin-ul îți cere apoi licența sau pornește perioada de probă pe pagina sa License.

Manual, dintr-un zip. Descarcă jf-quickconnect_x.y.z.zip din Account → Licenses (SHA-256 este afișat lângă buton), extrage-l într-un folder nou Quick Connect by MediaLab_x.y.z.0 în interiorul folderului de plugin-uri Jellyfin — /var/lib/jellyfin/plugins/ la o instalare din pachet Linux, /config/plugins/ în volumul de configurare la imaginea Docker oficială, %ProgramData%\Jellyfin\Server\plugins\ pe Windows — și repornește Jellyfin.

Pasul 2 — Activează licența

1. Deschide Dashboard → Plugins → Quick Connect by MediaLab și apasă License.
2. Lipește cheia de licență și apasă Activate with key. Plugin-ul contactează serverul de licențe, leagă cheia de acest server și afișează licența ca Active.
3. Nu ai încă o cheie? Pe aceeași pagină introdu e-mailul pentru a porni perioada de probă gratuită de 30 de zile sau cumpără o licență; plugin-ul se activează singur când plata este finalizată.

Licența este verificată o dată pe zi și la fiecare pornire a Jellyfin. Fără internet, plugin-ul funcționează în continuare 7 zile după ultima verificare reușită. Dacă muți serverul, Move license (release this server) de pe aceeași pagină eliberează cheia.

Pasul 3 — Verifică dacă Quick Connect este pornit

Deschide Quick Connect din meniul dashboard-ului Jellyfin. Primul panou arată dacă Quick Connect-ul propriu al Jellyfin este activat. Dacă scrie că este oprit, apasă Turn on Quick Connect (sau fă-o în Dashboard → General). Cât timp este oprit, aplicațiile Jellyfin nu pot cere deloc coduri, așa că acesta este primul lucru de verificat când un utilizator raportează o problemă.

Pasul 4 — Stabilește setările

În același panou:

• The phone and screen pages are active — întrerupătorul principal pentru paginile proprii ale plugin-ului.
• Approval from the phone with username + password too — util pentru telefoanele pe care Jellyfin nu este autentificat. Dezactivează-l dacă vrei aprobări doar de pe un telefon care are deja o sesiune Jellyfin.
• Administrator accounts cannot approve through the phone page — oprit implicit; merită pornit dacă vrei ca conturile de administrator să rămână în afara fluxului de autentificare pe televizor.

La How to use găsești cele două adrese de pe serverul tău: pagina de telefon (/Connect/Page) și pagina de ecran (/Connect/Screen). Împărtășește adresa paginii de telefon cu utilizatorii tăi sau pune codul ei QR lângă televizor. Ghidul complet este în user guide.

Pasul 5 — Arată utilizatorilor tăi cum funcționează

Într-o aplicație Jellyfin pe televizor (Android TV, Fire TV, webOS, Tizen, Roku și celelalte): alege Quick Connect pe ecranul de autentificare. Aplicația afișează un cod din 6 cifre.

Într-un browser de televizor: deschide pagina de ecran. Aceasta afișează codul și un cod QR care duce la pagina de telefon.

Pe telefon: scanează codul QR sau deschide pagina de telefon, tastează codul dacă nu este deja completat, apoi aprobă cu o atingere ca utilizator Jellyfin deja autentificat pe telefon, sau cu nume de utilizator și parolă. Televizorul se autentifică singur.

Nu ai încă un cont? Cu Registration instalat, pagina de telefon afișează un link pentru a crea unul — util când o persoană nouă se alătură gospodăriei și nu vrei să o ghidezi nici pe ea prin tastatura televizorului.

Note de securitate de știut

• Codurile sunt ale Jellyfin: Jellyfin le creează și expiră singur. Plugin-ul doar le aprobă.
• 10 încercări greșite (coduri greșite sau parole greșite) de la o adresă în 10 minute o blochează pentru 10 minute.
• Conturile dezactivate sunt refuzate, iar opțional conturile de administrator nu pot aproba prin pagina de telefon.
• Paginile de telefon și de ecran sunt servite cu o politică strictă de securitate a conținutului și nu trimit referrer.
• Fiecare aprobare este înregistrată cu utilizatorul, adresa și modul de aprobare; panoul listează aprobările recente.

Despre date: codurile QR sunt generate pe server, iar paginile de ecran și de telefon încarcă doar fișierele plugin-ului. Codurile în așteptare stau în memorie; state/approvals.json păstrează ultimele 500 de aprobări (timp, utilizator, dispozitiv, aplicație, IP, metodă). Parolele și tokenurile nu sunt trimise niciodată unor terți. După autentificare, televizorul sau browserul este trimis la adresa stabilită de administrator (implicit: interfața web a serverului), iar tokenul de sesiune este scris în stocarea browserului înainte de redirecționare, niciodată pus în URL. Adresele locale și externe sunt doar HTTPS.

Sfaturi și depanare

„Quick Connect is not available on this server.” Pornește Quick Connect în Jellyfin (panoul are un buton pentru asta) și verifică dacă licența plugin-ului este activă.

„The code is not valid or has expired.” Verifică cifrele de pe televizor; codurile Jellyfin expiră după un timp. Cere aplicației un cod nou.

„Too many attempts.” Așteaptă 10 minute. Blocarea este pe adresă, așa că un NAT partajat poate afecta mai mulți utilizatori deodată — dacă se întâmplă des, verifică dacă cineva introduce repetat codul greșit, în loc să presupui că plugin-ul e defect.

O licență pe viață și actualizările automate. Catalogul public oferă întotdeauna cea mai nouă versiune. Când fereastra de actualizare a unei licențe pe viață s-a încheiat, versiunile publicate după ea nu sunt licențiate: dacă actualizările automate de plugin-uri ale Jellyfin instalează una, plugin-ul se oprește cu „version not licensed” până când folosești Roll back to x.y.z pe pagina sa License sau cumperi un update pass. Pentru a evita asta, folosește depozitul tău privat, care oferă doar versiunile permise de licența ta, sau elimină declanșatoarele sarcinii programate Update Plugins din Dashboard → Scheduled Tasks (asta oprește actualizările automate pentru toate plugin-urile).

Ceva s-a stricat după o actualizare. Pe pagina License, Roll back to x.y.z instalează versiunea anterioară; repornește Jellyfin după aceea. Asta oprește actualizarea automată a Jellyfin pentru plugin până la următorul Install update, așa că sarcina zilnică nu aduce versiunea mai nouă înapoi.

Acoperirea clienților. Fluxul de ecran și de telefon a fost emulat în Chrome cu un User-Agent Philips NETTV (25/25), dar nu a fost testat pe televizoare fizice. Aprobarea codurilor din aplicațiile Quick Connect native a fost simulată prin API cu clientul „Jellyfin Android TV”; Android TV real, Swiftfin, Findroid, Kodi/JellyCon, Infuse și Streamyfin nu au fost testate. Dacă un anumit client se comportă greșit, acesta este un feedback util — spune-ne.

Concluzie

Tastarea unei parole de pe telecomandă este o frecare pe care o poți elimina fără să slăbești nimic: codurile rămân ale Jellyfin, parolele rămân ale Jellyfin, iar plugin-ul doar face evident pasul de aprobare. Instalează-l din depozitul tău privat, pornește Quick Connect în dashboard, decide dacă aprobările de pe telefon pot folosi nume de utilizator + parolă și pune adresa paginii de telefon unde utilizatorii tăi o pot găsi. Mai multe detalii pe pagina produsului, în changelog pentru note despre versiuni și codul sursă, și în baza noastră de cunoștințe și FAQ pentru restul stack-ului.