explainer (creador de videos explicativos)

¿Qué hace explainer (creador de videos explicativos)?

Un archivo de especificación lista las escenas; los scripts capturan el material, ponen voz a la narración, construyen una subcomposición de HyperFrames por escena y verifican todo antes de enviarlo.

1. understand   leer el código / docs / app sobre la que hay dudas
2. capture      scripts/capture.py      capturas de pantalla, cuadros de elementos, grabaciones, redacción
3. spec         tú escribes explainer.json (escenas + narración + afirmaciones con fuentes)
4. verify facts scripts/verify.py facts (puerta: nada se verbaliza hasta que pasa)
5. build        scripts/build_explainer.py (voz, leyendas, escenas; sin personaje por defecto)
6. verify       scripts/verify.py all   (activos, construcción, render, audio) - bucle hasta que esté limpio
7. render       scripts/render.py

Las rutas son relativas a la raíz de este paquete: la carpeta que contiene .claude-plugin/, dos niveles arriba de este archivo (resolver primero los enlaces simbólicos). Requiere los skills públicos de HyperFrames (hyperframes, hyperframes-cli; hyperframes-registry y media-use para extras). Lee hyperframes una vez antes de editar composiciones generadas a mano.

0. Verificación previa (siempre primero)

Ejecuta python3 scripts/setup.py doctor (añade --json para analizarlo). Lista cada dependencia, para qué sirve y el comando de instalación exacto para esta máquina; sale con 1 cuando falta un elemento requerido.

• Requerido faltante (ffmpeg, Node.js 18+, los skills de HyperFrames, y la clave de ElevenLabs o say cuando esa voz está configurada): dile al usuario en una línea para qué sirve cada uno y propón el comando impreso. Ejecútalo solo después de que el usuario diga que sí. Nunca escribas ni pidas una clave API tú mismo: dile al usuario que exporte ELEVENLABS_API_KEY en su shell.
• Opcional faltante: ofrécelos una vez y di qué desbloquea cada uno. Playwright da capturas web con cuadros de zoom de elementos y capturas de página completa, tesseract (OCR) da el escaneo de secretos en capturas de pantalla, y ASR (mlx-whisper / openai-whisper) da la verificación de audio y tiempos exactos de palabras. Omítelos si el usuario los rechaza; las comprobaciones correspondientes se convierten entonces en pasos manuales de review.
• Skills de HyperFrames (hyperframes, hyperframes-cli, hyperframes-registry, media-use): si faltan, recomienda npx hyperframes skills. Lee hyperframes (y hyperframes-cli para problemas de render) antes de construir o editar cualquier composición.

Configuración (primera ejecución, o cuando el usuario quiere cambiar algo)

python3 scripts/setup.py show imprime la configuración activa. Si no hay ninguna, entrevista al usuario (una pregunta corta a la vez, ofrece el valor predeterminado) y escríbela:

Pregunta	Indicador	Opciones
¿Qué partes?	--features	explainer solo (no se necesita archivo de personaje), o character,explainer para hacer posible un presentador
Idioma de la narración	--language	Código ISO (en, es, ...): elige una voz say clara y le dice al ASR qué esperar
Voz de la narración	--narration-voice	voice (el proveedor configurado), say (gratis, macOS), none (solo leyendas)
Proveedor de voz	--voice	elevenlabs (su ELEVENLABS_API_KEY del entorno + --voice-id), say, none
Límites de crédito	--max-chars, --max-seconds, --daily-credit-cap	los números del usuario
Renderizado	--render	local, cloud, preview
Tamaño	--size	1080x1920 (predeterminado), 1920x1080, 1080x1080

python3 scripts/setup.py init --features explainer --voice say --render local --yes

init ejecuta primero el doctor y ofrece las mismas instalaciones. Si existe una configuración, pregunta antes de sobrescribir (pasa --force cuando se ejecuta de forma no interactiva). setup.py voices --lang <code> lista las voces de macOS para un idioma y las voces de ElevenLabs del usuario; --say-voice "<name>" elige una. Nunca preguntes, imprimas ni escribas claves API.

1. Entender, luego guionizar

• Obtén los datos de la fuente primero: lee el código, PR, documento o aplicación. Un explicador incorrecto es peor que ninguno. Muestra la forma de la cosa antes de los detalles, recorre un caso real (nombres reales, valores reales) y mantén cada escena en una sola idea.
• Forma (≤ styles.explainer.max_seconds): 3-5 escenas de aproximadamente 6-12 s cada una y un título de cierre. TTS lee aproximadamente 2.4 palabras por segundo: mantén la narración de una escena por debajo de ~25 palabras.

Elegir un estilo para este video

