akomlik/publish-youtube

Estágio 4: Metadados do YouTube, Miniatura Composta e Upload Multilíngue (/publish-youtube)

Propósito

Converte qualquer exportação .mp4 4K finalizada e projeto .fcproj em um pacote completo de lançamento para o YouTube (youtube_metadata.json, captions.en.srt, captions.ua.srt, captions.ru.srt e thumbnail.jpg / thumbnail_ua.jpg / thumbnail_ru.jpg) e o publica no YouTube usando a YouTube Data API v3.

Principais Regras do Studio v2

1. Títulos com Gancho Primeiro (Otimizados para Mobile e Algoritmo): Use por padrão o gancho narrativo de alta curiosidade como título principal (ex.: Saved by Nina's Sharp Eyes! Escorting to Zumba & 21.5 mi Pollença Loop) em vez de prefixar com carimbos de data (YYYY-MM-DD · ...), que são truncados em dispositivos móveis. Títulos com data são preservados em title_alternatives e recordingDetails.recordingDate.
2. Comentário Automático de Seletor de Idioma Fixado: Ao fazer upload de projetos multilíngues (--option-b), upload_youtube_api.py publica automaticamente um comentário de seletor de idioma no nível superior no mestre em inglês, com links diretos para as edições dubladas em ucraniano e russo, para que os espectadores mobile tenham acesso com um clique sem precisar expandir a descrição.
3. Código ISO Estrito ua para Ucrânia Localmente: Sempre use ua (UA) em todos os nomes de arquivo locais (captions.ua.srt, voiceover_ua_part1.wav, thumbnail_ua.jpg, _UA.mp4) e chaves em Storyboard.md / youtube_metadata.json. upload_youtube_api.py traduz automaticamente "ua" -> "uk" apenas na comunicação com a YouTube Data API v3.
4. Regra do Analisador de Capítulos do YouTube: O YouTube usa o último bloco de timestamp 00:00 na descrição de um vídeo para rotular os capítulos da barra de progresso. Portanto, blocos inline 🇺🇦 УКРАЇНСЬКОЮ e 🇷🇺 ПО-РУССКИ dentro da descrição em inglês nunca devem incluir listas de capítulos 00:00 (capítulos localizados pertencem estritamente a localizations["ua"] e localizations["ru"]).
5. Data de Gravação Obrigatória (recordingDetails.recordingDate): Todo vídeo enviado ou atualizado (incluindo edições EN, UA e RU) DEVE definir recordingDetails.recordingDate (YYYY-MM-DDT00:00:00.000Z, derivado de recording_date em youtube_metadata.json ou do prefixo YYYY-MM-DD da pasta do projeto) via part="snippet,status,localizations,recordingDetails".
6. Herança de Ambiente (Dependências Zero de Wrapper): Defina GEMINI_API_KEY, GOOGLE_OAUTH_CLIENT_ID e GOOGLE_OAUTH_CLIENT_SECRET usando seu gerenciador de ambiente preferido (ex.: direnv + 1Password, perfil de shell ou um arquivo .env local) e inicie o Antigravity a partir dessa sessão de shell para que todos os processos filhos os herdem automaticamente. Após a autorização inicial, ~/.config/antigravity_youtube/token.json armazena em cache o token de atualização OAuth para uploads futuros sem necessidade de interação.

Passo 1: Gerar Pacote de Metadados, Faixas .srt e Miniatura Composta

Execute 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 "СПАСЁН У ВОРОТ"

• Modos de Miniatura (--thumb-mode):
  • preserve (padrão): Mantém uma thumbnail.jpg personalizada/composta existente no diretório do projeto e gera automaticamente thumbnail_ua.jpg e thumbnail_ru.jpg localizadas, se ausentes.
  • composite_ai: Usa o Gemini 3 Pro Image (gemini-3-pro-image-preview) com --thumb-hero <hero.jpg>, --thumb-prop <prop.jpg> e --thumb-text "<GANCHO DE 3-4 PALAVRAS>" para gerar uma miniatura composta no estilo YouTube Studio (fundo cênico desfocado + ciclista sorrindo à esquerda + adesivo de recorte com borda branca do objeto principal à direita + manchete superior em negrito amarelo/branco).
  • frame: Extrai um frame limpo de 1920×1080 em --thumb-sec.

Passo 2: Upload para o YouTube (en_only, option_a ou option_b)

Modo 1: Upload de Vídeo Único (en_only ou option_a — Padrão Diário)

Faz upload do Mestre em Inglês 4K (private), define títulos e descrições localizados em EN/UA/RU, envia captions.en.srt, captions.ua.srt e captions.ru.srt, e define 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

(Para atualizar metadados/legendas/miniatura em um vídeo já enviado sem reenviar o MP4, adicione --update-video-id <VIDEO_ID>).

Modo 2: Upload Multilíngue Completo de 3 Edições (option_b — Ocasiões Especiais e Histórias de Família)

Faz upload da 🇺🇦 Edição Ucraniana 4K (_UA.mp4, Não Listado, com thumbnail_ua.jpg) e da 🇷🇺 Edição Russa 4K (_RU.mp4, Não Listado, com thumbnail_ru.jpg) com suas faixas de narração nativas replicadas e legendas .srt, e então envia/atualiza o 🇺🇸 Mestre em Inglês 4K (Privado, com thumbnail.jpg) com links clicáveis para ambas as edições localizadas:

./.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