Raycast extension: teal.fm scrobbler from spotify (api or desktop app)
README.md

Teal Scrobbler for Raycast #

Scrobbles what you play on Spotify to teal.fm. Plays are written as fm.teal.feed.play records in your own ATProto repo, and while music is playing your teal.fm "now playing" status (fm.teal.actor.status) is kept up to date.

Commands #

Command What it does
Teal Scrobbler Setup and status: sign in to teal.fm, connect Spotify, see the current track, the upload queue and recent scrobbles.
Scrobble Spotify Background command. Polls the player every 20 s and scrobbles finished plays. Run it once by hand to turn it on. Raycast lists it under Settings → Extensions.

Setup #

1. teal.fm (pick one) #

OAuth (recommended): open Teal Scrobbler → teal.fm → Sign in with OAuth, enter your handle and approve in the browser. The extension only asks to create teal.fm plays and update your teal.fm status. It never gets general access to your account.

  • It works as an ATProto loopback client: the PDS redirects to http://127.0.0.1:52741/callback, where the extension listens briefly. No server or hosted client metadata is involved.
  • Limit: Bluesky's PDS caps sessions for clients without a backend at 2 weeks. After that, the extension shows "Sign in again" and keeps finished plays in its queue until you do.
  • If Raycast closes the form before the browser comes back, the browser shows "can't connect to 127.0.0.1". Copy that URL and use Finish Sign-In from Pasted URL.

App password: in Bluesky, create one under Settings → Privacy and Security → App Passwords. Put your handle and the app password in the extension preferences. App passwords don't expire, but they give full account access apart from DMs and account settings. OAuth takes precedence when both are set.

2. Spotify (pick a source in preferences) #

  • Desktop app: needs no setup. Reads the Spotify app on this Mac through AppleScript. macOS asks once to let Raycast control Spotify. Only sees playback on this Mac and reports a single artist string.

  • Web API (OAuth with PKCE, no secret): sees playback on every device (phone, speakers, web player) and gets all artists plus the ISRC.

    1. Create an app at https://developer.spotify.com/dashboard (Web API).
    2. Add the redirect URI https://raycast.com/redirect?packageName=Extension.
    3. Paste the app's Client ID into the extension preferences.
    4. Teal Scrobbler → Spotify → Connect Spotify Web API.

    Spotify apps in development mode only work for accounts you add under the app's User Management, so add yourself.

  • Auto (default): Web API when connected, otherwise the desktop app.

When does a play count? #

The teal.fm rule: a track under 2 minutes counts once it has been played in full. A longer track counts after half its length, capped at 4 minutes. Only real listening counts: seeking forward doesn't, pauses don't, and replaying a track counts again. Plays that fail to upload (offline, or teal.fm not signed in) wait in a queue and are retried on each run.

Development #

npm install
npm run dev     # loads the extension into Raycast
npm run lint

License #

MIT