Vidéo Par Code

Compétence Vidéo par Code

Une boîte à outils exécutable et un flux de production pour les équipes humain–agent créant des vidéos déterministes en code. Tout le code des scènes reste à l'intérieur du dépôt ou de l'espace de travail du projet ; tous les médias générés, prises audio, images fixes et reçus de vérification résident dans un répertoire $PROD externe explicite.

Ordre de travail : brief → audio & timing → style & prompt → 3 images de conception → code de scène → passerelle déterminisme & limites de texte → rendu complet → vérification & planche contact → reçu de livraison

---

1. Environnement et Test de Vérification Rapide

Avant de construire un nouveau film, assurez-vous que les dépendances de base sont installées et que le test de vérification rapide de 4 secondes passe depuis la racine du dépôt :

cd starter && npm ci && cd ..
node tests/runtime-contract.mjs

---

2. Répertoire de Production et Intention (RUNBOOK.md §1–2)

1. Choisissez un répertoire de production absolu en dehors de l'extraction du code :

   PROD="/chemin/absolu/vers/sorties-video/<slug-projet>"
   mkdir -p "$PROD"/{audio,analysis,stills,renders,checks}
   

2. Copiez templates/brief.md vers "$PROD/brief.md" et remplissez le public, le message clé, le rapport hauteur/largeur (1920x1080 paysage ou 1080x1920 portrait), la durée, la source voix/musique et les marges de la zone de sécurité.

---

3. Identité Audio et Timing (docs/04-music-audio-and-timing.md, docs/05-narration-and-captions.md)

N'animez jamais avec des horodatages estimés. Mesurez d'abord le fichier audio réel et enregistrez son hachage SHA-256 :

uv run tools/timing/audio-identity.py "$PROD/audio/source.wav" \
  --out "$PROD/analysis/identity.json" --copy-wav "$PROD/analysis/analysis.wav"

• Narration parlée :
  • Synthétisez via le TTS local Kokoro ONNX (avec fusion de fragments de mots < 4 et dictionnaire phonétique --say say.json) : uv run tools/timing/kokoro-narrate.py script.txt --out-dir "$PROD/audio" --voice af_heart --say say.json
  • Vérifiez l'aller-retour de l'audio parlé via le whisper-cli local : uv run tools/verify/verify-narration.py "$PROD/audio/narration.wav" "$PROD/audio/timing.json"
  • Vérifiez les scripts/paroles pour le soulèvement de n-gramme textuel par rapport au texte de référence : python3 tools/verify/check-lift.py candidate.txt reference.txt
• Pistes réactives musique / parole / stem :
  • Séparez 6 stems via Demucs (vocals, drums, bass, guitar, piano, other) et normalisez en WAV 44,1 kHz : uv run --python 3.12 tools/timing/separate-stems.py "$PROD/audio/song.mp3" --out-dir "$PROD/analysis"
  • Extrayez les enveloppes de stem à 120 Hz, le temps musical monotone tau, la phase de temps/mesure, les silences, features.f32 et la hauteur/vibrato de guitare à 100 ips : uv run --python 3.12 tools/timing/analyze-stems.py "$PROD/analysis" --fps 120 --stem-pitch
  • Alignez les paroles au niveau du mot (whisper-cli, mlx-whisper, faster-whisper, ou déformation d'énergie de bande vocale acoustic) : uv run tools/timing/align-words.py "$PROD/analysis/stems/vocals.wav" --script lyrics.txt --backend whisper-cli --out "$PROD/analysis/words.json"
  • Repères légers de fichier unique / grille de temps / enveloppe visualiseur :
    • uv run tools/timing/cue-extract.py "$PROD/audio/song.mp3" --out "$PROD/analysis/cues.json"
    • uv run --python 3.12 tools/timing/beat-grid.py "$PROD/analysis/analysis.wav" --out "$PROD/analysis/beats.json"
    • python3 tools/build-visualizer.py "$PROD/analysis/analysis.wav" --out "$PROD/analysis/features.js"

---

4. Sélection de Style et Assemblage de Prompt (prompts/README.md)

Parcourez prompts/styles/INDEX.md (86 cartes de style visuel rédigées réparties dans 13 familles) et prompts/briefs/ (5 briefs de format : explainer-voiceover, vertical-short, lyric-video, instrumental-visualizer, data-story).

Assemblez la spécification combinée pour votre style et votre brief choisis :

python3 tools/build-prompt.py <id-style> --brief <id-brief> --out "$PROD/style-prompt.md"

---

5. Contrat de Création de Scène (lib/API.md, docs/06-building-scenes.md, docs/12-advanced-engines-and-benchmarks.md)

Chaque page HTML de scène charge lib/harness.js (window.H) et éventuellement :

• lib/sound.js (window.SOUND) — synthèse audio Web procédurale
• lib/features.js (window.FEATURES) — curseur de stem binaire features.f32 à 120 Hz, impulsion de début réfractaire, tau(t) monotone et recherche de paroles words.json
• lib/ink-doodle.js (window.INK) — ligne d'ébullition déterministe à 8 ips, primitives de doodle ondulées, écriture marker en MAJUSCULES ancrée à gauche, et caméra Ken Burns plate
• lib/webgl-post.js (createPost) — post-traitement Three.js à 4 étages (FxOverShader, UnrealBloomPass, FinalGradeShader avec ACES / paperMode, inversion d'impact luma seulement, glitch, secousse, grain, et superposition d'interface utilisateur nette)

Chaque page expose :

• <canvas id="c" width="1920" height="1080"></canvas> (ou 1080 × 1920 pour le vertical)
• window.DURATION (secondes) et window.FPS (par défaut 30)
• window.__ready (Promise se résolvant après le chargement des polices et des plaques hors écran mises en cache)
• window.__renderFrame = (t) => { ... } — fonction pure de t en secondes.
  • Commencez chaque image par ctx.reset() (ou save()/restore() équilibré).
  • Utilisez H.rng(seed) et H.noise(seed) en dehors de la boucle d'image ; ne faites jamais avancer l'état mutable entre les images.
  • Mettez en cache les textures de papier/surface une fois via H.paperTexture(...) ou H.offscreen(key, w, h, fn).
  • Exposez window.__textBounds = () => [...] pour le texte critique de l'histoire ({text, critical: true, left, right, top, bottom}) afin que les vérifications automatisées de zone de sécurité puissent vérifier chaque image.
• window.scoreSound = (k) => { ... } — planifie les événements sonores procéduraux à des horodatages fixes de la timeline (supprime automatiquement les fonds sonores/musique lorsque --voice est fourni).

Règles Clés de Production Issues des Tests

• Marges de zone de sécurité et poids de police : Sur macOS Chrome, Arial ne fournit que les poids 400 et 700 (600 passe à 700 Gras et élargit les lignes d'environ ~9%). Auditez toujours measureText(s).actualBoundingBox* sur toutes les images (x: 80..960, y: 190..1640 pour les courts verticaux 1080x1920).
• Styles de caméra continue (transit-map, pan-and-zoom) : Commencez l'interpolation de la caméra à beat[i].start (jamais beat[i].start - preRoll lorsque i bascule à beat[i].start, ce qui provoque un saut d'une image), atténuez les superpositions locales au temps sur 0.20 s, et protégez les étiquettes dans l'espace mondial afin qu'elles ne soient dessinées que lorsqu'elles se trouvent à l'intérieur de la zone de visualisation de la carte découpée.

---

6. Rendu des Images Fixes, Vérification du Déterminisme et Rendu Maître (docs/07-rendering.md)

1. Passerelle de Déterminisme de Recherche :

   node starter/determinism.mjs path/to/film.html
   

2. Passerelle d'Images Fixes de Conception (inspectez l'ouverture, le milieu dense et les images de fin avant le rendu complet) :

   node starter/render.mjs path/to/film.html --stills 1.5,12.0,24.0 --outdir "$PROD/stills"
   

