BeaverMakerLab/code-to-video

Code-to-Video Explainer Studio (Moteur Vidéo Animé Universel Piloté par le Code)

📘 Consultez le manuel d'utilisation complet : README.md (incluant vérification de l'environnement, guide des 6 styles, solutions de doublage, montage inter-agents et guide de dépannage).

Cette compétence permet à n'importe quel Agent de Codage IA capable de lire/écrire des fichiers et d'exécuter des commandes (tels que Claude Code, Codex, DeepSeek Harness, OpenHands/OpenClaw, Antigravity, Cursor, etc.) de jouer le rôle d'un réalisateur vidéo professionnel, programmeur d'animations et producteur. En utilisant le moteur de rendu vidéo local piloté par le code, elle transforme n'importe quel texte, dépôt de code, article de recherche ou idée créative en une vidéo explicative animée en haute définition 1080p 60fps avec une esthétique d'encre et de papier.

---

Les Trois Règles Fondamentales (À respecter impérativement par tous les Agents)

1. D'abord valider le storyboard, ensuite écrire le code (Human-in-the-Loop) : Tant que l'utilisateur n'a pas explicitement confirmé le storyboard.json, il est strictement interdit d'écrire du code de page spécifique ou de procéder au rendu final.
2. Le temps est une fonction pure $Visual = f(t)$ : Le code de la page doit être une fonction pure de la variable temps $t$. Il est interdit d'utiliser Math.random() (utilisez PV.rng(seed) pour l'aléatoire), Date.now(), les transitions CSS ou requestAnimationFrame.
3. Zone de sécurité pour les sous-titres (Safe Zone) : La taille du canevas est de 1920×1080. La zone inférieure $y > 900$ est réservée aux sous-titres ; il est interdit d'y placer des formes ou du texte. La zone d'activité principale du contenu doit rester dans x: 140~1780, y: 180~880.

---

Pipeline de Production (Processus Standard en Cinq Étapes)

Première étape : Digestion du contenu et conception du Storyboard

Lorsque l'utilisateur demande une vidéo (ou fournit du matériel) :

