Communitygithub.com

shinyobjectz/reactable

HyperFrames 구성을 위한 자산 전처리 — 텍스트 음성 변환 나레이션(Kokoro), 오디오/비디오 전사(Whisper), 투명 오버레이를 위한 배경 제거(u2net). TTS → 전사 → 캡션 체인을 지원하며 각 명령어는 첫 실행 시 자체 모델을 다운로드합니다.

reactable란 무엇인가요?

이 스킬은 HyperFrames 구성을 위한 미디어 전처리 CLI 도구 세 가지(tts, transcribe, remove-background)를 제공합니다. 각 도구는 첫 실행에 모델을 다운로드하고 `~/.cache/hyperframes/`에 캐시합니다. TTS(tts)는 Kokoro-82M을 사용해 로컬에서 음성을 생성하며 54개 목소리 중 하나를 선택할 수 있습니다. 전사(transcribe)는 Whisper를 사용하여 단어 수준의 타임스탬프가 포함된 transcript.json을 생성하고, 모델 크기(tiny ~ large-v3)를 선택할 수 있습니다. 배경 제거(remove-background)는 u2net_human_seg를 사용해 비디오/이미지에서 배경을 제거하고 투명 오버레이(VP9 알파 WebM, ProRes 4444 MOV, PNG)를 출력하며, 레이어 분리(--background-output)를 지원합니다. 모든 도구는 Python 의존성이 필요하며, Claude Code, Cursor, Codex 등 AI 에이전트가 나레이션 생성, 음성 전사, 배경 제거 워크플로를 자동화할 때 유용합니다.

지원 대상~Claude Code✓Codex CLI~Cursor
npx skills add https://github.com/shinyobjectz/reactable/tree/HEAD/skill/vendored/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는 접두사에서 음소 변환기(phonemizer) 로케일을 자동 감지합니다. — 목소리가 텍스트와 일치하면 --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 <code> (.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) 사용. 첫 실행 시 약 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) 시크 및 워밍업이 발생하여 기본 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

# … (필요한 경우 배경 제거도 사용)

관련 스킬