MusicMaster

Music discovery (Spotify, Last.fm) and Hi-Res audio downloads (Qobuz, TIDAL) through a unified CLI.

Language

Match user's language: Respond in the same language the user uses.

All commands use bash ${SKILL_PATH}/run.sh <script> [args...], which activates the venv and runs the corresponding Python script. Output is human-readable by default; use --json where supported for structured output.

First-Time Setup

Step 1: Check Dependencies

bash ${SKILL_PATH}/scripts/setup.sh check

Output is key=value pairs. 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 with Step 4

Where to get credentials:

Spotify: https://developer.spotify.com/dashboard (free)
Last.fm: https://www.last.fm/api/account/create (free)
Qobuz: Requires Studio/Sublime subscription
TIDAL: Run tiddl auth login in venv for OAuth (no .env entry needed)

Step 4: Verify

bash ${SKILL_PATH}/run.sh status

Shows which services are READY, DISABLED, or need setup. Only use services marked READY.

Preflight Check → Fix Table

Check	Fix (macOS)	Fix (Linux)
`PYTHON=missing`	`brew install python3`	`sudo apt install python3`
`VENV=missing`	`bash ${SKILL_PATH}/scripts/setup.sh install`	Same
Core deps missing (SPOTIPY, PYLAST, etc.)	`bash ${SKILL_PATH}/scripts/setup.sh install --force`	Same
`ENV_FILE=missing`	`cp ${SKILL_PATH}/.env.example ${SKILL_PATH}/.env` then edit	Same
Spotify: NOT CONFIGURED	Edit `.env`: set `SPOTIFY_CLIENT_ID` and `SPOTIFY_CLIENT_SECRET`	Same
Last.fm: NOT CONFIGURED	Edit `.env`: set `LASTFM_API_KEY`	Same
Qobuz: NOT CONFIGURED	Edit `.env`: set `QOBUZ_EMAIL` and `QOBUZ_PASSWORD`	Same
TIDAL: NOT CONFIGURED	Run `tiddl auth login` inside the venv	Same
Spotify/Last.fm/Qobuz: ERROR (validation failed)	Check credentials in `.env` are correct, re-obtain from dashboard if needed	Same
TIDAL: ERROR (token expired)	Run `tiddl auth refresh` or `tiddl auth login` inside the venv	Same

Service Types

Type	Services	Purpose
Discovery	Spotify, Last.fm	Search, recommendations, similar artists
Downloads	Qobuz, TIDAL	High-quality audio (FLAC, Hi-Res)

Degradation Strategy

All 4 services (Spotify, Last.fm, Qobuz, TIDAL) are optional. After running status, apply this table:

Scenario	Strategy
No Last.fm	Skip & continue — Use Spotify only for discovery
No Spotify	Skip & continue — Use Last.fm only for discovery
No discovery services at all	Halt & guide — Tell user at least one discovery service is needed and guide setup
No Qobuz	Auto-fallback — Use TIDAL for downloads
No TIDAL	Auto-fallback — Use Qobuz for downloads
No download services at all	Discovery only — Inform user that downloads are unavailable, continue with discovery features only

When a fallback is used, tell the user which service is being used and why.

Discovery Commands

Last.fm — Similar Artists

bash ${SKILL_PATH}/run.sh lastfm_artists "Radiohead"

Returns a list of similar artists with match scores.

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

Returns the user's top artists and tracks from listening history.

Spotify — Search

bash ${SKILL_PATH}/run.sh spotify_search "OK Computer"

Searches Spotify catalog for tracks, albums, and artists.

Spotify — User Library

bash ${SKILL_PATH}/run.sh spotify_user tracks|artists

Gets the user's saved tracks or followed artists (requires OAuth).

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 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 a 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
bash ${SKILL_PATH}/run.sh download_status --json

Poll the status of a specific download or list all downloads. Use --active to show only pending/in_progress tasks. Use --json for structured 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

Print this checklist at the start, update as you go:

Download Progress:
- [ ] Step 1: Check service status
- [ ] Step 2: Search platform catalog
- [ ] Step 3: Present results to user
- [ ] Step 4: Start download
- [ ] Step 5: Monitor progress
- [ ] Step 6: Verify completion
- [ ] Step 7: Report results

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)
Tell user download is queued, optionally open download_ui for visual monitoring
Poll with download_status DOWNLOAD_ID until completed
Report using the completion report template below

Completion Report

After a download finishes, present this report to the user:

MusicMaster Download Complete!

Input: [album/track] - [title] by [artist]
Platform: [Qobuz/TIDAL]
Quality: [Hi-Res 24-bit / FLAC 16-bit / etc.]

Result:
- Track count: [N tracks]
- Total size: [X MB]
- Download path: [/path/to/files]

Files:
- [file1.flac] (XX MB)
- [file2.flac] (XX MB)
- ...

Next Steps:
- Open folder: open "[download path]"
- Download more: "download [another album]"

Gather file paths and sizes from the download_status output and by listing the download directory.

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` shows `NOT CONFIGURED`	Guide user to edit `${SKILL_PATH}/.env` (see Preflight Check -> Fix Table)
Spotify OAuth expired	Spotify commands fail with auth error	Run `bash ${SKILL_PATH}/run.sh spotify_auth` to re-authorize
TIDAL token expired	`status` shows `ERROR` for TIDAL	Run `tiddl auth refresh` or `tiddl auth login` in venv
Service disabled by user	`status` shows `DISABLED`	Run `enable_service` if user wants to re-enable
No results	Search returns empty	Try different keywords or check service availability

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

hifi-download