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)를 사용합니다. 첫 실행 시 약 168MB의 가중치를 ~/.cache/hyperframes/background-removal/models/에 다운로드합니다.
흰색 외곽선이 있는 다이컷 스티커에는 u2net을 사용하지 마세요
remove-background (u2net)는 현저한 객체 분할입니다 — 피사체의 몸체를 분할하고 흰색 다이컷 외곽선을 잘라냅니다. 그림 주변의 흰색 선이 "객체"가 아니기 때문입니다. 평평한 알려진 색상 배경에 흰색 외곽선으로 렌더링된 투명 Telegram/메시징 스티커의 경우, 피사체를 분할하는 대신 배경을 키잉하세요:
- 평평한 배경을 플러드 필. PIL
ImageDraw.floodfill을 네 모서리 모두의 점(약 24px 간격)에서 시드하고, 채워진 픽셀 → 알파 0, 나머지는 불투명으로 표시합니다. 이렇게 하면 흰색 외곽선, 내부 동일 색상 소품, 분리된 섬(몸체와 분리된 날아가는 컵이 자체 외곽선 유지)이 보존됩니다. 생성 프롬프트가 피사체를 평평한 균일 배경에 배치하고 흰색 다이컷 외곽선을 명시적으로 요청해야 합니다. - 외곽선 없는 변형(구워진 외곽선 제거보다 깔끔함): 각 이미지를 image-to-image로 다시 실행 — 완성된 렌더링을
--ref로 전달하고 "동일한 포즈/소품을 재현하지만 흰색 외곽선을 제거하고 평평한 순수 크로마키 그린(#00b140) 배경에 배치"라고 프롬프트한 다음, 소프트 크로마키로 그린을 키잉하고 절대 이진 마스크를 사용하지 마세요(alpha = clip((HIGH-(G-max(R,B)))/(HIGH-LOW),0,1), LOW≈30 HIGH≈95, 전역 디스필G = min(G, max(R,B))추가). 이진 플러드 필 + 침식은 계단/앨리어싱 가장자리를 생성합니다 — 침식 대신 이진 알파를 블러(GaussianBlur(0.8))하여 부드러운 가장자리를 만듭니다. - 메시징 스티커 크기 조정: 솔리드 알파 바운딩 박스로 자르고 긴 쪽을 정확히 대상(예: 512)으로 스케일링 — 512² 정사각형으로 패딩하지 마세요(피사체가 작아지고 주변에 빈 공간이 생깁니다).
적용되지 않는 경우: 비디오 오버레이용 사람 컷아웃(u2net이 올바른 도구임); 다이컷 외곽선이 없는 아트; 불균일/복잡한 배경의 피사체(플러드 필에는 평평한 키 색상이 필요함).
레이어 분리 (--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)에서는 미묘한 색상 변이나 가장자리 불일치가 보일 수 있습니다. 이러한 이유로 --background-output 권장 — 플레이트가 원래 배경을 제공하므로 시각적 중복이 없습니다. |
| 단색 배경 위의 컷아웃 | 단색 (검정, 흰색, 회색) | 배경의 단색이 컷아웃 가장자리의 압축 아티팩트를 강조할 수 있습니다. --quality best (crf 12)는 아티팩트를 최소화하지만 파일 크기가 증가합니다. |
| 그라데이션 또는 텍스처 배경 위의 컷아웃 | 그라데이션, 패턴 또는 텍스처 | 잘 작동합니다. 배경의 시각적 복잡성이 가장자리 아티팩트를 숨깁니다. |
| 알파 블렌딩 지원 없음 | 컷아웃 아래에 아무것도 없음 (깜빡임) | 컷아웃을 rgba(0,0,0,0) 배경의 HTML 요소로 감싸거나 의도된 배경을 명시적으로 포함해야 합니다. |
<!-- 텍스트-뒤-피사체 패턴 (구멍 뚫기 플레이트 사용) -->
<video src="plate.webm" data-start="0" data-duration="6" data-track-index="0" muted playsinline></video>
<div style="position:absolute;inset:0;display:flex;align-items:center;justify-content:center;z-index:2">
<h1>텍스트</h1>
</div>
<video src="subject.webm" data-start="0" data-duration="6" data-track-index="1" muted playsinline style="z-index:3"></video>
‘투명’ 처리 vs 실제 알파
투명 WebM은 알파 채널을 지원하지만 모든 비디오 형식이 그런 것은 아닙니다:
| 형식 | 알파 지원 | 참고 |
|---|---|---|
.webm (VP9) | 예 | Chrome/Firefox에서 기본 지원. <video>에서 직접 재생. |
.mov (ProRes 4444) | 예 | 편집 소프트웨어용. .mp4 또는 .webm보다 파일 크기가 훨씬 큼. |
.png | 예 | 정적 이미지 컷아웃. |
.jpg | 아니요 | 배경 제거 출력에 사용하지 마세요. |
.mp4 | 아니요 | 배경 제거 출력에 사용하지 마세요. |
요구 사항
Python 3.8+ 및 opencv-python, numpy, Pillow, onnxruntime이 필요합니다 (pip install opencv-python numpy Pillow onnxruntime). 모델은 첫 사용 시 다운로드됩니다 (~168 MB, ~/.cache/hyperframes/background-removal/models/에 캐시됨).
GPU 가속 (CUDA)을 위해 onnxruntime-gpu를 설치하세요. CPU 가용성 자동 감지; --device cpu로 재정의.
일반 팁
- 파이프라인: 이 도구들은 함께 사용하도록 설계되었습니다. 일반적인 워크플로:
tts로 음성 생성 → 오디오를transcribe에 전달하여 캡션 생성 → 배경이 있는 비디오에remove-background를 실행하여 투명 오버레이 생성 → 모두 하나의 HyperFrames 컴포지션으로 결합. - 캐싱: 각 도구는 첫 실행 시 해당 모델을
~/.cache/hyperframes/에 다운로드합니다. 캐시를 지우려면 해당 하위 디렉토리를 삭제하세요. - 오류 처리: 모델 다운로드 실패 또는 지원되지 않는 파일 형식을 확인하세요. 출력 경로가 올바르고 쓰기 가능한지 확인하세요.
- 성능: GPU를 사용할 수 있는 경우
onnxruntime-gpu를 설치하여remove-background속도를 크게 높일 수 있습니다. CPU는 느리지만 작동합니다.