hey-spotify 🎤 🎵

A premium, voice-controlled terminal interface for Spotify playback. Control your music without leaving your terminal or touching your keyboard.

📋 Prerequisites

• Spotify Premium: A Premium subscription is required for playback control via the Spotify API.
• Python 3.8+: Ensure you have a modern Python version installed.

🚀 Quick Start

1. Install

Install the package directly via pip:

pip install hey-spotify

Note: Depending on your OS, you might need to install system dependencies for PyAudio (e.g., portaudio on macOS or python3-pyaudio on Linux).

2. Spotify API Setup

1. Go to the Spotify Developer Dashboard.
2. Create a new app and name it (e.g., hey-spotify).
3. Add http://127.0.0.1:8888/callback as a Redirect URI in your app settings.
4. Set up your environment variables (see Environment Variables section).

3. Run

Launch the CLI:

hey-spotify

On the first run, it will open your browser for authentication.

🎙️ Voice Commands

Once active, just say "Hey Spotify" followed by:

• play <song name> — Plays a specific track.
• pause / stop — Pauses current playback.
• resume / continue — Resumes playback.
• next / skip — Skips to the next track.
• previous — Goes back to the previous track.
• volume <0-100> — Sets volume to a specific level.
• volume up / volume down — Adjusts volume by 10%.
• now playing — Shows information about the current track.
• exit / quit — Closes the application.

⚙️ Configuration

Environment Variables

You can create a .env file in your working directory or set them in your shell:

SPOTIPY_CLIENT_ID='your_client_id'
SPOTIPY_CLIENT_SECRET='your_client_secret'
SPOTIPY_REDIRECT_URI='http://127.0.0.1:8888/callback'

CLI Options

• --list-mics: List all detected microphone devices.
• --mic-index <index>: Use a non-default microphone.
• --no-wake-word: Disable "Hey Spotify" trigger and listen continuously.
• --language <lang>: Change recognition language (e.g., en-US, es-ES).
• --voice-debug: See what the engine is hearing in real-time.

🛠️ Troubleshooting

• Microphone not found: Ensure you've granted terminal permissions for the microphone and use --list-mics to find the correct index.
• Spotify Authentication: Ensure your Redirect URI in the Dashboard exactly matches the one in your environment.

📄 License

Distributed under the MIT License. See LICENSE for more information.