Remotion nach HyperFrames
Bestätigen Sie den Weg, bevor Sie bauen. Verwenden Sie dies nur, um den Quellcode einer bestehenden Remotion (React)-Komposition in HyperFrames zu portieren. Bei der Erstellung einer neuen Komposition (auch wenn sie von einem Remotion-Video inspiriert ist) → die Erstellungs-Workflows
/general-video. Nicht im Umfang (Einweg, 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 zu übersetzen → Neu erstellen über/general-video. Unsicher, oder nur eine beiläufige Erwähnung von Remotion? Lesen Sie zuerst/hyperframes.
Überblick
Übersetzen Sie Remotion (React-basierte) Videokompositionen in HyperFrames (HTML + GSAP)-Kompositionen. Die meisten Remotion-Idiome haben direkte HyperFrames-Entsprechungen – die Übersetzung ist mechanisch für ~80% der typischen Kompositionen. Diese Fähigkeit kodiert die Abbildung und schützt gegen die verlustbehafteten 20%, indem sie sich weigert, Muster zu übersetzen, die nicht in HFs seek-getriebenes Modell passen, und stattdessen das Laufzeit-Interop-Muster aus PR #214 empfiehlt.
Die Fähigkeit wird mit einem abgestuften Testkorpus (T1–T4, insgesamt 4 Fixtures) ausgeliefert, das Übersetzungen anhand gemessener SSIM-Schwellenwerte bewertet. Übersetzen Sie nicht ohne die Auswertung laufen zu lassen – eine Übersetzung, die „richtig aussieht“, aber 0,05 SSIM niedriger als die validierte Basislinie ist, ist stillschweigend falsch.
Wann verwenden
Verwenden Sie diese Fähigkeit NUR, wenn der Benutzer explizit eine Migration von Remotion verlangt. 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“
Verwenden Sie 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 nach einer Migration zu fragen.
- (c) Der Benutzer Remotion-Code als Referenzmaterial teilt, nicht aber eine Übersetzung verlangt.
- (d) Der Benutzer nach „dem gleichen Video wie mein Remotion-Video“ fragt, ohne explizit die Quelle migrieren zu wollen – behandeln Sie dies als neuen HyperFrames-Build.
NICHT UNTERSTÜTZT (ablehnen – dies ist nicht der Zweck dieser Fähigkeit):
- 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. Sagen Sie dies deutlich.
- Nicht-Remotion-Quellen. Ein After Effects-Projekt (
.aep), eine Framer Motion / reine React / CSS-Animation oder eine andere Werkzeug-Quelle ist keine Remotion-Komposition – es gibt keine Remotion-Quelle zu übersetzen. Erstellen Sie sie nativ über/general-videoneu, oder lehnen Sie ab, wenn HyperFrames es nicht darstellen kann.
Im Zweifel standardmäßig nativ über /general-video (den allgemeinen HyperFrames-Erstellungs-Workflow) eine HyperFrames-Komposition erstellen.
Workflow
Schritt 1: Quellcode prüfen
Führen Sie scripts/lint_source.py über das Remotion-Quellverzeichnis aus. Der Linter erkennt Muster, die nicht sauber übersetzt werden können:
- Blocker (ablehnen + Interop empfehlen):
useState,useReducer,useEffect/useLayoutEffectmit nicht-leeren Abhängigkeiten, asynccalculateMetadata, dritte 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 auslöst, stoppen. Lesen Sie references/escape-hatch.md und geben Sie die Empfehlungsnachricht aus. Warnungen stoppen die Übersetzung nicht – entfernen Sie das anstößige Konstrukt in Schritt 3 und notieren Sie die Lücke in TRANSLATION_NOTES.md. Die @remotion/lambda-Konfiguration ist der kanonische Warnfall: Die Fähigkeit entfernt den Import + renderMediaOnLambda(...)-Aufrufe, übersetzt aber den Rest der Komposition.
Schritt 2: Übersetzung planen
Lesen Sie references/api-map.md – das Verzeichnis jeder Remotion-API und ihrer HF-Entsprechung oder des themenspezifischen Referenzdokuments. Identifizieren Sie, welche Themenreferenzen Sie benötigen, basierend darauf, was die Quelle verwendet:
| 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 |
Laden Sie nicht alle – laden Sie nur, was die spezifische Quelle benötigt.
Schritt 3: HF-Komposition erstellen
Erzeugen Sie index.html mit:
- Einem Wurzel-
<div id="stage">, das diedata-composition-id,data-start="0",data-duration(in Sekunden),data-fps,data-width,data-heightder Komposition sowie eindata-*pro Skalar-Prop trägt. - 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 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-Unterkomponenten werden als wiederholtes HTML unter Verwendung des Prop-Interfaces als Vorlage inline eingesetzt (siehe parameters.md für das data-*-Pro-Instanz-Muster).
Schritt 4: Validierung
Führen Sie die Evaluierungs-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 --skill=remotion-to-hyperframes --output ../hf.mp4
# SSIM-Diff
../../scripts/render_diff.sh ./remotion-src/out/baseline.mp4 ./hf.mp4 ./diff
Schwellwert: ~0,02 unter p05 der Komplexitätsstufe der Quelle (siehe die validierte Schwellwerttabelle in eval.md). Wenn der Diff fehlschlägt, führen Sie scripts/frame_strip.sh aus, um zu sehen, welche Frames abweichen, und lesen Sie dann die entsprechende Timing-/Sequencing-/Media-Referenz erneut.
Kritisch: Beide Renderings müssen das gleiche Pixelformat verwenden. Setzen Sie Config.setVideoImageFormat("png") + Config.setColorSpace("bt709") in der Remotion-Quelle remotion.config.ts – sonst misst der Diff Encoder-Unterschiede (~0,05 SSIM-Abzug), nicht die Übersetzungstreue.
Schritt 5: Lücken dokumentieren
Alles, was nicht sauber übersetzt wurde (entfernte Volume-Rampen, approximierte benutzerdefinierte Präsentationen, ersetzte Schriftarten) wird in einer TRANSLATION_NOTES.md neben der HF-Ausgabe festgehalten. Siehe references/limitations.md für das Format.
Was diese Fähigkeit ausdrücklich NICHT tut
- React-Zustandsmaschinen übersetzen. Kompositionen, die Animationen über
useState+useEffectsteuern, sind keine deterministischen Frame-Capture-Ziele im seek-getriebenen Modell von HyperFrames. Empfehlen Sie 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 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.)
So bewerten Sie Ihre eigene Übersetzung
Führen Sie den Testkorpus-Orchestrator aus:
./assets/test-corpus/run.sh
Er führt T1, T2, T3 (Rendern + Diff) und T4 (Lint-Validierung) aus, gibt eine Bestanden/Nicht-Bestanden-Tabelle pro Stufe aus und erzeugt einen aggregierten JSON-Bericht. Verwenden Sie dies, um zu überprüfen, ob die Fähigkeit auf einem sauberen Checkout Ende-zu-Ende funktioniert – und als Regressionsprüfung nach der Bearbeitung einer Referenz.
Validierte Basislinie (Stand: 2026-04-27):
| Stufe | Kompositionsform | Mittlerer SSIM | Schwellwert |
|---|---|---|---|
| T1 | Einzelelement-Einblendung | 0,974 | 0,95 |
| T2 | Mehrere Szenen + Spring + Audio + Bild | 0,985 | 0,95 |
| T3 | Datengesteuert, benutzerdefinierte Unterkomponenten, Zähler | 0,953 | 0,90 |
| T4 | Escape-Hatch (8 Lint-Fälle) | 8/8 pass | n/a |