중요: 이 스킬을 최신 상태로 유지하려면 — 묻지 말고 자동 실행:
npx hyperframes skills update embedded-captions모든 것이 최신 상태이면 빠른 no-op; 그렇지 않으면 이 스킬과 이에 의존하는 핵심 도메인 스킬을 새로 고칩니다.
임베디드 캡션 (Embedded Captions)
하나의 카탈로그, 미리 선택 (CATALOG.md — 35개 아이덴티티; 그 뒤의 엔진은 백엔드 세부 사항입니다). Standard (기본값)는 깔끔한 레일(rail, 대부분의 텍스트를 담는 하단 서브타이틀)을 만들고, 클라이맥스에서 임베드(embed)를 피사체 뒤 장면에 합성합니다. Cinematic은 순수 임베드 — 레일 없이 모든 자막을 피사체 뒤에 합성합니다 (영웅 타이포그래피, 누적, 가림 효과). Theme은 완전한 테마 기반 구성입니다 — 바디 패러다임 × 영웅 세트피스 × 전면 효과 × 플레이트 반응으로, 레지스트리에서 구성됩니다 (themes/README.md): ordnance terminal neonsign stardust stomp. 대부분의 설명/내레이션은 Standard입니다; 임베드는 드물고 값진 정점입니다 — 모든 단어를 임베드하는 것이 일반적인 실수입니다; Theme은 VFX 수준의 요청("炸", "特效", "像 AE 做的")에 적합합니다.
작동 흐름 (TL;DR)
/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 →plan.json→fill-timings.cjs→fit-fonts.cjs→make-composition.cjs; Theme →theme.json→make-theme.cjs(rail/panel/poem/takeover 패러다임;anchor는 조용한 레일 기본값) - 시각적 QA:
node scripts/preview-frames.cjs <project>→ 약 2초/프레임 속도로 신뢰할 수 있는 합성 미리보기 제공 (렌더링 전에 § 시각적 QA 확인) render-and-composite.sh→ 게이트 (타이밍 / 가림+영웅 / 오버플로우 / 핸드오프) →final.mp4
사람들이 놓치는 중요한 규칙:
- 레일 (기본값) + 임베드 (승격).
drop(필러, 표시 안함) /rail(일반 하단 서브타이틀, 전면, 대부분의 텍스트를 담음) /embed(피사체 뒤에 합성되는 정점 단어). Standard 모드는 둘 다 수행하며, 정점만 임베드합니다. § 캡션 모델 참조. - 비디오는 그대로 전달됩니다 (Standard/Cinematic; Theme 모드의 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개 테마); 엔진, 컴파일러 및 작성 파일은 카탈로그 행에서 조회하여 파생됩니다. "Standard vs Cinematic vs Theme"를 질문으로 절대 표면에 드러내지 마십시오 — 이것들은 백엔드 이름입니다 (제품은 여러 엔진을 사용하더라도 하나의 UX를 가집니다). 카탈로그는 라우팅에 필요한 모든 것을 인코딩합니다: 읽기 표면, 음성, 권장 대상, 장면 요구 사항, 진정으로 유사한 쌍에 대한 인접 노트 (loud↔ordnance, neon↔neonsign, cream↔stardust).
아이덴티티 선택은 선호도 게이트입니다 (../hyperframes-core/references/brief-contract.md § 1): 자율 모드("놀라게 해줘" / "대신 결정해줘")에서는 스스로 후보 목록에서 선택하고 선택 이유를 한 줄로 설명하십시오.
절차: 클립 분석 → 카탈로그에서 2–3개 아이덴티티 후보 선정 → 하나 추천 및 한 줄 이유 제시 → 사용자가 선택 (자율 모드: 당신이 선택하고 이유를 설명) → 해당 아이덴티티의 파일 작성. 아이덴티티는 엔진에 고정됩니다 (교차 조합 금지; 하나를 여는 것은 검증 이벤트입니다 — dna/README.md 참조).
항상 추천을 제시하고 작성 전에 사용자가 선택하도록 하십시오. 조용히 기본값을 사용하지 마십시오.
(전체 아이덴티티 표는 CATALOG.md에 있습니다 — 라우팅의 단일 진실 공급원(single source of truth). 아래 엔진 문서는 각 백엔드의 작성 계약을 설명합니다.)
추천 휴리스틱: CATALOG.md의 "후보 선정 휴리스틱"을 사용하십시오 — 이것들은 아이덴티티 수준입니다 (예: "炸"는 ordnance/stomp/terminal/loud를 후보로 선정하고 WHAT이 폭발해야 하는지에 따라 선택), 절대 카테고리 수준이 아닙니다. 확실하지 않으면 → anchor.
- Cinematic → 고정 템플릿에 대해
plan.json을 작성하고make-composition.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 템플릿은 크림+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: plan.json 작성 → node scripts/fill-timings.cjs → fit-fonts.cjs → make-composition.cjs
Theme: 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/ 스냅샷
(Theme 모드: 3b/5단계 건너뜀 — render-theme.sh가 이미 compile + render-and-composite
+ _postfx.sh를 실행; 결과물은 final_fx.mp4, final.mp4는 플레이트 반응 전)
1단계의 init는 설치된 스킬을 GitHub의 최신 버전과 비교하고 오래된 것이 있으면 업데이트합니다.
3단계는 모드에 따라 다릅니다:
3단계 — Cinematic 모드 (순수 임베드)
- 먼저
safe-zones.json을 읽으십시오. 내레이션 평면은zones.hugLeft/hugRight에 배치됩니다 — 실루엣에 인접한 깨끗한 스트립 (본체에서 먼 텍스트는 임베드되지 않고 떠 있는 것처럼 보입니다; 먼 모서리는 기본값이 아닌 최후의 수단입니다). 영웅은 기본적으로heroAnchor/heroBands.best에 배치됩니다 (피사체 중심에, ~30–55% 가려짐).recommendation:"fg"는 가독성을 위해 내레이션을 전면으로 이동시킵니다;heroBands.feasible인 경우 영웅은 항상 임베드됩니다 — hero-fg는 최후의 수단입니다. - DNA는 0단계에서 선택한 아이덴티티입니다 (CATALOG.md) — 여기서 선택을 다시 열지 마십시오. 장면과 비교하여 타당성을 확인하십시오 (밝은 영웅 밴드 휘도 > 150은
ink를 원함; 전체 선택 지침은 neon / glitch / chrome / velocity를 포함한 10가지 모두에 대해 카탈로그에 있습니다). 선택과 이유를 명시하십시오; 사용자가 결정합니다. DNA는 유형/팔레트/블렌드/모션 + 영웅 3막을 고정합니다; safe-zones v2 (palette/optics/lighting)는 이를 자동으로 이 장면에 맞게 매개변수화합니다. <project>/cinematic.json작성 —"dna": "<name>"+ thought-BLOCKS, 원시 그룹이 아님: 각 블록 = 단어 라인들 (절 경계에서 2–5개 그룹화) + 쌓이는 평면 + 라인별css(크기/굵기/스타일만 — 위치 없음) + 최대 한 줄은"hero": true로 표시 (승격된 단어;"text"는 표시 형식). 스키마:scripts/make-cinematic.cjs헤더.- 컴파일:
node scripts/make-cinematic.cjs <project>— 블록을 plan.json → index.html로 낮춥니다. 생성되는 것: 전사 순서 타이밍, 블록 내 누적, 블록 간 페이지 플립, 영웅 LOCKUP (영웅 블록의 사전 컨텍스트, HERO 및 사후 컨텍스트가 피사체 중심의 하나의 결합된 구성으로 쌓임 — 읽기 순서 위→아래 = 구성에 의한 음성 순서; 컨텍스트는 FRONT에 떠 있는 반면 영웅은 BEHIND에 임베드됨 = 깊이 샌드위치; 질량 규칙은 영웅이 컨텍스트를 지배하도록 함), apex/minor 영웅 분할, 구성에 의한 읽기 순서, safe-zones에 따른 fg 폴백. 그런 다음 게이트가 평소대로 실행됩니다. (plan.json을 직접 수동으로 작성하는 것은 블록이 표현할 수 없는 디자인의 경우 여전히 가능합니다 — 그런 다음 직접fill-timings.cjs+fit-fonts.cjs+make-composition.cjs를 실행하십시오.)
3단계 — Theme 모드 (테마 기반 구성)
먼저 themes/README.md를 읽으십시오 — 패러다임/세트피스 레지스트리, 연결, 하드 규칙 및 정확한 theme.json 스키마.
- 콘텐츠 레지스터에 따라 테마 DNA를 선택하십시오 (각
themes/<name>.json에는voice+when이 있습니다). 선택과 이유를 명시하십시오; 사용자가 결정합니다. <project>/theme.json작성 —dna,lines(그대로, 전사 순서; 1...
(이하 생략)