Skip to content

Offline-first lyrics, cover art, and canvas for downloaded songs - #2778

Open
loucass wants to merge 12 commits into
maxrave-dev:devfrom
loucass:fix/offline-first-media
Open

loucass wants to merge 12 commits into
maxrave-dev:devfrom
loucass:fix/offline-first-media

Conversation

@loucass

@loucass loucass commented Oct 30, 2026 •

Copy link
Copy Markdown

Offline-first lyrics, cover art, and canvas

Summary

Downloaded songs now behave offline-first: saved lyrics appear immediately, downloaded songs
keep their cover art on disk instead of relying on Coil's 24-hour cache, and their Apple Music
animated artwork or Spotify canvas is pinned alongside the download.

Lyrics

  • Render lyrics already saved on the device as soon as a track starts, using
    LyricsProvider.OFFLINE.
  • Refresh from the selected provider in the same coroutine and replace the saved copy when it
    returns.
  • Restore saved AI translations the same way.
  • Do not write the saved-first copy back to the database and do not upload it to the community
    lyrics database (saveToDatabase gate).
  • Provider fallback chains are untouched, so a failed fetch still ends at the saved lyrics.

Cover art

  • Add ArtworkStore (common) with an Android implementation and a Desktop no-op.
  • Pin downloaded covers under filesDir/artwork; filenames are {videoId}.jpg for
    i.ytimg.com/vi/... and {sha256(canonicalUrl)}.jpg otherwise (the =wNNN-hNNN size segment
    is stripped).
  • Add LocalArtworkInterceptor, registered before NetworkFirstInterceptor, so Coil resolves a
    pinned file only when one exists.
  • Save covers when a download enters PREPARING/DOWNLOADING; backfill existing downloads from
    MainActivity.onStart.
  • Remove pinned covers when a download is removed or the downloaded cache is cleared; keep shared
    album art when another download still uses it.
  • Non-downloaded songs keep the existing 24-hour image cache.
  • The now-playing widget uses the singleton image loader so it can resolve pinned covers.

Canvas and animated artwork

  • Add CanvasStore (common) with an Android implementation and a Desktop no-op.
  • Pin a downloaded song's canvas under filesDir/canvas/<videoId>/:
    • Apple Music animated artwork is a VOD HLS stream. Download the playlist and every segment,
      initialisation segment, and key it references, rewrite the playlist to relative local
      filenames, and play the local playlist offline.
    • Spotify canvas is an MP4 or a still image; download it together with its thumbnail.
  • Pin when a download enters PREPARING/DOWNLOADING, and on the first successful online
    canvas resolution for a song that is already downloaded. Existing downloads are not
    backfilled in bulk: they get their canvas the next time they are played online or downloaded
    again.
  • Show the pinned canvas before asking any source, but only while the matching global setting
    (Apple Music animated artwork or Spotify canvas) is still on.
  • Delete the pinned canvas when its download is removed, sweep orphans when the app comes to the
    foreground, and clear all of them with "Clear downloaded cache". "Clear canvas cache" leaves
    pinned canvases alone.
  • Backup and restore include the canvas/ folder.

Testing

  • ./gradlew :composeApp:jvmTest — adds ArtworkFilesTest (4 tests) and
    CanvasPlaylistTest (6 tests: relative segments, shared byte-range files, AES keys, absolute
    URLs, master rejection, CRLF preservation).
  • ./gradlew :androidApp:assembleDebug
  • CI: https://github.com/loucass/SimpMusic/actions/runs/43650971641 — green; :composeApp:jvmTest
    77 tests / 0 failures, arm64-v8a debug APK built.

Notes

  • Artwork and canvas pinning are Android-only; Desktop binds NoOpArtworkStore and
    NoOpCanvasStore.
  • Pinned images are re-encoded as JPEG 90.
  • If the app is killed mid-save, the next foreground backfill retries.
  • A master HLS playlist is not pinned: the repository already resolves the rendition ladder, and
    the store refuses a master rather than choosing one.
  • The pinned canvas is a local file in app-private storage, so clearing the online canvas cache
    does not remove it.
  • No Android instrumentation tests were added.

Linked issue

Closes #2777
Closes #2602
Closes #2829

Checklist

  • This PR addresses an accepted issue (linked above)
  • I wrote or personally reviewed every line of this change
  • I tested it on Android and/or Desktop (say which, and how)

Android: arm64-v8a debug APK built from this branch in CI (run 43650971641), JVM suite green.
Manual offline pass on the debug APK (lyrics, cover art, Apple Music animated artwork, Spotify
canvas, video mode, download removal, backup/restore) is still to be run.

@loucass loucass changed the title Offline-first lyrics and cover art for downloaded songs Offline-first lyrics, cover art, and canvas for downloaded songs Nov 14, 2026
@loucass loucass closed this Nov 14, 2026
@loucass loucass reopened this Nov 14, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

1 participant