Skip to content

chore: integrate Wholphin upstream Stage C - #116

Merged
constbogdan merged 3 commits into
mainfrom
chore/upstream-stage-c
Nov 6, 2026
Merged

constbogdan merged 3 commits into
mainfrom
chore/upstream-stage-c

Conversation

@constbogdan

Copy link
Copy Markdown
Owner

Stage C local upstream integration

Authenticated scope and boundary

  • Protected Mosaic main: b8cf05293dbbddc3d6c8473426213b9a696a5f59.
  • Stage B upstream boundary: 55960c24625ef03bc5ac71b58806efdd613ffcc7.
  • Exact Stage C target: 621686d8e2785b0944f3dc730f84f8c0fa7d7356.
  • Observed upstream main: bd46ff3e03c9a9f100fefcc2554be7c245a08c68.
  • Branch chore/upstream-stage-c, worktree C:\Projects\Wholphin\mosaic-upstream-stage-c.
  • Pending native parents, in order: [protected main, Stage C target]. No final merge commit,
    push, PR update or publication is authorized by this task.
  • Stage B is merged through PR chore: integrate Wholphin upstream Stage B #115. Its protected-main CI completed Full validation:
    https://github.com/constbogdan/Mosaic/actions/runs/42231256780.
  • PR chore: review upstream changes to action.yml, pr.yml and 12 more #114 remains the independent Draft for the later range, with head
    b2c90b95a86031d60ef19a10e39215d9e909a887. Its branch and evidence are untouched.
  • The primary local main checkout stays at 8c800002; the Stage B worktree stays at
    32b37b83. Fetching authenticated main does not authorize switching either checkout.

Exactly two incoming commits:

  1. 3ef221bf910ddf00351df04592b0b066a4ecdffd — Improve track persistence for series & episodes (PR 1802).
  2. 621686d8e2785b0944f3dc730f84f8c0fa7d7356 — Include image tags in item image URLs (PR 2031).

Stage C is an ancestor of the observed upstream main. No later upstream commit is merged.
The original incoming delta is 38 paths, 3,016 additions and 278 deletions.

Actual conflicts and semantic review

Three paths conflicted:

Path Combined resolution
data/AppDatabase.kt Preserve integrity entity/DAO/converters and old migrations; add track entity/DAO and Mosaic version 37.
services/hilt/DatabaseModule.kt Preserve mosaic database and manual migration; provide both DAOs.
test/ui/TestModule.kt Preserve in-memory Mosaic test wiring and provide both DAOs.

The remaining 35 incoming paths were also reviewed, not accepted solely because Git merged
them cleanly. Repository, stream selection, upgrade handling, playback/view-model consumers,
DI/test helpers and image-owner/tag forwarding are the relevant semantic overlaps. Shared
resources add the upstream selection explanation strings without replacing Mosaic resources.

Schema and upgrade contract

Mosaic schema 36 already contains season_integrity_expectations; upstream's schema 40 does
not. Installed Mosaic databases must not be opened using upstream's incomplete schema export.
Stage C uses the next Mosaic version, 37, and replaces the incoming 40 export with KSP's
generated 37 export. All previously exported Mosaic schemas remain unchanged.

The supported migration graph remains:

2 --manual--> 3 -> 4 -> 5 -> 6 -> 7 -> 8 -> 9 -> 10 -> 11 -> 12
  -> 20 -> 30 -> 31 -> 32 -> 33 -> 34 -> 35 -> 36 -> 37

Every edge after 2-to-3 is Room-generated. The 36-to-37 edge adds
SeriesTrackChoice with primary key (userId, parentId, type) and a cascading foreign key
to users.rowId. Its remaining columns are parentType, itemId, language, activation,
trackFlags, codec, relativeTrackIndex, title and audioChannels. UUIDs retain Mosaic's
dashless converter; Room's enum conversion stores the upstream enum names. No new app-wide
converter or destructive fallback is introduced. All 12 old entity definitions, including
integrity indexes and converters, remain identical in the generated export.

Schema identity hashes:

  • 36: ec1d2505bdedd948527ea4dadc0010ef.
  • 37: 57cc12dbab9f37cb933a256611377430.

Migrations.Migrate36to37 is the auto-migration post-step. It copies legacy audio/subtitle
language preferences as DEPRECATED parent choices inside Room's schema-upgrade transaction,
retains source item IDs and user ownership, and preserves disabled subtitles even without a
language. Nullable/empty preferences create no unsupported new choice. INSERT OR IGNORE
makes the conversion repeat-safe and does not replace a newer choice. The old
PlaybackLanguageChoice table and all other existing tables remain.

