Patchwork

Album cover collage generator based on Last.fm and ListenBrainz listening history.

A full TypeScript rewrite of an original PHP version, with significant improvements in performance and features.

Tech stack

The project runs in SSR mode with Astro and the Node.js adapter (or Vercel). Album covers are fetched from the Last.fm and ListenBrainz APIs, then assembled into a single JPEG image by Sharp, a native image processing library built on libvips — very fast and memory-efficient.

A filesystem cache avoids regenerating already-produced images. TTL is dynamic based on the requested period: 6h for the last 7 days, up to 7 days for overall history.

The project ships with a Dockerfile and docker-compose.yml for self-hosted deployment, as well as a one-click Vercel deploy button.

Features

• Support for Last.fm and ListenBrainz
• Configurable grids from 1×1 to 10×10
• Adjustable image size (50–300px)
• Optional borders between covers
• Filesystem cache with dynamic TTL per period
• Response headers: X-Cache, X-Generation-Time, X-Image-Width/Height
• Optional self-hosted Matomo analytics

API

The image is generated via a simple HTTP request:

GET /patchwork.jpg?username=USER&provider=lastfm&period=overall&rows=3&cols=3&size=150