184 lines
10 KiB
Markdown
184 lines
10 KiB
Markdown
# Offline Parity: Browse, Artwork & Downloads Queue
|
||
|
||
## Context
|
||
|
||
When the device is offline, the app is far less usable than when streaming, even
|
||
though downloaded content exists on disk:
|
||
|
||
- **Albums / Artists / Tracks load blank.** `browser_screen.dart` hard-gates the
|
||
whole Browse area behind a live `SubsonicClient`, and the backing providers
|
||
(`artistsProvider`, `albumsProvider`) return `const []` while
|
||
`LibraryIndexController.ensureBuilt()` bails before touching its cache when
|
||
`client == null`. So the only way to reach downloaded music offline is the
|
||
Downloads tab.
|
||
- **The Downloads tab plays one song at a time.** Tapping a saved track calls
|
||
`playback.playSongs([d.song])` — a single-element queue — and the screen has no
|
||
shuffle / play-all / play-next / add-to-queue controls that every streaming
|
||
screen has.
|
||
- **No offline artwork.** Downloads save only the audio file and the `coverArt`
|
||
*id*; the image itself is never cached, and all art URIs are built inline via
|
||
`client.coverArtUri(...)` guarded by `client != null`, so offline every cover
|
||
goes blank.
|
||
|
||
**Decisions made with the user:**
|
||
1. Offline browse views show **downloaded content only** (reconstructed from the
|
||
downloads manifest) — everything shown is guaranteed playable. Online browse is
|
||
unchanged (server-backed).
|
||
2. Downloading a track **also caches its cover art** to disk so offline browse and
|
||
Now Playing show real artwork.
|
||
|
||
**Intended outcome:** offline, the Albums / Artists / Tracks tabs, their detail
|
||
screens, artwork, and the Downloads tab all behave like a first-class local
|
||
library with full queue controls — parity with the streaming experience, scoped to
|
||
what's been downloaded.
|
||
|
||
The key enabler already exists: the downloads manifest persists the **full
|
||
`Song`** per completed track (`DownloadInfo.song` → `song.toJson()`), carrying
|
||
`albumId`, `artistId`, `album`, `artist`, `coverArt`, `year`, `genre`, `track`,
|
||
`discNumber`. That is enough to reconstruct Albums/Artists/Tracks. The
|
||
`playlists.dart` controller is an in-repo precedent for the offline-mirror pattern.
|
||
|
||
---
|
||
|
||
## Part A — Reconstruct the offline library from downloads
|
||
|
||
### A1. New pure module: `lib/library/offline_library.dart`
|
||
Pure, I/O-free grouping functions over `List<Song>` (mirrors the style of
|
||
`library/browse_query.dart`):
|
||
- `List<Album> albumsFromSongs(List<Song> songs)` — group by `albumId` (fallback:
|
||
album name), synthesize an `Album` (id, name, artist, artistId, coverArt, year,
|
||
genre, `songCount`, and `songs:` sorted by disc/track).
|
||
- `List<Artist> artistsFromSongs(List<Song> songs)` — group by `artistId`
|
||
(fallback: artist name), synthesize an `Artist` (id, name, coverArt from any
|
||
album, `albumCount`, and `albums:` built via `albumsFromSongs`).
|
||
- `Album? albumFromSongs(...)` / `Artist? artistFromSongs(...)` helpers keyed by id
|
||
for the detail providers.
|
||
|
||
These reuse the existing `Album`/`Artist`/`Song` models in `subsonic/models.dart`.
|
||
|
||
### A2. Providers gain an offline branch — `lib/state/providers.dart`
|
||
Introduce one shared source-of-songs seam so all three views stay consistent:
|
||
- `downloadedSongsProvider` → `ref.watch(downloadManagerProvider).completed.map((d) => d.song)`.
|
||
|
||
Then wire offline fallbacks (offline = `subsonicClientProvider == null`):
|
||
- `artistsProvider`: when `client == null`, return `artistsFromSongs(downloadedSongs)`
|
||
instead of `const []`.
|
||
- `albumsProvider`: when `client == null`, return `albumsFromSongs(downloadedSongs)`.
|
||
- Tracks: add offline handling to `visibleTracksProvider`, `trackGenresProvider`,
|
||
`trackYearsProvider` so that when offline they derive from `downloadedSongs`
|
||
rather than the (empty, wiped-on-disconnect) `libraryIndexProvider`. Keep
|
||
reusing `applyTrackQuery` / `applyAlbumQuery` / `distinctGenres` / `distinctYears`
|
||
for sort+filter so offline behaves identically to online.
|
||
- Detail families `artistProvider` / `albumProvider`: when `client == null`, build
|
||
from `albumFromSongs` / `artistFromSongs` instead of throwing `StateError`.
|
||
|
||
Each affected provider must also `watch` `downloadManagerProvider` so the lists
|
||
populate as downloads complete and recompute on connect/disconnect.
|
||
|
||
### A3. Un-gate the Browse screen — `lib/screens/browser_screen.dart`
|
||
- Replace the blanket `client == null → _NotConnected` gate (≈ lines 84–96) with:
|
||
render the `_ArtistsPanel` / `_AlbumsPanel` / `_TracksPanel` whenever there is
|
||
data to show; keep `_NotConnected` only when offline **and** there are zero
|
||
downloads (message tuned to "You're offline — download music to browse it here").
|
||
- `_TracksPanelState.initState`: only call `ensureBuilt()` when online; offline the
|
||
songs come from the A2 fallback, so skip the crawl.
|
||
- Leave `LibraryIndexController` untouched — the offline path deliberately does not
|
||
use the full cached catalog (decision: downloaded-only).
|
||
|
||
---
|
||
|
||
## Part B — Cache cover art on download + offline art resolver
|
||
|
||
### B1. Save artwork with each download — `lib/downloads/download_manager.dart`
|
||
- In `_run(...)`, after the audio file lands, if `song.coverArt != null` and that
|
||
art id isn't already cached, fetch `client.coverArtUri(song.coverArt!, size: 512)`
|
||
via the existing `_dio` and save to `downloads/<key>/art/<sanitized coverArt>.jpg`
|
||
(temp `.part` + rename, like the audio path). Dedup by `coverArt` id so all tracks
|
||
of an album share one file. Art failure is soft (never fails the audio download).
|
||
- Track cached art in state: add `Map<String,String> artById` (coverArt id →
|
||
absolute path) to `DownloadState`, populated in `reloadForServer` (scan the `art/`
|
||
dir or re-derive from completed songs' `coverArt`) and on each completed download.
|
||
- Public accessor `String? localArtPathFor(String? coverArtId)` (sync, reads state)
|
||
parallel to the existing `localPathFor(id)`.
|
||
- `remove` / `clearAll`: delete an album's art only when no remaining download
|
||
references that `coverArt` id (and wipe the `art/` dir on `clearAll`).
|
||
|
||
### B2. Central art resolver + dual-source image widget
|
||
- Add a resolver in `providers.dart` — a function/provider
|
||
`resolveArtUri(ref, {String? coverArt, int size})` that returns:
|
||
`localArtPathFor(coverArt)` as `Uri.file(...)` if cached → else
|
||
`client.coverArtUri(coverArt, size)` if online → else `null`.
|
||
- New widget `lib/widgets/art_image.dart` (`ArtImage(uri, ...)`) that picks
|
||
`FileImage` vs `NetworkImage` by URI scheme, preserving the current
|
||
`Image.network` styling/`ValueKey(artUri)`/placeholder behavior.
|
||
- Replace the inline `client.coverArtUri(...)` art-URI construction and the raw
|
||
`Image.network(artUri, ...)` calls with the resolver + `ArtImage` in:
|
||
`browser_screen.dart` (album tiles ≈240, track rows ≈382), `mini_player.dart`
|
||
(≈28/51), `now_playing_screen.dart` (≈460), `home_screen.dart` (`artFor`, ≈24–26
|
||
and its `Image.network` sites), and `cassette_view.dart` (≈139). This makes
|
||
offline artwork appear everywhere a downloaded track's art is cached.
|
||
- In the playback closure `coverArtUriFor` (`providers.dart` ≈564) prefer the local
|
||
art file too, and switch the `onArt` accent extraction to `FileImage` when the
|
||
resolved art URI is a `file://` (so accent extraction works offline).
|
||
|
||
---
|
||
|
||
## Part C — Downloads tab: queue parity
|
||
|
||
### `lib/screens/downloads_screen.dart` (template: `playlists_screen.dart`)
|
||
- Tapping a saved row plays the **whole** saved list from that index:
|
||
`playback.playSongs(completed.map((d) => d.song).toList(), startIndex: i)`
|
||
(replacing `playSongs([d.song])` at line 79). Keep the list order stable and
|
||
consistent between what's shown and what's enqueued.
|
||
- Add header controls to the "Saved" panel mirroring `playlists_screen.dart`
|
||
(≈346–356): **Play all** (`playSongs(songs)`), **Shuffle**
|
||
(`toggleShuffle()` then `playSongs(songs)`, or set shuffle + play). Reuse the same
|
||
button widgets/tokens the playlists header uses.
|
||
- Add a per-row `PopupMenuButton` (like `playlists_screen.dart` ≈494–496):
|
||
**Play next** (`playback.playNext(d.song)`), **Add to queue**
|
||
(`playback.addToQueue(d.song)`), alongside the existing delete action.
|
||
- Render each row's artwork via the B2 resolver + `ArtImage` (downloaded art is
|
||
always local, so covers show offline).
|
||
|
||
---
|
||
|
||
## Critical files
|
||
|
||
- New: `lib/library/offline_library.dart`, `lib/widgets/art_image.dart`
|
||
- `lib/state/providers.dart` — offline provider branches, `downloadedSongsProvider`,
|
||
art resolver, `coverArtUriFor`/`onArt`.
|
||
- `lib/downloads/download_manager.dart` — art download + `artById` + `localArtPathFor`.
|
||
- `lib/screens/browser_screen.dart` — un-gate offline, art via resolver.
|
||
- `lib/screens/downloads_screen.dart` — full-list enqueue + queue controls + art.
|
||
- `lib/screens/{home_screen,now_playing_screen}.dart`, `lib/widgets/{mini_player,cassette_view}.dart`
|
||
— swap art rendering to resolver + `ArtImage`.
|
||
|
||
## Reused, not rebuilt
|
||
|
||
- `applyAlbumQuery` / `applyTrackQuery` / `distinctGenres` / `distinctYears`
|
||
(`library/browse_query.dart`) — offline sort/filter.
|
||
- `DownloadState.completed`, `localPathFor` pattern (`downloads/download_manager.dart`).
|
||
- `PlaybackCommands.playSongs / toggleShuffle / playNext / addToQueue`
|
||
(`playback/playback_engine.dart`) — already fully local-file aware.
|
||
- `playlists_screen.dart` header + row-menu widgets — copy for the Downloads screen.
|
||
- Playback already prefers local files (`streamUriFor`, `providers.dart` ≈547).
|
||
|
||
## Verification
|
||
|
||
1. `flutter analyze` clean; run existing tests (`flutter test`).
|
||
2. **Online seed:** connect to a server, download a few tracks spanning ≥2 albums
|
||
and ≥2 artists (some sharing an album).
|
||
3. **Go offline** (airplane mode, or stop the server / an unreachable URL so
|
||
`ping` fails and `client == null`).
|
||
4. Browse tab:
|
||
- Artists / Albums / Tracks list exactly the downloaded content, sorted/filtered
|
||
like online; artwork shows (from cached art).
|
||
- Open an album and an artist detail — populated, all rows playable.
|
||
- With zero downloads offline, the friendly offline-empty state shows (not blank).
|
||
5. Tap a track in an offline Album → whole album enqueues starting at that track;
|
||
Shuffle / Play next / Add to queue behave like the streaming screens.
|
||
6. Downloads tab: tapping a saved song enqueues the full saved list at that index;
|
||
Play all / Shuffle header + per-row Play next / Add to queue work; covers render.
|
||
7. **Reconnect** → Browse returns to the full server catalog; nothing regressed.
|
||
8. Confirm downloaded-track artwork also renders offline in the mini-player and Now
|
||
Playing, and the accent color still extracts from the local art.
|