Skip to content
Back to search

stunning-winner

Self-hosted music scrobbler & listening stats API, a Last.fm / ListenBrainz alternative. ListenBrainz-compatible: scrobble from Pano Scrobbler, Navidrome, Jellyfin, Web Scrobbler… Wrapped, streaks, top artists. Serverless on Cloudflare Workers + D1, Hono, Better Auth, OpenAPI. Open source (AGPL).

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 21 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/powpowchuuuu/stunning-winner with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/powpowchuuuu/stunning-winner'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/powpowchuuuu--stunning-winner/badge.svg)](/listings/powpowchuuuu--stunning-winner)

HTML

<a href="/listings/powpowchuuuu--stunning-winner"><img src="/api/listings/powpowchuuuu--stunning-winner/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

You need a Cloudflare account, Node.js 22.18+ and [Vite+](https://viteplus.dev/) (`vp`), which installs the pinned pnpm for you.

git clone https://github.com/powpowchuuuu/stunning-winner.git scrobbler
cd scrobbler
vp install

**1. Create the database and the cache.**

cd apps/api
npx wrangler d1 create scrobbler
npx wrangler kv namespace create CACHE

**2. Store their IDs locally.** Copy `apps/api/.env.cloudflare.example` to `apps/api/.env.cloudflare` and fill in `D1_DATABASE_ID` and `KV_CACHE_ID`. This file is git-ignored: `wrangler.jsonc` keeps placeholder IDs, and the deploy scripts inject the real ones at deploy time, so your account's IDs never end up in the repository.

**3. Set the auth secret, run the migrations and deploy the API.**

openssl rand -base64 32 | npx wrangler secret put BETTER_AUTH_SECRET
vp run db:migrate:remote
vp run deploy

**4. Deploy the web front.** It reaches the API Worker through a service binding, so both share one origin and Better Auth cookies stay first-party.

cd ../web
vp run deploy

**5. Trust the web origin.** Set `TRUSTED_ORIGINS` in `apps/api/wrangler.jsonc` to the URL of your web Worker (for example `https://scrobbler.example.com`), then redeploy the API. Open the web app, create your account, and set `DISABLE_SIGNUP` to `"true"` if the instance is just for you.

Optional API variable: `BASE_URL`, the public URL used by Better Auth (defaults to the request origin).

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 195 lines
  1. # Scrobbler: a self-hosted, open source music scrobbler for Cloudflare Workers
  2. **A ListenBrainz-compatible scrobbler you deploy on your own Cloudflare account.** Track every song you play,
  3. browse your listening history, and get detailed listening stats and a yearly "Wrapped"-style review, without
  4. handing your data to a third party. A free, open source alternative to Last.fm and a self-hostable
  5. ListenBrainz server, built on Cloudflare Workers, D1 and KV with Hono and Better Auth.
  6. ![Profile page with top albums, on repeat, milestones and recent activity](docs/screenshots/profile.png)
  7. ## Why
  8. - **Your data, your account.** Listens live in your own Cloudflare D1 database. Export, query or delete them whenever you like.
  9. - **Works with the apps you already use.** The server speaks the ListenBrainz API, so any scrobbler that can point at a custom ListenBrainz server can send listens to it.
  10. - **Cheap to run.** Two Workers, one D1 database and one KV namespace. A personal instance fits comfortably in Cloudflare's free tier.
  11. - **Open source.** AGPL-3.0, no tracking, no ads.
  12. ## Features
  13. - **ListenBrainz-compatible API** at `/1`: submit listens, now playing, token validation, listen history, listen count, delete a listen, latest import and top artists / recordings / releases.
  14. - **Native JSON API** at `/v1` with an OpenAPI 3 document (`/v1/openapi.json`) and interactive docs (`/v1/docs`).
  15. - **Listening statistics** for any period (this week, this month, this year, last quarter, all time…): top artists, albums and tracks, daily activity, listening clock, streaks, discoveries, forgotten favourites, on repeat, trends, period comparison, one-shots, weekly charts, diversity, listening sessions, repeats, milestones and "on this day".
  16. - **Year in review**, a Spotify Wrapped-style recap of your year: artist of the year, top albums, totals and more.
  17. - **Artist, album and track pages** with first and last listen, play counts and a timeline.
  18. - **Album art** from the Cover Art Archive (by MusicBrainz release ID) with a Deezer fallback by name, cached at the edge.
  19. - **Last.fm import**: upload a Last.fm CSV export from the settings to bring your scrobble history over.
  20. - **Accounts and API tokens** with Better Auth (username + password, per-app API keys that you can revoke).
  21. - **Private profiles**: hide your listens and stats from everyone but yourself.
  22. - **Rate limiting** on the API and auth endpoints, and an optional switch to close sign-ups on a personal instance.
  23. ## Screenshots
  24. The web front is called **Needle**. Its interface is currently in French.
  25. | Listening stats | Top artists |
  26. | ----------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
  27. | ![Listening stats for the month: listens, artists, albums and tracks compared with the previous period](docs/screenshots/stats.png) | ![Top artists for the month with period filters](docs/screenshots/top-artists.png) |
  28. | Year in review | Artist page |
  29. | -------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
  30. | ![Year in review: total listens, artists, tracks, albums and active days](docs/screenshots/year-in-review.png) | ![Artist page with play counts, first listen and a monthly timeline](docs/screenshots/artist.png) |
  31. ## Compatible scrobbling apps
  32. Because the server implements the ListenBrainz API, you connect apps the same way you would connect them to
  33. ListenBrainz: pick **ListenBrainz** (or "custom ListenBrainz server") in the app, then paste your server URL
  34. and an API token. Create the token in the web app under **Réglages → Tokens d'API**; the page shows the server
  35. URL to use next to it.
  36. Apps that let you set a custom ListenBrainz URL include:
  37. | App | Platform |
  38. | --------------------------------------------------------------- | ----------------------------------------------------------------------- |
  39. | [Pano Scrobbler](https://github.com/kawaiiDango/pano-scrobbler) | Android, Windows, Linux |
  40. | [Web Scrobbler](https://web-scrobbler.com/) | Browser extension (YouTube, Spotify Web, Bandcamp, SoundCloud…) |
  41. | [Navidrome](https://www.navidrome.org/) | Self-hosted music server |
  42. | [Jellyfin](https://jellyfin.org/) (ListenBrainz plugin) | Self-hosted media server |
  43. | [Multi-Scrobbler](https://github.com/FoxxMD/multi-scrobbler) | Self-hosted bridge for Spotify, Plex, Jellyfin, Subsonic, MPD, Last.fm… |
  44. Anything else that talks to the ListenBrainz API with a configurable root URL should work too. Some apps
  45. want the root URL (`https://scrobbler.example.com`), others want the API path (`https://scrobbler.example.com/1/`).
  46. ## Quick start: deploy on Cloudflare
  47. You need a Cloudflare account, Node.js 22.18+ and [Vite+](https://viteplus.dev/) (`vp`), which installs the
  48. pinned pnpm for you.
  49. ```bash
  50. git clone https://github.com/powpowchuuuu/stunning-winner.git scrobbler
  51. cd scrobbler
  52. vp install
  53. ```
  54. **1. Create the database and the cache.**
  55. ```bash
  56. cd apps/api
  57. npx wrangler d1 create scrobbler
  58. npx wrangler kv namespace create CACHE
  59. ```
  60. **2. Store their IDs locally.** Copy `apps/api/.env.cloudflare.example` to `apps/api/.env.cloudflare` and fill in
  61. `D1_DATABASE_ID` and `KV_CACHE_ID`. This file is git-ignored: `wrangler.jsonc` keeps placeholder IDs, and the
  62. deploy scripts inject the real ones at deploy time, so your account's IDs never end up in the repository.
  63. **3. Set the auth secret, run the migrations and deploy the API.**
  64. ```bash
  65. openssl rand -base64 32 | npx wrangler secret put BETTER_AUTH_SECRET
  66. vp run db:migrate:remote
  67. vp run deploy
  68. ```
  69. **4. Deploy the web front.** It reaches the API Worker through a service binding, so both share one origin and
  70. Better Auth cookies stay first-party.
  71. ```bash
  72. cd ../web
  73. vp run deploy
  74. ```
  75. **5. Trust the web origin.** Set `TRUSTED_ORIGINS` in `apps/api/wrangler.jsonc` to the URL of your web Worker
  76. (for example `https://scrobbler.example.com`), then redeploy the API. Open the web app, create your account,
  77. and set `DISABLE_SIGNUP` to `"true"` if the instance is just for you.
  78. Optional API variable: `BASE_URL`, the public URL used by Better Auth (defaults to the request origin).
  79. ## Local development
  80. ```bash
  81. cp apps/api/.dev.vars.example apps/api/.dev.vars # set BETTER_AUTH_SECRET
  82. cp apps/web/.dev.vars.example apps/web/.dev.vars
  83. vp run @scrobbler/api#db:migrate:local
  84. cd apps/api && vp run dev # API on http://localhost:8787
  85. cd apps/web && vp run dev # web front on http://localhost:3000
  86. ```
  87. Signing in from the local web front also needs `TRUSTED_ORIGINS=http://localhost:3000` in `apps/api/.dev.vars`.
  88. ```bash
  89. vp check --fix # format, lint, type-check
  90. vp run -r test # all tests
  91. ```
  92. ## API overview
  93. | Path | What it is |
  94. | ------------------ | ------------------------------------------------------------------------ |
  95. | `/1/*` | ListenBrainz API v1. Authenticate with `Authorization: Token <api key>`. |
  96. | `/v1/*` | Native JSON API: listens, now playing, profile, stats and insights. |
  97. | `/v1/openapi.json` | OpenAPI document for `/v1`. |
  98. | `/v1/docs` | Interactive API reference. |
  99. | `/api/auth/*` | Better Auth (sign-up, sign-in, sessions, API keys). |
  100. Submit a listen exactly as you would to ListenBrainz:
  101. ```bash
  102. curl -X POST https://scrobbler.example.com/1/submit-listens \
  103. -H "Authorization: Token $TOKEN" \
  104. -H "Content-Type: application/json" \
  105. -d '{
  106. "listen_type": "single",
  107. "payload": [{
  108. "listened_at": 1763650000,
  109. "track_metadata": { "artist_name": "Nicki Minaj", "track_name": "Super Bass" }
  110. }]
  111. }'
  112. ```
  113. Read stats from the native API:
  114. ```bash
  115. curl https://scrobbler.example.com/v1/users/<username>/stats/summary
  116. curl "https://scrobbler.example.com/v1/users/<username>/stats/artists?range=this_month"
  117. curl https://scrobbler.example.com/v1/users/<username>/stats/wrapped
  118. ```
  119. Errors always look like `{ "code": 404, "error": "…" }` and timestamps are Unix seconds (UTC). See `/v1/docs` on
  120. your instance for every endpoint, parameter and response field.
  121. ## Architecture
  122. ```
  123. apps/
  124. api/ Hono Worker: /1 (ListenBrainz), /v1 (native API + OpenAPI), /api/auth (Better Auth)
  125. web/ TanStack Start front (Panda CSS, Zag.js) on its own Worker, relays API paths via a service binding
  126. packages/
  127. types/ Wire and domain types
  128. core/ Business rules behind ports: no I/O, no Cloudflare
  129. db-d1/ Cloudflare D1 repositories and SQL migrations
  130. cache-kv/ Workers KV cache
  131. auth/ Better Auth setup (username + API key plugins)
  132. testing/ Node-only test doubles (D1 on node:sqlite, KV in memory)
  133. ```
  134. - **Ports and adapters.** The core knows nothing about Cloudflare. Storage, cache and auth are adapters, so another database (Postgres, SQLite, Turso…) is a new `packages/db-<name>` that passes the same tests.
  135. - **Protocols are thin.** ListenBrainz and the native API only map their wire format onto the same core services, so a Last.fm-compatible endpoint would be one more folder.
  136. - **Built for D1's limits.** Batch inserts use a single `json_each` statement, every listen read is bounded by an index, and stats are cached in KV keyed by the listen count, so new listens invalidate them naturally.
  137. More detail for contributors is in [AGENTS.md](AGENTS.md).
  138. ## Tech stack
  139. [Cloudflare Workers](https://workers.cloudflare.com/) · [D1](https://developers.cloudflare.com/d1/) ·
  140. [Workers KV](https://developers.cloudflare.com/kv/) · [Hono](https://hono.dev/) ·
  141. [Better Auth](https://www.better-auth.com/) · [TanStack Start](https://tanstack.com/start) ·
  142. [Panda CSS](https://panda-css.com/) · [Zag.js](https://zagjs.com/) · [Vite+](https://viteplus.dev/) · TypeScript
  143. ## Contributing
  144. Issues and pull requests are welcome. Run `vp check --fix` and `vp run -r test` before opening a PR, and read
  145. [AGENTS.md](AGENTS.md) for the dependency rules the codebase keeps.
  146. ## License
  147. [AGPL-3.0](LICENSE). If you run a modified version as a public service, you must share your changes.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.