Skip to content

About

Retro (Spotify Voice Remote) - offline voice remote for Spotify Premium. Local Whisper, zero cloud, zero cost.

Topics

Resources

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

Retro - personalized voice music remote

CI License: PolyForm Strict Python 3.10-3.12 Windows 10/11 $0

Retro

A free, local voice remote for Spotify Premium. Runs in your system tray, listens offline (speech never leaves your machine), and controls whatever device Spotify is already playing on - desktop, phone, speaker.

"hey retro, play bohemian rhapsody"

Why it's different

  • It knows your music. Your top artists, playlists, and liked songs are injected into the recognizer's vocabulary and boosted in search ranking - so niche artist names and personal playlist names ("7.0", spoken as "seven point o") resolve correctly when generic assistants fail.
  • It forgives how people actually talk. Two speech engines hear every command and their transcriptions compete in a fuzzy-ranked search - a garbled "play money to work by eat" still finds Money Twërk by Yeat. Control words ("skip", "pause") dispatch instantly with zero transcription latency.
  • Zero cloud, zero cost, zero secrets. There is no server and no account: Spotify Connect is the player, auth is PKCE against your own free developer app, speech is processed entirely on-device (GPU-accelerated Whisper when you have an NVIDIA card), and your session token is encrypted at rest.

Architecture

flowchart LR
    MIC([Microphone]) --> VOSK["Vosk (streaming)<br/>wake-word spotting"]
    VOSK -- "hey retro..." --> CUT[wake-phrase<br/>audio slicing]
    CUT --> WHISPER["Whisper (GPU/CPU)<br/>command transcription<br/>+ personal hotwords"]
    VOSK -. "control words<br/>(skip/pause/...)" .-> INTENT
    WHISPER --> INTENT[intent parser<br/>+ homophone aliases]
    INTENT --> SEARCH["dual-hearing fuzzy search<br/>artist affinity + ranking"]
    SEARCH --> API[Spotify Connect<br/>Web API]
    API --> DEV([Your Spotify device])
    INTENT -. feedback .-> OSD[instant OSD +<br/>sound cues]
Loading

Everything left of the Spotify API runs offline on your machine.

