Communitygithub.com

motion-voice

Produza e sincronize a narração de um papercut reel com o vídeo. Três caminhos: Qwen3-TTS local, sua própria gravação ou outro TTS, ou uma voz de placeholder. Abrange regras de entrega, voice.json, legendas e temporização de cenas.

O que é motion-voice?

Este skill automatiza o processo de criar e sincronizar a narração para um papercut reel no ecossistema Motion (motion.build). Ele produz dois artefatos essenciais: arquivos WAV individuais para cada linha do script e um arquivo de temporização (`timing_narrator.js`) que mapeia cada palavra com seu instante de início e fim. O skill oferece três caminhos: (A) usar o TTS local Qwen3-TTS com suporte a clones de voz, controle de tom e instruções por linha; (B) usar sua própria gravação ou outro motor TTS, transcrevendo com ASR para gerar a temporização; (C) gerar um placeholder silencioso ou com a voz `say` do macOS para iniciar a edição visual antes da narração final. Após gerar a voz, o skill constroi automaticamente as legendas no formato Remotion `Caption[]` e o plano de cenas (`plan.json`), integrando-se perfeitamente com as etapas seguintes de construção de cenas, som e renderização. As regras de entrega enfatizam uma voz humana, pausada e com ênfase natural, incluindo respiração entre frases, entonação de perguntas e tom caloroso, sem soar como um locutor. O skill também lida com correções manuais por meio de um arquivo `picks_override.json`, permitindo ajustar a escolha das takes sem reprocessar todo o pipeline.

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

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

Voz Papercut

Toda etapa posterior precisa de duas coisas na pasta de narração: voice/final_narrator/<id>.wav (um WAV por linha do script) e timing_narrator.js (início e fim de cada palavra). Este skill as produz por um dos três caminhos e depois constroi as legendas e o plano de cenas. A referência completa dos scripts está em $MOTION_LIB/core/voice/README.md.

Pré-voo

  • Biblioteca: $MOTION_LIB, senão a linha MOTION_LIB= em ~/.config/motion-explainer/config.env, senão pergunte uma vez. Exporte-a, e . "$MOTION_LIB/env.sh" carrega ASR_PY, QWEN_TTS_PY e os outros valores de configuração no shell.
  • Um projeto estruturado (motion-build, passo 1) com narration/script.json e video/episode.json contendo scenes. new_episode.sh copia build_timing.py para narration/.
  • Se o usuário já tem um TTS instalado, use-o como está e não o reconstrua (caminho B, ou A se for Qwen3-TTS). Pergunte uma vez qual é e onde roda. Caso contrário, pergunte qual caminho e diga o que precisa:
CaminhoNecessitaModo de instalação
A. Qwen3-TTS localo venv de voz de $MOTION_LIB/core/voice/setup_tts.sh (download do modelo 2.3-4.2 GB)Completa
B. Sua própria gravação ou outro TTSum backend ASR (mlx-whisper ou faster-whisper) e librosa + numpy para o passo de pitch, no Python que ASR_PY e QWEN_TTS_PY nomeiamCompleta, ou esses pacotes manualmente
C. Placeholderffmpeg; macOS para --sayPadrão

Se o caminho precisar de mais do que a instalação tem, execute ./install.sh --doctor e passe para motion-setup. Sem ASR, o build_timing.py apenas estima 2,75 palavras por segundo, então as legendas desviam do áudio real.

Caminho A: Qwen3-TTS local

A partir da pasta da série:

cp $MOTION_LIB/core/voice/voice.example.json voice/voice.json     # uma vez por série; edite-o
$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) e instruct. Recomendado: CustomVoice 1.7B, Ryan ou Aiden, instruct "amigável, natural, conversacional, como contar para um amigo; pausas claras entre as frases; destaque a palavra-chave de cada linha". takes_per_line padrão é 3. tempo permanece 1.0 (outros valores precisam de rubberband). qa_targets define a faixa de pitch e a correspondência ASR (0.9).
  • Uma linha de script pode conter tts (texto reescrito para pronúncia; as legendas mantêm text) e seu próprio instruct. num.json mapeia numerais para palavras faladas ({"13.000": "treze mil"}) para que a correspondência ASR não falhe em dígitos.
  • Execute um processo TTS por vez; o modelo 1.7B consome muita memória.
  • finalize.sh executa ASR e pitch em cada take, escolhe um por linha, corta, normaliza a intensidade para -16 LUFS, reexecuta ASR nos finais e escreve timing_narrator.js. Após ouvir, coloque correções em voice/picks_override.json ({"l3_name": 2}) e reexecute com SKIP_PICK=1.
  • Voice Design (descrever uma voz em palavras) é um modo do Qwen3-TTS que o narrate.py não aciona. Gere com ele em outro lugar e use o caminho B.

