hey-spotify-cli 1.0.0__tar.gz

hey_spotify_cli-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 prayag
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

hey_spotify_cli-1.0.0/PKG-INFO

@@ -0,0 +1,110 @@
+Metadata-Version: 2.4
+Name: hey-spotify-cli
+Version: 1.0.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-cli
+Project-URL: Documentation, https://prayagtushar.github.io/hey-spotify-cli/
+Project-URL: Repository, https://github.com/prayagtushar/hey-spotify-cli.git
+Project-URL: BugTracker, https://github.com/prayagtushar/hey-spotify-cli/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-cli.svg)](https://pypi.org/project/hey-spotify-cli/)
+[![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-cli
+```
+
+*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.

hey_spotify_cli-1.0.0/README.md

@@ -0,0 +1,76 @@
+# hey-spotify 🎤 🎵
+
+[![PyPI version](https://img.shields.io/pypi/v/hey-spotify-cli.svg)](https://pypi.org/project/hey-spotify-cli/)
+[![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-cli
+```
+
+*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.

hey_spotify_cli-1.0.0/hey_spotify/__init__.py

@@ -0,0 +1,15 @@
+from importlib import import_module
+from typing import Any
+
+__all__ = ["SpotifyClient", "VoiceEngine", "ParsedCommand", "parse_voice_command"]
+
+
+def __getattr__(name: str) -> Any:
+    if name == "SpotifyClient":
+        return import_module(".spotify_client", __name__).SpotifyClient
+    if name == "VoiceEngine":
+        return import_module(".voice_engine", __name__).VoiceEngine
+    if name in ("ParsedCommand", "parse_voice_command"):
+        utils_module = import_module(".utils", __name__)
+        return getattr(utils_module, name)
+    raise AttributeError(f"module '{__name__}' has no attribute '{name}'")

hey_spotify_cli-1.0.0/hey_spotify/__main__.py

@@ -0,0 +1,264 @@
+import asyncio
+import argparse
+import re
+from typing import Any, Optional
+
+try:
+    from dotenv import load_dotenv
+except ModuleNotFoundError:
+    def load_dotenv() -> bool:  # type: ignore[override]
+        return False
+
+from .spotify_client import SpotifyClient
+from .utils import parse_voice_command
+from .voice_engine import VoiceEngine
+from .ui.theme import ACCENT, APP_LOGO, APP_SUBTITLE, ERROR, SUCCESS, WARNING
+
+RICH_AVAILABLE = True
+try:
+    from rich.console import Console
+    from rich.live import Live
+
+    from .ui.cli import generate_boot_banner, generate_layout
+except ModuleNotFoundError:
+    RICH_AVAILABLE = False
+
+    def generate_boot_banner() -> str:
+        return f"{APP_LOGO}\n{APP_SUBTITLE}\n"
+
+    def generate_layout(current_song: str = "None", status: str = "Waiting...", last_command: str = "N/A") -> str:
+        return (
+            f"Now Playing: {current_song}\n"
+            f"Status: {status}\n"
+            f"Last Command: {last_command}\n"
+        )
+
+
+class PlainConsole:
+    def clear(self) -> None:
+        return
+
+    def print(self, message: Any) -> None:
+        print(_strip_markup(str(message)))
+
+
+class NoopLive:
+    def __enter__(self) -> "NoopLive":
+        return self
+
+    def __exit__(self, exc_type: Any, exc: Any, traceback: Any) -> bool:
+        return False
+
+    def update(self, _renderable: Any) -> None:
+        return
+
+
+def _strip_markup(message: str) -> str:
+    return re.sub(r"\[/?[^\]]+\]", "", message)
+
+
+console = Console() if RICH_AVAILABLE else PlainConsole()
+
+
+def print_status(style: str, message: str) -> None:
+    if RICH_AVAILABLE:
+        console.print(f"[{style}]{message}[/]")
+        return
+    console.print(message)
+
+
+def _update_view(live: Any, current_song: str, status: str, last_command: str) -> None:
+    live.update(generate_layout(current_song=current_song, status=status, last_command=last_command))
+
+
+async def handle_command(spotify: SpotifyClient, command: str) -> str:
+    parsed = parse_voice_command(command)
+
+    if parsed.action == "play":
+        return await asyncio.to_thread(spotify.play_specific_track, str(parsed.value or ""))
+    if parsed.action == "pause":
+        return await asyncio.to_thread(spotify.toggle_playback, "pause")
+    if parsed.action == "resume":
+        return await asyncio.to_thread(spotify.toggle_playback, "resume")
+    if parsed.action == "next":
+        return await asyncio.to_thread(spotify.skip_track)
+    if parsed.action == "previous":
+        return await asyncio.to_thread(spotify.previous_track)
+    if parsed.action == "volume_set":
+        if parsed.value is not None:
+            return await asyncio.to_thread(spotify.set_volume, int(parsed.value))
+        return "Invalid volume value."
+    if parsed.action == "volume_delta":
+        if parsed.value is not None:
+            return await asyncio.to_thread(spotify.adjust_volume, int(parsed.value))
+        return "Invalid volume value."
+    if parsed.action == "now_playing":
+        song = await asyncio.to_thread(spotify.current_song)
+        return f"Now playing: {song}"
+    if parsed.action == "exit":
+        return "Exiting hey-spotify."
+
+    return (
+        "I didn't understand the command. Try: "
+        "play <song>, pause, resume, next, previous, volume <0-100>."
+    )
+
+
+def list_microphones() -> int:
+    microphones = VoiceEngine.list_microphones()
+    if not microphones:
+        print_status(
+            ERROR,
+            "No microphones detected. Check OS microphone permissions and input device settings.",
+        )
+        return 1
+
+    print_status(SUCCESS, "Detected microphone devices:")
+    for index, microphone in enumerate(microphones):
+        console.print(f"  [{index}] {microphone}")
+    return 0
+
+
+async def main(
+    microphone_index: Optional[int] = None,
+    voice_debug: bool = False,
+    require_wake_word: bool = True,
+    language: Optional[str] = None,
+) -> None:
+    load_dotenv()
+
+    console.clear()
+    console.print(generate_boot_banner())
+    await asyncio.sleep(0.8)
+
+    try:
+        listener = VoiceEngine(
+            microphone_index=microphone_index,
+            debug=voice_debug,
+            language=language,
+        )
+    except Exception as exc:
+        print_status(ERROR, f"Microphone initialization failed: {exc}")
+        return
+
+    try:
+        spotify = SpotifyClient()
+    except Exception as exc:
+        print_status(ERROR, f"Spotify client initialization failed: {exc}")
+        return
+
+    current_song = "Nothing playing"
+    status = "Waiting for wake word"
+    last_command = "N/A"
+
+    print_status(SUCCESS, "hey-spotify is active. Say 'Hey Spotify' to begin.")
+    print_status(ACCENT, f"Using microphone: {listener.selected_mic_name}")
+    print_status(ACCENT, f"Voice language: {listener.language}")
+    if not require_wake_word:
+        print_status(WARNING, "Wake word disabled. Listening directly for commands.")
+
+    live_context = (
+        Live(
+            generate_layout(current_song=current_song, status=status, last_command=last_command),
+            console=console,
+            refresh_per_second=6,
+        )
+        if RICH_AVAILABLE
+        else NoopLive()
+    )
+
+    with live_context as live:
+        while True:
+            pending_command: Optional[str] = None
+            if require_wake_word:
+                status = "Listening for wake word"
+                _update_view(live, current_song, status, last_command)
+
+                wake_word_detected, pending_command = await asyncio.to_thread(
+                    listener.listen_for_wake_event
+                )
+                if not wake_word_detected:
+                    continue
+
+                status = "Wake word detected"
+                _update_view(live, current_song, status, last_command)
+            else:
+                status = "Listening for command"
+                _update_view(live, current_song, status, last_command)
+
+            command = pending_command or await asyncio.to_thread(listener.get_command)
+            if not command:
+                status = "Could not understand command"
+                _update_view(live, current_song, status, last_command)
+                print_status(WARNING, "Could not understand command.")
+                continue
+
+            last_command = command
+            status = "Executing command"
+            _update_view(live, current_song, status, last_command)
+
+            try:
+                result = await handle_command(spotify, command)
+                if result == "Exiting hey-spotify.":
+                    print_status(ACCENT, result)
+                    break
+
+                current_song = await asyncio.to_thread(spotify.current_song)
+                status = result
+                _update_view(live, current_song, status, last_command)
+                print_status(ACCENT, result)
+            except Exception as exc:
+                status = "Command failed"
+                _update_view(live, current_song, status, last_command)
+                print_status(ERROR, f"Error: {exc}")
+
+
+def cli() -> None:
+    parser = argparse.ArgumentParser(description="EchoSpotify voice-controlled Spotify CLI")
+    parser.add_argument(
+        "--list-mics",
+        action="store_true",
+        help="List detected microphone devices and exit.",
+    )
+    parser.add_argument(
+        "--mic-index",
+        type=int,
+        default=None,
+        help="Microphone index to use (find indexes with --list-mics).",
+    )
+    parser.add_argument(
+        "--voice-debug",
+        action="store_true",
+        help="Print recognized wake/command transcripts for debugging.",
+    )
+    parser.add_argument(
+        "--no-wake-word",
+        action="store_true",
+        help="Skip wake-word detection and listen directly for commands.",
+    )
+    parser.add_argument(
+        "--language",
+        type=str,
+        default=None,
+        help="Speech recognition language (example: en-US). Overrides VOICE_LANGUAGE.",
+    )
+    args = parser.parse_args()
+
+    if args.list_mics:
+        raise SystemExit(list_microphones())
+
+    try:
+        asyncio.run(
+            main(
+                microphone_index=args.mic_index,
+                voice_debug=args.voice_debug,
+                require_wake_word=not args.no_wake_word,
+                language=args.language,
+            )
+        )
+    except KeyboardInterrupt:
+        print_status(ERROR, "Shutting down... Goodbye.")
+
+
+if __name__ == "__main__":
+    cli()

hey_spotify_cli-1.0.0/hey_spotify/py.typed

@@ -0,0 +1 @@
+# Typing marker for PEP 561

hey_spotify_cli-1.0.0/hey_spotify/spotify_client.py

@@ -0,0 +1,171 @@
+import os
+from typing import Any, Optional
+
+try:
+    import spotipy
+    from spotipy.oauth2 import SpotifyOAuth
+except ModuleNotFoundError:
+    spotipy = None
+    SpotifyOAuth = None
+
+try:
+    from dotenv import load_dotenv
+except ModuleNotFoundError:
+    def load_dotenv() -> bool:  # type: ignore[override]
+        return False
+
+
+class SpotifyClient:
+    def __init__(self) -> None:
+        if spotipy is None or SpotifyOAuth is None:
+            raise RuntimeError(
+                "Missing dependency 'spotipy'. Run: pip install -r requirements.txt"
+            )
+
+        load_dotenv()
+        client_id = os.getenv("SPOTIPY_CLIENT_ID") or os.getenv("SPOTIFY_CLIENT_ID")
+        client_secret = os.getenv("SPOTIPY_CLIENT_SECRET") or os.getenv("SPOTIFY_CLIENT_SECRET")
+        redirect_uri = os.getenv("SPOTIPY_REDIRECT_URI") or os.getenv("SPOTIFY_REDIRECT_URI")
+
+        missing_envs = []
+        if not client_id:
+            missing_envs.append("SPOTIPY_CLIENT_ID (or SPOTIFY_CLIENT_ID)")
+        if not client_secret:
+            missing_envs.append("SPOTIPY_CLIENT_SECRET (or SPOTIFY_CLIENT_SECRET)")
+        if not redirect_uri:
+            missing_envs.append("SPOTIPY_REDIRECT_URI (or SPOTIFY_REDIRECT_URI)")
+        if missing_envs:
+            formatted = ", ".join(missing_envs)
+            raise RuntimeError(f"Missing environment variables: {formatted}")
+
+        scope = (
+            "user-modify-playback-state "
+            "user-read-playback-state "
+            "user-read-currently-playing"
+        )
+        self.sp = spotipy.Spotify(
+            auth_manager=SpotifyOAuth(
+                client_id=client_id,
+                client_secret=client_secret,
+                redirect_uri=redirect_uri,
+                scope=scope,
+                cache_path=".cache",
+            )
+        )
+
+    def _active_device_id(self) -> Optional[str]:
+        try:
+            devices = self.sp.devices().get("devices", [])
+        except Exception:
+            return None
+
+        if not devices:
+            return None
+        for device in devices:
+            if device.get("is_active"):
+                return device.get("id")
+        return devices[0].get("id")
+
+    def _current_playback(self) -> Optional[dict[str, Any]]:
+        try:
+            return self.sp.current_playback()
+        except Exception:
+            return None
+
+    def current_song(self) -> str:
+        playback = self._current_playback()
+        if not playback or not playback.get("item"):
+            return "Nothing playing"
+
+        item = playback["item"]
+        artist_names = ", ".join(artist["name"] for artist in item.get("artists", []))
+        return f"{item.get('name', 'Unknown')} - {artist_names or 'Unknown artist'}"
+
+    def play_specific_track(self, track_name: str) -> str:
+        if not track_name:
+            return "Tell me what to play, for example: play Numb by Linkin Park."
+
+        try:
+            results = self.sp.search(q=track_name, limit=1, type="track")
+        except Exception as exc:
+            return f"Spotify search failed: {exc}"
+
+        items = results.get("tracks", {}).get("items", [])
+        if not items:
+            return f"Could not find '{track_name}'."
+
+        track = items[0]
+        track_uri = track["uri"]
+        track_name = track.get("name", "Unknown song")
+        artist_name = track.get("artists", [{}])[0].get("name", "Unknown artist")
+
+        device_id = self._active_device_id()
+        if not device_id:
+            return "No Spotify device found. Open Spotify on phone/desktop and try again."
+
+        try:
+            self.sp.start_playback(device_id=device_id, uris=[track_uri])
+        except Exception as exc:
+            return f"Could not start playback: {exc}"
+
+        return f"Playing {track_name} by {artist_name}."
+
+    def toggle_playback(self, action: str) -> str:
+        device_id = self._active_device_id()
+        if not device_id:
+            return "No Spotify device found. Open Spotify and start a device first."
+
+        if action == "pause":
+            try:
+                self.sp.pause_playback(device_id=device_id)
+            except Exception as exc:
+                return f"Could not pause playback: {exc}"
+            return "Paused playback."
+        if action == "resume":
+            try:
+                self.sp.start_playback(device_id=device_id)
+            except Exception as exc:
+                return f"Could not resume playback: {exc}"
+            return "Resumed playback."
+        return "Unknown playback action."
+
+    def skip_track(self) -> str:
+        device_id = self._active_device_id()
+        if not device_id:
+            return "No active Spotify device."
+        try:
+            self.sp.next_track(device_id=device_id)
+        except Exception as exc:
+            return f"Could not skip track: {exc}"
+        return "Skipped to next track."
+
+    def previous_track(self) -> str:
+        device_id = self._active_device_id()
+        if not device_id:
+            return "No active Spotify device."
+        try:
+            self.sp.previous_track(device_id=device_id)
+        except Exception as exc:
+            return f"Could not go to previous track: {exc}"
+        return "Went to previous track."
+
+    def set_volume(self, volume_percent: int) -> str:
+        volume_percent = max(0, min(100, int(volume_percent)))
+        device_id = self._active_device_id()
+        if not device_id:
+            return "No active Spotify device."
+        try:
+            self.sp.volume(volume_percent, device_id=device_id)
+        except Exception as exc:
+            return f"Could not set volume: {exc}"
+        return f"Volume set to {volume_percent}%."
+
+    def adjust_volume(self, delta: int) -> str:
+        playback = self._current_playback()
+        if not playback:
+            return "Nothing is playing, so I cannot adjust volume."
+        current = playback.get("device", {}).get("volume_percent")
+        if current is None:
+            return "Could not read current volume."
+        target = max(0, min(100, current + delta))
+        return self.set_volume(target)

hey_spotify_cli-1.0.0/hey_spotify/ui/cli.py

@@ -0,0 +1,126 @@
+from rich import box
+from rich.align import Align
+from rich.console import Group
+from rich.layout import Layout
+from rich.panel import Panel
+from rich.text import Text
+
+from .theme import (
+    APP_LOGO,
+    APP_SUBTITLE,
+    APP_TITLE,
+    FOOTER_BORDER,
+    HEADER_BORDER,
+    HISTORY_BORDER,
+    STATUS_BORDER,
+)
+
+
+def _status_style(status: str) -> str:
+    lowered = status.lower()
+    if "error" in lowered or "failed" in lowered:
+        return "bold red3"
+    if "listening" in lowered or "wake word" in lowered:
+        return "bold yellow3"
+    if any(token in lowered for token in ("playing", "paused", "resumed", "volume", "skipped")):
+        return "bold spring_green3"
+    return "bold bright_white"
+
+
+def generate_boot_banner() -> Panel:
+    logo = Text.from_markup(f"[spring_green3]{APP_LOGO}[/spring_green3]")
+    subtitle = Text.from_markup(f"[hot_pink2]{APP_SUBTITLE}[/hot_pink2]")
+    hints = Text.from_markup(
+        "[bright_cyan]Wake:[/] [white]'hey spotify'[/]    "
+        "[bright_cyan]Try:[/] [white]play after hours[/], [white]volume 40[/], [white]next[/]"
+    )
+
+    return Panel(
+        Group(
+            Align.center(logo),
+            Align.center(subtitle),
+            Align.center(Text.from_markup("[grey74]Voice-first music terminal[/grey74]")),
+            Align.center(hints),
+        ),
+        title="[bold hot_pink2]BOOT SEQUENCE[/bold hot_pink2]",
+        subtitle="[bold white]ready for command capture[/bold white]",
+        border_style=HEADER_BORDER,
+        box=box.DOUBLE,
+        padding=(1, 2),
+    )
+
+
+def generate_layout(current_song: str = "None", status: str = "Waiting...", last_command: str = "N/A") -> Layout:
+    """
+    Creates a full-screen layout for the hey-spotify CLI.
+    """
+    layout = Layout()
+    layout.split_column(
+        Layout(name="header", size=8),
+        Layout(name="body", ratio=1),
+        Layout(name="footer", size=3),
+    )
+
+    header_group = Group(
+        Align.center(Text.from_markup(f"[bold hot_pink2]{APP_TITLE}[/bold hot_pink2]")),
+        Align.center(Text.from_markup("[spring_green3]| ||| ||||| ||| |[/spring_green3]")),
+        Align.center(Text.from_markup("[grey70]Hands-free Spotify control in your terminal[/grey70]")),
+    )
+    layout["header"].update(
+        Panel(
+            header_group,
+            border_style=HEADER_BORDER,
+            box=box.HEAVY,
+        )
+    )
+
+    layout["body"].split_row(
+        Layout(name="status_panel", ratio=5),
+        Layout(name="log_panel", ratio=4),
+    )
+
+    playback_text = Text()
+    playback_text.append("NOW PLAYING\n", style="bold bright_white")
+    playback_text.append(f"{current_song}\n\n", style="spring_green3")
+    playback_text.append("SYSTEM STATUS\n", style="bold bright_white")
+    playback_text.append(status, style=_status_style(status))
+
+    layout["status_panel"].update(
+        Panel(
+            playback_text,
+            title="[bold spring_green3]Playback Deck[/bold spring_green3]",
+            border_style=STATUS_BORDER,
+            box=box.ROUNDED,
+            padding=(1, 2),
+        )
+    )
+
+    history_text = Text()
+    history_text.append("LAST HEARD\n", style="bold bright_white")
+    history_text.append(f"'{last_command}'\n\n", style="deep_sky_blue2")
+    history_text.append("COMMANDS\n", style="bold bright_white")
+    history_text.append("play <song>\n", style="white")
+    history_text.append("pause | resume\n", style="white")
+    history_text.append("next | previous\n", style="white")
+    history_text.append("volume up/down | volume 40\n", style="white")
+    history_text.append("now playing", style="white")
+
+    layout["log_panel"].update(
+        Panel(
+            history_text,
+            title="[bold deep_sky_blue2]Voice Log[/bold deep_sky_blue2]",
+            border_style=HISTORY_BORDER,
+            box=box.ROUNDED,
+            padding=(1, 2),
+        )
+    )
+
+    layout["footer"].update(
+        Panel(
+            "[bold yellow3]Wake:[/] 'hey spotify'   [bold orchid]Exit:[/] Ctrl+C",
+            border_style=FOOTER_BORDER,
+            box=box.SQUARE,
+        )
+    )
+
+    return layout

hey_spotify_cli-1.0.0/hey_spotify/ui/theme.py

@@ -0,0 +1,23 @@
+APP_TITLE = "hey-spotify"
+APP_SUBTITLE = "Voice Control for Spotify"
+
+APP_LOGO = r"""
+:'######::'########:::'#######::'########:'####:'########:'##:::'##:
+'##... ##: ##.... ##:'##.... ##:... ##..::. ##:: ##.....::. ##:'##::
+ ##:::..:: ##:::: ##: ##:::: ##:::: ##::::: ##:: ##::::::::. ####:::
+. ######:: ########:: ##:::: ##:::: ##::::: ##:: ######:::::. ##::::
+:..... ##: ##.....::: ##:::: ##:::: ##::::: ##:: ##...::::::: ##::::
+'##::: ##: ##:::::::: ##:::: ##:::: ##::::: ##:: ##:::::::::: ##::::
+. ######:: ##::::::::. #######::::: ##::::'####: ##:::::::::: ##::::
+:......:::..::::::::::.......::::::..:::::....::..:::::::::::..:::::
+"""
+
+ACCENT = "bright_cyan"
+SUCCESS = "spring_green3"
+WARNING = "yellow3"
+ERROR = "red3"
+
+HEADER_BORDER = "hot_pink2"
+STATUS_BORDER = "spring_green3"
+HISTORY_BORDER = "deep_sky_blue3"
+FOOTER_BORDER = "orchid"

hey_spotify_cli-1.0.0/hey_spotify/utils.py

@@ -0,0 +1,51 @@
+import re
+from dataclasses import dataclass
+from typing import Optional, Union
+
+
+@dataclass
+class ParsedCommand:
+    action: str
+    value: Optional[Union[str, int]] = None
+
+
+def parse_voice_command(raw_command: str) -> ParsedCommand:
+    command = raw_command.strip().lower()
+    if not command:
+        return ParsedCommand(action="unknown")
+
+    if command.startswith("play "):
+        query = command.replace("play", "", 1).strip()
+        return ParsedCommand(action="play", value=query)
+    if command == "play":
+        return ParsedCommand(action="play", value="")
+
+    if any(word in command for word in ("exit", "quit", "goodbye")):
+        return ParsedCommand(action="exit")
+
+    if any(word in command for word in ("pause", "stop")):
+        return ParsedCommand(action="pause")
+
+    if any(word in command for word in ("resume", "continue", "unpause")):
+        return ParsedCommand(action="resume")
+
+    if any(word in command for word in ("next", "skip")):
+        return ParsedCommand(action="next")
+
+    if any(word in command for word in ("previous", "go back", "back track")):
+        return ParsedCommand(action="previous")
+
+    if "volume up" in command or "louder" in command:
+        return ParsedCommand(action="volume_delta", value=10)
+
+    if "volume down" in command or "quieter" in command:
+        return ParsedCommand(action="volume_delta", value=-10)
+
+    volume_match = re.search(r"(?:set )?volume(?: to)?\s+(\d{1,3})", command)
+    if volume_match:
+        return ParsedCommand(action="volume_set", value=int(volume_match.group(1)))
+
+    if any(word in command for word in ("what is playing", "now playing", "current song")):
+        return ParsedCommand(action="now_playing")
+
+    return ParsedCommand(action="unknown")

hey_spotify_cli-1.0.0/hey_spotify/voice_engine.py

@@ -0,0 +1,183 @@
+import os
+import re
+from difflib import SequenceMatcher
+from typing import Optional
+
+try:
+    import speech_recognition as sr
+except ModuleNotFoundError:
+    sr = None
+
+
+class VoiceEngine:
+    def __init__(
+        self,
+        microphone_index: Optional[int] = None,
+        debug: bool = False,
+        language: Optional[str] = None,
+    ) -> None:
+        if sr is None:
+            raise RuntimeError(
+                "Missing dependency 'SpeechRecognition'. Run: pip install -r requirements.txt"
+            )
+
+        self.debug = debug
+        self.language = (language or os.getenv("VOICE_LANGUAGE") or "en-US").strip() or "en-US"
+        self.wake_words = (
+            "hey spotify",
+            "hello spotify",
+            "ok spotify",
+            "okay spotify",
+            "hey spotty",
+        )
+
+        mic_names = self.list_microphones()
+        if not mic_names:
+            raise RuntimeError(
+                "No input device detected. Connect a microphone, grant terminal mic access, "
+                "then run: python main.py --list-mics"
+            )
+
+        if microphone_index is None:
+            env_index = os.getenv("MIC_DEVICE_INDEX")
+            if env_index:
+                try:
+                    microphone_index = int(env_index)
+                except ValueError as exc:
+                    raise RuntimeError(
+                        f"Invalid MIC_DEVICE_INDEX='{env_index}'. It must be an integer."
+                    ) from exc
+            else:
+                microphone_index = self._choose_default_mic_index(mic_names)
+
+        if microphone_index is not None:
+            if microphone_index < 0 or microphone_index >= len(mic_names):
+                raise RuntimeError(
+                    f"Invalid microphone index {microphone_index}. Run: python main.py --list-mics"
+                )
+
+        self.recognizer = sr.Recognizer()
+        self.recognizer.dynamic_energy_threshold = True
+        self.recognizer.pause_threshold = 0.8
+        self.recognizer.non_speaking_duration = 0.5
+        self.recognizer.phrase_threshold = 0.25
+
+        selected_index = microphone_index
+        self.selected_mic_name = (
+            mic_names[selected_index] if selected_index is not None else "system default"
+        )
+
+        try:
+            self.microphone = sr.Microphone(device_index=selected_index)
+        except Exception as exc:
+            raise RuntimeError(f"No usable microphone found: {exc}") from exc
+
+        with self.microphone as source:
+            self.recognizer.adjust_for_ambient_noise(source, duration=1)
+
+    @staticmethod
+    def list_microphones() -> list[str]:
+        if sr is None:
+            return []
+        try:
+            return sr.Microphone.list_microphone_names()
+        except Exception:
+            return []
+
+    @staticmethod
+    def _choose_default_mic_index(mic_names: list[str]) -> int:
+        ranked_keywords = ("microphone", "mic", "input", "headset", "airpods")
+        for index, name in enumerate(mic_names):
+            lowered = name.lower()
+            if any(keyword in lowered for keyword in ranked_keywords):
+                return index
+        return 0
+
+    @staticmethod
+    def _normalize(text: str) -> str:
+        cleaned = re.sub(r"[^a-z0-9\s]", " ", text.lower())
+        return " ".join(cleaned.split())
+
+    @staticmethod
+    def _is_spotify_token(token: str) -> bool:
+        known_aliases = {"spotify", "spotty", "spotifly", "spotifi", "spotfy"}
+        if token in known_aliases:
+            return True
+        return SequenceMatcher(None, token, "spotify").ratio() >= 0.72
+
+    def _extract_wake_remainder(self, transcript: str) -> tuple[bool, Optional[str]]:
+        normalized = self._normalize(transcript)
+        if not normalized:
+            return False, None
+
+        for wake_word in self.wake_words:
+            wake_normalized = self._normalize(wake_word)
+            if wake_normalized in normalized:
+                remainder = normalized.split(wake_normalized, 1)[1].strip()
+                return True, remainder or None
+
+        tokens = normalized.split()
+        if not tokens:
+            return False, None
+
+        greeting_tokens = {"hey", "hello", "hi", "ok", "okay"}
+        spotify_index: Optional[int] = None
+        for index, token in enumerate(tokens):
+            if self._is_spotify_token(token):
+                spotify_index = index
+                break
+
+        if spotify_index is None:
+            return False, None
+
+        has_greeting = any(token in greeting_tokens for token in tokens[: spotify_index + 1])
+        starts_with_spotify = spotify_index == 0
+        if not has_greeting and not starts_with_spotify:
+            return False, None
+
+        remainder_tokens = tokens[spotify_index + 1 :]
+        remainder = " ".join(remainder_tokens).strip()
+        return True, remainder or None
+
+    def _transcribe_once(
+        self,
+        timeout: Optional[float] = None,
+        phrase_time_limit: float = 4,
+    ) -> Optional[str]:
+        with self.microphone as source:
+            try:
+                audio = self.recognizer.listen(
+                    source,
+                    timeout=timeout,
+                    phrase_time_limit=phrase_time_limit,
+                )
+            except sr.WaitTimeoutError:
+                return None
+
+        try:
+            text = self.recognizer.recognize_google(audio, language=self.language)
+        except sr.UnknownValueError:
+            return None
+        except sr.RequestError:
+            return None
+
+        return text.lower().strip()
+
+    def listen_for_wake_event(self) -> tuple[bool, Optional[str]]:
+        transcript = self._transcribe_once(timeout=None, phrase_time_limit=4.5)
+        if self.debug and transcript:
+            print(f"[voice-debug] wake-listen heard: {transcript}")
+        if not transcript:
+            return False, None
+
+        return self._extract_wake_remainder(transcript)
+
+    def listen_for_wake_word(self) -> bool:
+        detected, _ = self.listen_for_wake_event()
+        return detected
+
+    def get_command(self) -> Optional[str]:
+        transcript = self._transcribe_once(timeout=5, phrase_time_limit=8)
+        if self.debug and transcript:
+            print(f"[voice-debug] command heard: {transcript}")
+        return transcript

hey_spotify_cli-1.0.0/hey_spotify_cli.egg-info/PKG-INFO

@@ -0,0 +1,110 @@
+Metadata-Version: 2.4
+Name: hey-spotify-cli
+Version: 1.0.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-cli
+Project-URL: Documentation, https://prayagtushar.github.io/hey-spotify-cli/
+Project-URL: Repository, https://github.com/prayagtushar/hey-spotify-cli.git
+Project-URL: BugTracker, https://github.com/prayagtushar/hey-spotify-cli/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-cli.svg)](https://pypi.org/project/hey-spotify-cli/)
+[![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-cli
+```
+
+*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.

hey_spotify_cli-1.0.0/hey_spotify_cli.egg-info/SOURCES.txt

@@ -0,0 +1,18 @@
+LICENSE
+README.md
+pyproject.toml
+hey_spotify/__init__.py
+hey_spotify/__main__.py
+hey_spotify/py.typed
+hey_spotify/spotify_client.py
+hey_spotify/utils.py
+hey_spotify/voice_engine.py
+hey_spotify/ui/__init__.py
+hey_spotify/ui/cli.py
+hey_spotify/ui/theme.py
+hey_spotify_cli.egg-info/PKG-INFO
+hey_spotify_cli.egg-info/SOURCES.txt
+hey_spotify_cli.egg-info/dependency_links.txt
+hey_spotify_cli.egg-info/entry_points.txt
+hey_spotify_cli.egg-info/requires.txt
+hey_spotify_cli.egg-info/top_level.txt

hey_spotify_cli-1.0.0/hey_spotify_cli.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

hey_spotify_cli-1.0.0/hey_spotify_cli.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+hey-spotify = hey_spotify.__main__:cli

hey_spotify_cli-1.0.0/hey_spotify_cli.egg-info/requires.txt

@@ -0,0 +1,5 @@
+spotipy>=2.24.0
+python-dotenv>=1.0.1
+PyAudio>=0.2.14
+SpeechRecognition>=3.10.4
+rich>=13.7.1

hey_spotify_cli-1.0.0/hey_spotify_cli.egg-info/top_level.txt

@@ -0,0 +1 @@
+hey_spotify

hey_spotify_cli-1.0.0/pyproject.toml

@@ -0,0 +1,52 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "hey-spotify-cli"
+version = "1.0.0"
+authors = [
+  { name="Prayag Tushar", email="prayagtushar@gmail.com" },
+]
+description = "A premium, voice-controlled terminal interface for Spotify playback."
+readme = "README.md"
+requires-python = ">=3.8"
+keywords = ["spotify", "cli", "voice-control", "voice-command", "hands-free", "music"]
+license = { text = "MIT" }
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Environment :: Console",
+    "Intended Audience :: End Users/Desktop",
+    "Intended Audience :: Developers",
+    "Topic :: Multimedia :: Sound/Audio :: Players",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.8",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+]
+dependencies = [
+    "spotipy>=2.24.0",
+    "python-dotenv>=1.0.1",
+    "PyAudio>=0.2.14",
+    "SpeechRecognition>=3.10.4",
+    "rich>=13.7.1",
+]
+
+[project.urls]
+Homepage = "https://github.com/prayagtushar/hey-spotify-cli"
+Documentation = "https://prayagtushar.github.io/hey-spotify-cli/"
+Repository = "https://github.com/prayagtushar/hey-spotify-cli.git"
+BugTracker = "https://github.com/prayagtushar/hey-spotify-cli/issues"
+
+[project.scripts]
+hey-spotify = "hey_spotify.__main__:cli"
+
+[tool.setuptools]
+packages = ["hey_spotify", "hey_spotify.ui"]
+
+[tool.setuptools.package-data]
+hey_spotify = ["py.typed"]

hey_spotify_cli-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+