Voz para papercut
Cada etapa posterior necesita dos cosas en la carpeta de narración: voice/final_narrator/<id>.wav (un WAV por línea de guion) y timing_narrator.js (un inicio y fin para cada palabra). Esta habilidad los produce mediante una de tres rutas, luego construye los subtítulos y el plan de escenas. La referencia completa para los guiones está en $MOTION_LIB/core/voice/README.md.
Verificación previa
- Librería:
$MOTION_LIB, o la líneaMOTION_LIB=en~/.config/motion-explainer/config.env, o preguntar una vez. Exportarla, y. "$MOTION_LIB/env.sh"cargaASR_PY,QWEN_TTS_PYy los otros valores de configuración en el shell. - Un proyecto scaffolded (
motion-build, paso 1) connarration/script.jsonyvideo/episode.jsonque contienescenes.new_episode.shcopiabuild_timing.pyennarration/. - Si el usuario ya tiene un TTS instalado, úsalo tal cual y no lo reconstruyas (ruta B, o A si es Qwen3-TTS). Pregunta una vez cuál y dónde se ejecuta. De lo contrario, pregunta qué ruta, y di lo que necesita:
| Ruta | Necesita | Modo de instalación |
|---|---|---|
| A. Qwen3-TTS local | el venv de voz de $MOTION_LIB/core/voice/setup_tts.sh (descarga de modelo 2.3-4.2 GB) | Completa |
| B. Tu propia grabación u otro TTS | un backend ASR (mlx-whisper o faster-whisper) y librosa + numpy para el paso de tono, en el Python que nombren ASR_PY y QWEN_TTS_PY | Completa, o esos paquetes a mano |
| C. Relleno | ffmpeg; macOS para --say | Estándar |
Si la ruta necesita más de lo que tiene la instalación, ejecuta ./install.sh --doctor y pasa el control a motion-setup. Sin ASR, build_timing.py solo estima 2.75 palabras por segundo, por lo que los subtítulos se desvían del audio real.
Ruta A: Qwen3-TTS local
Desde la carpeta de la serie:
cp $MOTION_LIB/core/voice/voice.example.json voice/voice.json # una vez por serie; edítalo
$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 o Aiden, instruct "amigable, natural, conversacional, como contarle a un amigo; pausas claras entre oraciones; enfatiza la palabra clave de cada línea".takes_per_linepor defecto es 3.tempose queda en 1.0 (otros valores necesitanrubberband).qa_targetsestablece el rango de tono y la coincidencia ASR (0.9).- Una línea de guion puede llevar
tts(texto reescrito para pronunciación; los subtítulos mantienentext) y su propioinstruct.num.jsonmapea numerales a palabras habladas ({"13,000": "trece mil"}) para que la coincidencia ASR no falle con dígitos. - Ejecuta un proceso TTS a la vez; el modelo 1.7B consume mucha memoria.
finalize.shejecuta ASR y tono en cada toma, selecciona una por línea, recorta, normaliza el volumen a -16 LUFS, vuelve a ejecutar ASR en los archivos finales y escribetiming_narrator.js. Después de escuchar, coloca correcciones envoice/picks_override.json({"l3_name": 2}) y vuelve a ejecutar conSKIP_PICK=1.- El Diseño de Voz (describir una voz con palabras) es un modo de Qwen3-TTS que
narrate.pyno maneja. Genéralo con él en otro lugar y usa la ruta B.
Ruta B: tu propia grabación u otro TTS
- Coloca un WAV por línea en
voice/final_narrator/<id>.wav, o tomas raw comovoice/takes/narrator/<id>_<k>.wavy ejecutafinalize.shcomo arriba. - Para líneas terminadas, transcríbelas, escribe
voice/chosen_narrator.jsoncomo{id: "voice/final_narrator/<id>.wav"}, luego desdenarration/:
$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
Ruta C: relleno
Desde la carpeta narration/:
python3 $MOTION_LIB/core/tools/placeholder_vo.py [--wps 3.0] [--say [VOZ]]
Escribe WAVs silenciosos (o la voz say de macOS con --say) y timing_narrator.js solo a partir de script.json, distribuyendo los tiempos de las palabras por su longitud. --wps 3.5 a 4 se aproxima al ritmo objetivo (por defecto 3.0). El reel se puede construir y temporizar primero y re-doblar después: intercambia los WAVs, vuelve a ejecutar finalize.sh, vuelve a ejecutar build_vo.py, y las marcas de palabra se actualizan.
Reglas de entrega
La entrega es humana, sin prisas y enfatizada. El espectador debe seguir cada línea en la primera escucha.
- Espacio para respirar. Una pausa real al final de cada oración y entre los beats de una lista ("Bien. Bien. Bien."). Comienza con 0.3-0.4 s entre líneas (
gapenepisode.json, por defecto 0.22;gapsañade un beat extra después de una línea nombrada) y juzga al oído. Las pausas van solo en los límites de oraciones o cláusulas: un espacio de 0.2 s dentro de una frase, como "lo copió, | tomando...", se lee como retraso. Usa el límite de 30 s para respirar en lugar de cortar pausas, y nunca reduzcas el tempo para conseguirlo. - Énfasis. Las una o dos palabras en las que se apoya cada línea (el número, la palabra de giro, el veredicto) provienen de la tabla de puesta en escena del guion. Pásalas como un
instructpor línea. - Tono. Conversacional y un poco divertido, no con energía de locutor. Las preguntas suenan como preguntas reales, la línea de gancho suena curiosa, la CTA es cálida. El narrador sigue sin bromear; la imagen lo hace.
- Modelo clonado (sin instrucciones). Con una voz clonada (
ref_audio+ref_text, modelo Base) las palancas son el texto y la toma. Escribe las pausas en la puntuación (puntos entre los beats de una lista, una pregunta corta como su propia oración). Genera varias semillas de una toma continua (SEED_BASE,takes_per_line), elige la que tenga más movimiento de tono en las palabras objetivo y ASR 0.9 o mejor, y vuelve a tomar una línea plana sola (ONLY=l4_peak) y empálmala en un límite de oración. Solo clona una voz que tengas derecho a usar. - Guion completo de una vez da una prosodia consistente: genera una toma,
split_take.pyla corta por línea, luego establece"gap": 0enepisode.json. Por escena está bien si el usuario lo prefiere. - Reproduce las primeras tres líneas al usuario antes de la ejecución completa:
ONLY=l1_hook,l2_...,l3_... narrate.sh ....
Subtítulos y temporización
Desde video/, una vez que episode.json tiene 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 # Sección de Temporización de STORYBOARD.md
captions.json es un Caption[] de Remotion; los límites de las escenas provienen de las marcas de tiempo de las palabras; la duración de la composición es durationInFrames de plan.json. build_vo.py marca cualquier escena por debajo de 1.2 s. Sin librería, transcribe el WAV con la habilidad de subtítulos de Remotion (whisper.cpp) o cualquier herramienta de voz a texto que devuelva marcas de tiempo de palabras.
Los subtítulos son una etiqueta rasgada por palabra, páginas de 1-3 palabras, a 3.5-4 palabras por segundo ($MOTION_LIB/style/$MOTION_STYLE/docs/style-guide.md, secciones 11 y 13).
Entrega
El siguiente paso es motion-build (stubs, escenas, sonido, renderizado). Lee src/plan.json y la sección de Temporización de video/STORYBOARD.md. Cualquier cambio posterior de voz vuelve a ejecutar build_vo.py y timing_md.py; la caché de escenas entonces vuelve a renderizar todo.