Communitygithub.com

HyperFrames 미디어 전처리

HyperFrames 컴포지션을 위한 자산 전처리 — 텍스트 음성 변환(TTS, Kokoro), 오디오/비디오 자막 생성(Whisper), 배경 제거(u2net)를 지원합니다. 음성 해설 생성, 자막을 위한 음성 변환, 투명 오버레이용 배경 제거, TTS 음성 또는 Whisper 모델 선택, 또는 이들을 연계(TTS → 자막 생성 → 캡션)할 때 사용하세요. 각 명령어는 첫 실행 시 자체 모델을 다운로드합니다.

HyperFrames 미디어 전처리란 무엇인가요?

이 스킬은 HyperFrames 컴포지션을 위한 세 가지 CLI 명령어(tts, transcribe, remove-background)를 제공하는 미디어 전처리 도구입니다. 'tts' 명령어는 Kokoro-82M 모델을 사용하여 API 키 없이 로컬에서 음성 오디오를 생성하며, 54개의 다양한 음성(영어, 스페인어, 프랑스어, 일본어 등)을 지원합니다. 'transcribe' 명령어는 OpenAI Whisper 모델을 사용하여 오디오/비디오 파일에서 단어 수준 타임스탬프가 포함된 transcript.json을 생성하며, 다양한 모델 크기(tiny부터 large-v3까지)를 지원합니다. 'remove-background' 명령어는 u2net_human_seg 모델을 사용하여 비디오 또는 이미지에서 배경을 제거하고 투명 오버레이(VP9 알파 WebM 또는 ProRes 4444)를 생성합니다. 특히 '--background-output' 옵션을 통해 컷아웃과 배경판(plate)을 분리하여 레이어 간 텍스트나 그래픽을 배치할 수 있는 고급 합성 패턴을 지원합니다. 모든 명령어는 첫 실행 시 모델을 다운로드하여 ~/.cache/hyperframes/에 캐시하며, Claude Code, Cursor, Codex 등 다양한 AI 에이전트 플랫폼에서 사용할 수 있습니다.

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

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

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

미리보기

스킬 README에서

문서

HyperFrames 미디어 전처리은(는) 무엇을 하나요?

컴포지션을 위한 자산을 생성하는 세 가지 CLI 명령어: tts(음성), transcribe(타임스탬프), remove-background(투명 비디오). 각 명령어는 첫 실행 시 모델을 다운로드하고 ~/.cache/hyperframes/에 캐시합니다. 출력 파일을 프로젝트에 넣은 다음 컴포지션 HTML에서 참조하세요. 오디오/비디오 요소 규칙은 hyperframes 스킬을 참조하세요.

텍스트 음성 변환 (tts)

Kokoro-82M으로 로컬에서 음성 오디오를 생성합니다. API 키가 필요 없습니다.

npx hyperframes tts "텍스트 입력" --voice af_nova --output narration.wav
npx hyperframes tts script.txt --voice bf_emma --output narration.wav
npx hyperframes tts --list                       # 전체 54개 음성 목록

음성 선택

콘텐츠에 맞게 음성을 선택하세요. 기본값은 af_heart입니다.

콘텐츠 유형음성이유
제품 데모af_heart/af_nova따뜻하고 전문적인 느낌
튜토리얼 / 사용법am_adam/bf_emma중립적이고 따라하기 쉬움
마케팅 / 프로모션af_sky/am_michael활기차거나 권위적인 느낌
문서화bf_emma/bm_george명확한 영국식 영어, 공식적
캐주얼 / 소셜af_heart/af_sky친근하고 자연스러운 느낌

다국어 지원

음성 ID의 첫 글자에 언어가 인코딩되어 있습니다: a=미국 영어, b=영국 영어, e=스페인어, f=프랑스어, h=힌디어, i=이탈리아어, j=일본어, p=브라질 포르투갈어, z=중국어(표준). CLI는 접두사에서 음소 변환기 로케일을 자동 감지합니다 — 음성이 텍스트와 일치하면 --lang이 필요 없습니다.

npx hyperframes tts "La reunión empieza a las nueve" --voice ef_dora --output es.wav
npx hyperframes tts "今日はいい天気ですね" --voice jf_alpha --output ja.wav

