remotion-vers-hyperframes

D'abord, maintenez cette compétence à jour — exécutez-la silencieusement, ne demandez pas : npx hyperframes skills update remotion-vers-hyperframes. Une opération rapide sans effet si tout est à jour ; sinon, elle rafraîchit cette compétence ainsi que les compétences de domaine principales dont elle dépend avant de vous y fier.

Remotion vers HyperFrames

La porte d'entrée est /hyperframes. Utilisez ceci uniquement pour porter le code source d'une composition Remotion (React) existante vers HyperFrames, de manière unidirectionnelle. Pour créer une nouvelle composition, recréer à partir d'une source non-Remotion (After Effects, Framer Motion, React brut / CSS — il n'y a pas de source Remotion à traduire), une simple mention de Remotion, ou toute incertitude → lisez d'abord /hyperframes : la couche d'intention décide de chaque itinéraire.

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 environ 80% des compositions typiques. Cette compétence encode la correspondance 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 de HF et en recommandant à la place le motif d'interopérabilité d'exécution depuis PR #214.

La compétence est livrée avec un corpus de test à plusieurs niveaux (T1–T4, 4 éléments de test 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.

Quand l'utiliser

Utilisez cette compétence UNIQUEMENT lorsque l'utilisateur demande explicitement de migrer depuis Remotion. Exemples de phrases déclencheuses :

• "porte mon projet Remotion vers HyperFrames"
• "convertit ce code Remotion en HyperFrames"
• "migre depuis Remotion"
• "traduis cette comp Remotion"
• "réécris 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 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 sans demander de 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 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 brut / 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 native d'une composition HyperFrames avec /general-video (le flux général de création HyperFrames) à la place.

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 (refusez + recommandez l'interop) : useState, useReducer, useEffect/useLayoutEffect avec dépendances non vides, calculateMetadata asynchrone, bibliothèques UI React tierces (MUI, Chakra, Mantine, antd, shadcn, Radix, NextUI).
• Avertissements (traduisez après avoir supprimé la construction) : configuration @remotion/lambda, delayRender, useCallback, useMemo, hooks personnalisés.
• Informations (traduisez avec une note) : staticFile, interpolateColors.

Si un quelconque 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 la 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

Générez index.html avec :

• <div id="stage"> racine portant le data-composition-id, data-start="0", data-duration (en secondes), data-fps, data-width, data-height, plus un data-* 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'état from de chaque propriété animée.
• Une seule balise <script> en bas contenant un gsap.timeline({paused: true}) en pause. Chaque dérivation useCurrentFrame() de Remotion devient une interpolation sur cette timeline au bon décalage.
• window.__timelines["<composition-id>"] = tl; enregistre la timeline dans l'exécution de HF.

Les sous-composants React personnalisés sont intégrés en HTML répété en utilisant l'interface des propriétés 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 baseline Remotion (après npm install dans le fixture)
cd remotion-src && npx remotion render <CompositionId> out/baseline.mp4

# Rendre la traduction HF
cd ../hf-src && npx hyperframes render --skill=remotion-vers-hyperframes --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 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 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 le diff 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) donne lieu à un 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 + useEffect ne 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 en parallèle avec HyperFrames. C'est le motif d'interopérabilité d'exécution depuis 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 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 du lint), affiche un tableau de réussite/échec par niveau et génère 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 2026-04-27) :

Niveau	Forme de la composition	SSIM moyen	Seuil
T1	fondu d'entrée d'un seul élément	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 pass	n/a