Communitygithub.com

motion-voice

Papercut 릴에 음성을 입히고 영상에 맞춰 타이밍을 조정합니다. 로컬 Qwen3-TTS, 자체 녹음 또는 다른 TTS, 또는 임시 음성의 세 가지 경로를 제공합니다. 전달 규칙, voice.json, 캡션 및 장면 타이밍을 다룹니다. "음성 설정", "음성 재녹음", "스크립트 타이밍"에 사용합니다.

motion-voice란 무엇인가요?

이 스킬은 Papercut 모션 그래픽 워크플로우의 핵심 단계로, 내레이션 오디오를 생성하고 영상 편집에 필요한 정확한 단어별 타임스탬프를 제공합니다. 사용자는 로컬 Qwen3-TTS (1.7B 모델), 자체 녹음 또는 다른 TTS 엔진, macOS `say` 명령어를 사용한 임시 음성 중에서 선택할 수 있습니다. 주요 기능으로는 음성 피치 및 강세 제어, ASR(자동 음성 인식) 기반 타이밍 정렬, 자막 파일(captions.json) 생성, 그리고 장면별 타임라인 계획(src/plan.json) 수립이 포함됩니다. 특히, 음성의 전달 규칙(호흡, 강세, 톤)을 상세히 정의하여 자연스럽고 강조된 내레이션을 보장하며, `voice.json` 설정 파일을 통해 화자, 명령어, 발음 교정 등을 세밀하게 조정할 수 있습니다. 최종 결과물인 `timing_narrator.js`와 오디오 파일은 이후 모션 빌드, 자막, 렌더링 단계에서 직접 사용됩니다.

지원 대상~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/boytegar/motion-skills/tree/HEAD/skills/motion-voice

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

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

문서

Papercut 음성

모든 후반 작업 단계에는 내레이션 폴더에 두 가지가 필요합니다: voice/final_narrator/<id>.wav (스크립트 라인당 하나의 WAV)와 timing_narrator.js (모든 단어의 시작과 끝). 이 스킬은 세 가지 경로 중 하나로 이를 생성한 다음, 캡션과 장면 계획을 구축합니다. 스크립트에 대한 전체 참조는 $MOTION_LIB/core/voice/README.md에 있습니다.

사전 점검

  • 라이브러리: $MOTION_LIB, 또는 ~/.config/motion-explainer/config.env의 MOTION_LIB= 줄, 아니면 한 번 묻습니다. 내보내고, . "$MOTION_LIB/env.sh"를 실행하면 ASR_PY, QWEN_TTS_PY 및 기타 구성 값을 셸에 로드합니다.
  • 스캐폴딩된 프로젝트(motion-build, 1단계)로 narration/script.json과 scenes를 보유한 video/episode.json이 있어야 합니다. new_episode.sh는 build_timing.py를 narration/에 복사합니다.
  • 사용자에게 이미 TTS가 설치된 경우, 그대로 사용하고 재구축하지 않습니다 (경로 B, 또는 Qwen3-TTS인 경우 A). 어느 것인지와 어디서 실행되는지 한 번 묻습니다. 그렇지 않으면 경로를 묻고 필요한 사항을 알려줍니다:
경로필요 요소설치 모드
A. 로컬 Qwen3-TTS$MOTION_LIB/core/voice/setup_tts.sh의 음성 venv (모델 다운로드 2.3-4.2 GB)전체
B. 자체 녹음 또는 다른 TTSASR 백엔드 (mlx-whisper 또는 faster-whisper) 및 피치 패스를 위한 librosa + numpy (ASR_PY 및 QWEN_TTS_PY가 지정하는 Python 내)전체, 또는 해당 패키지를 수동으로
C. 임시ffmpeg; --say에는 macOS표준

경로에 설치된 것보다 더 많은 것이 필요한 경우, ./install.sh --doctor를 실행하고 motion-setup에 넘깁니다. ASR이 없으면 build_timing.py는 초당 2.75단어만 추정하므로 캡션이 실제 오디오와 어긋납니다.

경로 A: 로컬 Qwen3-TTS

시리즈 폴더에서:

