jellytau_lib/player/

background_policy.rs

//! 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.

use crate::player::media::MediaType;

/// What the player should do when the app is backgrounded.
#[derive(Debug, Clone, Copy, PartialEq, Eq, serde::Serialize, serde::Deserialize, specta::Type)]
#[serde(rename_all = "camelCase")]
pub enum BackgroundAction {
    /// Carry on. Music, and video the user explicitly asked to keep hearing
    /// while it is in a picture-in-picture window.
    KeepPlaying,
    /// Swap the video stream for an audio-only one and keep playing.
    HandOffToAudio,
    /// Stop making sound. The user did not ask for background playback.
    Pause,
}

/// Decide what backgrounding should do.
///
/// * `is_video` — whether the current item has a picture to lose. Music is
///   never paused by backgrounding; that is what a music player is for.
/// * `background_audio_armed` — the per-player toggle (UR-040).
/// * `in_picture_in_picture` — the app is not "gone", it is in a floating
///   window and still visible. Pausing here would break PiP (UR-041).
///
/// TRACES: UR-040, UR-041 | DR-224 | UT-211
pub fn background_action(
    is_video: bool,
    background_audio_armed: bool,
    in_picture_in_picture: bool,
) -> BackgroundAction {
    // PiP first: the window is still on screen, so this is not backgrounding in
    // any sense the user would recognise.
    if in_picture_in_picture {
        return BackgroundAction::KeepPlaying;
    }

    // Music has no picture to lose; a music player that stopped when the screen
    // locked would be broken in an obvious way.
    if !is_video {
        return BackgroundAction::KeepPlaying;
    }

    if background_audio_armed {
        BackgroundAction::HandOffToAudio
    } else {
        BackgroundAction::Pause
    }
}

/// Whether a media type has a picture that backgrounding would throw away.
///
/// TRACES: UR-040 | DR-224
pub fn is_video_media(media_type: MediaType) -> bool {
    matches!(media_type, MediaType::Video)
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn video_without_the_toggle_pauses() {
        // THE REPORTED BUG. Native video runs in a foreground media service that
        // keeps playing when the app is hidden, and nothing paused it -- so
        // locking the screen gave background audio to a user who never asked
        // for it.
        assert_eq!(
            background_action(true, false, false),
            BackgroundAction::Pause
        );
    }

    #[test]
    fn video_with_the_toggle_hands_off_to_audio() {
        assert_eq!(
            background_action(true, true, false),
            BackgroundAction::HandOffToAudio
        );
    }

    #[test]
    fn music_always_keeps_playing() {
        // Backgrounding a music player and having it stop would be absurd. The
        // toggle is irrelevant here: there is no picture to give up.
        assert_eq!(
            background_action(false, false, false),
            BackgroundAction::KeepPlaying
        );
        assert_eq!(
            background_action(false, true, false),
            BackgroundAction::KeepPlaying
        );
    }

    #[test]
    fn picture_in_picture_is_not_backgrounding() {
        // The video is in a floating window and still on screen. Pausing would
        // break PiP (UR-041), which is a separate feature reached through
        // onUserLeaveHint rather than onStop.
        assert_eq!(
            background_action(true, false, true),
            BackgroundAction::KeepPlaying
        );
        assert_eq!(
            background_action(true, true, true),
            BackgroundAction::KeepPlaying
        );
    }

    #[test]
    fn the_rule_does_not_depend_on_the_renderer() {
        // There is deliberately no renderer parameter. The WebView path and the
        // native path must answer identically -- the split between them is what
        // produced the defect, because the toggle only ever reached one.
        for armed in [true, false] {
            let once = background_action(true, armed, false);
            let again = background_action(true, armed, false);
            assert_eq!(once, again);
        }
    }

    #[test]
    fn only_video_counts_as_having_a_picture() {
        assert!(is_video_media(MediaType::Video));
        assert!(!is_video_media(MediaType::Audio));
    }
}