Add configurable TV Mode to simulate continuous random TV playback

[neura-neura]

Summary

This PR adds a new configurable TV Mode designed to simulate the experience of watching a real TV channel with automatically selected random content.

The main goal is to solve the current limitation where random playback can open content, but does not fully behave like a continuous TV experience. With this change, the app can now keep selecting and playing content automatically, including random series episodes or movies, based on user preferences and without requiring constant manual interaction.

Motivation

The existing random flow is useful, but it does not fully simulate a TV-like experience.

This PR introduces a dedicated TV Mode that:

• starts random playback with a single press
• can continue indefinitely
• can pick either movies, TV shows, or both
• can prefer dubbed or subtitled content
• can work globally or inside a specific TV show
• can automatically skip broken, unavailable, or stalled content
• can avoid polluting Continue Watching if the user disables that behavior

This effectively turns the app into a configurable “random TV” experience.

What was added

1. New TV Mode system

A new dedicated TV Mode flow was implemented instead of relying only on the existing Random button behavior.

TV Mode can:

• pick random content from the selected source
• automatically start playback
• continue infinitely after each movie or episode finishes
• behave differently depending on whether it was launched globally or from inside a specific show

2. Home quick action support

A new configurable Home quick action was added.

Users can now choose between:

• None
• Random
• TV Mode

This simplifies the previous button conflict and makes the Home screen behavior explicit.

3. TV Mode button on Home

When TV Mode is selected as the quick action and enabled, a dedicated TV Mode button appears on the Home screen.

Pressing it starts a random TV-like playback session.

4. TV Mode button inside result pages

A dedicated TV Mode button was added to result pages for series and compatible content.

This allows users to start TV Mode directly from a show page.

Example:

• If launched from Home, TV Mode can behave globally and choose from all candidates.
• If launched from a show page, TV Mode can stay restricted to that show and pick random episodes from it.

5. Local show TV Mode

When TV Mode is started from a specific TV show, playback can remain limited to that show.

This enables a “shuffle this show like a TV channel” behavior.

6. Season scope options

A new setting was added to control how local show TV Mode behaves:

• selected season only
• any season

Example:

• If the user starts TV Mode from Season 2 of a series and selects “selected season only”, only episodes from Season 2 are used.
• If “any season” is selected, TV Mode can pick episodes from any season of that same show.

7. Content filtering options

TV Mode now supports content scope preferences:

• TV Shows only
• Movies only
• TV Shows and Movies

This allows users to decide what kind of random TV experience they want.

8. Dub/Sub preference support

TV Mode now respects user preference for dubbed/subtitled content when multiple options are available.

If the preferred option is not available, playback falls back gracefully to other available content.

9. Automatic playback for TV simulation

TV Mode now automatically starts playback instead of stopping at the content page.

Behavior:

• for movies, it starts the movie directly
• for TV shows, it can automatically select a dubbing option if available, choose a random episode, and start playback

This is one of the key pieces needed to actually simulate a TV.

10. Proper behavior after playback ends

When normal playback ends in a TV show, the app usually continues with the next episode of that same show.

This PR changes that behavior for TV Mode:

• global TV Mode no longer just follows the next normal episode
• it instead selects the next item according to the active TV Mode session
• local show TV Mode can still stay inside the same show, but with randomized episode selection

This makes TV Mode feel intentional rather than just chaining default next-episode behavior.

11. Player-level TV Mode toggle

A TV Mode on/off control was added directly to the player controls.

This gives the user immediate visibility and control over whether TV Mode is active during playback.

It can be used to:

• enable TV Mode from the player
• disable the current TV Mode session from the player
• switch into either local-show or fully random behavior depending on settings

12. Configurable player start behavior

A new option was added for what should happen when the user enables TV Mode from the player while watching a show:

• keep TV Mode inside the current show
• start fully random TV Mode

This makes the player toggle much more flexible.

13. Automatic recovery when content has no playable links

Previously, if random content was selected but no playable links were available, the user could be taken out of the flow.

Now, when TV Mode is active:

• if the selected movie/show has no links
• if the chosen episode has no playable source
• if mirrors are exhausted

the app automatically tries another valid random item instead of breaking the TV experience.

14. Stall protection

A new optional TV Mode stall protection system was added.

Users can configure:

• whether stall protection is enabled
• how many retries/buffering stalls should be tolerated
• how many seconds to wait while loading/buffering before skipping

If content gets stuck too much, TV Mode will automatically move on to another item based on the current session rules.

This is especially useful for preserving the “TV” feeling without manual intervention.

15. Continue Watching control

A new option was added to decide whether TV Mode playback should appear in Continue Watching.

If disabled:

