fix(177): map Album/Track in the Jellyfin music video projection #555

Merged
timothy merged 1 commits from issue-177-jellyfin-mv-album-track into main 2026-07-21 23:50:19 +02:00
Owner

Jellyfin-sourced music videos rendered weaker MTV-style credits than local NFO libraries: the Scriban credits templates expose Album/Track and MusicVideoNfoReader has always mapped both, but the Jellyfin projection never did.

The fix is two layers, not one

The issue frames this as a single projection change. It isn't:

Layer Change Why
JellyfinLibraryItemResponse add Album not on the DTO at all
JellyfinApiClient.ProjectToMusicVideoMetadata Album = item.Album, Track = item.IndexNumber the change the issue describes — add path only
JellyfinMusicVideoLibraryScanner.UpdateMetadata copy both scalars not in the issue. UpdateMetadata copies fields one by one, so without this an EXISTING music video keeps a stale/empty album forever and only newly-added items benefit — the same class of bug #497 fixed one layer down for child collections

Live-server findings

Verified against the real Jellyfin server (1437 MusicVideo items):

  • No Refit fields change needed. Album comes back on 111 items with fields=Path alone — it is a plain BaseItemDto property, not an ItemFields enum value, so adding it to fields would have been wrong. IndexNumber likewise (4 items). AlbumId is always null.
  • ParentIndexNumber deliberately NOT used for Track. It looks tempting (66 items carry it vs 4 for IndexNumber), but on live data where both are present ParentIndexNumber is 1 while IndexNumber holds the real ordinal (2, 3, 5); where only ParentIndexNumber is present it is a collection/disc grouping that tracks the Album (Glastonbury: 2022 -> 230). It is a different axis, not a track number.

Downstream reach

Wider than the issue's "credits" framing: {{ album }} renders in the _ArtistTitleAlbum_CenterTop overlay, music_video_album / music_video_track in the _musicVideo XMLTV template, plus ChronologicalMediaComparer ordering and the Lucene AlbumField search index.

Verification

  • ErsatzTV.Tests 1797 passed, ErsatzTV.Scanner.Tests 1484 passed, ErsatzTV.Infrastructure.Tests 111 passed — all green locally.
  • Both negative controls confirmed non-vacuous under forced rebuild: removing the projection lines fails Should_Project_Album_And_Track (while Should_Leave_Album_And_Track_Null_When_Absent correctly still passes); removing the UpdateMetadata lines fails ScanLibrary_Should_Update_Album_And_Track_On_Rescan_Of_Existing_Item.
  • Cold independent adversarial review: no findings at >=80 confidence.
  • Emby is genuinely unaffected — it has no music-video projection at all (no MusicVideo match anywhere under ErsatzTV.Infrastructure/Emby or ErsatzTV.Scanner/Core/Emby).

Note

Also strips a pre-existing UTF-8 BOM from JellyfinLibraryItemResponse.cs (already on main; the format gate only trips on it once the file is touched) — per the format-as-you-touch convention.

Expected one-time side effect

Album/Track now participate in the update dirty-check, so the first rescan after deploy marks existing items whose Jellyfin-side album/track differs as IsUpdated and reindexes them. Intentional backfill, identical in shape to the #497 precedent.

fixes #177

