Communitygithub.com

HyperFrames Media – 오디오 및 미디어 에셋 생성 도구

HyperFrames 컴포지션을 위한 오디오 및 미디어 에셋(음성 해설/TTS, 배경 음악, 음향 효과, 자막, 배경 제거)을 생성합니다. 하나의 공유 오디오 엔진(`scripts/audio.mjs`)을 통해 다중 제공업체 TTS(HeyGen/ElevenLabs/Kokoro 로컬)를 지원하며, 배경 음악 및 음향 효과는 기본적으로 HeyGen 오디오 라이브러리 검색을 사용하고 자격 증명이 없을 경우 로컬 Lyria/MusicGen BGM 생성 및 내장 SFX 라이브러리로 대체됩니다. Whisper 전사, 배경 제거, 자막 작성 기능도 포함합니다.

HyperFrames Media – 오디오 및 미디어 에셋 생성 도구란 무엇인가요?

HyperFrames Media는 오디오 및 미디어 에셋 생성을 위한 통합 도구로, AI 에이전트나 개발자가 대화형 애플리케이션에서 고품질의 오디오/비디오 자료를 손쉽게 제작할 수 있도록 설계되었습니다. 이 도구는 단일 오디오 엔진(`scripts/audio.mjs`)을 중심으로 다중 제공업체 TTS(HeyGen, ElevenLabs, Kokoro 로컬), 배경 음악(BGM) 및 음향 효과(SFX) 생성, Whisper 기반 전사, 배경 제거, 그리고 정교한 자막(캡션/가라오케 등) 작성을 지원합니다. 가장 큰 장점은 자격 증명 유무에 따라 지능적으로 제공업체를 전환한다는 점입니다. 예를 들어, HeyGen API 키가 있으면 고품질의 Starfish TTS와 풍부한 오디오 라이브러리를 활용할 수 있고, 키가 없어도 ElevenLabs나 Kokoro 같은 로컬 엔진으로 부드럽게 대체되어 중단 없는 개발을 보장합니다. BGM은 기본적으로 HeyGen 라이브러리에서 검색되며, 자격 증명이 없으면 Lyria 또는 MusicGen을 통해 로컬에서 생성됩니다. SFX는 HeyGen 검색을 시도하고, 실패하면 내장된 21개의 사운드 라이브러리로 대체됩니다. 이 도구는 Claude Code, Cursor, Codex 등 다양한 AI 에이전트 환경에서 사용할 수 있으며, 명확한 JSON 기반 요청/응답 스키마와 함께 제공되어 다른 워크플로우나 컴포지션 시스템과 쉽게 통합됩니다. 특히, 오디오 생성 전에 사용자 인증 상태를 확인하고 대화형으로 진행 여부를 결정하도록 설계되어, 사용자가 항상 자신의 자격 증명 상태를 인지하고 선택할 수 있도록 돕습니다. 요약하자면, HyperFrames Media는 하나의 강력한 엔진 아래 오디오 생성, 전사, 자막, 배경 제거를 통합하여 개발자의 생산성을 극대화하고, 다양한 제공업체 간의 전환을 자동화하여 신뢰성과 유연성을 동시에 제공합니다.

지원 대상~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/1345AbhishekKumar/starter-supabase/tree/HEAD/.agents/skills/hyperframes-media

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

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

문서

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 자격 증명은 $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는 동일한 코드의 단일 실행 CLI입니다(하나의 텍스트 → wav + 단어). 요청 파일 없이 HeyGen TTS만 필요할 때 사용합니다.

전체 플래그 목록과 audio_meta.json 스키마는 scripts/audio.mjs의 헤더에 있습니다. 아래 참조는 각 기능의 제공업체 세부 정보와 엣지 케이스를 다룹니다.

사전 점검 — 오디오 생성 전 로그인 상태 확인

음성이나 BGM을 생성하기 전에 항상 먼저 실행하세요 — 전체 워크플로우 내에서든, 일회성 "BGM/음성 해설 생성" 요청에서든. HeyGen 자격 증명이 없다고 해서 자동으로 로컬 엔진으로 대체되어서는 안 됩니다: 먼저 로그인을 권장하고 사용자가 결정하도록 하세요. 공유 사전 점검을 실행하고 그 출력을 그대로 전달하세요 — 자체적으로 "키 누락" 프롬프트를 만들지 말고, per-repo .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에 저장됩니다(per-repo .env 없음). 출력에는 음성/BGM이 대체될 로컬 엔진 목록과 종속성이 누락된 경우 pip 힌트도 포함됩니다. 이 출력을 그대로 전달하세요 — 자신의 말로 바꾸지 마세요. 그런 다음 멈추고 사용자가 선택(로그인, 또는 "계속" / "로컬"로 오프라인 계속)할 때까지 기다리세요 — 무엇이든 생성하기 전에. 이것은 단순한 참고 사항이 아니라 실제 결정 지점입니다: 다른 질문에 포함시키지 말고, 스스로 진행하지 마세요. (예외: 자율/비대화형 모드에서는 상태를 기록하고 오프라인으로 계속합니다.)
  • npx hyperframes auth status --json은 결정적 분기를 위해 { configured, recommended_action, offline_engines }를 반환합니다.
  • CLI를 실행할 수 없는 경우(PATH에 없고 npx가 가져올 수 없음) → 여전히 로그인을 권장(npx hyperframes auth login)하고 사용자의 선택을 위해 중지하세요 — "자격 증명 없음"을 로컬 생성을 위한 묵시적 허가로 취급하지 마세요.