El paquete incluye solo valores predeterminados neutros. Elige un estilo por video según el tema, la audiencia y la marca o preferencias del usuario, y pregunta cuando sea importante (una marca, un canal público, una serie). No repitas el aspecto del video anterior por costumbre. Ponlo en el bloque style de la especificación:

Clave	Valores
palette	background, panel, ink, muted, accent, highlight (colores CSS; mantén el contraste del texto ≥ 4.5:1)
typography	font, mono (fuentes incluidas en HyperFrames), title_scale (0.6-1.6)
layout	align (left, center), radius (0-60), background_style (solid, gradient)
motion	motion (calm, normal, lively): duraciones y easing de cada movimiento
captions	caption_style (box, outline, plain, none), caption_position (bottom, top)

Un kit de brand en la configuración (mismas claves) anula tu elección clave por clave. El conjunto del presentador sigue el fondo del video a menos que su bloque tenga su propio style (ver talking-clip).

2. Capturar el material

python3 scripts/capture.py url http://localhost:3000/login --name login
python3 scripts/capture.py url http://localhost:3000/login --name login --box "#submit"   # necesita Playwright
python3 scripts/capture.py screen --name settings --interactive
python3 scripts/capture.py record --name signup --seconds 12          # macOS
python3 scripts/capture.py add --name diagram --file ./docs/arch.png
python3 scripts/capture.py redact --name login --box 820,410,360,48   # o --blur
python3 scripts/capture.py list

• url usa Playwright cuando está instalado (requerido para --box y --full-page), sino Chrome sin interfaz. Sin Playwright, proporciona cuadros de enfoque como rectángulos de píxeles [x, y, w, h] leídos del PNG (el doble de los píxeles CSS a la escala predeterminada). Si Playwright vive en un virtualenv, ejecuta los scripts con ese intérprete (.venv/bin/python scripts/capture.py ...). --box registra el cuadro de un elemento en píxeles de imagen para que una escena pueda hacer zoom directamente hasta él. Por defecto --scale 2 mantiene el texto nítido al hacer zoom.
• Captura la región más pequeña que cuente la historia; un escritorio completo reducido a un marco de teléfono es ilegible. Usa cuadros de enfoque para hacer zoom.
• Un sitio web completo como proyecto en lugar de tomas individuales: npx hyperframes capture <url> (hyperframes-cli).

3. Escribir la especificación

examples/explainer/explainer.json es un ejemplo completo y funcional. Pon la especificación en la raíz del material: los archivos de código y capturas a los que hace referencia deben estar dentro de la carpeta de la especificación. Tipos de escena:

tipo	necesita	qué muestra
screen	capture, opcional focus: [{"box": "#sel" o [x,y,w,h], "label": "...", "at": s}]	la captura de pantalla, luego un movimiento de cámara a cada cuadro con un resaltado y una etiqueta
recording	capture (un video), opcional focus	la grabación de pantalla, silenciada, misma cámara y etiquetas
code	file, lines: "a-b" (≤ 24, líneas ≤ ~49 caracteres en vertical), highlight: [{"lines": [a, b], "at": s}]	el código en una tarjeta, líneas apareciendo, bandas en las líneas clave
diagram	nodes: [{"id","label","sub"?,"highlight"?}], edges: [[a, b]], opcional flow: [ids]	cuadros y flechas construyéndose, un token viajando a lo largo de flow
title	text, opcional sub, dur	una tarjeta final o de sección

Movimiento, en cualquier escena (opcional; los colores y la sincronización provienen del estilo, así que varíalos por video como el resto del aspecto):

Clave	Qué
callouts: [{"type": "circle" o "arrow", "box": [x,y,w,h] o "#sel", "at": s, "note": "..."}]	círculo o flecha dibujados a mano que aparecen; píxeles de imagen en escenas de pantalla/grabación, píxeles de marco en otras
kinetic: [{"text", "at", "dur", "y"?, "from"?}]	palabras que aparecen con énfasis; úsalo con moderación (una o dos por video)
counter: {"to", "from"?, "at", "dur", "prefix"?, "suffix"?, "label"?}	un contador que llega al valor exacto
nivel superior transition: "wipe" o "fade"	una transición en cada corte (por defecto none)

Siguen los elementos del registro count-up, caption-kinetic-slam, hw-callout-circle y hw-arrow (ver /hyperframes-registry). style.hand_font: "Caveat" obtiene esa fuente manuscrita con npx hyperframes add. No hagas que cada video use todas las funciones; elige lo que la historia necesita.