Jellyfin-sourced music videos rendered weaker MTV-style credits than local NFO libraries: the Scriban credits templates expose Album/Track and `MusicVideoNfoReader` has always mapped both, but the Jellyfin projection never did. ## The fix is two layers, not one The issue frames this as a single projection change. It isn't: | Layer | Change | Why | |---|---|---| | `JellyfinLibraryItemResponse` | add `Album` | not on the DTO at all | | `JellyfinApiClient.ProjectToMusicVideoMetadata` | `Album = item.Album`, `Track = item.IndexNumber` | the change the issue describes — **add path only** | | `JellyfinMusicVideoLibraryScanner.UpdateMetadata` | copy both scalars | **not in the issue.** `UpdateMetadata` copies fields one by one, so without this an EXISTING music video keeps a stale/empty album forever and only newly-added items benefit — the same class of bug #497 fixed one layer down for child collections | ## Live-server findings Verified against the real Jellyfin server (1437 `MusicVideo` items): - **No Refit `fields` change needed.** `Album` comes back on 111 items with `fields=Path` alone — it is a plain `BaseItemDto` property, not an `ItemFields` enum value, so adding it to `fields` would have been wrong. `IndexNumber` likewise (4 items). `AlbumId` is always null. - **`ParentIndexNumber` deliberately NOT used for `Track`.** It looks tempting (66 items carry it vs 4 for `IndexNumber`), but on live data where both are present `ParentIndexNumber` is `1` while `IndexNumber` holds the real ordinal (2, 3, 5); where only `ParentIndexNumber` is present it is a collection/disc grouping that tracks the Album (`Glastonbury: 2022` -> 230). It is a different axis, not a track number. ## Downstream reach Wider than the issue's "credits" framing: `{{ album }}` renders in the `_ArtistTitleAlbum_CenterTop` overlay, `music_video_album` / `music_video_track` in the `_musicVideo` XMLTV template, plus `ChronologicalMediaComparer` ordering and the Lucene `AlbumField` search index. ## Verification - `ErsatzTV.Tests` 1797 passed, `ErsatzTV.Scanner.Tests` 1484 passed, `ErsatzTV.Infrastructure.Tests` 111 passed — all green locally. - **Both negative controls confirmed non-vacuous under forced rebuild**: removing the projection lines fails `Should_Project_Album_And_Track` (while `Should_Leave_Album_And_Track_Null_When_Absent` correctly still passes); removing the `UpdateMetadata` lines fails `ScanLibrary_Should_Update_Album_And_Track_On_Rescan_Of_Existing_Item`. - Cold independent adversarial review: no findings at >=80 confidence. - Emby is genuinely unaffected — it has no music-video projection at all (no `MusicVideo` match anywhere under `ErsatzTV.Infrastructure/Emby` or `ErsatzTV.Scanner/Core/Emby`). ## Note Also strips a **pre-existing** UTF-8 BOM from `JellyfinLibraryItemResponse.cs` (already on `main`; the format gate only trips on it once the file is touched) — per the format-as-you-touch convention. ### Expected one-time side effect Album/Track now participate in the update dirty-check, so the first rescan after deploy marks existing items whose Jellyfin-side album/track differs as `IsUpdated` and reindexes them. Intentional backfill, identical in shape to the #497 precedent. fixes #177
timothy added 1 commit 2026-07-21 23:24:05 +02:00
fix(177): map Album/Track in the Jellyfin music video projection
PR Gates / CI image pin matches docker/ci (pull_request) Successful in 12s
PR Gates / Docs update reminder (pull_request) Successful in 13s
PR Gates / decisions lifecycle (pull_request) Successful in 13s
Build ErsatzTV Image / Build & test (.NET) (pull_request) Successful in 7m40s
Build ErsatzTV Image / API docs in sync (OpenAPI + endpoint index) (pull_request) Successful in 21s
Build ErsatzTV Image / Formatting (changed .cs conform to .editorconfig) (pull_request) Successful in 18s
Build ErsatzTV Image / EF migration integrity (SQLite + MySql) (pull_request) Successful in 6m10s
Build ErsatzTV Image / Build & push image (amd64) (pull_request) Has been skipped
Build ErsatzTV Image / Functional E2E (curl contracts) (pull_request) Successful in 15m39s
b45dcc7190
Jellyfin-sourced music videos rendered weaker MTV-style credits than local
NFO libraries: the Scriban credits templates expose Album/Track, and
MusicVideoNfoReader has always mapped both, but the Jellyfin projection
never did. ChronologicalMediaComparer orders music videos by the same two
fields, so they were also ordering worse.

Verified against the live server (1437 MusicVideo items): Album comes back
on 111 and IndexNumber on 4, both WITHOUT being named in the `fields` query
param -- Album is a plain BaseItemDto property, not an ItemFields value, so
no Refit `fields` change is needed (and adding one would be wrong).

ParentIndexNumber is deliberately NOT used for Track: on live data, where
both are present ParentIndexNumber is 1 while IndexNumber carries the real
ordinal, and where only ParentIndexNumber is present it is a collection/disc
grouping that tracks the Album ("Glastonbury: 2022" -> 230).

The fix is two layers, not one. The projection alone would only ever reach
music videos ADDED after it -- UpdateMetadata copies scalars field by field,
so an existing item whose album/track is set or corrected in Jellyfin would
keep a stale value forever. That is the same class of bug #497 fixed for
child collections, one layer up.

Also strips a pre-existing UTF-8 BOM from JellyfinLibraryItemResponse.cs,
which the format gate flags once the file is touched (format-as-you-touch).

fixes #177
Author
Owner

Cold independent adversarial review completed against this diff (review-only agent, no implementation role). Traced the full path Jellyfin API -> DTO -> projection -> scanner add path AND update path -> DB -> credits template; specifically attacked the IndexNumber vs ParentIndexNumber choice, test non-vacuousness, Emby scope, and dirty-check side effects.

Result: no findings at >=80 confidence. Both negative controls independently confirmed non-vacuous. The one behavioral side effect (first rescan reindexes existing items whose album/track differs) was assessed as an intentional one-time backfill matching the #497 precedent, not a defect.

Review-verdict: MERGEABLE @ b45dcc7190

Cold independent adversarial review completed against this diff (review-only agent, no implementation role). Traced the full path Jellyfin API -> DTO -> projection -> scanner add path AND update path -> DB -> credits template; specifically attacked the `IndexNumber` vs `ParentIndexNumber` choice, test non-vacuousness, Emby scope, and dirty-check side effects. Result: **no findings at >=80 confidence.** Both negative controls independently confirmed non-vacuous. The one behavioral side effect (first rescan reindexes existing items whose album/track differs) was assessed as an intentional one-time backfill matching the #497 precedent, not a defect. Review-verdict: MERGEABLE @ b45dcc71900c0e85ac82be9624bfe4d4bbf3e01b
timothy merged commit c90a11d2b4 into main 2026-07-21 23:50:19 +02:00
timothy deleted branch issue-177-jellyfin-mv-album-track 2026-07-21 23:50:20 +02:00
Sign in to join this conversation.