Crie um vídeo com Helios
Um vídeo Helios é uma única página HTML com uma função, window.renderAt(t). Ela desenha o quadro no tempo t em segundos. O renderizador Helios carrega a página no Chrome headless, chama renderAt(t) uma vez por quadro, captura cada quadro e codifica o MP4. Não há bundler, framework ou script de captura para escrever.
1. Escreva a página
Cada quadro deve ser uma função pura de t. O renderizador pode solicitar quadros em qualquer ordem e renderiza o mesmo quadro de forma idêntica todas as vezes.
- Derive tudo de
t: posições, opacidade, qual cena está sendo exibida. Nunca use contadores,x += speed, física passo a passo ousetTimeout/setInterval. - A aleatoriedade deve ser semear. Use
rand(seed)abaixo, não umMath.random()puro dentro derenderAt. - Carregue assets antes do primeiro quadro. Mantenha uma promessa
readypara fontes e imagens, e façarenderAtassíncrono eawait ready. O renderizador aguarda qualquer promessa querenderAtretorne. - Dimensione a página para o vídeo. Um canvas do tamanho do vídeo, com
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, start, dur) => clamp((t - start) / dur); // 0→1 sobre [start, start+dur]
const rand = (seed) => { const x = Math.sin(seed * 12.9898) * 43758.5453; return x - Math.floor(x); };
const ready = document.fonts.ready; // mais quaisquer imagens que você carregar
window.renderAt = async (t) => {
await ready;
ctx.fillStyle = '#0b0b10';
ctx.fillRect(0, 0, W, H);
// Cena 1 (0–3s): o título sobe.
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('Olá, vídeo', W / 2, H / 2 + 60 * (1 - p));
ctx.globalAlpha = 1;
// Partículas: uma posição semear por partícula, animada 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>
Páginas com DOM, CSS, SVG e WebGL também funcionam. Defina estilos a partir de t dentro de renderAt, ou deixe animações CSS e timelines GSAP/motion rodarem. O renderizador as busca para o tempo de cada quadro. Consulte references/pages.md.
2. Renderize
npx -y @helios-project/cli@latest render video.html -o video.mp4 --duration 12
| Flag | Uso |
|---|---|
--duration <s> | Duração em segundos. Frações são aceitas. Obrigatório para uma página renderAt. |
--width 1080 --height 1920 | Tamanho do quadro; o padrão é 1920×1080. Corresponda ao seu canvas. Vertical 9:16 é 1080x1920. |
--fps <n> | Taxa de quadros; o padrão é 30. |
--audio song.mp3 | Trilha sonora, cortada para o vídeo. |
--mode canvas | Mais rápido para uma página que contém apenas um <canvas> de tela cheia. O padrão, dom, captura a página como ela aparece. |
--preset medium | Para o arquivo final. É várias vezes menor com a mesma qualidade e leva mais tempo para codificar. O padrão, ultrafast, é rápido para rascunhos. |
A renderização é quadro a quadro exata. O quadro n é exatamente renderAt(n / fps), sem quadros perdidos ou duplicados e sem dependência da velocidade da máquina.
Para um GIF, renderize o MP4 e depois converta. Consulte references/pages.md.
3. Olhe para os quadros antes de dizer que está pronto
Não entregue um vídeo que você não examinou. Renderize quadros estáticos e folhas de contato a partir da própria página; eles são rápidos e não precisam de codificação:
npx -y @helios-project/cli@latest still video.html --at 0.5,3,7.25 # PNGs em tamanho real
npx -y @helios-project/cli@latest sheet video.html --every 1 --duration 12 # uma grade rotulada
npx -y @helios-project/cli@latest sheet video.html --strip 2:3 --fps 30 # cada quadro entre 2–3s
npx -y @helios-project/cli@latest sheet video.html --at 4 --crop 600,300,720,480 # zoom em uma região
Antes de uma renderização longa, verifique se a página é realmente uma função de t:
npx -y @helios-project/cli@latest verify video.html --duration 12 # sai com código 1 e nomeia os quadros que dependem do histórico
Abra os PNGs com sua ferramenta de visualização de imagens e verifique:
- o texto é legível e está dentro do quadro
- as transições realmente acontecem
- não há quadros vazios ou pretos
- o ritmo corresponde ao briefing
Corrija a página, verifique novamente e renderize novamente.
4. Música e som
--audio multiplexa um arquivo de áudio. Para sincronizar visuais com a música, use uma destas opções:
- BPM conhecido: a batida
kcai emk * 60 / bpmsegundos. Conduza pulsos a partir detem relação a essa grade. - Tempo desconhecido: analise o áudio na página. Decodifique-o uma vez e pré-calcule um envelope de volume e, em seguida, leia o envelope em
tdentro derenderAt. Consulte references/music.md.
Quando algo está errado
| Sintoma | Correção |
|---|---|
| "How long should the video be? Pass --duration" | Adicione --duration <segundos>. |
window.renderAt(2.5) threw: … | Sua página gerou um erro naquele momento. A mensagem inclui seu stack trace. |
| A primeira renderização pausa para baixar o Chromium | Isso é esperado e acontece uma vez. Não execute npx playwright install você mesmo: ele busca uma versão para a versão errada do Playwright. |
| "The page defines no window.helios, window.renderAt(t) …" | Seu script nunca definiu renderAt. Verifique a página para um erro de carregamento, como um erro de sintaxe ou uma importação com falha. |
Quadros diferem entre duas renderizações, ou verify falha | Algo não é uma função de t: um Math.random() não semeado, um contador ou um timer. |
| Quadros WebGL em branco | Desenhe dentro de renderAt (ou um loop rAF), não uma vez no carregamento. |
Projetos maiores (componentes React/Vue, edição em estúdio, renderização em nuvem distribuída) usam os pacotes Helios diretamente: https://github.com/BintzGavin/helios.