comfy-h3-render-core

ComfyUI H3 Render Core (Cœur de rendu physique H3 et orchestration)

Positionnement dans la pipeline : Étape centrale de génération physique du court métrage. Principes fondamentaux : Ne pas coder en dur les numéros de nœuds ComfyUI, prévenir rigoureusement le verrouillage du pilote WDDM sous Windows, appliquer le verrouillage de la parole pour un seul locuteur et les vérifications de sécurité des dimensions de l'espace latent.

---

1. Contrat d'exécution et entrées/sorties

• Entrées :
  1. plan.json (contenant les mouvements de caméra, les dialogues, le timing sur 175 images) ;
  2. Images clés de l'étape 2 : segments/{seg_id}_keyframe.png ;
  3. style_bible.json.
• Sorties :
  1. Vidéo générée nativement par H3 : segments/{seg_id}.mp4 (avec son et image natifs) ;
  2. Journal de surveillance de l'état de la mémoire GPU et registre des temps de rendu.

---

2. SOP dure : Trois lois physiques anti-accident (avec exemples numériques et contre-exemples d'erreurs)

2.1 Loi n°1 : Règle de divisibilité par 32 de la largeur de l'espace latent (prévention des plantages de l'espace latent VAE)

• Phénomène/Erreur : RuntimeError: shape '[1, 24, 1, 1, 15, 2, 26, 2]' is invalid for input of size 38160
• Cause racine : Les dimensions des patches 3D de MiniMax H3 exigent que la largeur soit divisible par 16, et que le quotient soit pair (soit width % 32 == 0).
• Critère et action :
  • Interdit : 848×480 (848/16=53 est impair, non divisible par patch=2, plantage garanti !) ;
  • Verrouillage obligatoire : Pour le format large standard, utiliser 832×480 (832/16=52 est pair, 52/2=26, division parfaite !).

2.2 Loi n°2 : Défense contre le verrouillage du mutex du pilote WDDM sous Windows (prévention d'un ralentissement de 15×)

• Phénomène : Sous Windows, après activation de cudaMallocAsync ou du transfert asynchrone multi-flux (async-offload), un échantillonnage unique passe de 40 secondes à 600 secondes (durée totale par segment jusqu'à 70 minutes).
• Cause racine : Le modèle de pilote WDDM de Windows, lors du transfert de poids importants entre flux CUDA, provoque une grave contention de verrouillage mutex du noyau (Mutex Lock Contention).
• Action (Paramètres de démarrage dorés de ComfyUI) :

  python <COMFYUI_PATH>/main.py --disable-auto-launch --disable-mmap --disable-cuda-malloc --disable-async-offload --listen 127.0.0.1 --port 8188
  

  En utilisant le cache natif et l'ordonnancement mono-flux, on évite le verrouillage du pilote, la durée de génération par segment se stabilise à 350 secondes (5,8 minutes).

2.3 Loi n°3 : Verrouillage de la parole pour un seul locuteur et assemblage des instructions de silence (élimination des mouvements de bouche généralisés)

Lors de la construction de [Subject 1] et [Action 1], l'assemblage séparé doit être strictement appliqué :

• [Subject 1] : Primary speaker: [SpeakerName], alongside [ListenerName] (silent listener).
• Primitive centrale de [Action 1] :

  Only [SpeakerName] is actively speaking with natural, synchronized Mandarin lip movement, [Action]. 
  Crucial requirement: [ListenerName] remains strictly silent with lips tightly sealed and mouth completely closed, neither speaking nor making any mouth motions, showing a tense glare. 
  In the final 1.2 seconds, all characters firmly close their mouths, ending on a tense silent glare.
  

---

3. SOP dure : Protection contre la fragmentation mémoire GPU et reprise après interruption

1. Nettoyage mémoire GPU entre les plans : Après le rendu de chaque plan, appeler l'endpoint ComfyUI /free :

   payload = {"unload_models": False, "free_memory": True}
   

   Vider le cache des tenseurs 3D intermédiaires de l'espace latent de PyTorch pour éviter l'accumulation d'OOM lors d'une production continue de longue durée.
2. Reprise après interruption et évitement du rendu redondant : Détecter segments/{seg_id}.mp4. Si le fichier existe déjà et a une taille supérieure à 100 Ko, imprimer directement [Réutilisation] et passer à l'étape suivante, permettant une reprise quasi instantanée après interruption.

---

4. Scripts d'outils dédiés

• Moteur d'assemblage et d'ordonnancement du graphe d'exécution H3 : python scripts/h3_render_orchestrator.py --plan plan.json --server 127.0.0.1:8188