Repository navigation
chore: integrate Wholphin upstream Stage C - #116
Merged
Merged
Conversation
## 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.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Stage C local upstream integration
Authenticated scope and boundary
b8cf05293dbbddc3d6c8473426213b9a696a5f59.55960c24625ef03bc5ac71b58806efdd613ffcc7.621686d8e2785b0944f3dc730f84f8c0fa7d7356.bd46ff3e03c9a9f100fefcc2554be7c245a08c68.chore/upstream-stage-c, worktreeC:\Projects\Wholphin\mosaic-upstream-stage-c.push, PR update or publication is authorized by this task.
https://github.com/constbogdan/Mosaic/actions/runs/42231256780.
b2c90b95a86031d60ef19a10e39215d9e909a887. Its branch and evidence are untouched.8c800002; the Stage B worktree stays at32b37b83. Fetching authenticated main does not authorize switching either checkout.Exactly two incoming commits:
3ef221bf910ddf00351df04592b0b066a4ecdffd— Improve track persistence for series & episodes (PR 1802).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:
data/AppDatabase.ktservices/hilt/DatabaseModule.ktmosaicdatabase and manual migration; provide both DAOs.test/ui/TestModule.ktThe 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 doesnot. 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:
Every edge after 2-to-3 is Room-generated. The 36-to-37 edge adds
SeriesTrackChoicewith primary key(userId, parentId, type)and a cascading foreign keyto
users.rowId. Its remaining columns areparentType,itemId,language,activation,trackFlags,codec,relativeTrackIndex,titleandaudioChannels. UUIDs retain Mosaic'sdashless 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:
ec1d2505bdedd948527ea4dadc0010ef.57cc12dbab9f37cb933a256611377430.Migrations.Migrate36to37is the auto-migration post-step. It copies legacy audio/subtitlelanguage preferences as
DEPRECATEDparent 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 IGNOREmakes the conversion repeat-safe and does not replace a newer choice. The old
PlaybackLanguageChoicetable 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).
Validation evidence and limitations
Local validation on 2026-11-06 (not hosted integration acceptance):
are retained in
.logs/stage-c/focused/; command output infocused-verified.log.compared with Stage B's recorded 652 tests. Command:
gradlew.bat :app:compileDefaultDebugKotlin :app:testDefaultDebugUnitTest.Evidence:
.logs/stage-c/complete-jvm.logand.logs/stage-c/complete/XML reports.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_checkandforeign_key_check. The latest-schema test snapshots every existing table, including saveduser preferences/authentication, playback/index/delay choices, integrity expectations,
remembered tabs, display settings and Seerr relationships.
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.
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.logandoffline-apk-verifier.log.reviewed before final compilation/testing. Intermediate fixture-construction errors were
corrected, not skipped; the final suites above are green.
graph (eligible cached results reused) and whitespace checks. Evidence:
.logs/validation/20261106-175747-16468/summary.txtand 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.
No connected device or running emulator was reported by
adb devices -l. A configured TVAVD 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.parentIdfor parent-level track preferences is retained. Itdoes 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.