Remotion vers HyperFrames
Aperçu
Traduisez 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 la cartographie et se prémunit contre les 20 % problématiques en refusant de traduire les motifs qui ne correspondent pas au modèle basé sur la recherche d'HyperFrames (seek-driven model) et en recommandant à la place le modèle d'interopérabilité d'exécution (runtime interop pattern) de PR #214.
La compétence est livrée avec un corpus de tests échelonnés (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 « semble correcte » mais dont le rendu est 0,05 SSIM inférieur à la référence validée est silencieusement erronée.
Quand utiliser
Utilisez cette compétence UNIQUEMENT lorsque l'utilisateur demande explicitement de migrer depuis Remotion. Exemples de phrases déclencheurs :
- « porter mon projet Remotion vers HyperFrames »
- « convertir ce code Remotion en HyperFrames »
- « migrer depuis Remotion »
- « traduire cette comp Remotion »
- « réécrire ceci 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 une vidéo Remotion similaire en A/B.
- (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 ma Remotion » sans demander explicitement de migrer la source — traitez cela comme une nouvelle construction HyperFrames.
En cas de doute, par défaut, créez une composition HyperFrames native avec la compétence hyperframes.
Workflow
Étape 1 : Linter la source
Exécutez scripts/lint_source.py sur le répertoire source Remotion. Le lint détecte les motifs qui ne peuvent pas être traduits proprement :
- Bloqueurs (refuser + recommander l'interop) :
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. - Infos (traduire avec une note) :
staticFile,interpolateColors.
Si un bloqueur se déclenche, 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 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 de son équivalent HF ou de 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/<Family>, Font.loadFont, @font-face | fonts.md |
Ne les chargez pas toutes — chargez uniquement ce dont la source spécifique a besoin.
Étape 3 : Générer la composition HF
Émettez index.html avec :
- Un élément racine
<div id="stage">portant ledata-composition-idde la composition,data-start="0",data-duration(en secondes),data-fps,data-width,data-height, plus undata-*par propriété 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 ; 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 un tween sur cette timeline au décalage correct. window.__timelines["<composition-id>"] = tl;enregistre la timeline avec l'exécution de 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 --output ../hf.mp4
# Diff SSIM
../../scripts/render_diff.sh ./remotion-src/out/baseline.mp4 ./hf.mp4 ./diff
Seuil : environ 0,02 en dessous du p05 du niveau de complexité de la source (voir le tableau des seuils validés de 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 un format de pixel correspondant. Définissez Config.setVideoImageFormat("png") + Config.setColorSpace("bt709") dans le fichier remotion.config.ts de la source Remotion — sinon, le diff mesure les différences d'encodeur (environ 0,05 SSIM) 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 abandonnées, présentations personnalisées approximées, polices substituées) doit être documenté dans un fichier TRANSLATION_NOTES.md placé à 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'images déterministes dans le modèle basé sur la recherche d'HyperFrames. Recommandez le modèle d'interopérabilité d'exécution. - Exécuter le pipeline de rendu Remotion parallèlement à HyperFrames. C'est le modèle d'interopérabilité d'exécution 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 bloqueur — la configuration Lambda concerne le déploiement, pas l'animation. La compétence le supprime comme avertissement et traduit le reste. Voir references/escape-hatch.md.)
Comment noter votre propre traduction
Exécutez l'orchestrateur du corpus de tests :
./assets/test-corpus/run.sh
Il exécute T1, T2, T3 (rendu + diff) et T4 (validation du lint), affiche un tableau de 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 checkout 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 + ressort + audio + image | 0.985 | 0.95 |
| T3 | Piloté par les données, sous-composants personnalisés, compteur | 0.953 | 0.90 |
| T4 | Échappatoire (8 cas de lint) | 8/8 réussi | n/a |