Integrate native decoder TV and internet EPG artwork with Jellyfin 12.2

README.integration.md

@@ -0,0 +1,54 @@
+# Enigma2 dla Jellyfin 12.2
+
+Lokalne rozszerzenie wtyczki Enigma2 6.0.0.0, wersja 7.0.0.0. Zachowuje identyfikator wtyczki, nazwę usługi, konfigurację połączenia, natywne strumienie, nagrania i timery dekodera. Profile transkodowania pozostają na dekoderze.
+
+## Funkcje
+
+- Pełna lista 216 kanałów skonfigurowanego bukietu „Polskie”, z numerami, logo i wyszukiwaniem. Stronicowanie API obsługuje również większe listy.
+- Ulubione, ukrywanie, kolejność i domyślny widok osobno dla każdego użytkownika. Ulubione synchronizują się z natywnym Jellyfinem. Ukrywanie i kolejność są nakładane także na natywny endpoint `/LiveTv/Channels`, po kontroli uprawnień i przed stronicowaniem; widok domyślny dotyczy strony dodatku.
+- Globalny przełącznik **Obsługuj nagrania z Vu+ (Enigma2 Recordings)** w konfiguracji wtyczki Enigma2, domyślnie wyłączony. Wyłączenie nie rejestruje dostawcy biblioteki nagrań, pozostawia telewizję, EPG oraz timery i nie usuwa plików z dekodera. Zmiana wymaga restartu Jellyfina oraz odświeżenia kanałów dostawców. Nie jest to przełącznik na stronie kanałów.
+- Widok audycji na najbliższe sześć godzin, przejścia do szczegółów kanału/audycji oraz natywnego przewodnika, nagrań i timerów.
+- Rzeczywiste grafiki audycji z `https://epg.polishteam.one/guide.xml`, pobierane i buforowane przez Jellyfin. Brak generowania obrazków.
+- Konserwatywne dopasowanie po jednoznacznym kanale, dokładnym znormalizowanym tytule oraz czasie rozpoczęcia ±7 minut. Brak zgadywania przy niejednoznacznych danych. Harmonogram i EIT do timerów pozostają z Enigmy.
+- Stałe identyfikatory audycji: service reference, EIT i początek emisji, zamiast losowej liczby. Poprawiona deduplikacja i cache kanałów przy odczycie wielu bukietów.
+
+## Otwieranie
+
+Jellyfin Web → menu **Telewizja dekodera**. Bezpośrednio: `/DecoderIntegration/Channels` na tym samym serwerze i adresie, pod którym użytkownik loguje się do Jellyfina. Strona korzysta z zapisanej sesji Jellyfin Web; wymagane logowanie z opcją **Zapamiętaj mnie**. Nie ma oddzielnych kont ani haseł dodatku. Bez zapisanej sesji strona pokazuje odnośnik do logowania.
+
+W Jellyfin 10.11 strony `configurationpage` są ograniczone do administratorów w routerze klienta. Dlatego dla wszystkich użytkowników użyto standardowego `menuLinks` w `/usr/share/jellyfin/web/config.json` i strony HTML serwowanej przez wtyczkę. API preferencji wymaga uprawnienia Live TV i identyfikuje użytkownika z uwierzytelnionych claims, bez przyjmowania dowolnego UserId od klienta. Administracyjny stan importu: `GET /DecoderIntegration/Status`.
+
+Grafiki trafiają do natywnego EPG i są dostępne również w innych klientach Jellyfina. Własna strona i jej układ są funkcją przeglądarkową; nie zmieniają interfejsu aplikacji Android TV. Uprawnienia kanałów nadal egzekwuje natywne API Jellyfina.
+
+## Źródła i ograniczenia
+
+Sprawdzono 11.10.2026: [wydania autora](https://github.com/knackebrot/jellyfin-plugin-enigma2/releases) i [manifest](https://github.com/knackebrot/jellyfin-repo/blob/master/manifest.json) nadal wskazują **6.0.0.0, 22.06.2024**, jako najnowsze opublikowane wydanie. **7.0.0.0 jest wersją lokalną tego projektu**, nie oficjalnym wydaniem autora. Pochodzenie vendora: `UPSTREAM.txt`, licencja CC0.
+
+Źródło grafik: PolishTeam. Dozwolone adresy obrazków to HTTPS na `ptv-prod.wphcdn.cloud` i `media.teleman.pl`; dane XML mają limit 128 MiB i zablokowane DTD/encje zewnętrzne. Brak pasującej grafiki pozostawia dotychczasowe dane Enigmy. Awaria importu nie blokuje telewizji. Feed jest odświeżany najwyżej co 6 h przy odświeżaniu przewodnika; po błędzie ponowna próba po 15 minutach, ostatni dobry cache ważny do 48 h. Cache feedu jest w pamięci, po restarcie pobiera się ponownie.
+
+Nie wszystkie audycje mają zgodny tytuł i grafikę w źródle. Dostępność zewnętrznego feedu nie jest gwarantowana. Pełne odświeżanie EPG i cache zdjęć może potrwać; dopiero zakończone natywne Refresh Guide usuwa stare losowe identyfikatory audycji.
+
+## Budowanie i wdrożenie
+
+SDK .NET 10, `dotnet run --project Tests -c Release`. Projekt odwołuje się do Jellyfin 12.2. Testy konsolowe sprawdzają dopasowanie, niejednoznaczność, zakres czasu, alias HD, ograniczenia URL i walidację preferencji.
+
+Budowano w izolowanym `mcr.microsoft.com/dotnet/sdk:10.0` na CT100195 z limitem dwóch CPU i osobnym katalogiem `/tmp/jellyfin-decoder-plugin`. Nie zmieniono usług serwera strumieniowego. Artefakt: `Jellyfin.Plugin.Enigma2/bin/Release/net10.0/Jellyfin.Plugin.Enigma2.dll`.
+
+`deploy.py` uruchamia się w CT100191 po umieszczeniu DLL w `/tmp/Jellyfin.Plugin.Enigma2.dll`. Odmawia restartu przy aktywnym odtwarzaniu. Zachowuje stare katalogi wtyczki, konfigurację oraz web-config w `/var/lib/jellyfin/decoder-plugin-backups/<UTC>`, przenosi starą wersję poza katalog plugins i instaluje nową z zachowaniem tożsamości. Restartuje tylko Jellyfin, nie dekoder.
+
+Powrót po aktualizacji serwera wymaga przywrócenia **pełnej kopii danych i konfiguracji sprzed migracji oraz pakietów Jellyfin 10.11.6**. Sama zamiana DLL nie cofa zmian bazy danych. W obrębie Jellyfina 12.2 można przywrócić poprzednią zgodną wersję dodatku z kopii wdrożenia. Wrapper FFmpeg i profile odbiornika są zachowane.
+
+`verify.py` sprawdza aktywność wtyczki, kanały, timery, izolację preferencji dwóch kont i politykę administracyjną. Konta testowe usuwa w finally. `test-browser.cjs` sprawdza rzeczywisty Jellyfin Web w izolowanym Edge headless i usuwa własne konto. Nie drukuje tokenów ani haseł.
+
+Kod jest także aktualizowany w `C:\Users\michal\git\jellyfin-plugin-enigma2` na gałęzi `codex/decoder-integration`. Dodatkowy remote `ekacprzak`: `ssh://git@git.e-kacprzak.eu:2222/michal/jellyfin-plugin-enigma2.git`. Zmiany wtyczki są wypychane wyłącznie do tego remote; GitHub origin pozostaje źródłem upstream.
+
+Przed końcowym wyłączeniem dostawcy ukryto jego kafelek i ostatnio dodane na 19 istniejących kontach przez natywne MyMediaExcludes/LatestItemsExcludes (wyraźna zgoda użytkownika); kopia poprzednich ustawień: `/var/lib/jellyfin/decoder-plugin-backups/home-exclusions-20261011T104028Z.json`. `hide-recordings-home.py` dokumentuje ten jednorazowy krok. Nie jest mechanizmem przełącznika obsługi nagrań. Po ewentualnym ponownym włączeniu dostawcy użytkownicy mogą odznaczyć wykluczenie biblioteki w ustawieniach ekranu głównego.
+
+
+## Aktualizacja serwera 11.10.2026
+
+Jellyfin w CT100191 zaktualizowano z 10.11.6 do **12.2.0**, FFmpeg do **8.1.3**. Pełna kopia po zatrzymaniu serwera: `/var/backups/jellyfin-pre12-20261011T110237Z/data-config.tar` (9 465 702 400 bajtów). Migracje zakończyły się pomyślnie; zachowano 19 kont, 216 kanałów i 33 timery. LDAP 19/22 usunięto, SSO zachowano. Test inicjacji OIDC z Host `jellyfin.e-kacprzak.eu` zwrócił 302 do `login.e-kacprzak.eu`; adres techniczny nie jest dozwolonym callbackiem w Keycloak. Pełnego logowania użytkownika w Keycloak nie automatyzowano.
+
+SSO autora nie ma jeszcze paczki ABI 12. Przygotowano lokalny build 4.0.0.4 z upstream `f1e157bac29e6d27a0844378f3e1d4a4fdaa577a`, .NET10 i zależnościami Jellyfin12.2. Usunięto starą referencję XML cryptography6, przypięto Pkcs10; build bez ostrzeżeń i błędów. Reprodukcja bez instalacji: `python3 compat/build-sso12.py` na Linuxie z Dockerem. Oficjalne dodatki: DLNA14, OpenSubtitles25, TVmaze14, Webhook22, SessionCleaner6. Kopia starych paczek: `/var/lib/jellyfin/decoder-plugin-backups/upgrade12-20261011T110701Z`.
+
+Enigma7 aktywna. Obsługa nagrań Vu wyłączona w konfiguracji, lista dostawców `/Channels` pusta. Testy konsolowe obejmują także rejestrację przed utworzeniem Plugin.Instance i odpowiedzi przy Accept-Encoding gzip/br. Test API: preferencje dwóch kont, natywna lista/paginacja, uprawnienia administracyjne. Test Edge headless: 216 kanałów, ulubione, ukrywanie/przywracanie, EPG, brak błędów JS. Po aktualizacji uruchomiono pełny skan bibliotek i odświeżanie EPG.