자동 감지를 재정의하려는 경우(양식화된 억양)에만 --lang을 사용하세요. 유효한 코드: en-us, en-gb, es, fr-fr, hi, it, pt-br, ja, zh. 영어 이외의 언어 음소 변환은 시스템에 espeak-ng가 설치되어 있어야 합니다(brew install espeak-ng / apt-get install espeak-ng).

속도

  • 0.7-0.8 — 튜토리얼, 복잡한 콘텐츠, 접근성
  • 1.0 — 자연스러운 속도 (기본값)
  • 1.1-1.2 — 인트로, 전환, 경쾌한 콘텐츠
  • 1.5+ — 거의 적절하지 않음; 신중히 테스트

긴 스크립트

몇 문단 이상인 경우 .txt 파일에 작성하고 경로를 전달하세요. 약 5분 이상의 음성 입력은 세그먼트로 분할하는 것이 좋습니다.

요구 사항

Python 3.8+ 및 kokoro-onnx와 soundfile (pip install kokoro-onnx soundfile). 모델은 첫 사용 시 다운로드됩니다(~311 MB + ~27 MB 음성, ~/.cache/hyperframes/tts/에 캐시).

자막 생성 (transcribe)

단어 수준 타임스탬프가 포함된 정규화된 transcript.json을 생성합니다.

npx hyperframes transcribe audio.mp3
npx hyperframes transcribe video.mp4 --model small --language es
npx hyperframes transcribe subtitles.srt          # 기존 자막 가져오기
npx hyperframes transcribe subtitles.vtt
npx hyperframes transcribe openai-response.json

언어 규칙 (필수)

사용자가 오디오가 영어라고 명시적으로 밝히지 않는 한 절대 .en 모델을 사용하지 마십시오. .en 모델(small.en, medium.en)은 영어 이외의 오디오를 변환(transcribe)하는 대신 영어로 번역(translate)합니다. 이는 원래 언어를 조용히 파괴합니다.

  1. 언어를 알고 있고 영어가 아닌 경우 → --model small --language <코드> (.en 접미사 없음)
  2. 언어를 알고 있고 영어인 경우 → --model small.en
  3. 언어를 모르는 경우 → --model small (.en 없음, --language 없음) — whisper가 자동 감지

기본 모델은 small이지 small.en이 아닙니다.

모델 크기

모델크기속도사용 시기
tiny75 MB가장 빠름빠른 미리보기, 파이프라인 테스트
base142 MB빠름짧은 클립, 깨끗한 오디오
small466 MB보통기본값 — 대부분의 콘텐츠
medium1.5 GB느림중요한 콘텐츠, 잡음이 있는 오디오, 음악
large-v33.1 GB가장 느림프로덕션 품질

보컬이 있는 음악: 최소 medium부터 시작; 제작된 트랙은 수동 SRT/VTT 가져오기가 필요한 경우가 많습니다. 모든 자막 생성 후 필수인 캡션 품질 확인, 클리닝 JS, 재시도 규칙, OpenAI/Groq API 가져오기 경로는 hyperframes/references/transcript-guide.md를 참조하세요.

출력 형태

컴포지션은 단어 객체의 플랫 배열을 사용합니다. id 필드(w0, w1, ...)는 캡션 재정의에서 안정적인 참조를 위해 정규화 중에 추가됩니다. 이전 버전과의 호환성을 위해 선택 사항입니다.

[
  { "id": "w0", "text": "안녕하세요", "start": 0.0, "end": 0.5 },
  { "id": "w1", "text": "세계.", "start": 0.6, "end": 1.2 }
]

배경 제거 (remove-background)

비디오 또는 이미지에서 배경을 제거하여 피사체(일반적으로 사람 — 아바타, 발표자, 진행자)가 컴포지션에서 투명 오버레이로 표시되도록 합니다.

npx hyperframes remove-background subject.mp4 -o transparent.webm  # 기본값: VP9 알파 WebM
npx hyperframes remove-background subject.mp4 -o transparent.mov   # ProRes 4444 (편집용)
npx hyperframes remove-background portrait.jpg -o cutout.png       # 단일 이미지 컷아웃
npx hyperframes remove-background subject.mp4 -o subject.webm \
  --background-output plate.webm                                   # 한 번에 두 레이어
