# hey-spotify 🎤 🎵

[![PyPI version](https://img.shields.io/pypi/v/hey-spotify.svg)](https://pypi.org/project/hey-spotify/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

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:

```bash
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](https://developer.spotify.com/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](#environment-variables) section).

### 3. Run
Launch the CLI:

```bash
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:

```bash
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.
