[Feature]: Android app: music cache and offline mode
還沒有人認領這個 Issue。
評估
- 難度
- 5/5
- 預估耗時
- 一週以上
- 新手友好度
- 15/100
- Issue 類型
- 功能
- 描述清晰度
- 基本清楚
- 活躍度
- 活躍
- 技術堆疊
- android, kotlin, react-native, typescript
研究方向
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.
由索引模型根據 Issue 內容生成。
描述
[!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.
- 主要語言
- TypeScript
- 星號
- 4
- 分支
- 1
- 平均合併
- 4 小時 49 分鐘
- 30 天內合併 PR
- 5
環境準備
- 提供 Dockerfile 或 Docker Compose 檔案
- 沒有 Pull Request 範本
- 沒有貢獻指南
從這裡開始
- 先讀完整個 Issue,再讀專案的貢獻指南。
- 在 Issue 下留言說明你要接手 —— 這能避免兩個人做同樣的事。
- Fork 儲存庫,在一個分支上完成修改。
- 送出 Pull Request,並在描述裡引用這個 Issue 編號。
tinystream-dev/tinystream 的其他 Issue
-
bug
難度 2/5 1-3 小時 新手友好度 82/100
tinystream-dev/tinystream#132 ·
-
bug
難度 2/5 1-3 小時 新手友好度 82/100
tinystream-dev/tinystream#131 ·
-
bug
難度 1/5 1 小時以內 新手友好度 88/100
tinystream-dev/tinystream#129 ·
-
bug
難度 2/5 1-3 小時 新手友好度 76/100
tinystream-dev/tinystream#128 ·
-
bug
難度 2/5 1-3 小時 新手友好度 78/100
tinystream-dev/tinystream#124 ·
查看 tinystream-dev/tinystream 的全部 Issue
相似的 Issue
-
bug frontend
難度 2/5 1-3 小時 新手友好度 85/100
CivicTechWR/accessible-housing-portal#578 ·
維護者通常 1 天內回覆
-
難度 2/5 1-3 小時 新手友好度 68/100
nekko-labs/nekko-agent#2998 ·
維護者通常 1 天內回覆
-
難度 1/5 1 小時以內 新手友好度 86/100
sandbox-quantum/switch#2163 ·
維護者通常 1 天內回覆
-
enhancement ux
難度 2/5 1-3 小時 新手友好度 72/100
lolimmlost/aidj#433 ·
維護者通常 1 天內回覆
-
test: ipcShownDialogKeys.test.tsx can fail the unit run with 'window is not defined' after it ends未關閉
難度 2/5 1-3 小時 新手友好度 72/100
維護者通常 1 天內回覆