explicador-corto

¿Qué hace explicador-corto?

Crea un video explicativo vertical: presentador en la mitad inferior, gráficos animados en la mitad superior, fichas de subtítulos grandes en el centro. Una idea por clip. Los tokens de tema controlan color, tipo, radio y movimiento, permitiendo que el mismo guión se vea cálido, monocromático, de alto contraste o juguetón.

Cuándo usarlo

• Un video explicativo vertical de enseñanza o producto de 8 a 30 segundos
• Un pipeline reutilizable HTML/Canvas que exporte MP4
• Temas visuales intercambiables sin reescribir el código de la escena

Diseño

+---------------------------+
|   gráficos / tarjetas (1080) |
|                           |
|---------------------------|  <- ficha de subtítulo en la unión
|   recorte del presentador (960) |
|                           |
+---------------------------+
         1080 x 1920

Sistema de temas

Los temas están en template/themes/*.json (y sample/themes/ para la demo). El tema activo es theme.json en la carpeta del proyecto.

bash template/scripts/use-theme.sh warm          # o mono | high-contrast | playful
# o desde un proyecto copiado:
bash scripts/use-theme.sh mono

Tokens (variables CSS después de loadTheme):

Token	Función
--ink --mute	Texto
--bg --bg-hi --bg-lo	Fondo del escenario
--surface --surface-2	Tarjetas
--accent --accent-2 --accent-3	Énfasis
--chip-bg --chip-fg	Ficha de subtítulo
--radius-card --radius-chip --chip-size	Forma
--headline-weight	Grosor del título
--font-sans --font-mono	Tipo (OFL woff2 en fonts/)

Preajustes: warm (predeterminado), mono, high-contrast, playful.

Edita un archivo JSON, vuelve a ejecutar use-theme.sh, recarga. Sin paso de compilación para el tema en sí.

Cambio de fuente

1. Coloca un woff2 con licencia abierta en fonts/ y mantén su archivo de licencia junto a él.
2. Establece fonts.sans / fonts.sans_file (y mono) en el JSON del tema.
3. Apunta @font-face en index.html al nuevo archivo si cambia el nombre de la familia.
4. Renderiza un fotograma intermedio y confirma.

Valores predeterminados incluidos: Inter + JetBrains Mono (SIL OFL). Los textos de licencia se distribuyen en fonts/.

Inicio rápido (demo de tema, sin grabación de presentador)

npm install
node scripts/render_sample.mjs warm
node scripts/render_sample.mjs mono
# salidas: sample/out/<preset>/<preset>.mp4 + fotogramas estáticos

Requiere: Node 18+, Chrome o Chromium del sistema, ffmpeg.

Pipeline completo del proyecto (autocontenido)

1. Copia template/ en una nueva carpeta de proyecto (o trabaja dentro de sample/).
2. Escribe escenas en main.js que llamen a window.render(t) y usen variables CSS del tema.
3. Presentador opcional: coloca una grabación, completa src/edit.json, ejecuta python3 src/edit.py (necesita numpy + soundfile), luego python3 src/captions.py.
4. Desde la raíz del skill (después de npm install):

PRESET=warm bash template/build.sh
# o, para un proyecto copiado:
SKILL_ROOT=/ruta/a/explainer-short PRESET=mono bash build.sh
# o llama al renderizador directamente:
node scripts/render.mjs --dir ruta/al/proyecto --preset warm --out ruta/al/proyecto/out/video.mp4

5. Si tienes out/voice.wav, python3 mix.py normaliza la sonoridad a -14 LUFS / -1 dBTP y build.sh lo multiplexa.

template/scripts/render.mjs también se copia junto con la plantilla para que un proyecto pueda mantener una copia local.

Reglas de diseño

1. Una idea. Un objeto, una promesa, resuelta antes del final.
2. Legible a la distancia de un brazo. Tipografía grande, alto contraste, pocas palabras en pantalla.
3. Las fichas de subtítulos son la voz. Mantén las indicaciones breves; congela en la última palabra brevemente.
4. Tematiza, no codifiques. Los colores, radios y tamaño de ficha provienen de tokens.
5. Predeterminado de buen gusto. Cálido es el predeterminado; la persona elige un preajuste.

Revisión antes de publicar

Puntúa cada eje de 0 a 3. Publica solo si el promedio es al menos 2.3. El revisor independiente mide el archivo principal.

Eje	Busca
Congelación	El último subtítulo se mantiene ~0.3-0.5s; sin corte a mitad de palabra
Sonoridad	Aproximadamente -14 LUFS integrados (mide con ffmpeg loudnorm)
Pico verdadero	<= -1 dBTP
Portada	El fotograma final o el desplazamiento de miniatura es una tarjeta de título clara
Tema	Tokens aplicados; sin colores de marca codificados sobrantes
Claridad	Un desconocido capta el punto sin audio

Rúbrica completa: references/review-rubric.md. Zonas seguras: references/cover.md.

Archivos

Ruta	Función
package.json	Declara playwright-core
template/	Proyecto inicial (HTML, tema, fuentes, build.sh)
template/themes/	JSON de preajustes
template/theme.js	loadTheme() -> variables CSS en :root
sample/	Demo de tema autocontenido de 12s
scripts/render.mjs	Renderizado de fotogramas sin cabeza + multiplexión ffmpeg
scripts/render_sample.mjs	Envoltorio conveniente para preajustes de muestra
references/	Estructura, temas, rúbrica de revisión, portada, final
docs/	Fotogramas de vista previa de ejecuciones verificadas

Lista de verificación para el agente

• npm install ejecutado en la raíz del skill
• Preajuste de tema elegido (o el predeterminado warm)
• theme.json coincide con el preajuste
• Las escenas usan variables CSS, no colores de marca codificados
• La muestra o la construcción completa produce MP4
• ffprobe confirma 1080x1920 y duración esperada
• El fotograma intermedio se ve acorde a la marca para el preajuste
• Sonoridad ~ -14 LUFS y pico verdadero <= -1 dBTP cuando hay audio
• Media de la rúbrica de revisión >= 2.3
• Sin restos de marcas personales o de terceros en el proyecto