assafkip/claude-video-editor

Faire une Vidéo — La Compétence Débutant→MP4 Finalisé

Deux phases, huit étapes séquentielles. Chaque étape produit un artéfact concret que l'étape suivante consomme. Ne sautez pas d'étapes.

Quand utiliser cette compétence — et quand déléguer

Utilisez cette compétence quand :

• L'utilisateur est nouveau sur HyperFrames et part d'un concept, d'un script ou d'un plan
• Il souhaite un parcours complet, pas une documentation de référence
• Il n'a pas encore décidé du format

Déléguez quand :

• L'utilisateur colle une URL et veut une vidéo depuis ce site → invoquez /website-to-hyperframes
• L'utilisateur veut explicitement un format vertical 9:16 avec visage caméra + incrustations de scène → exécutez les Étapes 1–4 ici, puis invoquez /short-form-video à partir de l'Étape 5
• L'utilisateur demande les règles du framework, pas une vidéo → invoquez /hyperframes

Les deux phases

• Phase 1 — INTERVIEW (Étapes 1–4) : un passage conversationnel pour rassembler tout avant de toucher au code. Intention, format, script, voix, style, actifs, rythme. Synthétiser dans un BRIEF.md et attendre une approbation explicite.
• Phase 2 — CONSTRUCTION (Étapes 5–8) : squelette → storyboard → compositions → lint → prévisualisation Studio → rendu brouillon → vérification visuelle → prévisualisation MP4 → rendu final.

---

Étape 1 · Intention et format

Posez une question à la fois via AskUserQuestion, à choix multiples si possible.

1. À quoi sert cette vidéo ? (promo · pub sociale · teaser lancement · démo produit · tutoriel · explicative · carte intro/outro · autre)
2. Qui est le public ? (libre)
3. Durée cible ? (10–20s court · 20–45s promo · 45–90s explicative · 1,5–3 min leçon · personnalisée)
4. Ratio d'aspect ? (16:9 1920×1080 · 9:16 1080×1920 · 1:1 1080×1080)
5. Fréquence d'images ? (30 par défaut · 60 pour UI nette · 24 cinématographique)
6. Plateforme / contraintes de diffusion ? (taille fichier · date limite · où elle sera jouée)

Point d'étape : les six éléments capturés. Si la réponse est 9:16 + visage caméra, prévoir la délégation vers /short-form-video à l'Étape 5.

Banque de questions complète : Read: references/interview-questions.md

---

Étape 2 · Script et voix

