metehan2236/3d-animator

Animateur 3D

Une invite comme "Fais une vidéo 3D cool" produit une scène terne, avec un éclairage plat et une caméra fixe, car le modèle prend des décisions par défaut sans aucune intention cinématographique. Ce skill impose ces décisions avant l'écriture du code et fournit l'infrastructure pour les mettre en œuvre.

Objectif : Un film livré sans erreurs techniques dès la première version, qui pourra être finalisé après quelques révisions. Pas la perfection, mais un point de départ solide et révisable. Ce qui garantit cela, ce n'est pas l'infrastructure, mais l'ordre des étapes ci-dessous ; ne sautez aucune étape.

Le format du projet est HyperFrames. Les règles de composition sont définies par hyperframes-core.

Par quel exemple commencer

Demande	Point de départ	À lire
Mouvement de personnes, véhicules, objets, action, histoire	assets/example-street-film/	references/motion.md
Narration en voix off, explication de concept, présentation	assets/example-chip-film/	references/film-grammar.md
Les deux	Prenez le film de rue, ajoutez le langage narratif	Les deux

Toujours lire : references/materials.md, references/craft.md, references/sound.md.

Conservez la structure, réécrivez le contenu en fonction du sujet. Ne transportez pas la rue, la balle ou la puce de l'exemple vers de nouveaux projets. Si une vidéo de référence est fournie, apprenez-en la technique, ne copiez pas son texte ou son montage. Sections de scene.js : décor, personnages, chorégraphie, caméra, apparence.

Conditions du film

S'il en manque une, le résultat ressemble à une "démo 3D", pas à un film :

1. Échelle réelle : 1 unité = 1 mètre. Le flou d'objectif, les ombres et les textures ne sont corrects qu'ainsi.
2. Espace plein et profond : Premier plan, plan moyen, arrière-plan et au-delà. Au moins 25 objets. Le héros est modélisé pièce par pièce.
3. Éclairage naturel : Lumière principale motivée + skyDome. Un objet sans ombre semble flotter.
4. Texture correcte : Chaque surface utilise M.* ou une méthode tout aussi rigoureuse. Aucune surface n'est unie.
5. Une histoire et une raison : Chaque mouvement a une raison. Un nouvel événement se produit environ toutes les 3 secondes.
6. Écriture caméra : Chaque plan a une seule fonction. L'objectif et le mouvement servent cette fonction.
7. Son : Enregistrements réels, musique, voix off. Chaque son est lié à une cause dans l'image.

Flux

1. Plan (shot-plan.md)

Avant d'écrire le code : un message en une phrase, le héros, la liste des décors, l'idée d'éclairage, la palette, la liste des textures et le tableau des plans.

Durée	Événement	Caméra (objectif, mouvement)	Son	Sous-titre
9.1–10.2	La balle glisse des mains de l'enfant	46mm, contre-plongée, f/3.2	Souffle court	Personne ne regarde la balle.

