Remotion zu HyperFrames
Bestätige den Weg, bevor du baust. Verwende dies nur, um eine bestehende Remotion-Komposition (React) nach HyperFrames zu portieren. Eine neue Komposition (auch wenn sie von einem Remotion-Video inspiriert ist) → die Erstellungs-Workflows /
/general-video. Ausgeschlossen (Einbahnstraße, nur Remotion): kein Rückwärtsexport (HyperFrames → Remotion oder ein anderes Framework), und eine Nicht-Remotion-Quelle (After Effects, Framer Motion, reines React/CSS) hat keine Remotion-Quelle zum Übersetzen → neu erstellen via/general-video. Unsicher, oder nur eine beiläufige Erwähnung von Remotion? Lies zuerst/hyperframes.
Überblick
Übersetzt Remotion (React-basierte) Videokompositionen in HyperFrames (HTML + GSAP)-Kompositionen. Die meisten Remotion-Idiome haben direkte Äquivalente in HyperFrames – die Übersetzung ist für ~80% typischer Kompositionen mechanisch. Diese Fähigkeit kodiert die Abbildung und schützt vor den verlustbehafteten 20%, indem sie sich weigert, Muster zu übersetzen, die nicht in HFs seek-basiertes Modell passen, und stattdessen das Runtime-Interop-Muster aus PR #214 empfiehlt.
Die Fähigkeit wird mit einem gestuften Testkorpus (T1–T4, 4 Fixtures insgesamt) ausgeliefert, das Übersetzungen anhand gemessener SSIM-Schwellenwerte bewertet. Übersetze nicht, ohne die Auswertung laufen zu lassen – eine Übersetzung, die „richtig aussieht“, aber 0.05 SSIM niedriger als die validierte Baseline rendert, ist stillschweigend falsch.
Wann verwenden
Verwende diese Fähigkeit NUR, wenn der Benutzer explizit nach Migration von Remotion fragt. Beispiel-Trigger-Phrasen:
- „portiere mein Remotion-Projekt nach HyperFrames“
- „konvertiere diesen Remotion-Code nach HyperFrames“
- „migriere von Remotion“
- „übersetze diese Remotion-Komposition“
- „schreibe dies als HyperFrames-HTML um“
Verwende diese Fähigkeit NICHT, wenn:
- (a) Der Benutzer eine neue HyperFrames-Komposition erstellt, selbst wenn er ein ähnliches Remotion-Video hat oder A/B-testet.
- (b) Der Benutzer Remotion beiläufig erwähnt, ohne nach Migration zu fragen.
- (c) Der Benutzer Remotion-Code als Referenzmaterial teilt, anstatt nach einer Übersetzung zu fragen.
- (d) Der Benutzer nach „dem gleichen Video wie mein Remotion-Video“ fragt, ohne explizit die Quelle migrieren zu wollen – behandle dies als einen neuen HyperFrames-Build.
NICHT UNTERSTÜTZT (ablehnen – das ist nicht, was diese Fähigkeit tut):
- Die Rückwärtsrichtung. Das Exportieren einer HyperFrames-Komposition zurück nach Remotion (oder in ein anderes Framework) ist kein Workflow – die Übersetzung ist nur Remotion → HyperFrames. Sage dies deutlich.
- Nicht-Remotion-Quellen. Ein After Effects-Projekt (
.aep), eine Framer Motion / reines-React/CSS-Animation oder die Quelle eines anderen Tools ist keine Remotion-Komposition – es gibt keine Remotion-Quelle zum Übersetzen. Erstelle sie nativ via/general-videoneu oder lehne ab, wenn HyperFrames sie nicht darstellen kann.
Bei Unsicherheit standardmäßig eine native HyperFrames-Komposition mit /general-video (dem allgemeinen HyperFrames-Erstellungs-Workflow) erstellen.
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, asynccalculateMetadata, Drittanbieter-React-UI-Bibliotheken (MUI, Chakra, Mantine, antd, shadcn, Radix, NextUI). - Warnungen (übersetzen nach Entfernen des Konstrukts):
@remotion/lambda-Konfiguration,delayRender,useCallback,useMemo, benutzerdefinierte Hooks. - Info (übersetzen mit Hinweis):
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 störende Konstrukt in Schritt 3 und notiere die Lücke in TRANSLATION_NOTES.md. Die @remotion/lambda-Konfiguration ist der kanonische Warnungsfall: Die Fähigkeit entfernt den Import + die renderMediaOnLambda(...)-Aufrufe, übersetzt aber den Rest der Komposition.
Schritt 2: Plane die Übersetzung
Lese references/api-map.md – das Verzeichnis 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
Gebe index.html aus mit:
- Einem Root-
<div id="stage">, das diedata-composition-id,data-start="0",data-duration(in Sekunden),data-fps,data-width,data-heightder Komposition trägt, plus eindata-*pro skalarem Prop. - Einer flachen Liste von Szenen-Divs mit
data-start/data-duration/data-track-index. - Inline
<style>für das Layout; CSS setzt denfrom-Zustand jeder animierten Eigenschaft. - Einem einzelnen
<script>-Tag am unteren Ende, das eine pausiertegsap.timeline({paused: true})enthält. Jede Remotion-useCurrentFrame()-Ableitung wird zu einem Tween auf dieser Timeline am richtigen Offset. window.__timelines["<composition-id>"] = tl;registriert die Timeline bei der HF-Laufzeit.
Benutzerdefinierte React-Subkomponenten 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: Validieren
Führe das Evaluierungs-Harness aus – references/eval.md für die vollständige Anleitung. Schneller Pfad:
# Rendere Remotion-Baseline (nach npm install im Fixture)
cd remotion-src && npx remotion render <CompositionId> out/baseline.mp4
# Rendere HF-Übersetzung
cd ../hf-src && npx hyperframes render --skill=remotion-to-hyperframes --output ../hf.mp4
# SSIM-Diff
../../scripts/render_diff.sh ./remotion-src/out/baseline.mp4 ./hf.mp4 ./diff
Schwellenwert: ~0.02 unterhalb p05 der Komplexitätsstufe der Quelle (siehe validierte Schwellenwerttabelle in eval.md). Wenn der Diff fehlschlägt, führe scripts/frame_strip.sh aus, um zu sehen, welche Frames abweichen, und lies dann die entsprechende Timing/Sequencing/Media-Referenz erneut.
Kritisch: Beide Renderings müssen das gleiche Pixelformat verwenden. Setze Config.setVideoImageFormat("png") + Config.setColorSpace("bt709") in der Remotion-Quelle in remotion.config.ts – sonst misst der Diff Kodiererunterschiede (~0.05 SSIM-Abzug), nicht die Übersetzungstreue.
Schritt 5: Dokumentiere Lücken
Alles, was sich nicht sauber übersetzen ließ (weggelassene Lautstärkerampen, angenäherte benutzerdefinierte Präsentationen, ersetzte 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
- React-Statusmaschinen übersetzen. Kompositionen, die Animationen über
useState+useEffectsteuern, sind keine deterministischen Frame-Capture-Ziele in HyperFrames' seek-basiertem Modell. Empfehle das Runtime-Interop-Muster. - Remotions Render-Pipeline neben HyperFrames ausführen. Das ist das Runtime-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 entfernt es als Warnung und übersetzt den Rest. Siehe references/escape-hatch.md.)
Wie du deine eigene Übersetzung bewertest
Führe den Testkorpus-Orchestrator aus:
./assets/test-corpus/run.sh
Er führt T1, T2, T3 (Rendern + Diff) und T4 (Lint-Validierung) aus, gibt eine pro-Stufe Bestehen/Nicht-Bestehen-Tabelle aus und erstellt einen aggregierten JSON-Bericht. Verwende dies, um zu überprüfen, ob die Fähigkeit Ende-zu-Ende auf einem sauberen Checkout funktioniert – und als Regressionstest nach dem Bearbeiten einer Referenz.
Validierte Baseline (Stand: 2026-04-27):
| 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 Subkomponenten, Count-up | 0.953 | 0.90 |
| T4 | Escape-Hatch (8 Lint-Fälle) | 8/8 bestanden | n/v |