name: embedded-captions description: > 기존 단일 인물 토킹헤드 영상에 자막이나 내장 자막을 추가하되, 영상 자체는 편집하지 않습니다. 일반 자막, 피사체 뒤에 내장되는 시네마틱 자막, VFX 자막, "炸/特效/酷炫字幕" 또는 35가지 스타일 카탈로그의 명명된 정체성에 사용합니다. 백엔드 엔진이 아닌 시각 정체성으로 라우팅합니다. 조용한 `anchor` 레일이 기본값이며, 사용자가 명시적으로 완전한 시네마틱 처리를 원할 때만 모든 단어를 내장합니다. 워크플로는 전사와 피사체 매팅을 포함하여 로컬에서 엔드투엔드로 실행됩니다. 적용하기 전에 멀티샷 영상은 분할하세요.

먼저, 이 스킬을 최신 상태로 유지하세요 — 사용자에게 확인 후 실행: npx hyperframes skills update embedded-captions. 모든 것이 최신이면 빠르게 아무 일도 일어나지 않으며, 그렇지 않으면 이 스킬과 이 스킬이 의존하는 핵심 도메인 스킬을 새로 고칩니다.

내장 자막

하나의 카탈로그, 먼저 선택 (CATALOG.md — 35가지 정체성; 그 뒤의 엔진은 백엔드 세부 사항입니다). 표준 (기본값)은 깔끔한 레일 (대부분의 텍스트를 담는 하단 1/3 자막) + 피크 순간에 피사체 뒤 장면에 합성되는 내장 클라이맥스를 만듭니다. 시네마틱은 순수 내장 — 레일 없이, 모든 자막이 피사체 뒤에 합성됩니다 (히로 타이포그래피, 누적, 가림 효과). 테마는 완전한 테마 구헌 — 본체 패러다임 × 히로 세트피스 × 전면 효과 × 판 반응, 레지스트리에서 구성됩니다 (themes/README.md): ordnance terminal neonsign stardust stomp. 대부분의 설명/내레이션은 표준입니다. 내장은 드물고 얻기 힘든 피크입니다 — 모든 단어를 내장하는 것이 흔한 실수입니다. 테마는 VFX 수준의 요청 ("炸", "特效", "AE처럼")에 사용됩니다.

작동 흐름 (요약)

/hyperframes를 통해 라우팅되며, 의도 레이어는 입력(클립)만 확인하고 정체성 선택을 지연된 요청으로 알립니다 — 후보 목록은 클립을 조사해야 하므로 아래 1단계에 있습니다. 레이어의 실행 형태 질문은 적용되지 않습니다 (영상은 그대로이며, 검토할 스토리보드가 없습니다). BRIEF.md가 있는 경우 확인된 입력과 사용자 메모를 담고 있습니다 — 먼저 읽으세요.

아래 설명 문구는 깁니다. 파이프라인 자체는 짧습니다 — 결정적인 모든 것은 계산되거나 컴파일되며, 수동으로 작성되지 않습니다:

