Innate-Labs/product-demo-video

Product Demo Video（产品演示片）

실제 웹 제품을 스타일리시한 데모 비디오로 만듭니다: 실제 페이지 스크린샷 + 코드로 재구성한 인터페이스를 브라우저 창 목업에 조립하고, 자막, 로고, 음악을 추가하여 세로/정사각형 숏폼 비디오로 렌더링합니다.

완전 자동—실행 가능한 프로젝트만 제공하면 Claude가 다음을 수행합니다:

• 제품 자동 이해: CLAUDE.md / README / 라우터를 읽고 각 페이지의 용도와 제품의 톤을 파악합니다.
• 코드 읽고 카피 자동 생성: 각 페이지의 실제 기능에 기반하여 해당 시나리오에 맞는 제목/부제목 자막과 주소 표시줄을 자동 작성합니다. 직접 작성할 필요가 없습니다.
• 로고 자동 찾기: public/ 디렉토리에서 프로젝트의 실제 벡터 로고를 찾아 인트로와 아웃트로에 사용합니다.

사용자는 몇 가지 핵심 선택 사항(캔버스 비율, 포함할 페이지, 리듬, 사운드)만 결정하면 됩니다.

사전 스킬: 이 스킬은 [remotion-best-practices](비디오 프레임워크)와 agent-browser에 의존합니다. Remotion 코드를 처리하기 전에 먼저 remotion-best-practices를 로드하여 도메인 지식을 확보하세요.

사용 시기

사용자가 실행 가능한 웹 제품(자신의 프로젝트 또는 지정된 디렉토리)을 제품 데모/홍보 숏폼 비디오로 만들고자 할 때. 일반적인 예: "우리 제품 데모 비디오 만들어 줘", "이 페이지를 세로 홍보 영상으로 만들어 줘".

결과물 형태

mp4로 렌더링되는 Remotion 프로젝트:

• 캔버스: 세로 1280×1706 (3:4, 기본값, 소셜 미디어 적합) / 정사각형 1080×1080 / 가로 1920×1080
• 구조: N개의 장면, 각 장면 = 제품 페이지(실제 스크린샷 또는 코드 재구성)를 브라우저 창 목업에 넣고 하단에 자막 배치; 장면 간 크로스페이드 + 전체 창 느린 Ken Burns; 마지막에 브랜드 로고 + 슬로건
• 사운드: 로열티 프리 BGM(기본값) 또는 TTS 내레이션(선택 사항)

전체 프로세스 (5단계)

1단계 — 제품 파악 및 내러티브 계획

1. 프로젝트의 CLAUDE.md / README.md / DESIGN.md를 읽고 다음을 파악합니다: 제품이 무엇인지, 핵심 페이지/기능은 무엇인지, 톤 규정(색상/폰트/금지 사항 — reference/tone.md 참조, 프로젝트 자체 DESIGN.md를 반드시 준수).
2. 페이지 라우터를 나열하고(find app -name page.tsx), 각 페이지의 기능을 읽고 자동으로 '사용자 여정' 내러티브 라인(예: '핵심 기능 A → B → C → 결과 페이지')을 요약하고, 각 세그먼트에 대한 자막 카피를 자동으로 작성합니다.
3. 사용자와 확인: 캔버스 비율, 포함할 단계, 리듬, 사운드 방식. 실제 스크린샷을 찍을 수 없는 페이지는 사전에 위험을 표시합니다(실시간/특수 데이터가 필요한 페이지).

2단계 — 실제 페이지 스크린샷 (가능한 페이지 우선)

agent-browser를 사용합니다. 자세한 내용은 scripts/capture-pages.md를 참조하세요. 핵심 사항:

• 대상 프로젝트의 프론트엔드/백엔드를 시작하고(백그라운드) 준비될 때까지 기다립니다.
• 표준 뷰포트 설정 agent-browser set viewport 1440 900 2 (@2x retina, 16:10 일반 브라우저 비율, 선명한 스크린샷).
• 로그인 처리: 대부분의 (app) 페이지는 로그인이 필요합니다. dev.db에서 테스트 계정을 찾습니다. 비밀번호는 해시되어 있으므로, 사용자 승인 후 프로젝트 자체 해시 함수로 임시 재설정합니다(스크린샷 후 반드시 복원, 주의 사항 참조).
• dev 각인 제거: agent-browser eval "document.querySelectorAll('nextjs-portal').forEach(e=>e.remove())".
• 각 대상 페이지의 깨끗한 스크린샷을 찍어 Remotion 프로젝트의 public/<brand>/에 저장합니다.

3단계 — 스크린샷이 불가능한 페이지 코드 재구성 (품질 핵심 포인트)

일부 페이지는 실제 스크린샷을 찍을 수 없습니다(실시간 음성 면접방 headless 마이크 없음, 보고서 페이지 백엔드 생성 의존, 데이터 누락). 상상으로 그리지 마십시오—

1. 실제 컴포넌트 코드를 읽습니다(components/.../XxxLayout.tsx 등), 실제 레이아웃/요소/데이터 구조를 확인합니다.
2. 실제 구조를 기반으로 Remotion에서 React 컴포넌트로 1:1 재구성하여 창 콘텐츠 영역(크기 = 창 콘텐츠 영역 W×H)에 렌더링합니다.
3. 예시는 templates/screens/InterviewScreen.tsx(세션형 인터페이스), templates/screens/ReportScreen.tsx(보고서형 인터페이스)를 참조하세요. 이들은 '실제 코드 기반 재구성'의 중립적인 템플릿입니다. 제품을 변경할 때 동일한 방법을 사용하여 제품의 실제 콘텐츠로 다시 작성하십시오.

4단계 — 데모 비디오 조립

