A lightweight, feature-rich JavaScript extension for Spicetify that acts as a real-time bi-directional bridge between the Spotify Desktop Client and a WebSocket server (e.g., Python).

• Native Settings UI: Access configuration settings directly inside Spotify by clicking your Profile Picture.
• API Key Authentication: Optional security token support to protect incoming commands and authenticate outgoing push events.
• WSS / Secure Connections: Full support for encrypted wss:// connections for remote setups or local SSL environments.
• Automatic Reconnection: Safely attempts auto-reconnecting if the server drops or restarts.
• Real-Time Push Events: Emits instant WebSocket events on player state changes:
  • InitialState: Dispatched immediately upon WebSocket connection (includes live-patched progress timestamp).
  • SongChanged: Triggered on track changes.
  • PlayPauseChanged: Triggered when playback is paused or resumed.
  • VolumeChanged: Triggered on volume adjustments (uses trailing debounce to avoid network spam).
  • RepeatChanged: Triggered when repeat mode is changed.
  • ShuffleChanged: Triggered when shuffle mode is toggled.
  • SeekChanged: Triggered only when manually seeking or scrubbing through a track.
  • Ping: Triggered periodically every 30 seconds as a heartbeat.
• Full Control Commands: Supports incoming JSON requests to control playback, volume, shuffle, repeat, seeking, and status queries.

You can configure the extension directly within Spotify:

1. Click on your Profile Picture in the top-right corner of Spotify.
2. Click Connect API Settings.
3. Adjust your settings in the popup modal:
   • WebSocket Server URL: Default is ws://127.0.0.1:9090. Use wss://IP:PORT:9090 for encrypted connections or wss://DOMAIN:PORT for remote connections.
   • API Key / Secret Token (Optional): Set a custom secret token matching your server configuration for authenticated setups.
   • Reconnect Interval (ms): Set how fast the extension attempts to reconnect on disconnect (Minimum 1000ms).

1. Download spicetify-connect-api.js.

2. Place the file in the appropriate path for your operating system:

   • Windows: C:\Users\%username%\AppData\Roaming\spicetify\Extensions\ (Paste in Win + R)
   • Linux / macOS: ~/.config/spicetify/Extensions/

3. Enable the extension in your terminal:

spicetify config extensions spicetify-connect-api.js

4. Apply the changes:

spicetify apply

If you are building a Python application to interact with this extension, use the companion Python package:

👉 tobfd/spicetify-websocket

It handles the WebSocket server setup, SSL/WSS contexts, API Key verification, event listeners, response matching, and typed command execution out of the box!

By default, the extension connects to ws://127.0.0.1:9090.

Send JSON messages in the following structure (include "token" if API Key is set in settings):

{
  "requestName": "SetVolume",
  "requestId": "unique-id-123",
  "token": "your-optional-api-key",
  "payload": {
    "level": 0.8
  }
}

Emitted event types include: InitialState, SongChanged, PlayPauseChanged, VolumeChanged, RepeatChanged, ShuffleChanged, SeekChanged, Ping.

{
  "eventName": "SongChanged",
  "token": "your-optional-api-key",
  "payload": { ... }
}

{
  "eventName": "Response",
  "requestId": "unique-id-123",
  "token": "your-optional-api-key",
  "success": true,
  "payload": { ... }
}