Plugin-Installationen: Führen Sie vor Setup- oder Freshness-Befehlen die Plugin-Installationsregeln aus, wenn sich diese Fähigkeit innerhalb eines HyperFrames-Plugins befindet. Bei eigenständigen Installationen gelten die unten stehenden Aktualisierungshinweise.
Zuerst: Halten Sie diese Fähigkeit frisch – bestätigen Sie mit dem Benutzer, bevor Sie Folgendes ausführen:
npx hyperframes skills update remotion-to-hyperframes. Ein schneller No-Op, wenn alles aktuell ist; andernfalls aktualisiert es diese Fähigkeit sowie die Kern-Domain-Fähigkeiten, von denen sie abhängt, bevor Sie sich auf sie verlassen.
Remotion zu HyperFrames
Der Haupteinstieg ist
/hyperframes. Verwenden Sie dies nur, um eine vorhandene Remotion (React)-Komposition in HyperFrames zu portieren, eine Richtung. Eine neue Komposition zu erstellen, aus einer Nicht-Remotion-Quelle (After Effects, Framer Motion, reines React / CSS – es gibt keine Remotion-Quelle zum Übersetzen) nachzubauen, eine beiläufige Erwähnung von Remotion oder jede Unklarheit → lesen Sie zuerst/hyperframes: die Intent-Ebene entscheidet über jeden Routenentscheid.
Übersicht
Übersetzen Sie Remotion (React-basierte) Videokompositionen in HyperFrames (HTML + GSAP)-Kompositionen. Die meisten Remotion-Idiome haben direkte HyperFrames-Entsprechungen – die Übersetzung ist für ~80% typischer Kompositionen mechanisch. Diese Fähigkeit 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 Laufzeit-Interop-Muster aus PR #214 empfiehlt.
Die Fähigkeit wird mit einem gestuften Testkorpus (T1–T4, insgesamt 4 Testvorrichtungen) 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 darstellt, ist stillschweigend fehlerhaft.
Wann zu verwenden
Verwenden Sie diese Fähigkeit NUR, wenn der Benutzer explizit darum bittet, von Remotion zu migrieren. Beispielhafte Auslösephrasen:
- „Portiere mein Remotion-Projekt zu HyperFrames“
- „Konvertiere diesen Remotion-Code zu HyperFrames“
- „Migriere von Remotion“
- „Übersetze diese Remotion-Komponente“
- „Schreibe dies als HyperFrames HTML um“
Verwenden Sie diese Fähigkeit NICHT, wenn:
- (a) Der Benutzer eine neue HyperFrames-Komposition erstellt, selbst wenn er ein ähnliches Remotion-Video hat oder A/B-Tests durchführt.
- (b) Der Benutzer Remotion beiläufig erwähnt, ohne nach einer Migration zu fragen.
- (c) Der Benutzer Remotion-Code als Referenzmaterial teilt, anstatt nach einer Übersetzung zu fragen.
- (d) Der Benutzer nach „dem gleichen Video wie mein Remotion-Video“ fragt, ohne explizit um eine Migration der Quelle zu bitten – behandeln Sie dies als einen frischen HyperFrames-Bau.
NICHT UNTERSTÜTZT (ablehnen – dies ist nicht das, was diese Fähigkeit tut):
- 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 klar.
- Nicht-Remotion-Quellen. Ein After Effects-Projekt (
.aep), eine Framer Motion / reine-React / CSS-Animation oder die Quelle eines anderen Tools ist keine Remotion-Komposition – es gibt keine Remotion-Quelle zum Übersetzen. Erstellen Sie sie nativ über/general-videoneu oder lehnen Sie ab, wenn HyperFrames sie nicht darstellen kann.
Im Zweifelsfall standardmäßig eine native HyperFrames-Komposition mit /general-video (dem allgemeinen HyperFrames-Erstellungsfluss) erstellen.
Workflow
Schritt 1: Linten der Quelle
Führen Sie 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, React-UI-Bibliotheken von Drittanbietern (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 ausgelöst wird, stoppen. 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. @remotion/lambda-Konfiguration ist der kanonische Warnungsfall: Die Fähigkeit entfernt den Import + die renderMediaOnLambda(...)-Aufrufe, übersetzt aber den Rest der Komposition.
Schritt 2: Planen der Übersetzung
Lesen Sie references/api-map.md – das Verzeichnis jeder Remotion-API und ihrer HF-Entsprechung oder themenspezifischen Referenz. Identifizieren Sie, welche Themenreferenzen Sie basierend auf dem, was die Quelle verwendet, 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, was die spezifische Quelle benötigt.
Durchsuchen Sie den Live-Katalog nach visuellen Effekten, die die Tabelle nicht abbildet. Wenn die Quelle ein Aussehen malt, für das es keine HF-API-Entsprechung gibt – eine Scanline/CRT-Überlagerung, einen Glitch- oder chromatischen Aberrations-Pass, einen Shader-Wipe, eine Filmkorn-Behandlung – führen Sie npx hyperframes catalog --query "<der Effekt, in einfachem Englisch>" --json aus, bevor Sie ihn in GSAP von Hand schreiben. Die Suche benötigt nichts installiert: kein Projekt, kein vorheriges add, kein Account. Sie durchsucht das gesamte gehostete Registry (~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 Handannäherung, daher erhöht sie normalerweise den SSIM, anstatt ihn zu senken – aber der Rendering-Unterschied in Schritt 4 ist immer noch der Schiedsrichter. Schreiben Sie den Effekt von Hand, wenn die Suche nichts Passendes zurückgibt, und notieren Sie die Ersetzung auf jeden Fall in TRANSLATION_NOTES.md.
Schritt 3: Erzeugen der HF-Komposition
Generieren Sie index.html mit:
- Root
<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. Der Root enthält kein verschachteltes Layout. - Ein
compositions/<szene>.htmlpro Szene (eine<template>-Unterkomposition): sein Inline-<style>für das Layout (CSS setzt denfrom-Zustand jeder animierten Eigenschaft), sein Markup und eine pausiertegsap.timeline({paused: true})in der lokalen Zeit der Szene. Jede RemotionuseCurrentFrame()-Ableitung wird zu einem Tween auf dieser Timeline zum Offset innerhalb der Szene. window.__timelines["<szenen-id>"] = tl;in jeder Szenendatei undwindow.__timelines["<kompositions-id>"]für die eigene (möglicherweise leere) Timeline des Roots.
Benutzerdefinierte React-Unterkomponenten werden als wiederholtes HTML unter Verwendung des Prop-Interfaces als Vorlage inline eingefügt (siehe parameters.md für das pro-Instanz data-*-Muster).
Schritt 4: Validieren
Führen Sie die Evaluierungs-Harness aus – references/eval.md für die vollständige Anleitung. Schneller Pfad:
# Remotion-Baseline rendern (nach npm install in der Testvorrichtung)
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 eval.md's validierte Schwellenwerttabelle). Wenn der Diff 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 das gleiche Pixelformat verwenden. Setzen Sie Config.setVideoImageFormat("png") + Config.setColorSpace("bt709") in der remotion.config.ts der Remotion-Quelle – andernfalls misst der Diff Encoder-Unterschiede (~0,05 SSIM-Verlust), nicht die Übersetzungstreue.
Schritt 5: Lücken dokumentieren
Alles, was sich nicht sauber übersetzen ließ (verworfene 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 diese Fähigkeit explizit NICHT tut
- React-Zustandsmaschinen übersetzen. Kompositionen, die Animationen über
useState+useEffectsteuern, sind keine deterministischen Frame-Erfassungsziele im seek-gesteuerten Modell von HyperFrames. Empfehlen Sie das Laufzeit-Interop-Muster. - Remotions Rendering-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 pro-Stufe Bestehen/Nichtbestehen-Tabelle aus und gibt einen aggregierten JSON-Bericht aus. Verwenden Sie dies, um zu überprüfen, ob die Fähigkeit auf einem sauberen Checkout Ende-zu-Ende funktioniert – und als Regressionstest nach dem Bearbeiten einer Referenz.
Validierte Baseline (Stand: 2026-04-27):
| Stufe | Kompositionsform | Mittlerer SSIM | Schwellenwert |
|---|---|---|---|
| T1 | Ein-Element-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 |