Under the hood

¿Qué hace Under the hood?

Convierte un tema (o el código del usuario) en un vídeo explicativo narrado y animado. El estilo es cálido y dibujado a mano:

• un fondo de "papel" crema con cuadrícula de puntos y arte de línea en tinta
• azul para peticiones, naranja para respuestas, verde para cifrado o éxito
• un indicador de paso en la parte superior y subtítulos grandes en la parte inferior
• paquetes que vuelan entre recuadros y movimientos de cámara entre "mundos"

El resultado de referencia está en ${CLAUDE_SKILL_DIR}/assets/example-cookie/, que muestra qué pasa cuando escribes "cookie" en Google. Abre su scenes.js cada vez que necesites un patrón para algo complejo.

Todo está impulsado por código. Una página canvas renderiza fotogramas de forma determinista, los clips de narración establecen la duración de cada escena, y la música y los efectos de sonido se sintetizan desde la misma línea de tiempo. Un cambio en el script resincroniza todo, y un vídeo de 60 segundos se renderiza en unos 30 segundos.

Tema solicitado: $ARGUMENTS

Dónde está cada cosa

• Scripts: ${CLAUDE_SKILL_DIR}/scripts/ (llámalo SCRIPTS).
• Entorno de ejecución: UTH_HOME (por defecto ~/.local/share/under-the-hood) contiene el módulo de node, el venv de TTS y las voces guardadas. doctor.sh imprime las rutas exactas, incluyendo PY (el Python de TTS).
• Proyectos: ./explainers/<slug>/ en el directorio de trabajo actual, a menos que el usuario indique otro lugar. Si el directorio de trabajo es la carpeta personal, pregunta dónde colocarlo para no ensuciar ~.

Una carpeta de proyecto tiene este aspecto:

index.html  engine.js  scenes.js  script.json  timeline.js
narration/  (clips de voz: <id>.wav, <id>_take2.wav, más archivos de vista previa)
audio/      (pistas y mix.wav)
.shots/     (capturas de pantalla, una carpeta nueva por ejecución)
<slug>.mp4

Flujo de trabajo

0. Verifica la configuración (una línea cuando estés listo)

bash ${CLAUDE_SKILL_DIR}/scripts/doctor.sh          # añade --no-tts si el vídeo no tiene narración

Si imprime READY, anota PY y VOICES y continúa. Si imprime líneas MISSING, carga la skill under-the-hood-setup y síguela, luego ejecuta el doctor de nuevo.

1. Breve toma de requisitos

Si $ARGUMENTS está vacío, pregunta por el tema. Luego pregunta solo aquello que no puedas decidir razonablemente, en un solo mensaje, con valores predeterminados sensatos:

• Enfoque, solo cuando el tema sea amplio. "Cómo funciona internet" necesita un enfoque, "qué pasa cuando haces git push" no.

• Voz: ofrécelo siempre, porque los usuarios no saben que pueden usar su propia voz. Preséntalo así:

  1. voz integrada (por defecto, funciona de inmediato)
  2. una voz guardada, si VOICES lista alguna
  3. tu propia voz: graba unos 20 a 30 segundos en tu teléfono y envía el archivo. Tu voz permanece en tu máquina.
  4. sin narración (solo música y efectos de sonido)

  Si eligen su propia voz, lee ${CLAUDE_SKILL_DIR}/references/voice.md y dales sus consejos de grabación y el párrafo de muestra antes de cualquier otra cosa. Pueden grabar mientras tú escribes el guión gráfico.

• Duración: por defecto de 30 a 60 segundos, 16:9.

No conviertas esto en un cuestionario. Como máximo dos o tres preguntas cortas.

2. Comprende el tema y asegúrate de tener los hechos correctos

Si el usuario dio código, léelo y traza el flujo real. Los espectadores técnicos notarán los errores. Por lo tanto:

