akomlik/publish-youtube

ステージ4：YouTubeメタデータ、コンポジットサムネイル、多言語アップロード（/publish-youtube）

目的

完成した4K .mp4 書き出しと .fcproj プロジェクトから、完全なYouTubeリリースパッケージ（youtube_metadata.json、captions.en.srt、captions.ua.srt、captions.ru.srt、thumbnail.jpg / thumbnail_ua.jpg / thumbnail_ru.jpg）を生成し、YouTube Data API v3を使用してYouTubeに公開します。

Key Studio v2 ルール

1. フックファーストタイトル（モバイル＆アルゴリズム最適化）： デフォルトでは、好奇心を誘うナラティブフックをプライマリタイトルとします（例：Saved by Nina's Sharp Eyes! Escorting to Zumba & 21.5 mi Pollença Loop）。日付スタンプ（YYYY-MM-DD · ...）を前に置くとモバイルでタイトルが途切れるため避けてください。アーカイブ日付タイトルは title_alternatives と recordingDetails.recordingDate に保持されます。
2. 自動ピン留め言語切り替えコメント： 多言語プロジェクト（--option-b）をアップロードする場合、upload_youtube_api.py は英語マスター動画にトップレベルの言語切り替えコメントを自動投稿し、ウクライナ語版とロシア語版の動画への直接リンクを提供します。モバイル視聴者は説明文を展開せずに1タップで言語を切り替えられます。
3. ウクライナのローカルISOコード ua の厳格な使用： すべてのローカルファイル名（captions.ua.srt、voiceover_ua_part1.wav、thumbnail_ua.jpg、_UA.mp4）および Storyboard.md / youtube_metadata.json のキーでは、常に ua（UA）を使用します。upload_youtube_api.py は、YouTube Data API v3ワイヤー上でのみ自動的に "ua" -> "uk" に変換します。
4. YouTubeチャプターパーサールール： YouTubeは、動画の説明文にある 最後の 00:00 タイムスタンプブロックをシークバーチャプターのラベルとして使用します。そのため、英語の説明文内にある 🇺🇦 УКРАЇНСЬКОЮ や 🇷🇺 ПО-РУССКИ のブロックには、決して 00:00 チャプターリストを含めないでください（ローカライズされたチャプターは localizations["ua"] と localizations["ru"] 内に厳密に配置します）。
5. 必須の録画日（recordingDetails.recordingDate）： アップロードまたは更新されるすべての動画（EN、UA、RU エディションを含む）は、part="snippet,status,localizations,recordingDetails" を指定して、recordingDetails.recordingDate（YYYY-MM-DDT00:00:00.000Z、youtube_metadata.json の recording_date または YYYY-MM-DD プロジェクトフォルダプレフィックスから取得）を 必ず 設定する必要があります。
6. 環境変数の継承（ラッパー依存関係ゼロ）： お好みの環境マネージャー（例：direnv + 1Password、シェルプロファイル、ローカルの .env ファイル）を使用して GEMINI_API_KEY、GOOGLE_OAUTH_CLIENT_ID、GOOGLE_OAUTH_CLIENT_SECRET を設定し、そのシェルセッションからAntigravityを起動して、すべての子プロセスが自動的にそれらを継承するようにします。一度認証すると、~/.config/antigravity_youtube/token.json にOAuthリフレッシュトークンがキャッシュされ、将来のアップロードではプロンプトが表示されなくなります。

ステップ1：メタデータパッケージ、.srt トラック、コンポジットサムネイルの生成

generate_youtube_metadata.py を実行します：

./.venv/bin/python ./.agents/skills/publish-youtube/scripts/generate_youtube_metadata.py \
  --project-dir "./04_Project_Catalog/YEAR/<project_name>" \
  --mp4 "~/Movies/Exports/YEAR/<project_name>.mp4" \
  --thumb-mode preserve \
  --thumb-text "SAVED AT THE GATE" \
  --thumb-text-ua "ВРЯТОВАНИЙ БІЛЯ ВОРІТ" \
  --thumb-text-ru "СПАСЁН У ВОРОТ"

• サムネイルモード（--thumb-mode）：
  • preserve（デフォルト）：プロジェクトディレクトリに既存のカスタム/コンポジット thumbnail.jpg を保持し、存在しない場合はローカライズされた thumbnail_ua.jpg と thumbnail_ru.jpg を自動生成します。
  • composite_ai：--thumb-hero <hero.jpg>、--thumb-prop <prop.jpg>、--thumb-text "<3〜4単語のフック>" を指定してGemini 3 Pro Image（gemini-3-pro-image-preview）を使用し、YouTube Studioスタイルのコンポジットサムネイル（ぼかした風景背景＋左側の笑顔のライダー＋右側の白枠ステッカーカットアウトのキープロップ＋太字の黄色/白のトップ見出し）を生成します。
  • frame：--thumb-sec で指定された時間からクリーンな1920×1080フレームを抽出します。

ステップ2：YouTubeへのアップロード（en_only、option_a、または option_b）

モード1：単一動画アップロード（en_only または option_a — 日常のデフォルト）

4K英語マスター（private）をアップロードし、ローカライズされた EN/UA/RU のタイトルと説明文を設定し、captions.en.srt、captions.ua.srt、captions.ru.srt をアップロードし、thumbnail.jpg を設定します：

./.venv/bin/python ./.agents/skills/publish-youtube/scripts/upload_youtube_api.py \
  --metadata "./04_Project_Catalog/YEAR/<project_name>/youtube_metadata.json" \
  --privacy private

（MP4を再アップロードせずに、既にアップロードされた動画のメタデータ/キャプション/サムネイルを更新するには、--update-video-id <VIDEO_ID> を追加します）。

モード2：完全3エディション多言語アップロード（option_b — 特別な機会や家族のストーリー向け）

4K 🇺🇦 ウクライナ語版（_UA.mp4、未掲載、thumbnail_ua.jpg 付き）と4K 🇷🇺 ロシア語版（_RU.mp4、未掲載、thumbnail_ru.jpg 付き）を、ネイティブの吹き替えトラックと .srt キャプションと共にアップロードし、その後4K 🇺🇸 英語マスター（公開、thumbnail.jpg 付き）を、両方のローカライズ版へのクリック可能なリンクと共にアップロード/更新します：

./.venv/bin/python ./.agents/skills/publish-youtube/scripts/upload_youtube_api.py \
  --metadata "./04_Project_Catalog/YEAR/<project_name>/youtube_metadata.json" \
  --privacy private \
  --option-b