akomlik/publish-youtube

Etapa 4: Metadatos de YouTube, Miniatura Compuesta y Subida Multilingüe (/publish-youtube)

Propósito

Convierte cualquier exportación 4K .mp4 finalizada y proyecto .fcproj en un paquete completo de lanzamiento para YouTube (youtube_metadata.json, captions.en.srt, captions.ua.srt, captions.ru.srt, y thumbnail.jpg / thumbnail_ua.jpg / thumbnail_ru.jpg) y lo publica en YouTube mediante la YouTube Data API v3.

Reglas Clave de Studio v2

1. Títulos con Gancho Primero (Optimizados para Móvil y Algoritmo): Por defecto, usar el gancho narrativo de alta curiosidad como título principal (ej. Salvado por los Ojos Agudos de Nina! Escoltando a Zumba y Vuelta de 21.5 mi a Pollença) en lugar de anteponer marcas de fecha (AAAA-MM-DD · ...), que se truncan en móvil. Los títulos con fecha de archivo se conservan en title_alternatives y recordingDetails.recordingDate.
2. Comentario Automático de Cambio de Idioma Fijado: Al subir proyectos multilingüe (--option-b), upload_youtube_api.py publica automáticamente un comentario de nivel superior de cambio de idioma en el máster en inglés que enlaza directamente a las ediciones con voz en ucraniano y ruso, para que los espectadores móviles tengan acceso con un solo clic sin expandir la descripción.
3. Código ISO Estricto ua para Ucrania Localmente: Usar siempre ua (UA) en todos los nombres de archivo locales (captions.ua.srt, voiceover_ua_part1.wav, thumbnail_ua.jpg, _UA.mp4) y en las claves de Storyboard.md / youtube_metadata.json. upload_youtube_api.py traduce automáticamente "ua" -> "uk" solo en el cable de la YouTube Data API v3.
4. Regla del Analizador de Capítulos de YouTube: YouTube usa el último bloque de marcas de tiempo 00:00 en la descripción de un video para etiquetar los capítulos de la barra de desplazamiento. Por lo tanto, los bloques en línea 🇺🇦 УКРАЇНСЬКОЮ y 🇷🇺 ПО-РУССКИ dentro de la descripción en inglés nunca deben incluir listas de capítulos 00:00 (los capítulos localizados pertenecen estrictamente dentro de localizations["ua"] y localizations["ru"]).
5. Fecha de Grabación Obligatoria (recordingDetails.recordingDate): Cada video subido o actualizado (incluyendo las ediciones EN, UA y RU) DEBE establecer recordingDetails.recordingDate (AAAA-MM-DDT00:00:00.000Z, derivado de recording_date en youtube_metadata.json o el prefijo AAAA-MM-DD de la carpeta del proyecto) mediante part="snippet,status,localizations,recordingDetails".
6. Herencia de Entorno (Dependencias Cero Envoltorio): Configurar GEMINI_API_KEY, GOOGLE_OAUTH_CLIENT_ID y GOOGLE_OAUTH_CLIENT_SECRET usando su gestor de entorno preferido (ej. direnv + 1Password, perfil de shell, o un archivo .env local) e iniciar Antigravity desde esa sesión de shell para que todos los procesos hijo los hereden automáticamente. Una vez autorizado una vez, ~/.config/antigravity_youtube/token.json almacena en caché el token de actualización OAuth para futuras subidas sin intervención.

Paso 1: Generar Paquete de Metadatos, Pistas .srt y Miniatura Compuesta

Ejecutar 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 "SALVADO EN LA PUERTA" \
  --thumb-text-ua "ВРЯТОВАНИЙ БІЛЯ ВОРІТ" \
  --thumb-text-ru "СПАСЁН У ВОРОТ"

• Modos de Miniatura (--thumb-mode):
  • preserve (por defecto): Mantiene una thumbnail.jpg personalizada/compuesta existente en el directorio del proyecto y genera automáticamente thumbnail_ua.jpg y thumbnail_ru.jpg localizadas si faltan.
  • composite_ai: Usa Gemini 3 Pro Image (gemini-3-pro-image-preview) con --thumb-hero <hero.jpg>, --thumb-prop <prop.jpg>, y --thumb-text "<GANCHO DE 3-4 PALABRAS>" para generar una miniatura compuesta al estilo de YouTube Studio (fondo escénico desenfocado + ciclista sonriente a la izquierda + recorte con borde blanco del objeto clave a la derecha + título en negrita amarillo/blanco en la parte superior).
  • frame: Extrae un fotograma limpio de 1920×1080 en --thumb-sec.

Paso 2: Subir a YouTube (en_only, option_a o option_b)

Modo 1: Subida de Video Único (en_only o option_a — Predeterminado Diario)

Sube el máster en inglés 4K (private), establece títulos y descripciones localizadas EN/UA/RU, sube captions.en.srt, captions.ua.srt y captions.ru.srt, y establece 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 actualizar metadatos/subtítulos/miniatura en un video ya subido sin volver a subir el MP4, añadir --update-video-id <VIDEO_ID>).

Modo 2: Subida Multilingüe Completa de 3 Ediciones (option_b — Ocasiones Especiales e Historias Familiares)

Sube la edición 🇺🇦 Ucraniana 4K (_UA.mp4, Sin listar, con thumbnail_ua.jpg) y la edición 🇷🇺 Rusa (_RU.mp4, Sin listar, con thumbnail_ru.jpg) con sus pistas de voz nativas replicadas y subtítulos .srt, luego sube/actualiza el máster 🇺🇸 Inglés 4K (Privado, con thumbnail.jpg) con enlaces directos a ambas ediciones 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