Space Station Worker
The hub of Space Station: a Cloudflare Worker and D1 catalog in front of a music library mirrored to Google Drive, streaming the audio through the Worker.
What it does
- Holds the catalog (artists, albums, genres, tracks and the links between them) in D1 and serves it as one compact download, with a cheap version fingerprint so clients know when to refresh.
- Streams audio from Drive with range requests, and serves album art from Drive through an R2 cache.
- Radio and AutoDJ endpoints with an artist-repeat cooldown. AutoDJ drifts between neighbouring genres with a weighted random walk over a hand-curated adjacency graph.
- Likes, a global play history and a wishlist of tracks liked on radio that are not in the library, all shared across clients.
- Keeps D1 in step with Drive on a 15-minute cron using Drive's changes feed. A quiet run is one API call.
- A live radio station list (Death.FM and SomaFM channels) with a shared per-stream scrobble switch.
- A browser player served as static assets: artists, genres, stations and likes, fuzzy search, a crossfading queue, keyboard shortcuts, lock-screen media controls and history-aware navigation with no build step.
Under the hood
- JavaScript on Workers with D1 for the catalog, R2 for art, and the Drive API through
googleapis. A seed script reads tags from the local files withmusic-metadataand matches them to Drive file ids. - Sync reads only part of each new file: the ID3v2 head and any trailing APEv2 or ID3v1 tag, a few small range requests per track. A queue and a bounded batch per run keep each invocation small, and a file that fails five times is dropped.
- Authentication lives in the Worker. Machine clients send a fixed header pair, and a browser goes through a Google login that is checked against a single allowed account and kept as a signed session cookie.
- A Chromecast cannot log in or add headers to a media request, so the receiver uses separate routes gated by a shared secret. The receiver is a real API client: it extends its own queue, signs its own Last.fm calls and records its own history.
- Split releases such as "A; B" are listed under each artist, and the fuzzy search is implemented twice (web and Android) with the same test cases.
- The Worker also tells clients where the home LAN server is, so they can prefer it. Tests run on Node's runner against real migrations on SQLite, with a scripted fake Drive, plus a headless-Chrome smoke test of the web player.
The Drive layout, hostnames and credentials are not described here.