판단 게이트 (나쁜 클립 거부) → CATALOG.md에서 하나의 정체성 선택 (35가지 정체성, 엔진/컴파일러는 조회로 결정 — 모드/카테고리 질문을 표시하지 마세요)
hyperframes init (프로젝트 디렉토리가 이미 존재하고 동영상이 있으면 건너뜁니다 — matte.cjs/transcribe.cjs는 디렉토리의 모든 동영상을 source.mp4로 사용합니다) → bash scripts/prepare.sh <project> (매트 ∥ 전사 ∥ 오디오 엔벨로프를 병렬로 처리한 후, 장면 팔레트/광학/조명과 함께 safe-zones 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 (앞에 있는, 대부분의 텍스트를 담는 하단 1/3 자막) / embed (피사체 뒤에 합성되는 피크 단어). 표준 모드는 둘 다 사용하며, 피크만 내장합니다. § 자막 모델 참조.
동영상은 그대로 제공됩니다 (표준/시네마틱; 테마 모드의 PLATE 예산은 유일한 허용 예외 — 각 테마 DNA에 정의된 등록 게이트 반응 비트 (차지 딤, 펀치, 셰이크, 그레인)가 매트 합성 후 적용되어 피사체+텍스트+판이 하나의 프레임으로 움직입니다) — 자막만 추가됩니다. 매트는 피사체가 내장 트랙을 가릴 수 있게 합니다. 영상을 그레이딩/리컬러/스캔라인 하지 마세요.
두 가지 규칙집: 레일 → references/rail.md (얇음), 내장 제작 → references/composition-craft.md (풍부함, 내장 전용). 필요에 따라 훑어보세요.

자막 모델 — 레일 + 내장

모든 말하는 구절은 세 가지 중 하나입니다:

	무엇	어떻게 표시됨
drop	필러 — 음/어, 더듬음, 자기 수정	표시되지 않음
rail	기본값 — 일반적인 말하는 내용 (그대로)	깔끔한 하단 1/3 자막, 앞에, 읽을 수 있게. 강조 단어는 인라인 `emphasis` 하이라이트 (강조 색상 / 활성 단어 팝)를 받을 수 있습니다 — 레일에 그대로 유지.
embed	승격된 피크 — 헤드라인 비트	피사체 뒤에 합성된 큰 단어 하나 (매트 가림), 설계된 진입 + 퇴장

레일이 대부분의 텍스트를 담고, 내장은 드물고 얻기 힘든 피크입니다. 희소성은 클립이 아닌 비트/블록 기준입니다: 블록 당 ≤1 히로 (생각), 두 개가 동시에 보이지 않음, 히로 윈도우 사이에 최소 비트의 간격 (컴파일러가 0.6초 미만을 경고). 짧은 클립 → 보통 1–2개; 긴 설명 → 섹션 당 약 1개. 여러 히로 중에서 가장 큰 것이 APEX (이것만 전체 잠금 내장 + 너비 맞춤 상승을 받음); 작은 것은 MINOR 피크로 컬럼에서 확대된 강조 줄로 표시됨 (전경, 감쇠된 모션) — 모든 비트가 매트 쇼케이스가 필요한 것은 아니며, 이것이 바로 apex를 이벤트로 유지하는 이유입니다. 모든 단어를 내장하는 것은 여전히 흔한 실수입니다.

레일 표면 정체성은 정확히 이것을 구축합니다 (레일 = rail.html, 내장 = index.html의 클라이맥스). 컬럼 흐름 정체성은 레일을 버리고 모든 것을 내장 스타일로 만듭니다 — 단어를 반드시 읽어야 하는 설명/내레이션 요청이 아닌, 분위기-우선/소셜 요청에만 추천하세요 (CATALOG.md는 정체성 별로 이를 인코딩합니다).

0단계 — CATALOG에서 하나의 정체성 선택

하나의 프론트엔드, 세 가지 엔진. 사용자가 CATALOG.md에서 정체성을 선택합니다 (35개 항목: 클래식 10개 + 테마 25개). 엔진, 컴파일러 및 작성 파일은 카탈로그 행에서 조회로 파생됩니다. "표준 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." 같은 단어를 환각합니다). 경고를 따르고 거부하세요, 조작된 단어로 자막을 만들지 마세요.
소스에 이미 자막/내장 자막/무거운 텍스트 그래픽이 포함된 경우 — 두 번째 자막 시스템을 추가하면 충돌이 발생하고 영상이 그대로 제공됩니다 (덮거나 인페인트하지 않음). 번인 텍스트는 종종 클립 중간에만 나타납니다: 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+ → 불투명 텍스트 + 스크림 (절대 맨 밝은 텍스트를 사용하지 마세요). 시네마틱 템플릿은 크림+screen으로 고정되어 있습니다 — 이 점검을 사용하여 _적합한 정체성을 선택_하세요 (밝은 장면 → ink, 또는 불투명 레일 anchor 테마), 색상을 변경하지 마세요.
톤별 정체성 추천 (당신이 추천하고, 사용자가 선택 — 0단계 + CATALOG.md 참조). 설명 / 인터뷰 / 반드시 읽어야 하는 단어 → 레일/패널 표면 정체성; 시적 / 소셜 / "시네마틱" → 레지스터별 컬럼 흐름 정체성; "炸 / 特效 / VFX" / 명명된 세계 → 테마 정체성. 확실하지 않을 때 → anchor (단어가 읽히고, 장면이 안전함) — 하지만 후보 목록을 제시하고 사용자가 선택하게 하세요.

파이프라인 — 5단계

1. hyperframes init <project> --non-interactive --video <video.mp4> --skill=embedded-captions
2. bash scripts/prepare.sh <project>       # 매트 ∥ 전사 (병렬) → safe-zones. 하나의 명령어.
                                           #   → 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를 실행합니다. 전달물

embedded-captions