Caminho B: sua própria gravação ou outro TTS

  • Coloque um WAV por linha em voice/final_narrator/<id>.wav, ou takes brutos como voice/takes/narrator/<id>_<k>.wav e execute finalize.sh como acima.
  • Para linhas finalizadas, transcreva-as, escreva voice/chosen_narrator.json como {id: "voice/final_narrator/<id>.wav"}, e então a partir de 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

Caminho C: Placeholder

A partir da pasta narration/:

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

Ele escreve WAVs silenciosos (ou a voz say do macOS com --say) e timing_narrator.js a partir apenas de script.json, distribuindo os tempos das palavras pelo comprimento delas. --wps 3.5 a 4 aproxima o ritmo alvo (padrão 3.0). O reel pode ser construído e temporizado primeiro e ter a voz trocada depois: substitua os WAVs, reexecute finalize.sh, reexecute build_vo.py, e as marcações das palavras acompanham.

Regras de entrega

A entrega é humana, sem pressa e enfatizada. O espectador deve seguir cada linha na primeira audição.

  • Espaço para respirar. Uma pausa real no final de cada frase e entre os beats da lista ("Bem. Bem. Bem."). Comece com 0,3-0,4 s entre as linhas (gap em episode.json, padrão 0,22; gaps adiciona uma batida extra após uma linha nomeada) e julgue pelo ouvido. As pausas vão apenas nos limites de frases ou orações: uma lacuna de 0,2 s dentro de uma frase, como "copiou, | pegando...", parece atraso. Use o limite de 30 s para espairecer em vez de cortar pausas, e nunca desacelere o ritmo para conseguir.
  • Ênfase. As uma ou duas palavras em que cada linha se apoia (o número, a palavra surpresa, o veredito) vêm da tabela de staging do script. Passe-as como um instruct por linha.
  • Tom. Conversacional e ligeiramente divertido, não energia de locutor. Perguntas soam como perguntas reais, a frase de efeito soa curiosa, a CTA é calorosa. O narrador ainda não brinca; a imagem sim.
  • Modelo clone (sem instruções). Com uma voz clonada (ref_audio + ref_text, modelo Base) as alavancas são o texto e a take. Escreva as pausas na pontuação (pontos finais entre os beats da lista, uma pergunta curta como sua própria frase). Gere várias sementes de uma take contínua (SEED_BASE, takes_per_line), escolha a que tem mais movimento de pitch nas palavras alvo e ASR 0,9 ou melhor, e regrave uma linha isolada e monótona sozinha (ONLY=l4_peak) e emende-a em um limite de frase. Apenas clone uma voz que você tenha direito de usar.
  • Script inteiro de uma vez dá prosódia consistente: gere uma take, o split_take.py corta por linha, depois defina "gap": 0 em episode.json. Por cena está ok se o usuário preferir.
  • Toque as três primeiras linhas para o usuário antes da execução completa: ONLY=l1_hook,l2_...,l3_... narrate.sh ....

Legendas e temporização

A partir de video/, assim que episode.json tiver 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    # Seção de Temporização do STORYBOARD.md

captions.json é um Caption[] do Remotion; os limites das cenas vêm dos timestamps das palavras; a duração da composição é durationInFrames do plan.json. build_vo.py sinaliza qualquer cena abaixo de 1,2 s. Sem biblioteca, transcreva o WAV com o skill de legendas do Remotion (whisper.cpp) ou qualquer ferramenta de reconhecimento de fala que retorne timestamps de palavras.

As legendas são uma etiqueta rasgada por palavra, páginas de 1 a 3 palavras, a 3,5 a 4 palavras por segundo ($MOTION_LIB/style/$MOTION_STYLE/docs/style-guide.md, seções 11 e 13).

Passagem

O próximo passo é motion-build (stubs, cenas, som, renderização). Ele lê src/plan.json e a seção de Temporização de video/STORYBOARD.md. Qualquer alteração posterior de voz reexecuta build_vo.py e timing_md.py; o cache de cenas então renderiza tudo novamente.

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.

Habilidades Relacionadas