HyperFrames Media
컴포지션에 필요한 오디오 및 미디어 에셋(음성 해설(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 자격 증명 존재 여부(CLI가 아닌 $HEYGEN_API_KEY / $HYPERFRAMES_API_KEY / ~/.heygen 에서 확인)에 따라 저하됩니다:
| 기능 | 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는 엄격합니다 — 분리된 생성을 시작하지 않고 건너뜁니다(대기 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입니다.
전체 플래그 목록과 audio_meta.json 스키마는 scripts/audio.mjs의 헤더에 있습니다. 아래 참조는 각 기능의 공급자 세부 정보와 가장자리 사례를 다룹니다.
사전 확인 — 오디오 생성 전 로그인 상태 표시
전체 워크플로우 내에서 또는 일회성 "BGM/음성 해설 생성" 요청에서 음성 또는 BGM을 생성하기 전에 항상 이 작업을 실행하세요. HeyGen 자격 증명이 없다고 해서 자동으로 로컬 엔진으로 폴백(fallback)되어서는 안 됩니다. 먼저 로그인을 권장하고 사용자가 결정하도록 하세요. 공유 사전 확인을 실행하고 출력을 그대로 전달하세요 — 자체 "키 누락" 프롬프트를 즉흥적으로 만들지 말고, 리포지토리별 .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이 폴백(fallback)될 항목과 종속성이 누락된 경우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로 폴백(fallback)됩니다. 이것이 엔진의 HeyGen 경로가 CLI가 아닌 자체 포함된scripts/heygen-tts.mjs(REST)인 이유입니다. CLI는 Kokoro 경로에만 사용됩니다.references/tts.md를 참조하세요.
BGM 및 SFX — 기본적으로 HeyGen 오디오 라이브러리(/v3/audio/sounds)에서 검색되며, HeyGen TTS와 동일한 자격 증명을 사용하고, 위 스위치의 자격 증명 없는 폴백(fallback)을 사용합니다:
| 에셋 | 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도 고정하세요. - 항상
--model을transcribe에 전달하세요. 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 검색을 사용합니다. 자격 증명 없는 폴백(fallback)은 생성(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를 통해 다시 빌드하거나, 해당 워크플로우의 명시적 재정의 메커니즘을 사용하세요.