pr-explainer-film
Una película muda por defecto, de ~30 segundos, en cinco movimientos. La forma es el punto clave: el espectador siente que el diff es ininteligible, luego obtiene la respuesta en palabras sencillas, después ve la prueba, y finalmente sabe qué escribir.
| Tiempo | Movimiento | Propósito |
|---|---|---|
| 0-2s | Gancho | Nombrar el tamaño del cambio ("15 archivos modificados.") |
| 2-8s | Difuminado del diff | Los fragmentos reales pasan rápidamente; los contadores aumentan |
| 8-13s | Palabras sencillas | Un titular de una frase más tres puntos breves |
| 13-23s | Cuatro destellos | Una capacidad cada uno, mostrada junto a las líneas reales que la sustentan |
| 23-30s | Cierre | El comando de instalación se escribe carácter por carácter, luego la URL |
Entradas
Recopila estos datos antes de construir. Pregunta solo por lo que falte.
- Fuente del cambio: un PR o release de GitHub (
gh pr diff,gh pr view --json title,body,files), o un árbol de trabajo local (git diffmás archivos no rastreados). Solo lectura; nunca modifiques el repositorio. - Audiencia: quién no leerá el diff (clientes, compañeros de equipo, seguidores). Esto determina el vocabulario en el resumen y los destellos.
- CTA: el comando de instalación exacto y/o la URL. Úsalo textualmente. Si el producto tiene un solo comando canónico, muestra solo ese comando y ningún otro nombre de herramienta.
- Marca: paleta, logotipo (tu propio archivo), tipografía. Los valores predeterminados en la plantilla son neutros y oscuros.
Flujo de trabajo
- Lee el cambio. Obtén la lista de archivos con recuentos de añadidos/eliminados y los fragmentos reales. Escribe el cambio en una frase que un no ingeniero entendería; si no puedes, aún no entiendes el cambio.
- Elige el contenido (consulta
references/content-rules.md): número del gancho, 5-8 fragmentos del diff para el difuminado, 3 puntos del resumen, exactamente 4 destellos de capacidades, CTA. - Andamiaje.
npx --yes hyperframes init <dir> --non-interactive --example=blank, luego copiatemplate/index.htmlytemplate/film.config.jssobre los archivos generados. Coloca tu logotipo enassets/logo.pngsi tienes uno. - Rellena
film.config.js. Todo el texto, fragmentos y números residen allí. Editaindex.htmlsolo para cambiar las variables de marca en:root, los tiempos o el diseño. - Valida:
npx --yes hyperframes lintluegonpx --yes hyperframes check. Corrige todos los errores. Advertencias aceptables conocidas:nested_structure_needs_subcomposition(la película es intencionadamente un solo archivo para facilitar el cambio de marca). - Míralo.
npx --yes hyperframes snapshot --at 1,4,6,8.3,11,14,17,19.5,22,26,29y abresnapshots/contact-sheet-*.jpg. Verifica la lista a continuación; corrige y toma nuevas instantáneas hasta que esté limpio. - Renderiza.
npx --yes hyperframes render --quality high --workers 2 --output final.mp4. Confirma conffprobeque sea 1920x1080, H.264, y de 28-34s. - Revisa de 4 a 6 fotogramas extraídos del MP4 (
ffmpeg -ss T -i final.mp4 -frames:v 1 f.png), no solo las instantáneas.
Reglas que hacen que el formato funcione
- El diff debe ser real. Copia líneas reales del diff real. Nunca inventes código o recuentos. Calcula los recuentos a partir de
git diff --shortstatmáswc -lde los nuevos archivos. - Ilegible a propósito. El desplazamiento se acelera (
power2.in) y se difumina. No lo ralentices para que la gente pueda leer; la carta de "demasiado para leer" compensa eso. - Palabras antes que pruebas. El resumen viene antes de cualquier destello de capacidad. Cada título de destello es un beneficio en 2-4 palabras; la descripción es una frase sin jerga; el fragmento son 1-5 líneas reales con la línea clave resaltada.
- Exactamente cuatro destellos, una idea cada uno, de unos 2,6 segundos cada uno. Elimina los más débiles en lugar de reducir el texto.
- Superficies alternas. Oscuro para el diff y los destellos, una escena clara para el resumen. El cambio de fondo señala "ahora es simple".
- Cierra con el comando. Escribe el comando real carácter por carácter, luego muestra la URL. Sin segundo CTA.
- Higiene de copia. Elimina los comentarios de código que mencionen competidores o herramientas no relacionadas antes de que lleguen a un fragmento. Nunca muestres una CLI que no sea la del CTA.
- Tus propios activos. Usa tu propio logotipo, tipografías que la máquina ya tenga, y ningún medio de stock o de terceros. La música es opcional; si se usa, solo pistas con licencia para uso comercial (resuelve a través de
media-use), y mantén la película completamente legible sin sonido. - Determinismo. Sin
Math.random,Date.nowni llamadas de red en la composición; anima el texto escrito y los contadores a partir de un valor de progreso de interpolación para que la búsqueda sea exacta.
Lista de verificación de fotogramas (pasos 6 y 8)
- El número del gancho y el texto coinciden con el cambio real.
- La ventana del diff se recorta dentro de su marco; los encabezados de archivo y las líneas verdes/rojas son legibles en reposo, difuminadas al moverse.
- Los contadores terminan en los números reales.
- La diapositiva del resumen muestra los tres puntos antes de que se desvanezca.
- Cada destello tiene título, frase y fragmento visibles juntos, nada recortado.
- El fotograma final muestra el comando completo y la URL, escritos exactamente.
Entrega
Entrega final.mp4 y la carpeta del proyecto (index.html, film.config.js, assets/, meta.json). Reporta la ruta, duración y cualquier advertencia de validación que haya sido aceptada. La carpeta se rerenderiza con el mismo comando; para cambiar la marca o reutilizar para el próximo lanzamiento, edita solo film.config.js.
Consulta references/content-rules.md para límites de tamaño y redacción.