Skip to content

Improve track persistence for series & episodes - #1802

Merged
damontecres merged 20 commits into
mainfrom
develop/episode-track-persist
Oct 16, 2026
Merged

damontecres merged 20 commits into
mainfrom
develop/episode-track-persist

Conversation

@damontecres

@damontecres damontecres commented Aug 7, 2026 •

Copy link
Copy Markdown
Owner

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 #1795
Maybe fixes #1783
Related to #1136 & #1798
Closes #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.

Screenshots

image image image

AI or LLM usage

None

Try it out

You can try this unstable development branch by following the instructions here: https://github.com/damontecres/Wholphin/releases/tag/develop-episode-track-persist

Note: this PR contains database changes!! This means if you install this branch, you CANNOT switch to another development branch nor stable unless you uninstall the app first!! The app will not start otherwise!

@damontecres damontecres added enhancement New feature or request database Contains database changes subtitles labels Aug 7, 2026
@damontecres
damontecres marked this pull request as draft August 7, 2026 01:25
@LessRinn

LessRinn commented Aug 7, 2026 •

Copy link
Copy Markdown

It worked, thank you!

@BlackstormFirst

BlackstormFirst commented Aug 12, 2026 •

Copy link
Copy Markdown

Hello, I’ve just switched from the official client to your version due to various bugs and design issues—but primarily because of the poor handling of audio and subtitle streams. I hope this fix meets my expectations. Thanks a lot for your efforts in this area.

Edit:

This not retain the current audio codec type for example and i am still in "default" mode.
(I managed to force the subtitle type for the entire series, but there was a misalignment when I reached an intermediate episode that didn't have the same number of languages and in the next episode, with the same number of languages, the subtitles didn't match the series' forced selection but rather the one from the previous episode.)

I just tested this branch, and it still doesn't quite meet my expectations, even though it's getting closer.
Here is how I see things...

By default:
When you access the first item, the server sends its "best indices"—determined by the server-side strategy (in v12, the suggested indices seem improved, especially regarding forced subtitles, though this remains to be verified).
Then, by default, all subsequent videos (previous/next) should rely on the user's current selection or fallback to the most appropriate option, while maintaining that selection.

"Smart mode" should behave roughly the same way but must check each item to see if the streams (audio/subtitles) match the user's preferences (this allows, for instance, reverting to the correct language and subtitles when switching from a multi-language episode to a single-language one, and then back to content in your preferred language). However, note that if the audio language matches your preferred language, the system should select the forced subtitle track—or no subtitles at all if only full subtitle tracks exist.

"Always default" mode always loads the default audio streams but still attempts to adjust the subtitles (e.g., if a default subtitle track exists but isn't marked as "forced" while the audio language matches, the subtitle track should not be loaded).

There are many possible variations, but your implementation of modes and languages ​​based on server settings certainly facilitates the integration of an audio and subtitle manager.

I should point out that all indicators and their variants must be taken into account to implement the best possible fallbacks.

@damontecres

Copy link
Copy Markdown
Owner Author

I just tested this branch, and it still doesn't quite meet my expectations, even though it's getting closer.

Thanks for trying it out @BlackstormFirst. Wholphin closely (not probably not exatly) follows the same logic as the server for Default/Always/Smart/etc subtitle mode setting.

This PR is about implementing a better override. Such as if just for one specific series you want to use a different language.

If you're getting unexpected behavior, please feel free to reply here or open an issue. Make sure you include all of the relevant settings, media info, & which tracks were chosen.

@damontecres
damontecres marked this pull request as ready for review October 16, 2026 14:15
@damontecres
damontecres merged commit 3ef221b into main Oct 16, 2026
3 checks passed
@damontecres
damontecres deleted the develop/episode-track-persist branch October 16, 2026 14:53
wibuf pushed a commit to wibuf/Wholphin that referenced this pull request Nov 9, 2026
Since upstream's per-series track memory (damontecres#1802), a series with a
remembered subtitle choice was scored without the keywords. Every choice
converted from the old per-series language setting remembers only the
language, so all English tracks tied and the default-flagged one won,
often "Signs & Songs" on anime. A full track picked by hand that happened
to be the default also lost to the next episode's default signs track.

Keywords now add to that score (600 a match: above the remembered
default/SDH/signs flags, below forced and language). If the remembered
track itself goes against the keywords, a signs or commentary track
picked on purpose, they step aside.

The signs check also leaves out [bracketed] group tags, as the avoided
keywords already did, so "Full Subtitles [MTBB (Hakoniwa songs)]" isn't
taken for a signs track in Only-forced.

Five new test cases; the old code fails the three that cover the bugs.
CLAUDE.md: --tests matches class names, and StreamChoiceServiceTest.kt
holds ten classes.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01GYiLfNr8FMN8XLdB45Uy6E
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

database Contains database changes enhancement New feature or request subtitles

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Subtitles are changed only once for the entire series Subtitles: Multiple unexpected behaviours

3 participants