feat(player): auto-switch source when stuck buffering (opt-in)

[RjBiermann]

Summary

Opt-in player setting — "Auto-switch stuck source" (Player settings, off by default). When a source stalls during playback, the player switches to the next ranked source instead of spinning forever. Fixes the silent-stall case behind #3096 and #3097.

Problem

Hard errors already switch mirrors automatically (PlayerView.playerError → nextMirror()), and #2968 added mid-stream timeout recovery by re-preparing. But when a source just silently stalls — player sits in STATE_BUFFERING, position frozen, no exception thrown — nothing reacts. The user gets an endless spinner unless they manually open the source picker.

How it works

StuckBufferingWatcher polls the player once per second (cheap: one status check + one position read). When enabled, it switches to the next source via the existing nextMirror() / loadLink(sameEpisode = true) path — position is preserved, no player code changes.

Triggers (either one fires a switch):

Trigger	Condition
Single stall	buffering with no position advance for 10 s
Repeated stalls	buffering ≥ 15 of the last 60 s (~25% duty) — catches choppy streams that keep creeping forward

Guardrails:

• 60 s cooldown between switches
• Budget reset on success — a switch that leads to 30 s+ of playback progress past the switch point restores the full budget, so working sources get effectively unlimited switches. Only a cycle where nothing ever plays is capped at 3, preventing an infinite loop when all mirrors are dead
• hasNextMirror() checked first — never triggers the "no links found" page-pop
• Manual switch respected — picking a source yourself resets the stall tracking, so the previous source's stall history can't auto-switch away from your pick
• Live streams & torrents excluded — mirror-switching fights the live-edge logic on live TV, and torrent/magnet buffering is inherent to the source, so neither triggers a switch
• Firing clears the stall state (hysteresis); a toast informs the user

Telemetry: per-host failure counters are recorded locally (DataStore, incremented on playerError and stall switches). Nothing reads them yet — they're the data source for a possible future reliability-ordering PR. Local only, never synced.

Non-breaking / scope

• Off by default — with the setting off, the tick early-returns and behavior is identical to today (covered by unit tests)
• Touches only ui/player wiring, a settings row, strings, and one preference. No changes to CS3IPlayer.kt, PlayerView.kt, MainAPI, or any extension-facing API
• Interaction with fix: skip broken CF bypass on Android TV + recover from mid-stream ti… #2968: the timeout-recovery prepare() retry and this watcher can alternate (retry → buffer → retry…). The frozen-position detection acts as a circuit breaker for that loop after ~10 s. fix: skip broken CF bypass on Android TV + recover from mid-stream ti… #2968's path itself is untouched
• Known limitation: the single-stall trigger can't distinguish user-scrubbing from real stalls; the cooldown and success-reset budget bound the damage (noted in code)

Testing

Unit tests (in this PR): fire timing, cooldown, session cap, budget reset on recovery, host parsing — fake clock, no Android dependencies.

Manual, TV emulator, throttled network (3G / 3.5G), multiple sessions:

• Switches fire on both triggers; position preserved; toast shown
• Budget reset verified live: after each successful switch that resumed playback, a later stall correctly fired again as "switching source (1/3)"
• Feature off → no behavior change observed

Transparency note: one session hit an unrelated OutOfMemoryError (heap saturated at the 512 MB debug-build limit during source resolution). GC logs show the heap hit 511 MB ~16 s before the watcher fired; the watcher's footprint is a deque of ~60 longs. Pre-existing emulator/extension behavior, not introduced here.

AI usage disclosure

This change was written with AI assistance (GLM 4.6 / glm-5.3-flash via OpenCode Go, coding-agent workflow), per AI-POLICY. Unit tests pass locally; the feature was manually smoke-tested on an emulator as described above.

[RjBiermann]

Rebased onto master and pushed a follow-up fix: the per-session switch cap (3) burned its whole budget on mirrors that eventually played fine. Now a switch that leads to 30s+ of playback progress past the switch point resets the counter — working sources get effectively unlimited switches, while a cycle where nothing plays is still capped at 3 so it can't loop forever.

Verified on the TV emulator with network throttling (3G / 3.5G): switches fire on both triggers, budget restores after each recovery, unit tests + lint pass.

[RjBiermann]

untitled.mp4

Tested with network throttle and skipping ahead.