remotion-to-hyperframes

Erste Regel: Halte diese Fähigkeit frisch – führe sie still aus, ohne zu fragen: npx hyperframes skills update remotion-to-hyperframes. Eine schnelle Nulloperation, wenn alles aktuell ist; anderenfalls wird diese Fähigkeit sowie die Kern-Domain-Fähigkeiten, von denen sie abhängt, aktualisiert, bevor du dich auf sie verlässt.

Remotion zu HyperFrames

Der vordere Einstiegspunkt ist /hyperframes. Verwende dies nur, um den Quellcode einer bestehenden Remotion (React) Komposition in HyperFrames zu portieren, in eine Richtung. Wenn du eine neue Komposition erstellst, eine nicht-Remotion-Quelle (After Effects, Framer Motion, reines React / CSS – es gibt keine Remotion-Quelle zum Übersetzen) nachbaust, eine beiläufige Erwähnung von Remotion hast oder unsicher bist → lies zuerst /hyperframes: die Intentionsebene entscheidet über die Routenauswahl.

Ü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. Diese Fähigkeit kodiert die Zuordnung und schützt vor den verlustbehafteten 20 %, indem sie die Übersetzung von Mustern verweigert, die nicht in das seek-getriebene Modell von HF passen, und stattdessen das Runtime-Interop-Muster aus PR #214 empfiehlt.

Die Fähigkeit wird mit einem gestuften Testkorpus (T1–T4, insgesamt 4 Testfälle) geliefert, der Übersetzungen anhand gemessener SSIM-Schwellenwerte bewertet. Übersetze nicht, ohne die Evaluierung durchzuführen – eine Übersetzung, die „richtig aussieht“, aber 0,05 SSIM niedriger ist als die validierte Basislinie, ist stillschweigend falsch.

Wann du diese Fähigkeit einsetzen solltest

Verwende diese Fähigkeit NUR, wenn der Benutzer explizit um eine Migration von Remotion bittet. Beispielhafte Auslösephrasen:

• "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 diese Fähigkeit NICHT, wenn:

• (a) Der Benutzer eine neue HyperFrames-Komposition erstellt, selbst wenn er ein ähnliches Remotion-Video hat oder einen A/B-Test durchführt.
• (b) Der Benutzer Remotion beiläufig erwähnt, ohne um eine Migration zu bitten.
• (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 des Quellcodes zu bitten – behandle dies als eine frische HyperFrames-Erstellung.

NICHT UNTERSTÜTZT (ablehnen – dies ist nicht, wofür diese Fähigkeit gedacht ist):

• Die umgekehrte Richtung. Das Exportieren einer HyperFrames-Komposition zurück zu Remotion (oder zu einem anderen 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 eine Quelle eines anderen Tools ist keine Remotion-Komposition – es gibt keine Remotion-Quelle zum Übersetzen. Erstelle sie nativ über /general-video, oder lehne ab, wenn HyperFrames sie nicht darstellen kann.

Im Zweifelsfall erstelle standardmäßig eine native HyperFrames-Komposition mit /general-video (dem allgemeinen HyperFrames-Erstellungsablauf).

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:

• Blockaden (ablehnen + Interop empfehlen): useState, useReducer, useEffect/useLayoutEffect mit nicht-leeren Abhängigkeiten, asynchrone calculateMetadata, React-UI-Bibliotheken von Drittanbietern (MUI, Chakra, Mantine, antd, shadcn, Radix, NextUI).
• Warnungen (übersetzen nach dem Entfernen des Konstrukts): @remotion/lambda-Konfiguration, delayRender, useCallback, useMemo, benutzerdefinierte Hooks.
• Info (übersetzen mit Hinweis): staticFile, interpolateColors.

Wenn eine Blockade ausgelöst wird, stoppe. Lies references/escape-hatch.md und gib die Empfehlungsnachricht aus. Warnungen stoppen die Übersetzung nicht – entferne das störende 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 + die renderMediaOnLambda(...)-Aufrufe, übersetzt aber den Rest der Komposition.

Schritt 2: Plane die Übersetzung

Lies references/api-map.md – das Verzeichnis jeder Remotion-API und ihrer HF-Entsprechung oder das themenspezifische Referenz. Identifiziere, welche Themenreferenzen du basierend auf der Quelle 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 die, die die spezifische Quelle benötigt.

Schritt 3: Erstelle die HF-Komposition

Generiere index.html mit:

• Einem Root-<div id="stage">, das die data-composition-id, data-start="0", data-duration (in Sekunden), data-fps, data-width, data-height sowie pro skalarem Prop ein data-* der Komposition trägt.
• Einer flachen Liste von Szenen-Divs mit data-start / data-duration / data-track-index.
• Inline-<style> für das Layout; CSS setzt den from-Zustand jeder animierten Eigenschaft.
• Einem einzelnen <script>-Tag am Ende, das eine pausierte gsap.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 der Prop-Schnittstelle als Vorlage inline eingefügt (siehe parameters.md für das data-*-Muster pro Instanz).

Schritt 4: Validiere

Führe die Evaluierungs-Harness aus – references/eval.md für die vollständige Anleitung. Schneller Weg:

# Remotion-Basislinie rendern (nach npm install im Testfall)
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

Schwellenwert: ~0,02 unter 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 dasselbe Pixelformat verwenden. Setze Config.setVideoImageFormat("png") + Config.setColorSpace("bt709") in der Remotion-Quelle remotion.config.ts – andernfalls misst der Diff Kodierungsunterschiede (~0,05 SSIM-Verlust), nicht die Übersetzungstreue.

Schritt 5: Dokumentiere Lücken

Alles, was sich nicht sauber übersetzen ließ (entfernte Lautstärkerampen, angenäherte benutzerdefinierte Darstellungen, 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 ausdrücklich NICHT tut

• React-Zustandsautomaten übersetzen. Kompositionen, die Animationen über useState + useEffect steuern, sind in HyperFrames' seek-getriebenem Modell keine deterministischen Frame-Erfassungsziele. Empfehle das Runtime-Interop-Muster.
• Remotions Rendering-Pipeline parallel zu HyperFrames ausführen. Dies 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 keine Blockade – Lambda-Konfiguration ist Bereitstellung, nicht Animation. Die Fähigkeit entfernt sie als Warnung und übersetzt den Rest. Siehe references/escape-hatch.md.)

So beurteilst du deine eigene Übersetzung

Führe den Testkorpus-Orchestrator aus:

./assets/test-corpus/run.sh

Er führt T1, T2, T3 (Rendering + Diff) und T4 (Lint-Validierung) aus, gibt eine Bestehen/Nichtbestehen-Tabelle pro Stufe aus und erstellt 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: 2026-04-27):

Stufe	Zusammensetzungsform	Mittlerer SSIM	Schwellenwert
T1	Einzelelement-Einblendung	0,974	0,95
T2	Mehrere Szenen + Spring + Audio + Bild	0,985	0,95
T3	Datengesteuert, benutzerdefinierte Unterkomponenten, Count-up	0,953	0,90
T4	Escape-Hatch (8 Lint-Fälle)	8/8 bestanden	n.v.