cp $MOTION_LIB/core/voice/voice.example.json voice/voice.json     # 시리즈당 한 번; 편집
$MOTION_LIB/core/voice/narrate.sh voice/voice.json episodes/NN-slug/narration
$MOTION_LIB/core/voice/finalize.sh voice/voice.json episodes/NN-slug/narration episodes/NN-slug/narration/voice/takes/narrator [num.json]
  • voice.json: speaker (CustomVoice: Aiden, Dylan, Eric, Ryan, Serena, Vivian, Sohee, Ono_anna, Uncle_fu) 및 instruct. 권장: CustomVoice 1.7B, Ryan 또는 Aiden, instruct "친근하고, 자연스럽고, 대화하듯, 친구에게 이야기하는 것처럼; 문장 사이에 명확한 멈춤; 각 라인의 핵심 단어 강조". takes_per_line의 기본값은 3입니다. tempo는 1.0으로 유지합니다 (다른 값은 rubberband 필요). qa_targets는 피치 범위와 ASR 일치(0.9)를 설정합니다.
  • 스크립트 라인은 tts (발음을 위한 다시 철자된 텍스트; 캡션은 text 유지)와 자체 instruct를 가질 수 있습니다. num.json은 숫자를 발화 단어로 매핑합니다({"13,000": "thirteen thousand"}). ASR 일치가 숫자에서 실패하지 않도록 합니다.
  • 한 번에 하나의 TTS 프로세스를 실행합니다. 1.7B 모델은 메모리를 많이 사용합니다.
  • finalize.sh는 모든 테이크에 대해 ASR 및 피치를 실행하고, 라인당 하나를 선택하고, 트리밍하고, -16 LUFS로 음량을 정규화하고, 최종 파일에 대해 ASR을 다시 실행하고 timing_narrator.js를 작성합니다. 듣기 후, voice/picks_override.json에 수정 사항을 넣고({"l3_name": 2}) SKIP_PICK=1로 다시 실행합니다.
  • 음성 디자인 (말로 음성을 설명)은 narrate.py가 구동하지 않는 Qwen3-TTS 모드입니다. 다른 곳에서 생성하고 경로 B를 사용하십시오.

경로 B: 자체 녹음 또는 다른 TTS

  • voice/final_narrator/<id>.wav에 라인당 하나의 WAV를 넣거나, voice/takes/narrator/<id>_<k>.wav로 원시 테이크를 넣고 위와 같이 finalize.sh를 실행합니다.
  • 완성된 라인의 경우, 이를 전사하고 voice/chosen_narrator.json을 {id: "voice/final_narrator/<id>.wav"}로 작성한 다음, narration/에서:
