akomlik/publish-youtube

Stage 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. 후크 우선 제목 (모바일 및 알고리즘 최적화): 날짜 스탬프(YYYY-MM-DD · ...)를 앞에 배치하는 대신, 높은 호기심을 유발하는 내러티브 후크를 기본 제목(예: Saved by Nina's Sharp Eyes! Escorting to Zumba & 21.5 mi Pollença Loop)으로 사용합니다. 날짜가 포함된 아카이브 제목은 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 에디션 포함)는 youtube_metadata.json의 recording_date 또는 프로젝트 폴더 접두사 YYYY-MM-DD에서 파생된 recordingDetails.recordingDate (YYYY-MM-DDT00:00:00.000Z)를 part="snippet,status,localizations,recordingDetails"를 통해 반드시 설정해야 합니다.
6. 환경 상속 (래퍼 의존성 제로): GEMINI_API_KEY, GOOGLE_OAUTH_CLIENT_ID, GOOGLE_OAUTH_CLIENT_SECRET을 선호하는 환경 관리자(예: direnv + 1Password, 셸 프로필, 또는 로컬 .env 파일)를 사용하여 설정하고, 해당 셸 세션에서 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: 전체 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