Video Boost(구두 연설 강화)
프로젝트 디렉토리: 저장소 루트 (공개 저장소 github.com/Minerva67/video-boost; 로컬은 ~/CC/knock-video-boost/). HyperFrames 렌더링 + GSAP 타임라인 + 자체 구축 컴포넌트 라이브러리.
템플릿: runs/example/beats.mjs (구조 템플릿) + references/components.md (각 컴포넌트의 데이터 작성법). 판단 규칙은 전적으로 references/rules.md에 있음 (부하 유형, 섹션 구분, 레이아웃 순환, 템플릿 진입 순서, 소제목), 외부 문서에 의존하지 않음.
철칙 (사용자가 반복적으로 확인한 사항, 위반 시 재작업)
- 추가만 하고 수정하지 않음: 원본 영상의 화면, 장면 순서, 타임라인, 원음, 길이를 모두 그대로 유지. CTA도 마지막 몇 초에 겹쳐 놓으며, 영상을 길게 하지 않음.
- 카드는 구두 연설을 반복해서는 안 됨. 모든 이미지에 대해 테스트를 한 번 거침: '소리와 자막을 끄고, 이 이미지가 무엇을 더 제공하는가?' 답이 '같은 글자'라면 삭제. 자막이 이미 말하고 있는데 카드에 다시 쓰면 삼중 반복 (v4가 거부된 이유).
- 연기할 수 있으면 쓰지 말고, 실제 것을 얻을 수 있으면 연기하지 마라: 구두 연설이 실제로 존재하는 뉴스/보고서/제품/장소를 언급하면 우선 실제 스크린샷이나 사진을 배치 (
photo컴포넌트, 그 숫자를 강조 표시); 구두 연설이 'X 도구로 Y를 했다'면 X의 실제 인터페이스와 Y의 산출물을 연기 (Claude Code 세션 명령어 하나하나 입력 → 도구 호출 → 결과 테이블/보고서), 회색 막대 자리 표시 사용하지 않음 (v5→v6에서 지적받음). - 모식도 ≠ 조작: 모식도 인터페이스 (창 모서리에 '모식도' 표시)는 허용하지만, 원본 영상에 없는 관점을 추가하지 않음; 모든 숫자/출처는 실제 검색해야 함 (WebSearch+WebFetch로 페이지 원문 확인; 여러 매체의 기준이 다르면 구간을 쓰고 모두 표시), 예시 제목 유형 콘텐츠는 인기도/좋아요 숫자를 붙이지 않음.
- 얼굴을 가리지 않고, 비좁지 않게: 사람은 항상 하단 중앙에 붙어 있음 — 전체 화면 / 62% (일반 그래픽) / 50% (정보가 많은 그래픽, 사용자 10-02 요구 '정보량이 많으면 사람을 작게 하고 시각화할 공간을 많이 남겨라'). PIP (사람을 30% 구석으로 축소)는 거부됨.
- 스킨 = 테마, 기본값은 사용자 자신의 Knock〃 디자인 시스템 B 라인 밀도 (
brand/themes/knock/); 또한 비공개 테마 (brand/themes/<비공개 테마>/, 브랜드 규범 B 라인 따름). 테마 변경:node build.mjs runs/<name> --theme=<name>(public-<theme>/로 출력). Knock 버전 세부 사항: 종이 흰색 바탕, 문 노란색은 작은 색상 블록에만 사용,敲擊 오렌지 ≤5%, 1.5px 먹색 윤곽선, 그림자 없음; 오른쪽 상단 가로 로고 상주. Claude 스타일 스킨은 거부됨 ('디자인 시스템은 내 것을 사용하라'), Knock 삼색 대면적 화면 채움도 거부됨 ('너무 선명해서 피곤하다'). - 분할 로직: 여섯 가지 부하 유형 + 복합 유형 + 인접 세그먼트 다른 레이아웃 + 분기는 강화하지 않음, 규칙은
references/rules.md§1–2 참조 (사용자의 비디오 강화 PRD V3 및 '시각화 선택 규범 · 30 템플릿'에서 발췌, 완전히 포함). 저부하의 설득/의견 유형 구두 연설은 대부분의 시간을 전체 화면으로 돌아가고, 4–6개의 그래픽만 남겨야 함.
파이프라인
./prep.sh <비디오 파일> <name> # 원본 영상 복사 (HDR 자동 avconvert로 SDR 변환), 오디오 추출, medium 모델 beam5 전사, 구두점에 따라 재분할
# → runs/<name>/segs_beam.json 읽기, 교정 후 runs/<name>/script.txt 작성 (| = 자막 분할점)
.venv/bin/python align.py runs/<name> <길이> # 교정된 텍스트를 ASR 단어 수준 시간 + VAD 시간 보정에 정렬 → transcript.json / captions.json / voiced.json
.venv/bin/python fix_caps.py runs/<name> <길이> # <1s 또는 >9자/s인 자막 화면 자동 병합, 재정렬 (장/문장/멈춤을 넘어 병합하지 않음)
# → 먼저 runs/<name>/structure.md 작성 (논증 구조) → cut.md (편집 대본) → beats.mjs 작성 (runs/example/beats.mjs에서 복사하여 수정)
# 실제 소스 자료: node grab.mjs <URL> runs/<name>/assets/x.png --find "핵심 문장"; python3 commons.py "<영어 키워드>" runs/<name>/assets
node build.mjs runs/<name>
npx hyperframes lint runs/<name>/public # 0 error면 됨 (caption의 nested 경고는 알려진 문제)
HYPERFRAMES_BROWSER_PATH="/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" \
npx hyperframes render runs/<name>/public --sdr -q draft -o runs/<name>/draft.mp4 # 156s ≈ 100s
./review.sh runs/<name>/draft.mp4 <각 세그먼트 끝의 시간 지점...> # 연락처 시트 생성, 하나씩 확인
# → 편집자 심사: 독립적인 하위 에이전트 파견, 연락처 시트 + cut.md만 제공, references/editor.md §5에 따라 각 세그먼트를 '통과 / 반려'로 판단; 반려된 것은 수정 후 재심사
# 수정 완료 → -q draft 제거하고 공식 버전 output.mp4 생성
./evaluate.sh runs/<name> [--theme <테마>] [--platform xhs] # 마지막 단계: Eval (글자 크기/안전 영역 측정 + 23개 자동 검사) → runs/<name>/eval.md
# 기준 미달 시 배포 불가; WARN은 하나씩 판단하여 수정 가능하면 수정, 수정 후 재실행; 통과 후 → ~/Desktop/口播增强_<버전>_<테마>.mp4로 복사 → SendUserFile
모든 비디오는 Eval로 마무리되며, 배포 메시지에는 다음이 포함되어야 함: 기준 통과 여부, 자동 점수, 남은 WARN 및 그 이유.
환경: ffmpeg/ffprobe는 ~/.local/bin에; whisper 모델 ~/.cache/kvb-models/ggml-medium-q5_0.bin (디스크가 한 번 지워져서 prep.sh가 자동으로 다시 다운로드, 515MB); 렌더링은 시스템 Chrome 사용.
script.txt 교정 요점
- 먼저 prep의 두 가지 출력 확인: ① 'ASR 커버리지 검사', 누락된 문장은 하나씩 다시 전사하여 대본에 추가; ② '원본 영상에 내장된 하드코딩 자막', 감지되면 기본적으로 우리 자막을 끔 (
rules.md§8 참조). - 형식:
|는 화면 전환; 문장 끝에。를 쓰며, 이는 경계로만 작용하고 표시되지 않음; 물음표, 느낌표는 그대로 유지; 나머지 구두점은 쓰지 않음. - 오타만 수정하고, 표현 방식은 수정하지 않음; 기식음 (음/어) 제거 가능, 다듬거나 단어를 추가하지 않음. 고유명사는 실제 이름으로 작성 (ClockCode→Claude Code, Codeash→Codex).
- 들을 수 없는 단어:
.venv/bin/python retranscribe.py runs/<name> <시작> <종료> --terms "3–5개 해당 세그먼트 용어", 원속, 용어 추가, 0.8배 느린 재생의 세 가지 결과 제공. 여전히 확실하지 않으면 배포 시 시간 열과 함께 사용자에게 들어보도록 함. - 화면 분할: 세로 화면 ≤10자/화면 (라틴 문자는 반자로 계산), 의미적 멈춤에서 분할; 고유명사, 숫자+단위는 분리하지 않음; '의/와/에서'로 끝나서는 안 됨. 말하기 속도가 빠를 때 fix_caps는 문장을 넘지 않는 범위에서 병합, 상한 14자.
테마 (디자인 시스템 변경)
컴포넌트에 색상을 하드코딩하지 않고, 모두 역할을 통해 처리 (brand/themes/<name>/theme.json):
| 역할 | 용도 | Knock | 비공개 테마 |
|---|---|---|---|
| paper / card | 캔버스 / 카드 | 종이 흰색 / 흰색 | Gray50 / 흰색 |
| ink · ink70 · ink40 | 본문 3단계 회색 | 먹색 계열 | Gray900/700/500 |
| line · lineSoft | 구분선 | 석회색 | Gray300/100 |
| mark + markInk | 강조 상태 채움 (현재 항목, 체크, 진행 표시) | 문 노란색 | Tappy Green |
| accent | 한 화면에 한 번의 강조 (종료 상자, 명령 기호, 키워드) | 敲擊 오렌지 | Signal Purple |
| frame · stroke · shadow · radius | 카드 테두리/그림자/모서리 둥글기 | 1.5px 먹색 윤곽선, 그림자 없음, 18 | 1px 연회색 테두리+매우 연한 그림자, 16 |
| fontCn / fontEn / fontMono + fonts[] | 글꼴 (로컬 ttf, 렌더링 시 인터넷 연결 없음) | Outfit | Plus Jakarta Sans / Inter / JetBrains Mono |
| logo · logoPill | 오른쪽 상단 로고, 캡슐형 적용 여부 | 적용함 | 그대로 배치 |
| caption.style | 자막: pill 캡슐 가라오케 / stroke 흰색 글자 검은색 윤곽선 | pill | stroke (비공개 테마 PRD V3 자막 규범) |
새 디자인 시스템을 적용하는 단계: ①해당 규범을 읽고 B 라인/제품 UI 밀도에 해당하는 항목을 찾음 (비디오 오버레이는 절제해야 하며, 마케팅 A 라인의 큰 색상 블록은 가져오지 않음); ②브랜드 색상을 mark (대면적을 채워도 눈에 거슬리지 않는 것)와 accent (한 곳에만 나타나는 것)에 할당, 포화된 브랜드 색상은 차라리 mark로 낮추어 바탕을 채우지 않음; ③글꼴 OFL 버전을 테마 디렉토리에 배치; ④theme.json 생성 → build → eval 실행 + 수동 H4/H6; ⑤흰색 배경, 밝은 발광 등의 장면에서 자막 가독성 확인 (stroke 스타일은 윤곽선을 두껍게 해야 함).
beats.mjs 작성: 먼저 판단, 그 다음 컴포넌트 선택
0단계: 먼저 구조를 정리한 다음 소제목 작성
전체 텍스트를 읽고 runs/<name>/structure.md 작성: 논점, 구조 유형 (경로 / 프레임워크 / 병렬 / 문제→해결 / 대비), 각 세그먼트의 역할과 결론. 소제목 = 역할 단어 · 결론 (≤12자), 이어서 읽으면 논증 그 자체가 되어야 함. 한 세그먼트씩 따로 이름을 붙이면 주제 태그에 불과함 (사용자가 두 번 거부함). 세부 규칙 및 예시는 references/rules.md §4 참조.
1단계: 편집 대본 — 먼저 '편집자가 여기서 어떤 화면을 자를지' 생각 (가장 중요, references/editor.md 참조)
먼저 runs/<name>/cut.md를 작성한 다음 beats.mjs를 작성. 세그먼트별로 채움: 구두 연설이 무엇을 말하는지 → 기능 (설명 / 증명 / 주의 집중 재설정, 해당되지 않으면 그림을 추가하지 않음) → 편집자가 자를 화면 → 소스 자료 등급 → 왜 더 높은 등급을 사용하지 않는지.
- 소스 자료 등급은 높은 순서대로 찾음: ①실제 소스 자료 (뉴스/공식 웹사이트 스크린샷, 실제 사진, 실제 인터페이스,
grab.mjs/commons.py로 가져오고photo컴포넌트로 배치) → ②데모 (cc/folio/resume/checktable) → ③데이터 그래픽 → ④텍스트 카드. ③④를 선택할 때는 구체적인 이유를 반드시 작성해야 함. - 구두 연설이 실제로 존재하는 것을 언급하면 (뉴스, 보고서, 회사, 제품, 장소, 사람), 먼저 ①을 시도.
- 하나의 화면은 한 가지 일만 말하며, 구두 연설 순서대로 항목별로 진입; 빈 칸, 전체 테이블을 한 번에 배치, 큰 빈 공간이 나타나면 분할하거나 소스 자료를 변경해야 함.
- 단지 의견, 전환, 감정, 구두 요약 → 전체 화면, 그림을 추가하지 않음 (느린 확대 가능). 전체 비디오에 4–6개의 그래픽이면 충분.
2단계: 컴포넌트 선정
소스 자료 등급이 정해지면 컴포넌트를 선택. ③④ 등급은 내용 모양에 따라 references/rules.md §6의 표를 참조; 컴포넌트 작성법은 references/components.md 참조.
- 전체 비디오에 'N개 포인트' 구조가 있을 때, 진행 표시는 build가 CH + TRACK에 따라 자동 생성.
cc는 '명령 → 단계 → 산출물'의 모든 소프트웨어 조작을 연기할 수 있으며, AI 도구에 국한되지 않음.- 구두 연설에 '댓글 / 팔로우 / 쪽지'가 나타나면
cta를 사용. - 라이브러리에 적절한 컴포넌트가 없으면
components.md末尾의 '새 컴포넌트 목록'에 따라 새로 작성. - 구두 연설 외의 실제 데이터를 사용하려면 먼저
rules.md§7의 경계를 확인.
HyperFrames 공식 디렉토리 (npx hyperframes catalog)에는 tiktok-follow / yt-comment-card / claude-exchange / chatgpt-exchange / code-typing 등의 기성 블록이 있지만, 플랫폼 색상 및 가짜 계정/댓글/좋아요가 포함되어 있음 — 동작만 빌리고 Knock 스킨으로 교체, 가짜 소셜 증명을 사용하지 않음. 새 컴포넌트는 components.mjs + brand/components.css에 작성하며, 진입 순서는 references/rules.md §2를 따름; 작성 목록은 references/components.md末尾의 '새 컴포넌트 목록' 참조.
글자 크기 (감각적으로 정하지 않음)
모든 그래픽 텍스트는 6가지 글자 크기만 사용: hero 140 / display 96 / title 54 / body 36 / small 28 / micro 22, 자막 76은 화면에서 가장 큰 읽기 텍스트. 하나의 그래픽은 최대 3가지 크기; dense는 글자 크기를 키우지 않음. 규범, 업계 근거 및 플랫폼 안전 영역은 references/typography.md 참조, Eval의 T1–T5, S1에서 실제 측정하여 확인.
모션 효과 소재 라이브러리 (GSAP 타임라인에 연결하고 프레임별로 정렬할 수 있는 것만 사용)
- GSAP 전체 플러그인 세트 (2025년부터 무료, 상업적 사용 가능; 이미 node_modules에 있으며 build가 자동 로드):
DrawSVG선 그리기,MorphSVG모양 변형 (예: '패치'가 부서지는 것),MotionPath경로 따라 이동 (예: 탈출 궤도의escape컴포넌트). - rough.js (MIT): 손으로 그린 강조 표시. beat에
annot: [{ sel, kind: 'circle'|'underline'|'box'|'strike', at }]작성; 경로는 고정 시드를 사용하여 Node에서 생성, 매번 렌더링 시 동일; 결론에만 사용, 각 그래픽당 ≤2곳. - HyperFrames 공식 컴포넌트 디렉토리 (Apache-2.0): 동작만 빌리고 현재 테마의 스킨으로 교체.
- 사용 가능하지만 제한 있음: Lottie 무료 애니메이션은 상업적 사용 가능하지만, 원본 파일을 재배포할 수 없으며 로컬에만 남기고 공개 저장소에는 넣지 않음. 사용하지 않음: 순수 CSS 애니메이션 라이브러리 (프레임별로 정렬 불가).
브랜드 로고 / 아이콘 (실제, 손으로 그리지 않음)
그래픽에 제품/회사 이름이 나타나면 이름 앞에 실제 로고를 추가: 텍스트에 :openai: ChatGPT라고 쓰면 md()가 brand/icons/openai.svg를 인라인으로 삽입.
- 아이콘 가져오기:
./fetch_icons.sh openai gemini google claudecode codex deepmind ...(Lobe Icons, MIT;si:xiaohongshu는 Simple Icons, CC0); 출처는brand/icons/SOURCES.txt에 기록. - 모든 것은 단색 버전 사용 (테마 ink 색상 상속): 컬러 로고 (Gemini 그라데이션, Google 4색)는 '강조색 한 화면에 한 번' 규칙을 깨뜨림.
- 이름과 로고는 실제 소유권과 일치해야 함 (Veo는 DeepMind 로고 사용); 라이브러리에 없는 브랜드는 그냥 글자만 쓰고 유사한 아이콘으로 대충 채우지 않음.
- 단지 지칭용 (누구의 제품인지), 협업/보증을 암시하지 않음.
3단계: 시간
모든 시간은 t('…원문…')를 사용하여 교정 원고에서 가져옴 (초를 직접 입력하지 않음), 그래픽 요소는 키워드가 말해지는 순간에 나타남; 명령어 유형 텍스트는 한 글자씩 입력됨 (dur은 대략 그 문장의 길이와 같음).
카메라 워크 규칙 (beats.mjs의 CAM에 작성)
| 레이아웃 | 사용 시점 | 매개변수 |
|---|---|---|
full 전체 화면 | 사람이 콘텐츠일 때: 후크, 의견, 전환, '예전에는 어떻게 했는지'에 대한 설명, 마무리, CTA | s 1 |
split 자리 양보 | 그래픽이 정보를 전달할 때만; 두 그래픽 세그먼트 사이의 간격이 < 4s이면 전체 화면으로 돌아가지 않음 (줄였다 늘리는 것을 피하기 위해) | s .62 하단 붙음 |
dense 밀집 | 정보가 많은 그래픽 (테이블 ≥8행, 목록 ≥6항목, 모식도 세션/보고서/이력서), beat에 dense: true 작성; 남은 공간은 below를 사용하여 두 번째 시각화 레이어를 배치하고, 글자 크기를 키우지 않음 | s .50 하단 중앙, 그래픽 영역 760px (rules.md §5 참조) |
push 느린 확대 | 핵심 판단, 정의, 마무리로 회상 | 1.00→1.06, d 5–9s |
punch 하드 컷 확대 | 후크에만 사용, 장 전환 시 하드 컷으로 돌아옴 | s 1.14, d 0; 셀카는 beats에서 LAYOUT.punch를 1.07로 낮춤 |
자리 양보 (split)는 snapBefore()를 사용: 앞쪽에서 멈춤만 찾아서 사람이 먼저 자리를 양보하고 그래픽이 나중에 진입하도록 보장 (build는 위반하는 그래픽에 대해 경고, Eval C6 검사). 나머지 이동은 snap()을 사용하여 말하기 멈춤에 맞춤 (voiced.json의 간격; ±0.7s 내에 찾을 수 없으면 ±1.4s로 완화; 말하기 속도가 너무 빨라 멈춤이 전혀 없으면 가장 가까운 자막 분할점으로 후퇴), 카메라는 단어 중간에 움직이지 않음; split의 착지 지점은 그래픽 진입보다 빨라야 함.
Eval (배포 전 반드시 실행)
파이프라인 마지막 단계 ./evaluate.sh runs/<name> (내부에서 먼저 node audit.mjs를 실행하여 글자 크기와 위치를 실제 측정한 다음 python3 eval.py 실행) → eval*.md: 기준 A1–A5 (통과하지 못하면 배포 불가) + 자동 B1–B6/C1–C5 + 수동 H1–H6 점수표. 기준, 임계값, 출처, 기준 점수는 references/eval.md 참조. 배포 시 보고: 기준 통과 여부, 자동 점수, 주요 WARN 및 수용 가능한 판단 항목인지 여부.
배포 전 자체 점검 (리뷰 연락처 시트 확인, 각 세그먼트 마지막 프레임 + 각 모식도 인터페이스 3–4프레임)
- 카드가 자막을 반복하고 있는지? 있으면 삭제.
- 글자/요소가 경계를 벗어나거나, 자막 영역 (y 1520–1670)을 침범하거나, 얼굴을 가리지 않는지?
- 모식도 인터페이스: 빈 컨테이너가 내용보다 먼저 노출되는지 (전체 블록이 페이드 인되어야 함)? 긴 내용이 자동으로 위로 스크롤되는지? 숫자에 출처가 있는지?
- 진행 표시가 맞는지 (현재 지점 / 완료 / 회고 모두 체크)?
- 길이 = 원본 영상 (ffprobe로 확인).
배포 멘트: 각 그래픽이 몇 초에 있는지, 시청자에게 무엇을 더 제공하는지 설명; 무엇이 모식도이고 무엇이 실제 검색인지 (출처 링크 포함); 사용자에게 들어볼 불확실한 글자도 함께 제공.
알려진 함정
- iPhone/Clips 원본 영상은 종종 HLG HDR: 색상 태그만 변경하면 피부색이 노래짐,
avconvert -p Preset1920x1080사용 (prep.sh에서 이미 처리); 렌더링 시--sdr추가. - Whisper는 오프닝 무음 시간을 0으로 당길 수 있음 → align.py의 VAD 시간 보정에서 처리; 긴 문장에 구두점이 없음 → resegment.py.
class="clip"요소에서 opacity를 애니메이션할 수 없음, 나가기 애니메이션은 내부 레이어에 적용; GSAP 타임라인은 paused 상태여야 하며window.__timelines["main"]에 연결해야 함.- Python에서 components.mjs를 수정할 때
'\n'이 실제 줄바꿈으로 이스케이프되어 JS 구문 오류가 발생할 수 있음 —'\\n'사용. - GSAP은
left/top을 애니메이션할 수 없음 (lint가 gsap_non_transform_motion을 보고) — x/y를 사용하고, 너비가 필요하면 페이지 스크립트에서 clientWidth를 측정. - 템플릿 문자열
${}는 Node에서 평가되므로, 그 안에document.*를 작성하지 말고 출력될 JS 문자열에 넣어야 함. - 리뷰 프레임을 삭제할 때
rm와일드카드를 사용하지 마십시오 (보안 검사에 차단됨); 동일한 이름의 파일을 덮어씁니다.
버전 역사 (취향 진화, 뒤돌아보지 마세요)
v1 Knock 삼색 화면 채움 + PIP → 거부 (너무 화려하고 얼굴을 가림) | v3 Claude 스킨 → 거부 (내 디자인 시스템을 사용하라) | v4 PRD 모든 구간 강화 → 거부 ('당신은 그가 말한 것을 시각화하고 있을 뿐이다') | v5 진행/메커니즘 다이어그램/모식도 mock만 유지 ✓ | v6 모식도를 실제 인터페이스 + 실제 데이터로 변경 ✓ | v7 포트폴리오/이력서 모식도 + 카메라 워크 규칙 추가 ✓ ('이번 버전은 매우 좋다') | 10-01 skill 첫 실행 ai-value + 테마화 (Knock/비공개 테마) + Eval v1 | 10-02 일반화하여 '내용 모양 → 컴포넌트'로 만든 후 블라인드 테스트에서 많은 테이블 텍스트 카드가 나옴 → 거부 ('시각화가 예전처럼 좋지 않다') → 편집자 관점 추가: 편집 대본 + 소스 자료 등급 + 실제 소스 자료 컴포넌트 + 심사