$ASR_PY $MOTION_LIB/core/voice/asr.py voice/final_narrator/*.wav > voice/asr_narrator_final.json
CHOSEN=voice/chosen_narrator.json TIMING_OUT=timing_narrator.js python3 build_timing.py voice/asr_narrator_final.json

경로 C: 임시

narration/ 폴더에서:

python3 $MOTION_LIB/core/tools/placeholder_vo.py [--wps 3.0] [--say [VOICE]]

script.json만으로 무음 WAV (또는 --say로 macOS say 음성) 및 timing_narrator.js를 작성하며, 단어 길이별로 단어 시간을 분배합니다. --wps 3.5 ~ 4는 목표 속도에 근접합니다 (기본값 3.0). 릴을 먼저 빌드 및 타이밍하고 나중에 음성을 다시 입힐 수 있습니다: WAV를 교체하고, finalize.sh를 다시 실행하고, build_vo.py를 다시 실행하면 단어 큐가 따라옵니다.

전달 규칙

전달은 인간적이고, 여유로우며 강조됩니다. 시청자는 모든 라인을 첫 번째 청취에 따라야 합니다.

  • 호흡 공간. 모든 문장 끝과 목록 비트 사이에 실제 멈춤 ("좋아. 좋아. 좋아."). 라인 사이에 0.3-0.4초로 시작하고 (episode.json의 gap, 기본값 0.22; gaps는 하나의 명명된 라인 뒤에 추가 비트를 추가) 귀로 판단합니다. 멈춤은 문장 또는 절 경계에만: 구절 내부의 0.2초 간격, 예를 들어 "복사했어요, | 가져가서..."는 지연으로 읽힙니다. 멈춤을 줄이는 대신 30초 한도를 확보하는 데 사용하고, 템포를 늦추지 마십시오.
  • 강조. 각 라인이 의존하는 한두 단어 (숫자, 반전 단어, 판결)는 스크립트의 스테이징 테이블에서 가져옵니다. 이를 라인별 instruct로 전달하십시오.
  • 톤. 대화하듯이 약간 즐거운, 아나운서 에너지가 아닙니다. 질문은 실제 질문처럼 들리고, 캐치 라인은 궁금하게, CTA는 따뜻하게. 내레이터는 여전히 농담하지 않습니다; 그림이 합니다.
  • 클론 모델 (명령어 없음). 클론 음성(ref_audio + ref_text, Base 모델)을 사용하면 레버는 텍스트와 테이크입니다. 멈춤을 구두점 (목록 비트 사이의 마침표, 짧은 질문을 자체 문장으로)에 작성합니다. 하나의 연속 테이크의 여러 시드를 생성하고(SEED_BASE, takes_per_line), 대상 단어에서 가장 많은 피치 움직임과 ASR 0.9 이상인 것을 선택하고, 평평한 라인을 단독으로 다시 테이크하고(ONLY=l4_peak) 문장 경계에서 스플라이스합니다. 사용할 권리가 있는 음성만 클론하십시오.
  • 스크립트 전체를 한 번에 일관된 운율을 제공합니다: 하나의 테이크를 생성하고, split_take.py가 라인별로 자른 다음, episode.json에서 "gap": 0을 설정합니다. 사용자가 선호하는 경우 장면별로도 괜찮습니다.
  • 전체 실행 전에 처음 세 라인을 사용자에게 재생합니다: ONLY=l1_hook,l2_...,l3_... narrate.sh ....

캡션 및 타이밍

video/에서, episode.json에 scenes가 있으면:

python3 $MOTION_LIB/core/tools/build_vo.py     # public/vo/voiceover.wav, public/vo/captions.json, src/plan.json
python3 $MOTION_LIB/core/tools/timing_md.py    # STORYBOARD.md의 타이밍 섹션

captions.json은 Remotion Caption[]입니다. 장면 경계는 단어 타임스탬프에서 비롯됩니다. 구성 길이는 plan.json의 durationInFrames입니다. build_vo.py는 1.2초 미만의 장면에 플래그를 지정합니다. 라이브러리가 없으면, Remotion 캡션 스킬 (whisper.cpp) 또는 단어 타임스탬프를 반환하는 모든 음성-텍스트 도구로 WAV를 전사합니다.

캡션은 단어당 하나의 찢어진 태그이며, 초당 3.5-4단어로 1-3단어 페이지입니다 ($MOTION_LIB/style/$MOTION_STYLE/docs/style-guide.md, 섹션 11 및 13).

인계

다음은 motion-build (스텁, 장면, 사운드, 렌더)입니다. 이는 src/plan.json과 video/STORYBOARD.md의 타이밍 섹션을 읽습니다. 이후 음성 변경은 build_vo.py와 timing_md.py를 다시 실행합니다. 그러면 장면 캐시가 모든 것을 다시 렌더링합니다.

Individual skills in this repo

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

bang-motion

Render a reel in the Bang Motion style: high-end cinematic motion graphics with a multi-layer glowing-horizon background, floating colour-mesh blobs, living film grain, frosted-glass UI cards, editorial kinetic typography, a breathing camera, and anti-PPT pacing. Use when the user says cinematic motion graphic, promo opener, product launch reel, kinetic typography, SaaS product tour, glassmorphic UI, anti-slides, or asks for a video that moves like footage instead of a deck. Gunakan skill ini setiap kali user meminta "video promo", "opener", "intro animasi", "motion graphic", "bumper", "kinetic typography", "animasi teks sinematik", "explainer", "video penjelasan" (jurnalisme visual, kartun edukasi, kolase), atau menunjukkan referensi video promosi/explainer dan ingin dibuatkan versi web-nya — bahkan bila mereka tidak menyebut kata "motion graphic" secara eksplisit. Juga gunakan bila user mengeluh hasil animasi web "seperti PPT/presentasi" dan ingin lebih sinematik, atau ingin meren...

isometric

Render a reel in the Isometric style: calm precise product line art in 2:1 dimetric isometric on a white or dark ground, drawn only with constant 2px hairlines, white-filled faces so nearer objects hide farther lines, rounded slabs with visible thickness, stacked layers, repeated-part grids, and one tiny dark accent per frame. Use when the user says isometric, product line art, technical illustration, exploded hardware view, or asks for a clean documentation-grade diagram look.

motion-build

Build and render a papercut episode from a storyboard with the library. Scaffolds the project, builds scenes with parallel agents, assets and audio, renders the mp4, then harvests reusables. Use for "build the reel", "scaffold an episode", "rebuild scene 4", "render it".

motion-explainer

Make a papercut reel, video or explainer end to end. Short vertical (9:16) cut-paper explainers from a link (repo, product page, announcement), idea to mp4. Also routes partial asks to the stage skills and hands out the style prompt for other tools.

motion-qa

Check a papercut reel's stills against the style DNA and the storyboard. Renders contact sheets at a few timestamps, runs the full checklist, then writes the delivery summary. Use for "QA the reel", "check my scenes look like paper", "is this ready to post".

motion-script

Turn a link into a papercut reel script. Researches a sourced facts list, writes the 75-95 word script on the 10-beat spine, a banner fact track, a staging table with one set per banner, and the humour pass. Use for "write the script", "research this repo for a reel".

motion-storyboard

Storyboard a papercut script before any code. Writes the Camera / Cut table, one block per scene with frame-level events on each stressed word, the SFX plan and the proof beat. Use for "storyboard this script" or "plan the camera moves and cuts".

papercut

Render a reel in the Papercut style: layered construction paper brought to life with paper grain, torn edges, stacked shade strips, drop shadows, rigid cut-out animation, a slow camera push, taped headline banners and word-by-word torn-tag captions. Use when the user says cut paper, papercraft, paper cutout, paper collage, construction paper, or asks for the default handcrafted explainer look.

관련 스킬