Communitygithub.com

whyiloveher2411/_biong_backend_FE

HyperFrames 컴포지션을 위한 오디오 및 미디어 에셋을 생성합니다. 단일 오디오 엔진(`scripts/audio.mjs`)으로 TTS(다중 제공자), 배경 음악, 음향 효과, 음성 전사, 자막, 배경 제거 등을 처리합니다.

_biong_backend_FE란 무엇인가요?

이 스킬은 HyperFrames 컴포지션(웹 기반 인터랙티브 멀티미디어 작품)에 필요한 모든 오디오 및 미디어 에셋을 생성하고 관리하는 단일 엔진을 제공합니다. `scripts/audio.mjs`라는 중앙 엔진은 `audio_request.json`을 입력받아 `audio_meta.json`과 실제 에셋 파일들을 출력하며, TTS(Text-to-Speech), 배경 음악(BGM), 음향 효과(SFX)의 세 가지 주요 기능을 제공합니다. 각 기능은 HeyGen API 키 존재 여부에 따라 제공자 체인이 자동으로 결정됩니다. HeyGen 크레덴셜이 있으면 HeyGen의 Starfish TTS(단어별 타임스탬프 포함), 음악 검색, 음향 효과 검색을 사용하고, 없으면 ElevenLabs/Kokoro 로컬 TTS, Lyria/MusicGen 로컬 BGM 생성, 번들된 SFX 라이브러리로 대체됩니다. 또한 Whisper 기반 음성 전사, 배경 제거, 자막 제작(카라오케, 마커 효과 포함) 기능을 제공하며, 모든 작업은 특정 워크플로우에 종속되지 않고 단일 엔진을 통해 일관되게 처리되어야 합니다. 이 스킬은 Claude Code, Cursor, Codex 등 AI 에이전트가 HyperFrames 관련 프로젝트에서 오디오/미디어 에셋을 생성할 때 사용됩니다.

지원 대상~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/whyiloveher2411/_biong_backend_FE/tree/HEAD/agent/skills/hyperframes-media

즐겨 사용하는 AI에게 물어보기

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

문서

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 크레덴셜 있음없음
TTSHeyGen Starfish REST (네이티브 단어 타임스탬프)→ ElevenLabs → Kokoro (transcribe 연결하여 단어 추출)
BGMHeyGen 음악 검색Lyria → MusicGen 로컬 생성 (분리 실행)
SFXHeyGen 음향 효과 검색 (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 "..."):

순서제공자감지 조건단어 타임스탬프
1HeyGen (Starfish)$HEYGEN_API_KEY / hyperframes auth login예, 네이티브 — --words narration.words.json으로 캡처
2ElevenLabs$ELEVENLABS_API_KEY 설정아니오 — 이후 transcribe 연결
3Kokoro-82M (로컬, 54개 음성)항상 (키 불필요)아니오 — 이후 transcribe 연결

게시된 hyperframes tts CLI는 종종 로컬 전용 빌드입니다(--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저장 위치폴백 (크레덴셜 없음)
BGMmusicassets/bgm/track.mp3 (검색) · track.wav (생성)Lyria / MusicGen 생성
SFXsound_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
대본 처리 — 입력 형식, 품질 게이트, 정리, APIreferences/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를 참조하세요.

관련 스킬