product-video

제품 영상

실제 화면을 사용하여 제품을 소개하는 60~120초 분량의 내레이션이 포함된 영상을 만듭니다. 출력물은 HyperFrames 프로젝트(하나의 생성된 index.html + 자산)와 렌더링된 MP4입니다.

모든 결과물(스크립트, 화면 텍스트, README)은 대상 청중의 언어로 작성하세요. 이 파일은 지침이므로 영어로만 제공됩니다.

출력 구조

비디오당 하나의 폴더를 만들고, 사용자가 달리 명시하지 않는 한 모든 코드 저장소 외부에 생성합니다:

<Product>-video/
  ROTEIRO.md | SCRIPT.md     스크립트, 클레임 표, 확인할 사항
  LEIA-ME.md | README.md     실제인 것, 재구성한 것, 제한 사항, 재실행 방법
  01-.. 0N-..                캡처된 자산, 소스당 하나의 폴더
  voz/ | voice/              내레이션 세그먼트(텍스트 및 장면별 오디오)
  ferramentas/ | tools/      설정 및 gen.js (컴포지션 생성기)
  hyperframes/
    index.html               생성됨. 절대 수동으로 편집하지 마세요.
    assets/{img,video,audio,fonts}
    renders/

워크플로우

단계를 순서대로 실행합니다. 각 단계는 검사(check)로 끝나며, 검사가 통과될 때까지 다음 단계를 시작하지 마세요.

P1. 소스

1. 사용자가 명명한 모든 소스를 찾습니다. 다른 머신의 경로는 존재하지 않으므로, 현재 사용자 폴더에서 동일한 프로젝트를 검색하고 사용한 경로를 알려주세요.
2. 제품이 어떻게 표시될 수 있는지 분류합니다:
   • 도달 가능한 라이브 앱: 캡처합니다 (P3, site-capture.cjs, record-interaction.cjs).
   • 공개 Figma 파일: 프로토타입 보기를 통해 프레임을 캡처합니다 (P3, figma-frames.cjs). 토큰이 필요하지 않습니다.
   • 로그인이 필요한 앱(접근 불가): 스크린샷이나 테스트 계정을 요청하세요. 기억에 의존하여 화면을 재구성하지 마세요.
3. 제품 자체의 단어를 추출합니다: 랜딩 페이지 카피, 기능 이름, 숫자, FAQ, 약관. 이는 클레임에 허용되는 유일한 출처입니다.

검사: 대상 청중, 제품의 모듈, 사용할 각 사실의 출처를 명명할 수 있어야 합니다.

P2. 스크립트

references/script.md를 읽고 템플릿에서 스크립트 파일을 작성합니다. 가장 중요한 규칙:

• 초당 2.3~2.6 단어로 예산을 잡습니다. 250단어는 약 100초입니다.
• 장면당 하나의 아이디어, 장면당 816초, 총 69장면.
• 내레이션의 모든 클레임은 클레임 표에 출처와 함께 행을 가져야 합니다. 출처가 뒷받침할 수 없는 것은 모두 생략합니다.
• 음성을 위한 작성: 브랜드 이름은 발음되는 대로, 숫자는 풀어서, 음성이 문자 하나하나를 말할 약어는 사용하지 않습니다.

검사: 클레임 표에 빈 출처 셀이 없고, "확인할 사항" 목록에 마케팅 카피에서 가져온 모든 숫자가 명명되어 있어야 합니다.

P3. 자산

설정 예제는 references/capture.md를 참조하세요.

소스	스크립트	출력
라이브 웹 앱, 정적	scripts/site-capture.cjs	첫 화면, 전체 페이지, 단계별 스크린샷, 스크롤 비디오, 컷아웃
라이브 웹 앱, 흐름	scripts/record-interaction.cjs	커서 또는 탭 오버레이가 있는 인터랙션 클립
공개 Figma 파일	scripts/figma-frames.cjs	프레임당 하나의 PNG, 프레임에 맞게 자름

또한 브랜드 수집: 로고(벡터가 있으면 벡터), 라이선스가 있는 브랜드 폰트 파일, 제품 CSS의 색상 토큰. scripts/page-styles.cjs <url>로 제품 자체 페이지의 스타일을 읽습니다: 헤드라인 패밀리, 두께, 줄 높이 및 자간, 버튼 스타일 및 프로스트 글라스 표면. 비디오는 추측 대신 이를 복사합니다.

