| name | hifi-download |
| description | 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". |
MusicMaster
Music discovery (Spotify, Last.fm) and Hi-Res audio downloads (Qobuz, TIDAL) through a unified CLI.
All 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).
First-Time Setup
Step 1: Check Dependencies
bash ${SKILL_PATH}/scripts/setup.sh check
Output is key=value pairs (this is a shell script, not a Python script). If VENV=missing, run install first.
Step 2: Install
bash ${SKILL_PATH}/scripts/setup.sh install [--with-qobuz] [--with-tidal]
Creates .venv, installs core dependencies (spotipy, pylast, requests, python-dotenv), and optionally installs download backends.
Step 3: Configure Credentials
IMPORTANT: Do NOT ask the user for credentials in chat. Instead:
- Create
.env from template if not exists: cp ${SKILL_PATH}/.env.example ${SKILL_PATH}/.env
- Tell user to edit
${SKILL_PATH}/.env with their credentials
- Wait for confirmation, then verify
Alternatively, use the config script:
bash ${SKILL_PATH}/run.sh setup_config --lastfm-key=KEY [--spotify-id=ID --spotify-secret=SECRET] [--qobuz-email=EMAIL --qobuz-password=PASS]
Where to get credentials:
Step 4: Verify
bash ${SKILL_PATH}/run.sh status
Returns JSON with discovery and downloads sections showing service status (ready, disabled, not_configured, error). Only use services with "available": true.
Service Types
| Type | Services | Purpose |
|---|
| Discovery | Spotify, Last.fm | Search, recommendations, similar artists |
| Downloads | Qobuz, TIDAL | High-quality audio (FLAC, Hi-Res) |
Discovery Commands
Last.fm — Similar Artists
bash ${SKILL_PATH}/run.sh lastfm_artists "Radiohead"
Returns JSON with results array of similar artists (name, match score, URL).
Last.fm — Similar Tracks
bash ${SKILL_PATH}/run.sh lastfm_tracks "Karma Police" "Radiohead"
Arguments: track name, then artist name.
Last.fm — Taste Profile
bash ${SKILL_PATH}/run.sh lastfm_taste
Analyzes Spotify listening history and returns JSON with similar_artists and similar_tracks discovered via Last.fm.
Spotify — Search
bash ${SKILL_PATH}/run.sh spotify_search "OK Computer"
Searches Spotify catalog. Returns JSON with results array containing track/album/artist details.
Spotify — User Library
bash ${SKILL_PATH}/run.sh spotify_user tracks|artists
Gets the user's top tracks or artists from Spotify (requires OAuth). Returns JSON with results array.
Spotify — Track/Album Info
bash ${SKILL_PATH}/run.sh spotify_info SPOTIFY_URI_OR_ID
Download Commands
Search Platform Catalog
bash ${SKILL_PATH}/run.sh platform_search "Album Name" -p qobuz|tidal
Searches the download platform's catalog. Returns JSON with results array containing IDs for use with download command.
Download (async — returns immediately)
bash ${SKILL_PATH}/run.sh platform_download ID -p qobuz|tidal -t album|track
Queues 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.
To block until the download completes (legacy behavior):
bash ${SKILL_PATH}/run.sh platform_download ID -p qobuz -t album --sync
Check Download Status
bash ${SKILL_PATH}/run.sh download_status DOWNLOAD_ID
bash ${SKILL_PATH}/run.sh download_status --all
bash ${SKILL_PATH}/run.sh download_status --active
Poll 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.
Open Download Dashboard
bash ${SKILL_PATH}/run.sh download_ui
Opens a web dashboard at http://localhost:8765 showing real-time download status with progress bars. Auto-refreshes every 3 seconds.
Service Management
Disable a Service
bash ${SKILL_PATH}/run.sh disable_service spotify --reason "No account"
Enable a Service
bash ${SKILL_PATH}/run.sh enable_service spotify
Workflow — Music Discovery
- Run
status to check available services
- Use
lastfm_artists or lastfm_tracks to find similar music
- Use
spotify_search to look up specific tracks/albums
- Present results to user in a clear table format
- If user wants to download, use
platform_search → platform_download
Workflow — Download Hi-Res Audio
- Run
status to confirm download service is READY
- Search:
platform_search "Album Name" -p qobuz
- Present results with quality info
- Download:
platform_download ID -p qobuz -t album (returns download_id immediately)
- 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
- Tell user the files will appear in the default download directory (
~/Music/Qobuz or ~/Music/TIDAL)
- 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.
Error Handling
| Error | Detection | Resolution |
|---|
| Venv missing | run.sh exits with venv_missing | Run bash ${SKILL_PATH}/scripts/setup.sh install |
| Service not configured | status JSON shows "status": "not_configured" | Guide user to edit .env or run setup_config |
| Spotify OAuth expired | stderr JSON with auth error (exit 1) | Run bash ${SKILL_PATH}/run.sh spotify_auth to re-authorize |
| TIDAL token expired | status JSON shows "status": "error" for tidal | Run tiddl auth refresh or tiddl auth login in venv |
| Service disabled by user | status JSON shows "status": "disabled" | Run enable_service if user wants to re-enable |
| No results | JSON "results": [] with "total": 0 | Try different keywords or check service availability |
| Unrecoverable error | stderr JSON with "recoverable": false (exit 2) | Fix root cause (missing credentials, broken install) |
Important Notes
- Spotify requires OAuth browser flow on first use (
spotify_auth script handles this)
- TIDAL auth is managed by
tiddl CLI tool, not stored in .env
- Qobuz credentials are stored in
.env (sensitive — ensure file is in .gitignore)
- Download paths default to
~/Music/Qobuz and ~/Music/TIDAL
- Quality settings: Qobuz 27=Hi-Res 24-bit (highest), TIDAL HiFi=lossless