npx hyperframes remove-background subject.mp4 -o transparent.webm --device cpu
npx hyperframes remove-background --info                           # 감지된 공급자

u2net_human_seg(MIT)를 사용합니다. 첫 실행 시 약 168MB의 가중치를 ~/.cache/hyperframes/background-removal/models/에 다운로드합니다.

레이어 분리 (--background-output)

--background-output(또는 -b)를 전달하면 컷아웃과 함께 두 번째 투명 비디오를 생성합니다: 동일한 소스 RGB, 알파는 mask 대신 255 − mask입니다. 컷아웃은 배경이 투명한 피사체이고, 플레이트는 피사체가 있던 자리가 투명 구멍인 원래 배경입니다.

파일알파는...용도
-o subject.webm마스크 — 피사체 불투명, 배경 투명전경 레이어, 위에 배치
--background-output plate.webm역마스크 — 배경 불투명, 피사체 영역 투명하단 레이어; 이 레이어와 피사체 사이에 텍스트나 그래픽 배치

두 출력 파일은 동일한 --quality 프리셋을 공유하며 단일 추론 패스로 실행됩니다 — 인코딩 비용은 약 두 배, 분할 비용은 동일합니다. 비디오 입력 및 .webm/.mov 출력에만 유효합니다.

구멍이 뚫린 플레이트, 인페인트된 깨끗한 플레이트가 아닙니다. plate.webm의 피사체 영역은 완전히 투명합니다 — 그 아래에 불투명한 무언가를 합성하여 구멍을 채우세요. --background-output가 올바른 도구인지 판단하는 단일 테스트: 피사체가 있던 자리, 피사체의 실루엣을 통해 어떤 것이 보일 수 있습니까?

사용 사례올바른 도구
컷아웃과 플레이트 사이의 텍스트/그래픽 (이 명령어가 존재하는 이유)구멍 뚫기 (--background-output)
피사체를 관련 없는 장면 위에 배치subject.webm만 사용; 플레이트 무시
다른 콘텐츠 없이 사람 없이 방만 단독으로 표시깨끗한 플레이트 — 인페인터(LaMa, ProPainter, E2FGVI) 필요. 이 명령어는 해당되지 않음.
피사체를 다른 피사체로 교체깨끗한 플레이트 — 위와 동일

사용자가 "사람이 제거된 방"을 요청하고 그것을 단독으로 표시하려는 경우 --background-output을 사용하지 마십시오. 인페인터가 필요하다고 알려주세요.

일반적인 계층 컴포지션 (표준 구멍 뚫기 사용 사례):

<!-- z=1 역알파 플레이트가 피사체 영역을 제외한 모든 것을 채웁니다 -->
<video
  src="plate.webm"
  data-start="0"
  data-duration="6"
  data-track-index="0"
  muted
  playsinline
></video>

<!-- z=2 두 레이어 사이에 그래픽/텍스트가 있습니다 -->
<h1 id="headline" style="z-index:2; ...">MAKE IT IN HYPERFRAMES</h1>

<!-- z=3 컷아웃이 헤드라인 위에 피사체를 다시 띄웁니다 -->
<div class="cutout-wrap" style="position:absolute;inset:0;z-index:3">
  <video
    src="subject.webm"
    data-start="0"
    data-duration="6"
    data-track-index="1"
    muted
    playsinline
  ></video>
</div>

이것은 아래의 텍스트-뒤-피사체 패턴과 기능적으로 동일하지만, 프로젝트에 원본 presenter.mp4가 필요하지 않습니다 — 플레이트가 그것을 대체합니다. 두 개의 투명 레이어만 제공하고 사용자가 그 사이에 임의의 콘텐츠를 넣을 수 있도록 하려는 경우에 유용합니다.

출력 형식

형식사용 시기
.webm (VP9 + 알파)기본값. 컴포지션에서 <video>를 통해 직접 재생됩니다.
.mov (ProRes 4444)DaVinci/Premiere/FCP에서 편집. 큰 파일.
.png단일 이미지 컷아웃 (정지 피사체, 배경 위에 레이어).

