feat: keep album and playlist covers with downloads

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
joshuafhigginsandClaude Opus 5.5 committed 2026-11-19 18:28:27 -05:00 Verified
1 parent 13b5bd7874
commit 6ce30fe17c
13 files changed
+254 -25

No files matched your search

@@ -98,7 +98,7 @@ export default function DownloadsScreen() {
? ""
: collection.kind === "album"
? albumCoverUrl(config.serverUrl, collection.id)
: playlistCoverUrl(config.serverUrl, collection.id)
: playlistCoverUrl(config.serverUrl, collection.id, null)
return (
<Pressable
accessibilityRole="button"
+9
View File
@@ -11,6 +11,7 @@ import {
} from "react-native"
import { prefetchCoverPalette } from "@/hooks/use-cover-palette"
import { downloadedCoverUri } from "@/lib/downloads"
import { useThemeColors } from "@/lib/theme"
import {
@@ -83,6 +84,12 @@ export const CoverImage = memo(function CoverImage({
[flatStyle, hasCover, uri]
)
const source = useMemo(() => ({ uri: sourceUri }), [sourceUri])
// A downloaded cover shows while the network copy loads, and offline.
const savedUri = hasCover ? downloadedCoverUri(uri) : null
const placeholder = useMemo(
() => (savedUri ? { uri: savedUri } : undefined),
[savedUri]
)
if (!hasCover) {
return (
@@ -109,6 +116,8 @@ export const CoverImage = memo(function CoverImage({
source={source}
style={[style, { backgroundColor: colors.coverPlaceholder }]}
contentFit={contentFit}
placeholder={placeholder}
placeholderContentFit={contentFit}
transition={150}
blurRadius={blurRadius}
onLoad={
+2 -1
View File
@@ -45,6 +45,7 @@ import type {
DownloadQueue,
SongDownloadState,
} from "@otunes/convex/client/download-queue"
import { FAVORITES_ID } from "@otunes/convex/client/download-queue"
import {
DOWNLOAD_OPTIONS_PATH,
DOWNLOAD_QUALITY_DETAILS,
@@ -67,7 +68,7 @@ export type DownloadTarget =
| (CollectionRef & { title: string; songIds: string[] })
/** The Favorites playlist has no ID, so downloads use this one. */
export const FAVORITES_DOWNLOAD_ID = "favorites"
export const FAVORITES_DOWNLOAD_ID = FAVORITES_ID
type DownloadsContextValue = {
queue: DownloadQueue | null
+78 -13
View File
@@ -4,6 +4,7 @@ import { Platform } from "react-native"
import {
createDownloadQueue,
type DownloadedCover,
type DownloadedSong,
type DownloadIndex,
type DownloadQueue,
@@ -20,25 +21,52 @@ import type { ServerConfig } from "@/lib/server-config"
const REMEMBERED_QUALITY_KEY = "otunes.download-quality"
const PARTIAL_SUFFIX = ".partial"
// Each song is a folder named `<songId>.<quality>` holding one audio file,
// named by the server so it keeps the right extension. Folders end in
// `.partial` until their download completes.
const COVERS_FOLDER = "covers"
const COVER_SIZE = 1024
// Each song is a folder named `<songId>.<quality>.<albumId>` holding one audio
// file, named by the server so it keeps the right extension. Folders end in
// `.partial` until their download completes. Covers are files named
// `<kind>-<id>` in the `covers` folder.
function serverDirectory(config: ServerConfig) {
const host = config.hostname.replace(/[^a-z0-9.-]/gi, "_")
return new Directory(Paths.document, "downloads", host)
}
function songFolderName(song: {
songId: string
quality: DownloadQuality
albumId?: string
}) {
return [song.songId, song.quality, song.albumId].filter(Boolean).join(".")
}
function parseSongFolder(name: string) {
const dot = name.lastIndexOf(".")
const quality = parseDownloadQuality(name.slice(dot + 1))
return quality ? { songId: name.slice(0, dot), quality } : null
const [songId, rawQuality, albumId, ...rest] = name.split(".")
const quality = parseDownloadQuality(rawQuality)
if (!songId || !quality || rest.length > 0) return null
return { songId, quality, albumId: albumId || undefined }
}
function songFolders(root: Directory) {
if (!root.exists) return []
return root
.list()
.filter((entry): entry is Directory => entry instanceof Directory)
.filter(
(entry): entry is Directory =>
entry instanceof Directory && entry.name !== COVERS_FOLDER
)
}
function coverFileName({ kind, id }: DownloadedCover) {
return `${kind}-${id}`
}
// Saved covers by their server URL, for `downloadedCoverUri`.
const savedCoverUris = new Map<string, string>()
function coverUrl(config: ServerConfig, { kind, id }: DownloadedCover) {
return `${config.serverUrl}/api/${kind}/${id}/cover`
}
function audioFile(folder: Directory) {
@@ -48,6 +76,19 @@ function audioFile(folder: Directory) {
function createStorage(config: ServerConfig): DownloadStorage {
const root = serverDirectory(config)
const indexFile = new File(root, "index.json")
const coversFolder = new Directory(root, COVERS_FOLDER)
// Remembers the covers saved in earlier launches.
if (coversFolder.exists) {
for (const entry of coversFolder.list()) {
const dash = entry.name.indexOf("-")
const kind = entry.name.slice(0, dash)
if (entry instanceof File && (kind === "album" || kind === "playlist")) {
const cover = { kind, id: entry.name.slice(dash + 1) } as const
savedCoverUris.set(coverUrl(config, cover), entry.uri)
}
}
}
function foldersFor(songIds: ReadonlySet<string>) {
return songFolders(root).filter((folder) => {
@@ -72,7 +113,7 @@ function createStorage(config: ServerConfig): DownloadStorage {
}
return songs
},
async save({ songId, requested, quality }, signal) {
async save({ songId, requested, quality, albumId }, signal) {
const cookieHeader = await getAuthCookieHeader(
config.serverUrl,
config.convexUrl
@@ -80,7 +121,7 @@ function createStorage(config: ServerConfig): DownloadStorage {
if (!cookieHeader) throw new Error("Sign in to download")
root.create({ intermediates: true, idempotent: true })
const name = `${songId}.${quality}`
const name = songFolderName({ songId, quality, albumId })
const partial = new Directory(root, `${name}${PARTIAL_SUFFIX}`)
if (partial.exists) partial.delete()
partial.create()
@@ -101,6 +142,25 @@ function createStorage(config: ServerConfig): DownloadStorage {
throw error
}
},
async saveCover(cover) {
const file = new File(coversFolder, coverFileName(cover))
if (file.exists) return
coversFolder.create({ intermediates: true, idempotent: true })
const url = coverUrl(config, cover)
await File.downloadFileAsync(`${url}?size=${COVER_SIZE}`, file)
savedCoverUris.set(url, file.uri)
},
async pruneCovers(keep) {
if (!coversFolder.exists) return
const kept = new Set(keep.map(coverFileName))
for (const entry of coversFolder.list()) {
if (kept.has(entry.name)) continue
entry.delete()
for (const [url, uri] of savedCoverUris) {
if (uri === entry.uri) savedCoverUris.delete(url)
}
}
},
async readIndex() {
if (indexFile.exists) {
try {
@@ -138,13 +198,18 @@ export function downloadQueueFor(config: ServerConfig) {
export function downloadedAudioUri(config: ServerConfig, songId: string) {
const song = downloadQueueFor(config).getDownloaded(songId)
if (!song) return null
const folder = new Directory(
serverDirectory(config),
`${songId}.${song.quality}`
)
const folder = new Directory(serverDirectory(config), songFolderName(song))
return folder.exists ? (audioFile(folder)?.uri ?? null) : null
}
/**
* The saved copy of a cover URL (`albumCoverUrl` or `playlistCoverUrl`,
* without size), for showing while the network copy loads or fails.
*/
export function downloadedCoverUri(url: string) {
return savedCoverUris.get(url.split("?")[0]) ?? null
}
export async function readRememberedDownloadQuality() {
try {
return parseDownloadQuality(
@@ -88,6 +88,7 @@ export async function POST(request: NextRequest) {
const response: DownloadOptionsResponse = {
songs: songs.map((song) => ({
id: song._id,
albumId: song.album,
files: Object.fromEntries(
Object.keys(song.files).map((codec) => [codec, true as const])
),
+4 -1
View File
@@ -21,6 +21,7 @@ import { useDownloadsVersion } from "@/hooks/use-downloads"
import {
downloadQueue,
readRememberedDownloadQuality,
registerDownloadsServiceWorker,
requestPersistentStorage,
writeRememberedDownloadQuality,
} from "@/lib/downloads"
@@ -31,6 +32,7 @@ import type {
DownloadableSong,
DownloadSource,
} from "@otunes/convex/client/download-queue"
import { FAVORITES_ID } from "@otunes/convex/client/download-queue"
import {
DOWNLOAD_OPTIONS_PATH,
DOWNLOAD_QUALITY_DETAILS,
@@ -53,7 +55,7 @@ export type DownloadTarget =
| (CollectionRef & { title: string; songIds: string[] })
/** The Favorites playlist has no ID, so downloads use this one. */
export const FAVORITES_DOWNLOAD_ID = "favorites"
export const FAVORITES_DOWNLOAD_ID = FAVORITES_ID
type DownloadsContextValue = {
/** Asks for a quality (unless remembered) and starts downloading. */
@@ -285,6 +287,7 @@ export function DownloadsProvider({ children }: { children: React.ReactNode }) {
useFailureToasts()
React.useEffect(() => {
void downloadQueue.load().catch(() => {})
registerDownloadsServiceWorker()
}, [])
const requestDownload = React.useCallback(async (target: DownloadTarget) => {
+1 -1
View File
@@ -41,7 +41,7 @@ function CollectionCover({ collection }: { collection: DownloadedCollection }) {
src={
collection.kind === "album"
? albumCoverUrl(collection.id)
: playlistCoverUrl(collection.id)
: playlistCoverUrl(collection.id, null)
}
alt={collection.title}
fill
+35 -2
View File
@@ -1,5 +1,6 @@
import {
createDownloadQueue,
type DownloadedCover,
type DownloadedSong,
type DownloadIndex,
type DownloadStorage,
@@ -18,6 +19,23 @@ const SONG_STORE = "songs"
const REMEMBERED_QUALITY_KEY = "otunes:download-quality"
const INDEX_KEY = "otunes:download-index"
// Covers live in Cache Storage under their unsized path. The service worker
// (public/downloads-sw.js) serves them only when the network fails, so
// online browsing and new playlist artwork are unaffected.
const COVER_CACHE = "otunes-download-covers"
const COVER_SIZE = 512
function coverPath({ kind, id }: DownloadedCover) {
return `/api/${kind}/${id}/cover`
}
/** Lets downloaded covers show offline. */
export function registerDownloadsServiceWorker() {
void navigator.serviceWorker
?.register("/downloads-sw.js", { scope: "/" })
.catch(() => {})
}
let database: Promise<IDBDatabase> | null = null
function openDatabase() {
@@ -65,7 +83,7 @@ const storage: DownloadStorage = {
db.transaction(SONG_STORE).objectStore(SONG_STORE)
)
},
async save({ songId, requested, quality }, signal) {
async save({ songId, requested, quality, albumId }, signal) {
const response = await fetch(songDownloadPath(songId, requested), {
signal,
})
@@ -74,13 +92,28 @@ const storage: DownloadStorage = {
}
const blob = await response.blob()
signal.throwIfAborted()
const entry: DownloadedSong = { songId, quality, bytes: blob.size }
const entry: DownloadedSong = { songId, quality, bytes: blob.size, albumId }
await transaction("readwrite", (audio, songs) => {
audio.put(blob, songId)
songs.put(entry)
})
return blob.size
},
async saveCover(cover) {
const cache = await caches.open(COVER_CACHE)
const key = coverPath(cover)
if (await cache.match(key)) return
const response = await fetch(`${key}?size=${COVER_SIZE}`)
if (!response.ok) throw new Error(`Cover failed with ${response.status}`)
await cache.put(key, response)
},
async pruneCovers(keep) {
const cache = await caches.open(COVER_CACHE)
const kept = new Set(keep.map(coverPath))
for (const request of await cache.keys()) {
if (!kept.has(new URL(request.url).pathname)) await cache.delete(request)
}
},
async readIndex() {
try {
const raw = localStorage.getItem(INDEX_KEY)
+4 -2
View File
@@ -1,6 +1,6 @@
import { convexAuthNextjsToken } from "@convex-dev/auth/nextjs/server"
import { api } from "@otunes/convex/_generated/api"
import type { Id } from "@otunes/convex/_generated/dataModel"
import type { Doc, Id } from "@otunes/convex/_generated/dataModel"
import { fetchQuery } from "convex/nextjs"
import { convexServerOptions } from "@/lib/convex-server"
import type { SongSource } from "@/lib/server-hls"
@@ -25,7 +25,9 @@ export async function getSongSource(id: string): Promise<SongSource> {
const SOURCE_BATCH_SIZE = 200
/** `getSongSource` for many songs, in batches. Missing songs are left out. */
export async function getSongSources(ids: string[]): Promise<SongSource[]> {
export async function getSongSources(
ids: string[]
): Promise<(SongSource & Pick<Doc<"songs">, "album">)[]> {
const token = await convexAuthNextjsToken()
const batches: string[][] = []
for (let start = 0; start < ids.length; start += SOURCE_BATCH_SIZE) {
+42
View File
@@ -0,0 +1,42 @@
// Serves covers of downloaded music when the network fails, so they show
// offline. Everything else, and every request that succeeds online, passes
// through untouched. Covers are saved by lib/downloads.ts.
const COVER_CACHE = "otunes-download-covers"
const COVER_PATH = /^\/api\/(album|playlist)\/[^/]+\/cover$/
self.addEventListener("install", () => self.skipWaiting())
self.addEventListener("activate", (event) =>
event.waitUntil(self.clients.claim())
)
/** The saved cover's key for a cover request, also through `/_next/image`. */
function coverKey(url) {
if (url.origin !== self.location.origin) return null
if (url.pathname === "/_next/image") {
const inner = url.searchParams.get("url")
return inner ? coverKey(new URL(inner, self.location.origin)) : null
}
return COVER_PATH.test(url.pathname) ? url.pathname : null
}
async function savedCover(key) {
const cache = await caches.open(COVER_CACHE)
return cache.match(key)
}
self.addEventListener("fetch", (event) => {
if (event.request.method !== "GET") return
const key = coverKey(new URL(event.request.url))
if (!key) return
event.respondWith(
fetch(event.request).then(
async (response) =>
response.ok ? response : ((await savedCover(key)) ?? response),
async (error) => {
const saved = await savedCover(key)
if (saved) return saved
throw error
}
)
)
})
+65 -2
View File
@@ -9,8 +9,13 @@ export type DownloadedSong = {
/** The quality the file is in, after any fallback to High. */
quality: DownloadQuality
bytes: number
/** Whose cover to keep for offline use. */
albumId?: string
}
/** Artwork kept on the device for downloaded songs and playlists. */
export type DownloadedCover = { kind: "album" | "playlist"; id: string }
/**
* An album or playlist downloaded as a whole. Playlists stay in sync: songs
* added later download in `quality`, and songs taken out are removed.
@@ -61,9 +66,14 @@ export type DownloadStorage = {
songId: string
requested: DownloadQuality
quality: DownloadQuality
albumId?: string
},
signal: AbortSignal
): Promise<number>
/** Fetches and keeps a cover unless it is already kept. */
saveCover(cover: DownloadedCover): Promise<void>
/** Deletes every kept cover not in `keep`. */
pruneCovers(keep: readonly DownloadedCover[]): Promise<void>
remove(songIds: readonly string[]): Promise<void>
readIndex(): Promise<DownloadIndex>
writeIndex(index: DownloadIndex): Promise<void>
@@ -72,6 +82,7 @@ export type DownloadStorage = {
export type DownloadableSong = {
id: string
files: Record<string, unknown>
albumId?: string
}
export type DownloadStatus = {
@@ -100,6 +111,9 @@ export type SongDownloadState = "here" | "device" | "removed" | "none"
export type DownloadQueue = ReturnType<typeof createDownloadQueue>
/** The Favorites playlist has no ID or cover; downloads use this one. */
export const FAVORITES_ID = "favorites"
function collectionKey({ kind, id }: CollectionRef) {
return `${kind}:${id}`
}
@@ -139,6 +153,9 @@ export function createDownloadQueue(
for (const songId of index.otherSongIds) {
if (downloaded.has(songId)) otherSongIds.add(songId)
}
// Retries covers that failed before (say, offline) and drops strays.
for (const cover of neededCovers()) saveCover(cover)
pruneCovers()
notify()
},
(error) => {
@@ -178,13 +195,26 @@ export function createDownloadQueue(
running.set(song.id, controller)
void storage
.save(
{ songId: song.id, requested: quality, quality: actual },
{
songId: song.id,
requested: quality,
quality: actual,
albumId: song.albumId,
},
controller.signal
)
.then(
(bytes) => {
if (controller.signal.aborted) return
downloaded.set(song.id, { songId: song.id, quality: actual, bytes })
downloaded.set(song.id, {
songId: song.id,
quality: actual,
bytes,
albumId: song.albumId,
})
if (song.albumId) {
saveCover({ kind: "album", id: song.albumId })
}
},
(error) => {
if (controller.signal.aborted) return
@@ -211,6 +241,34 @@ export function createDownloadQueue(
}
}
/** Covers are best effort: a missing one falls back to the placeholder. */
function saveCover(cover: DownloadedCover) {
void storage.saveCover(cover).catch(() => {})
}
/** Album covers of downloaded songs, and covers of downloaded playlists. */
function neededCovers() {
const covers = new Map<string, DownloadedCover>()
for (const song of downloaded.values()) {
if (song.albumId) {
covers.set(`album:${song.albumId}`, { kind: "album", id: song.albumId })
}
}
for (const collection of collections.values()) {
if (collection.kind === "playlist" && collection.id !== FAVORITES_ID) {
covers.set(`playlist:${collection.id}`, {
kind: "playlist",
id: collection.id,
})
}
}
return [...covers.values()]
}
function pruneCovers() {
void storage.pruneCovers(neededCovers()).catch(() => {})
}
/** Cancels and deletes audio, leaving the index as it is. */
async function deleteAudio(songIds: readonly string[]) {
if (songIds.length === 0) return
@@ -225,6 +283,7 @@ export function createDownloadQueue(
}
notify()
await storage.remove([...ids])
pruneCovers()
pump()
}
@@ -347,6 +406,9 @@ export function createDownloadQueue(
if (collection.kind === "album") {
for (const song of songs) otherSongIds.delete(song.id)
}
if (collection.kind === "playlist" && collection.id !== FAVORITES_ID) {
saveCover({ kind: "playlist", id: collection.id })
}
collections.set(collectionKey(collection), {
kind: collection.kind,
id: collection.id,
@@ -404,6 +466,7 @@ export function createDownloadQueue(
collections.delete(key)
await saveIndex()
await deleteUnheld(collection.songIds)
pruneCovers()
},
/**
+11 -1
View File
@@ -1008,7 +1008,16 @@ export const getSongSources = query({
}
const songs = await Promise.all(args.ids.map((id) => ctx.db.get(id)))
return songs.flatMap((song) =>
song ? [{ _id: song._id, files: song.files, length: song.length }] : []
song
? [
{
_id: song._id,
files: song.files,
length: song.length,
album: song.album,
},
]
: []
)
},
})
@@ -1053,6 +1062,7 @@ export const getSongsForPlayback = query({
return {
id: ids[index],
title: song.name,
albumId: song.album,
files: playbackCodecMap(song.files),
}
})
+1 -1
View File
@@ -146,7 +146,7 @@ export type SizedDownloadOption = DownloadOption & {
/** Server answer for a set of songs about to be downloaded. */
export type DownloadOptionsResponse = {
songs: { id: string; files: Record<string, true> }[]
songs: { id: string; albumId: string; files: Record<string, true> }[]
options: SizedDownloadOption[]
}