Background-audio handoff for video + repository/player refactor

Hand video playback off to a native audio-only stream when the app is
backgrounded or locked, with no on-device video decode (UR-040). Adds
player_enter/exit_background_audio commands, an audio-only stream URL
for video items across the repository layer, and the frontend handoff
state machine wired into VideoPlayer. Includes accompanying
repository/offline/player refactoring and regenerates the traceability
matrix.

src-tauri/src/lib.rs

@@ -14,120 +14,285 @@ mod storage;
 mod thumbnail;
 pub mod utils;
 
-use std::sync::{Arc, Mutex};
-use tokio::sync::Mutex as TokioMutex;
-use tauri::{Emitter, Manager};
-use tauri_specta::Builder;
-use log::{error, info};
 #[cfg(target_os = "android")]
 use log::warn;
+use log::{error, info};
+use std::sync::{Arc, Mutex};
+use tauri::{Emitter, Manager};
+use tauri_specta::Builder;
+use tokio::sync::Mutex as TokioMutex;
 
-use commands::{
-    sync_full_catalog, catalog_sync_status, set_show_server_catalog, resume_queued_downloads,
-    cancel_download, clear_stale_downloads, delete_album_downloads, delete_all_downloads, delete_download,
-    download_album, download_item, download_item_and_start, download_video, download_series, download_season,
-    get_download_storage_stats, get_downloads, get_download_manager_stats, set_max_concurrent_downloads,
-    get_smart_cache_stats, update_smart_cache_config, get_smart_cache_config, get_album_recommendations,
-    get_album_affinity_status,
-    mark_download_completed, mark_download_failed, start_download, enqueue_download, enqueue_video_downloads,
-    pin_item, unpin_item, is_item_pinned,
-    offline_get_items, offline_is_available, offline_search, pause_download, resume_download,
-    player_cycle_repeat, player_get_audio_settings, player_get_queue, player_get_status,
-    player_get_video_settings, player_next, player_pause, player_play, player_play_album_track,
-    player_play_item, player_play_queue, player_play_tracks, player_previous, player_seek, player_seek_video, player_set_audio_settings, player_set_audio_track, player_switch_audio_track,
-    player_set_subtitle_track, player_set_video_settings, player_set_volume, player_toggle_mute, player_stop, player_toggle,
-    player_toggle_shuffle,
-    // Sleep timer and autoplay commands
-    player_set_sleep_timer, player_cancel_sleep_timer, player_get_sleep_timer,
-    player_get_autoplay_settings, player_set_autoplay_settings,
-    player_cancel_autoplay_countdown, player_play_next_episode, player_on_playback_ended,
-    // HTML5 video state-report commands
-    player_report_state, player_report_position, player_report_media_loaded,
-    // Queue manipulation commands
-    player_add_to_queue, player_add_track_by_id, player_add_tracks_by_ids,
-    player_remove_from_queue, player_move_in_queue, player_skip_to,
-    // Preload commands
-    player_preload_upcoming, player_set_cache_config, player_get_cache_config,
-    // Jellyfin reporting commands
-    player_configure_jellyfin, player_disable_jellyfin,
-    // Session management commands
-    player_get_session, player_dismiss_session,
-    // Remote session control commands
-    remote_play_on_session, remote_send_command, remote_session_seek, remote_session_set_volume,
-    remote_session_toggle_mute,
-    // LMS multi-room sync group commands
-    lms_get_sync_groups, lms_create_sync_group, lms_unsync_player, lms_dissolve_sync_group,
-    // Session polling commands
-    sessions_set_polling_hint, sessions_poll_now, SessionPollerWrapper,
-    // Playback mode commands
-    playback_mode_get_current, playback_mode_set, playback_mode_is_transferring,
-    playback_mode_transfer_to_remote, playback_mode_transfer_to_local, playback_mode_set_transferring,
-    playback_mode_get_remote_status,
-    // Playback reporting commands
-    playback_reporter_init, playback_reporter_destroy,
-    playback_report_start, playback_report_progress, playback_report_stopped,
-    playback_mark_played, PlaybackReporterWrapper,
-    // Auth commands
-    auth_initialize, auth_connect_to_server, auth_login, auth_verify_session,
-    auth_logout, auth_get_session, auth_set_session, auth_start_verification,
-    auth_stop_verification, auth_reauthenticate,
-    // Device commands
-    device_get_id, device_set_id,
-    // Connectivity commands
-    connectivity_check_server, connectivity_set_server_url, connectivity_get_status,
-    connectivity_start_monitoring, connectivity_stop_monitoring,
-    connectivity_mark_reachable, connectivity_mark_unreachable,
-    // Storage commands
-    storage_delete_server, storage_delete_user, storage_get_access_token,
-    storage_get_active_session, storage_get_active_user, storage_get_path,
-    storage_get_playback_progress, storage_get_security_status, storage_get_servers, storage_get_size,
-    storage_get_users, storage_init, storage_mark_played, storage_mark_synced, storage_save_server,
-    storage_save_user, storage_set_active_user, storage_toggle_favorite, storage_update_playback_progress,
-    storage_update_playback_context,
-    // Offline cache commands
-    storage_get_libraries, storage_get_items, storage_get_item, storage_search_items,
-    storage_save_library, storage_save_item, storage_get_pending_sync_count,
-    // Sync queue commands
-    sync_queue_mutation, sync_get_pending, sync_mark_processing, sync_mark_completed,
-    sync_mark_failed, sync_get_pending_count, sync_cleanup_completed, sync_clear_user,
-    // Thumbnail cache and image commands
-    thumbnail_get_cached, thumbnail_save, thumbnail_get_stats, thumbnail_set_limit,
-    thumbnail_clear_cache, thumbnail_delete_item, image_get_url,
-    // People cache commands
-    storage_save_person, storage_get_person, storage_save_item_people, storage_get_item_people,
-    // Series audio preferences
-    storage_save_series_audio_preference, storage_get_series_audio_preference,
-    // Repository commands
-    repository_create, repository_destroy, repository_get_libraries, repository_get_items,
-    repository_get_item, repository_jray_actors_at, repository_get_latest_items, repository_get_resume_items,
-    repository_get_next_up_episodes, repository_get_recently_played_audio, repository_get_resume_movies,
-    repository_get_rediscover_albums,
-    repository_get_genres, repository_search, repository_get_playback_info,
-    repository_get_video_stream_url, repository_get_audio_stream_url,
-    repository_get_live_tv_channels, repository_get_channels, repository_open_live_stream,
-    repository_report_playback_start, repository_report_playback_progress, repository_report_playback_stopped,
-    repository_get_image_url, repository_mark_favorite, repository_unmark_favorite,
-    repository_get_person, repository_get_items_by_person, repository_get_similar_items,
-    repository_get_subtitle_url, repository_get_video_download_url,
-    // Playlist commands
-    playlist_create, playlist_delete, playlist_rename, playlist_get_items,
-    playlist_add_items, playlist_remove_items, playlist_move_item,
-    // Conversion commands
-    format_time_seconds, format_time_seconds_long, convert_ticks_to_seconds,
-    calc_progress, convert_percent_to_volume,
-    AuthManagerWrapper, SessionVerifierWrapper,
-    ConnectivityMonitorWrapper, CredentialStoreWrapper, DatabaseWrapper, PlayerStateWrapper,
-    MediaSessionManagerWrapper, VideoSettingsWrapper, ThumbnailCacheWrapper, SmartCacheWrapper,
-    PlaybackModeManagerWrapper, RepositoryManagerWrapper, DownloadManagerWrapper,
-};
-#[cfg(target_os = "android")]
-use playback_mode::PlaybackModeManager;
 use auth::AuthManager;
