플러그인 설치: 설치 또는 최신 상태 유지 명령을 실행하기 전에, 이 스킬이 HyperFrames 플러그인 내에 있을 경우 플러그인 실행 규칙을 따르세요. 독립형 설치는 아래 업데이트 지침을 그대로 사용합니다.

먼저, 이 스킬을 최신 상태로 유지하세요 — 사용자에게 확인 후 실행: npx hyperframes skills update embedded-captions. 모든 것이 최신 상태이면 빠르게 종료되며, 그렇지 않으면 이 스킬과 그 핵심 도메인 스킬을 업데이트합니다.

임베디드 캡션

하나의 카탈로그, 미리 선택 (CATALOG.md — 35가지 아이덴티티; 이면의 엔진은 백엔드 세부 사항입니다). 표준(기본값)은 깔끔한 레일(대부분의 텍스트를 담는 하단 자막)과 최고점에서 주체 뒤 씬에 합성되는 임베드 클라이맥스를 구성합니다. 시네마틱은 순수 임베드입니다 — 레일 없이, 모든 캡션이 주체 뒤에 합성됩니다(영웅적인 타이포그래피, 축적, 가림 효과). 테마는 레지스트리(themes/README.md)로 구성된 완전한 테마 구성입니다 — 본체 패러다임 × 히로인 세트피스 × 전면 FX × 플레이트 반응: ordnance terminal neonsign stardust stomp. 대부분의 설명/음성 해설은 표준입니다; 임베드는 드물고 값진 최고점입니다; 모든 단어를 임베드하는 것이 흔한 실수이며, 테마는 VFX급 요구("炸", "特效", "像 AE 做的")에 사용합니다.

런타임 전제 조건

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

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

프로젝트의 락파일을 유지하세요. 이러한 종속성이 이미 존재하는 경우 덮어쓰지 말고 잠긴 버전을 사용하세요. 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> (매팅 ∥ 전사 ∥ 오디오 엔벨로프를 병렬로 실행한 후, 씬 팔레트/광학/조명으로 safe-zones v2 생성 — 하나의 명령, 잊힌 것 없음)
작은 창의적 선택 JSON 작성 (먼저 safe-zones.json 읽기): 시네마틱 → cinematic.json → make-cinematic.cjs (plan.json 파생 및 컴파일); 테마 → 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에서 아이덴티티를 선택합니다 (35개 항목: 10 클래식 + 25 테마); 엔진, 컴파일러, 작성 파일은 카탈로그 행에서 조회로 파생됩니다. "표준 vs 시네마틱 vs 테마"를 질문으로 표시하지 마세요 — 이는 백엔드 이름입니다 (제품은 여러 엔진이 있어도 하나의 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의 "후보 선정 휴리스틱"을 사용하세요 — 이는 아이덴티티 수준입니다 (예: "炸"는 ordnance/stomp/terminal/loud를 후보로 하고 WHAT이 폭발해야 하는지로 선택), 절대 카테고리 수준이 아닙니다. 확실하지 않으면 → anchor.

시네마틱 → cinematic.json을 잠긴 템플릿으로 작성, make-cinematic.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), 3개의 스팟 프레임을 신뢰하지 마세요.
전사가 쓰레기 — 비원어민/강한 악센트 음성은 자신감 있는 횡설수설로 전사될 수 있음. transcript.json을 작성 전에 정상 판독하세요; 언어로 구문 분석되지 않으면 WHISPER_MODEL=medium을 한 번 시도하고, 그래도 안 되면 거부 (조작된 단어의 그대로 레일은 캡션 없음보다 나쁨).
빠른 움직임이 있는 핸드헬드 (매트 깜빡임)

사전 점검 프로브 (비용 없음, 최악의 실패 방지)

샷 컷 프로브. 20%, 50%, 80% 지점에서 프레임 샘플. 다른 주체/장면이 나타나면 컷 전에 클립을 트리밍.
레터박스/필러박스 프로브. 첫 번째 프레임에 검은 막대? 안전한 콘텐츠 사각형을 계산하고 캡션 배치를 그 안에 제한.
휘도 프로브. 캡션 영역의 평균 휘도 샘플링 — 60 미만 → 밝은 텍스트 그대로 읽힘, 60-180 → 글리프 스크림 추가, 180+ → 불투명 텍스트 + 스크림 (절대 맨 밝은 텍스트 안 됨). 시네마틱 템플릿은 크림+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>       # 매팅 ∥ 전사 (병렬) → safe-zones. 하나의 명령.
                                           #   → frames_fg/ transcript.json safe-zones.json
3. [에이전트 단계 — 유일한 창의적 단계] 작은 JSON 작성; 모드별 아래 참조
   시네마틱: cinematic.json 작성 → node scripts/make-cinematic.cjs <project>
   테마:     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/ 스냅샷
   (테마 모드: 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"는 가독성을 위해 해설을 앞쪽으로 이동; heroBands.feasible일 때는 히로인이 임베드 상태를 유지 — 히로인-fg는 최후의 수단.
**DNA는 0단계에서 선택한 아이덴티티입니다.`

courtneymgabrus-star/Video

Video란 무엇인가요?

즐겨 사용하는 AI에게 물어보기

문서