akomlik/publish-youtube

Phase 4: YouTube-Metadaten, Composite-Thumbnail & mehrsprachiger Upload (/publish-youtube)

Zweck

Verwandelt einen fertigen 4K-.mp4-Export und das .fcproj-Projekt in ein vollständiges YouTube-Veröffentlichungspaket (youtube_metadata.json, captions.en.srt, captions.ua.srt, captions.ru.srt sowie thumbnail.jpg / thumbnail_ua.jpg / thumbnail_ru.jpg) und veröffentlicht es über die YouTube Data API v3.

Wichtige Studio v2-Regeln

1. Hook-First-Titel (Mobil & Algorithmus optimiert): Standardmäßig wird der neugierig machende narrative Hook als primärer Titel verwendet (z. B. Gerettet durch Ninas scharfe Augen! Eskorte nach Zumba & 21,5 Meilen Pollença Loop), anstatt Datumsstempel (JJJJ-MM-TT · ...) voranzustellen, die auf Mobilgeräten abgeschnitten werden. Datumstitel im Archiv werden in title_alternatives und recordingDetails.recordingDate beibehalten.
2. Automatisierter gepinnter Sprachwechsler-Kommentar: Beim Hochladen mehrsprachiger Projekte (--option-b) postet upload_youtube_api.py automatisch einen Top-Level-Sprachwechsler-Kommentar auf dem englischen Master, der direkt auf die ukrainische und russische Sprachausgabe verweist, sodass Mobilnutzer ohne Aufklappen der Beschreibung per 1-Klick darauf zugreifen können.
3. Strikter ISO-Code ua für die Ukraine (lokal): Verwende immer ua (UA) in allen lokalen Dateinamen (captions.ua.srt, voiceover_ua_part1.wav, thumbnail_ua.jpg, _UA.mp4) und in den Schlüsseln von Storyboard.md / youtube_metadata.json. upload_youtube_api.py übersetzt "ua" -> "uk" automatisch nur auf der YouTube Data API v3-Ebene.
4. YouTube-Kapitel-Parser-Regel: YouTube verwendet den letzten 00:00-Zeitstempelblock in der Videobeschreibung, um die Kapitel in der Suchleiste zu kennzeichnen. Daher dürfen inline-Blöcke wie 🇺🇦 УКРАЇНСЬКОЮ und 🇷🇺 ПО-РУССКИ innerhalb der englischen Beschreibung niemals 00:00-Kapitellisten enthalten (lokalisierte Kapitel gehören ausschließlich in localizations["ua"] und localizations["ru"]).
5. Obligatorisches Aufnahmedatum (recordingDetails.recordingDate): Bei jedem hochgeladenen oder aktualisierten Video (einschließlich EN, UA und RU-Editionen) MUSS recordingDetails.recordingDate gesetzt werden (JJJJ-MM-TTDT00:00:00.000Z, abgeleitet von recording_date in youtube_metadata.json oder dem JJJJ-MM-TT-Projektordnerpräfix) über part="snippet,status,localizations,recordingDetails".
6. Umgebungsvariablen-Vererbung (Keine Wrapper-Abhängigkeiten): Setze GEMINI_API_KEY, GOOGLE_OAUTH_CLIENT_ID und GOOGLE_OAUTH_CLIENT_SECRET mit deinem bevorzugten Environment-Manager (z. B. direnv + 1Password, Shell-Profil oder einer lokalen .env-Datei) und starte Antigravity aus dieser Shell-Sitzung, sodass alle Kindprozesse sie automatisch erben. Nach einmaliger Autorisierung speichert ~/.config/antigravity_youtube/token.json das OAuth-Refresh-Token für zukünftige Uploads ohne erneute Eingabeaufforderung.

Schritt 1: Metadatenpaket, .srt-Titel & Composite-Thumbnails generieren

Führe generate_youtube_metadata.py aus:

./.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 "AM TOR GERETTET" \
  --thumb-text-ua "ВРЯТОВАНИЙ БІЛЯ ВОРІТ" \
  --thumb-text-ru "СПАСЁН У ВОРОТ"

• Thumbnail-Modi (--thumb-mode):
  • preserve (Standard): Behält ein vorhandenes benutzerdefiniertes/Composite-thumbnail.jpg im Projektverzeichnis und generiert automatisch lokalisierte thumbnail_ua.jpg und thumbnail_ru.jpg, falls diese fehlen.
  • composite_ai: Verwendet Gemini 3 Pro Image (gemini-3-pro-image-preview) mit --thumb-hero <hero.jpg>, --thumb-prop <prop.jpg> und --thumb-text "<3-4 WORT HOOK>", um ein YouTube-Studio-ähnliches Composite-Thumbnail zu generieren (unscharfer Landschaftshintergrund + links lächelnder Fahrer + rechts weiß umrandeter Sticker-Ausschnitt des Schlüsselrequisits + fette gelbe/weiße Kopfzeile).
  • frame: Extrahiert einen sauberen 1920×1080-Frame bei --thumb-sec.

Schritt 2: Upload zu YouTube (en_only, option_a oder option_b)

Modus 1: Einzel-Video-Upload (en_only oder option_a — Täglicher Standard)

Lädt den 4K-englischen Master hoch (private), setzt lokalisierte EN/UA/RU-Titel und -Beschreibungen, lädt captions.en.srt, captions.ua.srt und captions.ru.srt hoch und setzt 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

(Um Metadaten/Untertitel/Thumbnail eines bereits hochgeladenen Videos ohne erneuten MP4-Upload zu aktualisieren, füge --update-video-id <VIDEO_ID> hinzu.)

Modus 2: Vollständiger 3-Editionen-Mehrsprachen-Upload (option_b — Besondere Anlässe & Familiengeschichten)

Lädt die 4K-🇺🇦 ukrainische Edition (_UA.mp4, Nicht gelistet, mit thumbnail_ua.jpg) und die 4K-🇷🇺 russische Edition (_RU.mp4, Nicht gelistet, mit thumbnail_ru.jpg) mit ihren nativen, replizierten Voice-Over-Tonspuren und .srt-Untertiteln hoch. Anschließend wird der 4K-🇺🇸 englische Master (Privat, mit thumbnail.jpg) mit klickbaren Links zu beiden lokalisierten Editionen hochgeladen/aktualisiert:

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