akdavid4real/effectcraft-motion

Kit de motion design EffectCraft

Un workflow testé pour créer des vidéos de motion design d'entreprise de 60 secondes dans EffectCraft, qui ont l'air conçues, sont synchronisées et exemptes des bugs classiques : images vides entre les scènes, chevauchement des pistes vocales, texte caché par des décorations, chiffres qui disparaissent et effets sonores décalés par rapport au rythme.

Le design vient de l'apparence et de la mise en page, pas de rien. Choisissez l'un des cinq looks testés, écrivez chaque scène comme un appel scene() avec votre contenu et les timings des mots, et la mise en page gère la taille, la grille, la couleur et le mouvement. Les agents qui inventent un style finissent avec des dégradés sombres, des blobs lumineux et du texte centré en petit ; c'est la raison numéro un pour laquelle une promotion générée a l'air bon marché.

N'importe quel agent peut utiliser ceci. Tout fonctionne depuis un terminal (effectcraft-cli via scripts/ec.py). MCP est optionnel. Emplacement du kit : le dossier contenant ce fichier (appelez-le $KIT).

Pas ce kit : les vidéos d'histoires de personnages en bâtons (split-screen "mauvaise façon vs bonne façon") utilisent plutôt la compétence stick-figure-story.

Règles d'or (les raisons sont dans references/)

1. Les temps viennent des données, pas des suppositions. Le plan de scène se trouve dans timeline.json. Les scripts de scène utilisent SC("s3") et W("s3", "word") (le temps absolu où un mot est prononcé). Ne tapez jamais un temps comme 23.6.
2. Regardez chaque scène que vous construisez. Rendez les images de prévisualisation (ec.py frames) et ouvrez les PNG. Un code qui s'exécute sans erreur peut quand même produire un rendu incorrect.
3. "Terminé" signifie que les contrôles sont passés. timeline.py check a 0 FAIL, ec.py qa a 0 FAIL, ec.py qa-video a 0 FAIL, et vous avez regardé la planche contact. Rapportez les résultats honnêtement, avertissements inclus.
4. Utilisez un look et les mises en page (references/looks.md). Comparez deux looks avant de choisir. Au moins un tiers des scènes doivent être visuelles (téléphone / icônes / flux / barres, ou une scène personnalisée avec un objet). Le code de scène personnalisée est pour ce qu'aucune mise en page ne couvre (une carte, une maquette de produit), et il utilise toujours la palette du look P(S.bg) et les tailles de police LOOK.type.
5. Lisez references/pitfalls.md avant d'écrire un script EffectCraft. Lisez references/motion-design.md, references/looks.md et references/techniques.md (grille de beats, SFX alignés sur les pics, morphing continu, liste d'interdits) avant de concevoir des scènes.
6. La marque n'est pas à vous de modifier (references/brand.md). Montrez le vrai fichier logo, jamais le nom tapé comme un mot-symbole. Écrivez le slogan caractère par caractère. N'inventez pas de noms de produits, d'étiquettes de boutons ou de statistiques. Remplissez le bloc "brand" dans timeline.json pour que ec.py qa le vérifie.
7. Passer le QA n'est pas la même chose qu'un bon design. Planifiez le script de couleurs, les visuels et le moment signature avant d'écrire les scènes, et évaluez le film dans une revue de direction créative avant le rendu (references/design-review.md, comparé avec references/benchmark_sheet.png). 7b. Interface utilisateur réelle du produit (SaaS, films d'application) : suivez references/ui-footage.md : capturez uniquement des données d'exemple, recadrez sur un panneau, montrez-le lisiblement (55 %+ de largeur) ou reconstruisez-le comme une UI animée, un écran par plan, pas de murs teintés de miniatures, pas de chiffres inventés, et construisez ici pour que les contrôles QA s'exécutent.
8. Annonces haute énergie / hyper-kinétiques (style TikTok, un effet sur chaque mot parlé) : suivez references/high-energy.md et templates/hyper.jsx au lieu des mises en page calmes.
9. Rapportez ce que le rendu montre, pas ce que vous avez planifié. Avant d'écrire le rapport ou la remise, extrayez des images du MP4 final (pas de la prévisualisation) au milieu et à la dernière demi-seconde de chaque scène, et vérifiez chaque affirmation : chaque ligne à l'écran est-elle assez longue pour être lue, chaque étape dessinée est-elle vraiment visible, la capture d'écran est-elle lisible, la longueur correspond-elle au brief et au nom du fichier ? Lisez chaque transcription vocale par rapport au script, et écoutez le nom de la marque. Lors des tests, une remise d'agent décrivait quatre étapes de diagramme, trois promesses et "BridgeAxis Technologies" ; le film montrait la dernière étape 0,3 s avant le cut, les promesses pendant une demi-seconde, des captures d'écran illisibles, et une voix disant "Bridge Access". timeline.py check et ec.py qa préviennent désormais des erreurs de voix non lues et du texte lisible moins de min_read secondes : corrigez ces avertissements, ne les expliquez pas. Utilisez le réglage de raisonnement le plus élevé de votre agent : l'exécution bâclée était sur un niveau "Faible".

