jamesstothard-renderzero-comfyui-nodes/README.md

# RenderZero ComfyUI Nodes

ComfyUI custom nodes for RenderZero Studio image and video workflows.

## Install

Clone this repo into your ComfyUI custom nodes directory, then restart ComfyUI.

```powershell
cd ComfyUI/custom_nodes
git clone https://github.com/jamesstothard/renderzero-comfyui-nodes renderzero_bridge_nodes
```

Manual install also works: copy this repository folder into `ComfyUI/custom_nodes/renderzero_bridge_nodes`, then restart ComfyUI.

## Nodes

- `RenderZero Prompt Bridge`
  - Inputs: `positive_prompt`, `aspect_ratio`, `image_size`, `seed`
  - Supported `image_size` values: `480p`, `720p`, `1K`, `2K`, `4K`
  - Outputs: `positive_prompt`, `width`, `height`, `seed`
- `RenderZero Video Prompt Bridge`
  - Inputs: `positive_prompt`, `aspect_ratio`, `resolution_tier`, `frame_count`, `frame_rate`, `seed`
  - Supported `resolution_tier` values: `480p`, `720p`, `1080p`
  - Outputs: `positive_prompt`, `width`, `height`, `frame_count`, `frame_rate_int`, `frame_rate_float`, `seed`
  - Video sizes are fixed to RenderZero's 16-divisible table, including Wan-safe `832x480` for `480p` `16:9`
- `RenderZero Video Start Frame Bridge`
  - Input: `image_slot`
  - Output: raw `IMAGE`
  - Files are loaded from the ComfyUI `input` directory
  - Blank `image_slot` values raise a clear "start frame required" error
- `RenderZero Image Input`
  - Inputs: `slot_index`, `image_slot`, `target_width`, `target_height`
  - Output: raw `IMAGE`
  - Files are loaded from the ComfyUI `input` directory
  - Preserves the uploaded image's native aspect ratio instead of padding it to the RenderZero canvas size
  - `target_width` and `target_height` remain for workflow compatibility only; do any resize, crop, or normalization downstream with normal ComfyUI nodes such as `ImageScaleToTotalPixels` or `ImageScale`
  - Use this node for anonymous/additional reference-image workflows where RenderZero uploads one image per `slot_index`
- `RenderZero Video Output`
  - Input: `video_payload`
  - Output node that normalizes a connectable filename or path-like payload into a stable `gifs` history entry for RenderZero
  - Accepts filename/path-like outputs from upstream save/combine nodes such as `VHS_VideoCombine.Filenames`
  - Absolute paths must resolve inside the ComfyUI `output` directory
- `RenderZero Reference Bridge`
  - Inputs: `positive`, `negative`, `vae`, `character1_face`, `character1_outfit`, `character1_object`, `global_reference`
  - Outputs: conditioned `positive`, conditioned `negative`
  - Blank filename inputs are skipped
  - Reference conditioning order is `character1_face -> character1_outfit -> character1_object -> global_reference`
  - Files are loaded from the ComfyUI `input` directory, so RenderZero uploads each populated slot before queueing the workflow
- `RenderZero Image Output`
  - Input: `images`
  - Output node that saves the final image so RenderZero can fetch it from ComfyUI history

LoRAs are not part of the bridge-node contract. If you want LoRA support, add normal ComfyUI `LoraLoader` nodes to the workflow and export that graph in API format for RenderZero.

## Workflow rules

- Import the workflow into RenderZero using the ComfyUI API-format JSON, not the regular UI export.
- Image workflows:
  - Must contain exactly one `RenderZeroPromptBridge` node
  - Must contain exactly one `RenderZeroImageOutput` node
  - May contain zero or one `RenderZeroReferenceBridge` node
  - Must not contain the video bridge nodes
- Video workflows:
  - Must contain exactly one `RenderZeroVideoPromptBridge` node
  - Must contain exactly one `RenderZeroVideoStartFrameBridge` node
  - Must contain exactly one `RenderZeroVideoOutput` node
  - Must not contain the image bridge nodes
- Do not mix the image and video RenderZero bridge contracts in the same workflow.
- Image prompt-bridge outputs should feed your text encoder and any width/height inputs that need image dimensions.
- Video prompt-bridge outputs should feed your video model's prompt, width, height, frame-count, frame-rate, and seed inputs as needed.
- `RenderZeroVideoOutput` should be connected to one upstream save/combine filename output. RenderZero only reads the branch wired into that node.
- Multiple video save/combine branches are allowed in one graph. Only the single branch connected to `RenderZeroVideoOutput` is treated as the RenderZero result.
- For Wan workflows, connect your chosen `VHS_VideoCombine` `Filenames` output into `RenderZeroVideoOutput`.
- If you use `RenderZeroReferenceBridge` in an image workflow, connect your positive and negative conditioning branches plus the VAE into it, then feed its outputs into the guider or sampler branch.
- If you use `RenderZeroImageInput`, treat it like a raw upload loader. Preserve its output for reference fidelity, and do any explicit scaling or cropping with standard ComfyUI image nodes after it.
- Slot mapping in RenderZero image workflows is fixed:
  - `character1_face` <- Character 1 Face
  - `character1_outfit` <- Character 1 Outfit
  - `character1_object` <- Character 1 Object
  - `global_reference` <- Global Reference
- `global_reference` is optional. The workflow still runs when only face/outfit/object are populated, or when all four slots are blank.
- Connect the final rendered image tensor into `RenderZeroImageOutput` for image workflows.
- Connect the chosen video filename/path output into `RenderZeroVideoOutput` for video workflows.