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