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。

主要 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 會自動在英文主影片上張貼一則頂層語言切換評論，直接連結到烏克蘭文與俄文配音版本，讓行動裝置觀眾無需展開說明即可一鍵存取。
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、shell 設定檔或本機 .env 檔案）設定 GEMINI_API_KEY、GOOGLE_OAUTH_CLIENT_ID 與 GOOGLE_OAUTH_CLIENT_SECRET，並從該 shell 階段啟動 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：使用 Gemini 3 Pro Image（gemini-3-pro-image-preview）搭配 --thumb-hero <hero.jpg>、--thumb-prop <prop.jpg> 與 --thumb-text "<3-4 字鉤子>"，產生類似 YouTube Studio 風格的合成縮圖（模糊風景背景 + 左側微笑騎士 + 右側白色邊框貼紙裁切關鍵道具 + 粗體黃/白頂部標題）。
  • frame：在 --thumb-sec 指定的時間點提取一張乾淨的 1920×1080 畫格。

步驟 2：上傳至 YouTube（僅英文、選項 A 或選項 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）與 🇷🇺 俄文版本（_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