comfy-h3-render-core

ComfyUI H3 Render Core (Renderizado Físico y Programación H3)

Posición del proceso: Proceso central de generación física de videos cortos. Principios fundamentales: No hardcodear números de nodo de ComfyUI, prevenir estrictamente el bloqueo del controlador WDDM en Windows, y aplicar forzosamente el bloqueo de pronunciación de un solo hablante y la verificación de seguridad del tamaño del espacio latente.

---

1. Contrato de Ejecución y Entrada/Salida

• Entrada:
  1. plan.json (incluye movimiento de cámara, diálogo, secuencia temporal de 175 fotogramas);
  2. Imagen clave de fotograma fijo del segundo proceso: segments/{seg_id}_keyframe.png;
  3. style_bible.json.
• Salida:
  1. Video generado nativamente por H3: segments/{seg_id}.mp4 (con audio y video nativos);
  2. Registro de monitoreo del estado de la memoria de video y registro de tiempo de renderizado.

---

2. SOP Básico: Tres Leyes Físicas Contra Fallos (con Características Numéricas y Ejemplos de Error)

2.1 Primera Ley: Regla de Divisibilidad por 32 del Tamaño del Espacio Latente (Prevenir el Colapso del Espacio Latente de VAE)

• Fenómeno/Error: RuntimeError: shape '[1, 24, 1, 1, 15, 2, 26, 2]' is invalid for input of size 38160
• Causa Raíz: El tamaño del parche 3D de MiniMax H3 requiere que el ancho sea divisible por 16, y el cociente debe ser par (es decir, width % 32 == 0).
• Criterio y Acción:
  • Prohibido usar: 848×480 (848/16=53 es impar, no divisible por parche=2, ¡fallará!);
  • Bloqueo forzoso: Para pantalla ancha estándar, bloquear a 832×480 (832/16=52 es par, 52/2=26, ¡divisible perfectamente!).

2.2 Segunda Ley: Defensa Contra el Bloqueo del Mutex del Controlador WDDM en Windows (Prevenir Lentitud Extrema de 15x)

• Fenómeno: En Windows, al habilitar cudaMallocAsync o transferencia asíncrona multi-flujo (async-offload), el muestreo de un solo paso pasa de 40 segundos a 600 segundos (un solo segmento puede tardar hasta 70 minutos).
• Causa Raíz: El modelo de controlador WDDM de Windows, al transferir pesos grandes a través de flujos CUDA, genera una grave contención de bloqueo de mutex del kernel (Mutex Lock Contention).
• Acción (Parámetros de inicio dorados 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
  

  Usar caché nativa y programación de un solo flujo para evitar el bloqueo del controlador, manteniendo el tiempo de generación de un solo segmento estable en 350 segundos (5.8 minutos).

2.3 Tercera Ley: Ensamblaje de Instrucciones de Pronunciación de un Solo Hablante y Silencio General (Eliminar el Movimiento de Labios de Todos)

Al construir [Subject 1] y [Action 1], se debe aplicar forzosamente un ensamblaje separado:

• [Subject 1]: Primary speaker: [SpeakerName], alongside [ListenerName] (silent listener).
• [Action 1] Primitiva central:

  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 Básico: Protección Contra la Fragmentación de la Memoria de Video y Reanudación desde Puntos de Control

1. Recuperación de memoria de video entre tomas: Después de renderizar cada toma, se debe llamar al endpoint /free de ComfyUI:

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

   Vaciar el caché de tensores del espacio latente 3D intermedio de PyTorch para evitar OOM acumulativo en producción continua de larga duración.
2. Protección contra renderizado duplicado en reanudación: Detectar segments/{seg_id}.mp4. Si el archivo ya existe y su tamaño es mayor a 100KB, imprimir directamente [Reutilizar] y saltar, permitiendo una reanudación en segundos desde el punto de control.

---

4. Script de Herramienta Exclusivo

• Motor de Ensamblaje y Programación de Grafos de Ejecución H3: python scripts/h3_render_orchestrator.py --plan plan.json --server 127.0.0.1:8188