플러그인 설치: 설정 또는 freshness 명령 전, 이 스킬이 HyperFrames 플러그인 내부에 있을 경우 플러그인 실행 규칙을 따르세요. 독립 실행형 설치는 아래 업데이트 지침을 유지합니다.

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

Embedded Captions

하나의 카탈로그, 미리 선택 (CATALOG.md — 35가지 정체성; 그 뒤에 있는 엔진은 백엔드 세부 사항). Standard (기본값)는 깔끔한 축어 레일 (대부분의 텍스트를 전달하는 하단 1/3 자막) + 피크에서 피사체 뒤 장면 안에 합성된 embed 클라이맥스를 빌드합니다. Cinematic은 순수 embed — 레일 없음, 모든 자막이 피사체 뒤에 합성됩니다 (히어로 타이포그래피, 누적, 가림 효과). Theme은 완전한 테마 구축입니다 — body 패러다임 × hero 세트피스 × 전면 fx × 플레이트 반응, 레지스트리에서 구성 (themes/README.md): ordnance terminal neonsign stardust stomp. 대부분의 설명/내레이션은 Standard입니다; embed는 드물고 가치 있는 피크입니다 — 모든 단어를 삽입하는 것이 일반적인 실수입니다. Theme은 VFX 수준의 요청("炸", "特效", "像 AE 做的")을 위한 것입니다.

런타임 전제 조건

플러그인 설치 시 매트, 전사 및 렌더링을 위해 번들로 제공되고 매니페스트에 고정된 CLI를 사용합니다. 소스 체크아웃이 필요하지 않습니다. 로컬 미리보기 및 캡션 측정 도우미도 Sharp, Puppeteer (Chromium 브라우저 포함) 및 GSAP이 필요합니다. 읽기 전용 플러그인이 아닌 캡션 프로젝트에 설치하세요:

npm install --prefix <project> --save-dev --save-exact [email protected] [email protected] [email protected]

프로젝트의 lockfile을 유지하세요. 이러한 종속성이 이미 존재하는 경우 덮어쓰지 말고 잠긴 버전을 사용하세요. Bash 및 FFmpeg/ffprobe가 PATH에 있어야 합니다. 매트 및 전사는 첫 사용 시 자체 모델을 다운로드할 수 있습니다.

렌더링은 합성 전에 CLI가 성공적으로 종료될 때까지 기다립니다. 이전 HF_TIMEOUT_S 셸 와치독은 더 이상 사용되지 않습니다: 큰 부분 파일이 렌더링 완료를 증명하지 않습니다. 명시적인 빌드 체크아웃 인수 또는 HYPERFRAMES_ROOT는 플러그인 핀 대신 기여자 CLI를 선택합니다. 중단된 렌더링은 일반적으로 CLI/터미널을 통해 취소하세요; 캡션 도우미는 프로세스 스냅샷에서 강제 종료하거나 렌더링을 복구하지 않습니다.

운영 흐름 (요약)

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

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

결정 게이트 (나쁜 클립 거부) → CATALOG.md에서 하나의 정체성 선택 (35개 정체성; 엔진/컴파일러는 조회로 파생됨 — 모드/카테고리 질문 절대 표시 안 함)
hyperframes init (프로젝트 디렉토리가 이미 존재하고 내부에 비디오가 있으면 건너뜀 — matte.cjs/transcribe.cjs는 디렉토리의 모든 비디오를 source.mp4로 채택) → bash scripts/prepare.sh <project> (matte ∥ transcribe ∥ audio-envelope를 병렬로 실행한 다음, 씬 팔레트/광학/조명을 사용한 safe-zones v2 — 하나의 명령, 잊은 것 없음)
작은 JSON의 창의적 선택 작성 (먼저 safe-zones.json 읽기): Cinematic → cinematic.json → make-cinematic.cjs (plan.json을 파생하고 컴파일); Theme → theme.json → make-theme.cjs (rail/panel/poem/takeover 패러다임; anchor는 조용한 레일 기본값)
시각적 QA: node scripts/preview-frames.cjs <project> → 약 2초/프레임의 충실한 합성 미리보기 (렌더링 없음). 렌더링 비용을 지불하기 전에 § 시각적 QA 확인.
render-and-composite.sh → 게이트 (타이밍 / occlusion+hero / 오버플로 / 핸드오프) → final.mp4

사람들이 놓치는 중요한 규칙:

