[Feature]: Android app: music cache and offline mode

オープン
#47 コメント 0 件 リアクション 0 件 担当者 0 名 GitHub で見る

まだ誰も着手していません。

評価

難易度
5/5
見積もり時間
1週間以上
初心者へのやさしさ
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 の本文から書いたものです。

説明

enhancement

[!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
  1. Automatic cache: every track that plays is stored in full on the phone.
  2. Prefetch: the next 3 tracks in the queue are fetched ahead of time.
  3. Size limit: a setting (default 5 GB). When over the limit, the least recently played unpinned tracks are evicted (LRU).
  4. 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).
  5. Format (one setting for cache and pins):
    • Original (default): the file, or /flac when 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.
  6. 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), under music-cache/<serverId>/<trackId>.<ext>.
  • Write to .part files 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
  • 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, /stream is 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
  • 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) records now(). Add an optional at: DateTime argument (bounded: not in the future, not older than 30 days), and pass it to catalog::record_play.
  • Queue offline: the queue is edited locally. When back online, push it with SavePlayQueue unless 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分
マージ済み PR(30日)
5

環境構築

  • Dockerfile または Docker Compose ファイルあり
  • プルリクエストのテンプレートなし
  • コントリビューションガイドなし

はじめの一歩

  1. issue を最後まで読み、次にプロジェクトのコントリビューションガイドを読みます。
  2. 着手することを issue にコメントします — 二人が同じ作業をするのを防げます。
  3. リポジトリをフォークし、ブランチを切って変更します。
  4. issue 番号を参照したプルリクエストを送ります。

tinystream-dev/tinystream のほかの issue

tinystream-dev/tinystream の issue をすべて見る

似ている issue

TypeScript の issue をもっと見る

新しい issue をメールで受け取る

初心者向けの GitHub issue を短くまとめたダイジェスト。