YOUR NEXT STEP

Spotify Sense

Instructions for the upcoming NeuralCompanion interface.

Spotify Sense is an optional addon that connects NeuralCompanion to Spotify through the official Spotify Web API. It can read the current track, provide music-aware chat context, run explicit playback commands, lower music while NC speaks, comment on song changes, and offer optional story music.

It works from Spotify metadata only. It does not record or analyze the computer’s audio, and it cannot hear a song through a microphone.

Before you connect

You need:

  • Enable Spotify Sense in Addons and restart if requested.
  • A Spotify account and a Spotify playback device.
  • A Spotify Developer app with the exact local redirect URI below.
  • An account and device that permit Spotify Web API playback control. If the provider reports Premium required, resolve that in Spotify before retrying.
  • A running NC conversation runtime for spoken commands and chat context.

Create an app in the Spotify Developer Dashboard, then add this redirect URI exactly:

http://127.0.0.1:8765/spotify/callback

Use the explicit 127.0.0.1 address above, with the same port and path in NC and the Spotify app. Although NC’s callback validator also accepts localhost, Spotify does not accept localhost as a redirect URI. See Spotify’s redirect URI requirements. The NC login flow rejects HTTPS URLs and non-loopback hostnames.

Spotify Sense requests these scopes:

  • user-read-playback-state
  • user-modify-playback-state
  • user-read-currently-playing
  • playlist-read-private
  • playlist-read-collaborative
  • user-top-read

If you change scopes, disconnect and connect again so Spotify grants the new set.

Connect and activate

  1. Open Addons > Spotify Sense > Connect.
  2. Enter the app’s Client ID. Do not paste a Client Secret or access token into chat or a preset.
  3. Confirm the Redirect URI matches the URI saved in the Spotify app.
  4. Select Save Settings.
  5. Select Login / Connect and approve the request in the browser.
  6. Return to NC and confirm the account status.
  7. Select Refresh Devices and, under Playback, choose the intended Default device and volume.
  8. On Overview, turn on Enable Spotify Sense.

The Overview page shows Now playing, album artwork, and quick Play, Pause, Next, Previous, Refresh track, and Volume 30% actions. A Spotify quick view is also available from Conversation when the addon is connected and enabled.

Opening the Connect page, saving a Client ID, or reading this guide does not log in or start playback.

How commands are routed

Spotify Sense distinguishes between:

  • Explicit user commands — a clear request in chat or speech, such as “pause music”, “skip this”, or “play relaxing focus music”.
  • Autonomous/model-initiated changes — a suggestion generated by the model or another addon rather than a direct request.

Explicit user commands can run when Spotify Sense is enabled, connected, and the addon supports the action. They do not require Allow autonomous LLM Spotify control.

The playback controls have different jobs:

  • Allow autonomous LLM Spotify control permits model-initiated changes.
  • Require confirmation before changing music applies to those autonomous or tool-triggered changes. A direct user command is treated as confirmed.
  • Allow queue changes is required before NC adds to the queue, even for a direct request.
  • Allow playlist changes is required before NC starts a playlist, even for a direct request.
  • Default device and Default volume choose where and how loudly playback starts. They do not grant permission by themselves.

Start with manual playback and keep confirmation enabled for any autonomous control you choose to permit. A successful play ... command can add one-turn hidden context so the assistant can respond naturally about the selected track or playlist.

Useful examples:

  • “play Master of Puppets with Metallica”
  • “play ambient electronic”
  • “play relaxing focus music”
  • “pause music”
  • “resume Spotify”
  • “skip this”
  • “previous track”
  • “what song is this?”
  • “turn Spotify down”
  • “next song and comment about it”

Unclear requests fall through to the normal assistant reply instead of forcing a Spotify change.

Music awareness

Open Runtime → Vision Sensors → Spotify Sense → Awareness and enable Enable music awareness in chat. From the addon Overview, Open Spotify sensory settings opens this source. When Spotify is connected, NC can include compact playback metadata in normal chat:

  • track and artists
  • album
  • play/pause state
  • progress and duration
  • active device
  • playlist/context URI
  • metadata-based mood hint

