플러그인 설치: 설정 또는 업데이트 명령을 실행하기 전에, 이 스킬이 HyperFrames 플러그인 내부에 있을 경우 플러그인 실행 규칙을 따르십시오. 독립 실행형 설치의 경우 아래 업데이트 지침을 따르십시오.
먼저, 이 스킬을 최신 상태로 유지하십시오 — 실행 전 사용자 확인:
npx hyperframes skills update embedded-captions. 모든 것이 최신 상태이면 빠르게 아무 작업도 하지 않습니다. 그렇지 않으면, 의존하는 핵심 도메인 스킬과 함께 이 스킬을 업데이트합니다.
Embedded Captions
하나의 카탈로그, 미리 선택 (CATALOG.md — 35개의 정체성; 그 뒤의 엔진은 백엔드 세부 사항입니다). Standard(기본값)는 깨끗하고 문자 그대로의 레일(대부분의 텍스트를 담는 하단 서브타이틀) + 피크에서 인물 뒤로 합성된 임베드 클라이맥스를 만듭니다. Cinematic은 순수 임베드입니다 — 레일 없음, 모든 캡션이 인물 뒤에 합성됩니다(히어로 타이포그래피, 누적, 가려짐 효과). Theme는 완전한 테마 구조 — 레지스트리에서 구성된 바디 패러다임 × 히어로 세트피스 × 전면 효과 × 플레이트 반응입니다 (themes/README.md): ordnance terminal neonsign stardust stomp. 대부분의 설명/내레이션은 Standard입니다; 임베드는 드물고 가치 있는 피크입니다 — 모든 단어를 임베드하는 것이 흔한 실수입니다; Theme는 VFX 수준의 요청("炸", "特效", "像 AE 做的")을 위한 것입니다.
런타임 전제 조건
플러그인 설치는 매트 생성, 전사 및 렌더링을 위해 번들로 제공되는 매니페스트 고정 CLI를 사용합니다. 소스 체크아웃이 필요하지 않습니다. 로컬 미리보기 및 캡션 측정 도우미에는 Sharp, Puppeteer(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에서 ONE 정체성 선택 (35개 정체성; 엔진/컴파일러는 조회로 파생됨 — 모드/카테고리 질문을 절대 표시하지 마십시오)
hyperframes init(프로젝트 디렉토리가 이미 비디오와 함께 존재하는 경우 건너뛰십시오 —matte.cjs/transcribe.cjs는 디렉토리의 모든 비디오를 source.mp4로 채택합니다) →bash scripts/prepare.sh <project>(매트 생성 ∥ 전사 ∥ 오디오 엔벨로프를 병렬로 실행한 다음, 씬 팔레트/광학/조명을 사용한 safe-zones v2 — 하나의 명령, 잊힌 것이 없음)- 작은 JSON 창작 선택 작성 (먼저
safe-zones.json읽기): Cinematic →cinematic.json→make-cinematic.cjs(plan.json을 파생하고 컴파일함); Theme →theme.json→make-theme.cjs(레일/패널/포엠/테이크오버 패러다임;anchor는 조용한 레일 기본값) - 시각적 QA:
node scripts/preview-frames.cjs <project>→ ~2초/프레임으로 신뢰할 수 있는 합성 미리보기 (렌더링 없음). 렌더링 비용을 지불하기 전에 § Visual QA를 확인하십시오. render-and-composite.sh→ 게이트 (타이밍 / 가려짐+히어로 / 오버플로우 / 핸드오프) →final.mp4
사람들이 놓치는 중요한 규칙:
- 레일 (기본값) + 임베드 (승격).
drop(필러, 표시되지 않음) /rail(문자 그대로의 하단 서브타이틀, 앞에, 대부분의 텍스트를 전달) /embed(인물 뒤에 합성된 피크 단어). Standard 모드는 둘 다 수행하며, 피크만 임베드합니다. § Caption model을 참조하십시오. - 비디오는 UNTOUCHED 상태로 제공됩니다 (Standard/Cinematic; Theme 모드의 PLATE 예산만 유일한 허용 예외 — 테마 DNA별로 정의된 레지스터 게이트 반응 비트(차지-딤, 펀치, 셰이크, 그레인)가 매트 합성 후 적용되어 피사체+텍스트+플레이트가 하나의 프레임으로 움직입니다) — 캡션만 추가됩니다. 매트는 피사체가 임베드 트랙을 가릴 수 있도록 할 뿐입니다. 영상을 그레이딩/리컬러/스캔라인 처리하지 마십시오.
- 두 가지 규칙집: 레일 → references/rail.md (얇음), 임베드 제작 → references/composition-craft.md (풍부함, 임베드 전용). 필요에 따라 훑어보십시오.
캡션 모델 — 레일 + 임베드
모든 음성 구문은 다음 세 가지 중 하나입니다:
| 무엇 | 어떻게 표시됨 | |
|---|---|---|
| drop | 필러 — 음/어, 더듬거림, 자기 수정 | 표시되지 않음 |
| rail | 기본값 — 일반적인 음성 내용 (문자 그대로) | 깨끗한 하단 서브타이틀, 앞에, 읽기 쉽게. 펀치 단어는 인라인 emphasis 하이라이트(액센트 색상 / 활성 단어 팝)를 얻을 수 있습니다 — 레일에 유지됩니다. |
| embed | 승격된 피크 — 핵심 비트 | 하나의 큰 단어가 피사체 뒤에 합성됨 (매트 가려짐), 디자인된 진입 + 종료 |
레일은 대부분의 텍스트를 전달합니다. 임베드는 드물고 가치 있는 피크입니다. 희소성은 클립당이 아니라 비트/블록당입니다: 블록(생각)당 ≤1 히어로, 절대 두 개가 동시에 보이지 않음, 히어로 창 사이에 최소 한 비트의 공백 (컴파일러가 0.6초 미만에서 경고). 짧은 클립 → 보통 1–2개; 긴 설명 → 섹션당 약 하나. 여러 히어로 중에서 가장 큰 히어로는 APEX입니다 (전체 잠금 임베드 + 너비 맞춤 상승을 얻음); 작은 히어로는 MINOR 피크로, 열을 따라 크기가 강조된 라인(fg, 감쇠된 모션)으로 탑니다 — 모든 비트가 매트 쇼케이스를 필요로 하는 것은 아니며, 이것이 정확히 APEX를 이벤트로 유지하는 이유입니다. 모든 단어를 임베드하는 것은 여전히 흔한 실수입니다.
레일-표면 정체성은 정확히 이것을 구축합니다 (레일 = rail.html, 클라이맥스 = index.html의 임베드). 열-흐름 정체성은 레일을 없애고 모든 것을 임베드 스타일로 만듭니다 — 단어를 읽어야 하는 설명/내레이션이 아닌, 분위기-중심 요청에만 권장하십시오 (CATALOG.md는 정체성별로 이를 인코딩합니다).
0단계 — CATALOG에서 ONE 정체성 선택
하나의 프론트엔드, 세 개의 백엔드. 사용자가 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 템플릿은 크림+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: 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초/프레임 합성 미리보기 → § Visual 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 모드 (순수 임베드)
- 먼저
safe-zones.json을 읽으십시오. 나레이션 평면은 **zones.hugLeft/hugRight**에 배치됩니다 — 실루엣에 인접한 깨끗한 스트립 (몸에서 먼 텍스트는 떠 있는 것처럼 읽히며, 임베드되지 않음; 먼 코너는 기본값이 아닌 대체 수단입니다). 히어로는 기본적으로heroAnchor/heroBands.best로 설정됩니다 (피사체 중심, ~30–55% 가려짐).recommendation:"fg"는 가독성을 위해 NARRATION을 앞으로 이동시킵니다; 히어로는heroBands.feasible일 때마다 임베드된 상태로 유지됩니다 — hero-fg는 최후의 수단입니다. - DNA는 0단계에서 선택한 정체성입니다 —
cinematic.json의 템플릿 변수(색상표, 그림자, 대비율)는 해당 정체성의 DNA에서 잠겨 있습니다. 사용자 정의 색상/크기를 선택할 수 없습니다. 정체성이 텍스트 스타일입니다. - 히어로 블록을 선택하십시오. transcript.json을 읽고, 이야기 핵심 단어를 식별하십시오. 하나의 블록(생각)에 대해 하나의 히어로를 선택하십시오. 히어로 선정 규칙 (드물고, 타이밍이 중요하며, 의미상 최대치이어야 하고, 두 개의 히어로가 0.6초 이내에 겹치거나 나타나지 않아야 함 —
make-cinematic.cjs가 경고합니다). 히어로는 텍스트를 향상시키는 조명 패턴을 받습니다. 대부분의 단어는 레일에 남습니다. 텍스트 전반에 걸쳐 히어로를 뿌리지 마십시오. - 드롭을 표시하십시오 (선택 사항이지만 권장됨). 필러 단어(음, 어, 그니까)를 드롭 목록에 추가하십시오. 제공되지 않으면 컴파일러는 일반적인 필러의 기본 목록을 사용합니다.
- 사용자가 beam 계정을 가지고 있거나 특별히 요청하지 않는 한, 모션 라인 또는 스캔라인 효과를 보내지 마십시오.
cinematic.json이 이를 활성화하는 옵션을 제공하더라도, 기본값은 "정체성 정의" CSS와 부드러운 페이드/스케일 전환("액션" 값은 'fade' 또는 'scale')입니다. 요청 시 히어로를 위한 미묘한 빔을 켜는 것은 괜찮지만, 기본값은 깨끗합니다.
3단계 (대체) — Theme 모드
Theme에 대한 JSON 작성은 themes/README.md에 설명되어 있습니다. 이는 Cinematic과 구조가 다릅니다. render-theme.sh 스크립트는 theme.json을 반복하고, 테마별 파서로 각 DNA를 컴파일하고, 캡션 합성 및 플레이트 비트(차지-딤, 펀치, 그레인)를 위한 MicroBlaze 렌더 그래프를 준비합니다. 최종 결과물은 final_fx.mp4입니다 (동기화된 플레이트 반응이 있는 최종 합성). final.mp4는 플레이트 반응이 없는 중간 단계일 수 있습니다. Theme가 데이터를 보존하는 방법에 대한 세부 사항은 themes/README.md에 있습니다.
Visual QA
렌더링 비용을 지불하기 전에, ~2초/프레임 미리보기를 검토하십시오:
node scripts/preview-frames.cjs <project>
다음을 확인하십시오:
- 오클루전. 히어로는 인물 뒤에 있습니까? 아니면 앞에 떠 있습니까(safe-zones 참조)?
- 가독성. 모든 단어를 읽을 수 있습니까? 화면의 텍스트 밀도가 합리적입니까?
- 히어로 배치. 히어로는 피사체와 잘 정렬되어 있습니까? 하나의 비트에 두 개의 히어로가 활성화되어 있습니까(컴파일러 경고)?
- 매트 충실도. 매트 가장자리가 프레임 전체에서 깔끔합니까? 빠른 움직임이 깜빡임을 유발합니까?
- 합성 일관성. 임베드된 텍스트는 조명 환경에 속하는 것처럼 보입니까, 아니면 분리되어 보입니까? 색상, 질감 및 깊이를 확인하십시오.
렌더링을 요청하기 전에 안심할 때까지 미리보기를 반복하십시오.
렌더링
합성은 render-and-composite.sh가 CLI가 완료될 때까지 기다립니다. 프로세스는 여러 단계를 거칩니다:
- 타이밍 게이트. 오디오 지터 및 히어로 간격 검사.
- 가려짐 + 히어로. 매트 위에 임베드된 텍스트의 최종 배치.
- 오버플로우 게이트. 텍스트가 사용 가능한 영역을 초과하지 않는지 확인합니다.
- 핸드오프. 최종.mp4를 렌더링합니다.
Theme 모드: render-theme.sh는 자체 렌더링을 처리하고 플레이트 반응 효과를 추가합니다.
캡션 히스토리 및 버전 관리
history/ 디렉토리는 모든 이전 렌더링의 스냅샷을 유지합니다:
history/
2025-03-21T15-04-22_final.mp4
2025-03-21T15-04-22_transcript.json
2025-03-21T15-04-22_safe-zones.json
...
이를 통해 진행 상황을 추적하고, 필요한 경우 되돌리거나, 캡션 디자인을 반복할 수 있습니다.
문제 해결
매트가 깜빡임
- 움직임이 너무 빠름. 더 긴 시간 창으로
safe-zones를 다시 생성하거나 비디오를 안정화하십시오. - 피사체가 배경과 대비가 낮음.
prepare.sh실행 전에MATTE_CONTRAST=1.5를 시도하십시오.
전사가 정확하지 않음
- 악센트가 강한 음성. 더 큰 모델로 다시 전사:
WHISPER_MODEL=medium또는WHISPER_MODEL=large. - 배경 소음.
transcribe.cjs를 수동으로 실행하기 전에ffmpeg로 오디오를 전처리하십시오(노이즈 게이트, 필터).
히어로가 잘려 보임
- safe-zones 확인. 히어로가
heroAnchor영역 내에 완전히 배치되었는지 확인하십시오. - 더 작은 텍스트 크기 사용.
make-cinematic.cjs가 경고하는 경우 텍스트 크기를 조정하십시오.