Plugin-Installation: Führen Sie vor dem Setup oder Freshness-Befehlen die Plugin-Installationsregeln aus, wenn sich diese Fertigkeit innerhalb eines HyperFrames-Plugins befindet. Bei eigenständigen Installationen gelten die unten stehenden Update-Anweisungen.
Halten Sie diese Fertigkeit zunächst frisch – bestätigen Sie mit dem Benutzer vor dem Ausführen:
npx hyperframes skills update remotion-to-hyperframes. Eine schnelle No-Op, wenn alles aktuell ist; andernfalls aktualisiert es diese Fertigkeit sowie die Kern-Domain-Fertigkeiten, von denen sie abhängt, bevor Sie sich auf sie verlassen.
Remotion zu HyperFrames
Der primäre Einstieg ist
/hyperframes. Verwenden Sie dies nur, um eine bestehende Remotion (React)-Komposition in HyperFrames zu portieren, unidirektional. Erstellen einer neuen Komposition, Neuerstellung aus einer Nicht-Remotion-Quelle (After Effects, Framer Motion, reines React / CSS – es gibt keine zu übersetzende Remotion-Quelle), eine beiläufige Erwähnung von Remotion oder jegliche Unsicherheit → lesen Sie zuerst/hyperframes: die Intent-Ebene trifft alle Routenentscheidungen.
Übersicht
Übersetzen Sie 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. Diese Fertigkeit kodiert die Abbildung und schützt vor den verlustbehafteten 20 %, indem sie sich weigert, Muster zu übersetzen, die nicht in das seek-gesteuerte Modell von HF passen, und stattdessen das Runtime-Interop-Muster aus PR #214 empfiehlt.
Die Fertigkeit wird mit einem gestuften Testkorpus (T1–T4, insgesamt 4 Fixtures) ausgeliefert, der Übersetzungen anhand gemessener SSIM-Schwellenwerte bewertet. Übersetzen Sie nicht, ohne die Auswertung durchzuführen – eine Übersetzung, die „richtig aussieht“, aber 0,05 SSIM niedriger als die validierte Baseline rendert, ist stillschweigend falsch.
Wann verwenden
Verwenden Sie diese Fertigkeit NUR, wenn der Benutzer explizit eine Migration von Remotion anfordert. Beispiel-Auslöserphrasen:
- „Portieren Sie mein Remotion-Projekt zu HyperFrames“
- „Konvertieren Sie diesen Remotion-Code zu HyperFrames“
- „Migrieren Sie von Remotion“
- „Übersetzen Sie diese Remotion-Komposition“
- „Schreiben Sie dies als HyperFrames HTML um“
Verwenden Sie diese Fertigkeit 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 eine Quellmigration zu verlangen – behandeln Sie dies als neuen HyperFrames-Bau.
NICHT UNTERSTÜTZT (ablehnen – das ist nicht der Zweck dieser Fertigkeit):
- 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. Sagen Sie dies deutlich.
- Nicht-Remotion-Quellen. Ein After Effects-Projekt (
.aep), eine Framer Motion / Plain-React / CSS-Animation oder eine Quelle eines anderen Tools ist keine Remotion-Komposition – es gibt keine zu übersetzende Remotion-Quelle. Erstellen Sie es nativ über/general-videoneu, oder lehnen Sie ab, wenn HyperFrames es nicht darstellen kann.
Im Zweifelsfall kehren Sie zu /hyperframes zurück; dessen Intent-Ebene wählt die Route.
Arbeitsablauf
Schritt 1: Linten der Quelle
Führen Sie 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, asynchronecalculateMetadata, React-UI-Bibliotheken von Drittanbietern (MUI, Chakra, Mantine, antd, shadcn, Radix, NextUI). - Warnungen (nach Entfernen des Konstrukts übersetzen):
@remotion/lambda-Konfiguration,delayRender,useCallback,useMemo, benutzerdefinierte Hooks. - Info (mit Hinweis übersetzen):
staticFile,interpolateColors.
Wenn ein Blocker ausgelöst wird, stoppen Sie. Lesen Sie references/escape-hatch.md und zeigen Sie die Empfehlungsnachricht an. 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 Fertigkeit entfernt den Import + renderMediaOnLambda(...)-Aufrufe, übersetzt jedoch den Rest der Komposition.
Schritt 2: Planen der Übersetzung
Lesen Sie references/api-map.md – das Verzeichnis jeder Remotion-API und ihres HF-Äquivalents oder themenspezifischen Verweises. Identifizieren Sie, welche Themenverweise Sie basierend auf der Quelle benötigen:
| 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 das, was die spezifische Quelle benötigt.
Durchsuchen Sie den Live-Katalog nach visuellen Effekten, die die Tabelle nicht abbildet. Wenn die Quelle ein Look verwendet, für den es kein HF-API-Äquivalent gibt – eine Scanline/CRT-Überlagerung, einen Glitch- oder Chromatische-Aberration-Durchlauf, einen Shader-Wipe, eine Filmkorn-Behandlung – führen Sie npx hyperframes catalog --query "<der Effekt, auf Deutsch>" --json aus, bevor Sie ihn von Hand in GSAP schreiben. Die Suche benötigt keine Installation: kein Projekt, kein vorheriges add, kein Konto. Sie durchsucht das gesamte gehostete Register (~400 Blöcke und Komponenten) von jedem Verzeichnis aus, und transitions.md geht diesen Weg bereits für clockWipe() / iris() über npx hyperframes add sdf-iris. Eine echte Komponente ist näher an der Quelle als eine handgemachte Annäherung, sodass sie normalerweise den SSIM erhöht anstatt zu senken – aber der Render-Unterschied in Schritt 4 bleibt der Schiedsrichter. Schreiben Sie den Effekt von Hand, wenn eine Suche nichts Passendes ergibt, und notieren Sie die Ersetzung in TRANSLATION_NOTES.md.
Schritt 3: Generieren der HF-Komposition
Generieren Sie 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-*pro skalarem Prop trägt. - Ein Host-
<div>pro Szene mitdata-composition-src="compositions/<szene>.html"unddata-start/data-duration/data-track-index. Die Wurzel enthält kein verschachteltes Layout. - Eine
compositions/<szene>.htmlpro Szene (eine<template>-Unterkomposition): ihr Inline-<style>für das Layout (CSS setzt denfrom-Zustand jeder animierten Eigenschaft), ihr Markup und eine angehaltenegsap.timeline({paused: true})in der lokalen Zeit der Szene. Jede RemotionuseCurrentFrame()-Ableitung wird zu einem Tween auf dieser Timeline am Offset innerhalb der Szene. window.__timelines["<szenen-id>"] = tl;in jeder Szenendatei undwindow.__timelines["<kompositions-id>"]für die eigene (ggf. leere) Timeline der Wurzel.
Benutzerdefinierte React-Unterkomponenten werden als wiederholtes HTML unter Verwendung der Props-Schnittstelle als Vorlage inline eingefügt (siehe parameters.md für das data-*-Muster pro Instanz).
Schritt 4: Validieren
Führen Sie die Evaluierung durch – references/eval.md für die vollständige Anleitung. Kurzweg:
# 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 --skill=remotion-to-hyperframes --output ../hf.mp4
# SSIM-Unterschied
../../scripts/render_diff.sh ./remotion-src/out/baseline.mp4 ./hf.mp4 ./diff
Schwellenwert: ~0,02 unterhalb des p05 der Komplexitätsstufe der Quelle (siehe validierte Schwellenwerttabelle in eval.md). Wenn der Unterschied fehlschlägt, führen Sie scripts/frame_strip.sh aus, um zu sehen, welche Frames abgewichen sind, und lesen Sie dann die entsprechende Timing-/Sequencing-/Media-Referenz erneut.
Kritisch: Beide Renderings müssen dasselbe Pixelformat verwenden. Setzen Sie Config.setVideoImageFormat("png") + Config.setColorSpace("bt709") in der Remotion-Quelle (remotion.config.ts) – andernfalls misst der Unterschied Encoder-Differenzen (~0,05 SSIM-Verlust), nicht die Übersetzungstreue.
Schritt 5: Lücken dokumentieren
Alles, was sich nicht sauber übersetzen ließ (entfernte Lautstärkerampen, angenäherte benutzerdefinierte Präsentationen, ersetzte Schriftarten), wird in einer TRANSLATION_NOTES.md neben der HF-Ausgabe dokumentiert. Siehe references/limitations.md für das Format.
Was diese Fertigkeit ausdrücklich NICHT tut
- React-Zustandsmaschinen übersetzen. Kompositionen, die Animationen über
useState+useEffectsteuern, sind keine deterministischen Frame-Capture-Ziele im seek-gesteuerten Modell von HyperFrames. Empfehlen Sie das Runtime-Interop-Muster. - Remotions Rendering-Pipeline neben HyperFrames ausführen. Dies ist das Runtime-Interop-Muster aus PR #214 – eine separate Lösung für Kompositionen, die den Lint dieser Fertigkeit nicht bestehen.
(@remotion/lambda ist kein Blocker – Lambda-Konfiguration ist Deployment, nicht Animation. Die Fertigkeit entfernt sie 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 (Render + Diff) und T4 (Lint-Validierung) aus, gibt eine nach Stufen aufgeschlüsselte Bestanden/Nicht-Bestanden-Tabelle aus und erstellt einen aggregierten JSON-Bericht. Verwenden Sie dies, um zu überprüfen, ob die Fertigkeit auf einem sauberen Checkout Ende-zu-Ende funktioniert – und als Regressionstest nach der Bearbeitung einer Referenz.
Validierte Baseline (Stand: 27.04.2026):
| Stufe | Kompositionsform | 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/a |