HyperFrames 미디어
구성(composition)에 필요한 오디오 및 미디어 에셋 — 음성 해설(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는 엄격합니다 — 분리된 생성을 시작하는 대신 건너뜁니다(대기 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 + 워드).
전체 플래그 목록과 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는 홀 컷(hole-cut)이지 인페인트(inpainted)가 아닙니다. "사람 없는 장면"에는 다른 도구가 필요합니다.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참조. - 워크플로우 자막 HTML을 생성된 출력으로 취급하세요. 사전 설정 기반 비디오의 경우 재사용 가능한 스킨 소스는
.hyperframes/caption-skin.html에 있고 워크플로 스크립트는compositions/captions.html을 작성합니다. 스킨을 수정하기 위해 생성된compositions/captions.html을 편집하지 마세요. 워크플로우의captions.mjs를 통해 재구축하거나, 해당 워크플로우의 명시적 재정의 메커니즘을 사용하세요.