comfy-h3-render-core

ComfyUI H3 Render Core (H3 물리 렌더링 및 오케스트레이션 공정)

공정 위치: 단편 드라마 물리 생성 핵심 공정. 핵심 원칙: ComfyUI 노드 번호를 하드코딩하지 않고, Windows WDDM 드라이버 잠금을 엄격히 방지하며, 단일 발화자 잠금 및 잠재 공간 크기 안전 검사를 강제합니다.

---

1. 실행 계약 및 입출력

• 입력:
  1. plan.json (카메라 움직임, 대사, 175프레임 타임라인 포함);
  2. 2공정의 고정 프레임 기준 이미지: segments/{seg_id}_keyframe.png;
  3. style_bible.json.
• 출력:
  1. H3 네이티브 생성 비디오: segments/{seg_id}.mp4 (네이티브 오디오/비디오 포함);
  2. VRAM 상태 모니터링 로그 및 렌더링 시간台账.

---

2. 하드코어 SOP: 3대 충돌 방지 물리 법칙 (숫자 특징 및 오류 반례 포함)

2.1 법칙 1: 잠재 공간 차원 32整除 법칙 (VAE 잠재 공간 충돌 방지)

• 현상/오류: RuntimeError: shape '[1, 24, 1, 1, 15, 2, 26, 2]' is invalid for input of size 38160
• 근본 원인: MiniMax H3의 3D 패치 크기 요구 사항으로 인해 너비가 16으로 나누어 떨어져야 하며, 몫이 짝수여야 합니다 (즉, width % 32 == 0).
• 판단 기준 및 조치:
  • 절대 사용 금지: 848×480 (848/16=53은 홀수이므로 patch=2로 나눌 수 없어 반드시 충돌 발생!);
  • 강제 고정: 표준 와이드스크린은 832×480으로 고정합니다 (832/16=52는 짝수, 52/2=26으로 완벽하게 나누어 떨어짐!).

2.2 법칙 2: Windows WDDM 드라이버 상호 배제 잠금 방어 (15배 속도 저하 방지)

• 현상: Windows에서 cudaMallocAsync 또는 다중 스트림 비동기 전송(async-offload)을 활성화하면 단일 샘플링 단계가 40초에서 600초로 급증합니다 (단일 세그먼트당 최대 70분 소요).
• 근본 원인: Windows의 WDDM 드라이버 모델은 CUDA 스트림 간에 대용량 가중치를 전송할 때 심각한 커널 뮤텍스 잠금 경합(Mutex Lock Contention)을 발생시킵니다.
• 조치 (ComfyUI 골든 시작 인수):

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

  네이티브 캐시와 단일 스트림 스케줄링을 사용하여 드라이버 잠금을 우회하며, 단일 세그먼트 생성 시간은 350초 (5.8분) 으로 안정적으로 유지됩니다.

2.3 법칙 3: 단일 발화자 및 침묵 명령 조립 (모든 캐릭터의 입 움직임 제거)

[Subject 1] 및 [Action 1]을 구성할 때 분리 조립을 강제로 실행해야 합니다:

• [Subject 1]: Primary speaker: [SpeakerName], alongside [ListenerName] (silent listener).
• [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: VRAM 단편화 방지 및 체크포인트/재개 보호

1. 컷 간 VRAM 회수: 각 컷 렌더링이 완료된 후 ComfyUI /free 엔드포인트를 호출해야 합니다:

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

   PyTorch 중간 3D 잠재 공간 텐서 캐시를 비워 장기 연속 생산 중 OOM 누적을 방지합니다.
2. 체크포인트/재개를 통한 중복 렌더링 방지: segments/{seg_id}.mp4를 확인하여 파일이 이미 존재하고 크기가 100KB보다 크면 [재사용]을 출력하고 건너뛰어 초 단위 체크포인트 재개를 지원합니다.

---

4. 전용 도구 스크립트

• H3 실행 그래프 조립 및 스케줄링 엔진: python scripts/h3_render_orchestrator.py --plan plan.json --server 127.0.0.1:8188