Mini player missing when opening BookWave from active media notification #75

Closed
opened 2026-09-21 19:56:05 +02:00 by alexander · 0 comments
Owner

Problem

When playback is already active and BookWave is opened by tapping the media notification, the app can enter the normal navigation UI with no mini player visible.

That leaves the listener without an obvious in-app path to:

  • open the full player;
  • pause/resume;
  • seek/skip;
  • access player controls while navigating the app.

Expected behavior

The player chrome has one invariant:

If a book is loaded in the active MediaSession, the mini player is visible on every normal app screen except while the full player is expanded.

This must hold regardless of how playback was started or how the UI process/activity was entered:

  • playback started from the app;
  • notification/system media controls;
  • Bluetooth/headset controls;
  • Android Auto;
  • playback resumption / service-owned restoration;
  • warm Activity return;
  • Activity recreation while the playback service/session remains active.

When the full player is open, the mini player does not need to be visible behind it.

Current repository evidence

Observed against main at 91a742291144204aa1c61403c424a0b4999c27c8.

MainActivity.ShelfPlayerContent always composes MiniPlayer, and MiniPlayer is visible only when PlaybackUiState.bookId != null.

PlayerViewModel.playback is a direct view of PlaybackController.state.

PlaybackController initializes that state as PlaybackUiState.Idle and establishes its MediaController connection lazily. The first connection currently happens only through controller operations such as play/toggle/seek/etc.

The playback service, however, can own a loaded/playing MediaSession without the UI-side PlaybackController ever having connected—for example playback resumption or another system controller can operate the service first. The notification session activity then launches BookWave, but the newly created UI-side controller state can remain Idle even though the service session already contains the book.

That explains the missing mini player: the UI has not attached to the already-live MediaSession, so bookId stays null.

Important implementation constraint

Do not solve this by blindly calling PlaybackController.connect() on every ordinary app launch.

The controller is deliberately lazy because building a MediaController can instantiate/start PlaybackService. Starting the playback service just because the user opened an idle app would regress the current lifecycle/notification behavior.

The implementation should establish/refresh the UI connection when there is a legitimate active-playback/session entry path (including the media notification), while preserving idle cold-launch behavior.

PlaybackService.setSessionActivity(...) currently uses launchIntent() for notification/session activity. That is a likely seam for explicitly identifying a playback-origin launch without reversing the module dependency from :playback to :app.

Ownership

Primary: Playback & Lifecycle Agent

Required review lens: UI & Experience Agent for the global chrome invariant and navigation behavior.

Required acceptance lens: Test & Acceptance Agent for cold/warm entry, Activity recreation, and real notification/system-surface verification.

Android System & Auto Agent should review if the chosen fix changes setSessionActivity, notification/session intents, or system-controller lifecycle behavior.

Acceptance criteria

  1. With a book actively playing, tap the BookWave media notification: the app opens and the mini player is visible as soon as the session state is available.
  2. Tapping the mini player opens the full player.
  3. Mini-player transport controls operate the same live MediaSession as the notification.
  4. The mini player remains available while navigating Home, Library/Browse, Search, Downloads, Settings and other normal screens.
  5. The mini player is not separately shown while the full player is expanded.
  6. The same behavior holds when playback was started/resumed without the app UI being open (notification/system resume, headset/media button, and Android Auto where applicable).
  7. Activity recreation while the playback service/session remains active restores the mini player without requiring a new playback command.
  8. Opening BookWave normally when there is no loaded playback session does not create a spurious mini player, start playback, or leave an unnecessary playback foreground service/notification.
  9. Stopping playback/clearing the MediaSession removes the mini player as today.
  10. Add regression coverage that proves an already-live service/session can be attached to by a newly created UI surface, and mutation/reversion of that attachment makes the test fail.
  11. Perform device/emulator acceptance by starting playback, leaving/destroying the Activity while playback continues, then entering through the notification.

Out of scope

  • Redesigning the mini-player visuals.
  • Changing playback-resume freshness policy.
  • Changing Android Auto browse information architecture.
  • Making the mini player visible when no book is loaded.
