hifi-download（高保真下载）

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:

1. Create .env from template if not exists: cp ${SKILL_PATH}/.env.example ${SKILL_PATH}/.env
2. Tell user to edit ${SKILL_PATH}/.env with their credentials
3. 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:

• 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

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

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

1. Run status to check available services
2. Use lastfm_artists or lastfm_tracks to find similar music
3. Use spotify_search to look up specific tracks/albums
4. Present results to user in a clear table format
5. If user wants to download, use platform_search → platform_download

Workflow — Download Hi-Res Audio

1. Run status to confirm download service is READY
2. Search: platform_search "Album Name" -p qobuz
3. Present results with quality info
4. Download: platform_download ID -p qobuz -t album (returns download_id immediately)
5. 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
6. Tell user the files will appear in the default download directory (~/Music/Qobuz or ~/Music/TIDAL)
7. 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

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