yt-music

YouTube Music スキル

スキルのルートから同梱のスクリプトを実行します。

• scripts/helper.py：検索、ライブラリ、プレイリスト、歌詞、評価、アカウント
• scripts/player.py：再生クライアントとデーモンの管理
• scripts/player_daemon.py：永続的な Playwright ブラウザデーモン
• ランタイムの状態は ./.yt-music/ 内にローカル保存されます
• 再生には ./.yt-music/playwright-profile 内の Playwright 管理の専用ブラウザプロファイルを使用します

ワークフローの振り分け

複数の手順を含む処理や組み合わせたフローでは、場当たり的に処理を組み立てるのではなく、ユーザーをワークフローファイルに誘導します。

ユーザーの意図	ワークフローファイル
初回セットアップ、認証の期限切れ、デーモンが起動していない	Workflows/Setup.md
「X を再生して／Y のような曲を再生して／音楽を探して」	Workflows/PlayDiscover.md
「…のプレイリストを作って」「チャートを保存して」、アーティストの隠れた名曲	Workflows/BuildPlaylist.md
認証エラー、デーモンのタイムアウト、無音再生、Cookie の問題	Workflows/DiagnoseAuth.md
「テストを実行して」、編集後のスクリプトを検証、CI のスモークテスト	Workflows/RunTests.md

単発のリクエスト（検索を 1 回、評価を 1 回、playlist get を 1 回）はその場で処理します。ワークフローは不要です。

判断フロー

1. ユーザーが ID ではなく名前を指定した場合は、まず検索します。
2. 認証が必要な操作では、まず auth check を実行します。
3. 認証情報がない場合は、認証案内モードに切り替え、処理を続行しないでください。
4. 認証に成功した後にのみ、元のコマンドを実行します。
5. JSON は短い表またはリストに整形します。

ID の解決

検索を使って videoId、browseId、または playlistId を解決します。

uv run --with yt-musicapi python scripts/helper.py search "<query>" --type songs --limit 5
uv run --with yt-musicapi python scripts/helper.py search "<query>" --type artists --limit 3
uv run --with yt-musicapi python scripts/helper.py search "<query>" --type albums --limit 3

検索結果が曖昧な場合は、どれを希望するかユーザーに尋ねてください。

認証

library、playlist、rate、subscribe、home、history、taste、upload、または auth account を実行する前に、認証を確認します。

uv run --with yt-musicapi python scripts/helper.py auth check

認証情報がない場合は、要求された操作をまだ続行しないでください。

次のいずれかを提供するよう、ユーザーにはっきり案内してください。

• ログイン済みの music.youtube.com へのリクエストからコピーした Cookie 文字列
• cookies JSON のエクスポートファイルのパス

これは必須ルールです。

• 「認証情報がありません」とだけ伝えないでください
• シェルエラーを表示しただけで終わらないでください
• 「まずログインしてください」のような曖昧な質問をしないでください
• 次に必要な具体的な情報、つまり Cookie 文字列または cookies JSON ファイルのパスを尋ねてください
• 可能であればユーザーの言語に合わせてください。言語が不明な場合は、簡潔な英語を使用してください
• 以下の英語テンプレートはデフォルトとして扱い、ユーザーの言語に合わせて翻訳または調整してください

次のフローに従ってください。

1. ライブラリ、プレイリスト、アカウント、アップロード、または完全な再生機能にアクセスするには、事前に認証が必要であることをユーザーに伝えます。
2. ログイン済みのブラウザで music.youtube.com を開くよう案内します。
3. 次の 2 つの方法を提示します。
   • Cookie 文字列：DevTools を開き、Network で /browse をフィルタリングして再読み込みし、一致するリクエストを開いて Cookie ヘッダーの値をコピーし、返信してもらいます
   • Cookies JSON：Cookie 拡張機能を使って music.youtube.com の Cookie をエクスポートし、ファイルパスを返信してもらいます
4. ユーザーが Cookie 文字列または JSON ファイルのパスを返信したら、auth setup を実行します。
5. auth setup が成功した後、元のコマンドを再試行します。

ユーザー向けの推奨デフォルト文面：

