임베디드 자막 (Embedded Captions)
하나의 카탈로그, 미리 선택 (CATALOG.md — 17개의 아이덴티티; 그 뒤에 있는 세 가지 엔진은 백엔드 세부사항입니다). Standard(기본값)는 깔끔한 레일(대부분의 텍스트를 전달하는 하단 서브타이틀) + 피크에서 주제 뒤 장면에 합성되는 임베드 클라이맥스를 구축합니다. Cinematic은 순수 임베드입니다. 레일이 없고, 모든 자막이 주제 뒤에 합성됩니다(히로 타이포그래피, 누적, 오클루전이 효과로 사용됨). Theme는 완전한 테마 기반 구조입니다. 바디 패러다임 × 히로 세트피스 × 전면 FX × 플레이트 반응으로 구성되며, 레지스트리(themes/README.md)에서 조합됩니다: ordnance terminal neonsign stardust stomp. 대부분의 설명/내레이션은 Standard입니다; 임베드는 드물고 값진 피크입니다. 모든 단어를 임베드하는 것은 흔한 실수입니다. Theme는 VFX 급 요청("炸", "特效", "像 AE 做的")을 위한 것입니다.
작동 흐름 (요약)
아래의 설명은 깁니다. 파이프라인 자체는 짧습니다 — 결정론적인 모든 것은 계산되거나 컴파일되며, 직접 작성되지 않습니다:
- 결정 게이트(잘못된 클립 거부) → CATALOG.md에서 하나의 아이덴티티 선택 (17개 아이덴티티; 엔진/컴파일러는 조회로 결정됨 — 모드/카테고리 질문을 절대 표면화하지 않음)
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 →plan.json→fill-timings.cjs→fit-fonts.cjs→make-composition.cjs; Theme →theme.json→make-theme.cjs(레일/패널/시/테이크오버 패러다임;anchor는 조용한 레일 기본값) - Visual QA:
node scripts/preview-frames.cjs <project>→ 약 2초/프레임으로 충실한 합성 미리보기 (렌더링 없음). 렌더링 비용을 지불하기 전에 § Visual 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개; 긴 설명 → 섹션당 약 하나. 여러 히로 중에서 가장 큰 작성된 히로가 APEX (전체 락업 임베드 + 너비 맞춤 상승을 받는 유일한 히로); 작은 히로는 MINOR 피크로, 열에서 확대된 강조 라인(전경, 감쇠된 모션)으로 탑니다. 모든 비트가 매트 쇼케이스를 필요로 하는 것은 아니며, 이것이 바로 apex를 이벤트로 유지하는 이유입니다. 모든 단어를 임베드하는 것은 여전히 흔한 실수입니다.
레일-표면 아이덴티티는 정확히 이것을 구축합니다(레일 = rail.html, 임베드 = index.html의 클라이맥스). 컬럼 플로우 아이덴티티는 레일을 버리고 모든 것을 임베드 스타일로 만듭니다. 단어가 반드시 읽혀야 하는 설명/내레이션에는 권장하지 않고, 분위기-우선 요청에만 권장합니다 (CATALOG.md는 아이덴티티별로 이를 인코딩합니다).
단계 0 — CATALOG에서 하나의 아이덴티티 선택
하나의 프론트엔드, 그 뒤에 세 개의 엔진. 사용자는 CATALOG.md에서 아이덴티티를 선택합니다(17개 항목: 12 클래식 + 5 테마). 엔진, 컴파일러 및 창작 파일은 카탈로그 행에서 조회로 파생됩니다. "Standard vs Cinematic vs Theme"를 질문으로 절대 표면화하지 마십시오 — 그것들은 백엔드 이름입니다(제품은 여러 엔진이 있어도 하나의 UX를 가집니다). 카탈로그는 경로 지정에 필요한 모든 것을 인코딩합니다: 읽기 표면, 음성, 추천 대상, 씬 요구사항, 진정으로 가까운 쌍(loud↔ordnance, neon↔neonsign, cream↔stardust)에 대한 인접 참고 사항.
절차: 클립 조사 → 카탈로그에서 2–3개 아이덴티티 후보 추림 → 한 줄 이유와 함께 하나 추천 → 사용자가 선택 → 해당 아이덴티티의 파일 작성. 아이덴티티는 엔진에 고정됨(교차 조합 금지; 하나를 여는 것은 검증 이벤트 — dna/README.md 참조).
항상 추천을 제시하고 작성 전에 사용자가 선택하도록 하십시오. 조용히 기본값으로 진행하지 마십시오.
(전체 아이덴티티 테이블은 CATALOG.md에 있습니다. 경로 지정의 단일 진실 공급원입니다. 아래의 엔진 문서는 각 백엔드의 작성 계약을 설명합니다.)
추천 휴리스틱: CATALOG.md의 "후보 추림 휴리스틱"을 사용하십시오. 이는 아이덴티티 수준입니다(예: "炸"는 ordnance/stomp/terminal/loud를 후보로 추리고 WHAT이 폭발해야 하는지에 따라 선택), 절대 카테고리 수준이 아닙니다. 확실하지 않으면 → anchor.
- Cinematic →
make-composition.cjs에 의해 컴파일되는 잠긴 템플릿에 대해plan.json을 작성합니다. - 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."와 같은 단어를 환각함); 이를 따르고 거부하십시오. 제조된 단어에 자막을 추가하지 마십시오. - 소스에 이미 자막/서브타이틀/무거운 텍스트 그래픽이 포함됨(burned-in) — 두 번째 자막 시스템을 추가하면 충돌이 발생하고 푸티지는 그대로 전달됩니다(덮기/인페인팅 없음). 번인 텍스트는 종종 클립 중간에만 나타납니다: 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>
2. bash scripts/prepare.sh <project> # matte ∥ transcribe (병렬) → 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> (컴파일 + 렌더 + 플레이트 FX)
4. node scripts/preview-frames.cjs <project> # ~2초/프레임 합성 미리보기 → § Visual 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(주제에 CENTERED, 약 30–55% 가려짐)입니다.recommendation:"fg"는 가독성을 위해 NARRATION을 앞으로 이동시킵니다;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>"+ 생각-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–5개 단어 —takeover의 경우 각 라인은 하나의 CARD),minors(강조 단어),hero:{match}(클라이맥스 단어/구문; 임베드 세트피스의 경우lines에서 제외, 인라인 세트피스 및 패널+레닥트의 경우 포함).- 렌더링:
bash scripts/render-theme.sh <project>— 컴파일(컴파일 시점의 완전성 게이트), 두 레이어 렌더링, 합성, 플레이트 반응 적용 →final_fx.mp4. Visual QA를 위해 컴파일과 렌더링 사이에preview-frames.cjs를 사용하십시오.
Visual QA — 렌더링 전에 미리보기
node scripts/preview-frames.cjs <project> [t…]은 약 2초/프레임으로 충실한 미리보기 프레임을 합성합니다
(자막 레이어를 탐색 시점에 스크린샷 + 실제 비디오 프레임 + 매트 오클루전 + 레일 오버레이 = 그 순간 최종 합성이 어떻게 보일지).
기본 샘플 = 각 그룹/클라이맥스 윈도우.
전체 렌더링은 몇 분이 걸립니다. 레이아웃 문제를 _발견_하기 위해 렌더링을 사용하지 마십시오.
미리보기(<project>/preview/sheet.png)를 다음 기준으로 확인하십시오