hifi-download

MusicMaster

統一された CLI から、音楽の発見（Spotify、Last.fm）やハイレゾ音源のダウンロード（Qobuz、TIDAL）を行えます。

言語

ユーザーの言語に合わせる：ユーザーが使用する言語で応答してください。

すべてのコマンドは bash ${SKILL_PATH}/run.sh <script> [args...] を使用します。これにより venv が有効になり、対応する Python スクリプトが実行されます。出力はデフォルトで人間が読みやすい形式です。構造化された出力を利用できる場合は --json を使用してください。

初回セットアップ

ステップ 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：認証情報を設定する

重要：チャットでユーザーに認証情報を尋ねないでください。代わりに：

1. 存在しない場合は、テンプレートから .env を作成します：cp ${SKILL_PATH}/.env.example ${SKILL_PATH}/.env
2. 認証情報を入力するため、${SKILL_PATH}/.env を編集するようユーザーに伝えます
3. 確認を待ってから、ステップ 4 で検証します

認証情報の取得先：

• Spotify：https://developer.spotify.com/dashboard（無料）
• Last.fm：https://www.last.fm/api/account/create（無料）
• Qobuz：Studio／Sublime のサブスクリプションが必要です
• TIDAL：OAuth 用に venv 内で tiddl auth login を実行します（.env への記入は不要です）

ステップ 4：検証する

bash ${SKILL_PATH}/run.sh status

各サービスが READY、DISABLED、または 設定が必要 のいずれかであることを示します。READY と表示されたサービスのみを使用してください。

事前確認 → 修正表

確認項目	修正方法（macOS）	修正方法（Linux）
PYTHON=missing	brew install python3	sudo apt install python3
VENV=missing	bash ${SKILL_PATH}/scripts/setup.sh install	同上
コア依存関係が不足（SPOTIPY、PYLAST など）	bash ${SKILL_PATH}/scripts/setup.sh install --force	同上
ENV_FILE=missing	cp ${SKILL_PATH}/.env.example ${SKILL_PATH}/.env を実行してから編集	同上
Spotify：未設定	.env を編集し、SPOTIFY_CLIENT_ID と SPOTIFY_CLIENT_SECRET を設定	同上
Last.fm：未設定	.env を編集し、LASTFM_API_KEY を設定	同上
Qobuz：未設定	.env を編集し、QOBUZ_EMAIL と QOBUZ_PASSWORD を設定	同上
TIDAL：未設定	venv 内で tiddl auth login を実行	同上
Spotify／Last.fm／Qobuz：エラー（検証失敗）	.env の認証情報が正しいか確認し、必要に応じてダッシュボードから再取得	同上
TIDAL：エラー（トークンの有効期限切れ）	venv 内で tiddl auth refresh または tiddl auth login を実行	同上

サービスの種類

種類	サービス	目的
発見	Spotify、Last.fm	検索、おすすめ、類似アーティスト
ダウンロード	Qobuz、TIDAL	高音質オーディオ（FLAC、ハイレゾ）

機能縮退時の方針

4 つのサービス（Spotify、Last.fm、Qobuz、TIDAL）はすべてオプションです。status の実行後、この表に従ってください：

状況	方針
Last.fm が利用できない	スキップして続行 — 発見には Spotify のみを使用します
Spotify が利用できない	スキップして続行 — 発見には Last.fm のみを使用します
発見サービスがまったく利用できない	停止して案内 — 発見サービスが少なくとも 1 つ必要であることをユーザーに伝え、セットアップを案内します
Qobuz が利用できない	自動フォールバック — ダウンロードには TIDAL を使用します
TIDAL が利用できない	自動フォールバック — ダウンロードには Qobuz を使用します
ダウンロードサービスがまったく利用できない	発見のみ — ダウンロードは利用できないことをユーザーに伝え、発見機能のみを続行します

フォールバックを使用する場合は、使用するサービスとその理由をユーザーに伝えてください。

発見コマンド

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 のカタログからトラック、アルバム、アーティストを検索します。

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 を返します。エージェントはほかの作業を続けられます。進行状況を確認するには、download_status を使用します。

ダウンロードが完了するまで待機する場合（従来の動作）：

bash ${SKILL_PATH}/run.sh platform_download ID -p qobuz -t album --sync

ダウンロード状況を確認

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 を使用します。

ダウンロードダッシュボードを開く

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. status を実行して、利用可能なサービスを確認します
2. lastfm_artists または lastfm_tracks を使って、似た音楽を探します
3. spotify_search を使って、特定のトラック／アルバムを検索します
4. 結果を見やすい表形式でユーザーに提示します
5. ユーザーがダウンロードを希望する場合は、platform_search → platform_download を使用します

ワークフロー — ハイレゾ音源をダウンロード

最初にこのチェックリストを表示し、作業の進行に合わせて更新してください。

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

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. 以下の完了報告テンプレートを使って報告します

完了報告

ダウンロードが完了したら、この報告をユーザーに提示してください。

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]"

download_status の出力を確認し、ダウンロードディレクトリを一覧表示して、ファイルパスとサイズを取得します。

エラー処理

エラー	検出方法	解決方法
Venv が見つからない	run.sh が venv_missing で終了する	bash ${SKILL_PATH}/scripts/setup.sh install を実行します
サービスが設定されていない	status に NOT CONFIGURED と表示される	${SKILL_PATH}/.env を編集するようユーザーに案内します（「事前確認 -> 修正表」を参照）
Spotify OAuth の有効期限切れ	Spotify コマンドが認証エラーで失敗する	再認証するには bash ${SKILL_PATH}/run.sh spotify_auth を実行します
TIDAL トークンの有効期限切れ	status で TIDAL が ERROR と表示される	venv 内で tiddl auth refresh または tiddl auth login を実行します
ユーザーによってサービスが無効化されている	status に DISABLED と表示される	ユーザーが再度有効にしたい場合は、enable_service を実行します
検索結果がない	検索結果が空	キーワードを変えるか、サービスが利用可能か確認します

重要な注意事項

• Spotify を初めて使う際は OAuth のブラウザフローが必要です（spotify_auth スクリプトが処理します）
• TIDAL の認証は tiddl CLI ツールで管理され、.env には保存されません
• Qobuz の認証情報は .env に保存されます（機密情報のため、ファイルが .gitignore に含まれていることを確認してください）
• ダウンロード先のデフォルトは ~/Music/Qobuz と ~/Music/TIDAL です
• 音質設定：Qobuz 27＝ハイレゾ 24-bit（最高音質）、TIDAL HiFi＝ロスレス