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.
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)
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>
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
There was no way to keep music on a device for offline listening.
What this adds
~estimate when re-encoded). "Remember my choice" skips the prompt; settings can reset it.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/optionsreturns available qualities, sizes, and album IDs. Newlibrary.getSongSourcesbatch query.expo-file-systemin the documents folder, per server.public/downloads-sw.js) serves them only when the network request fails. Mobile saves them as files and shows them as the image placeholder.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
64e2847179to6ce30fe17c