런치 영상 게시 파이프라인

출시 / 워크스루 비디오

제품, 기능 또는 페이지를 짧은 모션 비디오에 내레이션을 추가하여 YouTube에 게시하고, 페이지에 삽입하며, 공지하는 반복 가능한 파이프라인입니다. 이 작업을 수동으로 하면 매번 수많은 비명시적 세부 사항(OAuth 문제, 음성 해설 동기화 계산, 클릭-투-플레이 임베드, 음량 목표 등)을 다시 발견해야 하기 때문에 필요합니다.

기본 출력: 1080p / 30fps 비디오, 약 45~60초, 감정적 음성 해설 포함, 사용자 승인을 위해 먼저 '미등록'으로 업로드된 후 공개로 전환됩니다. 사용자가 듣거나 보지 않은 비디오를 공개적으로 게시하지 마세요. 음성과 속도는 주관적입니다.

프로젝트에 맞게 구성하기

첫 사용 전에 config.md(몇 개의 ID와 경로)를 채우세요. 스킬은 하드코딩된 값 대신 이를 읽으므로 모든 제품에서 작동합니다. 필요한 값:

• YouTube 채널(OAuth 계정이 선택해야 함)
• OAuth 클라이언트 시크릿 경로 및 GCP 프로젝트 번호(YouTube Data API v3 활성화됨)
• 완성된 비디오 공지가 전달되는 곳(Slack 채널, Discord 등)
• 브랜드 색상 및 제품 URL 패턴

사용 시기

페이지/기능/도구에 대한 비디오를 제작하거나, 음성 해설을 추가하거나, YouTube에 비디오를 게시할 때 사용합니다. "최고 페이지에 비디오 추가"와 같은 광범위한 요청이 있을 경우, 먼저 상위 페이지를 가져온 다음(분석 도구에서) 각 페이지에 대해 이 파이프라인을 한 번 실행합니다. 하나를 시범 운영하고, 형식 승인을 받은 후 나머지를 배치 처리하세요.

파이프라인(7단계)

위에서 아래로 작업하세요. 각 단계는 참조된 파일이나 스크립트에 자세한 내용이 있습니다.

1. 주제 이해하기. 구현/문서를 읽어 표시된 단계가 실제 동작과 일치하도록 합니다. 도구 워크스루의 경우, 라이브 도구(Playwright)를 구동하여 실제 입력→출력 흐름을 확인하세요. 그것이 바로 워크스루입니다.

2. 실제 스크린샷 캡처하기. 프로덕션 환경에서 Playwright를 사용하여 1920×1080 해상도로 캡처합니다. 먼저 프로모션 배너/쿠키 바를 숨기세요. references/video-production.md → "스크린샷 캡처"를 참조하세요.

3. Remotion 비디오 빌드하기. remotion-scaffold/ 구조를 복사하세요. 장면은 src/theme.ts에서 30fps로 프레임 수를 계산합니다. 각 장면의 크기를 내레이션 길이(4단계)에 맞게 조정하세요. 전체 장면/애니메이션 패턴은 references/video-production.md에 있습니다.

4. 음성 해설 생성하기. scripts/tts_voiceover.py — OpenAI gpt-4o-mini-tts, 음성 ash, 감정을 위한 instructions 프롬프트 사용(이것이 없으면 읽기가 평평하고 로봇처럼 들리며, 이것이 VO에서 가장 중요한 세부 사항입니다). 장면별 클립을 생성하고, 각 클립을 해당 장면의 시작 프레임에 동기화하며, 혼합 트랙의 음량을 정규화합니다. 클립이 장면을 초과하면 theme.ts에서 장면 시간을 다시 조정한 후 다시 렌더링하세요.

5. 렌더링 + 먹싱 + 인코딩. npx remotion render 실행, ffmpeg로 VO 트랙을 먹싱(-c:v copy)한 다음, < 10 MB 업로드용 컷 인코딩(libx264 -crf 25 -movflags +faststart). 명령어는 references/video-production.md → "렌더링, 먹싱, 인코딩"에 있습니다.

6. YouTube에 게시하기. scripts/youtube.py(업로드는 youtubeuploader를 래핑하고, 나머지는 Data API 사용). 미등록으로 업로드하고, 사용자의 승인을 받은 후 공개로 설정하세요. 먼저 references/youtube-publishing.md를 읽으세요. 인증 설정, OAuth 리디렉션 문제, API 미활성화 오류, 할당량 제한 및 메타데이터 템플릿이 포함되어 있습니다.

7. 임베드 + 공지하기. 페이지에 클릭-투-플레이 파사드 섹션(포스터 + 재생 버튼; YouTube iframe은 클릭 시에만 마운트되어 초기 로드에 영향을 주지 않음)을 추가하세요. 그런 다음 링크를 팀 채널에 게시하세요. 두 패턴 모두 references/embed-and-announce.md에 있습니다.

가드레일

• 미등록 → 승인 → 공개, 매번 적용됩니다. 사용자 자신의 채널에 업로드하는 것은 사용자의 승인이 필요합니다.
• Google OAuth 동의는 사용자가 직접 해야 합니다 — 사용자를 대신해 "허용"을 클릭할 수 없습니다. 인증이 설정되지 않은 경우, 사용자를 안내하고(references/youtube-publishing.md 참조) 우회를 시도하지 마세요.
• 마스터 렌더링은 보관하세요. 업로드용 컷만 크기가 제한됩니다.
• YouTube API 할당량 ≈ 24시간에 6회 업로드. 그보다 큰 배치는 여러 날에 걸쳐 분산해야 합니다. 중간에 조용히 실패하지 않도록 명시하세요.
• CLI는 썸네일을 설정할 수 없습니다. 사용자가 Studio에서 직접 추가하거나(API를 통해 별도로 설정) 해야 함을 알리세요.