igm61799-cloud/voiceover-to-animation

Voix off → court métrage animé 2D codé

Vous réalisez un court métrage, pas un diaporama. La narration est fixe ; votre travail consiste à inventer ce que le spectateur voit à chaque instant, à le dessiner en code, et à livrer un MP4 dont les coupes et les sauts visuels tombent exactement sur les bons mots.

L'ensemble du pipeline est déterministe : chaque scène est une fonction pure du temps, donc n'importe quelle image peut être rendue indépendamment. Cette propriété vous offre tout le reste — instantanés pour la révision, rendu parallèle, synchronisation audio parfaite.

Ce dont vous avez besoin sur la machine

Vérifiez ces éléments avant de commencer ; ce sont les seules pièces mobiles.

python -c "import faster_whisper, playwright, PIL; print('ok')"
ffmpeg -version

Éléments manquants : pip install faster-whisper playwright pillow, puis python -m playwright install chromium. ffmpeg doit être dans le PATH. Si quelque chose ne peut pas être installé, dites à l'utilisateur ce qui manque plutôt que d'adopter une approche moins performante.

Le flux de travail

Gardez la vue de l'utilisateur simple : il vous a donné un audio et veut un film. Suivez ces étapes dans l'ordre et tenez une liste de tâches visible.

1. Écoutez d'abord : les timings des mots

python <skill>/scripts/transcribe.py voiceover.mp3 work

Cela imprime les phrases avec les heures de début et de fin et chaque mot sous la forme mot@début, et enregistre work/words.json. Tout ce qui suit est planifié en fonction de ces nombres. Notez la durée totale.

2. Configurez le projet à côté de l'audio

Copiez <skill>/assets/template/ dans le dossier de travail pour qu'il ressemble à ceci :

voiceover.mp3
render.py
src/index.html  src/engine.js  src/scenes.js  src/main.js

