comfy-h3-render-core

ComfyUI H3 Render Core (Renderização Física H3 e Orquestração de Processos)

Posicionamento do Processo: Processo central de geração física de curta-metragem. Princípios Básicos: Não fixar números de nós do ComfyUI, prevenir rigorosamente o travamento do driver WDDM no Windows, aplicar obrigatoriamente a trava de pronúncia individual e a verificação de segurança das dimensões do espaço latente.

---

1. Contrato de Execução, Entradas e Saídas

• Entradas:
  1. plan.json (contém movimento de câmera, diálogos e 175 quadros de temporização);
  2. Quadro-chave fixo da Fase 2: segments/{seg_id}_keyframe.png;
  3. style_bible.json.
• Saídas:
  1. Vídeo gerado nativamente pelo H3: segments/{seg_id}.mp4 (com áudio e vídeo nativos);
  2. Log de monitoramento do estado da VRAM e registro de tempo de renderização.

---

2. SOP Essencial: Três Leis Físicas de Prevenção de Desastres (com Características Numéricas e Exemplos de Erro)

2.1 Lei 1: Regra de Divisibilidade por 32 do Espaço Latente (Prevenção de Falha no Espaço Latente VAE)

• Sintoma/Erro: RuntimeError: shape '[1, 24, 1, 1, 15, 2, 26, 2]' is invalid for input of size 38160
• Causa Raiz: O Patch 3D do MiniMax H3 exige que a largura seja divisível por 16 e que o quociente seja par (ou seja, largura % 32 == 0).
• Critério e Ação:
  • Proibido usar: 848×480 (848/16=53, ímpar, não divisível por patch=2, causará falha!);
  • Fixar obrigatoriamente: Widescreen padrão deve ser fixado em 832×480 (832/16=52, par, 52/2=26, divisão perfeita!).

2.2 Lei 2: Defesa contra Trava de Mutex do Driver WDDM no Windows (Prevenção de Lentidão 15x)

• Sintoma: No Windows, ao ativar cudaMallocAsync ou transferência assíncrona multi-stream (async-offload), cada etapa de amostragem cai de 40 segundos para 600 segundos (um segmento leva até 70 minutos).
• Causa Raiz: O modelo de driver WDDM do Windows, ao transportar pesos grandes entre streams CUDA, causa uma disputa severa de trava de mutex do kernel (Mutex Lock Contention).
• Ação (Parâmetros de Inicialização Ideais do ComfyUI):

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

  Utiliza cache nativo e escalonamento de stream único para evitar a trava do driver, mantendo o tempo de geração por segmento estável em 350 segundos (5,8 minutos).

2.3 Lei 3: Montagem de Instruções de Pronúncia Individual e Supressão de Fala (Eliminar Movimento Bucal Coletivo)

Ao construir [Subject 1] e [Action 1], a montagem separada deve ser executada obrigatoriamente:

• [Subject 1]: Primary speaker: [SpeakerName], alongside [ListenerName] (silent listener).
• Primitiva principal 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 Essencial: Proteção contra Fragmentação de VRAM e Retomada de Produção a partir de Pontos de Interrupção

1. Reciclagem de VRAM entre Cenas: Após a renderização de cada cena, deve-se chamar o endpoint /free do ComfyUI:

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

   Limpa o cache do tensor 3D do espaço latente intermediário do PyTorch, prevenindo OOM acumulado em produção contínua de longo ciclo.
2. Retomada de Produção para Evitar Renderização Repetida: Verificar segments/{seg_id}.mp4; se o arquivo já existir e for maior que 100KB, imprimir diretamente [Reutilizar] e pular, suportando retomada em segundos.

---

4. Script de Ferramenta Exclusivo

• Motor de Montagem e Orquestração de Grafo de Execução H3: python scripts/h3_render_orchestrator.py --plan plan.json --server 127.0.0.1:8188