[Feature]: Android app: music cache and offline mode
Nobody has claimed this yet.
Assessment
- Difficulty
- 5/5
- Estimated time
- Over a week
- Newbie friendliness
- 15/100
- Issue type
- Feature
- Clarity
- Mostly clear
- Activity status
- Active
- Tech stack
- android, kotlin, react-native, typescript
- Domain
- audio-video-rtc, backend, databases, mobile
Research direction
Read epic #40 and prerequisite #46 first; inspect the Android Kotlin RangeSource and media service, the React Native playback and settings entry points, and src/api/music.rs:955. Map the cache and playback flow before estimating the work. Done means meeting the listed acceptance criteria for caching, pinned sync, offline playback and history, queue reconciliation, notifications, and eviction; this is a broad cross-platform feature with no specific tests named.
Written by the indexing model from the issue text.
Description
[!NOTE]
This issue was written by Claude (Claude Opus 5.5) from a planning session with @PhrolovaMoe. Part of #40, builds on #46. Read the epic first.
Area
Streaming / playback
Problem
On a phone, the connection to a self-hosted server comes and goes: tunnels, flights, bad reception, being away from home without a VPN. Music should keep playing through all of that. This is caching, not a "downloads" feature: what you listen to stays on the phone automatically, and you can additionally pin things to keep them.
Proposed solution
Behaviour
- Automatic cache: every track that plays is stored in full on the phone.
- Prefetch: the next 3 tracks in the queue are fetched ahead of time.
- Size limit: a setting (default 5 GB). When over the limit, the least recently played unpinned tracks are evicted (LRU).
- Pinning: albums, playlists and single tracks can be marked "Keep offline". Pinned tracks are fetched in full and never evicted. Pinned playlists stay in sync: tracks added later are fetched, and removed ones are unpinned. Sync on app start and foreground, and in the #44 background job. If the pinned total alone exceeds the limit, still keep everything pinned, and say so in settings (the limit then only governs unpinned tracks).
- Format (one setting for cache and pins):
- Original (default): the file, or
/flacwhen the decoder can't play the original - Opus:
/api/music/tracks/{id}/stream?format=opus&bitrate=<128|160|192|256>, default 160 kbps - With Opus selected, uncached tracks also play from the Opus stream, so the bytes played are the bytes cached and nothing is downloaded twice. Changing the format doesn't re-download existing cache entries; they're replaced as they're evicted.
- Original (default): the file, or
- Networks: settings for "Use mobile data for caching what's playing and up next" (default on) and "Use mobile data for pinned music" (default off). With the first off, tracks still stream on mobile data, but only the bytes needed for playback are fetched and nothing is prefetched.
Storage
- App-private storage (
filesDir, deleted with the app), undermusic-cache/<serverId>/<trackId>.<ext>. - Write to
.partfiles and rename when complete. - An index in expo-sqlite:
- tracks:
server, trackId, format, path, bytes, complete, lastPlayed, pinnedBy[] - the GraphQL JSON of each cached track, its album and its artist, plus cover images (through
expo-image's disk cache, or stored alongside), so offline browsing doesn't need the server
- tracks:
- Per-server isolation. Removing a server (#42) deletes its cache.
How it plugs into playback
- The Kotlin
RangeSource(#46) checks the cache first:- complete file → read it locally
- partially downloading (being cached right now) → serve ranges from the part file, blocking until those bytes have arrived
- otherwise → network
- For the original/flac formats, the cache writer downloads the whole file progressively (an ordinary GET, one stream) while the decoder reads ranges from the growing file. Seeking past what's downloaded uses a direct Range request without waiting.
- For Opus,
/streamis a live transcode without Range support. Seeking ahead of the downloaded part waits for it to arrive; the transcode runs much faster than real time, so this is fine. The one exception is the first play of a long track after a far seek: then use/stream?start=<sec>directly and don't cache that session. - Prefetching runs in a background coroutine in the media service, only while playing, with at most 1 concurrent download besides the playing track.
Pinned fetching and Live Update
- Pinned fetching runs as a WorkManager job (expedited, foreground service type
dataSync), resuming after restarts and connectivity changes, and respecting the network setting. - Its notification is a Live Update on Android 16:
- a promoted ongoing notification (
Notification.ProgressStyle,setRequestPromotedOngoing(true)) - a status bar chip showing progress
- text like "Caching Album — 7 of 12", with Pause and Cancel actions
- a promoted ongoing notification (
- On Android 14–15, show the same notification as a normal ongoing progress notification.
- Background caching of what's playing and prefetching stay silent (no notification beyond the media one).
Offline mode
- Offline means the active server is unreachable (a network error on its status query, or no network at all according to
@react-native-community/netinfo). Check again with backoff and on connectivity changes. - While offline:
- A banner: "Offline: showing music on this phone".
- The Music tab shows only cached content (albums with any cached tracks; uncached tracks greyed out), built from the sqlite metadata.
- Other tabs show an offline state with Retry.
- The mini-player and Now Playing work normally.
- Lyrics show only if they were cached with the track. Cache them when the track is cached.
- Offline plays:
- Each
Played(and star/unstar) while offline goes into an sqlite outbox with its timestamp, and is flushed in order when back online. - Server change:
played(trackId)(src/api/music.rs:955) recordsnow(). Add an optionalat: DateTimeargument (bounded: not in the future, not older than 30 days), and pass it tocatalog::record_play.
- Each
- Queue offline: the queue is edited locally. When back online, push it with
SavePlayQueueunless the server's queue changed after the app went offline; in that case, ask "Keep the queue from this phone or from the server?".
UI
- "Keep offline" toggles on album, playlist and track menus and headers.
- Badges: a small icon for cached tracks and a pin icon for pinned ones.
- Settings → This device → Music cache:
- storage used (cache vs pinned), with a bar
- size limit, format and bitrate, network toggles
- "Clear cache" (keeps pins), and a list of pinned items with unpin
Acceptance criteria
- Play an album, enable airplane mode and play it again: it works, gaplessly.
- Prefetch: with the next 3 tracks fetched, airplane mode mid-track doesn't interrupt the next 3.
- A pinned playlist fetches with a Live Update chip on Android 16 (and a normal notification on 14/15), survives an app restart, and picks up tracks added on the web.
- Eviction keeps usage under the limit and never touches pinned tracks.
- Offline plays appear in the server's history with the right times after reconnecting.
- Opus caching plays gaplessly and is roughly 1/5 the size of FLAC.
- Dominant language
- TypeScript
- Stars
- 4
- Forks
- 1
- Avg merge
- 4h 49m
- Merged PRs (30d)
- 5
Getting set up
- Ships a Dockerfile or Docker Compose file
- No pull request template
- No contributing guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
More from tinystream-dev/tinystream
-
bug
Difficulty 2/5 1-3 hours Newbie friendliness 82/100
tinystream-dev/tinystream#132 ·
-
bug
Difficulty 2/5 1-3 hours Newbie friendliness 82/100
tinystream-dev/tinystream#131 ·
-
bug
Difficulty 1/5 Under an hour Newbie friendliness 88/100
tinystream-dev/tinystream#129 ·
-
bug
Difficulty 2/5 1-3 hours Newbie friendliness 76/100
tinystream-dev/tinystream#128 ·
-
bug
Difficulty 2/5 1-3 hours Newbie friendliness 78/100
tinystream-dev/tinystream#124 ·
All issues in tinystream-dev/tinystream
Similar issues
-
Console writes URL credentials to the local log, though AGENTS.md says secrets never reach diskOpen
Difficulty 1/5 Under an hour Newbie friendliness 86/100
sandbox-quantum/switch#2163 ·
Maintainers usually reply within 1 day
-
automated issue report
Difficulty 1/5 Under an hour Newbie friendliness 78/100
Maintainers usually reply within 1 day
-
area/dashboard kind/bug QA/dev-automation
Difficulty 1/5 Under an hour Newbie friendliness 75/100
Maintainers usually reply within 1 day
-
bug pydanty:is-working
Difficulty 2/5 1-3 hours Newbie friendliness 82/100
pydantic/pydantic-ai#13939 ·
Maintainers usually reply within 1 day
-
self-host
Difficulty 2/5 1-3 hours Newbie friendliness 70/100
funmusicplace/mirlo#2625 ·
Maintainers usually reply within 1 day