Spotify Controller for StreamDock

Full Spotify playback control on your Mirabox / Fifine StreamDock deck — live album art, a progress bar, like/unlike, shuffle & repeat, volume, seek, and device switching. Every key is rendered as album-art-aware artwork, and controls respond the instant you press.

Not affiliated with, endorsed by, or sponsored by Spotify AB. "Spotify" and the Spotify logo are trademarks of Spotify AB. This is an independent, community project that talks to the public Spotify Web API.

Features

• Play / Pause key with full-bleed album art, a progress bar, and scrolling title
• Now Playing display (art + track + artist)
• Like / Unlike the current track
• Shuffle and Repeat (off → all → one) with clear on-state
• Volume up / down (configurable step) + an arc Volume gauge
• Seek forward / back (configurable step)
• Switch Device — cycle through your available Spotify Connect devices
• Album-art tiles — place four tiles in a 2×2 square for one big cover
• Instant press feedback, optimistic UI, and showAlert when a command is rejected
• Resilient auth (PKCE + rotating refresh token), auto-reconnect, stale/rate-limit indicators

Requirements

• Windows 10+ and the StreamDock software (v5.0+)
• Node.js 18+ installed and on your PATH (the plugin runs node app.js)
• A Spotify Premium account (the Web API only allows playback control for Premium)

Install

From a release (recommended)

1. Download the latest com.spotify.controller.sdPlugin.zip from Releases.
2. Unzip it into %APPDATA%\HotSpot\StreamDock\plugins\ so you have ...\plugins\com.spotify.controller.sdPlugin\.
3. Restart StreamDock and drag any Spotify action onto a key.

From source

git clone https://github.com/<you>/spotify-controller-streamdock.git com.spotify.controller.sdPlugin
cd com.spotify.controller.sdPlugin
npm install

Copy the folder into %APPDATA%\HotSpot\StreamDock\plugins\ and restart StreamDock.

Spotify setup (bring your own Client ID)

The plugin ships with a working Client ID, but it is registered to the original author, so everyone using it shares the same Spotify app quota. For anything beyond casual use, register your own — it takes two minutes:

1. Open the Spotify Developer Dashboard and Create app.
2. Add this exact Redirect URI:

   http://127.0.0.1:4381/callback
   

   (Spotify requires the literal loopback IP 127.0.0.1, not localhost.)
3. Copy your Client ID into app.js:

   const CLIENT_ID = '<your client id>';

4. Restart the plugin, press any Spotify key, and complete the sign-in in your browser.

No client secret is used — authorization is PKCE, so the Client ID is safe to keep in the source.

First run

Press any Spotify key while signed out and the browser opens the Spotify consent page; approve it and the deck comes alive. The refresh token is stored in StreamDock's global settings so you stay signed in across restarts. If a key ever shows the Connect lock again, just press it to re-authenticate.

Configuration

• Volume Up / Down — set the step (1–30%) in the key's Property Inspector.
• Seek Forward / Back — set the jump (5–60s) in the key's Property Inspector.

Development

app/                → n/a (single-file plugin)
app.js              main plugin (WebSocket ↔ StreamDock, Spotify Web API, canvas rendering)
manifest.json       action definitions
ui/*.html           Property Inspectors
svgs/               Tabler icon glyphs (tinted at load)
imgs/               key/category icons

Run the plugin standalone for debugging with test.bat. Logs are written to plugin.log (rotated at 512 KB) — never committed, and tokens are never logged.

Credits

• Icons: Tabler Icons (MIT)
• ws and @napi-rs/canvas (MIT)

License

MIT © derb1rd