Remotion zu HyperFrames
Bestätige den Weg, bevor du baust. Verwende dies nur, um eine vorhandene Remotion (React)-Kompositionsquelle nach HyperFrames zu portieren. Erstellung einer neuen Komposition (auch wenn sie von einem Remotion-Video inspiriert ist) → die Erstellungs-Workflows /
/general-video. Nicht im Bereich (Einweg, nur Remotion): kein Rückwärtsexport (HyperFrames → Remotion oder irgendein Framework), und eine nicht-Remotion-Quelle (After Effects, Framer Motion, reines React/CSS) hat keine zu übersetzende Remotion-Quelle → neu erstellen über/general-video. Unsicher oder nur eine beiläufige Remotion-Erwähnung? Lies zuerst/hyperframes.
Übersicht
Übersetze Remotion (React-basierte) Videokompositionen in HyperFrames (HTML + GSAP)-Kompositionen. Die meisten Remotion-Idiome haben direkte HyperFrames-Äquivalente — die Übersetzung ist für ~80% typischer Kompositionen mechanisch. Diese Fähigkeit kodiert die Zuordnung und schützt vor den verlustbehafteten 20%, indem sie sich weigert, Muster zu übersetzen, die nicht in HFs seek-gesteuertes Modell passen, und stattdessen das Laufzeit-Interop-Muster aus PR #214 empfiehlt.
Die Fähigkeit wird mit einem gestaffelten Testkorpus (T1–T4, insgesamt 4 Fixtures) ausgeliefert, der Übersetzungen gegen gemessene SSIM-Schwellenwerte bewertet. Übersetze nicht, ohne die Auswertung laufen zu lassen — eine Übersetzung, die "richtig aussieht", aber 0,05 SSIM niedriger als die validierte Basislinie rendert, ist stillschweigend falsch.
Wann verwenden
Verwende diese Fähigkeit NUR, wenn der Benutzer explizit darum bittet, von Remotion zu migrieren. Beispiel-Trigger-Phrasen:
- "portiere mein Remotion-Projekt zu HyperFrames"
- "konvertiere diesen Remotion-Code zu HyperFrames"
- "migriere von Remotion"
- "übersetze diese Remotion-Komponente"
- "schreibe dies als HyperFrames HTML um"
Verwende diese Fähigkeit NICHT, wenn:
- (a) Der Benutzer eine neue HyperFrames-Komposition erstellt, selbst wenn sie ein ähnliches Remotion-Video haben oder A/B-testen.
- (b) Der Benutzer Remotion beiläufig erwähnt, ohne eine Migration anzufordern.
- (c) Der Benutzer Remotion-Code als Referenzmaterial teilt, anstatt um eine Übersetzung zu bitten.
- (d) Der Benutzer nach "dem gleichen Video wie mein Remotion-Video" fragt, ohne explizit um eine Migration der Quelle zu bitten — behandle dies als einen neuen HyperFrames-Build.
NICHT UNTERSTÜTZT (ablehnen — das ist nicht, was diese Fähigkeit tut):
- Die umgekehrte Richtung. Das Exportieren einer HyperFrames-Komposition zurück nach Remotion (oder in ein anderes Framework) ist kein Workflow — die Übersetzung ist nur Remotion → HyperFrames. Sage das klar.
- Nicht-Remotion-Quellen. Ein After Effects-Projekt (
.aep), eine Framer Motion / reines React / CSS-Animation oder eine andere Tool-Quelle ist keine Remotion-Komposition — es gibt keine zu übersetzende Remotion-Quelle. Erstelle sie nativ über/general-videoneu oder lehne ab, wenn HyperFrames sie nicht darstellen kann.
Im Zweifelsfall erstelle stattdessen eine native HyperFrames-Komposition mit /general-video (dem allgemeinen HyperFrames-Erstellungs-Workflow).
Workflow
Schritt 1: Lint der Quelle
Führe scripts/lint_source.py über das Remotion-Quellverzeichnis aus. Der Lint erkennt Muster, die sich nicht sauber übersetzen lassen:
- Blocker (ablehnen + Interop empfehlen):
useState,useReducer,useEffect/useLayoutEffectmit nicht-leeren Dependencies, asynchronescalculateMetadata, React-UI-Bibliotheken von Drittanbietern (MUI, Chakra, Mantine, antd, shadcn, Radix, NextUI). - Warnungen (übersetzen nach Entfernen des Konstrukts):
@remotion/lambda-Konfiguration,delayRender,useCallback,useMemo, benutzerdefinierte Hooks. - Info (mit Hinweis übersetzen):
staticFile,interpolateColors.
Wenn ein Blocker ausgelöst wird, stoppe. Lese references/escape-hatch.md und zeige die Empfehlungsnachricht an. Warnungen stoppen die Übersetzung nicht — entferne das problematische Konstrukt in Schritt 3 und notiere die Lücke in TRANSLATION_NOTES.md. @remotion/lambda-Konfiguration ist der kanonische Warnungsfall: Die Fähigkeit entfernt den Import + renderMediaOnLambda(...)-Aufrufe, übersetzt aber den Rest der Komposition.
Schritt 2: Planung der Übersetzung
Lese references/api-map.md — den Index jeder Remotion-API und ihres HF-Äquivalents oder themenspezifischen Referenz. Identifiziere, welche Themenreferenzen du basierend auf dem, was die Quelle verwendet, benötigst:
| Quelle enthält | Referenz laden |
|---|---|
Composition, defaultProps, schema, calculateMetadata | parameters.md |
Sequence, Series, Loop, AbsoluteFill, Freeze | sequencing.md |
useCurrentFrame, interpolate, spring, Easing, interpolateColors | timing.md |
Audio, Video, Img, IFrame, staticFile, delayRender | media.md |
TransitionSeries, @remotion/transitions | transitions.md |
@remotion/lottie | lottie.md |
@remotion/google-fonts/<Family>, Font.loadFont, @font-face | fonts.md |
Lade nicht alle — lade nur, was die spezifische Quelle benötigt.
Schritt 3: Generiere die HF-Komposition
Erzeuge index.html mit:
- Root
<div id="stage">mit dendata-composition-id,data-start="0",data-duration(in Sekunden),data-fps,data-width,data-heightdes Kompositions sowie einemdata-*pro skalarer Eigenschaft. - Einer flachen Liste von Szenen-Divs mit
data-start/data-duration/data-track-index. - Inline
<style>für Layout; CSS setzt denfrom-Zustand jeder animierten Eigenschaft. - Einem einzelnen
<script>-Tag am Ende, das eine pausiertegsap.timeline({paused: true})enthält. JedeuseCurrentFrame()-Ableitung von Remotion wird zu einem Tween auf dieser Timeline zum richtigen Offset. window.__timelines["<composition-id>"] = tl;registriert die Timeline bei der HF-Laufzeit.
Benutzerdefinierte React-Unterkomponenten werden als wiederholtes HTML unter Verwendung des Prop-Interfaces als Vorlage inline eingefügt (siehe parameters.md für das pro-Instanz data-*-Muster).
Schritt 4: Validierung
Führe das Eval-Harness aus — references/eval.md für die vollständige Anleitung. Schneller Pfad:
# Remotion-Basislinie rendern (nach npm install im Fixture)
cd remotion-src && npx remotion render <CompositionId> out/baseline.mp4
# HF-Übersetzung rendern
cd ../hf-src && npx hyperframes render --output ../hf.mp4
# SSIM-Diff
../../scripts/render_diff.sh ./remotion-src/out/baseline.mp4 ./hf.mp4 ./diff
Schwellenwert: ~0,02 unter p05 der Komplexitätsstufe der Quelle (siehe die validierten Schwellenwerttabelle in eval.md). Wenn der Diff fehlschlägt, führe scripts/frame_strip.sh aus, um zu sehen, welche Frames abgewichen sind, und lies dann die entsprechende Timing-/Sequenzierungs-/Medienreferenz erneut.
Kritisch: Beide Renderings müssen ein übereinstimmendes Pixelformat verwenden. Setze Config.setVideoImageFormat("png") + Config.setColorSpace("bt709") in der Remotion-Quelle remotion.config.ts — andernfalls misst der Diff Encoder-Unterschiede (~0,05 SSIM-Einbuße), nicht die Übersetzungstreue.
Schritt 5: Lücken dokumentieren
Alles, was sich nicht sauber übersetzen ließ (verworfene Lautstärkerampen, approximierte benutzerdefinierte Präsentationen, substituierte Schriftarten), erhält eine TRANSLATION_NOTES.md, die neben der HF-Ausgabe geschrieben wird. Siehe references/limitations.md für das Format.
Was diese Fähigkeit explizit NICHT tut
- Übersetze React-Zustandsmaschinen. Kompositionen, die Animationen über
useState+useEffectsteuern, sind keine deterministischen Frame-Capture-Ziele in HFs seek-gesteuertem Modell. Empfehle das Laufzeit-Interop-Muster. - Führe die Remotion-Render-Pipeline neben HyperFrames aus. Das ist das Laufzeit-Interop-Muster aus PR #214 — eine separate Lösung für Kompositionen, die den Lint dieser Fähigkeit nicht bestehen.
(@remotion/lambda ist kein Blocker — Lambda-Konfiguration ist Deployment, nicht Animation. Die Fähigkeit verwirft es als Warnung und übersetzt den Rest. Siehe references/escape-hatch.md.)
Wie du deine eigene Übersetzung bewerten kannst
Führe den Testkorpus-Orchestrator aus:
./assets/test-corpus/run.sh
Dies führt T1, T2, T3 (Render + Diff) und T4 (Lint-Validierung) aus, gibt eine Tabelle mit Bestehen/Nichtbestehen pro Stufe aus und erzeugt einen aggregierten JSON-Bericht. Verwende dies, um zu überprüfen, ob die Fähigkeit auf einem sauberen Checkout durchgängig funktioniert — und als Regressionstest nach der Bearbeitung einer Referenz.
Validierte Basislinie (Stand 27.04.2026):
| Stufe | Kompositionsform | Mittlerer SSIM | Schwellenwert |
|---|---|---|---|
| T1 | Einzelelement-Einblendung | 0,974 | 0,95 |
| T2 | Mehrere Szenen + Spring + Audio + Bild | 0,985 | 0,95 |
| T3 | Datengetrieben, benutzerdefinierte Unterkomponenten, Count-up | 0,953 | 0,90 |
| T4 | Escape-Hatch (8 Lint-Fälle) | 8/8 bestanden | n/v |