• TV Mode playback should not populate Continue Watching
• resume entries are removed/avoided during TV Mode sessions
• Home resume content is refreshed accordingly

This prevents random TV sessions from polluting the user’s normal viewing history.

Result

With these changes, the app now supports a much more complete TV simulation mode.

A user can enable TV Mode, press one button, and let the app continuously choose and play random content according to their preferences, much closer to how a real TV channel behaves.

Testing

Tested scenarios include:

• Home quick action switching between None / Random / TV Mode
• global TV Mode from Home
• local TV Mode from a specific show
• selected season only vs any season
• TV Shows only / Movies only / both
• dubbed/sub preference handling
• player TV Mode toggle
• automatic continuation after playback ends
• fallback when content has no links
• stall protection retries and timeout behavior
• Continue Watching enabled/disabled behavior

[neura-neura]

I addressed the automated issues reported during the initial PR checks.

The remaining CodeFactor warning was fixed, and the branch was rebuilt afterward to verify everything still compiles correctly.

Current status:

• Artifact Build is passing
• CodeFactor is passing
• No conflicts with the base branch

The PR is now ready for review. Thanks for taking a look.

[fire-light42]

CodeFactor warnings are not a blocker. While it is good to check that, there is no need to force the code to follow all suggested changes.

This is quite a large pull request and will therefore require a bit more time to properly review. However, there are some important details which are I have noticed from a general overview.

1. Please make TV mode settings a separate sub-menu. With this many options we need to make navigation easier for the user.

2. Reduce options where possible. We want to minimize user confusion and minimize how overwhelmed they feel when opening settings. See if there are options which should be logically always turned on, or if you can bypass them with smart programming (for example reusing the existing preferences for sub/dub). You can leave some of these options as getKey/getBoolean even if the preference is hidden, if you want to leave room for power users to change this using extensions.

3. Prevent ALL possibilities of crashing (unhandled exceptions). If something can crash it will crash for someone running a weird setup. For example in your code you use requireContext() which works well in testing but will crash for someone in some edge case because requireContext() throws unhandled exceptions. Always use the nullable context instead.

4. If you used AI for any part of the pull request please disclose that, as per our AI policy. This is not a comment on your code quality, but something which is good for all new contributors to be aware of.

More comments to follow when I have tested and read through all code.

[neura-neura]

Follow-up update addressing maintainer feedback and additional issues found during testing.

First, sorry for the extra churn here. A few of these issues are things I should have caught earlier, especially the Movies only filtering problem and some of the TV mode anime dub/sub edge cases. I wanted to follow up with fixes rather than leave those gaps in the PR.

Changes included in this update:

• Moved TV Mode settings into a separate sub-menu to make navigation easier and reduce clutter in the main UI settings screen.
• Added dedicated TV Mode settings screen/navigation.
• Reduced visible TV Mode options to avoid overwhelming users.
• Removed the separate “enable TV mode buttons” switch.
• TV Mode availability is now driven by Home quick action = TV Mode.
• If TV Mode is not selected in Home quick action, the TV Mode sub-menu is still accessible but now shows a notice explaining that the user must enable it from the home quick action first.
• Switching the home quick action away from TV Mode now cleanly stops the active TV Mode session.

Dub/Sub handling:

• TV Mode now reuses the existing global anime preference from:
  Settings > Providers > Display Dubbed/Subbed Anime
• The TV Mode-specific dub/sub preference is no longer exposed in the UI.
• TV Mode dub/sub filtering is now applied only to anime, since that selector is anime-specific and should not affect non-anime TV shows or movies.

Content filtering:

• Fixed Movies only so it no longergoes to a endless loop.
• Fixed TV shows only content selection so it properly finds and uses compatible TV show candidates.
• Tightened TV Mode candidate classification so Movies only, TV shows only, and TV shows + movies behave more predictably.

Stall protection:

• TV Mode stall protection now ignores manual seek-bar scrubbing.
• The 10-second seek buttons does not trigger false stall protection skips.
• That seek-bar behavior is now fixed so manual user seeking does not trigger false stall protection skips.

Safety / structure:

• Adjusted the newer TV Mode settings flow to avoid avoidable hard crashes in edge cases by relying on nullable context access instead of assuming context is always available.
• Kept the hidden-key based structure where useful so advanced users still have room for power-user customization without exposing everything in the normal UI.

Verification:

• Rebuilt locally after these follow-up changes with:
  ./gradlew :app:assembleStableDebug

AI usage disclosure:
I used AI assistance during parts of this contribution for implementation help, refactoring help, and drafting text. All submitted code was reviewed manually by me, adjusted based on maintainer feedback and additional testing, and rebuilt locally before updating the pull request.

I understand that I am responsible for explaining and fixing any part of this contribution during review.