Images

Overview

Rewind has a unified image pipeline that handles artwork for all domains. Images are fetched from source APIs, stored in Cloudflare R2, and served through Cloudflare Images for on-the-fly transforms.

CDN URLs

All image responses include an image object:

{
  "image": {
    "url": "https://cdn.rewind.rest/cdn-cgi/image/width=300,height=300,fit=cover,format=auto,quality=85/listening/albums/1566/original.jpg?v=1",
    "thumbhash": "NwgKBwDIl4d2h3h/hrZ4d2h0d4QHQ2oA",
    "dominant_color": "#d8d8d8",
    "accent_color": "#d8d8d8"
  }
}

Image transforms

Sized images use Cloudflare’s /cdn-cgi/image/<options>/<R2 key> path. Transform options are comma-separated in the path; the v query parameter is only a cache buster.

https://cdn.rewind.rest/cdn-cgi/image/width={w},height={h},fit=cover,format=auto,quality=85/{r2_key}?v={image_version}

The transform options are:

Parameter	Values	Description
`width`	pixels	Target width
`height`	pixels	Target height
`fit`	`cover`, `contain`, `scale-down`	Resize behavior
`format`	`auto`, `webp`, `avif`, `jpeg`	Output format (`auto` picks best for client)
`quality`	1-100	Compression quality

Original images omit the transform path:

https://cdn.rewind.rest/{r2_key}?v={image_version}

ThumbHash

Every image includes a thumbhash, a compact placeholder (20-30 bytes, base64-encoded) that can be decoded client-side into a blurry preview image. This enables instant placeholder rendering before the full image loads. See thumbhash.io for decoder libraries.

Color extraction

Each image has two extracted colors:

dominant_color: the most common color in the image (hex).
accent_color: a secondary color that contrasts with the dominant color (hex).

These are useful for dynamic UI theming (e.g., tinting a background based on album art).

Image sources by domain

Domain	Primary source	Fallbacks
Listening (albums)	Apple Music	Deezer, iTunes
Listening (artists)	Apple Music	Deezer, Fanart.tv
Running	Strava map tiles	None
Watching (movies)	TMDB	Fanart.tv, Plex
Watching (shows)	TMDB	Fanart.tv, Plex
Collecting (vinyl)	Discogs	None
Collecting (media)	TMDB	None

CD artwork

Listening can also return accepted disc artwork separately from square album covers. The artwork service exposes GET /v1/listening/cd-artwork/albums/{id} with a read key. A missing accepted asset returns artwork: null; clients should keep their existing cover fallback. The accepted PNG is the canonical asset. When available, the variants array supplies an optional smaller, lossless WebP verified against that PNG. Use the advertised URL and retain the PNG fallback. Disc assets preserve transparency and use their own hash-addressed URLs rather than the square-cover transform path. The CD artwork album lookup may also return an optional fallback_artwork descriptor for a generic disc when album artwork is unavailable. Its image URLs refer to reviewed PNG or WebP assets served by Rewind; descriptor access follows the authenticated album lookup. Discman includes albums once approved disc artwork and playable preview audio are available. A normal album cover or Apple Music link alone does not complete that preparation. Artwork admin jobs report bounded provider error details and the next retry time. Known rate-limit rejections retry with backoff; rejected or uncertain generation remains held for diagnosis rather than appearing queued indefinitely. Active accepted artwork reports ready after automatic or manual activation. Bounded reconciliation also repairs historical successful statuses; failed upgrade jobs retain their own diagnostics while existing accepted art stays available. Hidden or review-held artwork is not declared ready. Album identity checks account for supported edition labels and artist-credit typography. Release dates can differ between promotions, territories and reissues; a date disagreement alone does not reject a verified album. Multiple catalog editions require tracklist evidence before a representative cover is selected. An uncertain physical pressing does not prevent a separately verified cover-based design. Distinct albums, recording variants and conflicting identities remain held. Discman uses catalog previews for the selected release. A played-song fallback is used only when its Apple Music URL identifies that same catalog album; an unrelated release’s preview is withheld.

Getting Started

Domains

Help