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