Add feature-gated dual subtitle MVP with merged subtitle track by beng1z · Pull Request #2549 · recloudstream/cloudstream

beng1z · 2026-03-01T21:25:20Z

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.

fire-light42

First round of comments, for the easiest to spot issues.
I will give you more once I can properly test it as the app reliably freezes when testing it.

We will not merge anything half-finished, as to keep CloudStream maintainable. We will therefore not merge a MVP. This feature will need to be polished before getting accepted.

fire-light42 · 2026-03-02T23:02:29Z

+
 \n%s</string>
    <string name="delete_message_series_section" formatted="true">رح كمان تمحي ل الأبد كل الحلقات اللي ب هيدا المسلسل؟
-\n


Why all of these removals?

Most of that diff was unintended newline and whitespace churn from touching the locale file. In the follow-up I trimmed the locale changes back and removed the AI-added dual subtitle strings from translated files; for now the new keys are only kept in the base strings file.

fire-light42 · 2026-03-02T23:18:41Z

+                return Pair(listOf(merged.first), listOf(merged.second))
+            }
+
+            event(ErrorEvent(ErrorLoadingException(context.getString(R.string.subtitles_secondary_load_failed))))


These events cause an error loop wherein the player goes to the next source and the subtitles are loaded again. This freezes the app.

I removed the ErrorEvent path here and changed it to clear the secondary selection and fall through to the normal single subtitle load path instead. That was meant to avoid the reload loop you pointed out.

fire-light42 · 2026-03-02T23:19:36Z

+
+            event(ErrorEvent(ErrorLoadingException(context.getString(R.string.subtitles_secondary_load_failed))))
+            dualMergedTrackId = null
+            return Pair(emptyList(), emptyList())


You should fall back to single subtitles if an error occurs.

Changed this in the follow-up. Unsupported or failed dual subtitle cases now drop back to the existing single subtitle path instead of returning empty sources or surfacing a dual subtitle load error from here.

fire-light42 · 2026-03-02T23:22:07Z

+    private fun cleanDualSubtitleCache(context: Context, exclude: File? = null) {
+        try {
+            context.cacheDir.listFiles { file ->
+                file.name.startsWith("dual_sub_") && file.name.endsWith(".vtt") && file != exclude


The name should be in a constant, as to prevent issues when someone in the future renames the subtitle file. The subtitle files should preferably also be in its own folder to ease future debugging.

Adjusted this. The generated files now live under a dedicated dual_subtitles cache subdirectory, and the dir, prefix, and extension are pulled into constants instead of being inlined.

fire-light42 · 2026-03-02T23:31:12Z

+        return try {
+            when (subtitle.origin) {
+                SubtitleOrigin.URL -> {
+                    val mergedHeaders = mutableMapOf<String, String>().apply {


Why merged headers? Other subtitles do not have merged headers.

Removed that header merge in the follow-up and switched this back to subtitle.headers only. I left the broader header and referer handling out of this PR.

fire-light42 · 2026-03-02T23:38:18Z

+    }
+
+    private fun isDualSubtitleTrackSelectionEnabled(): Boolean {
+        val enabled = getKey<Boolean>(SUBTITLE_DUAL_ENABLED_KEY) ?: false


WET code, use the function you defined

Changed this to use player.isDualSubtitleCombinationSupported(...) and moved the shared check onto IPlayer and CS3IPlayer, so GeneratorPlayer no longer duplicates the logic.

fire-light42 · 2026-03-02T23:40:01Z

+
+    <string name="subtitles_dual_enabled">ଡୁଆଲ୍ ସବ୍ଟାଇଟ୍ (ପରୀକ୍ଷାମୂଳକ)</string>
+    <string name="subtitles_edit_primary">ପ୍ରାଥମିକ</string>
+    <string name="subtitles_edit_secondary">ଦ୍ Secondary ିତୀୟ</string>


Do not translate strings using AI, let real people do the translations.

Removed the AI-added dual subtitle strings from the translated locale files in the follow-up. For now the new subtitle keys are only kept in the base strings file.

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 · 2026-04-18T15:45:14Z

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.

fire-light42 requested changes Mar 2, 2026

View reviewed changes

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

Address PR recloudstream#2549 review feedback

ada76ed

beng1z requested a review from fire-light42 March 3, 2026 14:26

beng1z force-pushed the feat/dual-subtitles-mvp-gated branch from ada76ed to 9ff0789 Compare April 18, 2026 15:45

beng1z marked this pull request as ready for review April 18, 2026 15:45

Conversation

beng1z commented Mar 1, 2026

Summary

What changed

AI usage disclosure

Testing

Notes

Uh oh!

fire-light42 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

beng1z commented Apr 18, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants