Remotion vers HyperFrames
Aperçu
Traduire des 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 environ 80 % des compositions typiques. Cette compétence encode le mappage et se prémunit contre les 20 % avec perte en refusant de traduire les motifs qui ne correspondent pas au modèle piloté par la recherche (seek-driven) de HF et en recommandant le motif d'interopérabilité runtime du PR #214 à la place.
La compétence est livrée avec un corpus de tests hiérarchisé (T1–T4, 4 jeux d'essai 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 correcte » mais rend un SSIM inférieur de 0,05 par rapport à la référence validée est silencieusement erronée.
Quand l'utiliser
Utilisez cette compétence UNIQUEMENT lorsque l'utilisateur demande explicitement une migration depuis Remotion. Exemples de phrases déclencheuses :
- « portez mon projet Remotion vers HyperFrames »
- « convertissez ce code Remotion en HyperFrames »
- « migrez depuis Remotion »
- « traduisez cette comp Remotion »
- « réécrivez ceci en HTML HyperFrames »
N'utilisez PAS cette compétence quand :
- (a) L'utilisateur crée une nouvelle composition HyperFrames, même s'il possède ou teste une vidéo Remotion similaire.
- (b) L'utilisateur mentionne Remotion en passant sans demander de migration.
- (c) L'utilisateur partage du code Remotion comme documentation plutôt que de demander une traduction.
- (d) L'utilisateur demande « la même vidéo que ma Remotion » sans demander explicitement de migrer le code source — traitez cela comme une nouvelle construction HyperFrames.
En cas de doute, utilisez par défaut la compétence hyperframes pour créer une composition HyperFrames native.
Flux de travail
Étape 1 : Analyser le code 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 :
- Bloqueurs (refuser + recommander l'interopérabilité) :
useState,useReducer,useEffect/useLayoutEffectavec des dépendances non vides,calculateMetadataasynchrone, bibliothèques d'interface utilisateur 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 bloqueur 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 incriminée à l'étape 3 et notez l'écart dans TRANSLATION_NOTES.md. La configuration @remotion/lambda est le cas canonique d'avertissement : la compétence supprime l'import et 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 sa 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/<Famille>, Font.loadFont, @font-face | fonts.md |
Ne les chargez pas tous — ne chargez que ce dont la source spécifique a besoin.
Étape 3 : Générer la composition HF
Émettez index.html avec :
- Un
<div id="stage">racine portant les attributs suivants de la composition :data-composition-id,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. - Une balise
<style>en ligne pour la mise en page ; le CSS définit l'étatfromde chaque propriété animée. - Une balise
<script>unique en bas contenant unegsap.timeline({paused: true})mise en pause. Chaque dérivation deuseCurrentFrame()de Remotion devient une interpolation (tween) sur cette timeline au décalage approprié. window.__timelines["<id-composition>"] = tl;enregistre la timeline dans le runtime de HF.
Les sous-composants React personnalisés sont intégrés sous forme de HTML répété en utilisant l'interface des props 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 le jeu d'essai)
cd remotion-src && npx remotion render <IdComposition> out/baseline.mp4
# Rendre la traduction HF
cd ../hf-src && npx hyperframes render --output ../hf.mp4
# Différence SSIM
../../scripts/render_diff.sh ./remotion-src/out/baseline.mp4 ./hf.mp4 ./diff
Seuil : environ 0,02 en dessous de p05 du niveau de complexité de la source (voir le tableau des seuils validés dans eval.md). Si la différence échoue, exécutez scripts/frame_strip.sh pour voir quelles images ont divergé, puis relisez la référence pertinente sur le timing/le séquencement/les médias.
Critique : les deux rendus doivent utiliser un format de pixels correspondant. Définissez Config.setVideoImageFormat("png") + Config.setColorSpace("bt709") dans le fichier remotion.config.ts de la source Remotion — sinon la différence mesure les différences d'encodeur (impact SSIM d'environ 0,05), et non la fidélité de la traduction.
Étape 5 : Documenter les écarts
Tout ce qui n'a pas été traduit proprement (rampes de volume supprimées, présentations personnalisées approximées, polices substituées) reçoit 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 déterministes de capture d'images dans le modèle piloté par la recherche d'HyperFrames. Recommandez le motif d'interopérabilité runtime. - Exécuter le pipeline de rendu de Remotion en parallèle d'HyperFrames. C'est le motif d'interopérabilité runtime du PR #214 — une solution séparée pour les compositions qui échouent à l'analyse de cette compétence.
(@remotion/lambda n'est pas un bloqueur — la configuration Lambda concerne le déploiement, pas l'animation. La compétence le supprime comme un avertissement et traduit le reste. Voir references/escape-hatch.md.)
Comment évaluer votre propre traduction
Exécutez l'orchestrateur du corpus de tests :
./assets/test-corpus/run.sh
Il exécute T1, T2, T3 (rendu + différence) et T4 (validation par analyse), 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 un répertoire vierge — et comme vérification de régression après toute modification d'une référence.
Référence validée (au 27-04-2026) :
| Niveau | Forme de la composition | SSIM moyen | Seuil |
|---|---|---|---|
| T1 | fondu d'entrée d'un élément unique | 0,974 | 0,95 |
| T2 | multi-scène + ressort + audio + image | 0,985 | 0,95 |
| T3 | piloté par données, sous-composants personnalisés, compteur | 0,953 | 0,90 |
| T4 | échappatoire (8 cas d'analyse) | 8/8 réussite | n/a |