HyperFrames VLOG 편집은(는) 무엇을 하나요?

원시 토킹헤드 동영상(필러 장면 포함)을 16:9로 간결하고 의미 전달이 명확하며 색감이 아름답고 자막이 있는 동영상으로 변환합니다.

근본 철학 / 출처

Walter Murch, Rule of Six (In the Blink of an Eye): 감정 51% > 스토리 23% > 리듬 10% > 시선 유도 > 2D > 3D. 감정과 스토리 흐름에 따라 구간을 우선 선택하고, 화면 오류는 나중에 처리합니다.
Casey Neistat: 도입 → 배경 → 콘텐츠 → 결말; 의도적인 점프컷; 다양한 필러 장면 사용.
토킹헤드: 음성이 골격(L-cut), 필러 장면을 덮고 펀치인으로 점프컷을 가립니다.
실제 적용 사례: 차량 VLOG 11:22 → 5:22, 23개 구간, 29개 자막 블록 (샘플 플랜: references/vi-du-plan.json).

사용 시기 / 사용하지 말아야 할 시기

사용: 긴 원테이크 동영상(VLOG, 공유, 녹화된 라이브스트림, 차량 촬영)을 요약 + 필러 + 자막 처리, 16:9 가로.
사용하지 않음: TikTok 스타일 9:16 세로, 단어 단위 실시간 자막; AI 아바타/더빙 동영상; 원본 그대로 두고 자막만 필요한 경우(대신 HyperFrames의 /embedded-captions 사용).

사전 조건

HUONG-DAN-CAI-DAT.md에 따라 설치한 후 node <skill>/scripts/kiem-tra-may.mjs 실행 시 모두 ✓가 나와야 합니다.

ffmpeg/ffprobe, Node ≥ 18, npx hyperframes (0.8.168–0.8.169에서 테스트 완료).
whisper-cli (whisper.cpp) + 모델 ~/.whisper-models/ggml-large-v3-turbo.bin (WHISPER_BIN, WHISPER_MODEL 변수로 변경 가능).
Mac: VideoToolbox 사용, 빠른 편집(2.7K HEVC 10-bit 기준 실시간의 약 2배); Windows/Linux: libx264로 전환(느림).
여유 디스크 공간: 동영상 분당 최소 0.6GB + 3GB. 첫 렌더 시 chrome-headless-shell 다운로드(~150MB).
Be Vietnam Pro 글꼴: assets/fonts/에 포함됨 (SIL OFL 라이선스, 인터넷 불필요).

실행 절차

S=<스킬 디렉토리>/scripts (보통 .claude/skills/hmhshare-mkt-bien-tap-vlog-hyperframes/scripts) W=<작업 디렉토리>, 예: ~/vlog-lam-viec/<slug>. 미디어 파일은 작업 디렉토리에 두고, 클라우드 동기화 폴더(Google Drive, OneDrive, Dropbox 등)에는 절대 두지 마세요(느리고 오류 발생).

1단계 — 준비 (기계, 약 1-3분).

node $S/01-chuan-bi.mjs --work $W --main "<주 동영상>" --broll "<필러1>,<필러2>,..."

결과: probe.json, contact.jpg, loi-thoai.txt (단어 타임스탬프), main_clean.wav, 필러 장면 프록시 hfproj/media/bNN*.mp4 + broll.json. 재실행 시 완료된 부분은 건너뜁니다(--force로 재실행).

2단계 — AI 편집 (references/chon-doan-bien-tap.md 참고). contact.jpg 확인(화자 위치 → tam_zoom, 자막 배치 위치), loi-thoai.txt 전체 읽기, 시청자 + 메시지 결정(불명확 시 사용자에게 질문), $W/plan.json의 doan 항목 작성(references/plan-json.md 참조). 빠른 총 길이 테스트:

node $S/02-cat-doan.mjs --work $W --main "<주 동영상>" --chi-tinh   # ban-cat.txt만 출력, 자르지 않음

→ 사용자 검토 포인트: 사용자가 미리 확인을 원하면 ban-cat.txt 테이블을 보내고 중단합니다. 기본값: 계속 진행하며 최종 보고서에 테이블 포함.

3단계 — 자르기 + 오디오 필터 + 이음새 점검 (기계).

node $S/02-cat-doan.mjs --work $W --main "<주 동영상>"

출력: hfproj/media/main_cut.mp4/.wav, segs.json, kiem-tra-noi.json. 단어 누락 경고 구간은 cut-words.json과 비교(Whisper 오인 가능), 실제 오류인 경우 lui_dau/them_cuoi를 추가하여 재실행.

