Remotion vers HyperFrames
Aperçu
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 environ 80% des compositions typiques. Cette compétence encode la cartographie et se prémunit contre les 20% perdants en refusant de traduire les motifs qui ne correspondent pas au modèle piloté par la recherche (seek) de HF et en recommandant plutôt le modèle d'interopérabilité d'exécution du PR #214.
La compétence est livrée avec un corpus de test à plusieurs 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 correcte" mais qui rend un SSIM inférieur de 0,05 par rapport à la référence validée est silencieusement erronée.
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 :
- Blocages (refuser + recommander l'interop) :
useState,useReducer,useEffect/useLayoutEffectavec des 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. - Infos (traduire avec une note) :
staticFile,interpolateColors.
Si un blocage 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 incriminée à 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 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 chargez pas toutes les références — chargez uniquement ce dont la source spécifique a besoin.
Étape 3 : Générer la composition HF
Émettez index.html avec :
- 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. <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 un tween sur cette timeline au bon décalage. window.__timelines["<composition-id>"] = tl;enregistre la timeline avec le runtime HF.
Les sous-composants React personnalisés sont intégrés en ligne sous forme de HTML répété en utilisant l'interface de props comme modèle (voir parameters.md pour le motif data-* par instance).
Étape 4 : Valider
Exécutez le banc d'essai d'évaluation — references/eval.md pour le guide complet. Chemin rapide :
# Rendu de la référence Remotion (après npm install dans la fixture)
cd remotion-src && npx remotion render <CompositionId> out/baseline.mp4
# Rendu de 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 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équence/média appropriée.
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 la différence mesure les différences d'encodeur (impact SSIM d'environ 0,05), pas la fidélité de la traduction.
Étape 5 : Documenter les lacunes
Tout ce qui n'a pas été traduit proprement (rampes de volume supprimées, présentations personnalisées approximatives, polices substituées) donne lieu à 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 piloté par la recherche d'HyperFrames. Recommandez le modèle d'interopérabilité d'exécution. - Exécuter le pipeline de rendu de Remotion en parallèle d'HyperFrames. C'est le modèle d'interopérabilité d'exécution du PR #214 — une solution distincte pour les compositions qui échouent au lint de cette compétence.
(@remotion/lambda n'est pas un blocage — la configuration Lambda concerne le déploiement, pas l'animation. La compétence la 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 test :
./assets/test-corpus/run.sh
Il exécute T1, T2, T3 (rendu + différence) et T4 (validation du lint), affiche une table 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 extraction 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 | fondu entrant d'un seul élément | 0,974 | 0,95 |
| T2 | multi-scènes + 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 |