headless-music 1.1.0__tar.gz

headless_music-1.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 imnotgoingtohindiclass
+
+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.

headless_music-1.1.0/PKG-INFO

@@ -0,0 +1,114 @@
+Metadata-Version: 2.4
+Name: headless-music
+Version: 1.1.0
+Summary: headless music: for minimal cpu/gpu usage while listening to music
+Author: Rishav Ganguly
+License: MIT
+Project-URL: Homepage, https://github.com/imnotgoingtohindiclass/headless_music
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: yt-dlp
+Requires-Dist: spotipy
+Requires-Dist: python-mpv
+Requires-Dist: rich
+Dynamic: license-file
+
+# headless_music
+
+A Spotify-inspired, terminal-based music player. `headless_music` brings music to your terminal with full-color ASCII album art and an endless recommendation queue.
+
+## Features
+
+- Spotify-inspired terminal UI with a modern 3-panel layout (built with `rich`).
+- Color ASCII album art (when available from Spotify).
+- Playlist-first playback for Spotify or YouTube playlists.
+- Endless radio mode that queues recommendations after the playlist ends.
+- Smooth, pulsing progress bar showing playback and loading status.
+- First-run configuration wizard for easy setup.
+- Cross-platform: runs on systems with Python and `mpv`.
+
+## Prerequisites
+
+`mpv` is required as the audio backend.
+
+### macOS (Homebrew)
+```bash
+brew install mpv
+```
+
+### Ubuntu/Debian
+```bash
+sudo apt update && sudo apt install mpv
+```
+
+### Windows (Chocolatey)
+```bash
+choco install mpv
+```
+
+## Installation
+
+To install, simply use the Python package manager pip:
+```bash
+pip install headless_music
+```
+
+## Usage
+
+To start the player, type into your terminal
+```bash
+headless_music
+```
+
+On first launch a setup wizard will walk you through adding your Spotify API credentials. Obtain these from the Spotify Developer Dashboard: [https://developer.spotify.com/dashboard/](https://developer.spotify.com/dashboard/)
+
+## Controls
+
+| Key   | Action                                           |
+| ----- | ------------------------------------------------ |
+| Space | Play / Pause                                     |
+| n     | Next track                                       |
+| p     | Previous track                                   |
+| c     | Re-run the configuration wizard (stops playback) |
+| q     | Quit                                             |
+
+## Configuration
+
+* Spotify API credentials (Client ID, Client Secret) are required for full functionality.
+* The configuration wizard writes credentials to a user config file (see `config` in repo for format).
+* `mpv` path and additional mpv options can be set in the config.
+
+
+## Contribution
+
+Contributions are welcome. Please open issues for bugs or feature requests and submit pull requests against `main`. Follow the existing code style and include tests for new functionality.
+
+## License
+
+This project is licensed under the MIT License. See `LICENSE` for details.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+

headless_music-1.1.0/README.md

@@ -0,0 +1,98 @@
+# headless_music
+
+A Spotify-inspired, terminal-based music player. `headless_music` brings music to your terminal with full-color ASCII album art and an endless recommendation queue.
+
+## Features
+
+- Spotify-inspired terminal UI with a modern 3-panel layout (built with `rich`).
+- Color ASCII album art (when available from Spotify).
+- Playlist-first playback for Spotify or YouTube playlists.
+- Endless radio mode that queues recommendations after the playlist ends.
+- Smooth, pulsing progress bar showing playback and loading status.
+- First-run configuration wizard for easy setup.
+- Cross-platform: runs on systems with Python and `mpv`.
+
+## Prerequisites
+
+`mpv` is required as the audio backend.
+
+### macOS (Homebrew)
+```bash
+brew install mpv
+```
+
+### Ubuntu/Debian
+```bash
+sudo apt update && sudo apt install mpv
+```
+
+### Windows (Chocolatey)
+```bash
+choco install mpv
+```
+
+## Installation
+
+To install, simply use the Python package manager pip:
+```bash
+pip install headless_music
+```
+
+## Usage
+
+To start the player, type into your terminal
+```bash
+headless_music
+```
+
+On first launch a setup wizard will walk you through adding your Spotify API credentials. Obtain these from the Spotify Developer Dashboard: [https://developer.spotify.com/dashboard/](https://developer.spotify.com/dashboard/)
+
+## Controls
+
+| Key   | Action                                           |
+| ----- | ------------------------------------------------ |
+| Space | Play / Pause                                     |
+| n     | Next track                                       |
+| p     | Previous track                                   |
+| c     | Re-run the configuration wizard (stops playback) |
+| q     | Quit                                             |
+
+## Configuration
+
+* Spotify API credentials (Client ID, Client Secret) are required for full functionality.
+* The configuration wizard writes credentials to a user config file (see `config` in repo for format).
+* `mpv` path and additional mpv options can be set in the config.
+
+
+## Contribution
+
+Contributions are welcome. Please open issues for bugs or feature requests and submit pull requests against `main`. Follow the existing code style and include tests for new functionality.
+
+## License
+
+This project is licensed under the MIT License. See `LICENSE` for details.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+

headless_music-1.1.0/headless_music/__init__.py

@@ -0,0 +1,2 @@
+__version__ = "1.1.0"
+__author__ = "Rishav Ganguly"

headless_music-1.1.0/headless_music/config.py

@@ -0,0 +1,123 @@
+import json
+import logging
+from pathlib import Path
+from rich.console import Console
+from rich.prompt import Prompt, Confirm
+
+console = Console()
+
+CONFIG_FILE = Path.home() / ".headless_music_config.json"
+LOG_FILE = Path.home() / ".headless_music.log"
+
+
+def setup_logging():
+    logging.basicConfig(
+        filename=LOG_FILE,
+        level=logging.WARNING,
+        format='%(asctime)s - %(levelname)s - %(message)s'
+    )
+
+
+def load_config():
+    if CONFIG_FILE.exists():
+        try:
+            with open(CONFIG_FILE, 'r') as f:
+                return json.load(f)
+        except Exception as e:
+            logging.warning(f"Could not load config: {e}")
+            console.print(f"[yellow]Warning: Could not load config: {e}[/yellow]")
+    return {}
+
+
+def save_config(config):
+    try:
+        with open(CONFIG_FILE, 'w') as f:
+            json.dump(config, f, indent=2)
+        return True
+    except Exception as e:
+        logging.error(f"Error saving config: {e}")
+        console.print(f"[red]Error saving config: {e}[/red]")
+        return False
+
+
+def validate_config(config):
+    required = ['SPOTIFY_CLIENT_ID', 'SPOTIFY_CLIENT_SECRET',
+                'PLAYLIST_SOURCE', 'PLAYLIST_URL']
+    missing = [key for key in required if not config.get(key)]
+
+    if missing:
+        console.print(f"[red]Missing configuration: {', '.join(missing)}[/red]")
+        return False
+    return True
+
+
+def setup_wizard():
+    console.clear()
+    console.print("=" * 60, style="cyan")
+    console.print("🎵 Welcome to headless_music Setup!",
+                  style="bold cyan", justify="center")
+    console.print("=" * 60, style="cyan")
+    console.print()
+
+    config = load_config()
+
+    console.print("📱 [bold]Spotify API Credentials[/bold]")
+    console.print("   Get these from: https://developer.spotify.com/dashboard",
+                  style="dim")
+    console.print()
+
+    spotify_id = Prompt.ask(
+        "   Spotify Client ID",
+        default=config.get('SPOTIFY_CLIENT_ID', '')
+    )
+    spotify_secret = Prompt.ask(
+        "   Spotify Client Secret",
+        default=config.get('SPOTIFY_CLIENT_SECRET', ''),
+        password=True
+    )
+
+    console.print()
+    console.print("🎧 [bold]Playlist Source[/bold]")
+    console.print()
+
+    source_choice = Prompt.ask(
+        "   Choose your playlist source",
+        choices=["spotify", "youtube"],
+        default=config.get('PLAYLIST_SOURCE', 'spotify')
+    )
+
+    console.print()
+
+    if source_choice == "spotify":
+        console.print("   Enter your Spotify playlist URL or URI", style="dim")
+        console.print("   Example: https://open.spotify.com/playlist/37i9dQZF1DXcBWIGoYBM5M",
+                      style="dim")
+        playlist_url = Prompt.ask("   Spotify Playlist URL/URI")
+    else:
+        console.print("   Enter your YouTube playlist URL", style="dim")
+        console.print("   Example: https://www.youtube.com/playlist?list=...",
+                      style="dim")
+        playlist_url = Prompt.ask("   YouTube Playlist URL")
+
+    console.print()
+
+    new_config = {
+        'SPOTIFY_CLIENT_ID': spotify_id,
+        'SPOTIFY_CLIENT_SECRET': spotify_secret,
+        'PLAYLIST_SOURCE': source_choice,
+        'PLAYLIST_URL': playlist_url
+    }
+
+    if save_config(new_config):
+        console.print("✓ Configuration saved!", style="bold green")
+        console.print(f"   Config location: {CONFIG_FILE}", style="dim")
+        console.print(f"   Log location: {LOG_FILE}", style="dim")
+    else:
+        console.print("⚠️  Could not save configuration.", style="yellow")
+
+    console.print()
+    if Confirm.ask("Start headless_music now?", default=True):
+        return new_config
+    else:
+        console.print("👋 Run this script again when you're ready!", style="cyan")
+        return None

headless_music-1.1.0/headless_music/fetchers/__init__.py

@@ -0,0 +1,4 @@
+from .spotify import SpotifyFetcher
+from .youtube import YouTubeFetcher
+
+__all__ = ['SpotifyFetcher', 'YouTubeFetcher']

headless_music-1.1.0/headless_music/fetchers/spotify.py

@@ -0,0 +1,166 @@
+import os
+import logging
+import random
+import spotipy
+from spotipy.oauth2 import SpotifyClientCredentials
+from spotipy.cache_handler import CacheFileHandler
+
+
+cache_path = os.path.join(os.path.expanduser("~"), ".cache_headless_music")
+cache_handler = CacheFileHandler(cache_path=cache_path)
+
+
+class SpotifyFetcher:
+    """Handle all Spotify API interactions."""
+
+    def __init__(self, client_id, client_secret):
+        self.client = None
+        self.client_id = client_id
+        self.client_secret = client_secret
+        self._initialize_client()
+
+    def _initialize_client(self):
+        """Initialize Spotify client with credentials."""
+        try:
+            self.client = spotipy.Spotify(
+                auth_manager=SpotifyClientCredentials(
+                    client_id=self.client_id,
+                    client_secret=self.client_secret,
+                    cache_handler=cache_handler
+                ),
+                requests_timeout=5
+            )
+            logging.info("Spotify client initialized")
+        except Exception as e:
+            logging.error(f"Failed to initialize Spotify: {e}")
+            self.client = None
+
+    def get_playlist_tracks(self, playlist_url):
+        """Fetch all tracks from a Spotify playlist."""
+        if not self.client:
+            return []
+
+        try:
+            playlist_id = self._extract_playlist_id(playlist_url)
+            results = []
+            offset = 0
+
+            while True:
+                response = self.client.playlist_tracks(playlist_id, offset=offset, limit=100)
+                for item in response['items']:
+                    if item['track']:
+                        track = item['track']
+                        image_url = (track['album']['images'][-1]['url']
+                                   if track['album']['images'] else None)
+                        results.append((
+                            track['name'],
+                            track['artists'][0]['name'],
+                            "Spotify",
+                            image_url
+                        ))
+
+                if not response['next']:
+                    break
+                offset += 100
+
+            logging.info(f"Fetched {len(results)} tracks from Spotify")
+            return results
+        except Exception as e:
+            logging.error(f"Error fetching Spotify playlist: {e}")
+            return []
+
+    def get_recommendations(self, seed_tracks, limit=20):
+        """Get Spotify recommendations based on seed tracks."""
+        if not self.client:
+            return []
+
+        results = []
+        seen_ids = set()
+
+        sample_size = min(len(seed_tracks), 5)
+        sampled = random.sample(seed_tracks, sample_size)
+
+        for title, artist, _, _ in sampled:
+            if len(results) >= limit:
+                break
+
+            try:
+                search_results = self.client.search(
+                    q=f"{title} {artist}", type="track", limit=1
+                )
+                if search_results['tracks']['items']:
+                    seed_id = search_results['tracks']['items'][0]['id']
+                    try:
+                        recs = self.client.recommendations(seed_tracks=[seed_id], limit=5)
+                        for track in recs['tracks']:
+                            track_id = track['id']
+                            if track_id not in seen_ids:
+                                image_url = (track['album']['images'][-1]['url']
+                                           if track['album']['images'] else None)
+                                results.append((
+                                    track['name'],
+                                    track['artists'][0]['name'],
+                                    "Spotify",
+                                    image_url
+                                ))
+                                seen_ids.add(track_id)
+                    except Exception:
+                        pass
+            except Exception:
+                continue
+
+        # Fallback: related artists
+        if len(results) < limit:
+            results.extend(self._get_related_artist_tracks(
+                sampled, limit - len(results), seen_ids
+            ))
+
+        logging.info(f"Generated {len(results)} recommendations")
+        return results
+
+    def _get_related_artist_tracks(self, seed_tracks, limit, seen_ids):
+        """Get tracks from related artists."""
+        results = []
+
+        for title, artist, _, _ in seed_tracks:
+            if len(results) >= limit:
+                break
+
+            try:
+                artist_results = self.client.search(
+                    q=f"artist:{artist}", type="artist", limit=1
+                )
+                if artist_results['artists']['items']:
+                    artist_id = artist_results['artists']['items'][0]['id']
+                    related = self.client.artist_related_artists(artist_id)
+
+                    for rel_artist in related['artists'][:3]:
+                        top_tracks = self.client.artist_top_tracks(rel_artist['id'])
+                        for track in top_tracks['tracks'][:2]:
+                            track_id = track['id']
+                            if track_id not in seen_ids:
+                                image_url = (track['album']['images'][-1]['url']
+                                           if track['album']['images'] else None)
+                                results.append((
+                                    track['name'],
+                                    track['artists'][0]['name'],
+                                    "Spotify",
+                                    image_url
+                                ))
+                                seen_ids.add(track_id)
+                                if len(results) >= limit:
+                                    return results
+            except Exception:
+                continue
+
+        return results
+
+    @staticmethod
+    def _extract_playlist_id(playlist_url):
+        """Extract playlist ID from various URL formats."""
+        if 'spotify.com' in playlist_url:
+            return playlist_url.split('playlist/')[-1].split('?')[0]
+        elif 'spotify:playlist:' in playlist_url:
+            return playlist_url.split('spotify:playlist:')[-1]
+        return playlist_url
+

headless_music-1.1.0/headless_music/fetchers/youtube.py

@@ -0,0 +1,59 @@
+import logging
+import random
+import yt_dlp
+
+
+class YouTubeFetcher:
+    def __init__(self):
+        self.ydl_opts_flat = {
+            'quiet': True,
+            'extract_flat': True,
+            'no_warnings': True,
+            'ignoreerrors': True,
+            'no_color': True
+        }
+        self.ydl_opts_full = {
+            'quiet': True,
+            'extract_flat': False,
+            'no_warnings': True,
+            'ignoreerrors': True,
+            'no_color': True
+        }
+
+    def get_playlist_titles(self, url):
+        try:
+            with yt_dlp.YoutubeDL(self.ydl_opts_flat) as ydl:
+                info = ydl.extract_info(url, download=False)
+            return [(e['title'], e.get('uploader', 'Unknown'), "YouTube", None)
+                    for e in info['entries'] if e]
+        except Exception as e:
+            logging.error(f"Error fetching YouTube playlist: {e}")
+            return []
+
+    def search_similar_tracks(self, seed_tracks, limit=10):
+        results = []
+        sample = random.sample(seed_tracks, min(3, len(seed_tracks)))
+
+        for title, artist, _, _ in sample:
+            try:
+                search_query = f"{artist} {title} audio"
+                with yt_dlp.YoutubeDL(self.ydl_opts_full) as ydl:
+                    search_results = ydl.extract_info(
+                        f"ytsearch5:{search_query}", download=False
+                    )
+                    if search_results and 'entries' in search_results:
+                        for entry in search_results['entries']:
+                            if entry:
+                                image_url = entry.get('thumbnail')
+                                results.append((
+                                    entry.get('title', 'Unknown'),
+                                    entry.get('uploader', 'Unknown'),
+                                    "YouTube",
+                                    image_url
+                                ))
+                            if len(results) >= limit:
+                                return results
+            except Exception:
+                continue
+
+        return results