검사: 캡처 중 일부를 열어 살펴보세요. 로그인 벽, 쿠키 배너 또는 개발자 오버레이를 보여주는 캡처는 실패한 캡처입니다.

P4. 음성

references/voice.md를 읽으세요. 음성을 생성하기 전에 사용자에게 어떤 음성을 사용할지 물어보세요: MCP 또는 API 키를 통해 도달하는 유료 서비스가 우선, 제공된 내레이션이 두 번째입니다. 무료 로컬 모델은 사용자가 요청하는 경우에만 사용하세요. 모델을 머신에 설치하기 때문입니다.

• MCP를 통한 음성 서비스: 전체 내레이션을 하나의 연속 테이크로 생성합니다(장면당 하나의 문단, 시작 부분에 하나의 전달 태그). scripts/voice.py --existing으로 정렬하고, scripts/split-take.py --level로 일시 중지 지점에서 자르고, scripts/voice.py --parts "voz/cena-{id}.wav"로 장면 파일을 결합합니다. 장면 경계는 정확하며 톤은 첫 장면부터 마지막 장면까지 동일하게 유지됩니다. 장면별로 요청된 내레이션은 요청 사이에 분위기가 바뀝니다.
• API 키를 통한 음성 서비스: scripts/voice.py --provider elevenlabs --el-voice <id>가 생성 및 결합합니다. scripts/elevenlabs.py는 연결을 확인하고, 음성 순위를 매기고, 음악을 구성합니다.
• 제공된 내레이션: --existing을 전달합니다. 장면 경계는 전사본을 스크립트에 정렬하여 결정됩니다.

표현력이 풍부한 모델을 사용하는 경우 테이크 시작 부분에 하나의 [오디오 태그]로 전달을 설정합니다. 각 장면은 text(깨끗한, 자막용)를 전달하고 tts(음성이 수신하는 것, 차이가 있을 때)를 전달할 수 있습니다.

모든 모드에서 단어 타이밍은 스크립트 텍스트에 정렬되므로 자막에 전사 오류가 표시되지 않습니다. 출력하는 misheard 목록을 읽으세요: 풀어 쓴 숫자와 동음이의어 외의 항목은 발음 문제입니다. 스크립트 텍스트를 수정하고 다시 생성하세요.

구성하기 전에 내레이션을 약 -18 LUFS로 정규화하세요.

검사: voiceover.json이 존재하고, 총 길이가 목표의 10% 이내이며, misheard가 설명되었고, scripts/voice-tone.py --scenes이 장면 간 중간 피치의 분산이 약 3세미톤 이하로 보고해야 합니다.

P5. 컴포지션

references/hyperframes.md(렌더러가 적용하는 규칙)를 읽고 assets/gen-template.js에서 시작합니다.

• 스크립트에서 index.html을 생성합니다. 음성이 변경될 때마다 타이밍이 변경됩니다. 생성기는 이를 흡수하지만 수동 편집은 그렇지 않습니다.
• 모든 애니메이션을 내레이션의 구문에 고정합니다(at(3, '패널에서')), 절대 짧은 단어 하나에 고정하지 마세요. "그", "와", "하나"는 장면당 여러 번 나타나며 첫 번째 일치가 잘못된 것입니다.
• 프레임 하단 17%를 자막용으로 예약합니다. 다른 어떤 것도 해당 대역에 들어가지 않습니다.
• 브라우저 창 또는 기기 목업 내부에 실제 화면을 표시합니다. 설명을 그 위에가 아닌 옆에 배치합니다.
• 문장당 하나의 명확한 하이라이트(링, 확대, 커서 이동)를 많은 작은 하이라이트보다 선호합니다.
• 헤드라인은 제품 자체의 헤드라인 스타일을 사용하고 태그는 표면 언어를 사용하며, 둘 다 P3에서 읽습니다. 가장 무거운 두께를 기본값으로 사용하지 마세요.
• 스토리, 릴 또는 쇼츠의 경우 references/vertical.md를 읽고 동일한 내레이션에서 두 번째 세로 컴포지션을 빌드하고 assets/gen-vertical-template.js에서 시작합니다. 16:9 버전을 절대 자르지 마세요.

검사: npx hyperframes lint에 0개의 오류가 있어야 합니다.

P6. 확인

