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 자격 증명 존재 여부($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 헤더에 있습니다. 아래 참조는 각 기능의 공급자 세부 정보와 엣지 케이스를 다룹니다.
사전 점검 — 오디오 생성 전 로그인 상태 표시
음성 또는 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를 통해 다시 빌드하거나, 워크플로의 명시적 재정의 메커니즘을 사용하세요(있는 경우).