3. Rendu MP4 Complet :
   • Rendu Playwright monoworker de référence (30 ips Canvas2D + audio procédural par défaut) :

     node starter/render.mjs path/to/film.html \
       --out "$PROD/renders/master.mp4" --fps 30 --audio page \
       --voice "$PROD/audio/narration.wav"
     

   • Rendu GPU multiworker WebSocket (60 ips Three.js / WebGL / typographie cinétique) :

     node tools/render/parallel-ws-render.mjs \
       --url "http://127.0.0.1:5173/?capture=1" --duration <DURATION> --fps 60 --workers 4 \
       --audio "$PROD/analysis/analysis.wav" --out "$PROD/renders/master.mp4"
     

   • Rendu Python + Pillow rawvideo sans navigateur (classeurs avec légendes et tutoriels) :

     uv run tools/render/workbook-render.py \
       --spec workbook.json --audio "$PROD/audio/narration.wav" --out-dir "$PROD/renders"
     

---

7. Passerelles de Vérification Obligatoires (docs/08-verification.md)

Chaque production doit exécuter et enregistrer ces vérifications dans "$PROD/checks/" avant la remise :

1. Passerelle Flux, Décodage, Synchronisation et Volume sonore :

   uv run tools/verify/verify-video.py "$PROD/renders/master.mp4" \
     --expect-seconds <DURATION> --fps 30 --width <W> --height <H> \
     --json "$PROD/checks/verify-video.json"
   

2. Inspection Visuelle de la Planche Contact :

   uv run tools/verify/contact-sheet.py "$PROD/renders/master.mp4" \
     "$PROD/checks/contact-sheet.jpg" --n 16 --cols 4 --tile-width 270
   

   Inspectez visuellement contact-sheet.jpg et les images fixes de la scène pour détecter le recadrage du texte, les collisions d'étiquettes ou les images vides/figées non intentionnelles.
3. Audit de Dureté des Transitions et Coupes :

   uv run tools/verify/cut-harshness.py "$PROD/renders/master.mp4" \
     --top 15 --json "$PROD/checks/cut-harshness.json"
   

4. Diagnostics d'Apparence et de Palette :

   uv run tools/verify/measure-look.py "$PROD/renders/master.mp4" \
     --samples 16 --json "$PROD/checks/measure-look.json"
   

5. Audit des Limites de Texte sur Toutes les Images : Suivez le modèle dans tests/layout.mjs pour vérifier les limites d'encre fillText et window.__textBounds() sur chaque image 0 .. frames-1.

---

8. Emballage et Livraison (RUNBOOK.md §12)

Complétez "$PROD/qa.md" (à partir de templates/qa.md) et "$PROD/delivery.md" (à partir de templates/delivery.md). Rapportez les vérifications machine (dispositions PASS/WARN) séparément de l'approbation créative humaine visuelle et auditive.

Références Clés

• README.md — Guide de démarrage rapide et index des chapitres
• RUNBOOK.md — Liste de contrôle de production humain–agent en 12 étapes
• lib/API.md — Contrat exact des graphismes H et de l'audio procédural SOUND
• examples/README.md — Exemples travaillés en paysage, portrait et études de style
• docs/10-pitfalls.md — Tableau symptôme → cause → réparation