Ein Video mit Helios erstellen
Ein Helios-Video ist eine einzige HTML-Seite mit einer Funktion: window.renderAt(t). Sie zeichnet den Frame zum Zeitpunkt t Sekunden. Der Helios-Renderer lädt die Seite in einem Headless-Chrome, ruft renderAt(t) einmal pro Frame auf, erfasst jeden Frame und kodiert das MP4. Es gibt keinen Bundler, kein Framework und kein zu schreibendes Capture-Skript.
1. Die Seite schreiben
Jeder Frame muss eine reine Funktion von t sein. Der Renderer kann die Frames in beliebiger Reihenfolge anfordern und rendert denselben Frame jedes Mal identisch.
- Leite alles von
tab: Positionen, Deckkraft, welche Szene angezeigt wird. Verwende niemals Zähler,x += speed, Schritt-für-Schritt-Physik odersetTimeout/setInterval. - Zufälligkeit muss gesät werden. Verwende
rand(seed)(siehe unten), nicht ein bloßesMath.random()innerhalb vonrenderAt. - Lade Assets vor dem ersten Frame. Halte ein
ready-Promise für Schriftarten und Bilder bereit und macherenderAtasynchron und lasse esawait readyverwenden. Der Renderer wartet auf jedes Promise, dasrenderAtzurückgibt. - Passe die Seitengröße an das Video an. Ein Canvas in der Größe des Videos, mit
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 über [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 alle geladenen Bilder
window.renderAt = async (t) => {
await ready;
ctx.fillStyle = '#0b0b10';
ctx.fillRect(0, 0, W, H);
// Szene 1 (0–3s): Titel erscheint von unten.
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('Hallo, Video', W / 2, H / 2 + 60 * (1 - p));
ctx.globalAlpha = 1;
// Partikel: eine gesäte Position pro Partikel, animiert durch 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>
DOM-, CSS-, SVG- und WebGL-Seiten funktionieren ebenfalls. Setze Stile von t innerhalb von renderAt oder lasse CSS-Animationen und GSAP/Motion-Timelines laufen. Der Renderer sucht diese zu jedem Frame-Zeitpunkt. Siehe references/pages.md.
2. Rendern
npx -y @helios-project/cli@latest render video.html -o video.mp4 --duration 12
| Flag | Verwendung |
|---|---|
--duration <s> | Länge in Sekunden. Bruchteile sind in Ordnung. Erforderlich für eine renderAt-Seite. |
--width 1080 --height 1920 | Rahmengröße; Standard ist 1920×1080. Passe sie an dein Canvas an. Vertikal 9:16 ist 1080x1920. |
--fps <n> | Bildrate; Standard ist 30. |
--audio song.mp3 | Soundtrack, auf das Video zugeschnitten. |
--mode canvas | Schneller für eine Seite, die nur aus einem einzigen, vollformatigen <canvas> besteht. Der Standard dom erfasst die Seite so, wie sie aussieht. |
--preset medium | Für die endgültige Datei. Sie ist bei gleicher Qualität um ein Vielfaches kleiner und benötigt länger zum Kodieren. Der Standard ultrafast ist schnell für Entwürfe. |
Das Rendern ist frame-genau. Frame n ist genau renderAt(n / fps), ohne ausgelassene oder doppelte Frames und ohne Abhängigkeit von der Maschinengeschwindigkeit.
Für ein GIF rendere das MP4 und konvertiere es dann. Siehe references/pages.md.
3. Überprüfe die Frames, bevor du sagst, es ist fertig
Übergebe kein Video, das du nicht angesehen hast. Rendere Standbilder und Kontaktbögen von der Seite selbst; sie sind schnell und benötigen keine Kodierung:
npx -y @helios-project/cli@latest still video.html --at 0.5,3,7.25 # PNGs in voller Größe
npx -y @helios-project/cli@latest sheet video.html --every 1 --duration 12 # ein beschriftetes Raster
npx -y @helios-project/cli@latest sheet video.html --strip 2:3 --fps 30 # jeden Frame in 2–3s
npx -y @helios-project/cli@latest sheet video.html --at 4 --crop 600,300,720,480 # in eine Region zoomen
Überprüfe vor einem langen Render, ob die Seite wirklich eine Funktion von t ist:
npx -y @helios-project/cli@latest verify video.html --duration 12 # beendet mit 1 und nennt die Frames, die von der Historie abhängen
Öffne die PNGs mit deinem Bildbetrachter und überprüfe:
- Text ist lesbar und innerhalb des Rahmens
- Übergänge finden tatsächlich statt
- Es gibt keine leeren oder schwarzen Frames
- Das Tempo entspricht der Vorgabe
Korrigiere die Seite, überprüfe erneut und rendere erneut.
4. Musik und Ton
--audio multiplexed eine Audiodatei. Um Bilder mit der Musik zu synchronisieren, verwende eine der folgenden Methoden:
- Bekannter BPM: Beat
kfällt beik * 60 / bpmSekunden. Treibe Pulse vontgegen dieses Raster. - Unbekanntes Tempo: Analysiere das Audio in der Seite. Dekodiere es einmal und berechne eine Lautstärkehüllkurve vor, dann lese die Hüllkurve bei
tinrenderAt. Siehe references/music.md.
Wenn etwas schief geht
| Symptom | Behebung |
|---|---|
| „Wie lange soll das Video sein? Gib --duration an“ | Füge --duration <Sekunden> hinzu. |
window.renderAt(2.5) threw: … | Deine Seite hat zu diesem Zeitpunkt einen Fehler verursacht. Die Nachricht enthält deinen Stack-Trace. |
| Der erste Render pausiert, um Chromium herunterzuladen | Das ist zu erwarten und passiert einmal. Führe nicht selbst npx playwright install aus: es holt einen Build für die falsche Playwright-Version. |
| „Die Seite definiert weder window.helios noch window.renderAt(t) …“ | Dein Skript hat renderAt nie definiert. Überprüfe die Seite auf einen Ladefehler, wie z. B. einen Syntaxfehler oder einen fehlgeschlagenen Import. |
Frames unterscheiden sich zwischen zwei Rendern, oder verify schlägt fehl | Etwas ist keine Funktion von t: ein ungesätes Math.random(), ein Zähler oder ein Timer. |
| Leere WebGL-Frames | Zeichne innerhalb von renderAt (oder einer rAF-Schleife), nicht einmalig beim Laden. |
Größere Projekte (React/Vue-Komponenten, Studio-Bearbeitung, verteiltes Cloud-Rendering) verwenden die Helios-Pakete direkt: https://github.com/BintzGavin/helios.