Que fait Remotion vers HyperFrames ?
Confirmez la route avant de construire. Utilisez ceci uniquement pour porter le source d'une composition Remotion (React) existante vers HyperFrames. Créer une nouvelle composition (même inspirée d'une vidéo Remotion) → les workflows de création
/general-video. Hors périmètre (à sens unique, Remotion uniquement) : pas d'export inverse (HyperFrames → Remotion ou tout autre framework), et une source non Remotion (After Effects, Framer Motion, React simple / CSS) n'a pas de source Remotion à traduire → recréer via/general-video. En cas de doute, ou si Remotion est simplement mentionné en passant ? Lisez/hyperframesd'abord.
Aperçu
Traduisez les compositions vidéo Remotion (basées sur React) en compositions HyperFrames (HTML + GSAP). La plupart des idiomes Remotion ont des équivalents directs dans HyperFrames — la traduction est mécanique pour ~80% des compositions typiques. Cette compétence encode le mapping et protège contre les 20% problématiques en refusant de traduire les motifs qui ne correspondent pas au modèle orienté recherche (seek-driven) de HF et en recommandant le motif d'interopérabilité runtime de PR #214 à la place.
La compétence est livrée avec un corpus de test à niveaux (T1–T4, 4 fixtures au total) qui évalue les traductions par rapport à des seuils SSIM mesurés. Ne traduisez pas sans exécuter l'évaluation — une traduction qui "a l'air bonne" mais rend un SSIM 0,05 inférieur à la référence validée est silencieusement erronée.
Quand l'utiliser
Utilisez cette compétence UNIQUEMENT lorsque l'utilisateur demande explicitement de migrer depuis Remotion. Exemples de phrases déclencheuses :
- "port mon projet Remotion vers HyperFrames"
- "converti ce code Remotion en HyperFrames"
- "migre depuis Remotion"
- "traduis cette comp Remotion"
- "réécris cela en HTML HyperFrames"
N'utilisez PAS cette compétence lorsque :
- (a) L'utilisateur crée une nouvelle composition HyperFrames, même s'il a ou teste en A/B une vidéo Remotion similaire.
- (b) L'utilisateur mentionne Remotion en passant sans demander de migration.
- (c) L'utilisateur partage du code Remotion comme matériel de référence plutôt que de demander une traduction.
- (d) L'utilisateur demande "la même vidéo que mon Remotion" sans demander explicitement de migrer le source — traitez cela comme une nouvelle création HyperFrames.
NON PRIS EN CHARGE (refusez — ce n'est pas ce que fait cette compétence) :
- La direction inverse. Exporter une composition HyperFrames vers Remotion (ou vers tout autre framework) n'est pas un workflow — la traduction est Remotion → HyperFrames uniquement. Dites-le clairement.
- Sources non Remotion. Un projet After Effects (
.aep), une animation Framer Motion / React simple / CSS, ou toute autre source n'est pas une composition Remotion — il n'y a pas de source Remotion à traduire. Recréez-la nativement via/general-video, ou refusez si HyperFrames ne peut pas la représenter.
En cas de doute, privilégiez la création d'une composition HyperFrames native avec /general-video (le flux général de création HyperFrames).
Workflow
Étape 1 : Analyser la source
Exécutez scripts/lint_source.py sur le répertoire source Remotion. L'analyse détecte les motifs qui ne peuvent pas être traduits proprement :
- Blocants (refuser + recommander l'interop) :
useState,useReducer,useEffect/useLayoutEffectavec dépendances non vides,calculateMetadataasynchrone, bibliothèques React tierces (MUI, Chakra, Mantine, antd, shadcn, Radix, NextUI). - Avertissements (traduire après avoir supprimé la construction) : configuration
@remotion/lambda,delayRender,useCallback,useMemo, hooks personnalisés. - Info (traduire avec une note) :
staticFile,interpolateColors.
Si un blocant est déclenché, arrêtez-vous. Lisez references/escape-hatch.md et affichez le message de recommandation. Les avertissements n'arrêtent pas la traduction — supprimez la construction problématique à l'étape 3 et notez l'écart dans TRANSLATION_NOTES.md. La configuration @remotion/lambda est le cas d'avertissement canonique : la compétence supprime l'import + les appels renderMediaOnLambda(...) mais traduit le reste de la composition.
Étape 2 : Planifier la traduction
Lisez references/api-map.md — l'index de chaque API Remotion et son équivalent HF ou une référence par sujet. Identifiez les références thématiques dont vous aurez besoin en fonction de ce que la source utilise :
| La source contient | Charger la référence |
|---|---|
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 |
Ne les chargez pas toutes — chargez seulement ce dont la source spécifique a besoin.
Étape 3 : Générer la composition HF
Générez index.html avec :
- Un
<div id="stage">racine portant ledata-composition-idde la composition,data-start="0",data-duration(en secondes),data-fps,data-width,data-height, plus undata-*par prop scalaire. - Une liste plate de divs de scène avec
data-start/data-duration/data-track-index. - Un
<style>en ligne pour la mise en page ; le CSS définit l'étatfromde chaque propriété animée. - Une seule balise
<script>en bas contenant ungsap.timeline({paused: true})en pause. Chaque dérivation deuseCurrentFrame()de Remotion devient une interpolation sur cette timeline au décalage approprié. window.__timelines["<composition-id>"] = tl;enregistre la timeline avec le runtime HF.
Les sous-composants React personnalisés sont intégrés sous forme de HTML répété en utilisant l'interface de prop comme modèle (voir parameters.md pour le motif data-* par instance).
Étape 4 : Valider
Exécutez le harnais d'évaluation — references/eval.md pour le guide complet. Chemin rapide :
# Rendre la référence Remotion (après npm install dans la fixture)
cd remotion-src && npx remotion render <CompositionId> out/baseline.mp4
# Rendre la traduction HF
cd ../hf-src && npx hyperframes render --skill=remotion-to-hyperframes --output ../hf.mp4
# Diff SSIM
../../scripts/render_diff.sh ./remotion-src/out/baseline.mp4 ./hf.mp4 ./diff
Seuil : ~0,02 en dessous du p05 du niveau de complexité de la source (voir le tableau des seuils validés dans eval.md). Si le diff échoue, exécutez scripts/frame_strip.sh pour voir quelles images ont divergé, puis relisez la référence de timing/séquencement/média pertinente.
Critique : les deux rendus doivent utiliser le même format de pixel. Définissez Config.setVideoImageFormat("png") + Config.setColorSpace("bt709") dans le remotion.config.ts de la source Remotion — sinon le diff mesure les différences d'encodeur (~0,05 de perte SSIM), pas la fidélité de traduction.
Étape 5 : Documenter les lacunes
Tout ce qui n'a pas été traduit proprement (rampes de volume supprimées, présentations personnalisées approximées, polices substituées) donne naissance à un fichier TRANSLATION_NOTES.md écrit à côté de la sortie HF. Voir references/limitations.md pour le format.
Ce que cette compétence ne fait PAS explicitement
- Traduire les machines d'état React. Les compositions qui pilotent l'animation via
useState+useEffectne sont pas des cibles de capture d'image déterministes dans le modèle orienté recherche de HyperFrames. Recommandez plutôt le motif d'interopérabilité runtime. - Exécuter le pipeline de rendu de Remotion parallèlement à HyperFrames. C'est le motif d'interopérabilité runtime de PR #214 — une solution séparée pour les compositions qui échouent au lint de cette compétence.
(@remotion/lambda n'est pas un blocant — la configuration Lambda concerne le déploiement, pas l'animation. La compétence la supprime comme avertissement et traduit le reste. Voir references/escape-hatch.md.)
Comment évaluer votre propre traduction
Exécutez l'orchestrateur du corpus de test :
./assets/test-corpus/run.sh
Il exécute T1, T2, T3 (rendu + diff) et T4 (validation de lint), affiche un tableau réussite/échec par niveau, et émet un rapport JSON agrégé. Utilisez-le pour vérifier que la compétence fonctionne de bout en bout sur une copie propre — et comme vérification de régression après avoir modifié une référence.
Référence validée (au 27/04/2026) :
| Niveau | Forme de la composition | SSIM moyen | Seuil |
|---|---|---|---|
| T1 | fade-in d'un élément unique | 0,974 | 0,95 |
| T2 | multi-scène + spring + audio + image | 0,985 | 0,95 |
| T3 | piloté par données, sous-composants personnalisés, compteur | 0,953 | 0,90 |
| T4 | échappatoire (8 cas de lint) | 8/8 réussi | n/a |