HyperFrames 미디어 전처리
컴포지션을 위한 에셋을 생성하는 세 가지 CLI 명령: tts (음성), transcribe (타임스탬프), remove-background (투명 비디오). 각 명령은 최초 실행 시 모델을 다운로드하여 ~/.cache/hyperframes/에 캐시합니다. 출력 파일을 프로젝트에 넣은 다음 컴포지션 HTML에서 참조하세요. 오디오/비디오 요소 규칙은 hyperframes 스킬을 참조하십시오.
텍스트 음성 변환 (tts)
Kokoro-82M으로 로컬에서 음성 오디오를 생성합니다. API 키가 필요하지 않습니다.
npx hyperframes tts "Text here" --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 <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 avatar.mp4 -o transparent.webm # 기본값: VP9 알파 WebM
npx hyperframes remove-background avatar.mp4 -o transparent.mov # ProRes 4444 (편집용)
npx hyperframes remove-background portrait.jpg -o cutout.png # 단일 이미지 컷아웃
npx hyperframes remove-background avatar.mp4 -o transparent.webm --device cpu
npx hyperframes remove-background --info # 감지된 제공자 표시
u2net_human_seg (MIT)를 사용합니다. 첫 실행 시 약 168 MB의 가중치를 ~/.cache/hyperframes/background-removal/models/에 다운로드합니다.
출력 형식
| 형식 | 사용 시기 |
|---|---|
.webm (VP9 + 알파) | 기본값. 컴포지션이 <video>를 통해 직접 재생합니다. |
.mov (ProRes 4444) | DaVinci/Premiere/FCP에서 편집. 파일이 큼. |
.png | 단일 이미지 컷아웃 (정지 피사체, 배경 위에 레이어됨). |
Chrome은 VP9 알파를 기본적으로 디코딩하므로 .webm은 다른 음소거 자동 재생 비디오처럼 컴포지션에 연결됩니다. <video> 트랙 규칙은 hyperframes 스킬을 참조하세요.
TTS → 전사 → 캡션
미리 녹음된 음성 해설이 없는 경우, 생성하고 다시 전사하여 캡션용 단어 수준 타임스탬프를 얻으세요:
npx hyperframes tts script.txt --voice af_heart --output narration.wav
npx hyperframes transcribe narration.wav # → transcript.json
Whisper는 생성된 오디오에서 정확한 단어 경계를 추출하므로, 캡션 타이밍이 핸드 튜닝 없이 전달과 일치합니다.