templates/PromoVideo.tsx를 뼈대로 사용(브라우저 목업 + 장면 크로스페이드 + Ken Burns + 자막 + 아웃트로 + 오디오), templates/PromoRoot.tsx에서 composition을 등록합니다.

• 각 장면 설정 { type: 'image'|'<custom>', src?, addr, title, sub }.
• 주소 표시줄은 장면에 따라 변경됩니다(현실감 향상).
• 인트로와 아웃트로에서 프로젝트의 실제 로고를 자동으로 찾아 사용합니다(public/에서 icons/logo.svg와 같은 벡터 로고타입을 찾고, 순수 텍스트로 가장하지 마십시오).
• 톤 규정을 엄격히 준수합니다(아래 참조).

5단계 — 사운드 및 렌더링

• BGM(기본값): Mixkit 로열티 프리 상업용 음악, scripts/get-bgm.sh로 다운로드+미리 듣고 사용자 선택. 전체 비디오에 배경음으로 깔고, 처음과 끝에서 페이드 인/아웃.
• TTS 내레이션(선택 사항): scripts/gen-tts.sh, AiHubMix/OpenAI 호환 /audio/speech 사용(gpt-4o-mini-tts 고품질, 사용자 키 필요). 각 문장을 장면에 맞추고 장면 길이는 내레이션 길이에 따라 조정. macOS say 사용 금지(기계음, 품질 낮음).
• 렌더링: npx remotion render <id> out/<name>.mp4, 오디오 트랙 + 길이 확인 후 ~/Desktop/에 복사.

Tone — 톤 규정 (이것이 '터미널' 느낌의 핵심, 자세한 내용은 reference/tone.md 참조)

기본 톤 = 절제, 전문적, 실제적. 프로젝트의 DESIGN.md에서 달리 요구하지 않는 한:

• 색상: 흰색 배경(#F4F4F6 캔버스 / #FFF 창) + 흑백/회색 텍스트(#141414 / #8A8A90), 컬러 사용 금지; 기능적 빨간 점(녹화/연결 등)은 실제 그대로 유지.
• 폰트: 중/영문 통일 PingFang("PingFang SC","Heiti SC",sans-serif), 렌더링 머신이 macOS이므로 바로 사용 가능; Inter 등 사용 금지(한국어 fallback 불일치).
• 브라우저 목업: 둥근 모서리 18 흰색 창 + 상단 크롬 바(세 개의 회색 원, 신호등 컬러 사용 금지 + 주소 표시줄 필), 부드러운 그림자.
• 카메라 움직임: 이징 통일 Easing.bezier(0.16,1,0.3,1); 창 플로트인은 spring 사용; 전체 창 느린 Ken Burns scale 1→1.03 (창에 적용되고 내부 이미지에는 적용되지 않음, 그렇지 않으면 콘텐츠가 잘림).
• 리듬: 장면 길이 통일(기본 각 60프레임/2초 @30fps), 일정하게; 비트에 맞추려면 BGM의 BPM을 측정하여 마디에 맞출 수 있음.
• 자막: 하단 중앙 정렬, 제목 PingFang Semibold 큰 글자 + 부제목 회색 작은 글자, 크로스페이드.
• 이모지 없음.

금지 목록(하지 말 것): 컬러 남용, 신호등 컬러 점, Inter와 한국어 조합, objectFit: cover로 페이지 콘텐츠를 잘라내는 확대, 스크린샷 불가능 페이지를 상상으로 그림, 기계음 TTS, 리듬 불규칙, 순수 텍스트 가짜 로고.

시행착오 및 교훈 (필독)

• Headless 브라우저에는 마이크/카메라가 없음: 실시간 음성/비디오 페이지는 '준비 중/장치 사용 불가'에서 멈춰 스크린샷 불가—즉시 코드 재구성으로 전환, 고집하지 마십시오.
• 로컬 dev 데이터베이스 스키마 불일치: 코드에 마이그레이션을 추가했지만 로컬 DB에서 실행하지 않으면 500 오류 발생(예: no such column: xxx). 스크린샷/데이터 채우기를 위해 ALTER TABLE ADD COLUMN으로 누락된 열을 추가할 수 있음(안전, 데이터 삭제 안 함), 그러나 설명 필요.
• 로컬 데이터베이스 변경은 반드시 복원: 재설정한 테스트 비밀번호, 임시 채운 예제 데이터는 스크린샷 후 반드시 원래 값으로 복원(원래 해시/JSON 백업 먼저). 추가한 열은 유지 가능(이미 코드가 예상하는 것이므로).
• objectFit으로 콘텐츠 자르지 마십시오: 스크린샷을 창에 넣을 때 objectFit:"contain"으로 전체 표시; Ken Burns 확대는 외부 창에 적용, 이미지에 적용하지 않음, 그렇지 않으면 페이지 하단이 잘림.
• 예제 데이터 채울 때 필드 이름은 코드에서 확인: 프론트엔드가 읽는 필드 이름은 직관과 다른 경우가 많음(복수형/밑줄 등), 반드시 렌더링 컴포넌트를 읽어 확인하고 추측하지 마십시오.
• 한국어 카피에 ASCII 큰따옴표 포함 → 전체 문자열을 백틱으로 감쌉니다(전역 CLAUDE.md 규칙).
• Bash cwd는 호출 간에 지속됨: 절대 경로 사용, cd 하위디렉토리 반복 금지.

빠른 검증

Remotion 코드 변경 후: npx tsc --noEmit; 키 프레임 렌더링 npx remotion still <id> out/check.png --frame=N --scale=0.5로 시각적 자체 검사; 최종 렌더링 후 ffprobe로 오디오 트랙+길이 확인.