레일(기본값) + embed(승격). drop (표시되지 않는 필러) / rail (축어적 하단 1/3 자막, 전면, 대부분의 텍스트 전달) / embed (피사체 뒤에 합성된 피크 단어). Standard 모드는 둘 다 수행하며 피크만 삽입합니다. § 캡션 모델 참조.
비디오는 손대지 않은 상태로 전달됩니다 (Standard/Cinematic; Theme 모드의 PLATE 예산은 허용된 유일한 예외 — 테마 DNA별로 정의되고 매트 합성 후 적용되는 등록 게이트 반응 비트(charge-dim, punch, shake, grain)로 피사체+텍스트+플레이트가 하나의 프레임으로 움직입니다) — 캡션만 추가됩니다. 매트는 피사체가 embed 트랙을 가릴 수 있게 할 뿐입니다. 영상을 등급/재색/스캔라인하지 마세요.
두 가지 규칙집: 레일 → references/rail.md (얇음), embed 제작 → references/composition-craft.md (풍부, embed 전용). 필요에 따라 훑어보세요.

캡션 모델 — 레일 + embed

모든 음성 구문은 세 가지 중 하나입니다:

	무엇	표시 방법
drop	필러 — 음/어, 더듬음, 자기 수정	표시 안 함
rail	기본값 — 일반 음성 내용 (축어)	깔끔한 하단 1/3 자막, 전면, 읽기 쉬움. 강조 단어는 인라인 `emphasis` 하이라이트(액센트 색상 / 활성 단어 팝)를 얻을 수 있음 — 레일에 유지됩니다.
embed	승격된 피크 — 헤드라인 비트	피사체 뒤에 합성된 큰 단어 하나 (매트 가림), 디자인된 입장 + 퇴장

레일은 대부분의 텍스트를 전달합니다; embed는 드물고 가치 있는 피크입니다. 희소성은 클립당이 아니라 비트/블록당입니다: 블록(생각)당 ≤1 히어로, 두 개가 동시에 보이지 않음, 히어로 창 사이에 최소 한 비트의 공기(컴파일러가 0.6초 미만 경고). 짧은 클립 → 보통 1–2개; 긴 설명 → 섹션당 약 1개. 여러 히어로 중 가장 큰 작성된 것이 APEX (그것만 전체 잠금 embed + 너비 맞춤 상승을 얻음); 작은 것들은 MINOR 피크로 과장된 강조선(전경, 감쇠 동작)으로 자체 열을 탐 — 모든 비트가 매트 쇼케이스를 필요로 하는 것은 아니며, 이것이 정확히 apex를 이벤트로 유지합니다. 모든 단어를 삽입하는 것은 여전히 일반적인 실수입니다.

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

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

하나의 프론트엔드, 세 가지 백엔드. 사용자가 CATALOG.md에서 정체성(IDENTITY)을 선택합니다 (35개 항목: 10 클래식 + 25 테마); 엔진, 컴파일러 및 작성 파일은 카탈로그 행에서 조회하여 파생됩니다. "Standard vs Cinematic vs Theme"를 질문으로 표시하지 마세요 — 그것들은 백엔드 이름입니다 (제품은 여러 엔진을 가지고 있어도 하나의 UX를 가집니다). 카탈로그는 라우팅에 필요한 모든 것을 인코딩합니다: 읽기 표면, 음성, 추천 대상, 씬 필요 사항, 진정으로 가까운 쌍에 대한 인접 노트 (loud↔ordnance, neon↔neonsign, cream↔stardust).

정체성 선택은 선호도 게이트입니다 (../hyperframes/references/brief-contract.md § 1): 자율 모드("놀래켜 줘" / "나를 위해 결정해 줘")에서는 직접 후보 목록에서 선택하고 한 줄 이유를 말하세요. 묻지 마세요.

절차: 클립 프로브 → 카탈로그에서 2-3개 정체성 후보 목록 작성 → 한 줄 이유와 함께 하나 추천 → 사용자가 선택 (자율 모드: 당신이 선택하고 이유를 말함) → 해당 정체성의 파일 작성. 정체성은 엔진에 고정됨 (크로스 콤보 불가; 하나를 여는 것은 검증 이벤트 — dna/README.md 참조).

작성 전에 항상 추천을 제시하고 사용자가 선택하도록 하세요. 조용히 기본값으로 진행하지 마세요.

(전체 정체성 테이블은 CATALOG.md에 있습니다 — 라우팅의 유일한 진실 공급원. 아래 엔진 문서는 각 백엔드의 작성 계약을 설명합니다.)

