Crea un vídeo con Helios
Un vídeo Helios es una página HTML con una única función, window.renderAt(t). Dibuja el fotograma en el instante t segundos. El renderizador Helios carga la página en Chrome sin interfaz gráfica, llama a renderAt(t) una vez por fotograma, captura cada fotograma y codifica el MP4. No necesitas empaquetador, ni framework, ni escribir un script de captura.
1. Escribe la página
Cada fotograma debe ser una función pura de t. El renderizador puede pedir los fotogramas en cualquier orden y debe renderizar el mismo fotograma de forma idéntica cada vez.
- Deriva todo de
t: posiciones, opacidad, qué escena se muestra. Nunca uses contadores,x += velocidad, físicas paso a paso, nisetTimeout/setInterval. - La aleatoriedad debe estar seedada. Usa
rand(semilla)más abajo, no usesMath.random()directamente dentro derenderAt. - Carga los recursos antes del primer fotograma. Mantén una promesa
readypara las fuentes e imágenes, y haz querenderAtsea asíncrono y espere aready. El renderizador espera cualquier promesa que devuelvarenderAt. - Ajusta la página al tamaño del vídeo. Un canvas del tamaño del vídeo, con
html,body{margin:0;overflow:hidden}.
<!doctype html>
<html>
<head>
<meta charset="utf-8">
<style>html,body{margin:0;background:#0b0b10;overflow:hidden}</style>
</head>
<body>
<canvas id="c" width="1920" height="1080"></canvas>
<script>
const W = 1920, H = 1080;
const ctx = document.getElementById('c').getContext('2d');
const clamp = (x, a = 0, b = 1) => Math.min(b, Math.max(a, x));
const ease = (x) => 1 - Math.pow(1 - clamp(x), 3); // easeOutCubic
const span = (t, inicio, duracion) => clamp((t - inicio) / duracion); // 0→1 en [inicio, inicio+duracion]
const rand = (semilla) => { const x = Math.sin(semilla * 12.9898) * 43758.5453; return x - Math.floor(x); };
const ready = document.fonts.ready; // más cualquier imagen que cargues
window.renderAt = async (t) => {
await ready;
ctx.fillStyle = '#0b0b10';
ctx.fillRect(0, 0, W, H);
// Escena 1 (0–3s): título aparece ascendiendo.
const p = ease(span(t, 0.2, 1.2));
ctx.globalAlpha = p;
ctx.fillStyle = '#f5b700';
ctx.font = '800 140px system-ui, sans-serif';
ctx.textAlign = 'center';
ctx.fillText('Hola, vídeo', W / 2, H / 2 + 60 * (1 - p));
ctx.globalAlpha = 1;
// Partículas: una posición seedada por partícula, animadas por t.
for (let i = 0; i < 80; i++) {
const x = (rand(i) * W + t * 60 * (0.5 + rand(i + 99))) % W;
const y = rand(i + 7) * H;
ctx.fillStyle = `rgba(255,255,255,${0.15 + 0.35 * rand(i + 3)})`;
ctx.fillRect(x, y, 3, 3);
}
};
</script>
</body>
</html>
También funcionan páginas con DOM, CSS, SVG y WebGL. Aplica estilos desde t dentro de renderAt, o deja que las animaciones CSS y las timelines de GSAP/motion se ejecuten. El renderizador las posiciona en el tiempo de cada fotograma. Consulta references/pages.md.
2. Renderízalo
npx -y @helios-project/cli@latest render video.html -o video.mp4 --duration 12
| Flag | Uso |
|---|---|
--duration <s> | Duración en segundos. También valen fracciones. Obligatorio para una página con renderAt. |
--width 1080 --height 1920 | Tamaño del fotograma; el valor predeterminado es 1920×1080. Debe coincidir con tu canvas. Vertical 9:16 es 1080x1920. |
--fps <n> | Fotogramas por segundo; el valor predeterminado es 30. |
--audio cancion.mp3 | Banda sonora, ajustada a la duración del vídeo. |
--mode canvas | Más rápido para una página que es solo un <canvas> que ocupa toda la pantalla. El valor predeterminado, dom, captura la página tal como se ve. |
--preset medium | Para el archivo final. Con la misma calidad ocupa varias veces menos y tarda más en codificar. El valor predeterminado, ultrafast, es rápido para borradores. |
El renderizado es fotograma exacto. El fotograma n es exactamente renderAt(n / fps), sin fotogramas perdidos ni duplicados y sin dependencia de la velocidad de la máquina.
Para un GIF, renderiza el MP4 y luego conviértelo. Consulta references/pages.md.
3. Mira los fotogramas antes de decir que está terminado
No entregues un vídeo que no hayas mirado. Renderiza imágenes fijas y hojas de contacto desde la propia página; son rápidas y no necesitan codificación:
npx -y @helios-project/cli@latest still video.html --at 0.5,3,7.25 # PNGs a tamaño completo
npx -y @helios-project/cli@latest sheet video.html --every 1 --duration 12 # una cuadrícula etiquetada
npx -y @helios-project/cli@latest sheet video.html --strip 2:3 --fps 30 # todos los fotogramas entre 2–3s
npx -y @helios-project/cli@latest sheet video.html --at 4 --crop 600,300,720,480 # zoom en una región
Antes de un renderizado largo, comprueba que la página es realmente una función de t:
npx -y @helios-project/cli@latest verify video.html --duration 12 # sale con código 1 y nombra los fotogramas que dependen de historia
Abre los PNGs con tu visor de imágenes y comprueba:
- el texto es legible y está dentro del fotograma
- las transiciones realmente ocurren
- no hay fotogramas vacíos o negros
- el ritmo coincide con lo solicitado
Corrige la página, compruébalo de nuevo y renderiza otra vez.
4. Música y sonido
--audio multiplexa un archivo de audio. Para sincronizar lo visual con la música, usa una de estas opciones:
- BPM conocido: el pulso
kcae en el segundok * 60 / bpm. Conduce los destellos desdetcontra esa rejilla. - Tempo desconocido: analiza el audio dentro de la página. Decódelo una vez y precalcula una envolvente de volumen, luego lee la envolvente en
tdentro derenderAt. Consulta references/music.md.
Cuando algo falla
| Síntoma | Solución |
|---|---|
| "¿Cuánto debe durar el vídeo? Pasa --duration" | Añade --duration <segundos>. |
window.renderAt(2.5) lanzó: … | Tu página dio error en ese instante. El mensaje incluye tu traza de pila. |
| El primer renderizado se detiene para descargar Chromium | Es esperado, y ocurre una sola vez. No ejecutes npx playwright install por tu cuenta: descarga una compilación para una versión incorrecta de Playwright. |
| "La página no define window.helios, window.renderAt(t) …" | Tu script nunca definió renderAt. Revisa si la página tiene un error de carga, como un error de sintaxis o una importación fallida. |
Los fotogramas difieren entre dos renderizados, o verify falla | Algo no es función de t: un Math.random() sin seed, un contador o un temporizador. |
| Fotogramas WebGL en blanco | Dibuja dentro de renderAt (o un bucle rAF), no una vez al cargar. |
Los proyectos más grandes (componentes React/Vue, edición en estudio, renderizado en la nube distribuido) usan los paquetes Helios directamente: https://github.com/BintzGavin/helios.