feat: download music for offline playback on web and mobile #116

Merged
joshuafhiggins merged 3 commits from t3/music-download-quality into main 2026-11-19 18:31:37 -05:00
Owner

There was no way to keep music on a device for offline listening.

What this adds

  • Quality prompt when downloading a song, selection, album, or playlist: Medium, High, Lossless, or Dolby Atmos. Lossless and Atmos only appear if at least one song has them, and each option shows how many songs fall back to High and the download size (exact for files sent as-is, ~ estimate when re-encoded). "Remember my choice" skips the prompt; settings can reset it.
  • Fallbacks: songs missing Lossless or Atmos download in High. Medium is always transcoded (128 kbps AAC) from Lossless or High. High without a High file is transcoded from Lossless at 256 kbps.
  • Server: GET /api/song/[id]/download?quality= sends one whole file (transcodes go to a seekable .m4a; ALAC becomes FLAC for clients that can't play it). POST /api/download/options returns available qualities, sizes, and album IDs. New library.getSongSources batch query.
  • Web storage: IndexedDB, matching how YouTube's web player stores offline media. Persistent storage is requested on first download.
  • Mobile storage: expo-file-system in the documents folder, per server.
  • Covers: album covers of downloaded songs and covers of downloaded playlists are kept, and dropped once nothing needs them. Web keeps them in Cache Storage and a small service worker (public/downloads-sw.js) serves them only when the network request fails. Mobile saves them as files and shows them as the image placeholder.
  • Playback: in regular queues, a download stands in for the stream only when it's in the quality you'd stream. Queues started from the Downloads page play downloads in any quality. A download finishing or being removed mid-song doesn't interrupt playback.
  • Downloads page under Library (web sidebar, mobile Library list, iPad tab): a grid of downloaded albums and playlists with sizes, plus Other Downloaded Songs, a built-in list of songs downloaded on their own. Album and playlist pages show the downloaded quality.
  • Other Downloaded Songs: a song downloaded on its own joins it; downloading its album takes it out; a playlist holding it leaves it in. Outside a downloaded album or playlist, Download and Remove act on this list.
  • Per-download removal: removing a song from one album or playlist download only takes it out of that download, and the file stays while any other download holds it. Playlist sync doesn't bring removed songs back.
  • Playlist sync: downloaded playlists (including Favorites) download newly added songs in their chosen quality.
  • UI: download button with static progress ring on album/playlist/Favorites headers, Download / Remove Download in menus, mobile swipe to download (a red trash with a confirmation once downloaded), a downloaded mark on track rows, and a Downloads settings section that breaks storage down by quality and by album/playlist.

The download queue is shared in packages/convex/client/download-queue.ts, and each platform supplies only its storage.

Testing

Typecheck passes in web and mobile, and web lint is clean apart from an existing warning. The queue's ownership and cover rules were checked with a throwaway script (20 scenarios). Not yet exercised against a running server or device.


Changes made by Claude Opus 5.5 (claude-opus-5-5) running in Claude Code via T3 Code.

🤖 Generated with Claude Code

There was no way to keep music on a device for offline listening. ## What this adds - **Quality prompt** when downloading a song, selection, album, or playlist: Medium, High, Lossless, or Dolby Atmos. Lossless and Atmos only appear if at least one song has them, and each option shows how many songs fall back to High and the download size (exact for files sent as-is, `~` estimate when re-encoded). "Remember my choice" skips the prompt; settings can reset it. - **Fallbacks:** songs missing Lossless or Atmos download in High. Medium is always transcoded (128 kbps AAC) from Lossless or High. High without a High file is transcoded from Lossless at 256 kbps. - **Server:** `GET /api/song/[id]/download?quality=` sends one whole file (transcodes go to a seekable `.m4a`; ALAC becomes FLAC for clients that can't play it). `POST /api/download/options` returns available qualities, sizes, and album IDs. New `library.getSongSources` batch query. - **Web storage:** IndexedDB, matching how YouTube's web player stores offline media. Persistent storage is requested on first download. - **Mobile storage:** `expo-file-system` in the documents folder, per server. - **Covers:** album covers of downloaded songs and covers of downloaded playlists are kept, and dropped once nothing needs them. Web keeps them in Cache Storage and a small service worker (`public/downloads-sw.js`) serves them only when the network request fails. Mobile saves them as files and shows them as the image placeholder. - **Playback:** in regular queues, a download stands in for the stream only when it's in the quality you'd stream. Queues started from the Downloads page play downloads in any quality. A download finishing or being removed mid-song doesn't interrupt playback. - **Downloads page** under Library (web sidebar, mobile Library list, iPad tab): a grid of downloaded albums and playlists with sizes, plus **Other Downloaded Songs**, a built-in list of songs downloaded on their own. Album and playlist pages show the downloaded quality. - **Other Downloaded Songs:** a song downloaded on its own joins it; downloading its album takes it out; a playlist holding it leaves it in. Outside a downloaded album or playlist, Download and Remove act on this list. - **Per-download removal:** removing a song from one album or playlist download only takes it out of that download, and the file stays while any other download holds it. Playlist sync doesn't bring removed songs back. - **Playlist sync:** downloaded playlists (including Favorites) download newly added songs in their chosen quality. - **UI:** download button with static progress ring on album/playlist/Favorites headers, Download / Remove Download in menus, mobile swipe to download (a red trash with a confirmation once downloaded), a downloaded mark on track rows, and a Downloads settings section that breaks storage down by quality and by album/playlist. The download queue is shared in `packages/convex/client/download-queue.ts`, and each platform supplies only its storage. ## Testing Typecheck passes in web and mobile, and web lint is clean apart from an existing warning. The queue's ownership and cover rules were checked with a throwaway script (20 scenarios). Not yet exercised against a running server or device. --- Changes made by Claude Opus 5.5 (`claude-opus-5-5`) running in Claude Code via T3 Code. 🤖 Generated with [Claude Code](https://claude.com/claude-code)
joshuafhiggins added 3 commits 2026-11-19 18:28:28 -05:00
Users pick Medium, High, Lossless, or Dolby Atmos per download (with
optional "Remember my choice"). Songs without the picked format fall back
to High, and Medium is always transcoded. Web stores audio in IndexedDB
like YouTube Music; mobile stores files per server via expo-file-system.
Downloaded playlists stay in sync, and settings break down storage by
quality and by album or playlist.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
joshuafhiggins force-pushed t3/music-download-quality from 64e2847179 to 6ce30fe17c 2026-11-19 18:28:28 -05:00 Compare
joshuafhiggins merged commit 2ae87200f0 into main 2026-11-19 18:31:37 -05:00
Sign in to join this conversation.
No Reviewers
No labels
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: joshuafhiggins/otunes#116