Was macht Remotion nach HyperFrames?
Übersicht
Übersetze Remotion (React-basierte) Videokompositionen in HyperFrames (HTML + GSAP)-Kompositionen. Die meisten Remotion-Idiome haben direkte Entsprechungen in HyperFrames – die Übersetzung ist für ~80% typischer Kompositionen mechanisch. Dieses Skill kodiert die Zuordnung und schützt vor den verlustbehafteten 20%, indem es sich weigert, Muster zu übersetzen, die nicht in HFs suchlaufgesteuertes Modell passen, und stattdessen das Runtime-Interop-Muster aus PR #214 empfiehlt.
Das Skill wird mit einem gestaffelten Testkorpus (T1–T4, 4 Testfälle gesamt) ausgeliefert, der Übersetzungen anhand gemessener SSIM-Schwellenwerte bewertet. Nicht übersetzen, ohne die Auswertung durchzuführen — eine Übersetzung, die „gut aussieht“ aber 0,05 SSIM unter der validierten Basislinie liegt, ist stillschweigend falsch.
Wann verwenden
Verwende dieses Skill NUR, wenn der Benutzer explizit darum bittet, von Remotion zu migrieren. Beispielauslöser:
- „portiere mein Remotion-Projekt zu HyperFrames“
- „konvertiere diesen Remotion-Code zu HyperFrames“
- „migriere von Remotion“
- „übersetze diese Remotion-Komposition“
- „schreibe dies als HyperFrames HTML um“
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 verlangen.
- (c) Der Benutzer Remotion-Code als Referenzmaterial teilt, anstatt eine Übersetzung zu verlangen.
- (d) Der Benutzer nach „demselben Video wie mein Remotion-Video“ fragt, ohne explizit um eine Migration der Quelle zu bitten – behandle dies als eine neue HyperFrames-Komposition.
Bei Zweifeln standardmäßig das native hyperframes-Skill zum Erstellen einer HyperFrames-Komposition verwenden.
Arbeitsablauf
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 Abhängigkeiten, asynccalculateMetadata, Drittanbieter-React-UI-Bibliotheken (MUI, Chakra, Mantine, antd, shadcn, Radix, NextUI). - Warnungen (übersetzen nach Verwerfen des Konstrukts):
@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 Warnungsfall: Das Skill verwirft den Import + die Aufrufe von renderMediaOnLambda(...), übersetzt aber den Rest der Komposition.
Schritt 2: Plane die Übersetzung
Lese references/api-map.md – das Verzeichnis jeder Remotion-API und ihrer HF-Entsprechung oder themenspezifischen Referenz. Identifiziere, welche Themenreferenzen du basierend auf dem, was die Quelle verwendet, benötigst:
| Quelle enthält | Lade Referenz |
|---|---|
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: Erzeuge die HF-Komposition
Erzeuge index.html mit:
- Einem Wurzel-Element
<div id="stage">, das diedata-composition-id,data-start="0",data-duration(in Sekunden),data-fps,data-width,data-heightsowie eindata-*pro skalarem Prop trägt. - Einer flachen Liste von Szenen-
<div>s mitdata-start/data-duration/data-track-index. - Inline
<style>für das Layout; CSS setzt denfrom-Zustand jeder animierten Eigenschaft. - Einem einzelnen
<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 der HF-Laufzeitumgebung.
Benutzerdefinierte React-Unterkomponenten werden als wiederholtes HTML mit der Props-Schnittstelle als Vorlage inline eingefügt (siehe parameters.md für das data-*-Muster pro Instanz).
Schritt 4: Validieren
Führe das Evaluierungs-Harness aus – references/eval.md für die vollständige Anleitung. Schneller Pfad:
# Rendere die Remotion-Basislinie (nach npm install im Testfall)
cd remotion-src && npx remotion render <CompositionId> out/baseline.mp4
# Rendere die HF-Übersetzung
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-/Medien-Referenz erneut.
Kritisch: Beide Renderings müssen dasselbe Pixelformat verwenden. Setze Config.setVideoImageFormat("png") + Config.setColorSpace("bt709") in der Remotion-Quelle in remotion.config.ts – sonst misst der Diff Encoder-Unterschiede (~0,05 SSIM-Verlust) statt Übersetzungstreue.
Schritt 5: Lücken dokumentieren
Alles, das nicht sauber übersetzt werden konnte (verworfene Lautstärke-Rampen, 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
- Übersetze keine React-Zustandsmaschinen. Kompositionen, die Animationen über
useState+useEffectsteuern, sind in HyperFrames' suchlaufgesteuertem Modell keine deterministischen Frame-Capture-Ziele. Empfehle das Runtime-Interop-Muster. - Führe Remotions Rendering-Pipeline nicht neben HyperFrames aus. Das ist das Runtime-Interop-Muster aus PR #214 – eine separate Lösung für Kompositionen, die den Lint dieses Skills nicht bestehen.
(@remotion/lambda ist kein Blocker – Lambda-Konfiguration ist Deployment, nicht Animation. Das Skill verwirft 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 Bestanden/Nicht-Bestanden-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 der Bearbeitung einer Referenz.
Validierte Basislinie (Stand 2026-04-27):
| Stufe | Form der Komposition | Mittlerer SSIM | Schwellenwert |
|---|---|---|---|
| T1 | Einzelelement-Fade-in | 0,974 | 0,95 |
| T2 | Mehrere Szenen + Spring + Audio + Bild | 0,985 | 0,95 |
| T3 | Datengesteuert, benutzerdefinierte Unterkomp. | 0,953 | 0,90 |
| T4 | Escape-Luke (8 Lint-Fälle) | 8/8 bestanden | n.v. |