Skip to main content

## Module background_policy

Source
Expand description

What playback should do when the app stops being visible.

TRACES: UR-040 | DR-224 | UT-211

## §The defect this exists for

The per-player background-audio toggle (UR-040) was built for the WebView `<video>` path, where backgrounding the app kills the decode: the toggle decided whether to hand off to a native audio stream or let playback die.

Native video then became the default renderer (DR-188). On that path playback runs through ExoPlayer inside a `MediaSessionService` — a foreground media service whose entire purpose is to keep playing when the app is not visible. Nothing stops it, and nothing in the codebase paused playback on background.

So locking the screen kept the audio playing whether or not the toggle was on. The toggle governed a handoff that no longer had anything to hand off from: there was no gap in playback to bridge. A user who had never touched it got background audio anyway, which is the bug as reported.

## §Why the decision lives in Rust

It depends on what the item is (a video keeps its picture; music has none to lose) and on a user setting — domain questions, not presentation ones, and the answer must be identical for both renderers. The frontend and the Android activity carry it out; neither decides it. Putting the rule in either would have reproduced exactly the split that caused this: two renderers, two behaviours, one toggle that only reached one of them.

## Enums§

BackgroundAction
  What the player should do when the app is backgrounded.

## Functions§

background_action
  Decide what backgrounding should do.
is_video_media
  Whether a media type has a picture that backgrounding would throw away.