HyperFrames 미디어
컴포지션에 필요한 오디오 및 미디어 에셋(음성 해설(TTS), 배경 음악 + 음향 효과, 전사, 자막, 배경 제거)을 생성하고, 해당 데이터를 HTML에서 소비하고 애니메이션화합니다. 에셋을 컴포지션에 배치하는 방법은 hyperframes-core를 참조하세요.
오디오 엔진 — TTS · BGM · SFX를 위한 단일 소스
워크플로우는 오디오를 직접 구현하거나 타사 복사본을 사용하지 않습니다. 하나의 엔진 — scripts/audio.mjs — 이 중립적인 audio_request.json을 받아 audio_meta.json(및 assets/voice|bgm|sfx 아래의 에셋)을 작성합니다.
# <MEDIA_DIR> = 이 스킬의 디렉토리
node <MEDIA_DIR>/scripts/audio.mjs --request ./audio_request.json --hyperframes . --out ./audio_meta.json
세 가지 기능 모두 하나의 스위치 — HeyGen 크레덴셜의 존재 여부($HEYGEN_API_KEY / $HYPERFRAMES_API_KEY / ~/.heygen에서 확인, CLI 아님)에 따라 성능이 저하됩니다.
| 기능 | HeyGen 크레덴셜 있음 | 없음 |
|---|---|---|
| TTS | HeyGen Starfish REST (네이티브 단어 타임스탬프) | → ElevenLabs → Kokoro (transcribe 연결하여 단어 추출) |
| BGM | HeyGen 음악 검색 | Lyria → MusicGen 로컬 생성 (분리 실행) |
| SFX | HeyGen 음향 효과 검색 (min_score 0.4) | 번들된 21개 파일 라이브러리 (assets/sfx/) |
- 요청 (
audio_request.json):{ provider?, lang?, speed?, lines: [{ id, text, sfx?: [names] }], bgm: { mode?, query?, prompt? } }.id는 각 라인을 호출자의 모델(프레임 번호, 씬 ID 등)에 연결합니다.bgm.mode=retrieve | generate | none; 생략 시 자동(크레덴셜 있으면 검색, 없으면 생성). 명시적retrieve는 엄격합니다 — 분리된 생성을 시작하지 않고 건너뜁니다(wait-bgm단계가 없는 호출자용). - 출력 (
audio_meta.json, id 키 기준):{ tts_provider, voice_id, bgm, bgm_pending, …, voices: [{ id, path, duration_s, words }], sfx: [{ id, name, file, source, offset_s, duration_s, volume }], total_duration_s }. --only tts,bgm,sfx는 하위 집합을 실행하고 기존--out에 병합됩니다(예: TTS+BGM 먼저, SFX는 큐가 생성된 후).- BGM 생성은 분리되어 실행됩니다(
bgm_pending: true) — 조립 전에scripts/wait-bgm.mjs를 실행하세요. scripts/heygen-tts.mjs는 요청 파일 없이 HeyGen TTS만 필요한 경우를 위한 단일 호출 CLI입니다(하나의 텍스트 → wav + 단어).
전체 플래그 목록과 audio_meta.json 스키마는 scripts/audio.mjs의 헤더에 있습니다. 아래 참조는 각 기능의 제공자 세부 사항과 엣지 케이스를 다룹니다.
제공자 체인 (엔진 뒤의 세부 사항)
TTS — 사용 가능한 첫 번째 제공자가 사용됩니다(엔진 또는 npx hyperframes tts "..."):
| 순서 | 제공자 | 감지 조건 | 단어 타임스탬프 |
|---|---|---|---|
| 1 | HeyGen (Starfish) | $HEYGEN_API_KEY / hyperframes auth login | 예, 네이티브 — --words narration.words.json으로 캡처 |
| 2 | ElevenLabs | $ELEVENLABS_API_KEY 설정 | 아니오 — 이후 transcribe 연결 |
| 3 | Kokoro-82M (로컬, 54개 음성) | 항상 (키 불필요) | 아니오 — 이후 transcribe 연결 |
게시된
hyperframes ttsCLI는 종종 로컬 전용 빌드입니다(--help에 "Kokoro-82M"이라고 표시되고--provider/--words없음).$HEYGEN_API_KEY가 설정되어 있어도 자동으로 Kokoro로 폴백합니다. 이것이 엔진의 HeyGen 경로가 CLI가 아닌 자체 포함된scripts/heygen-tts.mjs(REST)인 이유입니다. CLI는 Kokoro 경로에만 사용됩니다.references/tts.md를 참조하세요.
BGM 및 SFX — 기본적으로 HeyGen 오디오 라이브러리(/v3/audio/sounds)에서 검색되며, HeyGen TTS와 동일한 크레덴셜을 사용하고, 위 스위치에서 크레덴셜이 없는 경우 폴백합니다.
| 에셋 | HeyGen type | 저장 위치 | 폴백 (크레덴셜 없음) |
|---|---|---|---|
| BGM | music | assets/bgm/track.mp3 (검색) · track.wav (생성) | Lyria / MusicGen 생성 |
| SFX | sound_effects (min_score 0.4) | assets/sfx/<슬러그>.mp3 | 번들된 21개 파일 라이브러리 (assets/sfx/* + manifest.json) |
references/bgm.md와 references/sfx.md를 참조하세요.
라우팅
| 작업 | 참조 문서 |
|---|---|
오디오 엔진 — 요청/메타 스키마, --only, 스위치 | scripts/audio.mjs (헤더 주석) |
npx hyperframes tts / heygen-tts.mjs — 제공자, 음성, 단어 | references/tts.md |
| 베트남어 TTS 스크립트 — 구두점, 음성학 (TTS 계층) | references/tts-vi.md |
| BGM — HeyGen 검색 + 로컬 Lyria / MusicGen 생성 | references/bgm.md |
| SFX — HeyGen 검색 (min_score 0.4) + 번들된 로컬 라이브러리 | references/sfx.md |
npx hyperframes transcribe — Whisper, 모델 규칙, 출력 형태 | references/transcribe.md |
npx hyperframes remove-background — 투명 컷아웃 | references/remove-background.md |
| TTS → 전사 → 자막 (녹음된 음성 해설 없음) | references/tts-to-captions.md |
| 자막 제작 — 스타일 감지, 레이아웃, 단어 그룹화, 종료 | references/captions/authoring.md |
| 대본 처리 — 입력 형식, 품질 게이트, 정리, API | references/captions/transcript-handling.md |
| 자막 모션 — 카라오케, 마커 효과, 오디오 반응형 | references/captions/motion.md |
| 모델 캐시, 시스템 종속성, 문제 해결 | references/requirements.md |
절대 규칙
- 하나의 엔진, 타사 복사본 없음.
scripts/audio.mjs(또는 일회성 HeyGen TTS의 경우heygen-tts.mjs)를 통해 오디오를 생성합니다. 워크플로우 내에서 TTS/BGM/SFX를 다시 구현하지 마십시오 —audio_request.json어댑터를 작성하고 엔진을 호출하세요. - "HeyGen 사용 가능" = 확인 가능한 크레덴셜, CLI가 아님. 전체 스위치는
heygenCredential()에 의해 결정됩니다. 게시된hyperframes tts는 Kokoro 전용일 수 있으며,hyperframes bgm/hyperframes sfx명령은 전혀 없습니다. - 음성 ID는 제공자별로 다릅니다.
am_michael은 Kokoro 전용입니다. HeyGen UUID는 Kokoro에서 작동하지 않습니다.--voice를 전달하는 경우, 사용자 환경이 변경될 때 제공자가 자동으로 변경되는 것을 방지하기 위해--provider도 함께 지정하세요. - 항상
transcribe에--model을 전달하세요. CLI 기본값small.en은 비영어 오디오를 자동으로 번역합니다.references/transcribe.md→ "언어 규칙"을 참조하세요. - HeyGen은 단어 타임스탬프를 반환하고, ElevenLabs / Kokoro는 반환하지 않습니다. 엔진은 후자 두 가지에 대해 자동으로
transcribe를 연결합니다. 독립 실행형으로 사용할 때는 HeyGen에--words를 전달하거나 오디오 파일에 대해transcribe를 실행하세요. - 자막은 평면 단어 배열 형식
{ id, text, start, end }을 사용합니다.references/transcribe.md→ "출력 형태"를 참조하세요. remove-background --background-output는 구멍을 뚫는 것이지, 인페인팅이 아닙니다. "사람이 없는 장면"의 경우 다른 도구가 필요합니다.references/remove-background.md→ "적절한 도구가 아닌 경우"를 참조하세요.- BGM/SFX는 기본적으로 HeyGen 검색을 사용하며, 크레덴셜 없는 경우 폴백은 생성(BGM) 또는 번들 라이브러리(SFX)입니다.
/audio/sounds는 텍스트 쿼리로 순위를 매깁니다 — 효과를 구체적으로 지정하세요(dramatic sound대신glass shatter). 일치하는 항목이 없으면 건너뛰며, 렌더를 차단하지 않습니다. SFX는 음성 + BGM 아래에서 볼륨 ~0.35로 배치됩니다.references/sfx.md/references/bgm.md를 참조하세요.