• Acierta el orden de los eventos. Ejemplo: en una página ya cargada, el DNS y el handshake TLS ya ocurrieron, así que colócalos en el primer contacto o etiquétalos como "primera visita".
• Prefiere lo que los sistemas modernos realmente hacen. Ejemplo: Chrome habla con Google mediante QUIC y TLS 1.3, no un handshake TCP de tres vías de libro de texto.
• Escribe "simplificado" en un subtítulo cuando simplifiques.
• Usa valores ilustrativos (IPs de ejemplo, dominios .example, puntuaciones inventadas) y evita precisión falsa como recuentos exactos de milisegundos.
• No recrees logotipos ni IU pixel-exactas de productos reales. Los sustitutos de línea encajan mejor con el estilo.

3. Guión gráfico y guion, luego obtén aprobación antes de construir

Planea de 4 a 8 pasos numerados, aproximadamente de 30 a 60 segundos, más una escena de title al principio y una escena de end al final. Para cada escena escribe:

• Narración (script.json): {"id", "text", "gap"}. gap es la pausa después de la línea, de 0,25 a 0,45 segundos.
• Subtítulo (cap): 8 palabras o menos, legible cuando está silenciado. Subsubtítulo (sub): una línea corta.
• Golpe visual: qué aparece y se mueve, y qué sonido tiene.

Lee ${CLAUDE_SKILL_DIR}/references/narration.md antes de escribir la narración. La narración tipo artículo suena a IA leyendo un artículo. Escribe como una persona que explica algo a un amigo.

Muestra al usuario el guion y el guión gráfico como una tabla corta y espera la aprobación. Cambiar palabras ahora es gratis. Después de la generación de voz, cuesta volver a ejecutar.

No uses guiones largos ni punto y coma en la narración ni en el texto en pantalla. El TTS los lee de forma extraña, y las frases cortas suenan más naturales.

4. Crear estructura

bash SCRIPTS/new_project.sh ./explainers/<slug> "<título de página>"

Esto copia engine.js, un scenes.js de inicio (un pequeño ejemplo funcional de "enviar") y script.json. Se niega a sobrescribir una carpeta no vacía. Reemplaza el contenido de inicio con el guión gráfico real.

5. Construye scenes.js

Primero lee ${CLAUDE_SKILL_DIR}/references/engine-api.md. Cubre el modelo de tiempo, todos los ayudantes, las zonas de diseño, los nombres de sonido y la configuración de arranque. Ideas clave:

• defineScenes([...]) con duraciones de diseño. Anima en tiempo de diseño con prog(t, S.id + a, S.id + b). El motor estira cada escena para que se ajuste a su clip de voz, así que nunca ajustes manualmente a las duraciones del clip.
• Mantén el mundo dentro de y 150 a 800. El rastreador se sitúa encima y los subtítulos debajo.
• Las cosas que deben persistir (un navegador, un servidor) aparecen en una escena y permanecen dibujadas después.
• Para un segundo "lugar", como dentro de un centro de datos, dibuja en x + 1920 y desplázate con camera(t). Empieza a revelar su contenido durante el desplazamiento para que la pantalla nunca esté vacía en medio del movimiento.
• Cada evento visible recibe un sonido en sfx(add). Las teclas obtienen key, los paquetes voladores whoosh*, las llegadas thunk o pop, el éxito chime o success. Esto es una gran parte de por qué se siente terminado.

6. Vista previa sin voz, comprueba los fotogramas

node SCRIPTS/shots.js <proyecto>            # mitad de cada escena, guardado en una carpeta .shots/<time>/ nueva

Mira cada captura de pantalla. Reduce la escala antes de leer (sips -Z 960 en macOS, ffmpeg -i in.png -vf scale=960:-1 out.png en otros). Comprueba:

• texto que se superpone o sale de los bordes
• fotogramas vacíos durante los desplazamientos
• elementos dibujados encima de cosas que deberían estar detrás

Arregla y vuelve a tomar capturas. Si la página falla al arrancar, el script imprime los errores de página.

7. Voz

Voz integrada (sin --voice):

$PY SCRIPTS/narrate.py --script <proyecto>/script.json --out <proyecto>/narration --takes 2

