Metadata-Version: 2.4
Name: hey-spotify
Version: 1.1.0
Summary: A premium, voice-controlled terminal interface for Spotify playback.
Author-email: Prayag Tushar <prayagtushar@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/prayagtushar/hey-spotify
Project-URL: Documentation, https://prayagtushar.github.io/hey-spotify/
Project-URL: Repository, https://github.com/prayagtushar/hey-spotify.git
Project-URL: BugTracker, https://github.com/prayagtushar/hey-spotify/issues
Keywords: spotify,cli,voice-control,voice-command,hands-free,music
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Intended Audience :: End Users/Desktop
Classifier: Intended Audience :: Developers
Classifier: Topic :: Multimedia :: Sound/Audio :: Players
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: spotipy>=2.24.0
Requires-Dist: python-dotenv>=1.0.1
Requires-Dist: PyAudio>=0.2.14
Requires-Dist: SpeechRecognition>=3.10.4
Requires-Dist: rich>=13.7.1
Dynamic: license-file

# 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.