자격 증명 해결, 전체 키 우선순위 및 로컬 종속성 목록은 references/requirements.md에 있습니다.

제공업체 체인 (엔진 뒤의 세부 사항)

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/<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
대본 처리 — 입력 형식, 품질 게이트, 정리, 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는 텍스트 쿼리로 순위를 매깁니다 — 효과를 구체적으로 지정하세요(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를 통해 다시 빌드하거나, 해당 워크플로우의 명시적 재정의 메커니즘(있는 경우)을 사용하세요.

Individual skills in this repo

This repo contains 13 individual skills — each has its own dedicated page.

1345AbhishekKumar/starter-supabase

Add captions to a talking-head video. ONE catalog (CATALOG.md) of 32 visual identities behind two engines: column-flow (captions composited INTO the scene — matte occlusion + mix-blend; cream/ink/editorial/keynote/documentary/loud/neon/glitch/chrome/velocity) and themed constitutions (anchor/ordnance/terminal/neonsign/stardust/stomp/scoreboard/transit/vhs/arcade/dossier/laser/thunder/hologram/biolume/aurora/spectrum/papercut/popup/chalkboard/graffiti/brush/inkwater/ransom/lastpage/nightcity — e.g. a glyph-decode climax, a neon sign WRITTEN stroke by stroke, or the quiet `anchor` rail default). Route by identity, never by mode. Trigger on "captions/subtitles", "embed/cinematic captions", "VFX captions", "炸/特效/酷炫字幕", a named identity, or top-tier motion-graphics asks. Embedding every word is wrong for most talking-head content — `anchor` is the verbatim default. Pipeline: transcription → hyperframes remove-background matting → HTML render → ffmpeg overlay. Requires hyperframes and a single-subject clip.

1345AbhishekKumar/starter-supabase

The fallback workflow for authoring custom HyperFrames video compositions at any length or format — longer or multi-scene pieces, brand / sizzle reels, montages, title cards, static loops, and freeform compositions. Input- and length-agnostic. If a specialized workflow clearly fits the input — a marketed product, a website, a topic explainer, a GitHub PR, existing footage, a short motion graphic, or a Remotion port — prefer it (see /hyperframes); use this only as the general fallback when none fit.

1345AbhishekKumar/starter-supabase

All animation knowledge for HyperFrames — atomic motion rules, multi-phase scene blueprints, scene transitions, broader motion-design techniques, AND the seven runtime adapters (GSAP default, plus Lottie, Three.js, Anime.js, CSS keyframes, Web Animations API, TypeGPU). Use for any motion or animation task: pick 2-4 rules and compose, or load a blueprint, or look up runtime-specific API (e.g. GSAP eases / Lottie player / Three.js mixer). HyperFrames-native: single paused timeline, seek-safe, deterministic.

1345AbhishekKumar/starter-supabase

HyperFrames CLI dev loop. Use when running npx hyperframes init, add, catalog, capture, lint, validate, inspect, layout, snapshot, preview, play, render, publish, lambda, doctor, browser, info, upgrade, skills, compositions, docs, benchmark, telemetry, transcribe, tts, or remove-background, or when troubleshooting the HyperFrames build/render environment. Entry point for AWS Lambda cloud rendering (`hyperframes lambda deploy / render / progress / destroy / policies`).

1345AbhishekKumar/starter-supabase

The HyperFrames composition contract — build one renderable project. Use for composition structure, the `data-*` timing attributes, `class="clip"`, tracks, sub-compositions, variables, framework-owned media playback, deterministic-render rules, and validation. Read before writing composition HTML.

1345AbhishekKumar/starter-supabase

Non-animation creative direction for HyperFrames videos. Use for design spec (frame.md / design.md) handling, palettes, typography, narration, beat planning, audio-reactive visuals, composition patterns, and brand / style decisions. For atomic motion patterns and scene blueprints, use `hyperframes-animation`.

1345AbhishekKumar/starter-supabase

Install and wire registry blocks and components into HyperFrames compositions. Use when running hyperframes add, installing a block or component, wiring an installed item into index.html, or working with hyperframes.json. Covers the add command, install locations, block sub-composition wiring, component snippet merging, registry discovery, and authoring a new block or component to contribute upstream (idea → scaffold → validate → PR).

1345AbhishekKumar/starter-supabase

Use when the user wants a short, design-led motion graphic where motion is the message: kinetic typography, stat or number count-up, chart/data-viz hit, logo sting, brand lockup, lower-third, callout, social overlay, animated headline/tweet/news item, motion poster, or quick captured-page highlight. Usually under 10s and up to ~30s, with no narration arc, voice-over, or live-action subject. Can render to MP4 or transparent overlay. Not for longer, multi-scene, narrated, or brand-reel pieces (use general-video), narrated website videos (website-to-video), topic explainers (faceless-explainer), product promos (product-launch-video), PR videos (pr-to-video), or captions on existing footage (embedded-captions). When unsure whether it's a quick motion-first piece or a longer / narrated treatment, see /hyperframes.

1345AbhishekKumar/starter-supabase

Use when the user has a music track (an audio file, or a video to pull audio from) and wants a beat-synced HyperFrames video, calm to hard-hitting. The music drives everything: one analyzer reads it once, the orchestrator lays out the frames and fills a per-frame plan, and one sub-agent builds each frame. Typography and templates are the floor — a complete video needs zero assets — but any images or videos the user supplies are cut into the frames on the same beat grid (beat-cut / ken-burns). The genre (lyric video, slideshow, kinetic promo) falls out of the per-frame choices; the pipeline never branches on it.

1345AbhishekKumar/starter-supabase

turn a product or marketing URL, pasted script, or brief into a product launch video, including SaaS promos, feature reveals, app launches, company promos, and product marketing videos. Use this skill when the user wants to market, launch, promote, or reveal a product. Do not use it for general non-launch website tours, non-product topic explainers, GitHub pull requests, captioning existing footage, or short unnarrated motion graphics. If the intent is unclear, route through /hyperframes first. This is the new shot-sequence architecture: every visual frame is authored as a time-coded shot sequence picked from a menu of golden blueprints, so frames develop over their full duration instead of freezing after entrance.

1345AbhishekKumar/starter-supabase

turn a GitHub pull request (a PR URL like github.com/<owner>/<repo>/pull/<N>, an <owner>/<repo>#<N> ref, or 'this PR' in a checked-out repo) into a code-change explainer video, up to ~3 min (sweet spot 30-90s) — changelog, feature reveal, fix, or refactor walkthrough, rendered from the diff / commits / files. The input is a CODE CHANGE read via the gh CLI; there is no website capture. Use this skill for a GitHub PR. Do not use it for a product launch/promo (use /product-launch-video), a tour of a real website (use /website-to-video), a topic explainer with no PR (use /faceless-explainer), captions on existing footage (use /embedded-captions), or a short unnarrated motion graphic (use /motion-graphics). If the intent is unclear, route through /hyperframes first.

1345AbhishekKumar/starter-supabase

Port an existing Remotion (React) composition to HyperFrames HTML. Use ONLY when the user explicitly asks to port/convert/migrate/translate a Remotion source. Do NOT use: (a) authoring a new HyperFrames composition; (b) Remotion mentioned in passing; (c) Remotion code shared as reference only; (d) "same video as my Remotion one" without explicit migrate request — treat as fresh build. Doubt → `/general-video`. One-way, Remotion-only: no reverse export (HyperFrames→Remotion or any framework), no non-Remotion source (After Effects, Framer Motion, plain React/CSS) → out of scope, re-create via `/general-video`. Flags unsupported patterns (useState, useEffect, async calculateMetadata, third-party React libs, `@remotion/lambda`) and recommends runtime interop over lossy translation. Unsure whether to port vs. build fresh, or only a passing Remotion mention? → /hyperframes.

1345AbhishekKumar/starter-supabase

Capture a general website/URL and turn it into a HyperFrames video (site tour, showcase, or social clip from the site's own visuals). Uses headless Chrome screenshots + brand assets. Use when intent is general — portfolio/blog/landing-page showcase or social clip from the site. NOT for: product/SaaS launch or promo (→ /product-launch-video, even from a URL); topic explainer with no site (→ /faceless-explainer); GitHub PR (→ /pr-to-video); adding captions to existing video (→ /embedded-captions); short unnarrated page-highlight motion graphic (→ /motion-graphics). Unclear launch-vs-general-site? Ask one question or start at /hyperframes.

관련 스킬