Créez une vidéo avec Helios
Une vidéo Helios est une page HTML unique avec une fonction, window.renderAt(t). Elle dessine l'image au temps t secondes. Le moteur de rendu Helios charge la page dans Chrome headless, appelle renderAt(t) une fois par image, capture chaque image et encode le MP4. Pas de bundler, pas de framework et pas de script de capture à écrire.
1. Écrivez la page
Chaque image doit être une fonction pure de t. Le moteur de rendu peut demander les images dans n'importe quel ordre, et il rend la même image de manière identique à chaque fois.
- Dérivez tout de
t: positions, opacité, scène affichée. N'utilisez jamais de compteurs,x += vitesse, physique pas à pas, ousetTimeout/setInterval. - L'aléatoire doit être ensemencé. Utilisez
rand(seed)ci-dessous, pas unMath.random()nu à l'intérieur derenderAt. - Chargez les actifs avant la première image. Conservez une promesse
readypour les polices et images, et rendezrenderAtasynchrone en attendantawait ready. Le moteur de rendu attend toute promesse querenderAtretourne. - Dimensionnez la page à la vidéo. Un canevas de la taille de la vidéo, avec
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 sur [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; // plus les images que vous chargez
window.renderAt = async (t) => {
await ready;
ctx.fillStyle = '#0b0b10';
ctx.fillRect(0, 0, W, H);
// Scène 1 (0–3s) : titre qui apparaît.
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('Bonjour, vidéo', W / 2, H / 2 + 60 * (1 - p));
ctx.globalAlpha = 1;
// Particules : position ensemencée par particule, animée par 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>
Les pages DOM, CSS, SVG et WebGL fonctionnent aussi. Définissez les styles depuis t dans renderAt, ou laissez les animations CSS et les timelines GSAP/motion s'exécuter. Le moteur de rendu les positionne au temps de chaque image. Voir references/pages.md.
2. Rendez-la
npx -y @helios-project/cli@latest render video.html -o video.mp4 --duration 12
| Drapeau | Utilisation |
|---|---|
--duration <s> | Durée en secondes. Les fractions sont acceptées. Obligatoire pour une page renderAt. |
--width 1080 --height 1920 | Taille de l'image ; la valeur par défaut est 1920×1080. Faites correspondre votre canevas. Le format vertical 9:16 est 1080x1920. |
--fps <n> | Taux d'images par seconde ; la valeur par défaut est 30. |
--audio song.mp3 | Bande-son, découpée à la durée de la vidéo. |
--mode canvas | Plus rapide pour une page qui n'est qu'un seul <canvas> plein écran. Le mode par défaut, dom, capture la page telle qu'elle apparaît. |
--preset medium | Pour le fichier final. Il est plusieurs fois plus petit à qualité égale et prend plus de temps à encoder. La valeur par défaut, ultrafast, est rapide pour les brouillons. |
Le rendu est image par image exacte. L'image n est exactement renderAt(n / fps), sans images sautées ou dupliquées et sans dépendance à la vitesse de la machine.
Pour un GIF, rendez le MP4 puis convertissez-le. Voir references/pages.md.
3. Examinez les images avant de dire que c'est fini
Ne livrez pas une vidéo que vous n'avez pas regardée. Rendez des images fixes et des planches contacts à partir de la page elle-même ; ils sont rapides et ne nécessitent aucun encodage :
npx -y @helios-project/cli@latest still video.html --at 0.5,3,7.25 # PNGs en pleine taille
npx -y @helios-project/cli@latest sheet video.html --every 1 --duration 12 # une grille étiquetée
npx -y @helios-project/cli@latest sheet video.html --strip 2:3 --fps 30 # chaque image entre 2–3s
npx -y @helios-project/cli@latest sheet video.html --at 4 --crop 600,300,720,480 # zoom sur une région
Avant un long rendu, vérifiez que la page est vraiment une fonction de t :
npx -y @helios-project/cli@latest verify video.html --duration 12 # renvoie 1 et nomme les images qui dépendent de l'historique
Ouvrez les PNGs avec votre outil de visualisation d'images et vérifiez :
- le texte est lisible et dans le cadre
- les transitions se produisent réellement
- il n'y a pas d'images vides ou noires
- le rythme correspond au brief
Corrigez la page, vérifiez à nouveau, et rendez à nouveau.
4. Musique et son
--audio mixe un fichier audio. Pour synchroniser les visuels avec la musique, utilisez l'une de ces méthodes :
- BPM connu : le battement
ktombe àk * 60 / bpmsecondes. Pilotez les impulsions depuistsur cette grille. - Tempo inconnu : analysez l'audio dans la page. Décodez-le une fois et précalculez une enveloppe de volume, puis lisez l'enveloppe à
tdansrenderAt. Voir references/music.md.
Quand quelque chose ne va pas
| Symptôme | Correction |
|---|---|
| "How long should the video be? Pass --duration" | Ajoutez --duration <secondes>. |
window.renderAt(2.5) threw: … | Votre page a généré une erreur à ce temps. Le message inclut votre trace de pile. |
| Le premier rendu fait une pause pour télécharger Chromium | C'est normal, et cela se produit une fois. N'exécutez pas npx playwright install vous-même : cela télécharge une build pour la mauvaise version de Playwright. |
| "The page defines no window.helios, window.renderAt(t) …" | Votre script n'a jamais défini renderAt. Vérifiez la page pour une erreur de chargement, comme une erreur de syntaxe ou un import échoué. |
Les images diffèrent entre deux rendus, ou verify échoue | Quelque chose n'est pas une fonction de t : un Math.random() non ensemencé, un compteur ou une minuterie. |
| Images WebGL vides | Dessinez à l'intérieur de renderAt (ou d'une boucle rAF), pas une fois au chargement. |
Les grands projets (composants React/Vue, édition en studio, rendu cloud distribué) utilisent directement les packages Helios : https://github.com/BintzGavin/helios.