Remotion vers HyperFrames
Vue d'ensemble
Traduire 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 mappage et se prémunit contre les 20% problématiques en refusant de traduire les motifs qui ne correspondent pas au modèle piloté par la recherche (seek-driven) d'HyperFrames et en recommandant plutôt le motif d'interopérabilité d'exécution décrit dans PR #214.
La compétence est livrée avec un corpus de test hiérarchisé (T1–T4, 4 montages 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 qui donne 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 d'expressions déclencheuses :
- « porte mon projet Remotion vers HyperFrames »
- « convertit ce code Remotion en HyperFrames »
- « migre depuis Remotion »
- « traduit cette comp Remotion »
- « réécris ceci en HTML HyperFrames »
N'utilisez PAS cette compétence lorsque :
- (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 matériel de référence plutôt que de demander une traduction.
- (d) L'utilisateur demande « la même vidéo que ma vidéo Remotion » sans demander explicitement de migrer la source — traitez cela comme une nouvelle création HyperFrames.
En cas de doute, par défaut, créez une composition HyperFrames native avec la compétence hyperframes.
Flux de travail
Étape 1 : Analyse du 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 dépendances non vides,calculateMetadataasynchrone, bibliothèques UI 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. - Informations (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'importation + 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 HyperFrames ou 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 tous — chargez uniquement ce dont la source spécifique a besoin.
Étape 3 : Générer la composition HyperFrames
Émettez index.html avec :
- Un
<div id="stage">racine portant les attributsdata-composition-id,data-start="0",data-duration(en secondes),data-fps,data-width,data-heightde la composition, plus undata-*par prop scalaire. - Une liste plate de
divde scène avecdata-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 unegsap.timeline({paused: true})en pause. Chaque dérivationuseCurrentFrame()de Remotion devient une interpolation (tween) sur cette timeline au décalage correct. window.__timelines["<composition-id>"] = tl;enregistre la timeline dans le runtime HyperFrames.
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 :
# Rendu de la référence Remotion (après npm install dans le montage)
cd remotion-src && npx remotion render <CompositionId> out/baseline.mp4
# Rendu de la traduction HyperFrames
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 : ~0,02 en dessous du p05 du niveau de complexité de la source (voir le tableau des seuils validés de 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 de timing/séquençage/média concernée.
Critique : les deux rendus doivent utiliser un format de pixel correspondant. Définissez Config.setVideoImageFormat("png") + Config.setColorSpace("bt709") dans le remotion.config.ts de la source Remotion — sinon la différence mesure les différences d'encodeur (~0,05 SSIM de pénalité), 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 TRANSLATION_NOTES.md écrit à côté de la sortie HyperFrames. 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é d'exécution. - Exécuter le pipeline de rendu de Remotion parallèlement à HyperFrames. C'est le motif d'interopérabilité d'exécution de PR #214 — une solution distincte 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 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érence) et T4 (validation de l'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 checkout propre — et comme test 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 | apparition progressive d'un seul élément | 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 d'analyse) | 8/8 réussi | n/a |