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 linhaMOTION_LIB=em~/.config/motion-explainer/config.env, senão pergunte uma vez. Exporte-a, e. "$MOTION_LIB/env.sh"carregaASR_PY,QWEN_TTS_PYe os outros valores de configuração no shell. - Um projeto estruturado (
motion-build, passo 1) comnarration/script.jsonevideo/episode.jsoncontendoscenes.new_episode.shcopiabuild_timing.pyparanarration/. - 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:
| Caminho | Necessita | Modo de instalação |
|---|---|---|
| A. Qwen3-TTS local | o 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 TTS | um backend ASR (mlx-whisper ou faster-whisper) e librosa + numpy para o passo de pitch, no Python que ASR_PY e QWEN_TTS_PY nomeiam | Completa, ou esses pacotes manualmente |
| C. Placeholder | ffmpeg; macOS para --say | Padrã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) einstruct. 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_linepadrão é 3.tempopermanece 1.0 (outros valores precisam derubberband).qa_targetsdefine 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êmtext) e seu próprioinstruct.num.jsonmapeia 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.shexecuta ASR e pitch em cada take, escolhe um por linha, corta, normaliza a intensidade para -16 LUFS, reexecuta ASR nos finais e escrevetiming_narrator.js. Após ouvir, coloque correções emvoice/picks_override.json({"l3_name": 2}) e reexecute comSKIP_PICK=1.- Voice Design (descrever uma voz em palavras) é um modo do Qwen3-TTS que o
narrate.pynã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 comovoice/takes/narrator/<id>_<k>.wave executefinalize.shcomo acima. - Para linhas finalizadas, transcreva-as, escreva
voice/chosen_narrator.jsoncomo{id: "voice/final_narrator/<id>.wav"}, e então a partir denarration/:
$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 (
gapemepisode.json, padrão 0,22;gapsadiciona 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
instructpor 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.pycorta por linha, depois defina"gap": 0emepisode.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.