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는 동일한 코드의 일회성 CLI입니다(하나의 텍스트 → wav + 단어). 요청 파일 없이 HeyGen TTS만 필요할 때 사용합니다.
전체 플래그 목록과 audio_meta.json 스키마는 scripts/audio.mjs의 헤더에 있습니다. 아래 참조는 각 기능 뒤에 있는 제공자 세부 정보와 가장자리 사례를 다룹니다.
사전 점검 — 오디오 전에 로그인 상태 표시
음성 또는 BGM을 생성하기 전에 항상 실행하세요 — 전체 작업 흐름 또는 일회성 "BGM/음성 해설 생성" 요청 모두. HeyGen 자격 증명이 없다는 것이 로컬 엔진으로 자동 폴백되는 이유가 되어서는 안 됩니다: 먼저 로그인을 권장하고 사용자가 결정하도록 하세요. 공유 사전 점검을 실행하고 그 출력을 그대로 전달하세요 — 직접 "키 누락" 프롬프트를 만들지 말고, 저장소별 .env에 키를 쓰겠다고 제안하지 마세요:
npx hyperframes auth status
- 로그인됨 → 계정이 출력됩니다. 계속 진행하세요.
- 로그인되지 않음(
exit 1은 정상입니다 — "로그인되지 않음"은 실패가 아닌 정상 상태입니다) → 등록 우선 안내가 출력됩니다. 로그인을 권장하세요:npx hyperframes auth login은 브라우저 OAuth입니다 — 로그인하고 계정을 생성합니다(이 저장소의 CLI를 통해 항상 사용 가능). 기존 HeyGen API 키(app.heygen.com/settings/api 참조)를 사용하려면npx hyperframes auth login --api-key를 실행하세요 — 공유~/.heygen에 저장됩니다(저장소별.env없음). 출력에는 로컬 엔진 음성/BGM이 폴백될 것과 종속성이 누락된 경우pip힌트도 나열됩니다. 이 출력을 그대로 전달하세요 — 자신의 말로 바꿔 말하지 마세요. 그런 다음 중지하고 사용자가 선택할 때까지 기다리세요 — 로그인하거나 "go" / "local"이라고 말하여 오프라인으로 계속 진행합니다 — 무엇이든 생성하기 전에. 이것은 단순한 지나가는 메모가 아닌 실제 결정 지점입니다: 다른 질문에 포함시키지 말고, 스스로 이를 넘어 진행하지 마세요. (예외: 자율/비대화형 모드에서는 상태를 기록하고 오프라인으로 계속 진행합니다.) npx hyperframes auth status --json은 결정적 분기를 위해{ configured, recommended_action, offline_engines }를 반환합니다.- CLI를 실행할 수 없는 경우(PATH에 없고
npx가 가져올 수 없음) → 그래도 로그인을 권장하고(npx hyperframes auth login) 사용자의 선택을 위해 중지하세요 — "자격 증명 없음"을 로컬 생성을 위한 묵시적 허가로 취급하지 마세요.
자격 증명 해결, 전체 키 우선 순위 및 로컬 종속성 목록은 references/requirements.md에 있습니다.
제공자 체인 (엔진 뒤의 세부 정보)
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/<slug>.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 |
| 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는 텍스트 쿼리로 순위를 매깁니다 — 효과를 구체적으로 지정하세요(glass shatter,dramatic sound아님). 일치하지 않으면 건너뛰며, 렌더를 차단하지 않습니다. SFX는 음성 + BGM 아래에서 약 ~0.35 볼륨에 위치합니다.references/sfx.md/references/bgm.md참조. - 작업 흐름 캡션 HTML을 생성된 출력으로 취급하세요. 사전 설정 기반 비디오의 경우 재사용 가능한 스킨 소스는
.hyperframes/caption-skin.html에 있고 작업 흐름 스크립트는compositions/captions.html을 작성합니다. 스킨을 수정하기 위해 생성된compositions/captions.html을 편집하지 마세요. 작업 흐름의captions.mjs를 통해 다시 빌드하거나, 해당 작업 흐름의 명시적 재정의 메커니즘을 사용하세요.