1. npx hyperframes check는 "Check passed"로 끝나야 합니다(린트, 런타임, 레이아웃, 모션, 대비).
2. npx hyperframes snapshot --no-end --at <장면당 한 번, 각 하이라이트 포함>을 실행하고 모든 프레임을 살펴보세요. ffmpeg로 2×2 검토 시트를 만들어 더 빠르게 검토하세요.
3. 각 프레임을 그 순간의 내레이션과 비교합니다. 일반적인 결함: 문장에 맞지 않는 화면, 잘못된 요소의 하이라이트, 텍스트 줄바꿈, 자막 대역 내부의 요소.
4. 드래프트를 렌더링(render -q draft)한 다음 MP4 자체를 확인합니다: ffprobe로 길이와 스트림, loudnorm으로 음량(목표 -16 ~ -17 LUFS, 음악 포함), ffmpeg로 추출한 프레임.

검사: MP4에서 가져온 각 장면의 프레임을, 스냅샷에서만이 아니라 확인했습니다.

P7. 전달

README를 작성합니다: 실제인 것(캡처됨), 실제 데이터로 HTML에서 재구성된 것, 개념적인 것, 알려진 제한 사항, 미리보기/확인/렌더링 명령어, 음성 교체 방법. 그런 다음 사용자에게 보고합니다: 만들어진 것, 확인된 것, 아직 사람의 결정이 필요한 것(확인되지 않은 숫자, 음악, 음성 품질).

이미 해결된 함정

코드	증상	원인 및 수정
X1	화면이 1초 일찍 전환됨	at()이 첫 번째 "그" 또는 "와"와 일치했습니다. 구문에 고정하세요.
X2	요소가 여러 장면 내내 숨겨짐	동일한 요소에 두 개의 fromTo 트윈; 나중 것이 "from" 상태를 즉시 렌더링합니다. 등장당 하나의 요소를 사용하거나 CSS 초기 상태에서 to()를 사용하세요.
X3	사이트가 스크립트에 403을 응답하지만 브라우저에서는 열림	헤드리스 사용자 에이전트. 데스크톱 UA를 보내는 lib/browser.cjs를 사용하세요.
X4	실행 시 "Executable doesn't exist"	설치된 브라우저 빌드가 Playwright 버전과 다릅니다. lib/browser.cjs가 가장 최신 로컬 Chromium, 그다음 Chrome으로 대체합니다.
X5	전체 페이지 스크린샷이 한 화면에서 잘림	앱이 내부 컨테이너를 스크롤합니다. 가장 큰 스크롤 가능한 요소를 찾고 뷰포트를 해당 높이로 늘리세요.
X6	스크롤 녹화가 끊김	Screencast 프레임 속도가 가변적입니다. 대신 프레임별로 스크롤을 렌더링하세요.
X7	변경되지 않는 파일을 계속 확인함	레코더가 검사하는 폴더와 다른 폴더에 씁니다. 출력 경로를 출력하고 확인하세요.
X8	카운터가 거대한 "%" 옆에 작게 렌더링됨	하위 선택자(.num span)가 내부 카운터 범위에도 일치했습니다. 레이블에는 자식 선택자를 사용하세요.
X9	자막에 잘못된 단어가 표시됨	자막이 원시 전사본에서 왔습니다. 타이밍을 스크립트 텍스트에 정렬하세요(voice.py가 이 작업을 수행).
X10	음성이 브랜드 또는 용어를 잘못 발음함	말하는 대로 작성(한 단어로 작성된 브랜드는 두 단어로 발음됨, 외국어 용어는 모국어 구문 사용), 숫자는 풀어 쓰고, 약어는 확장하세요.
X11	두 번째 캡처 실행이 첫 번째의 인덱스를 지움	덮어쓰는 대신 실행 간에 인덱스 파일을 병합하세요.
X12	시간 제한 래퍼 내부의 비디오가 검사 실패	시간 미디어 자체가 class="clip"을 전달합니다. 해당 컨테이너에는 타이밍이 없습니다.
X13	프로토타입 캡처에 토스트 또는 쿠키 막대가 포함됨	스크린샷 전에 오버레이를 닫고 숨긴 다음 프레임에 맞게 자르세요.
X14	녹화에 프로토타입 전용 버튼이 표시됨	녹화 전에 선택자 또는 텍스트 접두사로 테스트 및 개발 컨트롤을 숨기세요.
X15	제품이 증명할 수 없는 클레임	"최초", "전체", "보장"에는 출처가 필요합니다. 생략하거나 "확인할 사항"으로 이동하세요.
X16	마케팅 숫자에 근거가 없음	사용하기 전에 출처를 확인하세요: 문서와 페이지의 git 히스토리(git log -S'<숫자>')를 검색하세요. 복사 편집에서 수동으로 올린 숫자는 증거가 아닙니다. 삭제하세요.
X17	세로 컷을 읽을 수 없음	9:16의 데스크톱 화면은 9px 텍스트를 가지며, 이를 자른 것도 여전히 데스크톱처럼 보입니다. 제품의 모바일 랜딩 페이지가 하는 것처럼(references/vertical.md) 패널에 한 번에 하나의 조정된 요소를 표시하세요.
X18	내레이션이 극적이거나 행복감이 느껴짐	비언어적 태그([한숨]), [흥분함] 및 [진지함]은 제품 비디오에서 과장됩니다. [차분함]과 [따뜻함]을 사용하고, 명명된 장면만 다시 생성하고, scripts/voice-tone.py로 테이크를 비교하세요.
X19	레이아웃이 웹 페이지처럼 읽힘	왼쪽 정렬 열, 헤드라인 위의 섹션 레이블, 모서리의 작은 로고. 세로 비디오에서는 모든 것을 중앙 정렬하고, 레이블을 제거하고, 로고를 더 크게 만들고 중앙에 배치하세요.
X20	태그라인이 로고에서 멀리 떨어져 있음	로고 내보내기에 투명 패딩이 있습니다. 파일을 트리밍하고 실제 마크에 대해 위치를 지정하세요.
X21	일부 장면에서 내레이션이 평평하고 다른 장면에서 흥분됨	각 장면이 자체 태그와 함께 별도의 요청이었으므로 각각 별도의 연기였습니다. 하나의 태그로 하나의 연속 테이크를 생성하고, scripts/split-take.py로 일시 중지에서 자르고 scripts/voice-tone.py --scenes로 측정하세요. 장면 간 5세미톤의 분산은 기분 변화로 들렸고, 2세미톤은 일정하게 들렸습니다.
X22	헤드라인이 무겁고 제품과 다름	두께가 가정되었습니다(800). scripts/page-styles.cjs로 제품 자체의 헤드라인 스타일을 읽고 패밀리, 두께, 줄 높이 및 자간을 복사하세요.
X23	헤드라인에서 단어가 함께 실행됨	웹 페이지에서 복사한 좁은 자간이 비디오 크기에서 단어 사이의 간격을 닫습니다. word-spacing: .07em을 추가하세요.
X24	유리 태그가 단색 흰색처럼 보이거나 흐림 효과가 페이드 인 후에 나타남	배경이 너무 불투명함(하단 부분을 0.6 근처로 유지) 또는 페이드가 부모에 있음: 조상의 불투명도가 1 미만이면 요소가 뒤에 있는 것과 분리됩니다. backdrop-filter가 있는 요소에 애니메이션을 적용하세요.
X25	괜찮아 보이는 텍스트에서 대비 검사 실패	검사가 페이드 중간에 프레임을 샘플링했습니다. 보고된 시간에 스냅샷을 찍으세요. 요소가 진입 중이면 진입을 몇 프레임 이동하고 검사를 다시 실행하세요. 매우 짧은 컴포지션이 이 문제를 가장 많이 겪습니다.

