legacy-arrflix/docs/29-jellyfin-10.11-upgrade-and-scyfin-migration.md

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

# /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:

@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:

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:

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):

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.

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.)