Lisez src/engine.js une fois (c'est court) et parcourez references/engine-api.md pour savoir ce que vous avez déjà : easing, aléatoire basé sur une graine, une caméra, dessin partiel de chemins, et motifs de type gravure (nuages, pluie, éclairs, fumée, horizons).

3. Décidez la direction artistique, puis storyboardez en fonction des mots

Choisissez UN langage visuel et tenez-le pour tout le film : une petite palette (cinq ou six couleurs), un traitement pour les bords et la texture, une façon de dessiner les personnages. Le modèle fourni un aspect linogravure/gravure (papier os, encres marine, vermillon, or, bords découpés à la main qui tremblent). Utilisez-le, ou redéfinissez-le en changeant la palette dans scenes.js et les commutateurs POST — mais ne mélangez pas les styles entre les scènes. La variété provient de la couleur qui domine chaque scène (une scène de nuit, une scène de papier, une scène rouge), pas du changement des règles.

Ensuite, écrivez le storyboard avant d'écrire le code : un tableau de plans avec les heures de début et de fin absolues, les mots que chaque plan couvre, ce qui est à l'écran, et le mot exact sur lequel chaque battement tombe. Lisez references/storyboarding.md pour savoir comment transformer la narration en images — c'est la partie qui décide si le film est bon.

La version courte :

• Une idée par phrase. Une phrase à trois propositions donne généralement trois plans ou trois battements à l'intérieur d'un seul plan.
• Montrez la chose, ne la légendez pas. Un texte à l'écran qui répète la narration pousse le spectateur à lire au lieu de regarder. Par défaut, pas de texte du tout ; les noms, les données réelles et une courte étiquette neutre sur un graphique sont les exceptions. Si l'utilisateur a indiqué des préférences de texte, celles-ci priment.
• Donnez une colonne vertébrale au film : un personnage ou motif récurrent, et un rappel à la fin de quelque chose du début.
• Changez d'échelle et de caméra intentionnellement : plan large, gros plan, diagramme, carte, coupe transversale. Deux plans consécutifs ne doivent pas avoir la même composition.
• Si la narration se termine par une chute, ajoutez 1 à 2 secondes de queue silencieuse après le dernier mot pour que l'image finale puisse atterrir. render.py ajoute un padding à l'audio.

4. Construisez une scène de bout en bout avant d'écrire les autres

Écrivez le premier plan dans src/scenes.js, enregistrez-le dans SHOTS, et regardez-le :

python render.py stills 0.3,1.5,2.9 first

Ouvrez ensuite work/first.png avec l'outil de lecture. Faites cela avant de coder les autres scènes : cela prouve que le pipeline fonctionne et, plus important, vous permet de juger le style pendant qu'il est encore peu coûteux de le changer.

5. Écrivez les scènes restantes, quelques-unes à la fois

Règles qui maintiennent le système en état de marche (chacune existe parce que la violer provoque une défaillance spécifique) :

• Fonctions pures du temps. Un plan est function nom(g, t, u) où t est le temps absolu en secondes et u le temps depuis le début du plan. Pas de variables qui s'accumulent entre les images, pas de Math.random(), pas de Date. Utilisez hash(n), noise1(x), rng(graine). Les images sont rendues dans le désordre par plusieurs navigateurs à la fois ; tout ce qui est avec état se manifeste par du scintillement ou des morceaux qui ne correspondent pas.
• Animez avec des temps absolus. Écrivez E.out(seg(t, 12.62, 13.1)), en utilisant des nombres directement issus de la liste de mots. Lorsque le montage change, les battements restent sur leurs mots.
• Tout bouge un peu. Une image fixe est perçue comme un bug. Donnez à chaque plan un lent mouvement de caméra (un zoom de 1 + u * .01 suffit) et un mouvement secondaire (pluie, fumée, un objet qui se balance).
• Easez tout. E.out pour les arrivées, E.inOut pour les mouvements de caméra, E.back pour les pops, E.bounce pour les atterrissages. Le mouvement linéaire a l'air mécanique.
• Dessinez le monde plus grand que le cadre à chaque fois que la caméra dézoome ou tremble ; remplissez les fonds et le sol bien au-delà de 0..1920 pour qu'aucun bord ne soit jamais exposé.
• Les impacts reçoivent trois choses : un flash plein écran de 2-3 images, un shake qui s'estompe, et quelque chose qui réagit (un nuage, un recul, un changement de couleur).
• Divisez le code des scènes dans des fichiers (s1.js, s2.js, ...) dès qu'un fichier dépasse quelques centaines de lignes, et ajoutez-les dans index.html avant scenes.js.

Écrivez deux ou trois plans, générez une planche contact, regardez, corrigez, continuez. N'écrivez pas tout le film à l'aveugle.

6. Révisez avec les images fixes — ce sont vos yeux

Vous ne pouvez pas regarder la vidéo, donc la planche contact est votre révision. Pour chaque plan, échantillonnez au moins le début, le milieu de l'action principale et la fin, plus l'image exacte de chaque battement :

python render.py stills 12.2,13.3,14.3,15.4,16.5 act2     # jusqu'à ~16 timestamps par planche
python render.py sheet 4                                   # film entier, une image toutes les 4 s

Lisez le PNG et vérifiez, plan par plan : Le sujet est-il assez grand pour être lu en un coup d'œil ? Y a-t-il quelque chose de coupé, qui se chevauche ou qui flotte ? La chose importante a-t-elle du contraste par rapport à ce qui est derrière elle ? Cela a-t-il l'air conçu, ou la moitié du cadre est-elle vide ? Corrigez et re-rendez les mêmes timestamps. references/pitfalls.md liste les erreurs faciles à commettre et difficiles à remarquer.

Les erreurs de page sont affichées par render.py sous forme de lignes PAGE ERROR: — une image noire ou à moitié dessinée indique généralement une exception dans ce plan.

7. Rendu et vérification

python render.py full --workers 8

Lancez-le en arrière-plan ; un film de 70 s représente environ 2 100 images et prend quelques minutes. Il écrit output.mp4 (1920×1080, H.264 + AAC, audio étendu à la durée totale). Vérifiez ensuite le fichier lui-même, pas seulement les images fixes :

ffprobe -v error -show_entries format=duration:stream=codec_name,width,height -of default=nw=1 output.mp4
python render.py sheet 6

Confirmez la durée, la présence d'un flux audio, et que la planche d'ensemble n'a pas d'images vides. Dites clairement dans votre rapport que vous avez vérifié les images fixes et les propriétés du fichier mais que vous ne l'avez pas regardé en mouvement — l'utilisateur devrait le regarder une fois.

8. Remise

Donnez à l'utilisateur le chemin vers output.mp4, la planche d'ensemble, et une ligne sur la façon de re-rendre après des modifications. src/index.html ouvert dans un navigateur est un lecteur en direct avec l'audio, ce qui est le moyen le plus rapide pour lui de vérifier le timing.

Son

Livrez la voix off uniquement, sauf si l'utilisateur a demandé de la musique ou des effets sonores. Si c'est le cas, ajoutez-les comme entrées ffmpeg supplémentaires dans le multiplexage final, chronométrées à partir de la même liste de battements que celle utilisée pour les visuels.

Fichiers de référence

• references/storyboarding.md — transformer la narration en plans ; placement des battements ; métaphores visuelles ; ce qui rend une scène conçue. À lire avant l'étape 3.
• references/engine-api.md — chaque aide dans engine.js avec une utilisation en une ligne. À lire avant l'étape 5.
• references/pitfalls.md — modes de défaillance découverts à la dure, avec des correctifs. À lire avant l'étape 6.
• references/example-bells/ — un film complet de 71 secondes (16 plans, ~900 lignes de code de scène) avec son storyboard. Lisez storyboard.md pour voir le niveau de planification attendu ; ouvrez les fichiers src/s*.js lorsque vous voulez voir comment un effet spécifique a été construit (une caméra qui suit un personnage grimpant, une explosion, une carte, une plume qui dessine une ligne, un œil qui se plisse).