Hifi Download

1---
2name: hifi-download
3description: Discover music, get personalized recommendations, and download high-fidelity audio files. Use when user wants to find new music based on their taste, search for songs/albums/artists, get recommendations similar to artists they like, or download lossless audio (FLAC/Hi-Res) from Qobuz or TIDAL. Trigger phrases include "find music like", "recommend songs", "download album", "lossless", "Hi-Res", "FLAC", "music discovery", "similar artists", "setup music".
4---
5 
6# MusicMaster
7 
8Music discovery (Spotify, Last.fm) and Hi-Res audio downloads (Qobuz, TIDAL) through a unified CLI.
9 
10All commands use `bash ${SKILL_PATH}/run.sh <script> [args...]`, which activates the venv and runs the corresponding Python script. All scripts output structured JSON to stdout by default. Use `--format text` for human-readable output. Errors are JSON on stderr with exit code 1 (recoverable) or 2 (unrecoverable).
11 
12## First-Time Setup
13 
14### Step 1: Check Dependencies
15 
16```bash
17bash ${SKILL_PATH}/scripts/setup.sh check
18```
19 
20Output is key=value pairs (this is a shell script, not a Python script). If `VENV=missing`, run install first.
21 
22### Step 2: Install
23 
24```bash
25bash ${SKILL_PATH}/scripts/setup.sh install [--with-qobuz] [--with-tidal]
26```
27 
28Creates `.venv`, installs core dependencies (`spotipy`, `pylast`, `requests`, `python-dotenv`), and optionally installs download backends.
29 
30### Step 3: Configure Credentials
31 
32**IMPORTANT**: Do NOT ask the user for credentials in chat. Instead:
331. Create `.env` from template if not exists: `cp ${SKILL_PATH}/.env.example ${SKILL_PATH}/.env`
342. Tell user to edit `${SKILL_PATH}/.env` with their credentials
353. Wait for confirmation, then verify
36 
37Alternatively, use the config script:
38 
39```bash
40bash ${SKILL_PATH}/run.sh setup_config --lastfm-key=KEY [--spotify-id=ID --spotify-secret=SECRET] [--qobuz-email=EMAIL --qobuz-password=PASS]
41```
42 
43**Where to get credentials:**
44- Spotify: https://developer.spotify.com/dashboard (free)
45- Last.fm: https://www.last.fm/api/account/create (free)
46- Qobuz: Requires Studio/Sublime subscription
47- TIDAL: Run `tiddl auth login` in venv for OAuth
48 
49### Step 4: Verify
50 
51```bash
52bash ${SKILL_PATH}/run.sh status
53```
54 
55Returns JSON with `discovery` and `downloads` sections showing service status (`ready`, `disabled`, `not_configured`, `error`). **Only use services with `"available": true`.**
56 
57## Service Types
58 
59| Type | Services | Purpose |
60|------|----------|---------|
61| Discovery | Spotify, Last.fm | Search, recommendations, similar artists |
62| Downloads | Qobuz, TIDAL | High-quality audio (FLAC, Hi-Res) |
63 
64## Discovery Commands
65 
66### Last.fm — Similar Artists
67 
68```bash
69bash ${SKILL_PATH}/run.sh lastfm_artists "Radiohead"
70```
71 
72Returns JSON with `results` array of similar artists (name, match score, URL).
73 
74### Last.fm — Similar Tracks
75 
76```bash
77bash ${SKILL_PATH}/run.sh lastfm_tracks "Karma Police" "Radiohead"
78```
79 
80Arguments: track name, then artist name.
81 
82### Last.fm — Taste Profile
83 
84```bash
85bash ${SKILL_PATH}/run.sh lastfm_taste
86```
87 
88Analyzes Spotify listening history and returns JSON with `similar_artists` and `similar_tracks` discovered via Last.fm.
89 
90### Spotify — Search
91 
92```bash
93bash ${SKILL_PATH}/run.sh spotify_search "OK Computer"
94```
95 
96Searches Spotify catalog. Returns JSON with `results` array containing track/album/artist details.
97 
98### Spotify — User Library
99 
100```bash
101bash ${SKILL_PATH}/run.sh spotify_user tracks|artists
102```
103 
104Gets the user's top tracks or artists from Spotify (requires OAuth). Returns JSON with `results` array.
105 
106### Spotify — Track/Album Info
107 
108```bash
109bash ${SKILL_PATH}/run.sh spotify_info SPOTIFY_URI_OR_ID
110```
111 
112## Download Commands
113 
114### Search Platform Catalog
115 
116```bash
117bash ${SKILL_PATH}/run.sh platform_search "Album Name" -p qobuz|tidal
118```
119 
120Searches the download platform's catalog. Returns JSON with `results` array containing IDs for use with download command.
121 
122### Download (async — returns immediately)
123 
124```bash
125bash ${SKILL_PATH}/run.sh platform_download ID -p qobuz|tidal -t album|track
126```
127 
128Queues the download in a background process and returns JSON with `download_id` immediately. The agent is free to continue other work. Use `download_status` to poll progress.
129 
130To block until the download completes (legacy behavior):
131 
132```bash
133bash ${SKILL_PATH}/run.sh platform_download ID -p qobuz -t album --sync
134```
135 
136### Check Download Status
137 
138```bash
139bash ${SKILL_PATH}/run.sh download_status DOWNLOAD_ID
140bash ${SKILL_PATH}/run.sh download_status --all
141bash ${SKILL_PATH}/run.sh download_status --active
142```
143 
144Poll the status of a specific download or list all downloads. Use `--active` to show only pending/in_progress tasks. Output is JSON by default; use `--format text` for human-readable output.
145 
146### Open Download Dashboard
147 
148```bash
149bash ${SKILL_PATH}/run.sh download_ui
150```
151 
152Opens a web dashboard at `http://localhost:8765` showing real-time download status with progress bars. Auto-refreshes every 3 seconds.
153 
154## Service Management
155 
156### Disable a Service
157 
158```bash
159bash ${SKILL_PATH}/run.sh disable_service spotify --reason "No account"
160```
161 
162### Enable a Service
163 
164```bash
165bash ${SKILL_PATH}/run.sh enable_service spotify
166```
167 
168## Workflow — Music Discovery
169 
1701. Run `status` to check available services
1712. Use `lastfm_artists` or `lastfm_tracks` to find similar music
1723. Use `spotify_search` to look up specific tracks/albums
1734. Present results to user in a clear table format
1745. If user wants to download, use `platform_search` → `platform_download`
175 
176## Workflow — Download Hi-Res Audio
177 
1781. Run `status` to confirm download service is READY
1792. Search: `platform_search "Album Name" -p qobuz`
1803. Present results with quality info
1814. Download: `platform_download ID -p qobuz -t album` (returns download_id immediately)
1825. **Immediately** open the download dashboard with `download_ui` so the user can see real-time progress — **run this command in the background** (use `run_in_background: true` in Bash) since the dashboard is a long-running server process that will block otherwise
1836. Tell user the files will appear in the default download directory (`~/Music/Qobuz` or `~/Music/TIDAL`)
1847. **Do NOT poll `download_status` in a loop.** The dashboard handles progress visualization — move on immediately after opening it. Only poll on behalf of the user if they explicitly ask you to check for them.
185 
186## Error Handling
187 
188| Error | Detection | Resolution |
189|-------|-----------|------------|
190| Venv missing | `run.sh` exits with `venv_missing` | Run `bash ${SKILL_PATH}/scripts/setup.sh install` |
191| Service not configured | `status` JSON shows `"status": "not_configured"` | Guide user to edit `.env` or run `setup_config` |
192| Spotify OAuth expired | stderr JSON with auth error (exit 1) | Run `bash ${SKILL_PATH}/run.sh spotify_auth` to re-authorize |
193| TIDAL token expired | `status` JSON shows `"status": "error"` for tidal | Run `tiddl auth refresh` or `tiddl auth login` in venv |
194| Service disabled by user | `status` JSON shows `"status": "disabled"` | Run `enable_service` if user wants to re-enable |
195| No results | JSON `"results": []` with `"total": 0` | Try different keywords or check service availability |
196| Unrecoverable error | stderr JSON with `"recoverable": false` (exit 2) | Fix root cause (missing credentials, broken install) |
197 
198## Important Notes
199 
200- Spotify requires OAuth browser flow on first use (`spotify_auth` script handles this)
201- TIDAL auth is managed by `tiddl` CLI tool, not stored in `.env`
202- Qobuz credentials are stored in `.env` (sensitive — ensure file is in `.gitignore`)
203- Download paths default to `~/Music/Qobuz` and `~/Music/TIDAL`
204- Quality settings: Qobuz 27=Hi-Res 24-bit (highest), TIDAL HiFi=lossless
205