demo-video
완성된 디자인 비디오가 필요합니다. 이 기술은 테스트를 거친, 모든 기능이 포함된 파이프라인입니다. HyperFrames(HTML→비디오)를 기반으로 하지만, 앱을 직접 녹화하는 방법, 이 머신의 ffmpeg 해결 방법, 정확한 편집 레시피, 브랜드 디자인 시스템, 그리고 시간을 낭비하게 만드는 함정 등 재발견하기 어려운 부분들을 추가했습니다.
여기에는 브랜드가 적용되어 있지 않습니다. 디자인은 하나이며 교체 가능한 토큰을 사용합니다. 비디오가 어떤 브랜드에 속하는지는 단계일 뿐 가정이 아닙니다. — Phase 0B를 참조하세요.
🚦 단계는 작업 순서가 아닌 주제별로 그룹화됩니다.
아래 내용을 순서대로 따르기 전에 이 내용을 먼저 읽으십시오. 캡처 메커니즘은 함께 속해 있기 때문에 먼저 문서화되었지만, 캡처가 가장 먼저 할 일은 아닙니다:
컨셉이 먼저입니다: 이것이 무엇을 위한 것인가? → 아크 → PLAN.md (+ SCRIPT.md) → 승인
(이것은 `video-plan` 기술에서 담당하며, 여기서는 다루지 않습니다) │
│
↓ 여기서부터 푸티지가 존재합니다 ───────────────────────────────────────────────────────────────┘
Phase 0 환경 → 0B 브랜드 → 1A 캡처 / 1B 가져오기 → 3 준비 → 4 구성
→ 5 검증 → 6 렌더링
먼저 촬영하는 것이 더 빨라 보이지만 실제로는 그렇지 않습니다: 아크는 리뷰 중에 변경되는 것이며, 합의되지 않은 아크에 대해 캡처된 모든 비트는 다시 캡처해야 합니다. Phase 0과 0B는 일찍 실행할 수 있는 두 가지 작업입니다. 도구를 설치하고 팔레트를 결정합니다. Phase 1의 모든 것은 승인된 계획이 있어야 시작됩니다.
🚀 빠른 시작 — 빠른 경로
🚨 호출자가 이 모드를 선택합니다. 절대 당신이 선택하지 마십시오. 한 번의 질문으로 제안할 수는 있습니다. 상황에 따라 결론을 내리면 안 되며, 특히 다음 상황은 동의로 간주되지 않습니다:
- 호출자가 기술 패키지를 첨부했거나 압축을 풀었습니다 — 이것은 누군가 도구를 설치하는 방법일 뿐, 그들이 무엇을 만들고 싶어하는지에 대한 진술이 아닙니다.
- 요청이 탐색적으로 들리거나 브리프 없이 왔습니다.
- 그들이 처음으로 요청한 것입니다.
- 빠른 경로가 더 편리하다고 생각하는 경우.
"example.com의 비디오를 만들어 주세요"라고 말하는 사람은 example.com의 비디오를 요청한 것입니다. 그들이 실제로 일회용을 원했다고 결정하고 그들에게 알리지 않고 브랜드가 없는 1080p 초안을 제공하면, 그들은 완성된 작품을 기대했을 때 정확히 되돌릴 수 없는 부분(아크, 단어, 브랜드)을 건너뛰게 됩니다.
명확하지 않을 때는 물어보십시오. "빠른 스모크 테스트인가요, 아니면 실제로 다른 사람에게 보여줄 비디오인가요?" 한 줄로, 두 모드 중 어느 것인지 결정됩니다.
아래 승인 게이트는 누군가가 볼 비디오를 잘못 만드는 데 드는 비용이 크기 때문에 존재합니다. 일회용 실행은 그렇지 않으며, 캡처가 작동하는지 확인하기 위해 리뷰어를 컨셉 라운드에 참여시키는 것은 좋은 도구가 처음 10분 안에 버려지는 방법입니다. 두 실패 모두 실제입니다. 어떤 것이 적용되는지는 호출자만 알고 있습니다.
빠른 경로(호출자가 선택한 경우):
- 다시 말해 확인하세요 — 한 문장: "스모크 테스트로 진행하므로 승인 라운드와 브랜드를 건너뜁니다. 전체 프로세스를 원하시면 말씀해 주세요." 발표보다 확인이 중요합니다: 다른 모드에 있는 호출자에게 마지막으로 저렴하게 수정할 기회를 줍니다.
- 두 줄짜리
PLAN.md— 아크를 문장으로, 세 개 또는 네 개의 비트.SCRIPT.md없음, 서명 라운드 없음. - 중립 팔레트. 브랜드 추출 없음, 미리보기 승인 없음.
- 무음. 내레이션 없음, ElevenLabs 키 없음, 대본 확인 없음.
- 1080p만. 4K 없음, 게시 단계 없음.
- 내부 전용 — 고객에게 보여주지 않으며 공개적으로 게시되지 않습니다. 누군가 보여주고 싶어하는 경우, 그것은 다른 비디오입니다: 초안에 승인을 사후 적용하는 대신 제대로 실행하십시오.
이 파일의 다른 모든 내용(캡처 경로, 검증, 모호한 동의 중단)은 여전히 적용됩니다. 그것들은 의식이 아닙니다. 그것들은 깨진 비디오가 괜찮아 보이는 것을 방지합니다.
🛑 컨셉 게이트
이 기술은 요청으로 시작하지 않습니다. 승인된 PLAN.md (고객 대상의 경우 SCRIPT.md도 함께)로 시작합니다. 위의 빠른 경로는 유일한 예외이며, 방 밖의 누구도 결과를 볼 수 없을 때만 사용할 수 있습니다.
PLAN.md가 없다면, 그것은 video-plan 기술의 작업이며, 한 번의 패스가 필요합니다: 비디오의 목적, 데모 대 가이드, 언어, 아크, 비트 목록, 카피. 먼저 그 작업을 수행하고 돌아오십시오. 계획을 작성하기 위해 앱을 읽는 것은 괜찮습니다. 녹화하는 것은 아닙니다.
누가 계획을 작성했든 관계없이 두 가지를 확인해야 하며, 둘 다 질문이지 발표가 아닙니다:
먼저 분석할지 물어보십시오. "애플리케이션을 살펴보고 무엇을 보여줄지 제안할까요, 아니면 이미 알고 계신가요?" 제품을 제대로 읽는 데는 실제 시간이 걸리며, 호출자는 다른 시작 화면이나 완성된 아이디어를 가지고 있을 수 있습니다. 당신의 가정에 그들의 시간을 소비하지 마십시오.
촬영 전에 비트 목록을 승인받으십시오. 전체 PLAN.md를 다시 승인받을 필요는 없습니다. 계획은 이미 승인되었습니다. 그러나 곧 녹화할 구체적인 샷 목록(이 네 개의 비트, 이 순서로, 이것들을 강조)을 승인받아야 합니다. 한 번의 메시지면 충분하며, 마지막으로 저렴한 순간입니다. 캡처 후 순서를 변경하면 다시 촬영해야 합니다. 다른 아크에 맞게 편집된 비트는 기존 컷에 들어맞지 않기 때문입니다.
채팅에서 캡처 대상을 확인하십시오. 어떤 환경이 녹화될지, 따라서 어떤 버전의 제품이 대상이 될지는 사용자의 결정이며 대상은 이동합니다.
🚦 첫 번째 결정: 푸티지는 어디서 오는가?
대상이 도달 가능한 웹 페이지인 경우 → 직접 녹화하십시오. 스크린캐스트를 요청하지 마십시오.
도달 가능한 URL? ── 예 ──┬── 사용자(또는 고객) 소유, 브리프가 있음
│ │ └─▶ Phase 1A · 캡처 (references/playwright-capture.md)
│ │
│ └── 다른 사람의 웹사이트
│ └─▶ Phase 1A · 캡처, plus references/foreign-sites.md
│ (권한 게이트, 동의 장벽, 고정 헤더,
│ 지연 로딩 rect 드리프트 — 먼저 읽으십시오. 캡처
│ 프리미티브는 타인 DOM에서 안전하지 않습니다)
아니요 (데스크톱 앱, Figma, 네이티브 도구, 모바일,
또는 사용자가 이미 .mov를 제공한 경우)
▼
Phase 1B · 스크린캐스트 가져오기
자체 앱과 타사 사이트는 다른 캡처 패스를 가진 동일한 파이프라인입니다. 구성, 디자인 시스템, 검증 레이어 및 음성 해설은 변경되지 않습니다. 브랜드 추출은 이미 모든 라이브 웹사이트를 읽습니다. 변경되는 것은 기본적으로 공개 전용이며, 상태를 시드할 수 없고, 아무것도 쓰지 않아야 하며, 아래에서 움직이는 DOM을 측정해야 한다는 것입니다. (인증된 타사 캡처는 가능하지만 권장되지 않습니다. 도메인별 명시적 승인, 브라우저 샌드박스 활성화, 세션 파일 삭제가 필요합니다 — references/foreign-sites.md §0.)
이것은 스타일 선호도가 아닙니다. 캡처 경로는 더 나은 푸티지 그리고 대략 절반의 작업입니다. 손으로 한 스크린캐스트는 타임라인을 픽셀에서 역공학하고, 작성자의 재시도를 찾아내고, 모든 스포트라이트를 수동으로 측정하고, 브라우저 크롬을 자르고, 개인정보를 감사해야 합니다. 스크립트된 캡처는 구조적으로 이러한 문제가 전혀 없으며, 크롬이 없으며, 텍스트 크기를 선택할 수 있고, UI가 변경될 때 다시 실행할 수 있습니다. 동일한 흐름에서 측정: 밀집된 프레임 스캔이 필요한 71초의 스크린캐스트 대 모든 소스 시간과 요소 rect가 beats.json으로 전달되는 28초 캡처 — 그리고 완성된 프레임에서 1.5배의 텍스트 크기.
그럼에도 불구하고, 사용자가 이미 녹화한 것이 있다면 캡처하기 전에 시청하십시오. 그것은 그들의 제품에 대한 그들의 모델을 인코딩합니다. 어떤 기능을, 어떤 순서로, 그리고 요점이 무엇인지 보여줄지에 대한 편집적 판단은 캡처 경로가 무료로 제공하지 않는 유일한 것입니다.
참조 자료는 필요할 때 읽으십시오. 미리 로드하지 마십시오:
| 필요 사항 | 읽기 |
|---|---|
| 이 비디오는 어떤 브랜드인가? (토큰, 로고, 타입 — 웹사이트도 가능) | references/brand-style.md |
| 앱을 직접 구동 및 녹화; 2배속; 커서; 인증; beats.json | references/playwright-capture.md |
| 대상이 소유하지 않은 웹사이트 (권한 게이트, 동의 장벽, 고정 헤더, 지연 로딩 rect 드리프트, 라이브 미디어) | references/foreign-sites.md — 캡처 전에 읽기 |
| 컨테이너 또는 CI에서 헤드리스 실행 (CJK/이모지 폰트 누락, 첫 번째 캡처에서 Chromium 중단, 설치 직후 "Executable doesn't exist") | references/container-capture.md |
capture-lib.js에서 무언가를 변경한 후 | node <skill>/scripts/test-foreign-sites.mjs — 로컬 픽스처, 네트워크 없음; 모든 케이스는 배송된 결함 |
| 스포트라이트가 잘못된 픽셀을 프레임으로 잡았지만 좌표는 정확함 | references/foreign-sites.md §4 — boundingBox 대신 stableRect로 측정 |
| 다른 언어로 다시 캡처; 타임라인을 재구축하지 않고 기존 컷의 타이밍 변경 | references/playwright-capture.md §9-10 |
| 재시도로 가득 찬 .mov 제공 — 깔끔한 테이크 선택 및 컷 | references/multiple-takes.md |
| ffmpeg/CLI 실행 안 됨, "0 GB free", bunx, 권한 문제 | references/pitfalls.md §6 + scripts/setup-render-env.sh 실행 |
| 정확한 컷/크롭/속도/정지/프레임 제거 명령 | references/ffmpeg-recipes.md |
| 디자인: 창, 스포트라이트, 카드, 크로스페이드, 프리즈 프레임 | references/design-system.md (+ assets/template.html) |
| 두 부분으로 구성된 기능 가이드 구축 (컨셉 패널, 액션 비트, 안무) | references/guide-track-build.md |
| 내레이션 / ElevenLabs 음성 해설, 할당량 + 음성 함정 | references/voiceover.md |
| 음성이 실제로 대본을 말하는가? (브랜드 이름, 약어) | scripts/verify-narration.mjs — 종료 코드 1 = 수정 |
| 앱이 캡처 전에 빈 화면, 500 오류, 또는 "오프라인"으로 렌더링됨 | references/pitfalls.md §17 |
| TIMELINE.md 계약; "0:12 드래그" 피드백에 대응 | references/timeline-and-review.md |
| 스포트라이트를 어디에 배치해야 하는가? (절대 눈대중으로 하지 마십시오) | references/design-system.md → "NEVER eyeball coordinates" |
| 스포트라이트 가장자리가 패딩을 아무리 줘도 무언가를 계속 자름 | scripts/measure-spots.mjs — 대신 레이아웃의 여백 측정 |
| 컨트롤을 정말로 프레임할 수 없음 (어떤 가장자리에 6px 대역도 없음) | references/design-system.md → "Sometimes there is no box" |
| 앱의 크롬이 캡션 카드가 있어야 할 위치에 있음 | references/design-system.md → 비트별 카드 배치 + 컷에서 카드 분할 |
| 스틸이 클릭 후 상태를 보여줌 (빈 공간에 스포트라이트) | references/playwright-capture.md §16 — _hover 마크에서 정지 |
| 스크립트된 채팅 메시지가 사라짐; 에이전트가 "완료"되었지만 실제로는 아님 | references/playwright-capture.md §17-18 |
| "내 푸티지가 왜 정지/정렬 오류/에러인가" | references/pitfalls.md |
| 클릭 시 검은 원; 조용히 아무것도 하지 않은 수정 | references/pitfalls.md §11-13 |
| 검사가 PASS라고 표시했지만 실제로는 잘못됨 | references/pitfalls.md §15 |
| 모든 렌더링 전 (기계적 감사, 종료 코드 1 = 수정) | scripts/audit-composition.mjs |
| 대상이 실제로 보이는가? (스팟 여백 + 카드 폐색; 종료 코드 1 = 수정, 종료 코드 2 = 확인 불가) | scripts/verify-material.mjs |
| 스냅샷 후: 스포트라이트당 확대 크롭 (전체 프레임 읽기는 잘린 텍스트를 놓침) | scripts/crop-spots.mjs |
| 프레임이 음성이 말하는 내용을 보여주는가? (내레이션 가이드, 주제별) | scripts/verify-topics.mjs |
| 앱이 수행한 작업을 기록 — 이전 스냅샷, 이후 복원 | scripts/app-state.mjs |
| 비디오 옆에 독립형 교육 문서 (요청 시에만) | references/companion-docs.md |
렌더링이 아닌 스냅샷으로 루프를 작업하십시오. snapshot --at t1,t2,…는 몇 초가 걸립니다. 렌더링은 몇 분이 걸립니다. 스틸에서 프레이밍, 스포트라이트 좌표, 카피 및 개인정보를 올바르게 설정한 다음 한 번 렌더링하고 모션을 확인하십시오.
Phase 0 — 환경 (머신/세션당 한 번)
하나의 명령이 모든 경우를 처리합니다 — macOS 또는 Linux, 정상적인 머신, 누락되거나 제거된 ffmpeg, 누락된 HyperFrames, 또는 잘못된 "0 GB free" statfs 버그. 수동으로 진단하지 마십시오:
render_env="$(bash <skill>/scripts/setup-render-env.sh)" && eval "$render_env"
source <(…)를 사용하지 마십시오. Bash는 source의 상태를 보고하며, 프로세스 대체를 공급하는 상태를 보고하지 않습니다. 따라서 중간에 중단되는 부트스트랩(네트워크 없음, 설치 실패)은 성공을 보고하고 내보내기의 절반만 설정된 상태로 남깁니다. 먼저 캡처하면 실패가 표면화되고 실패 시 아무것도 적용되지 않습니다.
없는 경우 hyperframes(고정됨)를 설치하고, 전체 ffmpeg를 해결하며, 이 OS에 실제로 버그가 있는 경우에만 디스크 검사를 패치하고, HYPERFRAMES_FFMPEG_PATH, HYPERFRAMES_FFPROBE_PATH, PRODUCER_BROWSER_GPU_MODE 및 HYPERFRAMES_CLI를 내보냅니다.
ffmpeg라는 바이너리가 아닌 필터를 검사합니다. 파이프라인에는 fps/pad(Phase 3 프레임 고정), crop(Phase 1B 크롬 제거) 및 freezedetect(audit-composition.mjs + Phase 6 데드 에어 스윕)가 필요합니다. 두 개의 제거된 빌드가 일반적으로 이미 PATH에 있으며, 파이프라인 중간에 실패하기 전에 간단한 검사를 통과합니다: Playwright 번들 ffmpeg 및 Remotion 컴포지터 번들. 해결 순서: 전체 시스템 ffmpeg → brew(macOS) → ~/.hyperframes-cli의 ffmpeg-static/ffprobe-static 패키지(모든 플랫폼, sudo 불필요 — Linux의 일반적인 경로) → 마지막 수단으로 래핑된 Remotion 컴포지터 번들. 이 번들은 freezedetect가 없기 때문에 경고하며, 따라서 두 개의 프리즈 검사가 조용히 통과되므로 수동으로 확인해야 합니다(문제점 #1, #16).
그런 다음 가리키는 로컬 CLI($HYPERFRAMES_CLI)를 통해 렌더링하십시오. 절대 bunx/npx hyperframes를 사용하지 마십시오. 이는 매번 새로운 사본을 다시 생성합니다.
…
[번역을 위해 잘림]