@foorschtbar/node-red-contrib-spotify-light 1.1.0

Lightweight Node-RED node to read the Spotify playback state and currently playing track via the Spotify Web API

npm install @foorschtbar/node-red-contrib-spotify-light

node-red-contrib-spotify-light

Lightweight Node-RED node to read the playback state and the currently playing track from the Spotify Web API.

This package intentionally implements only two read-only endpoints:

• Get Currently Playing Track – GET /me/player/currently-playing
• Get Playback State – GET /me/player

Authentication uses the OAuth 2.0 Authorization Code flow directly inside the Node-RED editor, with automatic access-token refresh.

Background

Spotify changed their API so that the refresh token you receive after completing OAuth is now only valid for 6 months (the refresh token is used to renew the access token, which itself lasts just 1 hour and is required for every API request). The original node-red-contrib-spotify node is no longer maintained — its dependencies are outdated and it crashes frequently for me since Spotify's authentication flow change.

This package is a lightweight, up-to-date replacement with a much smaller dependency footprint. It deliberately implements only the two read-only endpoints needed to read the playback state and the currently playing track — everything required to drive my PixelIt Matrix Display. It also detects when the refresh token has expired and can notify you so you can re-authenticate manually — see the Error handling & re-authentication section for details.

Installation

Standard installation via Node-RED's palette manager or using npm:

npm install @foorschtbar/node-red-contrib-spotify-light

Setup

1. Create an app in the Spotify Developer Dashboard.
2. In Node-RED, add a spotify-light node and create a new Spotify account config node.
3. Enter the app's Client ID and Client Secret.
4. Copy the Redirect URI shown in the config node into the Spotify app's Redirect URIs settings and save.
5. Click Authenticate with Spotify and approve the requested permissions.

Requested scopes: user-read-currently-playing, user-read-playback-state.

Note: The redirect URI is derived from your Node-RED editor URL. If Node-RED is reachable under a different public URL than the one you are editing from, adjust the redirect URI in the Spotify dashboard accordingly.

Nodes

• spotify-light: Reads playback information for the configured account.

Actions

The action can be selected in the node's config or overridden per message via msg.action (currentlyPlaying / playbackState).

Input

Output

Error handling & re-authentication

Spotify refresh tokens issued for Dashboard apps are valid for 6 months and are not extended by refreshing. Once a refresh token expires (or is revoked), the node can no longer obtain new access tokens and the user must run the Authenticate with Spotify flow again.

When this happens the node reports it in two machine-readable ways so you can react automatically (e.g. send a webhook, push notification or e-mail to trigger a re-auth):

1. Catch node (recommended)

Wire a Catch node to the spotify-light node. On a re-auth failure the caught message contains:

msg.error.message  =  "Error: Re-authentication required: the Spotify refresh token is invalid or expired. ..."

Node-RED builds msg.error.message via the error's toString(), so it is prefixed with Error: . Match with includes(...) (not startsWith(...)).

You can filter on this to trigger only on re-auth (and not on transient network/API errors) and build a payload for your webhook/notification:

// Function node after a Catch node
if (msg.error && msg.error.message && msg.error.message.includes("Re-authentication required")) {
    msg.payload = {
        event: "spotify_reauth_required",
        message: msg.error.message,
        node: msg.error.source && msg.error.source.id,
        timestamp: new Date().toISOString()
    };
    return msg;   // forward to an http request / notification node
}
return null;      // ignore other (transient) errors

Forward the filtered message to an http request node to fire your webhook (or to any notification node such as ntfy, Gotify or Home Assistant). This exact Catch → Detect re-auth → Webhook / Notification branch is included in the example flow.

2. Status node

Wire a Status node to the spotify-light node. On a re-auth failure the node status is set to the exact text Re-authentication required, which you can match:

// Function node after a Status node
if (msg.status && msg.status.text === "Re-authentication required") {
    return msg;   // forward to your webhook / notification node
}
return null;

All other (transient) errors keep their original Spotify/HTTP error message, so you can distinguish a permanent re-auth requirement from a temporary failure.

Example Flow

An example flow is included in examples/example.json. It contains inject nodes for both actions, a debug output, and a Catch → Detect re-auth → Webhook / Notification branch that reacts to the re-authentication condition. Import it via the Node-RED menu → Import, then set your Spotify account on the spotify-light node and your webhook URL on the http request node.

Release workflow

• Change the version in package.json
• Update the package-lock.json by running npm install
• Create commit
• Tag the commit with the new version
• Push the commit and the tag to GitHub git push origin main --tags

License

MIT