FrameVelo

Was macht FrameVelo?

FrameVelo verwandelt eine Seite, die ihre Frames aus Code zeichnet, in ein MP4. Die Frames bleiben auf der GPU (drawElementImage oder das Canvas der Seite) und gehen direkt zum Hardware-Encoder, sodass ein Render nur einen Bruchteil der CPU- und Speicherlast von Screenshot-basierten Renderern benötigt. HyperFrames-Projekte werden von der offiziellen HyperFrames-Pipeline kompiliert; FrameVelo ersetzt nur die Aufnahme und Kodierung.

Aufruf

Nutzen Sie die MCP-Tools dieses Plugins, wenn sie verfügbar sind. Beim ersten Start installiert das Plugin FrameVelo in ~/.cache/framevelo (ca. eine Minute); falls die Tools direkt nach der Plugin-Installation fehlen, warten Sie und stellen Sie die Verbindung wieder her (/mcp), oder nutzen Sie die CLI unten.

• render: rendert; gibt den Ausgabepfad, die Framerate, Größe, Zeitmessungen, Warnungen und die letzten Logzeilen zurück.
• doctor: prüft Node, FFmpeg, Chrome, drawElementImage, die Hardware-Encoder und die HyperFrames-Unterstützung.
• install_browser: lädt chrome-headless-shell herunter (ca. 100 MB), wenn kein Chrome 151+ installiert ist.

Ohne die Tools nutzen Sie die CLI. --json gibt das Ergebnis (oder {"error": ...}) auf stdout aus:

npx -y -p github:gnipbao/framevelo -p @hyperframes/[email protected] -p @hyperframes/[email protected] framevelo render /abs/project -o /abs/out.mp4 --json -q

Der erste npx-Lauf installiert etwa eine halbe Minute lang. Wenn Sie häufig rendern, empfehlen Sie dem Benutzer, es einmal global zu installieren: npm install -g github:gnipbao/framevelo @hyperframes/[email protected] @hyperframes/[email protected]. Die CLI akzeptiert dieselben Optionen wie das Tool, als Flags (--frames 30 --quality draft). framevelo render --help listet sie auf.

Verwenden Sie absolute Pfade. Führen Sie nur einen Render gleichzeitig aus: Sie teilen sich den einzelnen Hardware-Encoder, und der MCP-Server reiht sie ohnehin in eine Warteschlange.

Arbeitsablauf

1. Eingabe finden: ein Projektverzeichnis mit index.html oder eine .html-Datei. Dauer, fps und Größe stammen von der Seite (HyperFrames data-duration/data-fps/data-width, window.__framevelo.duration, die GSAP-Timeline-Länge, window.__comp). Übergeben Sie diese nur, um sie zu überschreiben.
2. Ausschnittvorschau bei neuer oder geänderter Komposition: { input, output: "/tmp/preview.mp4", start: 2, frames: 30, quality: "draft" }. Dies dauert Sekunden. Betrachten Sie einen Frame: ffmpeg -v error -ss 0.5 -i /tmp/preview.mp4 -frames:v 1 /tmp/preview.png, dann das PNG anzeigen.
3. Komplett rendern mit Standardeinstellungen. Fügen Sie scale: 2 für 4K aus einem 1080p-Layout oder subframes: 3 für Bewegungsunschärfe hinzu.
4. Ergebnis prüfen: frames ist die erwartete Anzahl; audio ist true, wenn die Komposition Ton hat; lesen Sie warnings. screenshotFrames > 0 bedeutet, dass einige Intervalle die Verifikation nicht bestanden haben und per Screenshot erfasst wurden (immer noch korrekt, nur langsamer).
5. Melden Sie den Ausgabepfad, die Länge, Größe und die benötigte Zeit (wallMs).

Eine Seite rendertauglich machen

Jeder Frame muss eine reine Funktion der Zeit sein. FrameVelo sucht die Seite nach dem ersten dieser gefundenen Mechanismen ab:

1. window.__framevelo = { seek(t), duration, fps }. seek kann ein Promise zurückgeben.
2. window.__seek(t), mit optionalem window.__duration.
3. Eine pausierte GSAP-Timeline auf window.__timelines.main (oder dem ersten Schlüssel).

<canvas id="scene" width="1920" height="1080"></canvas>
<script>
  const g = document.getElementById("scene").getContext("2d");
  function draw(t) {
    g.fillStyle = "#05060a";
    g.fillRect(0, 0, 1920, 1080);
    g.fillStyle = "#6cf";
    g.fillRect(200 + 300 * t, 500, 120, 120);
  }
  window.__framevelo = { duration: 4, seek: draw };
</script>

• Fügen Sie Videomaterial mit <video data-start="1.5" src="clip.mp4"> in die Timeline ein (optional data-media-start, data-duration, data-playback-rate). FrameVelo sucht es auf den exakten Frame; Long-GOP-Quellen erhalten einen gecachten All-Intra-Proxy.
• Math.random wird gesät, sodass Rendervorgänge reproduzierbar sind.
• requestAnimationFrame-Schleifen, CSS-Übergänge, Date.now()- und performance.now()-Animationen können nicht gesucht werden. Verlagern Sie sie auf seek(t) oder eine pausierte GSAP-Timeline.
• Warten Sie auf Ressourcen innerhalb der Seite (Schriftarten, Bilder), bevor Sie den Treiber bereitstellen, oder geben Sie ein Promise von seek zurück.

Wissenswerte Optionen

Bedarf	Argumente
Schnellprüfung	frames: 30, quality: "draft", start: <s>
4K aus einem 1080p-Layout	scale: 2
Vertikale Seite ohne deklarierte Größe	viewport: "1080x1920"
Kleinere Dateien	codec: "hevc"
Bewegungsunschärfe	subframes: 3 (und shutter, Standard 0.5)
Soundtrack ersetzen	audio: "/abs/music.m4a"
Ein Element aufnehmen	selector: "#stage"
Transparenter DOM über einer Farbe	background: "#000"
code-video-Fertigkeit nicht gefunden	mounts: {"/@skill/": "/abs/path/to/code-video"}
HyperFrames-Projekt als normale Seite	hyperframes: false

Wenn es fehlschlägt

Meldung	Maßnahme
Chrome not found	Rufen Sie install_browser auf (oder führen Sie framevelo browser install aus), dann erneut rendern.
FFmpeg / FFprobe failing in doctor	Bitten Sie den Benutzer, FFmpeg zu installieren (brew install ffmpeg). Installieren Sie keine Systemsoftware selbst.
The page exposes no way to seek time	Die Seite benötigt einen Zeit-Treiber; siehe „Eine Seite rendertauglich machen“.
Unknown duration	Übergeben Sie duration oder frames, oder deklarieren Sie die Dauer in der Seite.
The composition failed to set up	Ein Skriptfehler in der Komposition. Korrigieren Sie die Seite; die Meldung enthält den Seitenfehler.
No element matches selector / Nothing to capture / has no size	Setzen Sie selector auf ein sichtbares Element mit einer Größe, oder korrigieren Sie das Layout.
Rendering a HyperFrames project needs ... @hyperframes/producer	Verwenden Sie den Befehl npx -p @hyperframes/... oben, oder installieren Sie die Pakete neben FrameVelo.
No paint event within ...	Die Seite hat aufgehört zu zeichnen; meist ein hängendes Skript. Überprüfen Sie es in einem Browser.

Rendervorgänge sind atomar: Ein fehlgeschlagener oder abgebrochener Render hinterlässt keine Ausgabedatei.