Structure du projet

<projet>/
  timeline.json        plan de scène + indices SFX + musique (démarrez avec $KIT/templates/timeline.example.json)
  audio_meta.json      fichiers vocaux + horodatages des mots (de l'étape audio)
  soundtrack.wav       généré par timeline.py mix
  assets/voice|sfx|bgm|icons|fonts
  scripts/lib.jsx      copie de $KIT/templates/lib.jsx (définissez COMP ; le look fournit les couleurs et polices)
  scripts/look.jsx     écrit par `ec.py look NOM --accent HEX`
  scripts/timing.jsx   généré (timeline.py emit) - ne jamais éditer
  scripts/wipes.jsx    généré (timeline.py emit) - exécuté en DERNIER
  scripts/reset.jsx, s1.jsx ... s8.jsx
  qa/                  prévisualisations et planches contact

Exécutez chaque commande depuis <projet>/. ec.py lit le chemin du projet et le nom de la composition depuis timeline.json.

Workflow A : nouvelle vidéo

0. Brief. Demandez avant de construire : marque/site web à égaler, humeur (fort / calme / technique / luxueux), durée et ratio d'aspect, voix (genre/ton), et si la musique/SFX sont souhaités. Deviner la direction créative est la raison la plus courante pour laquelle un premier montage est rejeté.

1. Configuration

mkdir -p <projet>/{scripts,assets/{voice,sfx,bgm,icons},qa} && cd <projet>
cp $KIT/templates/lib.jsx $KIT/templates/reset.jsx $KIT/templates/s1.jsx scripts/
cp $KIT/templates/timeline.example.json timeline.json   # éditer les noms projet/composition/sortie
python3 $KIT/scripts/ec.py fonts                         # installe les polices des looks (une fois par machine)

Définissez COMP dans scripts/lib.jsx avec le nom de la composition du timeline. Notez la couleur d'accentuation de la marque (logo, CSS du site web, produit). Si la marque a un site web, lisez son CSS pour l'accentuation et les polices. Placez les fichiers logo dans assets/logo/ et remplissez le bloc "brand" dans timeline.json : nom, slogan exact, fichiers logo, et tout nom de produit ou URL approuvé (references/brand.md).

2. Script et voix. Écrivez 8 lignes (accroche, problème, marque, 2–3 avantages, preuve, carte de fin) ; 60 s contient environ 110–130 mots parlés. Générez un fichier audio par ligne et obtenez les horodatages des mots dans audio_meta.json sous cette forme :

{"voices": [{"id": "s1", "path": "assets/voice/s1.wav", "duration_s": 6.45,
             "words": [{"word": "Chaque", "start": 0.30, "end": 0.59}, ...]}]}

Exécutez d'abord python3 $KIT/scripts/ec.py doctor. Il liste ce que cette machine a et comment installer ce qui manque. Quand il dit ready, ne recherchez pas et n'installez pas d'alternatives (edge-tts, Whisper, piper, Playwright) : les outils ci-dessous sont les testés. Sans voix du tout, chronométrez les scènes avec des décalages "in+0.5" au lieu de mots ; $KIT/demo/ est un exemple silencieux complet (ec.py demo le rend).

• Voix (la valeur par défaut) : Kokoro local, voix féminine af_heart. Gratuit, sans compte. Le modèle est mis en cache dans ~/.cache/hyperframes/tts/ (téléchargé une fois lors de la première exécution) :

  export HYPERFRAMES_PYTHON=~/.venvs/kokoro/bin/python   # REQUIS : l'environnement virtuel avec kokoro-onnx
  npx hyperframes tts "Texte de la ligne un." -v af_heart -o assets/voice/s1.wav   # un fichier par ligne
  

  Sans HYPERFRAMES_PYTHON, cela échoue avec "Le package kokoro-onnx n'est pas installé". N'installez rien avec pip : définissez la variable.
• Horodatages des mots : npx hyperframes transcribe assets/voice/s1.wav --json. Il utilise le modèle Parakeet, mis en cache dans ~/.cache/hyperframes/parakeet après la première exécution (le moteur auto le sélectionne). Parakeet est adapté aux voix TTS propres comme Kokoro. Ne passez pas -e whisper ici : le moteur Whisper d'hyperframes (whisper.cpp) n'est pas configuré. Pour les voix enregistrées réelles avec accents, la compétence d'édition de séquences utilise faster-whisper large-v3-turbo à la place (~/.venvs/asr). Copiez les mots et leurs heures de début et de fin dans audio_meta.json.
• Musique et SFX : le moteur audio media-use (node <skills>/media-use/audio/scripts/audio.mjs --request audio_request.json --out audio_meta.json --only bgm,sfx). Il récupère depuis le catalogue HeyGen par description, par exemple "bgm": {"mode": "retrieve", "query": "piano chaleureux calme"}. <skills> est ~/.claude/skills pour Claude Code, ~/.agents/skills pour Codex/OpenCode/DeepSeek.
• La synthèse vocale HeyGen (via le moteur ou le CLI heygen) est la voix alternative, mais le crédit gratuit s'épuise. Quand c'est le cas, utilisez Kokoro. La récupération de musique et SFX nécessite également que le CLI heygen soit connecté (heygen auth login --oauth) sauf si HEYGEN_API_BASE est défini ; sans cela, sfx répond toujours depuis la bibliothèque intégrée de media-use, et l'utilisateur peut fournir son propre fichier de musique.

Notez quel fournisseur et quelle voix vous avez réellement utilisés.

3. Timeline

python3 $KIT/scripts/timeline.py beats      # tempo musique, beats, débuts de mesures, drop -> beats.json (nécessite "music")
python3 $KIT/scripts/timeline.py suggest    # propose entrée/sortie de scène + voice_at ; avec beats.json, les scènes finissent sur les beats
# copiez dans timeline.json, définissez le "bg" de chaque scène (light/dark/accent), ajoutez des indices SFX ancrés aux mots
python3 $KIT/scripts/timeline.py words      # chaque mot avec son temps absolu
python3 $KIT/scripts/timeline.py check      # DOIT être 0 FAIL
python3 $KIT/scripts/timeline.py emit       # écrit scripts/timing.jsx + scripts/wipes.jsx
python3 $KIT/scripts/timeline.py mix        # écrit soundtrack.wav (-14 LUFS)

Coupez sur le beat : timeline.py snap déplace les cuts existants sur les beats où la voix tient toujours ; dans les scènes, BEAT(n), DOWNBEAT(n), nearBeat(t) et T.drop synchronisent les impacts et pops sur la musique (references/techniques.md). Le "at" du SFX peut être un nombre, "beat:12", "downbeat:3", "drop", "s2:late" (le mot "late" dans la voix de s2 ; "s2:the#2" = 2ème "the"), "wipe:s3" (la transition vers s3), "in:s3" ou "out:s3". Ajoutez "offset", "vol", "max" (longueur de coupe) et "align": "peak" (le moment le plus fort du son atterrit sur l'ancre : utilisez-le pour les impacts et pops).

4. Planifiez, puis écrivez les scènes. Écrivez d'abord le plan dans qa/design_review.md (references/design-review.md, parties 1-6) : le script de couleurs avec une ligne par scène, le visuel qui montre ce que chaque ligne dit, le héros de chaque scène, et le moment signature unique. Donnez à chaque scène un arrière-plan dans timeline.json ("bg": "light" | "dark" | "accent") et ré-exécutez timeline.py emit. Alternez-les pour que chaque cut lise comme un nouveau chapitre. Utilisez "accent" pour les 1-2 moments les plus forts, généralement le pic émotionnel. Placez la révélation de la marque et la carte de fin sur l'arrière-plan où le vrai logo se lit le mieux (généralement light), pas sur l'accent. Ensuite, écrivez scripts/s1.jsx ... sN.jsx, chacun un appel scene() avec une mise en page (spécifications : en haut de templates/layouts.jsx ; guide : references/looks.md) :

// scripts/s2.jsx
scene("s2", "list", { label: "Le problème",
  items: [["Arrivées tardives.", "late"], ["Surprises douanières.", "customs"], ["Un suivi qui ne vous dit *rien.*", "tracking", "rien"]],
  punch: ["Trop tard.", "trop"] });

*mot* marque la partie accentuée d'une ligne. Les temps sont des mots de timeline.py words ("word", "word#2", "word+0.3", "in+0.2"), écrits sans ponctuation. Les mises en page agrandissent ou réduisent le texte pour remplir le cadre, alors écrivez le texte que vous voulez et laissez la mise en page le dimensionner. Gardez les lignes à l'écran courtes :

elles sont des titres, pas la voix off. Seulement pour quelque chose qu'aucune mise en page ne couvre (une carte, une maquette de produit), copiez $KIT/templates/scene_template.jsx à la place.

Faites au moins un tiers des scènes visuelles. Un film qui n'est que des mots sur des arrière-plans se lit comme un diaporama, aussi bon soit le texte. Les mises en page visuelles mettent un objet à l'écran dont parle la voix : phone (le produit sur un écran de téléphone : une page de paiement, une commande, une mise à jour de suivi), icons (2-4 pictogrammes dessinés avec des étiquettes), flow (arrêts reliés par une ligne qui se remplit à mesure que chacun est prononcé : client → téléphone → banque, entrepôt → port → porte) et bars (2-4 barres qui grandissent : frais, temps d'attente, avant/après). Choisissez les scènes où la voix décrit une chose ou un processus, pas une affirmation.

scene("s4", "flow", { label: "Comment ça marche", title: ["Banké le *même jour.*", "argent", "même"],
  nodes: [{ icon: "shop", label: "Vous vendez", at: "vendez" }, { icon: "phone", label: "Tapnest", at: "app" },
          { icon: "bank", label: "Votre compte", at: "compte", note: "Même jour" }] });

Les icônes sont dessinées par le kit (pas de fichiers) : phone card bank cash clock check tick shop bolt chart truck box pin lock user people chat globe send star plane doc. Une scène visuelle personnalisée compte aussi lorsque ses couches image/objet ont "VIS" dans leurs noms (par exemple "s5 VIS map") ; ec.py qa prévient quand moins d'un tiers des scènes sont visuelles. Ne copiez pas layouts.jsx dans le projet : ec.py le charge depuis le kit, et une copie fige l'ancienne version.

5. Choisissez le look (lisez references/looks.md d'abord). Présélectionnez deux looks qui correspondent à la marque de manières différentes, prenez l'accent de la marque, et comparez-les sur VOS scènes :

python3 $KIT/scripts/ec.py new
python3 $KIT/scripts/ec.py import soundtrack.wav assets/icons/*.png
python3 $KIT/scripts/ec.py compare editorial swiss --accent FF5B1F   # -> qa/look_compare.png : OUVREZ-LE
python3 $KIT/scripts/ec.py look editorial --accent FF5B1F             # appliquez le gagnant

6. Construisez et prévisualisez

python3 $KIT/scripts/ec.py run s1 s2 s3 s4 s5 s6 s7 s8 wipes   # s1 crée la comp + soundtrack
python3 $KIT/scripts/ec.py frames 2 4 6.5                      # OUVREZ qa/frames.png et regardez-le

Prévisualisez deux ou trois moments de chaque scène. Pour corriger une scène, éditez-la et exécutez ec.py rebuild sN (efface uniquement cette scène, la reconstruit, ré-exécute les wipes). Pour tout reconstruire (par exemple après avoir changé le look) : ec.py run reset s1 ... sN wipes. Le look fournit la transition ; pour la remplacer, écrivez votre propre scripts/wipes.jsx sans la ligne d'en-tête "GENERATED" (emit laisse alors la

…

[suite tronquée pour la traduction].