CATALOG.md가 여기서 전체 답변 공간입니다: 이 워크플로우는 HyperFrames 컴포넌트 레지스트리를 검색하지 않습니다. 합성 워크플로우는 명명된 룩을 작성하기 전에 npx hyperframes catalog를 실행합니다. 이것은 그러면 안 됩니다. 그 엔진은 cinematic.json / theme.json을 소비하고 합성 자체를 내보내는 잠긴 컴파일러이므로, 레지스트리 항목 — 포함된 caption-* 블록 — 마운트할 대상이 없습니다. 레지스트리 블록은 디자인된 캔버스에 텍스트 스타일을 지정합니다. 이 스킬은 매트를 통해 누군가의 영상에 캡션을 새깁니다. 어떤 정체성도 요청에 맞지 않으면 말하고 가장 가까운 것을 선택하세요. 카탈로그 외부로 나가지 마세요.

추천 휴리스틱: CATALOG.md의 "Shortlisting heuristics"를 사용하세요 — 그것들은 정체성 수준입니다 (예: "炸"는 ordnance/stomp/terminal/loud를 후보로 하고 무엇이 폭발해야 하는지에 따라 선택), 카테고리 수준이 아닙니다. 확실하지 않음 → anchor.

Cinematic → 잠긴 템플릿에 대해 cinematic.json을 작성하고 make-cinematic.cjs로 컴파일합니다.
Theme → 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), 3개의 스팟 프레임을 신뢰하지 마세요.
전사 결과가 쓰레기 — 비원어민/강한 억양의 음성은 자신감 있는 횡설수설로 전사될 수 있습니다. 작성 전에 transcript.json을 읽고 이해가 되는지 확인하세요. 언어로 구문 분석되지 않으면 한 번 WHISPER_MODEL=medium을 시도하고, 그렇지 않으면 거부하세요 (조작된 단어의 축어 레일은 캡션 없는 것보다 나쁩니다).
빠른 움직임이 있는 핸드헬드 (매트 깜박임)

사전 점검 (비용 없이, 최악의 실패 방지)

샷 컷 프로브. 20%, 50%, 80% 지점에서 프레임 샘플링. 다른 피사체/씬이 나타나면 컷 전에 클립을 트림하세요.
레터박스 / 필러박스 프로브. 첫 번째 프레임에 검은색 막대가 있습니까? 안전한 콘텐츠 사각형을 계산하고 그 안에 캡션 배치를 제한하세요.
휘도 프로브. 캡션 영역의 평균 휘도를 샘플링하세요 — 60 미만 → 밝은 텍스트가 그대로 읽힘, 60–180 → 글리프 스크림 추가, 180+ → 불투명 텍스트 + 스크림 (절대 맨 밝은 텍스트 사용 안 함). Cinematic 템플릿은 cream+screen으로 LOCKED — 이 프로브를 사용하여 _맞는 정체성을 선택_하세요 (밝은 씬 → 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>       # matte ∥ transcribe (병렬) → safe-zones. 하나의 명령.
                                           #   → frames_fg/ transcript.json safe-zones.json
3. [에이전트 단계 — 유일한 창의적 단계] 작은 JSON 작성; 모드별 아래 참조
   Cinematic: cinematic.json 작성 → node scripts/make-cinematic.cjs <project>
   Theme:     theme.json 작성 → bash scripts/render-theme.sh <project>   (컴파일 + 렌더링 + 플레이트 fx)
4. node scripts/preview-frames.cjs <project>   # ~2초/프레임 합성 미리보기 → § 시각적 QA (렌더링 전)
5. bash scripts/render-and-composite.sh <project>  # 게이트 → final.mp4 + history/ 스냅샷
   (Theme 모드: 3b/5단계 건너뜀 — render-theme.sh가 이미 컴파일 + render-and-composite
    + _postfx.sh를 실행함; 산출물은 final_fx.mp4, final.mp4는 플레이트 반응 전)

1단계의 init는 설치된 스킬을 GitHub의 최신 버전과 비교하고 오래된 것이 있으면 전역 세트를 업데이트합니다.

3단계는 모드에 따라 다릅니다:

3단계 — Cinematic 모드 (순수 embed)

먼저 safe-zones.json을 읽으세요. 내레이션 평면은 **zones.hugLeft/hugRight**에 배치됩니다 — 실루엣에 인접한 깔끔한 스트립 (몸에서 먼 텍스트는 떠 있는 것으로 읽히고 삽입되지 않음; 먼 코너는 기본값이 아닌 대체 수단). 히어로의 기본값은 heroAnchor/heroBands.best (피사체 위에 중앙 정렬, 약 30–55% 가려짐). recommendation:"fg"는 가독성을 위해 NARRATION을 전면으로 이동시킵니다; heroBands.feasible이면 히어로는 삽입된 상태로 유지됩니다 — hero-fg는 최후의 수단입니다.
**DNA는 0단계에서 선택한 정체성입니다

… (잘림)

[번역을 위해 잘림]

embedded-captions