Requirements

  • Windows 10/11 (this app is Windows-only)
  • Spotify Premium (the playback-control API requires it)
  • Python 3.10–3.12 (winget install Python.Python.3.12 if you don't have it)
  • A microphone
  • Spotify open on at least one device (the API commands a device; it doesn't produce audio)
  • An NVIDIA GPU is optional - the installer detects one and enables faster, more accurate recognition automatically

Install ($0, ~5 minutes)

Step 1 - get Python (skip if you have 3.10-3.12):

winget install Python.Python.3.12

Step 2 - get Retro (either way works):

git clone https://github.com/haeganm/retro-spotify-voice-remote
cd retro-spotify-voice-remote
powershell -ExecutionPolicy Bypass -File install.ps1

    No git? Click Code → Download ZIP on this page, extract it anywhere permanent (not Downloads), then right-click install.ps1 → Run with PowerShell.

The installer creates an isolated environment (nothing touches your system Python), installs the tested dependency set, enables GPU acceleration if you have an NVIDIA card, and puts a Retro icon on your desktop.

Step 3 - connect your Spotify (one time):

  1. Go to https://developer.spotify.com/dashboard, log in with your Spotify account, and click Create app:
    • App name / description: anything ("Retro" works)
    • Redirect URI (must be exact): http://127.0.0.1:8888/callback - click Add
    • API: Web API → Save
  2. On the app's Settings page, copy the Client ID.
  3. Double-click the Retro icon on your desktop, paste the Client ID into the dialog, and approve the browser sign-in once. The speech models (~120 MB) download automatically on first run.

Done. Retro now lives in your system tray. Tray menu → Start with Windows makes it launch silently at login.

Developer install (no installer)
pip install .        # or pip install -e . for hacking
retro                # console entry point

Using the remote - read this first

Retro is a remote control, not a chatbot. It matches specific command patterns - it cannot chat, answer questions, or figure out "play something chill for studying". Stick to the phrases below and it's fast and reliable; freestyle and it will say "didn't catch that".

The rhythm: say the wake phrase, then the command:

  • One breath (fastest): "hey retro, play bohemian rhapsody"
  • Two-step: say "hey retro", wait for the chime, then speak the command within ~6 seconds. Use this when the room is noisy.

What the sounds mean: chime = it heard the wake word · soft pop = command done · low "uh-oh" = it heard you but couldn't match a command · the corner overlay and tray-icon tooltip show exactly what it did.

The commands

Say Does
play <song> / play <song> by <artist> search and play a track
queue <song> / play <song> next / add <song> to the queue add to queue
play the artist <name> / play songs by <name> play an artist
play the album <name> play an album
playlist <name> / play my playlist <name> your playlists (names with numbers work: say "seven point o" for "7.0")
play my liked songs shuffle your Liked Songs
pause / stop pause
play / resume resume
next / skip next track
previous / go back previous track (restarts the track if there's no previous)
volume up / volume down / turn it up volume ±10 (Spotify volume, never system volume)
set volume to fifty volume 0-100
what's playing show the current track
shuffle on / shuffle off shuffle
put it back / go back to what was playing undo - restore what was playing before

Getting the best recognition

  • Include the artist for anything that isn't famous: "play brain stew by green day" beats "play brain stew". Title + artist is the single biggest accuracy win.
  • Speak at a normal pace and let the sentence end - Retro processes when you stop talking (about half a second of silence).
  • Say the actual title, not a description. "play that one from the gym playlist" won't work; "playlist gym" will.
  • Control words ("skip", "pause") respond instantly; song searches take a moment (speech transcription + Spotify search).
  • If it keeps mishearing a phrase, run retro --misses to see what it actually heard - the transcript log (%APPDATA%\Retro\retro.log) shows both recognition engines' hearings for every command.
  • Test any command without speaking: retro --say "play daft punk".

Config

%APPDATA%\Retro\config.json:

{
  "client_id": "...",
  "wake_phrase": "hey retro",
  "model": "small",
  "input_device": null,
  "sound": true,
  "stt": "whisper",
  "whisper_model": "auto",
  "device": "auto",
  "notify": "smart",
  "duck": true,
  "osd": true,
  "log": true
}
  • model: the Vosk wake-word model - "small" (default) or "medium"
  • stt: "whisper" (default) or "vosk" to skip Whisper on very weak machines
  • whisper_model: "auto" (default: small.en on GPU, base.en on CPU) or any faster-whisper model name
  • device: "auto" (default: NVIDIA GPU when present - install nvidia-cublas-cu12 nvidia-cudnn-cu12 - else CPU), "cuda", or "cpu"
  • input_device: pick a microphone from the tray menu instead of editing this
  • sound: wake chime + success/error cues; false to disable
  • duck: true (default) - music volume dips while you speak a command, restored right after (big win for speaker setups)
  • notify: "smart" (default - subtle sound for control commands, voice/toast for results and errors; the tray tooltip always shows the last action) or "all" to toast everything
  • log: true (default) - keep the local speech transcript log for debugging; false disables it

Tray menu

Listening on/off · Microphone picker · Start with Windows · Re-authenticate · Quit

Tests

python test_intents.py   # parser + player logic (offline, instant)
python e2e_voice.py      # synthesized speech through the real model (Windows)

Privacy & security

  • Speech never leaves your machine - wake-word and transcription are fully offline. Outbound traffic is exactly: api.spotify.com/accounts.spotify.com (HTTPS, playback + auth) and two one-time model downloads (alphacephei.com, SHA-256-verified; huggingface.co, hash-verified). No telemetry, no update checks.
  • Auth is OAuth PKCE - no client secret exists anywhere. Your Spotify token is encrypted at rest with Windows DPAPI; your Client ID is not a secret. Everything lives in %APPDATA%\Retro, never in the repo.
  • Transcript log: recognized speech is kept locally in retro.log (last ~500 lines) for debugging. Set "log": false in config to disable, or delete the file anytime.
  • System-touching behaviors (both user-triggered, both reversible): "Start with Windows" creates a Startup shortcut; selecting a Bluetooth headset mic temporarily switches the Windows default audio output so your music keeps playing, restored when you switch back - crash-safe.

See SECURITY.md for the full threat model.

Troubleshooting

Symptom Do this
It never hears the wake word retro --mic-test - speak while it runs; pick the mic with the biggest bar (tray → Microphone), or leave it on Automatic
It mishears commands retro --misses lists everything it failed to parse; %APPDATA%\Retro\retro.log shows exactly what each engine heard
"No Spotify device found" Open Spotify on any device - this is a remote, not a player
Music goes quiet/mono on a Bluetooth headset mic Windows can't do hi-fi audio + headset mic at once; the app keeps sound flowing on the headset channel and restores hi-fi when you switch mics. Use Automatic (a wired/built-in mic) for full quality
Discord/Zoom voice breaks while Retro runs A Bluetooth headset has only ONE mic channel - if Retro is set to the headset mic, it holds that channel 24/7 and calls can't use it. Switch Retro to Automatic (tray → Microphone) so it listens via a built-in/wired mic and your headset stays free for calls
Commands need Premium The Spotify playback API rejects free accounts

Uninstall: delete the repo folder, %APPDATA%\Retro, and the desktop shortcut (plus tray → "Start with Windows" off, or delete the Startup shortcut).

License & credits

PolyForm Strict 1.0.0: see LICENSE. You're welcome to use Retro as-is for personal and other noncommercial purposes, and to read and learn from the source. Commercial use, redistribution, and derivative works require written permission - open an issue to ask (I'm reasonable). Copyright (C) 2026 Haegan McGarry.

The license covers everything in this repository - code, docs, logo, banner, and audio assets alike; see NOTICE for the plain-language summary.

Built on Vosk (Apache-2.0), faster-whisper / OpenAI Whisper (MIT), and spotipy (MIT).


Retro is an independent project - not affiliated with, endorsed by, or sponsored by Spotify AB. Spotify is a trademark of Spotify AB. Requires a user-created Spotify developer application and a Spotify Premium account.

About

Retro (Spotify Voice Remote) - offline voice remote for Spotify Premium. Local Whisper, zero cloud, zero cost.

Topics

Resources

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages