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工作室风格的合成缩略图（模糊风景背景 + 左侧微笑骑手 + 右侧白色边框关键道具贴纸剪切图 + 粗体黄色/白色顶部标题）。
  • 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：完整三版本多语言上传（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