You need to sign in to YouTube Music before I can access your library, playlists, account, uploads, or full playback.

Please send me one of these:
1. A Cookie string
2. A cookies JSON file path

Cookie 文字列の手順：

Open a logged-in music.youtube.com page
Open DevTools -> Network
Filter /browse and reload the page
Open any matching request
Copy the Cookie request header value
Send the full Cookie string back to me

Cookies JSON の手順：

Use a cookie export extension such as Cookie-Editor on music.youtube.com
Export cookies as JSON
Save the exported file locally
Send me the file path

セットアップコマンド：

uv run --with yt-musicapi python scripts/helper.py auth setup --cookie '<cookie string>'
uv run --with yt-musicapi python scripts/helper.py auth setup --cookies-file /path/to/cookies.json

よく使うコマンド

uv run --with yt-musicapi python scripts/helper.py search "<query>" [--type songs|artists|albums|playlists|videos]
uv run --with yt-musicapi python scripts/helper.py library playlists
uv run --with yt-musicapi python scripts/helper.py playlist get <playlistId>
uv run --with yt-musicapi python scripts/helper.py playlist create --title "<name>"
uv run --with yt-musicapi python scripts/helper.py playlist add <playlistId> <videoId...>
uv run --with yt-musicapi python scripts/helper.py lyrics <videoId>
uv run --with yt-musicapi python scripts/helper.py related <videoId>
uv run --with yt-musicapi python scripts/helper.py rate <videoId> LIKE|DISLIKE|INDIFFERENT
uv run --with yt-musicapi python scripts/helper.py charts [--country CN|US|KR|JP|ZZ]

コマンドの完全なリファレンス：references/commands.md

再生

再生は、常時起動する Playwright ブラウザデーモンを通じて実行されます。最初の再生コマンドで専用のブラウザーウィンドウが自動的に起動し、その後の open、play、pause、next、prev、seek、volume、status コマンドでも同じウィンドウが再利用されます。

uv run --with playwright python scripts/player.py daemon-start
uv run --with playwright python scripts/player.py open <videoId>
uv run --with playwright python scripts/player.py play
uv run --with playwright python scripts/player.py pause
uv run --with playwright python scripts/player.py next
uv run --with playwright python scripts/player.py prev
uv run --with playwright python scripts/player.py status
uv run --with playwright python scripts/player.py volume <0-100>
uv run --with playwright python scripts/player.py seek <seconds>
uv run --with playwright python scripts/player.py daemon-status
uv run --with playwright python scripts/player.py daemon-stop

重要な動作：

• デーモンは、./.yt-music/playwright-profile に専用の永続ブラウザープロファイルを起動します
• 初回起動時は、そのブラウザーウィンドウで music.youtube.com にサインインする必要がある場合があります
• Chrome を起動したり、デバッグポートを手動で開いたりする必要はありません
• open <videoId> でページが読み込まれても再生が一時停止状態のままの場合、自動再生がブロックされた可能性があります。その場合は、デーモンが管理するウィンドウで再生ボタンを一度クリックする必要があります
• daemon-status は、新しいブラウザーを起動せずにバックグラウンドのブラウザーが稼働中かどうかを確認します

再生コマンドが失敗した場合は、まず次の点を確認してください。

• デーモンが管理するブラウザーウィンドウがまだ開いている
• リクエストされたトラックの再生にサインインが必要な場合、そのブラウザーウィンドウで music.youtube.com にサインインしている
• リクエストされた曲のページが、そのブラウザーセッションで実際に再生できる
• ./.yt-music/player-daemon.log に起動エラーや Playwright のエラーが記録されていない

出力

• 検索結果：タイトル、アーティスト、アルバム、再生時間を含む番号付きの表
• プレイリストのトラック：タイトル、アーティスト、アルバムを含む番号付きリスト
• 歌詞：プレーンテキストを出力します
• 再生：▶ {title} — {artist} ({position} / {duration})
• エラー：原因と次の操作を示します

成功後は、再生、プレイリストへの追加、歌詞の表示、関連トラックの取得など、自然な次のステップを1つ提案してください。

注意事項

蓄積された教訓。このスキルで最も情報密度の高いセクションです。フローが分かりにくい形で失敗したら、随時追加してください。