+use commands::{
+    auth_connect_to_server,
+    auth_get_session,
+    // Auth commands
+    auth_initialize,
+    auth_login,
+    auth_logout,
+    auth_reauthenticate,
+    auth_set_session,
+    auth_start_verification,
+    auth_stop_verification,
+    auth_verify_session,
+    calc_progress,
+    cancel_download,
+    catalog_sync_status,
+    clear_stale_downloads,
+    // Connectivity commands
+    connectivity_check_server,
+    connectivity_get_status,
+    connectivity_mark_reachable,
+    connectivity_mark_unreachable,
+    connectivity_set_server_url,
+    connectivity_start_monitoring,
+    connectivity_stop_monitoring,
+    convert_percent_to_volume,
+    convert_ticks_to_seconds,
+    delete_album_downloads,
+    delete_all_downloads,
+    delete_download,
+    // Device commands
+    device_get_id,
+    device_set_id,
+    download_album,
+    download_item,
+    download_item_and_start,
+    download_season,
+    download_series,
+    download_video,
+    enqueue_download,
+    enqueue_video_downloads,
+    // Conversion commands
+    format_time_seconds,
+    format_time_seconds_long,
+    get_album_affinity_status,
+    get_album_recommendations,
+    get_download_manager_stats,
+    get_download_storage_stats,
+    get_downloads,
+    get_smart_cache_config,
+    get_smart_cache_stats,
+    image_get_url,
+    is_item_pinned,
+    lms_create_sync_group,
+    lms_dissolve_sync_group,
+    // LMS multi-room sync group commands
+    lms_get_sync_groups,
+    lms_unsync_player,
+    mark_download_completed,
+    mark_download_failed,
+    offline_get_items,
+    offline_is_available,
+    offline_search,
+    pause_download,
+    pin_item,
+    playback_mark_played,
+    // Playback mode commands
+    playback_mode_get_current,
+    playback_mode_get_remote_status,
+    playback_mode_is_transferring,
+    playback_mode_set,
+    playback_mode_set_transferring,
+    playback_mode_transfer_to_local,
+    playback_mode_transfer_to_remote,
+    playback_report_progress,
+    playback_report_start,
+    playback_report_stopped,
+    playback_reporter_destroy,
+    // Playback reporting commands
+    playback_reporter_init,
+    // Queue manipulation commands
+    player_add_to_queue,
+    player_add_track_by_id,
+    player_add_tracks_by_ids,
+    player_cancel_autoplay_countdown,
+    player_cancel_sleep_timer,
+    // Jellyfin reporting commands
+    player_configure_jellyfin,
+    player_cycle_repeat,
+    player_disable_jellyfin,
+    player_dismiss_session,
+    player_enter_background_audio,
+    player_exit_background_audio,
+    player_get_audio_settings,
+    player_get_autoplay_settings,
+    player_get_cache_config,
+    player_get_queue,
+    // Session management commands
+    player_get_session,
+    player_get_sleep_timer,
+    player_get_status,
+    player_get_video_settings,
+    player_move_in_queue,
+    player_next,
+    player_on_playback_ended,
+    player_pause,
+    player_play,
+    player_play_album_track,
+    player_play_item,
+    player_play_next_episode,
+    player_play_queue,
+    player_play_tracks,
+    // Preload commands
+    player_preload_upcoming,
+    player_previous,
+    player_remove_from_queue,
+    player_report_media_loaded,
+    player_report_position,
+    // HTML5 video state-report commands
+    player_report_state,
+    player_seek,
+    player_seek_video,
+    player_set_audio_settings,
+    player_set_audio_track,
+    player_set_autoplay_settings,
+    player_set_cache_config,
+    // Sleep timer and autoplay commands
+    player_set_sleep_timer,
+    player_set_subtitle_track,
+    player_set_video_settings,
+    player_set_volume,
+    player_skip_to,
+    player_stop,
+    player_switch_audio_track,
+    player_toggle,
+    player_toggle_mute,
+    player_toggle_shuffle,
+    playlist_add_items,
+    // Playlist commands
+    playlist_create,
+    playlist_delete,
+    playlist_get_items,
+    playlist_move_item,
+    playlist_remove_items,
+    playlist_rename,
+    // Remote session control commands
+    remote_play_on_session,
+    remote_send_command,
+    remote_session_seek,
+    remote_session_set_volume,
+    remote_session_toggle_mute,
+    // Repository commands
+    repository_create,
+    repository_destroy,
+    repository_get_audio_only_stream_url_for_video,
+    repository_get_audio_stream_url,
+    repository_get_channels,
+    repository_get_genres,
+    repository_get_image_url,
+    repository_get_item,
+    repository_get_items,
+    repository_get_items_by_person,
+    repository_get_latest_items,
+    repository_get_libraries,
+    repository_get_live_tv_channels,
+    repository_get_next_up_episodes,
+    repository_get_person,
+    repository_get_playback_info,
+    repository_get_recently_played_audio,
+    repository_get_rediscover_albums,
+    repository_get_resume_items,
+    repository_get_resume_movies,
+    repository_get_similar_items,
+    repository_get_subtitle_url,
+    repository_get_video_download_url,
+    repository_get_video_stream_url,
+    repository_jray_actors_at,
+    repository_mark_favorite,
+    repository_open_live_stream,
+    repository_report_playback_progress,
+    repository_report_playback_start,
+    repository_report_playback_stopped,
+    repository_search,
+    repository_unmark_favorite,
+    resume_download,
+    resume_queued_downloads,
+    sessions_poll_now,
+    // Session polling commands
+    sessions_set_polling_hint,
+    set_max_concurrent_downloads,
+    set_show_server_catalog,
+    start_download,
+    // Storage commands
+    storage_delete_server,
+    storage_delete_user,
+    storage_get_access_token,
+    storage_get_active_session,
+    storage_get_active_user,
+    storage_get_item,
+    storage_get_item_people,
+    storage_get_items,
+    // Offline cache commands
+    storage_get_libraries,
+    storage_get_path,
+    storage_get_pending_sync_count,
+    storage_get_person,
+    storage_get_playback_progress,
+    storage_get_security_status,
+    storage_get_series_audio_preference,
+    storage_get_servers,
+    storage_get_size,
+    storage_get_users,
+    storage_init,
+    storage_mark_played,
+    storage_mark_synced,
+    storage_save_item,
+    storage_save_item_people,
+    storage_save_library,
+    // People cache commands
+    storage_save_person,
+    // Series audio preferences
+    storage_save_series_audio_preference,
+    storage_save_server,
+    storage_save_user,
+    storage_search_items,
+    storage_set_active_user,
+    storage_toggle_favorite,
+    storage_update_playback_context,
+    storage_update_playback_progress,
+    sync_cleanup_completed,
+    sync_clear_user,
+    sync_full_catalog,
+    sync_get_pending,
+    sync_get_pending_count,
+    sync_mark_completed,
+    sync_mark_failed,
+    sync_mark_processing,
+    // Sync queue commands
+    sync_queue_mutation,
+    thumbnail_clear_cache,
+    thumbnail_delete_item,
+    // Thumbnail cache and image commands
+    thumbnail_get_cached,
+    thumbnail_get_stats,
+    thumbnail_save,
+    thumbnail_set_limit,
+    unpin_item,
+    update_smart_cache_config,
+    AuthManagerWrapper,
+    ConnectivityMonitorWrapper,
+    CredentialStoreWrapper,
+    DatabaseWrapper,
+    DownloadManagerWrapper,
+    MediaSessionManagerWrapper,
+    PlaybackModeManagerWrapper,
+    PlaybackReporterWrapper,
+    PlayerStateWrapper,
+    RepositoryManagerWrapper,
+    SessionPollerWrapper,
+    SessionVerifierWrapper,
+    SmartCacheWrapper,
+    ThumbnailCacheWrapper,
+    VideoSettingsWrapper,
+};
 use connectivity::ConnectivityMonitor;
 use credentials::CredentialStore;
 use download::cache::{CacheConfig as SmartCacheConfig, SmartCache};
 use download::DownloadManager;
 use jellyfin::{HttpClient, HttpConfig};