1. Source du script ? (coller · plan → je rédige · j'enregistre · TTS à partir du texte · pas de narration)
2. Si TTS : préférence vocale. Proposer les choix depuis npx hyperframes tts --help. Capturer aussi le rythme.
3. Si visage caméra : chemin d'enregistrement · plein écran ou coin · besoin de transcription ? (npx hyperframes transcribe <fichier> --model small.en --json)
4. Sous-titres ? (désactivés · dynamiques · corporate · karaoké mot par mot · minimal)

Point d'étape : script capturé (ou rédigé), plan audio capturé, plan sous-titres capturé.

---

Étape 3 · Collecte du style

Avant de demander quoi que ce soit à l'utilisateur, inventorier les actifs existants. Vérifier <racine-espace-de-travail>/assets/ et tout dossier assets/ du projet. Ne pas demander ce qui est déjà là.

Puis demander progressivement — il n'a pas besoin de répondre à tout :

1. Guide de style ou doc de marque ? (coller/chemin · non)
2. Palette de couleurs ? (codes hex · non — utiliser les valeurs par défaut de MOTION_PHILOSOPHY)
3. Polices ? (nom(s) Google Fonts · chemins de fichiers · non — utiliser Inter + JetBrains Mono par défaut)
4. Fichier logo ? (chemin · non — utiliser un mot-clé texte à la place)
5. Vidéos de référence pour l'ambiance ? (URLs/chemins · non)
6. Autres actifs ? (captures d'écran · photos produit · rushes · musique — lister les chemins)
7. Esthétique MOTION_PHILOSOPHY (fond noir · typo chrome · grille de perspective · transitions whip) ou un autre rendu ?
8. Rythme ? (kinétique 1–2s · équilibré 2–3s · relaxé 3–5s)
9. Musique ? (aucune · nappe ambiante 0.15 · fond musical 0.4 · pleine 0.8 — chemin du fichier s'il en a un)
10. Texte d'outro / appel à l'action ?

N'imposez jamais une marque à l'utilisateur. Revenez aux valeurs par défaut de MOTION_PHILOSOPHY uniquement quand il refuse explicitement de fournir un style.

Flux de style complet + valeurs par défaut MOTION_PHILOSOPHY : Read: references/style-intake.md

---

Étape 4 · Synthèse du brief (POINT D'ÉTAPE OBLIGATOIRE avant construction)

1. Lire MOTION_PHILOSOPHY.md s'il existe dans la racine de l'espace de travail — obligatoire si présent. S'il manque, continuer avec les valeurs par défaut de references/style-intake.md et noter l'absence dans le brief.
2. Demander où se trouvent les projets si ce n'est pas évident :
   • Si video-projects/ existe → utiliser video-projects/<slug>/
   • Sinon → demander à l'utilisateur
3. Écrire <dossier-projet>/BRIEF.md :
   • slug · intention · public · dimensions · fps · durée
   • script (complet ou plan)
   • choix voix · plan sous-titres · plan visage caméra
   • profil style : palette (hex), polices, chemin logo, vidéos de référence
   • rythme
   • inventaire des actifs avec chemins
   • texte d'outro / CTA
4. Montrer le brief. ATTENDRE une approbation explicite. Ne pas passer à l'Étape 5 sans un « oui, construis-la » clair.

---

Étape 5 · Squelette et storyboard

Vérification de délégation d'abord

Si le brief décrit un format vertical 9:16 avec visage caméra + incrustations de scène, invoquer /short-form-video MAINTENANT et lui passer le brief. Son squelette en 4 couches est conçu pour ce format.

Sinon continuer :

Squelette

1. mkdir <dossier-projet>
2. Si un projet frère avec un format similaire existe, proposer de copier ses hyperframes.json + meta.json comme modèle. Sinon, depuis l'intérieur du dossier : npx hyperframes init
3. Éditer meta.json avec le slug, les dimensions, le fps de l'utilisateur.
4. Copier les actifs fournis dans <dossier-projet>/assets/.
5. Créer <dossier-projet>/assets/style-profile.md depuis l'Étape 3 — source unique de vérité pour palette/polices/logo.

Storyboard

Générer <dossier-projet>/STORYBOARD.md en utilisant le modèle dans references/storyboard-template.md. Chaque temps fort obtient :

Temps fort N — TITRE (début–fin, durée) — Concept en une phrase
Éléments visuels : [chaque élément, taille, animation, timing]
Langage du mouvement : [type de mouvement]
Easing utilisés : [3–4 easing GSAP distincts]
Sortie : [transition vers le temps fort suivant]
Audio : [ligne VO / SFX / couche musicale]

En haut du fichier : un tableau de timing avec scène · début · durée · fichier de composition.

Proposer une structure en trois actes :

• Acte 1 (accroche) ≈ 20% de la durée
• Acte 2 (corps) ≈ 55%
• Acte 3 (conclusion + outro avec pause de 4–6 secondes) ≈ 25%

(MOTION_PHILOSOPHY §0 Loi 9, §1.)

Mapper les intentions utilisateur → blocs catalogue : Read: references/catalog-intent-map.md

Point d'étape : montrer le storyboard + tableau de timing. Itérer jusqu'à approbation de l'utilisateur.

---

Étape 6 · Construire les compositions

Invoquer /hyperframes pour les règles du framework. Cette compétence possède le squelette et la discipline ; /hyperframes applique les règles.

Squelette de chaque sous-composition

<div data-composition-id="nom-scene" data-start="..." data-duration="...">
  <style>[data-composition-id="nom-scene"] { /* ciblé */ }</style>
  <!-- DOM -->
  <script>
    (function(){
      const SLOT_DURATION = ...;
      const tl = gsap.timeline({ paused: true });
      // ... tweens ...
      tl.to({}, { duration: SLOT_DURATION }, 0);   // ancrage — MOTION_PHILOSOPHY Loi 11
      window.__timelines["nom-scene"] = tl;
    })();
  </script>
</div>

Modèle complet + motif sous-titres + motif fond ambiant : Read: references/composition-scaffold.md

Règles de construction

• Fond ambiant sur data-track-index="0" pour toute la durée de la composition.
• Ouvertures typo cinétiques : décalage de 0,06–0,10 s par mot.
• Sous-titres comme frères du corps de la composition racine dans index.html, chacun avec data-track-index ≥ 20. Jamais à l'intérieur des timelines de scène (MOTION_PHILOSOPHY §3.13).
• Blocs catalogue installés via npx hyperframes add <nom>. Immédiatement limiter le CSS du bloc à [data-composition-id="..."] — les blocs catalogue sont livrés avec des règles html, body { ... } qui se propagent dans le document parent quand ils sont chargés comme sous-compositions.
• Vertical + visage caméra : envelopper le visage natif 1920×1080 dans une transformation (translate + scale) pour le mode moitié inférieure ou plein écran. (Si vous arrivez ici au lieu de /short-form-video, envisagez sérieusement la délégation.)
• Appliquer UNIQUEMENT ce que l'utilisateur a fourni. Sa palette, ses polices, son logo. N'injectez rien d'autre. S'il a choisi les valeurs par défaut de MOTION_PHILOSOPHY, récupérez la palette + paire de polices depuis references/style-intake.md.

Déterminisme

Pas de Math.random(), pas de Date.now(), pas de fetch() au rendu. Utilisez des PRNG à graine ou des hachages sin-harmoniques (MOTION_PHILOSOPHY §3.10).

---

Étape 7 · Lint → Prévisualisation Studio (PRÉVISUALISATION ÉTAPE 1 — OBLIGATOIRE)

1. npx hyperframes lint — corriger toutes les erreurs, trier les avertissements.
2. npx hyperframes preview en arrière-plan.
3. Attendre « Studio running » sur http://localhost:3002.
4. Donner à l'utilisateur l'URL plus les URL individuelles des compositions (http://localhost:3002/?comp=<id>). Si le projet a des blocs shader WebGL, commencer par les URL individuelles — le repli WebGL logiciel peut bloquer la composition maîtresse.
5. ATTENDRE un « ça a l'air bon, rends un brouillon » explicite avant de continuer. Le silence n'est pas une approbation.

Le rechargement à chaud est actif — les modifications apparaissent en direct.

---

Étape 8 · Rendu brouillon → vérification visuelle → prévisualisation MP4 → final

Rendu brouillon

npx hyperframes render --quality draft --output renders/<slug>-draft.mp4

Vérification visuelle (OBLIGATOIRE avant livraison)

Lint réussi ≠ design fonctionnel. Extraire les images et les visualiser.

1. mkdir -p renders/frames
2. Pour chaque moment clé de temps fort ET chaque transition :

   ffmpeg -y -ss <t> -i renders/<slug>-draft.mp4 -frames:v 1 -q:v 2 renders/frames/t<t>.png
   

3. Appeler l'outil Read sur chaque PNG. L'outil Read charge l'image dans le contexte — ne vous contentez pas de lister les noms de fichiers.
4. Confirmer par image : pas de visages coupés, mode visage correct par scène, texte lisible et dans la palette, pas de débordement, transitions tombant sur les mots prévus, pas d'images vides.
5. Si quelque chose ne va pas : corriger → re-rendre → revérifier. Ne livrez jamais un brouillon cassé.

Prévisualisation MP4 (PRÉVISUALISATION ÉTAPE 2 — OBLIGATOIRE)

npx serve renders -p 8080 -n

N'utilisez PAS http.server de Python — il ne gère pas les requêtes HTTP Range, donc le défilement est cassé.

Donner à l'utilisateur http://localhost:8080/<slug>-draft.mp4. ATTENDRE une validation explicite sur la lecture et la synchro audio.

Rendu final

npx hyperframes render --quality standard --output renders/<slug>-final.mp4

Signaler le chemin de sortie. Terminé.

Liste de vérification pré-vol + pré-livraison complète : Read: references/build-checklist.md

---

Non-négociables (structurels — ne pas assouplir)

• NE SAUTEZ PAS la PRÉVISUALISATION ÉTAPE 1 (Studio) ni la PRÉVISUALISATION ÉTAPE 2 (MP4 rendu). Deux étapes par construction, toujours.
• NE DITES PAS qu'un rendu est terminé tant que les images n'ont pas été extraites ET lues via l'outil Read.
• NE CONSTRUISEZ PAS ailleurs que dans un dossier projet dédié. Ne mettez jamais index.html à la racine de l'espace de travail.
• NE DEMANDEZ PAS les actifs à l'utilisateur avant d'avoir inventorié son espace de travail.
• NE SAUTEZ PAS l'ancrage tl.to({}, { duration: SLOT_DURATION }, 0) à la fin de chaque timeline de sous-composition. MOTION_PHILOSOPHY Loi 11.
• N'UTILISEZ PAS Math.random() / Date.now() dans la logique de rendu. Hachages à graine uniquement.
• N'AJOUTEZ PAS class="clip" aux balises <video>. Cela les casse.
• N'IMPOSEZ PAS une marque à l'utilisateur. Demandez d'abord ; revenez aux valeurs par défaut de MOTION_PHILOSOPHY seulement quand il refuse explicitement.

---

Références

• references/interview-questions.md — banque de questions complète par Étape
• references/style-intake.md — interview style + valeurs par défaut MOTION_PHILOSOPHY
• references/catalog-intent-map.md — « l'utilisateur dit X → installer Y »
• references/storyboard-template.md — modèle temps par temps + exemple travaillé
• references/composition-scaffold.md — styles ciblés + modèle IIFE GSAP
• references/build-checklist.md — portes pré-vol et pré-livraison

Externe (niveau espace de travail) :

• MOTION_PHILOSOPHY.md — la seule référence externe que cette compétence suppose exister. Base esthétique. Le repli se trouve dans references/style-intake.md si le fichier est manquant.

Compétences liées

• /hyperframes — règles du framework, invoquer à l'Étape 6
• /hyperframes-cli — init · lint · preview · render · transcribe · tts
• /hyperframes-registry — installer des blocs catalogue
• /gsap — référence d'animation GSAP
• /short-form-video — déléguer à l'Étape 5 pour le format visage caméra 9:16
• /website-to-hyperframes — déléguer à l'Étape 1 si l'entrée initiale est une URL