Back to Details

hifi-download

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

MusicMaster

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. Output is human-readable by default; use 
--json
where supported for structured output.
通过统一的CLI实现音乐发现（Spotify、Last.fm）和高分辨率音频下载（Qobuz、TIDAL）。
所有命令均使用 
bash ${SKILL_PATH}/run.sh <script> [args...]
格式，该命令会激活虚拟环境（venv）并运行对应的Python脚本。默认输出为人类可读格式；在支持的场景下可使用 
--json
参数获取结构化输出。

First-Time Setup

首次设置

Step 1: Check Dependencies

步骤1：检查依赖

bash
bash ${SKILL_PATH}/scripts/setup.sh check
Output is key=value pairs. If 
VENV=missing
, run install first.
bash
bash ${SKILL_PATH}/scripts/setup.sh check
输出为键值对格式。如果显示
VENV=missing
，请先运行安装命令。

Step 2: Install

步骤2：安装

bash
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.
bash
bash ${SKILL_PATH}/scripts/setup.sh install [--with-qobuz] [--with-tidal]
创建
.venv
虚拟环境，安装核心依赖（
spotipy
、
pylast
、
requests
、
python-dotenv
），并可选择安装下载后端。

Step 3: Configure Credentials

步骤3：配置凭证

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
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:
重要提示：请勿在对话中向用户索要凭证。请按以下步骤操作：
  1. 如果
    .env
    文件不存在，从模板创建：
    cp ${SKILL_PATH}/.env.example ${SKILL_PATH}/.env
  2. 告知用户编辑
    ${SKILL_PATH}/.env
    文件，填入个人凭证
  3. 等待用户确认后，进行验证
或者使用配置脚本：
bash
bash ${SKILL_PATH}/run.sh setup_config --lastfm-key=KEY [--spotify-id=ID --spotify-secret=SECRET] [--qobuz-email=EMAIL --qobuz-password=PASS]
凭证获取渠道：

Step 4: Verify

步骤4：验证

bash
bash ${SKILL_PATH}/run.sh status
Shows which services are READY, DISABLED, or need setup. Only use services marked READY.
bash
bash ${SKILL_PATH}/run.sh status
显示各服务的状态：READY（就绪）、DISABLED（已禁用） 或 需要设置。仅可使用标记为READY的服务。

Service Types

服务类型

TypeServicesPurpose
DiscoverySpotify, Last.fmSearch, recommendations, similar artists
DownloadsQobuz, TIDALHigh-quality audio (FLAC, Hi-Res)
类型服务平台用途
音乐发现Spotify、Last.fm搜索、推荐、相似艺人查找
音频下载Qobuz、TIDAL高品质音频（FLAC、Hi-Res）下载

Discovery Commands

音乐发现命令

Last.fm — Similar Artists

Last.fm — 相似艺人

bash
bash ${SKILL_PATH}/run.sh lastfm_artists "Radiohead"
Returns a list of similar artists with match scores.
bash
bash ${SKILL_PATH}/run.sh lastfm_artists "Radiohead"
返回带有匹配分数的相似艺人列表。

Last.fm — Similar Tracks

Last.fm — 相似曲目

bash
bash ${SKILL_PATH}/run.sh lastfm_tracks "Karma Police" "Radiohead"
Arguments: track name, then artist name.
bash
bash ${SKILL_PATH}/run.sh lastfm_tracks "Karma Police" "Radiohead"
参数：曲目名称，然后是艺人名称。

Last.fm — Taste Profile

Last.fm — 品味档案

bash
bash ${SKILL_PATH}/run.sh lastfm_taste
Returns the user's top artists and tracks from listening history.
bash
bash ${SKILL_PATH}/run.sh lastfm_taste
返回用户收听历史中的热门艺人和曲目。

Spotify — Search

Spotify — 搜索

bash
bash ${SKILL_PATH}/run.sh spotify_search "OK Computer"
Searches Spotify catalog for tracks, albums, and artists.
bash
bash ${SKILL_PATH}/run.sh spotify_search "OK Computer"
在Spotify曲库中搜索曲目、专辑和艺人。

Spotify — User Library

Spotify — 用户库

bash
bash ${SKILL_PATH}/run.sh spotify_user tracks|artists
Gets the user's saved tracks or followed artists (requires OAuth).
bash
bash ${SKILL_PATH}/run.sh spotify_user tracks|artists
获取用户收藏的曲目或关注的艺人（需要OAuth认证）。

Spotify — Track/Album Info