+#[cfg(target_os = "android")]
+use playback_mode::PlaybackModeManager;
 use player::{MediaSessionManager, PlayerBackend, PlayerController, TauriEventEmitter};
 // NullBackend is used both for platforms without a native backend AND as a graceful
 // fallback when a native backend (MPV/ExoPlayer) fails to initialize, so the app can
@@ -138,7 +303,7 @@ use player::NullBackend;
 use player::MpvBackend;
 use settings::VideoSettings;
 use storage::Database;
-use thumbnail::{ThumbnailCache, CacheConfig as ThumbnailCacheConfig};
+use thumbnail::{CacheConfig as ThumbnailCacheConfig, ThumbnailCache};
 
 #[cfg(target_os = "android")]
 use credentials::initialize_secure_storage;
@@ -147,7 +312,9 @@ use credentials::initialize_secure_storage;
 use player::ExoPlayerBackend;
 
 #[cfg(target_os = "android")]
-use player::{MediaCommandHandler, RemoteVolumeHandler, set_media_command_handler, set_remote_volume_handler};
+use player::{
+    set_media_command_handler, set_remote_volume_handler, MediaCommandHandler, RemoteVolumeHandler,
+};
 
 /// Handler for media commands from Android MediaSession (lockscreen/notification controls).
 ///
