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는 접두사에서 음소 변환기(phonemizer) 로케일을 자동 감지합니다. — 목소리가 텍스트와 일치하면 --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 <code>(.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) 사용. 첫 실행 시 약 168MB의 가중치를 ~/.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이 있는 모든 요소)에 opacity: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
# … (필요한 경우 배경 제거도 사용)