Communitygithub.com

shengdabai/Tony-Claude-Code-Skills

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

Tony-Claude-Code-Skills란 무엇인가요?

이 스킬은 HyperFrames 컴포지션에서 사용할 미디어 에셋을 생성하기 위한 세 가지 CLI 명령어를 제공합니다: `tts` (텍스트-음성 변환), `transcribe` (오디오/비디오 전사), 그리고 `remove-background` (투명 비디오/이미지 생성). 각 명령어는 첫 실행 시 필요한 모델을 자동으로 다운로드하여 `~/.cache/hyperframes/`에 캐시하므로, 복잡한 설정 없이 즉시 사용할 수 있습니다. 생성된 에셋은 HyperFrames HTML 컴포지션에서 바로 참조하여 사용할 수 있습니다. `tts` 명령어는 Kokoro-82M 모델을 사용하여 API 키 없이 로컬에서 고품질 음성을 생성합니다. 54개의 다양한 목소리를 지원하며, 언어 접두사(예: 'a'=미국 영어, 'b'=영국 영어)를 통해 자동으로 음소화기 로케일을 감지합니다. `transcribe` 명령어는 OpenAI Whisper 모델을 사용하여 단어 수준 타임스탬프가 포함된 'transcript.json'을 생성하며, 모델 크기(tiny, base, small, medium, large-v3)를 선택할 수 있습니다. 특히 중요한 규칙으로, 비영어 오디오를 파괴하지 않도록 `.en` 접미사 모델 사용에 주의해야 합니다. `remove-background` 명령어는 u2net_human_seg 모델을 사용하여 비디오나 이미지의 배경을 제거하고 투명 오버레이(VP9 알파 WebM, ProRes 4444 MOV, PNG)를 생성합니다. 특히 `--background-output` 플래그를 사용하면 피사체와 배경 레이어를 분리하여, 프레젠터 뒤에 텍스트나 그래픽을 배치하는 '텍스트-피사체-뒤' 컴포지션을 쉽게 구현할 수 있습니다. 이 스킬은 특히 TTS → 전사 → 캡션으로 이어지는 워크플로우를 자동화하는 데 유용합니다. 예를 들어, 스크립트로 음성 해설을 생성하고, 이를 다시 전사하여 정확한 타임스탬프를 얻음으로써 동영상 캡션을 완벽하게 동기화할 수 있습니다. Cursor, Claude Code, Codex 등 모든 AI 코딩 에이전트에서 사용할 수 있으며, 개발자는 복잡한 미디어 처리 파이프라인을 단순화하여 HyperFrames 기반의 동적이고 인터랙티브한 웹 컴포지션 제작에 집중할 수 있습니다.

지원 대상✓Claude Code✓Codex CLI~Cursor
npx skills add https://github.com/shengdabai/Tony-Claude-Code-Skills/tree/HEAD/skills/hyperframes-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)은 비영어 오디오를 전사하지 않고 영어로 번역합니다. 이는 조용히 원래 언어를 파괴합니다.

  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": "Hello", "start": 0.0, "end": 0.5 },
  { "id": "w1", "text": "world.", "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)를 사용합니다. 첫 실행 시 약 168 MB의 가중치를 ~/.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이 있는 모든 요소)에 대해 불투명도:1을 강제하므로, 비디오의 불투명도를 직접 애니메이션화하면 조용히 재정의됩니다. 래퍼에는 data-* 속성이 없으므로 CSS/GSAP가 소유합니다.
  2. 두 비디오 모두 data-start="0" 및 data-media-start="0"을 사용하여 프레임워크가 t=0에서 동기식으로 디코딩합니다. 컷아웃을 늦게 마운트(data-start=3.3)하면 시크 + 웜업이 발생하여 기본 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 8 individual skills — each has its own dedicated page.

shengdabai/Tony-Claude-Code-Skills

Downloads videos from YouTube and other platforms for offline viewing, editing, or archival. Handles various formats and quality options.

shengdabai/Tony-Claude-Code-Skills

接收抖音、小红书、微信视频号等短视频链接或分享文案,查询作品/账号数据并提取语音文字稿,按作者和标题归档为 Markdown。用户希望完整解析短视频、取得数据或文字稿时使用;运行前检查 TikHub 与轻抖使用凭证,缺少时用新手能理解的方式引导购买和安全配置。

shengdabai/Tony-Claude-Code-Skills

Read-only queue dashboard for workspace-aware ship. (gstack)

shengdabai/Tony-Claude-Code-Skills

Anime.js adapter patterns for HyperFrames. Use when writing Anime.js animations or timelines inside HyperFrames compositions, registering animations on window.__hfAnime, making Anime.js seek-driven and deterministic, or translating Anime.js examples into render-safe HyperFrames HTML.

shengdabai/Tony-Claude-Code-Skills

Author a new HyperFrames registry block (caption style, VFX block, transition, lower third) or component (text effect, overlay, snippet) and ship it as an upstream PR to the hyperframes repo. Use ONLY when the user wants to CONTRIBUTE to the public catalog — for in-project caption/transition authoring use the `hyperframes` skill, for installing existing registry items use the `hyperframes-registry` skill.

shengdabai/Tony-Claude-Code-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.

shengdabai/Tony-Claude-Code-Skills

GSAP animation reference for HyperFrames. Covers gsap.to(), from(), fromTo(), easing, stagger, defaults, timelines (gsap.timeline(), position parameter, labels, nesting, playback), and performance (transforms, will-change, quickTo). Use when writing GSAP animations in HyperFrames compositions.

shengdabai/Tony-Claude-Code-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.

관련 스킬