The assistant is instructed to treat this as ambient context, not as a user request, and not to claim it heard the audio. Only mention music when relevant keeps the context quiet; Include paused Spotify track context keeps the last paused track available; Album art thumbnail controls the cover in the addon Overview.

Music response mode sets the strength:

  • Off — no hidden music context.
  • Subtle — quiet mood awareness; mention music only when useful.
  • Companion — music can become a small companion signal.
  • DJ / Music Critic — more playful music commentary when relevant.
  • Story soundtrack — treats the music as atmosphere for story or roleplay.

These modes affect response style, not playback permission.

Song changes and hidden replies

Open Runtime → Vision Sensors → Spotify Sense → Song changes. Song-change monitor checks Spotify about every seven seconds. Turn it on only if you want NC to notice track changes. Comment on song changes is a separate permission for an optional acknowledgement; a selected monitor alone does not make NC speak.

Cooldown controls reduce repetition:

  • Proactive comment cooldown (seconds)
  • Hidden response cooldown (seconds)
  • User music-change cooldown (seconds)

User music-change cooldown protects a track you changed manually. While it is active, NC waits before changing playback again. Set it to 0 only if you want NC to act immediately after your own changes.

A hidden music comment still needs the shared hidden-speech permission in Shared Awareness Policy, a fresh eligible track change, and the configured cooldown. Silence can be the correct result when nothing meaningful changed.

In Runtime → Vision Sensors → Spotify Sense, the Presets, Quick styles, Response prompts, and Source guidance tabs contain the hidden-sensory setup. Loading a preset or selecting a style does not by itself grant playback control, background speech, or image generation. These controls are not separate Awareness or Hidden Sense sections in Addons.

Ducking

Lower music while NC speaks reduces the Spotify volume during spoken replies. Restore volume after speech returns it afterward. Duck volume, Fade down (ms), and Fade up (ms) tune the transition.

Ducking is off by default. Note the starting volume and test one short reply. If Restore volume after speech is off, the lowered volume is intentional until you raise it. Pausing music and disabling awareness are separate actions.

Music Hub and story use

Music Hub is a larger browsing and playback surface for the connected account, including current playback, playlists, top music, and discovery. It uses the same connection and permissions as the rest of Spotify Sense.

Under Story:

  • Story mode background music allows story requests to use music.
  • Prefer story ambience favors ambient playlists.
  • Autonomous music is Off, Routines only, or Full.
  • Story music target volume, Transition floor volume, and the story fades control the soundtrack levels.

Story music requires its own opt-in and still uses the connected account and an active device. It does not turn on Allow autonomous LLM Spotify control for ordinary chat. If there is no connected account or active device, NC reports that instead of forcing playback.

Stop using it

  • In Runtime → Vision Sensors → Spotify Sense → Awareness, turn off Enable music awareness in chat to stop normal chat context.
  • In the same source’s Song changes tab, turn off Song-change monitor to stop track polling or Comment on song changes to stop optional acknowledgements.
  • Turn off Allow autonomous LLM Spotify control to block model-initiated playback.
  • Use Pause when you want playback itself to stop.
  • Use Connect > Disconnect to remove the account connection.

Hiding the Spotify Sense tab, disabling awareness, or stopping NC does not necessarily stop the Spotify app from playing. Review volume restoration before disconnecting while NC is speaking.

Troubleshooting

  • Specific song does not start: enable Debug log, retry, then open the debug log from Advanced. Track-like requests use a track-preferred search.
  • No active device: start Spotify on a phone, browser, or desktop app, then use Refresh Devices.
  • Premium required: playback control may require Premium or a capable device.
  • Invalid redirect URI: the URI in the Spotify app must match the addon URI character for character.
  • Missing scopes or new features fail: disconnect and reconnect so the new scope set is granted.
  • Token expired: NC refreshes tokens automatically. If refresh fails, disconnect and connect again.
  • Spotify app not open: open Spotify or transfer playback to another listed device.
  • Music context sounds wrong: check Now playing, Music response mode, and the cooldowns. The addon uses metadata; it does not analyze audio.

Spotify tokens are stored in local addon runtime storage. Do not commit runtime files, account tokens, or a real Client ID and secret to the repository. Never place credentials in a persona, preset, chat message, or screenshot.