4단계 — AI 자막 작성 + 컴포지션 구성. ban-cat.txt 읽고 plan.json의 chu( doan + sau 기준), canh_tram(기본 {"nhip":20}) 작성 후:

node $S/03-dung-hyperframes.mjs --work $W
cd $W/hfproj && npx hyperframes check --json        # lint 0 에러, layout 0, contrast 모두 통과 필요
npx hyperframes snapshot --at <스크립트가 출력하는 마커>  # AI가 contact sheet 확인: 자막 줄바꿈 문제, 얼굴 가림, 색상

플랜/자막 수정 → 03 재실행하여 프레임이 깔끔해질 때까지 반복(자막이 길면 문장 축소, 글꼴 크기 줄이지 않음).

5단계 — 렌더링 + 내보내기 (기계, Mac M1 Pro 기준 동영상 길이의 약 1.5배).

node $S/04-render-xuat.mjs --work $W --out "<결과 디렉토리>" --quality delivery

길이 일치, 오디오 존재, LUFS 확인, soat.jpg 생성 후 동영상 + du-an-hyperframes/ + plan/segs/자막 파일을 결과 디렉토리로 복사합니다. AI가 soat.jpg를 최종 확인합니다.

6단계 — 보고서. 사용자에게 반환: 동영상 경로, 전/후 길이, 타임라인 테이블(구간 유지, 주요 내용), 제거된 내용, plan.json에서 수정할 부분 안내. 렌더 캐시 삭제(주의사항 참고).

참고 자료

scripts/lib.mjs: ffmpeg/whisper/구문 찾기, 기기에 따른 인코더 선택.
scripts/01-chuan-bi.mjs · 02-cat-doan.mjs · 03-dung-hyperframes.mjs · 04-render-xuat.mjs · kiem-tra-may.mjs.
scripts/template.tpl: HTML + GSAP 프레임워크(9가지 자막 유형, 펀치인, 필러 장면 혼합, Ken Burns 효과).
references/plan-json.md: 플랜 형식 + 자막 유형 표 · references/vi-du-plan.json: 실제 플랜 23개 구간/29개 자막.
references/chon-doan-bien-tap.md: 구간 선택 규칙, 흐름 프레임워크, 시각적 리듬.
HyperFrames 문서: https://hyperframes.heygen.com (기기에 hyperframes, hyperframes-cli 스킬이 있으면 추가 참고).

주의사항 / 함정

Whisper 타임스탬프가 실제 오디오보다 약 0.3~0.5초 지연됨: 스크립트에서 진입점을 0.3초 앞당김; 그래도 부족하면 lui_dau 추가.
원본 2.7K/4K 동영상 전체에 프록시 생성 금지(11분에 ~40분 소요): 선택한 구간만 자름(3단계).
hfproj/ 루트에 두 번째 .html 파일 금지: HyperFrames에서 multiple_root_compositions 오류 발생. 템플릿은 scripts/에 있음.
lint 경고 nested_structure_needs_subcomposition / timeline_track_too_dense는 조직 제안이므로 무시 가능.
렌더링 시 디코딩 캐시가 시스템 임시 폴더에 저장됨(Mac/Linux: $TMPDIR/hyperframes-extract-cache-*, Windows: %TEMP%; 5분 동영상 기준 약 2GB): 렌더 완료 후 삭제.
"Checking browser" 단계가 처음에 몇 분 지속되는 것은 브라우저 다운로드 중이므로 멈춤이 아님.
자막이 많이 틀린 경우: 화면상 자막은 맞춤법을 정확히 작성해야 하며, 추출된 원문을 그대로 사용하지 않음. 전체 동영상 실시간 자막은 아직 지원되지 않음.
HDR/LOG 동영상: 미리 SDR로 변환(1단계에서 경고); 실시간 색보정은 Rec.709만 지원.
카메라 메모리 카드는 1단계부터 3단계 완료까지 계속 연결되어 있어야 함(3단계에서 원본 파일 다시 읽음). 동영상을 먼저 컴퓨터로 복사하는 것이 좋음.
Windows: 경로에 공백이 있으면 항상 큰따옴표로 감싸야 함.

출력

<결과 디렉토리>/: <slug>.mp4, du-an-hyperframes/(index.html + config, 미디어 제외), plan.json, segs.json, ban-cat.txt, loi-thoai.txt, kiem-tra-noi.json, broll.json, soat.jpg.

HyperFrames VLOG 편집