SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场hifi-download

hifi-download

通用与其它

查看项目

更新于 10-16 13:54

技能介绍

用途

hifi-download 属于 MusicMaster 技能，提供音乐发现（Spotify、Last.fm）与高保真音频下载（Qobuz、TIDAL）的统一 CLI 入口。适用于用户希望根据自己的品味寻找新音乐、检索特定曲目/专辑，并下载高品质音频文件的场景。

主要能力

音乐发现

  • Last.fm 相似艺人：bash ${SKILL_PATH}/run.sh lastfm_artists "Radiohead"，返回带匹配分数的相似艺人列表。
  • Last.fm 相似曲目：bash ${SKILL_PATH}/run.sh lastfm_tracks "Karma Police" "Radiohead"，参数为曲目名与艺人名。
  • Last.fm 品味画像：bash ${SKILL_PATH}/run.sh lastfm_taste，返回用户收听历史中的热门艺人与曲目。
  • Spotify 搜索：bash ${SKILL_PATH}/run.sh spotify_search "OK Computer"，搜索曲目、专辑与艺人。
  • Spotify 用户库：bash ${SKILL_PATH}/run.sh spotify_user tracks|artists，获取收藏曲目或关注的艺人（需 OAuth）。
  • Spotify 曲目/专辑信息：bash ${SKILL_PATH}/run.sh spotify_info SPOTIFY_URI_OR_ID。

下载高保真音频

  • 搜索下载平台目录：bash ${SKILL_PATH}/run.sh platform_search "Album Name" -p qobuz|tidal，返回供下载命令使用的 ID。
  • 下载（异步，立即返回）：bash ${SKILL_PATH}/run.sh platform_download ID -p qobuz|tidal -t album|track，在后台排队并立即返回 download_id。加 --sync 可阻塞至下载完成（旧行为）。
  • 查看下载状态：bash ${SKILL_PATH}/run.sh download_status DOWNLOAD_ID，也支持 --all、--active、--json。
  • 下载仪表盘：bash ${SKILL_PATH}/run.sh download_ui，在 http://localhost:8765 打开实时进度面板，每 3 秒自动刷新。

服务管理

  • 禁用服务：bash ${SKILL_PATH}/run.sh disable_service spotify --reason "No account"
  • 启用服务：bash ${SKILL_PATH}/run.sh enable_service spotify

使用方式

首次设置

  1. 检查依赖：bash ${SKILL_PATH}/scripts/setup.sh check（输出 key=value；若 VENV=missing 需先安装）。
  2. 安装：bash ${SKILL_PATH}/scripts/setup.sh install [--with-qobuz] [--with-tidal]，创建 .venv 并安装核心依赖（spotipy、pylast、requests、python-dotenv），可选安装下载后端。
  3. 配置凭据：不要向用户索要聊天中的凭据，而是若不存在则创建 cp ${SKILL_PATH}/.env.example ${SKILL_PATH}/.env，让用户自行编辑 .env，等待确认后验证。凭据来源：Spotify（https://developer.spotify.com/dashboard，免费）、Last.fm（https://www.last.fm/api/account/create，免费）、Qobuz（需 Studio/Sublime 订阅）、TIDAL（在 venv 中运行 tiddl auth login，不需要 .env 条目）。
  4. 验证：bash ${SKILL_PATH}/run.sh status，显示各服务 READY、DISABLED 或需设置，仅使用 READY 的服务。

降级策略

四个服务均可选，在 status 后按以下策略处理：

  • 无 Last.fm：跳过，仅用 Spotify 发现。
  • 无 Spotify：跳过，仅用 Last.fm 发现。
  • 无任何发现服务：停止并引导用户至少配置一个发现服务。
  • 无 Qobuz：自动回退到 TIDAL 下载。
  • 无 TIDAL：自动回退到 Qobuz 下载。
  • 无任何下载服务：仅发现，告知用户下载不可用。 使用回退时需告知用户正在使用哪个服务及原因。

典型工作流

音乐发现：运行 status 检查服务 → 用 lastfm_artists / lastfm_tracks 找相似音乐 → 用 spotify_search 查询特定曲目/专辑 → 以清晰表格呈现 → 如需下载走 platform_search → platform_download。

下载 Hi-Res 音频：

  • [ ] 1. 检查服务状态
  • [ ] 2. 搜索平台目录
  • [ ] 3. 向用户呈现结果
  • [ ] 4. 开始下载
  • [ ] 5. 监控进度
  • [ ] 6. 验证完成
  • [ ] 7. 报告结果

完成后按模板输出报告，包括输入、平台、音质、曲目数、总大小、下载路径、文件列表及后续操作建议（如 open "[download path]"）。文件路径与大小可从 download_status 输出及下载目录列表获取。

适用场景

  • 依据个人听歌历史或相似推荐发现新音乐。
  • 按名称检索曲目、专辑、艺人信息。
  • 下载 FLAC / Hi-Res 高保真音频并查看进度。

限制与注意事项

  • Spotify 首次使用需 OAuth 浏览器流程（由 spotify_auth 脚本处理）。
  • TIDAL 授权由 tiddl CLI 管理，不存储在 .env。
  • Qobuz 凭据存于 .env（敏感，需确保在 .gitignore 中）。
  • 下载路径默认为 ~/Music/Qobuz 与 ~/Music/TIDAL。
  • 音质设置：Qobuz 27=Hi-Res 24-bit（最高），TIDAL HiFi=无损。
  • Qobuz 需 Studio/Sublime 订阅。

常见错误处理

  • venv 缺失：run.sh 以 venv_missing 退出 → 运行 setup.sh install。
  • 服务未配置：status 显示 NOT CONFIGURED → 引导用户编辑 .env。
  • Spotify OAuth 过期：命令报认证错误 → 运行 bash ${SKILL_PATH}/run.sh spotify_auth 重新授权。
  • TIDAL token 过期：status 显示 ERROR → 在 venv 中运行 tiddl auth refresh 或 tiddl auth login。
  • 服务被用户禁用：status 显示 DISABLED → 需要时运行 enable_service。
  • 无结果：搜索返回空 → 换关键词或检查服务可用性。