Spotify — 曲目/专辑信息

bash
bash ${SKILL_PATH}/run.sh spotify_info SPOTIFY_URI_OR_ID
bash
bash ${SKILL_PATH}/run.sh spotify_info SPOTIFY_URI_OR_ID

Download Commands

音频下载命令

Search Platform Catalog

搜索平台曲库

bash
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.
bash
bash ${SKILL_PATH}/run.sh platform_search "Album Name" -p qobuz|tidal
在下载平台的曲库中搜索，返回可用于下载命令的ID。

Download (async — returns immediately)

下载（异步 — 立即返回）

bash
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
bash ${SKILL_PATH}/run.sh platform_download ID -p qobuz -t album --sync
bash
bash ${SKILL_PATH}/run.sh platform_download ID -p qobuz|tidal -t album|track
将下载任务加入后台进程队列，并立即返回
download_id
。Agent可继续执行其他任务。使用
download_status
命令查询进度。
如需等待下载完成后再返回（旧版行为）：
bash
bash ${SKILL_PATH}/run.sh platform_download ID -p qobuz -t album --sync

Check Download Status

检查下载状态

bash
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.
bash
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
查询特定下载任务的状态，或列出所有下载任务。使用
--active
参数仅显示待处理/进行中的任务。使用
--json
参数获取结构化输出。

Open Download Dashboard

打开下载仪表盘

bash
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.
bash
bash ${SKILL_PATH}/run.sh download_ui
在
http://localhost:8765
打开网页仪表盘，实时显示下载状态和进度条，每3秒自动刷新。

Service Management

服务管理

Disable a Service

禁用服务

bash
bash ${SKILL_PATH}/run.sh disable_service spotify --reason "No account"
bash
bash ${SKILL_PATH}/run.sh disable_service spotify --reason "No account"

Enable a Service

启用服务

bash
bash ${SKILL_PATH}/run.sh enable_service spotify
bash
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
  1. 运行
    status
    命令检查可用服务
  2. 使用
    lastfm_artists
    或
    lastfm_tracks
    查找相似音乐
  3. 使用
    spotify_search
    查找特定曲目/专辑
  4. 以清晰的表格格式向用户展示结果
  5. 如果用户想要下载，执行
    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. Tell user download is queued, optionally open 
    download_ui
    for visual monitoring
  6. Poll with 
    download_status DOWNLOAD_ID
    until completed
  7. Report download path and file size to user
  1. 运行
    status
    命令确认下载服务处于READY状态
  2. 搜索：
    platform_search "Album Name" -p qobuz
  3. 展示包含音质信息的搜索结果
  4. 下载：
    platform_download ID -p qobuz -t album
    （立即返回download_id）
  5. 告知用户下载任务已加入队列，可选择打开
    download_ui
    进行可视化监控
  6. 使用
    download_status DOWNLOAD_ID
    轮询直至下载完成
  7. 向用户报告下载路径和文件大小

Error Handling

错误处理

ErrorDetectionResolution
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 
.env
or run 
setup_config
Spotify OAuth expiredSpotify commands fail with auth errorRun 
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 resultsSearch returns emptyTry different keywords or check service availability
错误类型检测方式解决方法
虚拟环境缺失
run.sh
执行后返回
venv_missing
运行
bash ${SKILL_PATH}/scripts/setup.sh install
服务未配置
status
显示
NOT CONFIGURED
引导用户编辑
.env
文件或运行
setup_config
命令
Spotify OAuth过期Spotify命令执行时返回认证错误运行
bash ${SKILL_PATH}/run.sh spotify_auth
重新授权
TIDAL令牌过期
status
显示TIDAL服务为
ERROR
在虚拟环境中运行
tiddl auth refresh
或
tiddl auth login
用户禁用服务
status
显示
DISABLED
如果用户需要重新启用，运行
enable_service
命令
无搜索结果搜索返回空结果尝试不同关键词或检查服务可用性

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
  • Spotify首次使用时需要通过OAuth浏览器流程授权（
    spotify_auth
    脚本会处理此流程）
  • TIDAL的认证由
    tiddl
    CLI工具管理，不存储在
    .env
    文件中
  • Qobuz凭证存储在
    .env
    文件中（敏感信息 — 确保该文件已加入
    .gitignore
    ）
  • 默认下载路径为
    ~/Music/Qobuz
    和
    ~/Music/TIDAL
  • 音质设置：Qobuz 27=24位高分辨率（最高音质），TIDAL HiFi=无损音质