diff --git a/docs/29-jellyfin-10.11-upgrade-and-scyfin-migration.md b/docs/29-jellyfin-10.11-upgrade-and-scyfin-migration.md new file mode 100644 index 0000000..b3a7ac7 --- /dev/null +++ b/docs/29-jellyfin-10.11-upgrade-and-scyfin-migration.md @@ -0,0 +1,153 @@ +# 29 — Jellyfin 10.11.8 upgrade + scyfin theme migration (dev) + +Date: 2026-05-11 +Scope: `jellyfin-dev` (dev.arrflix.s8n.ru) only. Prod still on 10.10.3. +Trigger: home-section bug in 10.10.3 — `POST /DisplayPreferences/usersettings?client=Jellyfin%20Web` updated `CustomPrefs` but did NOT insert into the `HomeSection` table. Web UI ignored the layout and rendered factory defaults including Next Up. Verified fixed on 10.11.8 — see § 5. + +--- + +## 1. Migration path (executed) + +``` +10.10.3 → 10.10.7 → snapshot → 10.11.8 +``` + +Direct 10.10.3 → 10.11.x is unsupported. Skipping 10.10.7 is the most common cause of `MigrateLibraryDb` crashes (jellyfin#15027, #15244, #15293, #15504). Both stages take ~10s on our 176MB config. + +### Snapshots kept + +``` +/home/user/snapshots/jellyfin-dev-pre-1011-upgrade-20260511-033309.tar.zst (137M) +/home/user/snapshots/jellyfin-dev-post-10107-20260511-033839.tar.zst (138M) +``` + +Both produced via privileged Alpine + `tar --zstd` because userns-remap blocks tar from writing back to host bind paths (per `feedback_docker_sudo_bypass.md`). + +### Compose change + +```yaml +# /opt/docker/jellyfin-dev/docker-compose.yml +- image: jellyfin/jellyfin:10.10.3 ++ image: jellyfin/jellyfin:10.11.8 +``` + +No volume changes. No env-var changes. Same `user: "1000:1000"`, `userns_mode: "host"`, same index.html bind-mount path (`/jellyfin/jellyfin-web/index.html`). + +--- + +## 2. Schema changes observed + +- `library.db` consolidated into `jellyfin.db` (EF Core finalisation). Old DB removed. +- New tables: `BaseItems`, `BaseItemImageInfos`, `BaseItemMetadataFields`, `BaseItemProviders`, `BaseItemTrailerTypes`, `ItemValuesMap`, `MediaStreamInfos`, `AttachmentStreamInfos`, `KeyframeData`, `PeopleBaseItemMap`, `Peoples`. (Old `TypedBaseItems`, `mediastreams`, `People` are gone.) +- `DisplayPreferences` + `HomeSection` schema unchanged — same columns as 10.10.3. +- ffmpeg bumped 7.0.2 → 7.1.3 (better tonemapping). + +Internal migrations applied automatically: +``` +20251009200000_CleanMusicArtist +20260206200000_FixLibrarySubtitleDownloadLanguages +``` + +--- + +## 3. Theme switch — Cineplex v1.0.6 → scyfin OLED + +Reasons: +- Cineplex pinned to 10.10.x, abandoned for 10.11. +- scyfin (https://github.com/loof2736/scyfin) is the only top-tier 10.11.x theme with a dedicated 10.11 branch + recent release (v1.5.3, 2026-03-25) + zero open 10.11 bug reports. +- OLED variant gives a true black palette aligned with full-bleed ARRFLIX backdrop goals. + +Imports: +```css +@import url('https://cdn.jsdelivr.net/gh/loof2736/scyfin@latest/CSS/scyfin-theme.css'); +@import url('https://cdn.jsdelivr.net/gh/loof2736/scyfin@latest/CSS/theme-oled.css'); +``` + +Plus ARRFLIX-specific overrides (accent `#E50914`, force-English Play button, hide Cast & Crew / Quick Connect / Cast / SyncPlay, themed scrollbar). Full CustomCss in `/tmp/dev-branding.json` and applied via: + +```bash +curl -X POST -H "X-Emby-Token: $TOK" -H "Content-Type: application/json" \ + --data-binary @branding.json \ + https://dev.arrflix.s8n.ru/System/Configuration/branding +``` + +(POST returned 500 but the write persisted — verified via GET. Likely an EphemeralXmlRepository warning side-effect; non-blocking.) + +--- + +## 4. Home-section bug — fixed in 10.11.8 + +The 10.10.3 bug: posting CustomCss-style `homesection0…9` keys updated `CustomPrefs` but did NOT insert into the `HomeSection` table. The web client (10.10 + 10.11) reads `HomeSection` rows for `client="Jellyfin Web"`, so the legacy POST was a no-op visually. + +On 10.11.8 the same endpoint accepts a `HomeSections` array in the request body and writes both `CustomPrefs` and `HomeSection` rows atomically. Tested: + +```bash +curl -X POST -H "X-Emby-Token: $TOK" -H "Content-Type: application/json" \ + "https://dev.arrflix.s8n.ru/DisplayPreferences/usersettings?userId=$UID&client=Jellyfin%20Web" \ + -d '{"Id":"","SortBy":"SortName",..., + "CustomPrefs":{"homesection0":"resume","homesection1":"latestmedia", ...}, + "HomeSections":[{"Order":0,"Type":"Resume"},{"Order":1,"Type":"LatestMedia"},{"Order":2,"Type":"None"}, ...], + "Client":"Jellyfin Web"}' +``` + +→ HTTP 204 + DB shows `Type=4` at slot 0, `Type=6` at slot 1, `Type=0` everywhere else. + +Type integer reference (`Jellyfin.Data.Enums.HomeSectionType`): +``` +0 = None +1 = SmallLibraryTiles +2 = LibraryButtons +3 = ActiveRecordings +4 = Resume +5 = ResumeAudio +6 = LatestMedia +7 = NextUp <-- explicitly excluded by ARRFLIX policy +8 = LiveTv +9 = ResumeBook +``` + +ARRFLIX policy is now: **slot 0 = Resume, slot 1 = LatestMedia, slot 2-9 = None**. Continue Watching is always on, Next Up never. + +--- + +## 5. Plugin compat + +- OpenSubtitles **v20** (current prod) has `targetAbi: 10.9.0.0` — will NOT load on 10.11.x. +- v24 with `targetAbi: 10.11.8.0` is required (jellyfin-plugin-opensubtitles#166). +- Known regression: server issue #16544 reports SRT save failing on 10.11.7+ — workaround = Bazarr proxy. Re-test on dev before promoting to prod. + +Plugin upgrade command (deferred until we validate the rest): +```bash +curl -X POST -H "X-Emby-Token: $TOK" \ + "https://dev.arrflix.s8n.ru/Packages/Installed/Open%20Subtitles?AssemblyGuid=4b9ed42f-5185-48b5-9803-6ff2989014c4&Version=24.0.0.0&RepositoryUrl=https%3A%2F%2Frepo.jellyfin.org%2Ffiles%2Fplugin%2Fmanifest.json" +docker restart jellyfin-dev +``` + +--- + +## 6. Outstanding before promoting dev → prod + +- [ ] Test scyfin OLED rendering across home / detail / playback / settings on dev. +- [ ] Verify Continue Watching renders for `test` user (5 resume items present). +- [ ] OpenSubtitles v24 install + smoke test on a Polish-audio episode. +- [ ] Re-test HW accel — ffmpeg 7.1.3 changed tonemap; verify 4K HDR R&M still transcodes. +- [ ] Update prod compose to `jellyfin/jellyfin:10.10.7` → snapshot → `10.11.8`. +- [ ] Re-run `bin/set-home-layout.py` against prod once on 10.11.8 — should now work via API alone, no DB hack needed. +- [ ] Retire `bin/fix-home-db.sh` from the canonical playbook (kept as emergency-only). + +--- + +## 7. Rollback (if scyfin or any 10.11.8 behaviour blocks promotion) + +EF Core migrations are forward-only — 10.10.3 will not start against a 10.11.x DB. + +```bash +docker stop jellyfin-dev +docker run --rm --userns=host -v /home/docker:/dst alpine sh -c \ + "apk add --no-cache zstd tar; cd /dst; rm -rf jellyfin-dev/config; \ + tar -I 'zstd -d' -xf /dst/snap/jellyfin-dev-pre-1011-upgrade-*.tar.zst" +sed -i 's|10.11.8|10.10.3|' /opt/docker/jellyfin-dev/docker-compose.yml +docker compose -f /opt/docker/jellyfin-dev/docker-compose.yml up -d +``` + +(Snapshot path is `/home/user/snapshots/`. Mount it into the alpine helper if needed.)