이 스킬의 파일

• references/script.md: 스크립트 템플릿, 페이싱, 클레임 표, 발음 표.
• references/capture.md: 세 가지 캡처 스크립트, 캡처 사양, 브랜드 자산에 대한 설정.
• references/voice.md: TTS 설정, 음성, 정렬, 음량, 음악, 내레이션 교체.
• references/hyperframes.md: 컴포지션 규칙, CLI 명령어, 레이아웃 영역.
• references/vertical.md: 스토리용 9:16 버전: 안전 영역, 화면의 카메라, 자막, 부분 분할.
• assets/gen-template.js: 프로젝트의 tools 폴더에 복사할 16:9 컴포지션 생성기.
• assets/gen-vertical-template.js: 전체 및 짧은 에디션이 있는 세로 생성기.
• scripts/lib/browser.cjs, scripts/site-capture.cjs, scripts/record-interaction.cjs, scripts/figma-frames.cjs, scripts/element-shots.cjs, scripts/page-styles.cjs, scripts/voice.py, scripts/split-take.py, scripts/voice-tone.py, scripts/elevenlabs.py, scripts/lib/eleven.py.

ElevenLabs API 코드(--provider elevenlabs, elevenlabs.py)는 테스트할 키 없이 작성되었습니다. 첫 실제 실행에서 수정이 필요할 수 있습니다. --parts 경로와 로컬 경로는 테스트되었습니다.