Skip to content

Add feature-gated dual subtitle MVP with merged subtitle track#2549

Open
beng1z wants to merge 1 commit intorecloudstream:masterfrom
beng1z:feat/dual-subtitles-mvp-gated
Open

Add feature-gated dual subtitle MVP with merged subtitle track#2549
beng1z wants to merge 1 commit intorecloudstream:masterfrom
beng1z:feat/dual-subtitles-mvp-gated

Conversation

@beng1z
Copy link
Copy Markdown

@beng1z beng1z commented Mar 1, 2026

Summary

  • Add a feature-gated dual subtitle MVP (off by default).
  • Add explicit Primary / Secondary selection mode in source/subtitle dialog.
  • Implement parse-time subtitle merge into a single generated WebVTT track (no polling).
  • Block unsupported combinations (embedded secondary, embedded primary+secondary, secondary without primary) with clear user feedback.
  • Keep 403/header bugfix out of this PR scope, except dual-pipeline-required subtitle header merge.

What changed

  • IPlayer API expanded with secondary subtitle methods.
  • CS3IPlayer implements secondary state, dual merge pipeline, and merged track selection.
  • GeneratorPlayer updated for Primary/Secondary selection UX and Apply-based commit behavior.
  • Subtitle settings now include Dual subtitles (experimental) switch.
  • Added DualSubtitleComposer + unit tests.
  • Added/updated localized strings for all supported locales for the newly introduced dual subtitle keys.

AI usage disclosure

  • AI tooling was used to assist implementation and localization generation.
  • All code/resources were manually reviewed and adjusted.
  • Review feedback and requested UX constraints were applied manually.

Testing

  • Manual device test completed (dual subtitle selection, apply flow, unsupported combo blocking, layout behavior).
  • ./gradlew testStableDebugUnitTest assembleStableDebug --no-daemon passes.

Notes

  • Dual subtitles remain experimental and disabled by default.
  • Embedded-secondary scenarios are intentionally unsupported in MVP.

@beng1z beng1z marked this pull request as draft March 3, 2026 04:16
beng1z pushed a commit to beng1z/cloudstream that referenced this pull request Mar 3, 2026
@beng1z beng1z requested a review from fire-light42 March 3, 2026 14:26
Add opt-in dual-subtitle support (disabled by default) where the player
merges a primary and secondary subtitle track into a single generated
WebVTT file at parse time, rather than rendering two overlay tracks.

- `IPlayer` gets `setSecondarySubtitles` / `getCurrentSecondarySubtitle`
  and `isDualSubtitleCombinationSupported`.
- `CS3IPlayer` builds the merged track via `DualSubtitleComposer`,
  caches it under `cacheDir/dual_subtitles/dual_sub_<hash>.vtt`
  (constants for dir/prefix/extension), reuses the file on reload, and
  cleans stale entries on episode change.
- Network / file I/O for the merge is wrapped in
  `runBlocking(Dispatchers.IO)` so it never runs on the main thread when
  `loadOnlinePlayer` is called from the UI thread.
- On unsupported combinations (embedded secondary, secondary without
  primary, unsupported origin pair) the pipeline logs and falls back to
  the normal single-subtitle path instead of firing an `ErrorEvent` that
  previously triggered a next-source reload loop.
- `GeneratorPlayer` adds a Primary/Secondary selection mode in the
  source/subtitle dialog (gated on the new preference), uses an
  Apply-based commit so selections are only sent to the player once,
  and blocks unsupported combinations with a localized toast.
- New `Dual subtitles (experimental)` toggle in subtitle settings
  (`SUBTITLE_DUAL_ENABLED_KEY`).
- Landscape and portrait subtitle dialog layouts get the new tab
  buttons with `contentDescription` for accessibility, plus a color
  selector for the active-tab text.
- New base strings only; translated locales are left untouched.
- `DualSubtitleComposer` + unit tests cover overlap merging, adjacent
  same-text coalescing, short cue boundaries, primary/secondary-only
  cases, negative durations, and WebVTT header/timestamp formatting.
@beng1z beng1z force-pushed the feat/dual-subtitles-mvp-gated branch from ada76ed to 9ff0789 Compare April 18, 2026 15:45
@beng1z
Copy link
Copy Markdown
Author

beng1z commented Apr 18, 2026

Follow-up update:

  • Rebased the branch onto current master and squashed the five commits into one so the diff now reflects only the dual-subtitle changes (11 files, no locale churn).
  • Fixed the main-thread freeze that caused the error loop you observed: the merge pipeline in CS3IPlayer.buildMergedDualSubtitleSource previously did synchronous HTTP reads inside getSubSources, which is called from loadOnlinePlayer on the UI thread. loadSubtitleBytes now runs inside runBlocking(Dispatchers.IO) and the merged .vtt is reused from the cache on reload, so no re-download/re-parse on the retry path.
  • Cleaned up leftover cosmetics in values/strings.xml (restored blank_repo_message whitespace, fixed indentation, dropped the now-unused subtitles_secondary_load_failed string).
  • ./gradlew testStableDebugUnitTest assembleStableDebug both pass locally.

I understand the maintainability concern about merging an MVP — if there are specific polish items beyond what's above that need to land before this is acceptable, I'm happy to address them in-place rather than as a follow-up.

@beng1z beng1z marked this pull request as ready for review April 18, 2026 15:45
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.

1 participant