Una voz guardada: añade --voice <UTH_HOME>/voices/<nombre>.wav.

Una voz nueva a partir de una grabación: sigue ${CLAUDE_SKILL_DIR}/references/voice.md. Cubre prep_voice.sh, una línea de prueba rápida y consentimiento. Solo clona la voz del propio usuario, o una voz de la que confirmen tener consentimiento para usar.

Luego pide al usuario que escuche: <proyecto>/narration/narration-preview_take1.wav (usa open en macOS, xdg-open en Linux).

• La primera ejecución descarga aproximadamente 1 GB de pesos del modelo. Después, se ejecuta en tiempo real en Apple Silicon o GPU, más lento en CPU.
• Tú no puedes oír el audio. Díselo al usuario y pídele que juzgue las tomas de oído. Pueden mezclar tomas línea por línea. Rehacer una sola línea con --only <id>.
• Turbo admite etiquetas como [chuckle], [laugh], [sigh], [gasp] y [surprised]. Usa como máximo una o dos por vídeo.

Sin narración: omite este paso y build_timeline.py. Las escenas mantienen sus duraciones de diseño, y el vídeo obtiene solo música y efectos de sonido.

8. Línea de tiempo, renderizado, verificación

python3 SCRIPTS/build_timeline.py <proyecto> [--pick dns=2,enter=2]
node SCRIPTS/render.js <proyecto> [--music-db -12] [--sfx-db 1] [--silent] [--audio-only]

render.js construye las pistas de voz, música y efectos y las mezcla, bajando el volumen de la música bajo la voz y normalizando a -16 LUFS. Renderiza a <slug>.partial.mp4 y solo lo renombra a <slug>.mp4 después de que ffprobe confirme la duración completa.

Antes de decir al usuario que está listo, verifica el archivo real:

• ffprobe muestra la duración esperada más los flujos de vídeo y audio
• ffmpeg -ss <tiempo tardío> -frames:v 1 muestra la escena correcta
• la sonoridad es aproximadamente -16 LUFS

Luego abre el MP4 y la vista previa index.html. La vista previa reproduce la mezcla sincronizada, con capítulos y desplazamiento.

Informa claramente de lo que se verificó, de lo que no pudiste comprobar (cómo suena el audio) y de qué partes están simplificadas.

Reglas de trabajo

• Sin borrados globales. No ejecutes rm con comodines ni rm -rf en carpetas de proyecto. Las nuevas salidas van a carpetas nuevas, y los archivos se sobrescriben por nombre.
• Un comando detenido puede haberse ejecutado parcialmente. Si el usuario detiene un comando de varios pasos, comprueba qué cambió en disco antes de continuar e infórmale de cualquier efecto parcial. Un conjunto de clips medio intercambiado puede dejar un vídeo parcial corto que parece terminado.
• No actúes automáticamente ante pistas de preferencia. Si el usuario dice "me gusta la toma 2" mientras aún decide, confirma antes de volver a renderizar.
• Ofrece, no construyas: una versión vertical 9:16, recortar a 30 segundos, o más pulido. Mencíonalos en una línea cada uno.

Solución de problemas

• 'NoneType' object is not callable en PerthImplicitWatermarker: ejecuta uv pip install --python $PY "setuptools<81". La biblioteca de marcas de agua de Chatterbox necesita pkg_resources.
• La primera ejecución de TTS es lenta: eso es el calentamiento y la descarga del modelo. Las ejecuciones posteriores son más rápidas.
• Música demasiado alta o baja: --music-db (por defecto -12). Efectos: --sfx-db (por defecto 1). Usa --audio-only para iterar la mezcla rápidamente.
• Chrome no encontrado: establece CHROME_PATH, o carga la skill under-the-hood-setup.
• El audio sin conexión de Chrome no es idéntico bit a bit entre ejecuciones, por lo que las pistas difieren ligeramente entre renderizados. La sincronización es exacta y los fotogramas son idénticos píxel a píxel.