1. Établir une métaphore centrale : Trouvez une ou deux métaphores concrètes qui traversent toute la vidéo (par exemple, "projecteur" pour expliquer le mécanisme d'attention, "post-it sur un bureau" pour le cache, "réservoir et tuyaux" pour les équations de fluides).
2. Planifier la structure narrative :
   • Hook (accroche des 3 premières secondes) : Posez une question contre-intuitive ou un problème clé.
   • Intuition : Présentez la métaphore centrale.
   • Mechanism (analyse du principe) : Décomposez la formule ou les étapes clés.
   • Example & Numbers (exemple et calculs) : Parcourez des données concrètes.
   • Close (conclusion et synthèse) : Faites le lien avec le début, répondez à l'accroche.
3. Générer la structure du storyboard : Produisez un plan de storyboard de 4 à 8 pages, chaque page ayant un id, une section, un say (résumé du script) et 2 à 4 beats (actions spécifiques avec object, action, text, camera).
4. Demander la confirmation de l'utilisateur : Présentez le storyboard à l'utilisateur en demandant : "Le plan du storyboard est prêt. Veuillez vérifier la structure de chaque page et le rythme narratif. Si tout est correct, nous passerons à la phase de codage des pages."

Consultez la spécification détaillée et le modèle de structure : STORYBOARD_RULES.md

---

Deuxième étape : Génération du script et de la timeline (Script & Narration)

Après la validation du storyboard, créez le script.js :

1. Extrayez le texte parlé spécifique pour chaque page, décomposez-le en cues (phrases courtes pour sous-titres) de 16 caractères chinois maximum chacune.
2. Utilisez le moteur vocal (local CosyVoice 3 sur le port 9880, Edge-TTS, ou les clés API d'environnement VOLCENGINE_TTS_API_KEY / ELEVENLABS_API_KEY) pour générer l'audio de chaque phrase.
3. Extrayez les timestamps réels de lecture pour chaque cue : P.c(i) (moment de début), P.cw(i, 'mot clé') (moment où le mot est prononcé).

---

Troisième étape : Programmation des animations page par page (Page Drawing Code)

Chaque page correspond à un fichier pages/pNN.js. Utilisez l'API déclarative du moteur :

ENGINE.visual('p01', (P) => {
  P.title('① Intuition du principe de base', { accent: 'orange' });
  // Lie le début de la carte à la parole, phrase 0
  P.card(200, 260, 700, 480, { title: 'Caractéristiques d\'entrée', at: P.c(0) });
  // Déclenche la flèche et la surbrillance au mot spécifique
  P.arrow(920, 500, 1100, 500, { at: P.cw(1, 'transformation') });
  // Déduction progressive de la formule mathématique
  P.mathDecompose(1140, 400, 600, {
    title: 'Score d\'attention',
    terms: [
      { latex: 'Q K^T', name: 'Produit clé-requête', color: 'blue', at: P.c(2) },
      { latex: '\\sqrt{d_k}', name: 'Facteur d\'échelle', color: 'orange', at: P.c(3) }
    ]
  });
});

Astuce : Dans les environnements d'agents supportant les sous-agents ou les tâches parallèles, vous pouvez déléguer l'écriture de différentes pages à plusieurs sous-agents pour plus de rapidité. Consultez la syntaxe complète de l'API et la liste des composants : API.md

---

Quatrième étape : Boucle de vérification automatique de la géométrie et du visuel (Automated QA Loop)

Après avoir écrit le code, vous devez exécuter la vérification automatique. Ne la sautez surtout pas ! :

1. Exécutez l'outil de vérification dans le répertoire du projet :

   node engine/tools/check.mjs --only p01
   

2. Traitez les retours :
   • Si Collision detected ou Safe zone overlap apparaît :
   • Extrayez la Fix suggestion: ... de la sortie et appliquez directement les coordonnées suggérées en ajustant les valeurs dans pages/pNN.js.
3. Répétez la vérification jusqu'à ce que toutes les pages soient vertes (Passed).

---

Cinquième étape : Rendu vidéo multiprocessus sans tête en 1080p (Render)

Une fois toutes les pages validées, exécutez la commande de rendu parallèle :

# Rendu 16:9 paysage 1080p 60fps (avec accélération matérielle)
node engine/tools/render.mjs --fps 60 --workers 4 --hw

• Les fichiers de sortie se trouvent dans <répertoire_du_projet>/out/ :
  • <nom_du_projet>-with-subtitles.mp4 (version avec sous-titres bilingues précis)
  • <nom_du_projet>-no-subtitles.mp4 (version sans sous-titres)
  • Texte de publication et timestamps de chaque chapitre.

---

Mode d'exécution rapide : Génération automatique en une commande (CLI Run)

Si l'utilisateur souhaite une version brouillon entièrement automatique de bout en bout, utilisez le CLI automatisé intégré à la racine du projet :

# Exécution entièrement automatique (analyse doc -> storyboard -> génération pages -> rendu vidéo)
node apps/cli/dist/cli.js run <chemin_du_fichier_source> --style warm-story --duration 60

Ou lancez un serveur web pour un aperçu de la timeline en temps réel :

node apps/cli/dist/cli.js serve

---

Guide d'utilisation inter-plateformes pour les Agents (Universal Compatibility)

Cette compétence n'est liée à aucun environnement d'agent spécifique. Seuls un environnement Node.js et la capacité de lire/écrire des fichiers sont nécessaires :

• Claude Code : Référencez ce fichier dans CLAUDE.md à la racine du projet pour une activation globale, ou utilisez-le comme commande personnalisée.
• OpenHands / OpenClaw : Placez le répertoire de cette compétence dans le projet et déclarez-le dans AGENTS.md pour un montage automatique.
• DeepSeek Harness / Agent personnalisé : Injetez directement le contenu en tant que System Prompt ou contexte d'outil Skill Tool.
• Cursor / Windsurf : Invoquez via @SKILL.md dans la conversation.