## Problem When playback is already active and BookWave is opened by tapping the media notification, the app can enter the normal navigation UI with **no mini player visible**. That leaves the listener without an obvious in-app path to: - open the full player; - pause/resume; - seek/skip; - access player controls while navigating the app. ## Expected behavior The player chrome has one invariant: > **If a book is loaded in the active MediaSession, the mini player is visible on every normal app screen except while the full player is expanded.** This must hold regardless of how playback was started or how the UI process/activity was entered: - playback started from the app; - notification/system media controls; - Bluetooth/headset controls; - Android Auto; - playback resumption / service-owned restoration; - warm Activity return; - Activity recreation while the playback service/session remains active. When the full player is open, the mini player does not need to be visible behind it. ## Current repository evidence Observed against `main` at `91a742291144204aa1c61403c424a0b4999c27c8`. `MainActivity.ShelfPlayerContent` always composes `MiniPlayer`, and `MiniPlayer` is visible only when `PlaybackUiState.bookId != null`. `PlayerViewModel.playback` is a direct view of `PlaybackController.state`. `PlaybackController` initializes that state as `PlaybackUiState.Idle` and establishes its `MediaController` connection lazily. The first connection currently happens only through controller operations such as play/toggle/seek/etc. The playback service, however, can own a loaded/playing MediaSession without the UI-side `PlaybackController` ever having connected—for example playback resumption or another system controller can operate the service first. The notification session activity then launches BookWave, but the newly created UI-side controller state can remain Idle even though the service session already contains the book. That explains the missing mini player: the UI has not attached to the already-live MediaSession, so `bookId` stays null. ## Important implementation constraint Do **not** solve this by blindly calling `PlaybackController.connect()` on every ordinary app launch. The controller is deliberately lazy because building a MediaController can instantiate/start `PlaybackService`. Starting the playback service just because the user opened an idle app would regress the current lifecycle/notification behavior. The implementation should establish/refresh the UI connection when there is a legitimate active-playback/session entry path (including the media notification), while preserving idle cold-launch behavior. `PlaybackService.setSessionActivity(...)` currently uses `launchIntent()` for notification/session activity. That is a likely seam for explicitly identifying a playback-origin launch without reversing the module dependency from `:playback` to `:app`. ## Ownership Primary: **Playback & Lifecycle Agent** Required review lens: **UI & Experience Agent** for the global chrome invariant and navigation behavior. Required acceptance lens: **Test & Acceptance Agent** for cold/warm entry, Activity recreation, and real notification/system-surface verification. Android System & Auto Agent should review if the chosen fix changes `setSessionActivity`, notification/session intents, or system-controller lifecycle behavior. ## Acceptance criteria 1. With a book actively playing, tap the BookWave media notification: the app opens and the mini player is visible as soon as the session state is available. 2. Tapping the mini player opens the full player. 3. Mini-player transport controls operate the same live MediaSession as the notification. 4. The mini player remains available while navigating Home, Library/Browse, Search, Downloads, Settings and other normal screens. 5. The mini player is not separately shown while the full player is expanded. 6. The same behavior holds when playback was started/resumed without the app UI being open (notification/system resume, headset/media button, and Android Auto where applicable). 7. Activity recreation while the playback service/session remains active restores the mini player without requiring a new playback command. 8. Opening BookWave normally when there is no loaded playback session does **not** create a spurious mini player, start playback, or leave an unnecessary playback foreground service/notification. 9. Stopping playback/clearing the MediaSession removes the mini player as today. 10. Add regression coverage that proves an already-live service/session can be attached to by a newly created UI surface, and mutation/reversion of that attachment makes the test fail. 11. Perform device/emulator acceptance by starting playback, leaving/destroying the Activity while playback continues, then entering through the notification. ## Out of scope - Redesigning the mini-player visuals. - Changing playback-resume freshness policy. - Changing Android Auto browse information architecture. - Making the mini player visible when no book is loaded.
Sign in to join this conversation.
No labels
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference
alexander/Audiobookshelf-Manager-Claude#75
No description provided.