The incoming AppUpgradeHandler conversion was rejected: its upstream 1.0.10 threshold would
skip independent Mosaic versions, and a global non-empty count could silently skip rows after
an interrupted batch. Room migration, rather than app startup/version allocation, owns this
conversion. Stage B's independent session/HDR upgrade handling remains unchanged.

Fresh installs create both new track persistence and existing integrity persistence directly.
No production database is read, copied, reset or upgraded during this task.

Track and image behavior

Track choices are scoped to a persisted Jellyfin user row and stored independently for audio
and subtitles at season/series level. Existing item choices take precedence; season choices
precede series choices; ordinary profile/default selection remains the fallback. Relative
indexes, language, forced/default/SDH/external/signs flags, title, codec and channel metadata
are retained for matching across episodes. Disabled/only-forced subtitle choices and selection
explanations are integrated. Clearing selected streams uses the new persistence while keeping
per-item playback and track modifications intact.

Two incoming swapped-type lookups were reproduced and corrected: StreamChoiceService's audio
fallback queried SUBTITLE choices, while PlaybackViewModel loaded AUDIO choices for subtitles.
Regressions in the existing track-choice and playback suites fail before those two-line fixes.
The incoming test named for audio season-to-series fallback called the subtitle method;
it now exercises the real audio method instead. Blank legacy languages remain profile fallback,
not an activated wildcard choice, matching Mosaic's previous selection behavior.

Image URLs include the correct owning item's cache tag for own/series/parent primary, logo,
thumb and backdrop images, plus music, people, Live TV and studio callers. Missing or
mismatched parent tags are omitted; existing image fallback and Mosaic UI remain.

Home Acquiring/reload, session restoration, acquisition/Downloads, Missing Seasons request
selection and inactive-Seerr cleanup, cached expectations, playability, feature gates and
Mosaic signing/update identities remain in place. No Request badge or Stage D UI is added.

Complete changed-file inventory against protected main

The staged integration has 43 paths (the 38-path upstream delta plus reviewed Mosaic
schema/testing/documentation adaptations, with AppUpgradeHandler unchanged from main).

M	app/build.gradle.kts
A	app/schemas/com.github.damontecres.wholphin.data.AppDatabase/37.json
M	app/src/main/java/com/github/damontecres/wholphin/data/AppDatabase.kt
M	app/src/main/java/com/github/damontecres/wholphin/data/ItemPlaybackRepository.kt
M	app/src/main/java/com/github/damontecres/wholphin/data/PlaybackLanguageChoiceDao.kt
A	app/src/main/java/com/github/damontecres/wholphin/data/SeriesTrackChoiceDao.kt
M	app/src/main/java/com/github/damontecres/wholphin/data/model/Person.kt
M	app/src/main/java/com/github/damontecres/wholphin/data/model/PlaybackLanguageChoice.kt
A	app/src/main/java/com/github/damontecres/wholphin/data/model/RelativeMediaStream.kt
A	app/src/main/java/com/github/damontecres/wholphin/data/model/SeriesTrackChoice.kt
M	app/src/main/java/com/github/damontecres/wholphin/services/HomeSettingsService.kt
M	app/src/main/java/com/github/damontecres/wholphin/services/ImageUrlService.kt
M	app/src/main/java/com/github/damontecres/wholphin/services/MusicService.kt
M	app/src/main/java/com/github/damontecres/wholphin/services/StreamChoiceService.kt
M	app/src/main/java/com/github/damontecres/wholphin/services/hilt/DatabaseModule.kt
M	app/src/main/java/com/github/damontecres/wholphin/ui/components/ContextMenu.kt
M	app/src/main/java/com/github/damontecres/wholphin/ui/components/Dialogs.kt
M	app/src/main/java/com/github/damontecres/wholphin/ui/components/StudioCardGrid.kt
M	app/src/main/java/com/github/damontecres/wholphin/ui/components/TitleOrLogo.kt
M	app/src/main/java/com/github/damontecres/wholphin/ui/components/VideoStreamDetails.kt
M	app/src/main/java/com/github/damontecres/wholphin/ui/detail/DebugPage.kt
M	app/src/main/java/com/github/damontecres/wholphin/ui/detail/PersonPage.kt
M	app/src/main/java/com/github/damontecres/wholphin/ui/detail/episode/EpisodeViewModel.kt
M	app/src/main/java/com/github/damontecres/wholphin/ui/detail/livetv/LiveTvViewModel.kt
M	app/src/main/java/com/github/damontecres/wholphin/ui/detail/movie/MovieViewModel.kt
M	app/src/main/java/com/github/damontecres/wholphin/ui/detail/series/SeriesViewModel.kt
M	app/src/main/java/com/github/damontecres/wholphin/ui/playback/PlayExternalPage.kt
M	app/src/main/java/com/github/damontecres/wholphin/ui/playback/PlaybackViewModel.kt
M	app/src/main/java/com/github/damontecres/wholphin/ui/slideshow/SlideshowViewModel.kt
M	app/src/main/res/values/strings.xml
A	app/src/test/java/com/github/damontecres/wholphin/data/AppDatabaseMigrationTest.kt
A	app/src/test/java/com/github/damontecres/wholphin/data/model/RelativeMediaStreamTest.kt
A	app/src/test/java/com/github/damontecres/wholphin/services/ImageUrlServiceTest.kt
M	app/src/test/java/com/github/damontecres/wholphin/services/StreamChoiceServiceTest.kt
A	app/src/test/java/com/github/damontecres/wholphin/test/TestSeriesTrackChoice.kt
A	app/src/test/java/com/github/damontecres/wholphin/test/TestTrackFlag.kt
M	app/src/test/java/com/github/damontecres/wholphin/test/TestUtils.kt
M	app/src/test/java/com/github/damontecres/wholphin/ui/TestModule.kt
M	app/src/test/java/com/github/damontecres/wholphin/ui/playback/PlaybackViewModelTests.kt
M	docs/CODEX_HANDOFF.md
M	docs/UPSTREAM_RESOLUTION_DECISIONS.md
M	docs/history/README.md
A	docs/history/UPSTREAM_STAGE_C.md

