제품 출시 비디오 - 디스패치 진입점
Step 0 이전에 경로를 확인하세요. 이 스킬은 마케팅/출시/프로모션 중인 제품을 위한 비디오를 제작합니다. 실제로 일반 (비출시) 사이트 → 비디오(사이트 투어/쇼케이스, 제품 판매 아님)인 경우 →
/website-to-video; 제품이 없는 주제/개념인 경우 →/faceless-explainer; GitHub PR인 경우 →/pr-to-video; 기존 비디오에 자막/패키징인 경우 →/embedded-captions·/graphic-overlays. 범위 밖(거절, 허위 생성 금지): 실시간/렌더링 시점 데이터(모든 값은 작성 시점에 고정됨), 아직 존재하지 않는 푸티지/스크린샷/아바타(HyperFrames는 녹화 또는 캡처 불가). "비디오 만들기"라는 모호한 요청으로 여기로 라우팅되었거나, 제품-대-주제/출시-대-일반사이트가 불확실한 경우? 먼저/hyperframes를 읽으세요.
모든 산출물은 PROJECT_DIR = videos/<project-name>/에 기록됩니다(Step 0에서 생성). 아래 경로는 PROJECT_DIR 기준 상대 경로입니다. **사용자(오케스트레이터)**는 Bash 단계를 실행하고 서브에이전트를 디스패치합니다. 단계별 세부 사항은 연결된 가이드/에이전트/스크립트에 있습니다. 여기서 확장하지 마세요. 디스패치는 하네스 이식 가능: 첫 번째 서브에이전트 디스패치 전에 <SKILL_DIR>/../hyperframes-core/references/subagent-dispatch.md를 한 번 읽으세요. 이 파일은 디스패치 동사(병렬 팬아웃/백그라운드/대기)를 하네스의 프리미티브에 매핑합니다. 아래 동시성 제한은 해당 크기의 웨이브를 의미하며, 씬 수는 줄어들지 않습니다. 이 파일은 배경 읽기 자료가 아닌 바인딩 런북입니다: 단계를 순서대로 실행하고 각 단계 산출물을 지정된 스크립트 또는 에이전트 역할로 생성하세요. 임의 파이프라인(수동 내레이션, 임시 TTS 호출, 수동 작곡)으로 대체하지 말고, 요청이 명확해 보인다고 해서 일시 정지 단계를 건너뛰지 마세요. 수행할 수 없는 단계가 있으면 → 중단하고 보고하세요. 이를 무시하고 진행하면 모든 다운스트림 계약이 깨집니다.
| 단계 | 실행 방식 | 주요 산출물 | 상세 흐름 |
|---|---|---|---|
| init | Bash 직접 실행 | hyperframes.json | Step 0 (이 파일) |
| capture | Bash 직접 실행 (hyperframes capture) | capture/extracted/tokens.json | phases/capture/guide.md |
| design-system | 서브에이전트 | design-system/design.html + chunks/ | agents/design-system.md |
| story-design | 서브에이전트 | narrator_scripts.json | agents/story-design.md |
| audio | Bash 직접 실행 (audio.mjs) | audio_meta.json | phases/audio/guide.md |
| visual-design | 서브에이전트 | section_plan.md | agents/visual-design.md |
| prep | Bash 직접 실행 (prep.mjs) | group_spec.json | scripts/prep.mjs 헤더 |
| captions | Bash 직접 실행 (captions.mjs group -> html) | caption_groups.json + compositions/captions.html | scripts/captions.mjs 헤더 |
| scenes | N x 서브에이전트 (병렬, 씬당 하나씩) | compositions/scene_*.html | agents/hyperframes-scene.md |
| finalize | Bash 전주(대기-BGM + 조립 + 전환 + 호이스트 + SFX-확인) -> 최종화 서브에이전트 | renders/video.mp4 | Step 7 / agents/hyperframes-finalize.md |
사전 요구 사항 (최초 실행 전 설치)
macOS Apple Silicon 또는 Linux x64:
brew install [email protected] node ffmpeg # Linux에서는 apt/dnf 동등 명령어 사용
npx hyperframes doctor # Chrome/의존성 준비 상태 1회 확인
[email protected]— Homebrew Python, 시스템/usr/bin/python3아님 (그렇지 않으면 PEP 668이pip install차단); MusicGen 폴백에서 사용node >= 18+ffmpeg(audio.mjs가ffprobe사용)- Chrome은 최초
npx hyperframes capture실행 시 자동 다운로드됨.hoist-videos.mjs(Step 7, 씬이 푸티지를 선언할 때만 실행)는 캐시된 Chrome을 재사용함. 의존성 누락 보고 시node <SKILL_DIR>/scripts/hoist-videos.mjs --ensure-deps를 한 번 실행(약 5초)
선택적 API 키 (설정 안 함 -> 로컬 폴백; Step 0.5에서 주입; GEMINI_API_KEY ≡ GOOGLE_API_KEY):
| 키 | 사용처 | 기본 음성/폴백 |
|---|---|---|
HEYGEN_API_KEY (또는 hyperframes auth login) | TTS (클라우드, 단어 수준 타임스탬프 포함) | 음성: 자동 (최초 영어 Starfish 음성; --voice로 재정의) |
ELEVENLABS_API_KEY | TTS (클라우드; pip install elevenlabs 필요) | 음성 21m00Tcm4TlvDq8ikWAM (Rachel) |
| 둘 다 없음, 로그인 안 함 | TTS | 로컬 Kokoro, 음성 am_michael (비영어의 경우 --voice 전달) |
GEMINI_API_KEY (두 용도에 하나의 키) | 캡처 비전 캡션 + Lyria BGM | 설정 안 함 -> 자막은 DOM 컨텍스트만 사용; BGM은 로컬 MusicGen 사용 (최초 실행 시 약 300MB 다운로드) |
흐름
Step 0.0 - 브리프 확인 (1회 질문 후 제작)
Step 0 전에, 한 번의 메시지로 출시 비디오를 실질적으로 결정하고 추론할 수 없는 항목만 확인하세요. — 추천 기본값으로 시작하고, 사용자가 이미 제공한 내용은 건너뛰세요: 앵글/초점(제품 전체, 주요 기능, 오퍼/CTA), 길이(기본 ~30-90초; 최대 ~3분), 그리고 — /hyperframes가 이미 설정하지 않은 경우 — 화면비(기본 16:9; 세로/소셜용 9:16) 및 언어. 프리셋은 브랜드 캡처에서 파생되며, 질문하지 않습니다. 완전히 지정된 요청의 경우 이 단계를 건너뛰고 제작하세요.
Step 0 - 비디오 프로젝트 초기화
현재 작업 디렉토리는 에이전트 워크스페이스 루트입니다. 모든 비디오 산출물은 PROJECT_DIR = videos/<project-name>/에 저장됩니다.
<project-name> 이름 지정: 사용자가 명시적으로 지정한 디렉토리명을 우선 사용합니다. 그렇지 않으면 <브랜드>-promo와 같은 짧은 케밥-케이스 이름을 선택하세요(워크스페이스 기본 이름이나 타임스탬프는 절대 사용 금지). URL에서 도메인/페이지 제목으로 파생합니다. capture/가 기록되면 이름이 고정됩니다.
초기화($PROJECT_DIR/hyperframes.json이 존재하지 않을 때만):
PROJECT_DIR="${LAUNCH_VIDEO_DIR:-videos/<project-name>}"
mkdir -p "$(dirname "$PROJECT_DIR")"
npx hyperframes init "$PROJECT_DIR" --non-interactive --skip-skills --example=blank
hyperframes init는$PROJECT_DIR에 일반AGENTS.md/CLAUDE.md를 생성합니다. 그대로 두되, 일반 지침을 런타임 제약 조건으로 취급하지 마세요 — 이 스킬이 신뢰할 수 있는 정보 소스입니다.
제약 조건(각 위반은 이후 단계를 망가뜨림):
- 워크스페이스 루트에서
hyperframes init를 실행(또는AGENTS.md/CLAUDE.md생성)하지 마세요.PROJECT_DIR내부에hyperframes/하위 프로젝트를 만들지 마세요. - 모든 서브에이전트 디스패치 컨텍스트에는
PROJECT_DIR: <path>줄이 포함됩니다. 서브에이전트는 이를 프로젝트 루트로 취급합니다. - cwd 규율(마스터 포함): 모든 Bash 명령은
(cd "$PROJECT_DIR" && ...)서브쉘로 실행하세요 — 절대cd "$PROJECT_DIR" && ...를 베어로 사용하지 마세요(지속적인 cwd 변경으로 이후 상대 경로가 잘못됨).
Step 0.5 - API 키 안내
건너뛰는 경우: $PROJECT_DIR/.env가 이미 존재하거나 context.log가 비어 있지 않은 경우. 그렇지 않으면 설정된 것을 감지하고(HeyGen TTS = $HEYGEN_API_KEY / $HYPERFRAMES_API_KEY / ~/.heygen/credentials; ElevenLabs / Gemini = 해당 환경 키), 항상 일시 중지하고 질문하세요 — 작동 가능한 구성이 감지되어도 스스로 진행하지 마세요:
감지된 항목: <요약>. 클라우드 키는 선택 사항입니다. 없으면 설정되지 않은 제공자는 로컬로 폴백합니다(TTS -> Kokoro, HeyGen이 설정되지 않은 경우; BGM -> MusicGen). 다음 중 하나로 답변하세요:
- 키 붙여넣기 ->
$PROJECT_DIR/.env에 작성합니다- "go" -> 현재 설정된 상태로 진행합니다
- "skip" -> 설정되지 않은 항목은 로컬 폴백으로 진행합니다
키 붙여넣기 -> $PROJECT_DIR/.env에 쓰기/편집, 한 줄에 KEY=value 하나씩(같은 이름의 키는 덮어쓰며, 값은 검증하지 않음). "go" / "skip" -> Step 1.
Step 1 - 캡처 (Phase 1)
- 프롬프트에서
SKILL_DIR및 명시적TARGET_URL을 확인합니다. Step 0이 실행되었는지 확인합니다. $PROJECT_DIR/context.log가 있으면 읽고 아래 Resume 테이블을 사용하여 완료된 단계를 건너뜁니다.- 입력 분류(Step 1.0)하여
CAPTURE및VO_MODE를 설정한 다음, 일치하는 경로를 실행합니다. 두 경로 모두 동일한 다운스트림 명령을 공유합니다.
Step 1.0 - 입력 분류 (CAPTURE + VO_MODE 설정)
| 입력 형태 | 수행할 작업 |
|---|---|
| 프롬프트에 명시적 URL이 있음 | TARGET_URL = 해당 URL; CAPTURE=yes; 음성 해설 질문 없음(내레이션은 캡처된 사이트에서 옴). 경로 (A). |
| 사용자가 스크립트 또는 브리프를 붙여넣었거나 지목함 | (1) 원문 그대로를 $PROJECT_DIR/user_script.txt에 저장. (2) 음성 해설 질문 한 번(아래) -> VO_MODE 설정. (3) 스크립트에서 캡처 대상 확인(아래) -> CAPTURE 설정. |
| 제품이 없는 스크립트 문구 없는 주제/브리프 | CAPTURE=no; 음성 해설 질문 없음. 경로 (B). |
음성 해설 질문(사용자가 실제 스크립트 문구를 제공한 경우에만) — 한 줄로 질문하고 대기:
스크립트를 그대로 음성 해설로 사용할까요, 아니면 화면에 더 적합한 씬 내레이션으로 재구성할까요?
- 그대로 — 원문을 유지합니다. 씬을 분할하고 비주얼만 짝지어줍니다. 길이는 스크립트를 따릅니다.
- 재구성 — 브리프로 취급하고 씬당 1-2문장으로 더 간결한 내레이션을 다시 작성합니다.
VO_MODE = verbatim | restructure (기본 restructure); Step 2의 story-design으로 전달.
스크립트에서 캡처 대상 확인 — 기본적으로 사이트를 찾아 크롤링합니다(실제 브랜드 토큰이 프리셋 폴백보다 우선). 사용자가 거부한 경우에만 건너뜁니다("웹 없음/텍스트 전용/캡처 안 함"). 순서: (1) 스크립트에 명시적 http(s):// URL이 있음 -> 사용, 알림, CAPTURE=yes; (2) 명확한 브랜드/제품 이름 -> WebSearch로 공식 사이트 검색, 크롤링 전에 확인된 URL을 한 줄로 사용자에게 확인(거절/신뢰할 수 없음 -> CAPTURE=no); (3) 파생 가능한 것 없음 -> CAPTURE=no.
캡처 + 사용자 스크립트 공존: 크롤링은 브랜드 토큰 + 자산 + 시각적 레지스터만 제공합니다. 내레이션 스파인은
user_script.txt(VO_MODE를 통해 준수)이며, 사이트 자체 카피는 아닙니다.
(A) 캡처 경로 (CAPTURE=yes) :
(cd "$PROJECT_DIR" && npx hyperframes capture "<TARGET_URL>" -o ./capture)
(B) 비캡처 경로 (CAPTURE=no) — 최소 캡처 패키지를 합성합니다. 다운스트림은 동일합니다. **사용자(마스터)**가 프리셋을 선택합니다(추론할 사이트 없음; 사용자 의도에 따라 19개 프리셋 중 선택하거나 짧은 질문). 전체 스크립트/브리프는 visible-text.txt로 이동합니다. colors:[]는 프리셋 팔레트 폴백을 트리거합니다(사용자가 브랜드 색상을 명명한 경우에만 colors 채우기):
(cd "$PROJECT_DIR" && mkdir -p capture/extracted capture/assets)
(cd "$PROJECT_DIR" && cat > capture/extracted/tokens.json <<'JSON'
{ "title": "<브랜드/제목>", "description": "<한 줄>", "colors": [], "fonts": [], "headings": [], "sections": [], "ctas": [], "svgs": [], "cssVariables": {} }
JSON
)
(cd "$PROJECT_DIR" && echo '{}' > capture/extracted/design-styles.json)
(cd "$PROJECT_DIR" && printf '%s\n' "<전체 사용자 스크립트 / 브리프>" > capture/extracted/visible-text.txt)
사용자가 이미 최종
narrator_scripts.json을 가지고 있다면$PROJECT_DIR/에 배치하세요. Resume 테이블은 story-design을 건너뜁니다.
두 경로 모두 공유하는 다운스트림(경로 B는 build-design에 --style <선택된-프리셋>을 추가합니다. 경로 A는 자동 추론을 위해 생략합니다.):
(cd "$PROJECT_DIR" && node <SKILL_DIR>/scripts/derive-context-pack.mjs --capture ./capture)
(cd "$PROJECT_DIR" && node <SKILL_DIR>/phases/design-system/scripts/build-design.mjs ./design-system --no-emit) # 경로 B: --style <선택된-프리셋> 추가
검증(누락된 항목이 있으면 중단하고 보고. capture/BLOCKED.md가 존재하면 사이트가 크롤링을 차단한 것임 — 내부 지침을 따르세요.):
[ -