Chrome은 VP9 알파를 기본적으로 디코딩하므로, .webm은 다른 음소거 자동 재생 비디오처럼 컴포지션에 연결됩니다. <video> 트랙 규칙은 hyperframes 스킬을 참조하세요.

품질 프리셋

--quality fast|balanced|best는 VP9 인코더의 CRF만 제어합니다 — 분할 품질은 고정됩니다.

프리셋CRF사용 시기
fast30반복 작업, 더 작은 파일, 느슨한 색상 일치
balanced18기본값. 대부분의 용도에서 시각적으로 동일
best12마스터 / 최종 전달. 가장 큰 파일, 가장 정확한 일치

합성 패턴 — 올바른 것 선택

컷아웃 webm은 소스 mp4의 RGB를 재인코딩한 복사본입니다. 이 선택은 그 뒤에 무엇을 넣느냐에 따라 결과가 달라집니다:

패턴컷아웃 뒤에 있는 것결과
다른 장면 위의 컷아웃 (가장 일반적)정적 이미지, 그라데이션 또는 관련 없는 비디오훌륭합니다. 컷아웃의 RGB는 피사체의 유일한 소스입니다 — 이중화나 가장자리 헤일로가 없습니다. 이것이 remove-background가 만들어진 목적입니다.
자체 소스 mp4 위의 컷아웃 (텍스트-뒤-피사체)컷아웃이 생성된 동일한 mp4동일한 사람에 대한 두 개의 RGB 소스. 기본 --quality balanced(crf 18)에서는 이중화가 거의 보이지 않습니다. --quality fast(crf 30)에서는 약한 색상 변화/가장자리 헤일로가 보입니다. 마스터 파일에는 --quality best(crf 12)를 사용하세요.
동일한 사람의 다른 테이크 위의 컷아웃동일한 피사체의 다른 영상두 명의 다른 사람이 겹쳐 있는 것처럼 보입니다. 이렇게 하지 마세요.

텍스트-뒤-피사체 (발표자 뒤의 헤드라인):

<video
  src="presenter.mp4"
  id="bg"
  data-start="0"
  data-duration="6"
  data-track-index="0"
  muted
  playsinline
></video>
<h1 id="headline" style="z-index:2; ...">MAKE IT IN HYPERFRAMES</h1>
<div class="cutout-wrap" style="position:absolute;inset:0;z-index:3;opacity:0">
  <video
    src="presenter.webm"
    data-start="0"
    data-duration="6"
    data-track-index="1"
    muted
    playsinline
  ></video>
</div>

두 가지 핵심 규칙:

  1. 컷아웃 비디오를 시간 기반이 아닌 <div>로 감싸고 래퍼의 불투명도를 애니메이션 처리하고, 비디오 요소 자체는 애니메이션 처리하지 마십시오. 프레임워크는 활성 클립( data-start/data-duration이 있는 요소)에 강제로 opacity:1을 적용하므로, 비디오의 불투명도를 직접 애니메이션 처리하면 조용히 무시됩니다. 래퍼에는 data-* 속성이 없으므로 CSS/GSAP으로 제어됩니다.
  2. 두 비디오 모두 data-start="0" 및 data-media-start="0"을 사용하여 프레임워크가 t=0부터 동기화하여 디코딩하도록 합니다. 컷아웃을 늦게 마운트(data-start=3.3)하면 seek + 워밍업이 발생하여 기본 mp4와 한 프레임 차이가 납니다 — 컷에서 한 프레임의 정렬 불량으로 나타납니다.

그런 다음 GSAP으로 컷에서 래퍼 불투명도를 전환합니다: tl.set(cutoutWrap, { opacity: 1 }, 3.3).

TTS → 자막 생성 → 캡션

사전 녹음된 음성 해설이 없는 경우, 하나를 생성하고 다시 변환하여 캡션용 단어 수준 타임스탬프를 얻습니다:

npx hyperframes tts script.txt --voice af_heart --output narration.wav
npx hyperframes transcribe narration.wav   # → transcript.json

# 그런 다음 캡션을 transcript.json에 추가합니다 (예: hyperframes 마크업으로).

Individual skills in this repo

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

delorenj/skills

Plan and generate terminal ASCII animations/screensaver-style output (FPS, refresh rules, loop policy, low-flicker guidance), with a static poster frame and an optional local demo script.