Cada escena con narration debe llevar claims: cada afirmación técnica que hace, con una source (path:lines relativa a la especificación, capture:<name>, https://..., doc:<name>) y status: "supported" una vez que la hayas verificado contra esa fuente. "claims": [] significa que la narración no hace ninguna afirmación técnica. Las afirmaciones no respaldadas se corrigen o eliminan, nunca se verbalizan.

Sin personaje por defecto. Un explicador es narración, leyendas y elementos visuales. Añade el personaje como presentador solo cuando el usuario lo solicite, o cuando consideres que aporta valor (una serie con un presentador, una incorporación amigable) y se lo digas al usuario con el motivo. Luego añade un bloque presenter (intro / outro, cada uno {"text", "plan"?, "mood"?, "style"?, "claims"}; los planes siguen el formato de talking-clip) y construye con --presenter. También necesita features.character. Las escenas del presentador también reciben leyendas (a menos que la especificación establezca "captions": false). examples/explainer/explainer-with-presenter.json es el ejemplo.

4-5. Puerta de hechos, luego construir

python3 scripts/verify.py facts --spec explainer.json
python3 scripts/build_explainer.py --spec explainer.json --project out/explainer --estimate
python3 scripts/build_explainer.py --spec explainer.json --project out/explainer [--confirm] [--presenter]

--estimate imprime la duración y los créditos de ElevenLabs; informa al usuario antes de gastar, luego construye con --confirm. El constructor también ejecuta la puerta de hechos y se detiene si falla. Las leyendas muestran las propias palabras del guión (mayúsculas/minúsculas, puntuación, números) sincronizadas desde la alineación de ElevenLabs, ASR o una estimación.

6. Verificar (bucle requerido)

python3 scripts/render.py out/explainer --out out/explainer.mp4 --quality draft
python3 scripts/verify.py all --project out/explainer --spec explainer.json --video out/explainer.mp4

Etapa	Pasa cuando	Si falla
facts	cada afirmación narrada tiene una fuente existente y estado supported	verifica la fuente; corrige o elimina la afirmación
assets	las capturas y el código son legibles al tamaño de salida; el escaneo OCR (tesseract) / texto no encuentra correos electrónicos, claves, tokens ni números de tarjeta	añade cuadros de enfoque o recaptura más pequeño; capture.py redact; reemplaza secretos en el código con marcadores de posición
build	npx hyperframes check --json no tiene errores ni advertencias (excepto verify.ignore_rules)	corrige la especificación o la composición generada
render	has mirado la hoja de contactos (inicio, cada cambio de escena, mitad de escena, final): sin desbordamiento, superposición, corte o texto ilegible; los visuales coinciden con la narración	corrige, reconstruye, rerenderiza
audio	el ASR del audio renderizado coincide con el guión (verify.min_asr_similarity) y la duración está dentro del límite	regenera la voz o acorta

Cómo manejar el bucle:

1. Ejecuta verify.py all. Cada ejecución es una iteración (contada en <project>/.verify/state.json).
2. render siempre vuelve primero como review: abre las hojas de contactos que lista, verifica cada fotograma, luego registra lo que viste: python3 scripts/verify.py mark render pass --project out/explainer --note "<lo que verificaste>" (o fail, luego corrige). La marca está vinculada a esos archivos exactos; cualquier reconstrucción la invalida.
3. Sin OCR o ASR instalados, assets / audio también se convierten en review: verifica con el ojo o el oído y dílo en el informe.
4. Corrige lo que falló, reconstruye o rerenderiza, y ejecuta verify.py all nuevamente. Salida 0 = enviar.
5. Cuando el conteo llega a verify.max_iterations (por defecto 3) sale con 2: detente y dile al usuario lo que todavía falla. No envies en silencio. Elimina .verify/state.json para comenzar un conteo nuevo después de un cambio importante.

VERIFY.md muestra números: imágenes OCR escaneadas y aciertos, similitud ASR con palabras oídas y esperadas, duración contra el límite. Cítalos cuando informes. Las escenas se alargan automáticamente para que la última leyenda siga siendo legible; si permanece una advertencia line_unread, dale a esa escena más min_dur.

Mantén el HOME normal del usuario al ejecutar los scripts: un HOME temporal hace que npx, Playwright y whisper descarguen todo de nuevo, y rompe la autenticación de gh/npx.

Discrepancias de audio en números, acrónimos o palabras extranjeras: establece language en la configuración y escribe esas palabras en la narración como deberían sonar ("quince", "A P I"). VERIFY.md en el proyecto es el informe de lista de verificación; incluye su resumen cuando entregues el video.

7. Renderizar

python3 scripts/render.py out/explainer --out out/explainer.mp4 usa render.backend (local, cloud o preview); render.max_mb recodifica para ajustarse a un límite de carga. Nunca hagas commit de archivos mp4 o wav.