임베디드 캡션 (Embedded Captions)
하나의 카탈로그, 전면에 배치 (CATALOG.md — 17개 아이덴티티; 그 뒤에 있는 세 가지 엔진은 백엔드 세부사항입니다). 스탠다드 (기본값)는 깔끔한 레일(대부분의 텍스트를 담는 하단 서브타이틀)을 만들고, 클라이맥스에서 피사체 뒤 장면 안에 합성된 임베드를 추가합니다. 시네마틱은 순수 임베드 — 레일 없이, 모든 캡션이 피사체 뒤에 합성됩니다 (히로 타이포그래피, 누적, 가려짐 효과). 테마는 완전한 테마 구성으로, 신체 패러다임 × 히로 세트피스 × 전면 효과 × 플레이트 반응으로 구성되며 레지스트리(themes/README.md)에서 조합합니다: ordnance terminal neonsign stardust stomp. 대부분의 설명/내레이션 영상은 스탠다드가 적합하며, 임베드는 희소하고 값진 강조입니다 — 모든 단어를 임베드하는 것이 흔한 실수입니다. 테마는 VFX 수준의 요청("炸", "特效", "AE처럼")에 사용됩니다.
운영 흐름 (요약)
아래 설명은 깁니다. 하지만 파이프라인 자체는 짧습니다 — 결정론적인 모든 것은 수동으로 작성되지 않고 계산되거나 컴파일됩니다:
- 의사결정 게이트 (나쁜 클립 거부) → CATALOG.md에서 하나의 아이덴티티 선택 (17개 아이덴티티; 엔진/컴파일러는 조회로 결정 — 모드/카테고리 질문 절대 표시 금지)
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(정확한 하단 서브타이틀, 전면, 대부분의 텍스트 전달) /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에서 아이덴티티를 선택합니다 (17개 항목: 12개 클래식 + 5개 테마); 엔진, 컴파일러 및 작성 파일은 카탈로그 행에서 조회하여 결정됩니다. "스탠다드 vs 시네마틱 vs 테마"를 질문으로 표시하지 마십시오 — 이들은 백엔드 이름입니다 (하나의 제품은 여러 엔진을 가지고 있어도 하나의 UX를 가집니다). 카탈로그는 라우팅에 필요한 모든 것을 인코딩합니다: 읽기 표면, 음성, 추천 대상, 씬 요구사항, 진정으로 가까운 쌍(loud↔ordnance, neon↔neonsign, cream↔stardust)에 대한 인접 참고사항.
절차: 클립 분석 → 카탈로그에서 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% 지점에서
샘플을 읽으십시오. 다음 조건이면 거부:
- 여러 명의 화자 / 하드 컷 (각 샷을 분할하여 렌더링하거나 거부)
- 사람 피사체 없음 (이 스킬은 talking-head 용도)
- 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> --skip-skills
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 실행; 산출물은 final_fx.mp4, final.mp4는 플레이트 반응 전)
3단계는 모드에 따라 다릅니다:
3단계 — 시네마틱 모드 (순수 임베드)
- 먼저
safe-zones.json을 읽으십시오. 내레이션 평면은 **zones.hugLeft/hugRight**에 배치됩니다 — 실루엣에 ABUTTING되는 깨끗한 띠 (몸에서 멀리 떨어진 텍스트는 떠 있는 것처럼 보이며 임베드되지 않음; 먼 모서리는 기본값이 아닌 대비책). 히로는 기본적으로heroAnchor/heroBands.best(피사체에 CENTERED, ~30–55% 가려짐)에 배치됩니다.recommendation:"fg"는 가독성을 위해 내레이션을 전면으로 이동시킵니다; 히로는heroBands.feasible일 때마다 임베드 상태를 유지합니다 — 불가능할 때만 전면 대비책을 사용하십시오.