@@ -210,7 +377,11 @@ impl MediaSessionHandler {
                 "play" => client.send_session_command(session_id, "Unpause").await,
                 "pause" => client.send_session_command(session_id, "Pause").await,
                 "next" => client.send_session_command(session_id, "NextTrack").await,
-                "previous" => client.send_session_command(session_id, "PreviousTrack").await,
+                "previous" => {
+                    client
+                        .send_session_command(session_id, "PreviousTrack")
+                        .await
+                }
                 cmd if cmd.starts_with("seek:") => match cmd[5..].parse::<f64>() {
                     Ok(seconds) => {
                         let ticks = (seconds * 10_000_000.0) as i64;
@@ -297,7 +468,10 @@ impl RemoteVolumeHandler for RemoteVolumeSessionHandler {
         log::info!("[RemoteVolume] Spawning async task to send volume command...");
         tauri::async_runtime::spawn(async move {
             log::info!("[RemoteVolume] Async task started, calling send_remote_volume_command...");
-            match playback_mode.send_remote_volume_command(&command_str, volume).await {
+            match playback_mode
+                .send_remote_volume_command(&command_str, volume)
+                .await
+            {
                 Ok(_) => log::info!("[RemoteVolume] Volume command completed successfully"),
                 Err(e) => log::error!("[RemoteVolume] Failed to send volume command: {}", e),
             }
@@ -355,9 +529,16 @@ fn create_player_backend(
             Ok(java_vm) => {
                 match java_vm.attach_current_thread() {
                     Ok(mut env) => {
-                        let context_obj = unsafe { jni::objects::JObject::from_raw(ctx.context().cast()) };
+                        let context_obj =
+                            unsafe { jni::objects::JObject::from_raw(ctx.context().cast()) };
 
-                        match ExoPlayerBackend::new(&mut env, &context_obj, _event_emitter.clone(), playback_reporter.clone(), position_throttler.clone()) {
+                        match ExoPlayerBackend::new(
+                            &mut env,
+                            &context_obj,
+                            _event_emitter.clone(),
+                            playback_reporter.clone(),
+                            position_throttler.clone(),
+                        ) {
                             Ok(backend) => {
                                 info!("Successfully initialized ExoPlayer backend for Android");
                                 return Box::new(backend);
@@ -370,13 +551,21 @@ fn create_player_backend(
                         }
                     }
                     Err(e) => {
-                        emit_backend_init_failed(&app_handle, "exoplayer", format!("attach JNI thread failed: {}", e));
+                        emit_backend_init_failed(
+                            &app_handle,
+                            "exoplayer",
+                            format!("attach JNI thread failed: {}", e),
+                        );
                         return Box::new(NullBackend::new());
                     }
                 }
             }
             Err(e) => {
-                emit_backend_init_failed(&app_handle, "exoplayer", format!("create JavaVM failed: {}", e));
+                emit_backend_init_failed(
+                    &app_handle,
+                    "exoplayer",
+                    format!("create JavaVM failed: {}", e),
+                );
                 return Box::new(NullBackend::new());
             }
         }
@@ -440,6 +629,8 @@ fn specta_builder() -> Builder<tauri::Wry> {
         .commands(tauri_specta::collect_commands![
             // Player commands
             player_play_item,
+            player_enter_background_audio,
+            player_exit_background_audio,
             player_play_queue,
             player_play_album_track,
             player_play_tracks,
@@ -656,6 +847,7 @@ fn specta_builder() -> Builder<tauri::Wry> {
             repository_get_playback_info,
             repository_get_video_stream_url,
             repository_get_audio_stream_url,
+            repository_get_audio_only_stream_url_for_video,
             repository_get_live_tv_channels,
             repository_get_channels,
             repository_open_live_stream,
@@ -722,7 +914,12 @@ fn enable_linux_hardware_video_decoding() {
 #[cfg(target_os = "linux")]
 fn log_available_vaapi_decoders() {
     const HW_DECODERS: &[&str] = &[
-        "vah264dec", "vah265dec", "vavp9dec", "vaav1dec", "vampeg2dec", "vavp8dec",
+        "vah264dec",
+        "vah265dec",
+        "vavp9dec",
+        "vaav1dec",
+        "vampeg2dec",
+        "vavp8dec",
     ];
 
     let available: Vec<&str> = HW_DECODERS
@@ -1055,7 +1252,6 @@ pub fn run() {
         .expect("error while running tauri application");
 }
 
-
 #[cfg(test)]
 mod specta_bindings {
     /// Generates `src/lib/api/bindings.ts`. Run with `cargo test export_typescript_bindings`.
@@ -1063,9 +1259,10 @@ mod specta_bindings {
     fn export_typescript_bindings() {
         super::specta_builder()
             .export(
-                specta_typescript::Typescript::default().bigint(specta_typescript::BigIntExportBehavior::Number),
+                specta_typescript::Typescript::default()
+                    .bigint(specta_typescript::BigIntExportBehavior::Number),
                 "../src/lib/api/bindings.ts",
             )
             .expect("failed to export typescript bindings");
     }
-}
+}