Si aucun format n'est demandé, utiliser 16:9 1920×1080. Pour une Reel verticale, mettre 1080×1920 et replanifier les cadrages. Si l'utilisateur a donné le sujet, n'attendez pas d'approbation, montrez brièvement le plan et continuez. Si une décision modifie fondamentalement le film (format, langue, exigence d'humains réalistes), demandez d'abord.

2. Configurer le projet

npx hyperframes init <nom> --resolution landscape --non-interactive

Copiez tous les fichiers de assets/rig/ et les fichiers de l'exemple choisi à la racine du projet.

3. Son, puis image

Les durées viennent de la parole, les temps de caméra en dépendent. Commencez par le son.

node <dossier-skill>/scripts/make-sfx.mjs assets/sfx <durée-secondes>

node <dossier-skill>/scripts/build-audio.mjs .

Le script écrit voiceToMusicDb, overrun, voiceClash, overlap et le niveau du mix. S'il se termine avec un code d'erreur, corrigez les temps. Voir references/sound.md pour la recherche de sources, les licences et le mix. Si la musique est introuvable ou la licence ne correspond pas, scripts/make-music.mjs génère une base à partir du code. Les enregistrements du film de rue ne sont pas dans le skill, la liste est dans assets/example-street-film/SOURCES.md. Lors de la première configuration :

py -3.12 -m venv "%USERPROFILE%\.cache\3d-animator-venv"

"%USERPROFILE%\.cache\3d-animator-venv\Scripts\python" -m pip install kokoro-onnx soundfile faster-whisper "av<16"

Définissez la variable d'environnement HYPERFRAMES_PYTHON pour pointer vers ce fichier python. Kokoro ne connaît pas le turc : pour le turc, avec l'autorisation de l'utilisateur, générez la voix via un autre fournisseur, placez-la dans voice/NN.wav et avec le même texte dans voice/NN.txt. Le script ne régénère pas cette paire.

4. Scène

Outil	Fonction
createFilm({canvas, width, height, fps, samples, bloom, environment, background})	Chaîne de rendu
film.setShots([...])	Liste des prises ; chaque at est une coupe. track: (t) => ({pos, look, lens, fstop, focus, roll}) suit un sujet en mouvement
film.setKeys([...])	Caméra unique sans coupe
film.onUpdate(t => ...)	Mouvement des objets et des personnages. Appelé par sous-image
film.onFrame(T => ...)	Éclairage, look, décisions de mode. Appelé une fois par image
film.look	exposure, saturation, contrast, blackPoint, lift, shadowTint, midTint, highlightTint, flash, grain, vignette, aberration, fade, invert, bloom, stylize
film.skyDome, film.softLight, film.skyBackdrop, film.bakeEnvironment	Éclairage naturel et réflexions
film.mirrorFloor(mesh)	Véritable réflexion pour sol mouillé et eau
film.sunThroughBlinds, film.shaft, film.dust, film.burst, film.sparks, film.screen, film.wire	Effets et détails
M.*, skinned, boxUV	Textures (references/materials.md)
createCharacter, walker, createCar, driver, createBicycle, rider, loadRigged	Acteurs (references/motion.md)
speedProfile, groundPath, bounces, springTrack, track, noise1, rng, EASE	Aides au mouvement
addCaptions(tl, el, LINES)	Sous-titres mot à mot

Règle immuable : Tout ce qui est visible est une fonction pure du temps. N'écrivez pas rotation.y += 0.01, écrivez rotation.y = t * 0.6. Les images sont demandées dans un ordre aléatoire et plusieurs fois. N'utilisez pas Date.now(), performance.now(), requestAnimationFrame et Math.random sans graine.

5. Test visuel

Mettez SAMPLES = 4 et capturez des images à chaque temps fort du film. Ne prenez pas moins de 15 images. setTextureScale(SAMPLES < 16 ? 0.5 : 1) réduit considérablement les temps de test, car chaque worker de rendu régénère toutes les textures à partir de zéro :

npx hyperframes check

npx hyperframes snapshot --at <t1>,<t2>,... --timeout 240000

Utilisez --angle top pour les conflits. Avec SAMPLES de 1 à 4, la lumière du ciel et la mise au point sont trompeuses : les ombres sont dures, la mise au point semble ponctuelle. Prenez les décisions de texture et d'éclairage avec 16.

Ouvrez et regardez les images. Texture : le relief est-il exagéré, y a-t-il des étirements, chaque surface est-elle texturée ? Cadrage : le sujet et la tête sont-ils coupés, la fonction de chaque plan est-elle lisible ? Éclairage : direction, ombre de contact, éblouissement. Mouvement : glissement du pied, traversée d'objet, objet suspendu dans les airs. Texte : le sous-titre est-il lisible sur un fond clair ?

Si une vidéo de référence existe, placez les mêmes moments côte à côte (scripts/look-stats.mjs donne une comparaison tonale numérique), la méthode d'analyse de la référence est dans references/film-grammar.md.

6. Brouillon, inspection, correction

npx hyperframes render --quality draft --output draft.mp4

node <dossier-skill>/scripts/qa-film.mjs draft.mp4 --script script.json --whisper <python> --earshot <python>

Le navigateur extrait les images dans qa/sheet-*.jpg (4 images par seconde) et signale les images noires, les gelures, les éclairs d'une seule image, le niveau sonore, les mots inaudibles et le bulletin earshot. Regardez chaque page une par une. Même si la machine dit que tout est propre, les erreurs y sont visibles. Ensuite, ouvrez chaque plan rapproché en pleine taille (references/materials.md, contrôle image par image) : une image qui semble propre en petit ne l'est souvent pas en grand. Dans ce film, la plupart des erreurs n'apparaissent que de cette façon.

Corrigez chaque constatation avant de passer à la qualité finale. Ne re-rendez que la partie défectueuse :

npx hyperframes render --quality draft --start 18 --end 21 --output partie.mp4

7. Final

SAMPLES 24–32. L'échelle d'une scène de film de rue prend quelques minutes sur une RTX 4060 ; si la ligne de résumé affiche software gpu, cela prend beaucoup plus de temps, prévenez l'utilisateur dès le début.

npx hyperframes render --quality delivery --output final.mp4

Répétez l'inspection sur le film final, car un faible SAMPLES cache les erreurs de mise au point. Si earshot n'est pas installé, demandez la permission de l'installer (environ 1–3 Go). Le paquet earshot sur PyPI est un autre paquet ; la bonne source est github.com/Leonxlnx/earshot. Sur Windows, installez l'environnement virtuel dans un chemin court, torch a des problèmes avec les chemins longs.

Livraison

Dites ceci : ce que vous avez fait, ce que vous avez vérifié, ce que vous n'avez pas pu vérifier et ce qui manque encore. Listez les sources audio et musicales utilisées avec leurs licences. Même si le bulletin est élevé, launch-grade ne signifie pas que le film est beau. Le goût et le naturel de la voix off appartiennent à l'utilisateur.

Révision

Lorsque l'utilisateur demande une révision :

1. Transformez la note en plan : Dans quel plan, quoi, comment cela devrait-il apparaître. Si c'est vague, faites l'interprétation la plus probable et dites-la, ne posez pas de question pour chaque note.
2. Modifiez le bon endroit : Texture M.*, caméra setShots, timing via une seule constante (BRAKE_T), tonalité via film.look, son via script.json. Tout ce qui est lié à une constante se déplace ensemble.
3. Ne rendez que cette partie : avec --start et --end. Si seul le son a changé, ne rendez pas l'image (references/sound.md).
4. Montrez la partie côte à côte avec sa version précédente, puis lancez le rendu complet après approbation.
5. Écrivez la leçon permanente dans le skill : Si un type d'erreur se reproduit une deuxième fois, ajoutez-le à ce fichier ou à la référence concernée.

Humain réaliste : référence + vidéo IA

Ce film sert de référence à un outil de vidéo IA, l'image finale étant produite par cet outil. L'installation n'a pas encore été testée de bout en bout ; lors de la première utilisation, testez avec un seul plan et montrez le résultat à l'utilisateur.

1. Ne mettez en place que le blocking : Cadrage, mouvement de caméra, qui est où, quand. Ne perdez pas de temps sur les détails des personnages et les textures fines.
2. Donnez chaque plan séparément : Les outils IA sont plus cohérents avec des clips courts. Rendez plan par plan avec --start et --end. Désactivez les sous-titres ; mettez à zéro les valeurs de grain, d'aberration et de vignette. L'outil interprète les textes et les effets comme faisant partie de l'image réelle.
3. Fixez l'apparence : Convertissez d'abord la première image du plan en une image réaliste. Gardez les références du personnage et du décor cohérentes dans tous les plans, passez à la vidéo après approbation.
4. Dites le coût à l'avance : Indiquez quel outil, pour combien de plans et le crédit estimé, obtenez l'approbation. Vérifiez les outils disponibles à ce moment-là ; ne les présupposez pas.
5. Vérifiez : Images en pleine taille et points de coupe : visage, main, texte sur plaque et panneau, changement de vêtement d'un plan à l'autre. Si le mouvement s'éloigne de la chorégraphie, réduisez la puissance de transformation.
6. Terminez le son ici : Le son et les sous-titres restent dans cette ligne avec script.json. Vérifiez la durée des clips sortants, si elle a changé, ajustez les temps audio à la nouvelle durée.

Limites

Dites-le au début, pas à la fin :

• Personnages stylisés : Qualité de film d'animation. Pas de photoréalisme, de jeu d'acteur facial ou de bouche qui parle. Cela paraît étrange en plan rapproché. Si des humains réalistes sont nécessaires, utilisez la voie de référence ci-dessous ; dans les films sans humains, faites du héros un objet ou un véhicule, maintenez les humains à distance.
• La physique est dirigée par la direction artistique : Elle est écrite pour l'histoire, ce n'est pas une simulation réelle. Pas de simulation de tissu, de cheveux ou de fluide ; l'eau est imitée avec des particules.
• Le son synthétique généré par code sonne synthétique. Les enregistrements réels nécessitent une autorisation.
• La voix off en turc nécessite une voix externe.