HyperFrames 미디어 전처리
컴포지션용 에셋을 생성하는 세 가지 CLI 명령어: tts (음성), transcribe (타임스탬프), 그리고 remove-background (투명 비디오). 각 명령어는 첫 실행 시 모델을 다운로드하고 ~/.cache/hyperframes/에 캐시합니다. 출력물을 프로젝트에 넣은 다음 컴포지션 HTML에서 참조하세요 — 오디오/비디오 요소 규칙은 hyperframes 스킬을 참조하세요.
텍스트-음성 변환 (tts)
Kokoro-82M으로 로컬에서 음성 오디오를 생성합니다. API 키가 필요 없습니다.
npx hyperframes tts "여기에 텍스트" --voice af_nova --output narration.wav
npx hyperframes tts script.txt --voice bf_emma --output narration.wav
npx hyperframes tts --list # 모든 54개 목소리 목록
목소리 선택
콘텐츠 유형에 맞게 목소리를 선택하세요. 기본값은 af_heart입니다.
| 콘텐츠 유형 | 목소리 | 이유 |
|---|---|---|
| 제품 데모 | af_heart/af_nova | 따뜻하고 프로페셔널함 |
| 튜토리얼 / 방법 | am_adam/bf_emma | 중립적이고 따라하기 쉬움 |
| 마케팅 / 프로모션 | af_sky/am_michael | 활기차거나 권위적임 |
| 문서화 | bf_emma/bm_george | 명확한 영국식 영어, 공식적임 |
| 캐주얼 / 소셜 | af_heart/af_sky | 친근하고 자연스러움 |
다국어 지원
목소리 ID는 첫 글자에 언어를 인코딩합니다: a=미국 영어, b=영국 영어, e=스페인어, f=프랑스어, h=힌디어, i=이탈리아어, j=일본어, p=브라질 포르투갈어, z=중국어. CLI는 접두사에서 음소화기 로케일을 자동 감지합니다 — 목소리가 텍스트와 일치하면 --lang이 필요 없습니다.
npx hyperframes tts "La reunión empieza a las nueve" --voice ef_dora --output es.wav
npx hyperframes tts "今日はいい天気ですね" --voice jf_alpha --output ja.wav
오토 감지를 재정의하려는 경우에만 --lang을 사용하세요 (양식화된 억양). 유효한 코드: en-us, en-gb, es, fr-fr, hi, it, pt-br, ja, zh. 비영어 음소화는 시스템 전체에 espeak-ng가 필요합니다 (brew install espeak-ng / apt-get install espeak-ng).
속도
0.7-0.8— 튜토리얼, 복잡한 콘텐츠, 접근성1.0— 자연스러운 속도 (기본값)1.1-1.2— 인트로, 전환, 활기찬 콘텐츠1.5+— 거의 적절하지 않음; 신중히 테스트하세요
긴 스크립트
몇 단락 이상인 경우 .txt 파일에 작성하고 경로를 전달하세요. 약 5분 이상의 음성 입력은 여러 세그먼트로 나누는 것이 좋습니다.
요구 사항
Python 3.8+ 및 kokoro-onnx와 soundfile (pip install kokoro-onnx soundfile). 첫 사용 시 모델 다운로드 (~311 MB + ~27 MB 목소리, ~/.cache/hyperframes/tts/에 캐시됨).
전사 (transcribe)
단어 수준 타임스탬프가 포함된 정규화된 transcript.json을 생성합니다.
npx hyperframes transcribe audio.mp3
npx hyperframes transcribe video.mp4 --model small --language es
npx hyperframes transcribe subtitles.srt # 기존 자막 가져오기
npx hyperframes transcribe subtitles.vtt
npx hyperframes transcribe openai-response.json
언어 규칙 (필수 사항)
사용자가 명시적으로 오디오가 영어라고 말하지 않는 한 절대 .en 모델을 사용하지 마세요. .en 모델 (small.en, medium.en)은 비영어 오디오를 전사하지 않고 영어로 번역합니다. 이는 조용히 원래 언어를 파괴합니다.
- 언어를 알고 있고 비영어인 경우 →
--model small --language <코드>(.en접미사 없음) - 언어를 알고 있고 영어인 경우 →
--model small.en - 언어를 모르는 경우 →
--model small(.en없음,--language없음) — whisper가 자동 감지
기본 모델은 small이며, small.en이 아닙니다.
모델 크기
| 모델 | 크기 | 속도 | 사용 시기 |
|---|---|---|---|
tiny | 75 MB | 가장 빠름 | 빠른 미리보기, 파이프라인 테스트 |
base | 142 MB | 빠름 | 짧은 클립, 깨끗한 오디오 |
small | 466 MB | 보통 | 기본값 — 대부분의 콘텐츠 |
medium | 1.5 GB | 느림 | 중요한 콘텐츠, 시끄러운 오디오, 음악 |
large-v3 | 3.1 GB | 가장 느림 | 프로덕션 품질 |
보컬이 있는 음악: 최소 medium부터 시작; 제작된 트랙은 종종 수동 SRT/VTT 가져오기가 필요합니다. 캡션 품질 확인(모든 전사 후 필수), 정리 JS, 재시도 규칙, OpenAI/Groq API 가져오기 경로에 대해서는 hyperframes/references/transcript-guide.md를 참조하세요.
출력 형태
컴포지션은 단어 객체의 평면 배열을 사용합니다. id 필드 (w0, w1, ...)는 캡션 오버라이드에서 안정적인 참조를 위해 정규화 중에 추가됩니다; 하위 호환성을 위해 선택 사항입니다.
[
{ "id": "w0", "text": "Hello", "start": 0.0, "end": 0.5 },
{ "id": "w1", "text": "world.", "start": 0.6, "end": 1.2 }
]
배경 제거 (remove-background)
비디오나 이미지에서 배경을 제거하여 피사체(일반적으로 사람 — 아바타, 프레젠터, 토크 헤드)가 컴포지션에서 투명 오버레이로 표시되도록 합니다.
npx hyperframes remove-background subject.mp4 -o transparent.webm # 기본값: VP9 알파 WebM
npx hyperframes remove-background subject.mp4 -o transparent.mov # ProRes 4444 (편집용)
npx hyperframes remove-background portrait.jpg -o cutout.png # 단일 이미지 컷아웃
npx hyperframes remove-background subject.mp4 -o subject.webm \
--background-output plate.webm # 한 번에 두 레이어 모두
npx hyperframes remove-background subject.mp4 -o transparent.webm --device cpu
npx hyperframes remove-background --info # 감지된 공급자 표시
u2net_human_seg (MIT)를 사용합니다. 첫 실행 시 약 168 MB의 가중치를 ~/.cache/hyperframes/background-removal/models/에 다운로드합니다.
레이어 분리 (--background-output)
--background-output (또는 -b)를 전달하여 컷아웃과 함께 두 번째 투명 비디오를 내보냅니다: 동일한 소스 RGB, 알파는 mask 대신 255 − mask입니다. 컷아웃은 배경이 투명한 피사체이고, 플레이트는 피사체가 있던 자리에 투명한 구멍이 있는 원래 배경입니다.
| 파일 | 알파는… | 사용 용도 |
|---|---|---|
-o subject.webm | 마스크 — 피사체 불투명, 배경 투명 | 전경 레이어, 맨 위에 배치 |
--background-output plate.webm | 역 — 배경 불투명, 피사체 영역 투명 | 하단 레이어; 이 레이어와 피사체 사이에 텍스트나 그래픽 배치 |
두 출력 모두 동일한 --quality 사전 설정을 공유하고 단일 추론 패스로 실행됩니다 — 인코딩 비용은 약 두 배가 되지만 분할 비용은 동일합니다. 비디오 입력 및 .webm/.mov 출력에서만 유효합니다.
구멍이 뚫린 플레이트, 인페인팅된 깨끗한 플레이트가 아닙니다. plate.webm의 피사체 영역은 완전히 투명합니다 — 그 아래에 불투명한 무언가를 합성하여 구멍을 채우세요. --background-output가 올바른 도구인지 판단하는 단일 테스트: 피사체가 있던 자리에 피사체의 실루엣을 통해 무언가가 보일 수 있습니까?
| 사용 사례 | 올바른 도구 |
|---|---|
| 컷아웃과 플레이트 사이의 텍스트/그래픽 (이 명령어의 존재 이유) | 구멍 뚫기 (--background-output) |
| 관련 없는 장면 위에 피사체 | subject.webm만 사용; 플레이트는 무시 |
| 다른 콘텐츠 없이, 사람 없는 방을 단독으로 표시 | 깨끗한 플레이트 — 인페인터(LaMa, ProPainter, E2FGVI)가 필요. 이 명령어로 불가능. |
| 피사체를 다른 피사체로 교체 | 깨끗한 플레이트 — 위와 동일 |
사용자가 "사람이 제거된 방"을 요청하고 단독으로 표시하려는 경우, --background-output을 사용하지 마세요. 인페인터가 필요하다고 알려주세요.
일반적인 계층형 컴포지션 (표준적인 구멍 뚫기 사용 사례):
<!-- z=1 역알파 플레이트는 피사체 영역을 제외한 모든 것을 채웁니다 -->
<video
src="plate.webm"
data-start="0"
data-duration="6"
data-track-index="0"
muted
playsinline
></video>
<!-- z=2 그래픽 / 텍스트는 두 레이어 사이에 위치합니다 -->
<h1 id="headline" style="z-index:2; ...">MAKE IT IN HYPERFRAMES</h1>
<!-- z=3 컷아웃이 피사체를 헤드라인 위로 다시 띄웁니다 -->
<div class="cutout-wrap" style="position:absolute;inset:0;z-index:3">
<video
src="subject.webm"
data-start="0"
data-duration="6"
data-track-index="1"
muted
playsinline
></video>
</div>
이는 아래의 텍스트-피사체-뒤 패턴과 기능적으로 동일하지만, 프로젝트에 원본 presenter.mp4가 필요하지 않습니다 — 플레이트가 이를 대체합니다. 두 개의 투명 레이어만 제공하고 사용자가 그 사이에 임의의 콘텐츠를 드롭할 수 있도록 할 때 유용합니다.
출력 형식
| 형식 | 사용 시기 |
|---|---|
.webm (VP9 + 알파) | 기본값. 컴포지션은 <video>를 통해 직접 재생합니다. |
.mov (ProRes 4444) | DaVinci/Premiere/FCP에서 편집. 대용량 파일. |
.png | 단일 이미지 컷아웃 (정지된 피사체, 배경 위에 레이어됨). |
Chrome은 VP9 알파를 기본적으로 디코딩하므로, .webm은 다른 음소거 자동 재생 비디오처럼 컴포지션에 연결됩니다 — <video> 트랙 규칙은 hyperframes 스킬을 참조하세요.
품질 사전 설정
--quality fast|balanced|best는 VP9 인코더의 CRF만 제어합니다 — 분할 품질은 고정됩니다.
| 사전 설정 | CRF | 사용 시기 |
|---|---|---|
fast | 30 | 반복 작업, 더 작은 파일, 느슨한 색상 일치 |
balanced | 18 | 기본값. 대부분의 용도에서 시각적으로 동일함 |
best | 12 | 마스터 / 최종 전달. 가장 큰 파일, 가장 정확한 일치 |
합성 패턴 — 올바른 패턴 선택
컷아웃 webm은 소스 mp4의 RGB를 재인코딩한 복사본입니다. 이 선택은 그 뒤에 무엇을 배치하느냐에 따라 결과가 달라집니다:
| 패턴 | 컷아웃 뒤에 있는 것 | 결과 |
|---|---|---|
| 다른 장면 위의 컷아웃 (가장 일반적) | 정적 이미지, 그라데이션, 또는 관련 없는 비디오 | 훌륭함. 컷아웃의 RGB는 피사체의 유일한 소스 — 이중화나 가장자리 헤일로가 없음. 이것이 remove-background가 만들어진 목적입니다. |
| 자체 소스 mp4 위의 컷아웃 (텍스트-피사체-뒤) | 컷아웃이 생성된 동일한 mp4 | 같은 사람에 대한 두 개의 RGB 소스. 기본 --quality balanced (crf 18)에서는 이중화가 거의 보이지 않음; --quality fast (crf 30)에서는 희미한 색상 이동/가장자리 헤일로가 보입니다. 마스터에는 --quality best (crf 12)를 사용하세요. |
| 동일한 사람의 다른 테이크 위의 컷아웃 | 동일한 피사체의 영상 | 두 명의 다른 사람이 겹쳐 있는 것처럼 보입니다. 이렇게 하지 마세요. |
텍스트-피사체-뒤 (프레젠터 뒤의 헤드라인):
<video
src="presenter.mp4"
id="bg"
data-start="0"
data-duration="6"
data-track-index="0"
muted
playsinline
></video>
<h1 id="headline" style="z-index:2; ...">MAKE IT IN HYPERFRAMES</h1>
<div class="cutout-wrap" style="position:absolute;inset:0;z-index:3;opacity:0">
<video
src="presenter.webm"
data-start="0"
data-duration="6"
data-track-index="1"
muted
playsinline
></video>
</div>
두 가지 핵심 규칙:
- 컷아웃 비디오를 시간이 지정되지 않은
<div>로 감싸고 래퍼의 불투명도를 애니메이션화하세요. 비디오 요소 자체가 아닙니다. 프레임워크는 활성 클립(data-start/data-duration이 있는 모든 요소)에 대해 불투명도:1을 강제하므로, 비디오의 불투명도를 직접 애니메이션화하면 조용히 재정의됩니다. 래퍼에는data-*속성이 없으므로 CSS/GSAP가 소유합니다. - 두 비디오 모두
data-start="0"및data-media-start="0"을 사용하여 프레임워크가 t=0에서 동기식으로 디코딩합니다. 컷아웃을 늦게 마운트(data-start=3.3)하면 시크 + 웜업이 발생하여 기본 mp4와 한 프레임 차이가 납니다 — 컷에서 한 프레임의 정렬 불량으로 보입니다.
그런 다음 GSAP으로 컷에서 래퍼 불투명도를 전환합니다: tl.set(cutoutWrap, { opacity: 1 }, 3.3).
TTS → 전사 → 캡션
사전 녹음된 음성 해설이 없는 경우, 음성 해설을 생성하고 다시 전사하여 캡션용 단어 수준 타임스탬프를 얻습니다:
npx hyperframes tts script.txt --voice af_heart --output narration.wav
npx hyperframes transcribe narration.wav # → transcript.json
그런 다음 transcript.json을 캡션 트랙으로 사용합니다. 타임라인 규칙은 hyperframes 스킬을 참조하세요. 온디맨드 음성 해설이 있는 동영상은 스크립트에서 음성을 생성하고 정확한 캡션을 로컬에서 추출할 수 있으므로, 마이크 없이도 전문적인 품질을 얻을 수 있습니다.