whiteboard-explainer

Videos explicativos tipo pizarra blanca

El núcleo del estilo: la voz y la imagen se mueven juntas. Todo se dibuja, escribe, subraya y rodea con un círculo mientras se dice, y cada diapositiva se construye progresivamente. Lee references/style-guide.md antes de escribir el storyboard; contiene los colores, las reglas para palabras en pantalla, la divulgación progresiva, la tabla de sincronización temporal y la estructura completa del video.

Empieza cada video desde template/ (cópialo, no empieces desde cero): copia el template/ de este skill a <project>/video/, luego ejecuta source env.sh && cargo build --release. El binario es target/release/explainer (explainer.exe en Windows; R ... en env.sh lo ejecuta). La plantilla es una demo de ~95 s ("búsqueda binaria en un minuto") con cuatro escenas para copiar; template/README.md tiene todos los comandos. Ejecuta los scripts de Python desde la carpeta del proyecto como python -I narration/<x>.py con numpy, soundfile, librosa, faster-whisper y pillow instalados. Lo que contiene:

• src/kit.rs: el kit de dibujo (trazos a mano alzada, texto hand/note, underline, circle, arrow, stamp, counter, Card para figuras de paper con mark/ring/spot/zoom, camera, shrink_aside, iconos). Úsalo completo.
• src/lib.rs: despacho de escenas, fichas de capítulos con el dip de 0.1 s, tabla de imágenes, SceneCues (c.w(beat, "palabra") = cuando se dice una palabra). Escenas demo: s_intro.rs (apertura en frío, título, resumen final), s_idea.rs (una diapositiva construida sobre palabras habladas), s_figure.rs (ficha de figura con ring/mark/note/spot y un zoom), s_quiz.rs (el mcq de cuestionario con un sello de "trampa").
• src/objs.rs: objetos reutilizables (mcq, grid, token, vecbar, hbar, code_panel, chat_card, quote_card, axes/trace, vec_arrow, photo, ...) más una sección "este video": pon los objetos recurrentes de cada video allí para que cada escena los dibuje de forma idéntica.
• src/duck.rs: el sprite del presentador (posición de los pies, balanceo al hablar desde la envolvente de voz, ubicaciones por escena: grande en la apertura en frío / cuestionarios / cierre, pequeño abajo a la derecha en el resto). Sin sprites → sin presentador.
• src/t3d.rs (opcional): cubos en modo inmediato y View3 para inserciones 3D de tensores/arrays.
• narration/: script.py (escenas → beats, PAUSE para cuestionarios), tts.py (configuración de voz; encuentra el say.py de local-tts), build_vo.py (voz + caché por línea + modelado de pausas + tempo + alineación de palabras con faster-whisper → audio/narration.wav, src/cues.rs, src/envelope.rs), words.py (verifica cada c.w(...) clave, ramas de envío faltantes y marcadores de posición sobrantes; escribe WORDS.md), est_cues.py (señales provisionales y una pista silenciosa antes de que exista la voz), audit_vo.py / tts_try.py (auditoría de pronunciación), make_srt.py (subtítulos con un mapa DISPLAY, OVERRIDE y --review), envelope.py, glitch.py (verificación del archivo final).
• tools/: prep_figs.py (escribe src/figs.rs desde figs/*.png), get_pet.py (descarga un sprite de presentador), font_metrics.py, make_demo_fig.py, lowprio.py (ejecuta un trabajo con prioridad baja).
• media/: las fuentes. Solo los archivos de medios pueden estar en su nivel superior (include_media_dir! entra en pánico con otros), por lo que los textos de licencia viven en media/licenses/.
• HELPERS.md: el resumen que se le da a cada ayudante de escena (reglas, mapa de archivos, ciclo de compilación y verificación).
• STORYBOARD.md: el storyboard de la demo, que muestra el nivel de detalle que necesitan los ayudantes.
• THIRD_PARTY.md: licencias de fuentes, sprites, fframes y FFmpeg.

Requisitos

• Rust (estable) y fframes 1.3.0 desde crates.io (fijado en template/Cargo.toml; consulta sus términos de licencia para tu uso).
• Bibliotecas compartidas de FFmpeg (compilación "shared" de FFmpeg 7+) y LLVM/libclang para la compilación de fframes. template/env.sh lee FFMPEG_DIR y LIBCLANG_PATH; en Windows también pon bin de FFmpeg en PATH, tanto para cargo como para el binario compilado (sin los DLL sale 127 en silencio cuando se canaliza).
• Python 3.10+ con faster-whisper (alineación de palabras, auditoría) y numpy.
• El skill local-tts (mismo plugin) para la voz. Una GPU ayuda mucho; todo también funciona en una CPU.
• Un sprite de presentador (opcional): una mascota de Codex de github.com/gennadi-kuzmin/awesome-codex-pets (celdas de 192x208). python -I tools/get_pet.py --list, luego python -I tools/get_pet.py <pet-id> descarga y divide uno en sprites/. La licencia MIT de ese repositorio cubre su código; verifica los derechos de arte de cada mascota antes de publicar un video. Elige uno brillante (las mascotas oscuras desaparecen en la pizarra negra). Sin sprite, el video se renderiza sin presentador.

Versión de fframes y el skill oficial

Los nuevos videos usan fframes 1.3.0. El skill oficial del creador, fframes-video, cubre la API general y cambia con cada lanzamiento, así que léelo para cualquier cosa que este skill no cubra: su SKILL.md, luego references/api.md, audio.md, design.md y 3d.md. Instálalo con npx skills add https://fframes.studio -g -a claude-code -y (pídele al usuario que lo ejecute si tus permisos bloquean las instalaciones); los mismos archivos están en github.com/dmtrKovalenko/fframes bajo skills/fframes-video/. Este skill guarda solo lo específico de este estilo: la apariencia, el flujo de trabajo y las lecciones a continuación. Cuando los dos no estén de acuerdo en el renderizado, los problemas a continuación ganan.

Nuevo en 1.3 y vale la pena usarlo:

• Tomas 3D (fframes::three_d): ver la siguiente sección.
• Verificaciones más precisas: frame 3s --crop x,y,w,h (un recorte ampliado en píxeles de video, para trazos delicados y etiquetas pequeñas), frame --ids (contornos y nombres de cada elemento con un id), strip 2s,5s,9s (tiempos elegidos lado a lado) e inspect --pops (encuentra cosas que aparecen o desaparecen en un fotograma; agrupa los parpadeos del presentador). --pops verifica los fotogramas, no el mp4 codificado, así que aún ejecuta glitch.py en el archivo final.
• Lottie: característica lottie, frame.play_lottie(ctx, "x.json", LottieOptions { .. }) para un icono animado prefabricado. Los trazos del kit dibujados a mano siguen siendo el valor predeterminado; usa Lottie solo cuando coincida con el aspecto de pizarra blanca.
• include_media_dir!(pub struct M, "media", stereo) mantiene los archivos estéreo en estéreo.

Tomas 3D en un video de pizarra blanca

Usa 3D solo cuando la profundidad o una cámara en movimiento es la explicación: una pila de capas que se levanta, formas de tensores, una jerarquía de memoria, un dispositivo físico, una superficie de pérdida, una ficha de figura de paper que se inclina. El texto, las etiquetas, los gráficos y las flechas siguen siendo SVG dibujados a mano. Limítalo a uno o dos momentos 3D por capítulo: el video sigue siendo una pizarra blanca. references/three_d_example.rs es una prueba de 4 s (una pila de capas girando con una capa que se levanta, una etiqueta dibujada a mano fijada a ella, una ficha de paper dibujada en svgr en un plano 3D).

• fframes = { version = "=1.3.0", features = ["compile-time-svgtree", "cli", "3d", "wgpu"] }. El 3D funciona con el renderizador de fotogramas de CPU: con wgpu el 3D se renderiza en la GPU y se lee de vuelta (120 fotogramas a 1080p: 1,4 s en una RTX 4070 Laptop, 4,2 s con Renderer::cpu()). Cuando la GPU está ocupada, cambia los renderizadores a .cpu() (el ejemplo lee FF_3D=cpu) y nada más cambia. Los tipos wgpu pueden necesitar #![recursion_limit = "256"] en main.rs.
• Aspecto de pizarra: Background::Transparent sobre el rectángulo BG del kit, suelo Material::shadow_catcher, ToneMapping::Neutral para que la paleta del kit se mantenga fiel, y Material::standard(c).roughness(0.45).clearcoat(0.4) para objetos voluminosos que se lean en tamaño de tira.
• Etiquetas dibujadas a mano en objetos 3D: camera.project(scene.local_to_world(id, local), w, h) da el píxel dentro de la inserción; añade x/y de la inserción. Dibuja la etiqueta con el kit, en la palabra desencadenante.
• Figuras de paper en 3D: ctx.render_svgr(svgr!(..), w, h) → Texture::from_image(&img) en un Geometry::plane con Material::unlit(0xffffff). El mismo camino pone un PNG de figura en una ficha.
• Un objeto que se mueve debe permanecer dentro del cuadro de su renderizador de inserción, o se corta en el borde.
• Construye la escena una vez en new(), clónala y pósala por fotograma (ver el oficial 3d.md).
• Visuales de tensor/array: el modo inmediato funciona bien. La función de escena construye un Vec<Cube> a partir de t cada fotograma (las posiciones son aritmética simple, por lo que los bloques colapsan, dividen, desenrollan, rellenan fantasmas), renderiza una inserción con una geometría rounded_box compartida, y proyecta puntos para flechas dibujadas a mano. Escribe números de cubo solo en la capa frontal y omite las etiquetas de cubos atenuados (alfa < 0,6) o se muestran a través. Una inspect completa con 3D es lenta (~10 min para 5.400 fotogramas): ejecútala en segundo plano.
• Mantén una etiqueta fijada libre de cada objeto en todo el movimiento de la cámara (verifica un fotograma fijo al inicio y final de la toma), y comienza una toma 3D después de que un shrink_aside haya terminado, no durante.

Flujo de trabajo

1. Investiga la fuente en research/paper_notes.md: cada número con su tabla/página, más peligros de redacción (porcentaje vs puntos, etc.). Extrae las figuras del paper como imágenes (figs/, cartas blancas en el video). Muestra los propios diagramas y figuras del paper en pantalla.
2. Guion (narration/script.py): ~150 palabras por minuto, 1 oración por beat, deletreado para la voz ("Swee Bench", "T cero", números en palabras). Apertura en frío con el número más sorprendente → título + ficha de paper → hoja de ruta → capítulos → 3-4 cuestionarios (pregunta, opciones A-D, PAUSA, respuesta) → póster de veredicto reutilizando los mismos objetos dibujados anteriormente → letra pequeña → cierre. Verifica la duración después de la compilación de voz; recorta líneas o sube TEMPO (1.06 funciona) en lugar de apresurarte.
   • Los cuestionarios son de opción múltiple difíciles y precisos (guía de estilo sección 6): preguntas de razonamiento, cuatro opciones cuyas incorrectas son conceptos erróneos reales, exactamente una respuesta defendible. Escribe research/quiz_keys.md (cada opción justificada con una referencia de página/tabla, números derivados calculados en Python) y revísalo antes de construir la voz.
   • Enseña, no resumas. Construye cada idea desde cero con un ejemplo trabajado en números reales. Define cada término en la línea que lo introduce y reduce la jerga a algo cotidiano ("un nodo es solo un trabajo"). Comienza la mayoría de los beats con una palabra de conexión ("Entonces,", "Ahora,", "Pero") para que los giros sean audibles. Mantente cerca de 150 palabras por minuto: el dibujo necesita tiempo.
   • Introduce cada símbolo correctamente antes de que se use; repite un recordatorio breve en la línea que lo usa.
   • Haz que suene como una persona, no como IA. Lee references/natural-narration.md antes de escribir, luego ejecuta python -I scripts/aispeak_scan.py <project>/narration/script.py. Corrige las subidas de tono preparadas ("Aquí está el quid"), los replanteos no-X-sino-Y, los cierres citables y las preguntas auto respondidas antes de construir la voz.
   • Evita líneas con fragmentos de dos puntos ("Primero: ...", "Tres puntos de referencia."): la voz hace una pausa allí y la siguiente línea suena abrupta. La primera palabra de una escena sola ("Sonda.") puede ser tragada: escribe "A continuación, sonda.". Dale a "¡Gracias por ver!" su propio beat.
3. Storyboard (STORYBOARD.md): por escena, qué elemento aparece en qué palabra desencadenante, su posición aproximada (x, y), tamaño y color, qué figura/recorte, y los objetos recurrentes + significados de colores. Concreto suficiente para implementar, no diseñar. Reserva el área de la ficha (arriba a la izquierda) y el área del presentador (abajo a la derecha).
4. Voz: narration/build_vo.py vocaliza a través del say.py del skill local-tts, encontrado a través de LOCAL_TTS_SAY, luego ~/.claude/skills/local-tts/, luego ~/.claude/plugins/**. ¿GPU ocupada? GGML_BACKEND=CPU y WHISPER_DEVICE=cpu. En caché por línea; cambiar el texto de una línea fuerza una nueva toma. shape() limita cada silencio dentro de un clip por la puntuación que lo precede (0.14 s ninguno, 0.24 ,, 0.3 :;, 0.42 .?!), con 0.5 s entre líneas (0.7 después de una pregunta). Audita la voz antes de dibujar escenas: audit_vo.py transcribe cada clip sin el script como una indicación (Whisper indicado de build_vo oculta las malas pronunciaciones) y lo compara con el script. Ignora las ortografías estadounidenses y los homófonos; corrige las lecturas incorrectas reales, probando correcciones con tts_try.py (dentro de la oración completa: un nombre puede estar bien solo y mal en medio de la línea). Las lecturas incorrectas conocidas están en los problemas del skill local-tts. Vuelve a ejecutar la auditoría después de cada revocalización (Qwen ocasionalmente duplica una palabra, "the the"). ¿Voz aún no lista? est_cues.py escribe señales provisionales y una pista silenciosa, y las escenas se reajustan cuando build_vo.py sobrescribe ambas.
5. Kit + 1-2 escenas ejemplares dibujadas por ti y verificadas a tamaño completo, para que los ayudantes tengan un estándar de calidad.
6. Distribuye grupos de escenas a subagentes paralelos (modelos pequeños y rápidos con alto esfuerzo de razonamiento hacen esto bien cuando el resumen es ajustado; un modelo más fuerte solo se necesita para los ejemplares). Pon los objetos recurrentes en objs.rs y completa HELPERS.md primero, con rutas absolutas a research/. Copia el proyecto en work/<group>/ por agente (omite renderizados y la caché de narración) con el directorio de destino enlazado (cp -al target work/g/target, o un CARGO_TARGET_DIR por ayudante; luego elimina los artefactos de la caja explainer de esa copia ) para ahorrar disco y tiempo de compilación. Cada ayudante edita solo su src/s_<group>.rs, compila, ejecuta words.py e inspect, verifica tiras y fotogramas completos. Fusiona copiando sus s_*.rs de vuelta; compara otros archivos primero.
   • Mantén a los ayudantes rápidos. Las compilaciones son el cuello de botella: mantén [profile.release] incremental = true + codegen-units = 256 (recompilación ~50 s → ~25 s) y ejecuta como máximo ~4 ayudantes a la vez; da grupos posteriores a quien termine primero. Un grupo = 2 escenas de peso similar; divide un cuestionario o una escena densa. Presupuesto: como máximo 3 rondas de compilación y revisión por escena, una tira de 12 fotogramas más @end, luego enumera dudas restantes en lugar de pulir. Una ronda de corrección específica por ayudante es económica.
   • Verifica sus hechos: verifica cada número en pantalla contra paper_notes y calcula cada ejemplo trabajado (los ayudantes han inventado números, llevadas que van en dirección incorrecta y una demo que reveló la respuesta de un cuestionario posterior). Verifica que las fotos coincidan con la narración.
   • Revisa las tiras y fotogramas de cada ayudante tú mismo (sus imágenes de verificación pueden estar desactualizadas), luego envía correcciones concretas. Su falla común es agrupar cada fase en la mitad superior con letra pequeña: da rangos de y y px

…

[truncado para traducción]