Validation evidence and limitations

Local validation on 2026-11-06 (not hosted integration acceptance):

  • Production/test Kotlin compilation passed with Gradle 9.8.1 and Kotlin 2.4.21.
  • Focused regressions: 127 tests in 15 suites, zero failures/errors/skips. XML reports
    are retained in .logs/stage-c/focused/; command output in focused-verified.log.
  • Complete default-debug JVM suite: 695 tests in 79 suites, zero failures/errors/skips,
    compared with Stage B's recorded 652 tests. Command:
    gradlew.bat :app:compileDefaultDebugKotlin :app:testDefaultDebugUnitTest.
    Evidence: .logs/stage-c/complete-jvm.log and .logs/stage-c/complete/ XML reports.
  • Seven new native-SQLite Room tests cover fresh creation, all 19 exported historical schema
    versions (2 through 36), latest/35 upgrades, exact old-table data retention, disabled/null/blank
    settings, repeat-safe conversion, full new-choice metadata, season precedence, per-user
    isolation and foreign-key cascades. Each opened database passes integrity_check and
    foreign_key_check. The latest-schema test snapshots every existing table, including saved
    user preferences/authentication, playback/index/delay choices, integrity expectations,
    remembered tabs, display settings and Seerr relationships.
  • Existing track/playback suites add three local regressions for disabled-language conversion
    and the two incoming swapped-type lookups. The inherited audio fallback test now calls the
    audio method. Incoming relative-stream, flag, scoring and image-owner/tag tests remain.
  • Applicable offline tooling: 68 passed (identity 3, validation policy 29, version 11,
    delivery 18, APK verifier 7). The initial combined command used the wrong verifier module
    name: its 61 actual tests passed; the corrected verifier invocation passed all seven.
    Evidence: .logs/stage-c/offline.log and offline-apk-verifier.log.
  • Changed-file pre-commit/ktlint and whitespace checks passed. Initial hook autofixes were
    reviewed before final compilation/testing. Intermediate fixture-construction errors were
    corrected, not skipped; the final suites above are green.
  • Repository Fast passed, including changed-scope pre-commit, the same 127-test focused
    graph (eligible cached results reused) and whitespace checks. Evidence:
    .logs/validation/20261106-175747-16468/summary.txt and its adjacent stage logs.
    An initial Fast launch lacked ANDROID_HOME and stopped before tests; setting the existing
    SDK path for that process corrected it without source/tooling or persistent environment edits.
    No local Full command or APK assembly is part of this validation.
$env:ANDROID_HOME = Join-Path $env:LOCALAPPDATA 'Android\Sdk'
.\scripts\validate-local.ps1 -Level Fast -TestFilter @('*AppDatabaseMigrationTest', '*TestSeriesTrackChoice', '*TestTrackFlag', '*RelativeMediaStreamTest', '*StreamChoiceServiceTest', '*ImageUrlServiceTest', '*SeasonIntegrityTest', '*SeasonIntegrityExpectationTest', '*PlaybackViewModelTests', '*AppUpgradeHandlerTest', '*ServerRepositoryTest', '*UserSwitchListenerTest', '*HomeViewModelTest', '*SeriesRequestStateTest', '*RequestSeasonRulesTest')