delorenj/skills

ASCII video: convert video/audio to colored ASCII MP4/GIF.

delorenj/skills

Plan, build and quality-check a premium short commercial for a real business (roofing, property, ecommerce, B2B software) using AI-generated footage, code-built motion (HTML/GSAP), selective Three.js and an independent-critic "Gauntlet" loop. Use when asked to make a launch-style / SaaS-style video, business ad, explainer, sample reel or pitch video, or to review and improve one. Encodes motion principles distilled from 28 professional launch films, a quality bar, audio rules and a business-offer playbook.

delorenj/skills

CSS animation adapter patterns for HyperFrames. Use when authoring CSS keyframes, animation-delay based timing, animation-fill-mode, animation-play-state, or CSS-only motion that HyperFrames must seek deterministically during preview and rendering.

delorenj/skills

Generate professional voiceovers using ElevenLabs AI. Use when the user needs to create voiceovers for videos, audio narration, or text-to-speech content. Supports multiple voices with character presets (narrator, salesperson, expert) for natural delivery. Includes single scene regeneration for fine-tuning.

delorenj/skills

HyperFrames CLI dev loop — `npx hyperframes` for scaffolding (init), validation (lint, inspect), preview, render, and environment troubleshooting (doctor, browser, info, upgrade). Use when running any of these commands or troubleshooting the HyperFrames build/render environment. For asset preprocessing commands (`tts`, `transcribe`, `remove-background`), invoke the `hyperframes-media` skill instead.

delorenj/skills

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, and registry discovery.

delorenj/skills

Create video compositions, animations, title cards, overlays, captions, voiceovers, audio-reactive visuals, and scene transitions in HyperFrames HTML. Use when asked to build any HTML-based video content, add captions or subtitles synced to audio, generate text-to-speech narration, create audio-reactive animation (beat sync, glow, pulse driven by music), add animated text highlighting (marker sweeps, hand-drawn circles, burst lines, scribble, sketchout), or add transitions between scenes (crossfades, wipes, reveals, shader transitions). Covers composition authoring, timing, media, and the full video production workflow. For dev-loop CLI commands (init, lint, inspect, preview, render) see the hyperframes-cli skill; for asset preprocessing commands (tts, transcribe, remove-background) see the hyperframes-media skill.

delorenj/skills

Manim CE animations: 3Blue1Brown math/algo videos.

delorenj/skills

Join a Google Meet or Zoom call as a video meeting agent via PikaStreaming. Trigger: user drops a Google Meet or Zoom link, or asks to join a meeting.

delorenj/skills

Translate an existing Remotion (React-based) video composition into a HyperFrames HTML composition. Use ONLY when the user explicitly asks to port, convert, migrate, translate, or rewrite a Remotion composition as HyperFrames (e.g. "port my Remotion project to HyperFrames"). Do NOT use when (a) authoring a NEW HyperFrames composition (even if A/B-testing a Remotion video); (b) Remotion is mentioned in passing; (c) Remotion code is shared as reference, not for translation; (d) the user wants "the same video as my Remotion one" without explicitly asking to migrate the source — treat as a fresh HyperFrames build. When in doubt, default to the `hyperframes` skill. Detects unsupported patterns (useState, useEffect side effects, async calculateMetadata, third-party React component libraries, `@remotion/lambda`) and recommends the runtime interop escape hatch instead of a lossy translation.

delorenj/skills

Generate speech using the self-hosted voxxy (vox) TTS service at https://vox.delo.sh. Use when the user asks to speak, say, narrate, synthesize speech, clone a voice, create a voice, add or register a voice, pipe TTS, or control voice qualities by description (e.g. "a young woman with a cheerful voice"). Handles HTTP API usage, voice profile management, description-based voice design, cloning, MCP registration, and integration patterns for new platforms.

delorenj/skills

Capture a website and create a HyperFrames video from it. Use when: (1) a user provides a URL and wants a video, (2) someone says "capture this site", "turn this into a video", "make a promo from my site", (3) the user wants a social ad, product tour, or any video based on an existing website, (4) the user shares a link and asks for any kind of video content. Even if the user just pastes a URL — this is the skill to use.

delorenj/skills

YouTube transcripts to summaries, threads, blogs.

관련 스킬