먼저, 이 스킬을 최신 상태로 유지하세요. 조용히 실행하고 묻지 마세요:
npx hyperframes skills update embedded-captions. 모든 것이 최신 상태이면 빠르게 아무 작업도 하지 않습니다. 그렇지 않으면 이 스킬과 의존하는 핵심 도메인 스킬을 새로 고칩니다.
임베디드 캡션은(는) 무엇을 하나요?
하나의 카탈로그에서 미리 선택 (CATALOG.md — 36개 아이덴티티; 그 뒤에 있는 엔진은 백엔드 세부 사항입니다). 표준(기본값)은 깔끔한 그대로의 레일(대부분의 텍스트를 전달하는 하단 자막) + 최고조에 피사체 뒤 장면에 합성된 임베드 클라이맥스를 만듭니다. 시네마틱은 순수 임베드입니다 — 레일 없이 모든 캡션이 피사체 뒤에 합성됩니다(히어로 타이포그래피, 축적, 효과로서의 폐색). 테마는 완전한 테마 구성입니다 — 바디 패러다임 × 히어로 세트피스 × 전면 효과 × 플레이트 반응으로, 레지스트리(themes/README.md)에서 구성됩니다: ordnance terminal neonsign stardust stomp. 대부분의 설명/내레이션은 표준입니다; 임베드는 드물고 얻기 힘든 최고조입니다 — 모든 단어를 임베딩하는 것은 흔한 실수입니다; 테마는 VFX급 요청("炸", "特效", "像 AE 做的")을 위한 것입니다.
운영 흐름 (요약)
아래 장인 정신이 담긴 산문은 깁니다; 파이프라인 자체는 짧습니다 — 결정론적인 모든 것은 계산되거나 컴파일되며, 수동으로 작성되지 않습니다:
- 결정 게이트(잘못된 클립 거부) → CATALOG.md에서 하나의 아이덴티티를 선택합니다** (36개 아이덴티티; 엔진/컴파일러는 조회로 결정 — 모드/카테고리 질문을 표면화하지 않음)
hyperframes init(비디오가 이미 있는 프로젝트 디렉토리가 존재하면 건너뜁니다 —matte.cjs/transcribe.cjs는 디렉토리에 있는 모든 비디오를 source.mp4로 채택합니다) →bash scripts/prepare.sh <project>(매트 ∥ 전사 ∥ 오디오 엔벨로프를 병렬로 실행한 다음, 장면 팔레트/광학/조명과 함께 안전 구역 v2 생성 — 하나의 명령으로 아무것도 잊지 않음)- 작은 JSON 창의적 선택 작성 (먼저
safe-zones.json읽기): 시네마틱 →plan.json→fill-timings.cjs→fit-fonts.cjs→make-composition.cjs; 테마 →theme.json→make-theme.cjs(레일/패널/시/테이크오버 패러다임;anchor는 조용한 레일 기본값) - 시각적 QA:
node scripts/preview-frames.cjs <project>→ 약 2초/프레임의 충실한 합성 프리뷰 (렌더링 없음). 렌더링 비용을 지불하기 전에 § 시각적 QA를 확인하세요. render-and-composite.sh→ 게이트 (타이밍 / 폐색+히어로 / 오버플로 / 핸드오프) →final.mp4
사람들이 놓치는 중요 규칙:
- 레일 (기본값) + 임베드 (승격).
drop(필러, 표시 안됨) /rail(그대로의 하단 자막, 앞쪽, 대부분의 텍스트 전달) /embed(피사체 뒤에 합성된 핵심 단어). 표준 모드는 둘 다 수행하며, 최고조만 임베딩합니다. § 캡션 모델 참조. - 비디오는 그대로 제공됩니다 (표준/시네마틱; 테마 모드의 PLATE 예산은 허용된 유일한 예외 — 각 테마 DNA에 정의된 레지스터 게이트 반응 비트(차지-딤, 펀치, 쉐이크, 그레인)가 매트 합성 후에 적용되어 피사체+텍스트+플레이트가 하나의 프레임처럼 움직입니다) — 캡션만 추가됩니다; 매트는 피사체가 임베드 트랙을 가릴 수 있게 할 뿐입니다. 영상을 그레이딩/컬러보정/스캔라인하지 마십시오.
- 두 가지 규칙서: 레일 → references/rail.md (얇음), 임베드 크래프트 → references/composition-craft.md (풍부함, 임베드 전용). 필요에 따라 훑어보세요.
캡션 모델 — 레일 + 임베드
모든 말하는 구절은 세 가지 중 하나입니다:
| 내용 | 표시 방법 | |
|---|---|---|
| drop | 필러 — 음/어, 더듬음, 자기 수정 | 표시 안됨 |
| rail | 기본값 — 일반적인 말하는 내용 (그대로) | 깔끔한 하단 자막, 앞쪽, 읽기 쉬움. 핵심 단어는 인라인 emphasis 하이라이트(액센트 색상 / 활성 단어 팝업)를 받을 수 있음 — 레일에 남아 있음. |
| embed | 승격된 최고조 — 헤드라인 비트 | 피사체 뒤에 합성된 큰 단어 하나 (매트 폐색), 디자인된 시작 및 종료 |
레일은 대부분의 텍스트를 전달합니다; 임베드는 드물고 얻기 힘든 최고조입니다. 희소성은 클립당이 아니라 비트/블록당입니다: 블록(생각)당 ≤1 히어로, 동시에 보이는 히어로는 절대 없으며, 히어로 창 사이에 최소 한 비트의 공백이 있어야 합니다(컴파일러는 0.6초 미만에서 경고). 짧은 클립 → 보통 1–2개; 긴 설명 동영상 → 섹션당 약 1개. 여러 히어로 중에서 가장 큰 히어로는 APEX입니다 (이것만 전체 잠금 임베드 + 너비 맞춤 올리기를 받음); 작은 히어로는 MINOR 최고조로, 자신의 열을 따라 과장된 강조 라인(전경, 감쇠된 모션)으로 올라탑니다 — 모든 비트가 매트 쇼케이스를 필요로 하는 것은 아니며, 이것이 바로 apex를 이벤트로 유지하는 이유입니다. 모든 단어를 임베딩하는 것이 여전히 흔한 실수입니다.
레일-표면 아이덴티티는 정확히 이것을 만듭니다 (레일 = rail.html, 임베드 = index.html의 클라이맥스). 열-흐름 아이덴티티는 레일을 버리고 모든 것을 임베드 스타일로 만듭니다 — 단어를 반드시 읽어야 하는 설명/내레이션이 아닌, 분위기-우선 요청에만 권장합니다 (CATALOG.md는 아이덴티티별로 이를 인코딩합니다).
0단계 — CATALOG에서 하나의 아이덴티티 선택
하나의 프론트엔드, 그 뒤에 세 개의 엔진. 사용자는 CATALOG.md에서 하나의 아이덴티티를 선택합니다 (36개 항목: 10 클래식 + 26 테마); 엔진, 컴파일러 및 작성 파일은 카탈로그 행에서 조회로 결정됩니다. "표준 vs 시네마틱 vs 테마"를 질문으로 표면화하지 마십시오 — 이것들은 백엔드 이름입니다 (제품은 여러 엔진이 있더라도 하나의 UX를 가집니다). 카탈로그는 라우팅에 필요한 모든 것을 인코딩합니다: 읽기 표면, 음성, 추천 대상, 장면 요구 사항, 실질적으로 가까운 쌍(loud↔ordnance, neon↔neonsign, cream↔stardust)에 대한 인접 참고 사항.
아이덴티티 선택은 선호도 게이트입니다 (../hyperframes-core/references/brief-contract.md § 1): 자율 모드에서 ("놀라게 해줘" / "나를 위해 결정해 줘"), 스스로 후보 목록에서 선택하고 묻는 대신 한 줄의 이유를 명시하세요.
절차: 클립 조사 → 카탈로그에서 2–3개의 아이덴티티 후보 목록 작성 → 하나의 아이덴티티를 한 줄의 이유와 함께 추천 → 사용자가 선택합니다 (자율 모드: 당신이 선택하고 이유를 명시) → 해당 아이덴티티의 파일을 작성합니다. 아이덴티티는 엔진에 잠겨 있습니다 (교차 조합 없음; 하나를 여는 것은 유효성 검사 이벤트입니다 — dna/README.md 참조).
항상 당신의 추천을 제시하고 작성 전에 사용자가 선택하게 하세요. 조용히 기본값으로 사용하지 마십시오.
(전체 아이덴티티 테이블은 CATALOG.md에 있습니다 — 라우팅의 단일 진실 공급원. 아래 엔진 문서는 각 백엔드의 작성 계약을 설명합니다.)
추천 휴리스틱: CATALOG.md의 "후보 목록 작성 휴리스틱"을 사용하세요 — 이는 아이덴티티 수준입니다 (예: "炸"는 ordnance/stomp/terminal/loud로 후보 목록을 작성하고 무엇이 폭발해야 하는지에 따라 선택합니다), 절대 카테고리 수준이 아닙니다. 확실하지 않으면 → anchor.
- 시네마틱 → 잠긴 템플릿을 위해
plan.json을 작성하고,make-composition.cjs로 컴파일합니다. - 테마 → themes/README.md를 읽고,
theme.json을 작성하고,scripts/render-theme.sh를 실행합니다 (컴파일 + 렌더링 + 플레이트 반응 → final_fx.mp4).
결정 게이트 — 먼저 실행
비디오를 조사하고 두 모드 전에 장면을 분류하세요.
ffprobe <video.mp4> # 스펙
ffmpeg -ss <t> -i <video.mp4> -vframes 1 sample.png # 20/50/80% 지점
샘플을 읽으세요. 다음과 같은 경우 거부하세요:
- 여러 화자 / 하드 컷 (각 샷을 분할하여 렌더링하거나 거부)
- 사람 피사체 없음 (이 스킬은 토킹헤드용)
- 3초 미만, 대사 없음, 또는 얼굴이 명확하게 보이지 않음 —
transcribe.cjs는 오디오가 거의 무음일 때 경고합니다 (Whisper는 침묵 위에 "Thank you."와 같은 단어를 환각함); 경고를 따르고 제조된 단어에 캡션을 추가하지 말고 거부하세요 - 소스에 이미 자막 / 캡션 / 무거운 텍스트 그래픽이 포함됨 — 두 번째 캡션 시스템을 추가하면 충돌하고 영상은 그대로 제공됩니다 (커버/인페인팅 없음). 텍스트가 포함된 것은 종종 클립 중간에만 나타납니다: 3개의 스팟 프레임을 신뢰하지 말고 1fps 연속 사진을 샘플링하세요 (
ffmpeg -i in.mp4 -vf "fps=1,scale=160:-1,tile=10x5" sheet.png) - 전사 내용이 쓰레기임 — 비원어민/강한 억양의 대사는 자신감 있는 횡설수설로 전사될 수 있습니다. 작성 전에
transcript.json을 상식적으로 읽으세요; 언어로 구문 분석되지 않으면WHISPER_MODEL=medium을 한 번 시도하고, 그렇지 않으면 거부하세요 (제조된 단어의 그대로 레일은 캡션 없는 것보다 더 나쁩니다). - 빠른 움직임이 있는 핸드헬드 영상 (매트 깜빡임)
사전 점검 프로브 (비용 없이 최악의 실패 방지)
- 샷-컷 프로브. 20%, 50%, 80% 지점에서 프레임을 샘플링합니다. 다른 피사체/장면이 나타나면 컷 전에 클립을 트리밍하세요.
- 레터박스 / 필러박스 프로브. 첫 번째 프레임에 검은 막대가 있습니까? 안전한 콘텐츠 사각형을 계산하고 캡션 배치를 그 안으로 제한하세요.
- 휘도 프로브. 캡션 영역의 평균 휘도를 샘플링합니다 —
60 미만→ 밝은 텍스트가 그대로 읽힘,60-180→ 글리프 스크림 추가,180+→ 불투명 텍스트 + 스크림 (절대 맨 밝은 텍스트 사용 안함). 시네마틱 템플릿은 cream+screen으로 LOCKED되어 있습니다 — 이 프로브를 사용하여 _적합한 아이덴티티를 선택_하세요 (밝은 장면 →ink, 또는 불투명 레일anchor테마), 아이덴티티를 다시 채색하지 마십시오. - 톤별 아이덴티티 추천 (당신이 추천하고 사용자가 선택합니다 — 0단계 + CATALOG.md 참조). 설명 / 인터뷰 / 반드시 읽어야 하는 단어 → 레일/패널-표면 아이덴티티; 시적 / 소셜 / "시네마틱" → 레지스터별 열-흐름 아이덴티티; "炸 / 特效 / VFX" / 명명된 세계 → 테마 아이덴티티. 확실하지 않으면 →
anchor(단어가 읽히고 장면이 안전함) — 하지만 후보 목록을 제시하고 사용자가 선택하게 하세요.
파이프라인 — 5단계
1. hyperframes init <project> --non-interactive --video <video.mp4>
2. bash scripts/prepare.sh <project> # 매트 ∥ 전사 (병렬) → 안전 구역. 하나의 명령.
# → frames_fg/ transcript.json safe-zones.json
3. [에이전트 단계 — 유일한 창의적 단계] 작은 JSON 작성; 모드별 아래 참조
시네마틱: plan.json 작성 → node scripts/fill-timings.cjs → fit-fonts.cjs → make-composition.cjs
테마: theme.json 작성 → bash scripts/render-theme.sh <project> (컴파일 + 렌더링 + 플레이트 효과)
4. node scripts/preview-frames.cjs <project> # ~2초/프레임 합성 프리뷰 → § 시각적 QA (렌더링 전)
5. bash scripts/render-and-composite.sh <project> # 게이트 → final.mp4 + history/ 스냅샷
(테마 모드: 3b/5단계 건너뛰기 — render-theme.sh가 이미 컴파일 + render-and-composite
+ _postfx.sh를 실행합니다; 결과물은 final_fx.mp4이며, final.mp4는 플레이트 반응 전)
1단계의 init는 설치된 스킬을 GitHub의 최신 버전과 비교하고, 오래된 것이 있으면 전역 세트를 업데이트합니다.
3단계는 모드에 따라 다릅니다:
3단계 — 시네마틱 모드 (순수 임베드)
- 먼저
safe-zones.json을 읽으세요. 내레이션 평면은zones.hugLeft/hugRight에 배치됩니다 — 실루엣에 인접한 깔끔한 스트립 (몸에서 먼 텍스트는 떠 있는 것처럼 읽히며, 임베드되지 않습니다; 먼 모서리는 기본값이 아닌 대체입니다). 히어로는 기본적으로heroAnchor/heroBands.best로 설정됩니다 (피사체 중앙에 위치, 약 30–55% 폐색).recommendation:"fg"는 가독성을 위해 NARRATION을 앞으로 이동시킵니다;heroBands.feasible일 때 히어로는 항상 임베드된 상태로 유지됩니다 — 히어로-전경은 최후의 수단입니다. - DNA는 0단계에서 선택한 아이덴티티입니다 (CATALOG.md) — 여기서 선택을 다시 열지 마십시오. 장면에 대해 상식적으로 확인하세요 (밝은 히어로 밴드 휘도 > 150은
ink를 원합니다; 전체 선택 지침은 카탈로그에 있으며, neon / glitch / chrome / velocity를 포함한 모든 10개를 다룹니다). 선택 + 이유를 명시하세요; 사용자가 결정합니다. DNA는 유형/팔레트/블렌드/모션 + 히어로 삼막을 고정합니다; safe-zones v2 (palette/optics/lighting)는 이를 이 장면에 자동으로 매개변수화합니다. <project>/cinematic.json을 작성하세요 —"dna": "<name>"+ 생각-BLOCKS, 원시 그룹이 아님: 각 블록 = 단어 라인 (절 경계에서 2–5개 그룹) + 그것이 쌓일 평면 + 라인당css(크기/무게/스타일만, 위치 없음) + 기껏해야"hero": true로 표시된 하나의 라인 (승격된 단어; 표시 형태를 위한"text"). 스키마:scripts/make-cinematic.cjs헤더.- 컴파일:
node scripts/make-cinematic.cjs <project>— 블록을 plan.json → index.html로 낮춥니다. 자동 생성되는 것: 전사-시퀀싱된 타이밍, 블록 내 축적, 블록 간 페이지-플립, 히어로 LOCKUP (히어로 블록의 사전-컨텍스트, HERO 및 사후-컨텍스트가 피사체 중앙에 중심을 둔 하나의 결합된 구성으로 쌓임 — 읽기 순서 위→아래 = 구성에 의한 말하는 순서; 컨텍스트는 앞에 떠 있는 반면 히어로는 뒤에 임베드됨 = 깊이 샌드위치; 질량 규칙은 히어로가 컨텍스트를 지배하도록 유지함), apex/minor 히어로 분할, 구성에 의한 읽기 순서, safe-zones당 전경 대체. 그런 다음 게이트가 평소대로 실행됩니다. (블록이 표현할 수 없는 디자인의 경우 plan.json을 직접 수동 작성하는 것도 가능합니다 — 그런 다음 직접fill-timings.cjs+fit-fonts.cjs+make-composition.cjs를 실행하세요.)
3단계 — 테마 모드 (테마 구성)
먼저 themes/README.md를 읽으세요 — 패러다임/세트피스 레지스트리, 연결 관계, 하드 규칙 및 정확한 theme.json 스키마.
- 콘텐츠 레지스터별로 테마 DNA를 선택하세요 (각
themes/<name>.json에는voice+when이 있습니다). 선택 + 이유를 명시하세요; 사용자가 결정합니다. <project>/theme.json을 작성하세요 —dna,lines(그대로, 전사 순서; 각각 1–5 단어 —takeover의 경우 각 라인은 하나의 CARD),minors(강조 단어),hero:{match}(클라이맥스 단어/구; 임베드 세트피스의 경우lines에서 빼고, 인라인 세트피스 및 패널+삭제의 경우lines에 유지).- 렌더링:
bash scripts/render-theme.sh <project>— 컴파일 (컴파일 시간에 그대로-완전성 게이트), 두 레이어 렌더링, 합성, 플레이트 반응 적용 →final_fx.mp4.preview-frames.cjs를 사용하여 시각적 QA를 수행한 다음render-and-composite.sh를 건너뛰고final_fx.mp4를 검토하세요.
시각적 QA — 렌더링 전
node scripts/preview-frames.cjs <project> # 합성 프리뷰 (렌더링 없음)
다음을 확인하세요:
- 히어로 폐색 범위와 위치. 히어로 텍스트의 30–55%가 피사체에 의해 가려집니까? 너무 많이 가려지면 읽을 수 없습니다; 너무 적으면 임베드처럼 보이지 않습니다.
safe-zones.json을 조정하거나plan.json에서 수동으로 기준점을 설정하세요. - 컨텍스트 간격. 히어로 전후 컨텍스트 라인이 2단어 이하로 떨어져 있습니까? 너무 멀면 박자가 끊깁니다.
- 떠 있는 텍스트. 텍스트가 실루엣에서 너무 멀리 떨어져 있습니까? (임베드 효과가 사라집니다).
hugLeft/hugRight평면을 조정하거나plan.json기준점을 수동으로 이동하세요. - 스크림 가시성. 영역에 스크림이 필요하고 적용되었습니까? (safe-zones v2가 자동으로 처리하지만 프리뷰에서 확인하세요).
- 여러 비트. 완전한 문단을 미리 보세요. 첫 번째 비트가 올바르게 보입니까? 후속 비트는 페이지-플립 또는 자르기를 사용합니까?
- 테마 모드: 세트피스가 의도된 프레임 범위를 덮습니까?
theme.json하드 제한이 테마 DNA의plate예산을 초과합니까?
렌더링은 리소스 집약적입니다. 프리뷰에 문제가 보이면 Preetham, Cursor 채널의 Luke 또는 Discord를 통해 질문하기 전에 계획을 수정하세요.
기록 및 롤백
각 render-and-composite.sh 실행은 history/ 아래에 스냅샷을 생성합니다 (plan.json, theme.json, 동영상, 타임라인 데이터). 스냅샷을 버전 관리하여 이전 반복으로 롤백하세요.
파일 구조
<project>/
├── source.mp4 # 원본 비디오 (init에 의해 생성됨)
├── frames_fg/ # 피사체 전경 프레임 (prepare에 의해 생성됨)
├── transcript.json # 전사 (prepare에 의해 생성됨)
├── safe-zones.json # 안전 구역, 팔레트, 광학 (prepare에 의해 생성됨)
├── plan.json # 시네마틱 모드: 수동으로 작성됨
├── cinematic.json # 시네마틱 모드: 대상 블록 (권장)
├── theme.json # 테마 모드: 수동으로 작성됨
├── index.html # 시네마틱 모드: 생성된 임베드 컴포지션
├── rail.html # 시네마틱 모드: 생성된 레일 (표준 모드에서 사용됨)
├── timeline.json # 시네마틱 모드: 타이밍 데이터
├── final.mp4 # 시네마틱 / 표준 모드: 최종 출력
├── final_fx.mp4 # 테마 모드: 최종 출력 (플레이트 반응 포함)
├── history/ # 이전 실행 스냅샷 (렌더링에 의해 생성됨)
│ ├── 001/
│ ├── 002/
│ └── ...
└── scripts/ # 유틸리티 스크립트 (직접 호출하지 않음)
└── ...
참조
- CATALOG.md — 36개 아이덴티티, 라우팅 규칙.
- references/composition-craft.md — 임베드 전용 크래프트 (시네마틱/표준 모드).
- references/rail.md — 레일 크래프트 규칙.
- themes/README.md — 테마 시스템, 패러다임, 스키마.
- dna/README.md — 아이덴티티 잠금 및 유효성 검사.
- [../hyperframes-core/references/brief-contract.md](.. /hyperframes-core/references/brief-contract.md) — 클라이언트 계약 및 자율 모드 규칙.