• SAPISID Cookie の注意点。 auth setup --cookie は、SAPISID を time および music.youtube.com と組み合わせて SHA1 ハッシュ化し、API 認証ヘッダーを導出します。ユーザーが Cookie の行を 1 つだけ貼り付けた場合（Cookie: ヘッダー全体ではない場合）、スクリプトは SAPISID not found で終了します。必ず単一の Cookie ペアではなく、Cookie リクエストヘッダーの値全体を求めてください。フォールバックとして __Secure-3PAPISID も使用できます。
• Cookie は気付かないうちに期限切れになります。 Google はセッション Cookie をローテーションします。ファイルが存在するため、auth check は引き続き ok を返しますが、次の認証済み呼び出しは 401 になります。その場合は、auth remove を実行してから Workflows/Setup.md の手順 2 をやり直してください。むやみに再試行しないでください。
• デーモン初回起動時の自動再生ブロック。 Chrome のメディアポリシーにより、ユーザーがページを一度操作するまで自動再生がブロックされます。最初の player.py open <id> では、ページが paused 状態で読み込まれることがあります。デーモン管理のウィンドウ内で一度再生ボタンをクリックするようユーザーに伝えてください。操作がプロファイルに保持されるため、以降は自動再生されます。
• クラッシュ後のプロファイルロック。 以前にデーモンがクラッシュした場合、./.yt-music/playwright-profile/SingletonLock によって再起動がブロックされることがあります。daemon-stop を実行してからロックファイルを削除すれば、ログイン状態を失わずに復旧できます。
• playlist add-playlist にはソースへの所有権またはアクセス権が必要です。 ユーザー間でプレイリストを複製しようとすると、actions に差分が表示されずに失敗します。成功を報告する前に、ユーザーが --source-playlist の所有者であるか、アクセス権を持っていることを確認してください。
• get_album にはプレイリスト ID ではなくブラウズ ID が必要です。 ヘルパーは get_album_browse_id を介して OLAK*／PL* ID を自動変換しますが、ユーザーが正しいフラグを指定した場合に限ります。album に videoId を渡さないでください。
• charts --country ZZ は「グローバル」を意味します。 誤記ではありません。これがデフォルトです。地域別チャートには ISO 3166-1 alpha-2 コード（BR、US、KR、JP）を使用してください。
• related が空を返すことがあります。 再生回数の少ないトラックには、関連プレイリストのエントリーがありません。「見つかりませんでした」とユーザーに伝える代わりに、ラジオミックスとして watch <videoId> --limit 10 にフォールバックしてください。
• playlist remove には videoId だけではなく、トラックオブジェクト全体が必要です。 ヘルパーはまず get_playlist を使ってトラックを検索します。to_remove が空の場合、スクリプトはエラーではなく not_found, removed: 0 を返します。その内容をそのままユーザーに伝えてください。指定されたトラック ID がプレイリストに含まれていない可能性があります。
• YT_MUSIC_DATA_DIR はデフォルトの保存先を上書きします。 認証ファイルが予期しない場所にあるという報告を受けた場合、この環境変数が設定されているか確認してください。デフォルトは <skill-root>/.yt-music/ です。

例

例 1 — クイック検索と再生（どちらも認証は不要です）。

User: "Play Bohemian Rhapsody."
→ search "Bohemian Rhapsody" --type songs --limit 5
→ confirm pick with user if ambiguous
→ player.py open <videoId>
→ player.py status
→ offer: lyrics, related, save to playlist

例 2 — ブラジルのチャートプレイリストを作成します。

User: "Save this week's BR top 50 as a playlist."
→ route to Workflows/BuildPlaylist.md (Mode C)
→ auth check (required for playlist create/add)
→ charts --country BR
→ extract top 50 videoIds
→ playlist create --title "BR Top 50 — <date>" --privacy PRIVATE
→ playlist add <playlistId> <videoIds...>

例 3 — フローの途中での認証失敗。

User: "Add this track to my Liked playlist."
→ playlist add returns 401
→ route to Workflows/DiagnoseAuth.md (Symptom 2)
→ auth remove → Workflows/Setup.md step 2
→ retry original playlist add