No connected device or running emulator was reported by adb devices -l. A configured TV
AVD is not a running test target. No APK is built, signed, installed or published in this task.
JVM migration coverage uses synthetic exported-schema databases with real Room and native
SQLite under Robolectric; it is not Android device instrumentation acceptance. Physical-device
upgrade, multi-user/server track persistence, forced-subtitle playback, focus/dialog rendering
and live image-cache invalidation still require operator acceptance. Optional FFmpeg/AV1/MPV
native libraries are unavailable locally; compilation uses the repository's MPV stub.

Upstream's use of BaseItemDto.parentId for parent-level track preferences is retained. It
does not require an Episode kind: a non-episode DTO supplying a parent ID can participate in
parent-level choices. Live Jellyfin metadata and non-episode parent scope have not been accepted
on a device; do not infer that all parent IDs are season IDs from the DAO/model names alone.

damontecres and others added 3 commits October 16, 2026 10:53
## Description
This PR overhauls how audio and subtitle track persistence works for
series! Previously, when you chose an audio or subtitle track for an
episode, only the language was saved and used for subsequent episodes.
This meant aspects about why that choice were lost such as a forced or
hearing impaired track.

This PR changes the persistence to include more details about the chosen
track. Additionally, the persistence is saved at both the season and
series levels.

## How it works

Selecting the track uses the first success option:
1. Episode specific - User has explicitly chosen an audio/subtitle track
for this episode
2. Season specific - User has chosen the track for another episode in
this season
3. Series specific - User has chosen the track for another episode in
this series
4. User preferences - User has _not_ chosen a track for the episode,
season, nor series, so determine track based on the preferred audio
language, preferred subtitle language, and subtitle mode

Additionally, the season or series specific choices use a scoring
algorithm to find the best suited track. For example, if the chosen
tracks for an episode in the season had the forced flag, this will be
preferred for subsequent episodes. Same for SDH/hearing impaired or
title, etc. This means that the common case, where a season has
substantially identical tracks, will use the same ones across all
episodes (after choosing for one, otherwise falling back to the series
or user preferences).

Finally, this also means that users that prefer SDH/hearing impaired
subtitles can be prioritized now, though there is no global preference
for this yet.

The previous track language choices are migrated to the new algorithm.
They lack the additional context, but this makes for a seamless
transition.

## UI changes

The context menu for choosing audio or subtitle tracks now displays why
that track was chosen.

### Related issues
Fixes damontecres#1795
Maybe fixes damontecres#1783
Related to damontecres#1136 & damontecres#1798
Closes damontecres#1470

### Testing
Previous unit tests for track selection all pass, plus there are a few
additional unit tests. I've done some testing on the emulator and it
seems to work well. But I think real world testing will be needed.

## AI or LLM usage
None
## Description

Wholphin builds item image URLs without Jellyfin's `tag` query
parameter. `ImageUrlService` already receives the item's `imageTags` and
`backdropTags`, and the low-level `getItemImageUrl` supports `tag`, but
no branch passed it. Today only chapter and now-playing images set it.

Before: `/Items/{id}/Images/Primary?quality=96&fillHeight=229`
After:
`/Items/{id}/Images/Primary?quality=96&fillHeight=229&tag={ImageTags.Primary}`

This is how the official Jellyfin clients request images. jellyfin-web
and the official Jellyfin Android TV app both copy `ImageTags[...]` (and
the parent/series tags) into the image URL.

I also added `ImageUrlServiceTest`, which covers each branch.


### Related issues

I tested each one on the emulator against a stock Jellyfin 12.1 server
(no plugins), comparing `main` with this branch:

- **damontecres#366 (Image cache expiration): fixed by this PR.**
- **damontecres#1249 (blank tile for a newly added movie) and damontecres#1338 (episode cover
never refreshes): already fixed on `main` since v1.0.3, not by this
PR.** 
- **damontecres#360 (Option to hide spoilers): partly.**

## AI or LLM usage

This change was made with AI assistance (Claude Code). It was used for:
- the code changes in `ImageUrlService` and the call sites listed above
- the new `ImageUrlServiceTest`
- the emulator testing and benchmarks
- drafting this description

The testing is what's described above: unit tests, an Android TV
emulator against Jellyfin 12.1 servers (with Jellyfin Enhanced and
stock), request logs from a proxy, and a check of every tag against the
server's metadata. I've reviewed the change and can explain it.

I'm also a maintainer on Jellyfin Enhanced, which is how I ran into
this. I'm happy to share examples of my own coding work if that helps
with reviewing this.
@constbogdan
constbogdan merged commit 37e3702 into main Nov 6, 2026
4 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants