Sitio de video por scroll

Sitio Web con Video Desplazable (Scroll Video)

Cuándo usar

Usa este skill cuando el usuario quiera:

• crear una animación de desplazamiento al estilo Apple a partir de un video;
• construir un sitio web donde el video se controle mediante el desplazamiento (scroll scrubbing);
• convertir un video de producto en una página de aterrizaje cinematográfica;
• desarrollar una experiencia narrativa (scrollytelling) impulsada por video;
• convertir un video en una secuencia optimizada de imágenes para animación con scroll;
• crear una presentación de producto basada en canvas controlada por scroll;
• optimizar una secuencia existente de fotogramas generada para scroll.

No lo uses para fondos de video en reproducción automática comunes ni para efectos de scroll no relacionados.

Crea una experiencia minimalista de página completa, similar a un visor de animación de producto: la página proporciona la distancia de scroll mientras un canvas fijo llena el viewport y reproduce una secuencia de fotogramas derivada del video del usuario. La animación es la interfaz, no un fondo detrás de una página de aterrizaje convencional.

Invocación

Este skill tiene dos modos: crear un sitio web de scroll a partir de un video, u optimizar una secuencia de fotogramas existente. Si el primer argumento es optimize, sigue references/optimize.md y no ejecutes el flujo de construcción que se describe a continuación.

Trata esta forma concisa como una solicitud de construcción completa:

$scroll-video-website <ruta/al/video.mp4>

La ruta del video debe ser el primer argumento después del nombre del skill. Todo lo que sigue a la ruta son instrucciones opcionales del usuario sobre estilo, diseño, texto o comportamiento:

$scroll-video-website ./media/revelacion-producto.mp4
$scroll-video-website ./media/revelacion-producto.mp4 usa un fondo negro y tipografía condensada

El primer ejemplo significa: derivar la secuencia de fotogramas y construir el sitio web de animación por scroll completo descrito a continuación. En el segundo, conserva la misma arquitectura de animación basada en video mientras sigues las indicaciones visuales adicionales. Deja que el agente que usa este skill interprete e implemente el resto del prompt; este skill no define una gramática de comando separada para opciones de estilo.

Interpreta la ruta del video como relativa al directorio de trabajo actual a menos que sea absoluta. Si contiene espacios, el usuario debe ponerla entre comillas. Verifica la ruta exacta primero. Si el nombre de archivo simple no se encuentra allí, busca en el proyecto actual una coincidencia exacta de nombre de archivo, excluyendo los directorios de dependencias, compilación, caché y VCS. Continúa automáticamente si existe exactamente una coincidencia. Si no hay coincidencias o hay múltiples, pide al usuario la ruta precisa. Las llaves en <ruta/al/video.mp4> o {ruta_video} indican un marcador de posición y no forman parte de la ruta real. No requieras ni interpretes una palabra clave use.

Optimiza una secuencia existente exactamente con:

$scroll-video-website optimize

El comando optimize no toma ruta ni otros argumentos. Inspecciona el proyecto actual en busca de secuencias de fotogramas generadas. Continúa cuando se pueda identificar exactamente una secuencia. Si se identifican varias, muéstralas y pregunta cuál optimizar. Si no se encuentra ninguna secuencia o no se puede reconocer con certeza, informa al usuario que no se encontró la carpeta de fotogramas y detente.

Establecer el proyecto y el video fuente

Antes de editar:

1. Inspecciona la estructura del proyecto, scripts, framework, estilos, enrutamiento, convenciones de assets e instrucciones locales.
2. Localiza el video proporcionado por el usuario usando las reglas de invocación anteriores. Si no se proporcionó ningún video o ruta y no se puede identificar con confianza, pídelo antes de implementar.
3. Reutiliza la pila de trabajo existente. No estructures un proyecto de reemplazo cuando ya exista uno funcional.
4. Inspecciona las dimensiones, duración, tasa de fotogramas, número de fotogramas y tamaño de archivo del video con ffprobe cuando esté disponible.
5. Conserva el comportamiento no relacionado y realiza el conjunto de cambios coherente más pequeño necesario.

No crees arte sustituto ni reemplaces el metraje proporcionado. Evita duplicar el video fuente a menos que la construcción lo requiera.

Convertir el video en una secuencia de fotogramas

La ruta de representación predeterminada es una secuencia numerada de fotogramas WebP, no video.currentTime. Extrae los fotogramas en el área de assets públicos/estáticos del proyecto con nombres con relleno de ceros, como frames/frame_0001.webp.

• Conserva la cadencia original hasta 30 fps. Para un clip largo, muéstralo a aproximadamente 240–300 fotogramas totales para que la carga siga siendo práctica.
• Conserva la relación de aspecto original. Usa una calidad WebP razonable alrededor de 78–82 e inspecciona el resultado en lugar de asumir que la configuración es adecuada.
• Registra el número real de fotogramas extraídos en la implementación; no dejes una constante estimada.
• Prefiere ffmpeg para la extracción. Un comando representativo es ffmpeg -i input.mp4 -vf fps=30 -c:v libwebp -quality 80 frames/frame_%04d.webp; adapta la entrada, fps, ruta de salida y las herramientas existentes del proyecto.
• No elimines ni sobrescribas assets no relacionados. Si el destino ya contiene una secuencia, verifica que pertenezca a esta animación antes de reemplazarla.

Usa la búsqueda directa de video pausado solo cuando la extracción de fotogramas no esté disponible o la carga de fotogramas resultante sea claramente inadecuada. Si recurres a ello, explica la compensación y conserva el mismo comportamiento de scroll fijo, bidireccional y suavizado.

Coincidir con la experiencia de referencia

Cuando el usuario no proporciona instrucciones adicionales de diseño o texto, genera una página solo con canvas:

• una página blanca y un escenario fijo con desbordamiento oculto que cubre 100vw por 100vh;
• suficiente altura de documento invisible para un desplazamiento deliberado, aproximadamente 400vh para una fuente de 8 segundos o aproximadamente 240 fotogramas;
• sin barra de navegación, tarjetas, encabezados, llamadas a la acción, degradados ni texto de marketing inventado;
• un canvas que llena el escenario y dibuja cada fotograma con geometría cover, centrado en ambos ejes;
• una breve revelación de opacidad solo después de que el primer fotograma esté listo, evitando un destello de fotograma en blanco;
• tratamiento de imagen moderado solo cuando se adapte al metraje, como un fondo blanco, un ligero ajuste de contraste o mix-blend-mode: multiply para una representación de producto con fondo blanco.

Si el usuario solicita contenido, mantenlo escaso y colócalo sobre o entre momentos intencionados de la animación sin reducir el dominio visual del canvas. No introduzcas una dependencia de animación cuando el canvas nativo y las APIs del navegador sean suficientes.

Implementar el desplazamiento por canvas (canvas scrubbing)

Usa un escenario fijo o sticky que contenga un canvas aria-hidden. Ajusta su búfer de respaldo para la relación de píxeles del dispositivo, con un tope de aproximadamente 2, mientras mantienes las medidas de dibujo en píxeles CSS. Restablece la transformación del canvas antes de aplicar una nueva escala de DPR al redimensionar para que el escalado no se acumule.

Asigna el progreso total de la página (limitado) a la secuencia completa:

const rango = document.documentElement.scrollHeight - innerHeight
const progreso = rango > 0 ? Math.min(1, Math.max(0, scrollY / rango)) : 0
fotogramaDestino = progreso * (numFotogramas - 1)

Desplazarse hacia adelante debe avanzar la animación y el desplazamiento inverso debe revertirla. Los manejadores de scroll y redimensionamiento solo deben actualizar mediciones económicas o el destino. Ejecuta un único bucle requestAnimationFrame y suaviza un cabezal de reproducción de punto flotante con interpolación exponencial independiente de la tasa de fotogramas:

const dt = Math.min((ahora - ultimoTiempo) / 1000, 0.1)
const alpha = 1 - Math.exp(-dt * 9)
fotogramaActual += (fotogramaDestino - fotogramaActual) * alpha

Dibuja el fotograma entero a cada lado del cabezal de reproducción y desvanece el siguiente fotograma por el resto fraccionario. Primero limpia o pinta el fondo del canvas, restablece globalAlpha después de dibujar y vuelve a dibujar al redimensionar.

Cargar fotogramas progresivamente

No bloquees la primera pintura en toda la secuencia:

1. Carga el primer fotograma primero, dibújalo y revela el canvas.
2. Pon en cola fotogramas distribuidos uniformemente a lo largo de la línea de tiempo, por ejemplo, cada octavo fotograma, para que la búsqueda tenga un respaldo cercano temprano.
3. Pon en cola cada fotograma restante.

Rastrea los fotogramas solicitados por separado de los fotogramas cargados para que los pases de prioridad y restantes nunca soliciten la misma imagen dos veces. Mientras un fotograma solicitado aún se está cargando, dibuja el fotograma cargado más cercano. Maneja las fallas de carga de imágenes sin detener el resto de la secuencia.

Usa una estrategia de URL de assets que funcione con la ruta base del proyecto y el destino de implementación. Limpia los listeners de scroll, redimensionamiento, media-query, observadores y fotogramas de animación cuando el componente propietario se desmonte.

Comportamiento responsivo y accesibilidad

Mantén la representación cover en pantallas estrechas y acepta un recorte deliberado; no distorsiones las imágenes. Verifica la colocación importante del sujeto en tamaños de escritorio y móvil. Ten en cuenta los cambios en el viewport móvil y las áreas seguras si se agrega contenido visible.

Para prefers-reduced-motion: reduce, detén el desplazamiento y mantén el primer fotograma adecuado. Mantén cualquier contenido de la página accesible y no bloquees el desplazamiento. El canvas decorativo no debe crear contenido redundante para lectores de pantalla.

Verificar el resultado

Ejecuta las comprobaciones del proyecto e inspecciona el resultado en un navegador cuando esté disponible. Confirma:

• que las primeras y últimas posiciones de scroll lleguen al primer y último fotograma extraído;
• que el desplazamiento hacia adelante y hacia atrás se sienta continuo, sin saltos bruscos, reproducción automática, parpadeos ni canvas en blanco visible;
• que las solicitudes de fotogramas no se dupliquen y que los fotogramas faltantes o lentos usen un respaldo cargado cercano;
• que el recorte cover, el redimensionamiento DPR y el escalado del canvas funcionen en tamaños de escritorio y móvil;
• que el movimiento reducido mantenga un fotograma estático y la limpieza del componente esté completa;
• que la secuencia generada tenga el conteo, dimensiones, orden y tamaño total aceptable esperados;
• que el comportamiento no relacionado del proyecto aún funcione.

Finaliza resumiendo la experiencia, el número de fotogramas extraídos y su carga, las comprobaciones realizadas y cualquier limitación restante del material fuente.