Was macht Remotion zu HyperFrames?
Überblick
Übersetzt 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. Dieses Skill kodiert die Zuordnung und schützt vor den verlustbehafteten 20%, indem es die Übersetzung von Mustern verweigert, die nicht in HFs suchbasiertes Modell passen, und stattdessen das Laufzeit-Interop-Muster aus PR #214 empfiehlt.
Das Skill wird mit einem abgestuften Testkorpus (T1–T4, 4 Fixtures insgesamt) ausgeliefert, der Ü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 liegt, ist stillschweigend falsch.
Wann verwenden
Verwende dieses Skill NUR, wenn der Benutzer explizit um eine Migration von Remotion bittet. Beispiel-Trigger-Phrasen:
- „port my Remotion project to HyperFrames“
- „convert this Remotion code to HyperFrames“
- „migrate from Remotion“
- „translate this Remotion comp“
- „rewrite this as HyperFrames HTML“
Verwende dieses Skill 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 eine Migration zu fordern.
- (c) Der Benutzer Remotion-Code als Referenzmaterial teilt, anstatt eine Übersetzung zu verlangen.
- (d) Der Benutzer nach „dem gleichen Video wie mein Remotion-Eines“ fragt, ohne explizit um eine Migration des Quellcodes zu bitten – behandle dies als neue HyperFrames-Erstellung.
Im Zweifelsfall verwende stattdessen das hyperframes-Skill zum Erstellen einer nativen HyperFrames-Komposition.
Arbeitsablauf
Schritt 1: Lint der Quelle
Führe scripts/lint_source.py über das Remotion-Quellverzeichnis aus. Der Lint erkennt Muster, die nicht sauber übersetzt werden können:
- Blocker (ablehnen + Interop empfehlen):
useState,useReducer,useEffect/useLayoutEffectmit nicht-leeren Abhängigkeiten, asynchronescalculateMetadata, React-UI-Bibliotheken von Drittanbietern (MUI, Chakra, Mantine, antd, shadcn, Radix, NextUI). - Warnungen (nach Verwerfen des Konstrukts übersetzen):
@remotion/lambda-Konfiguration,delayRender,useCallback,useMemo, benutzerdefinierte Hooks. - Info (mit Notiz übersetzen):
staticFile,interpolateColors.
Wenn ein Blocker ausgelöst wird, stoppe. Lese references/escape-hatch.md und gib die Empfehlungsnachricht aus. Warnungen stoppen die Übersetzung nicht – verwerfe das störende Konstrukt in Schritt 3 und notiere die Lücke in TRANSLATION_NOTES.md. Die @remotion/lambda-Konfiguration ist der kanonische Warnfall: Das Skill verwirft den Import + renderMediaOnLambda(...)-Aufrufe, übersetzt aber den Rest der Komposition.
Schritt 2: Übersetzung planen
Lese references/api-map.md – das Verzeichnis jeder Remotion-API und ihres HF-Äquivalents oder themenspezifischen Referenz. Identifiziere, welche Themenreferenzen du basierend auf der Quelle 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 das, was die spezifische Quelle benötigt.
Schritt 3: HF-Komposition generieren
Erzeuge index.html mit:
- Wurzel-
<div id="stage">, das diedata-composition-id,data-start="0",data-duration(in Sekunden),data-fps,data-width,data-heightder Komposition sowie eindata-*-Attribut pro skalarem Prop trägt. - Eine flache Liste von Szenen-
divs mitdata-start/data-duration/data-track-index. - Inline-
<style>für Layout; CSS setzt denfrom-Zustand jeder animierten Eigenschaft. - Ein einzelnes
<script>-Tag am 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 HFs Laufzeit.
Benutzerdefinierte React-Subkomponenten werden als wiederholtes HTML mit der Prop-Schnittstelle als Vorlage inline eingefügt (siehe parameters.md für das pro-Instanz data-*-Muster).
Schritt 4: Validieren
Führe die Auswertungsharness aus – references/eval.md für die vollständige Anleitung. Schneller Pfad:
# Remotion-Baseline 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 eval.mds Tabelle validierter Schwellenwerte). 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.
Wichtig: Beide Renderings müssen dasselbe Pixelformat verwenden. Setze Config.setVideoImageFormat("png") + Config.setColorSpace("bt709") in der Remotion-Quelle remotion.config.ts – sonst 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ß (fallengelassene 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 dieses Skill explizit NICHT tut
- React-Zustandsmaschinen übersetzen. Kompositionen, die Animationen über
useState+useEffectsteuern, sind in HyperFrames' suchbasiertem Modell keine deterministischen Frame-Capture-Ziele. Empfehle das Laufzeit-Interop-Muster. - Remotions Render-Pipeline neben HyperFrames ausführen. Das ist das Laufzeit-Interop-Muster aus PR #214 – eine separate Lösung für Kompositionen, die das Lint dieses Skills nicht bestehen.
(@remotion/lambda ist kein Blocker – Lambda-Konfiguration betrifft Deployment, nicht Animation. Das Skill 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
Er führt T1, T2, T3 (Rendern + Diff) und T4 (Lint-Validierung) aus, gibt eine pro-Stufe Bestehen/Nichtbestehen-Tabelle aus und erzeugt einen aggregierten JSON-Bericht. Verwende dies, um zu überprüfen, ob das Skill bei einem sauberen Checkout Ende-zu-Ende funktioniert – und als Regressionstest nach Bearbeitung 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/a |