/distrokid-helper

Use when コレクションの楽曲を DistroKid 配信用に準備し、distrokid-helper Chrome 拡張へ渡すローカルサーバーを起動したいとき（30-distrokid 生成 / disc 分割 / metadata.md / ジャケット 3000×3000 新規生成 / uv run yt-collection-serve 起動）。『DistroKid 準備』『配信準備』『アルバム化』『distrokid-helper』で発動。DistroKid Web への転記・アップロード操作そのものは Chrome 拡張側の責務

何ができるか

collection の MP3 を DistroKid で配信できるアルバム一式に整え、Chrome 拡張へ受け渡すスキルです。35 曲上限に合わせた disc 分割、メタデータ、3000×3000 ジャケットを生成し、検証後に collection server を起動します。DistroKid Web への転記とアップロード自体は拡張で行います。

アルバムの分割案を作りたいとき

/distrokid-helper

対象 collection の MP3、DistroKid 設定、サムネイル設定を確認して plan から順に進めます。曲数が多い場合は disc 数や 1 disc の上限を相談し、重複タイトルは確定前にユニークな名前へ直します。

配信用ファイルとジャケットを作りたいとき

uv run yt-distrokid-prepare build --spec <collection>/30-distrokid/spec.json --release-date YYYY-MM-DD <collection>
uv run yt-distrokid-prepare cover --input <collection>/30-distrokid/cover-src.png <collection>

確定した spec.json から MP3 のコピーとメタデータを生成します。リリース日が決まっていれば初回 build で指定します。ジャケットは既存サムネイルの単純リサイズではなく、ブランド設定を引き継いだ文字なしの正方形画像を新規生成してから 3000×3000 JPEG にします。

DistroKid へ受け渡したいとき

uv run yt-distrokid-prepare verify <collection>

verify が green になった後、/extension --serve --distrokid で distrokid-helper 用の collection server を起動します。表示された URL を Chrome 拡張が読み、各 disc の release.json と音源をフォーム入力に使います。アップロード完了を確認したら uv run yt-workflow-state --collection <collection> record-distrokid-submission で workflow state に人間タスクの完了を記録し、/extension --stop --distrokid で server を停止します。

つまずいたら

• MP3 がない — collection に応じて /music --generate と /music --master を先に完了してください
• DistroKid が disabled と言われる — config/channel/distrokid.json の有効化と artist 設定が必要です。songwriter は本名を含むため、設定時は案内される PII 運用を確認してください
• disc が 35 曲を超える — disc 数を増やすか 1 disc の上限を小さくして plan を作り直してください
• ジャケットが非正方形 — 中央 crop の候補を確認してから cover をやり直してください。既存ジャケットの上書きには別途確認が必要です
• 拡張で collection が見えない — single-file server ではなく distrokid 用 server を起動し直し、検出された URL と port を使ってください

リファレンス

発動フレーズ

• DistroKid 準備
• 配信準備
• アルバム化
• distrokid-helper

前後工程

• 前工程: /music --master, /music --generate, /thumbnail, /extension
• 後工程: なし
• 委譲先: なし

成果物

• 書き込む: collections/<id>/30-distrokid/spec.json, collections/<id>/30-distrokid/cover_art_3000.jpg, collections/<id>/30-distrokid/<disc>/release.json, collections/<id>/30-distrokid/README.md, collections/<id>/workflow-state.json::human_tasks.distrokid_submission.completed_at
• 読み込む: collections/<id>/02-Individual-music/*.mp3, collections/<id>/10-assets/main.png, config/channel/distrokid.json

想定 API call 数

• 上限 / 承認: 画像生成前に confirm_cost の y/N 確認あり（-y でスキップ）。既存ジャケットを再利用すれば課金 call は 0。

前提

以下の 1〜3 を確認し、満たさなければ案内して停止する。4 は停止条件ではなく、未設定時に 2 択の分岐を提示する:

1. 対象コレクションの 02-Individual-music/*.mp3 が 1 件以上存在すること。無ければ前工程（/music --generate → /music --master、または /music --generate）を案内して停止する
2. config/channel/distrokid.json の distrokid.enabled が true で、distrokid.profile.artist が配信アーティスト名になっていること。false / 未設定のチャンネルでは本スキルを使わず、設定方法はユーザーに確認する
3. 対象チャンネルで load_skill_config("thumbnail") を実行し、ジャケット生成に使う実効設定が検証を通ること。配布済み既定値に任意の config/skills/thumbnail.yaml override をマージするため、override がなくても続行し、不要な設定ファイルを作成しない。実効設定の image_generation.provider が gemini / openai / codex のいずれかで、以下のプロンプト組み立てで参照する背景・スタイル項目が文字列であることも確認する。ConfigError（不正な YAML や設定値など）またはこの確認の失敗時は修正対象を案内して停止し、既定値だけに切り替えて続行しない
4. config/channel/distrokid.json の distrokid.profile.songwriter（作曲者の本名。{ "first": "...", "last": "..." } の nested 構造、middle は任意）が設定されているか確認する。schema 上は任意のため未設定でも停止しないが、未設定のまま進めると Chrome 拡張のフォーム一括入力で songwriter（本名）欄だけが空になり、DistroKid Web で曲ごとの手入力が必要になる。未設定の場合は plan / build（ステップ 1 / 4）に進む前に AskUserQuestion で以下の 2 択を提示し、選択に従う:
   • 設定して進める — config/channel/distrokid.json に profile.songwriter を追記してから続行する。songwriter は PII（本名）のため、追記する前に必ず references/pii-gitignore.md を Read し、記入例とあわせてリポジトリの公開範囲・.gitignore 運用を確認する
   • 手入力を了承して進める — 未設定のまま続行し、DistroKid Web フォームで songwriter 欄を曲ごとに手入力することを了承する

DistroKid Web への転記・アップロードは Chrome 拡張（/extension で導入する distrokid-helper）の責務であり、本スキルの前提には含まない。