The all-in-one local AI studio for your desktop: chat, image and video generation and a coding agent in one free, open source app. Windows and Linux. No Docker, no terminal, no cloud required.
TypeScript agentai-chatai-studioall-in-onecoding-agentdesktop-appfluximage-generationlinuxllmlocal-ailocal-llmopen-sourceprivacyself-hostedstable-diffusionuncensoreduncensored-aivideo-generationwindows
import { transparentPrompt } from '../lib/transparent-image'
import {
classifyModel, ref2vFamily, ref2vRefusal, findMatchingVAE, findMatchingCLIP, findFluxCLIPPair, findMiniMaxAudioVAE, findLtx25AudioVAE, isFastH3, wan22LowNoisePartner,
findMatchingAudioEncoder, findMatchingClipVision, findFramePackCLIPPair, getSystemVRAM,
} from './comfyui'
import { isMacOS } from './backend'
import { QWEN21_TURBO_NODES, QWEN21_TURBO_SAMPLING, QWEN21_TURBO_SIGMAS, isQwenImage21Turbo } from '../lib/render/qwen21-turbo'
import { comfyEditFullImages, qwenEditPlusOverCard } from '../lib/comfy-edit-memory'
import type { ModelType, GenerateParams, VideoParams } from './comfyui'
import { log } from '../lib/logger'
import { resolveRunSeed } from '../lib/run-seed'
import { nodeComboOptions, readComboOptions } from './comfyui-enum'
import { COMPONENT_REGISTRY, type ComponentSpec } from './component-registry'
import { MissingComponentsError, resolveFamilyParts, type SniffedFamily } from './family-components'
import {
getAllNodeInfo,
categorizeNodes,
detectAvailableModels,
type CategorizedNodes,
type AvailableModels,
type NodeMetadata,
} from './comfyui-nodes'
import type { ComfyApiGraph, ComfyInputValue, ComfyNodeInputs } from '../types/comfy-graph'
/**
* The `/object_info` node table as the LANE builders use it: they only ever ask
* whether a node class is installed, never what its schema says, so a presence
* map is the honest parameter type. `buildDynamicWorkflow` itself keeps the
* full `Record<string, NodeMetadata>` from getAllNodeInfo(), because it does
* read schemas (RMBG, the I2V conditioning node, LoraLoader's combo).
*/
type NodePresence = Record<string, unknown>
/**
* Split one `/object_info` input spec into the two halves every caller wants.
*
* ComfyUI writes a spec as `[typeName, config]` (current) or `[[options]]`
* (legacy combo). Neither half is guaranteed, and a custom node can put
* anything there, so both come back optional. Combo OPTIONS are not read here
* — `readComboOptions` is the single reader that knows all three shapes.
*/
function specParts(spec: ComfyInputValue | undefined): {
typeName?: string
config?: { [k: string]: ComfyInputValue }
} {
if (!Array.isArray(spec)) return {}
const head = spec[0]
const cfg = spec[1]
return {
typeName: typeof head === 'string' ? head : undefined,
config: typeof cfg === 'object' && cfg !== null && !Array.isArray(cfg) ? cfg : undefined,
}
}
/** The `default` a widget spec declares, or undefined when it declares none. */
function specDefault(spec: ComfyInputValue | undefined): ComfyInputValue | undefined {
return specParts(spec).config?.default
}
// promptFilenamePrefix und videoDecodeNode wohnen in comfyui-graph.ts (siehe
// dort). Re-Export, damit bestehende Importpfade unverändert bleiben.
export { promptFilenamePrefix, videoDecodeNode } from './comfyui-graph'
import { promptFilenamePrefix, videoDecodeNode, addVideoSave } from './comfyui-graph'
import { extraReferenceSlots, isQwenImageEditModel, referenceSide } from '../lib/edit-references'
import { canonicalImageRefs } from '../lib/image-ref-names'
import { KREA2_STYLE_LORA, LOCAL_END_FRAME_MODELS, createReferenceSupport, localAnimateReferenceSlots, localEndFrame, CREATE_REFERENCE_MODELS } from '../lib/frame-refs'
import { nativeUpscaleScale, upscaleTarget, type UpscaleFactor } from '../lib/local-upscale'
import { TRELLIS2_FILES } from './model-bundles'
import { WAN_FAST, findWanSpeedLora, isFastSampling, isWanSpeedLoraName, wanSamplingFor, wanSpeedKind, wanSpeedLoraNames } from '../lib/wan-speed'
import { addAudioStitch, addContextWindows, addContinueSource, addStitch, CONTINUE_NEEDS_UPDATE, type ContinueSource } from './video-continue'
// ─── Strategy Detection ───
export type WorkflowStrategy =
| 'unet_flux' // FLUX 1: UNETLoader + CLIPLoader + VAELoader + EmptySD3LatentImage
| 'unet_flux2' // FLUX 2: UNETLoader + CLIPLoader + VAELoader + EmptyFlux2LatentImage
| 'unet_krea2' // Krea 2: UNETLoader + CLIPLoader(type="krea2") + VAELoader + EmptyLatentImage (GH #136)
| 'unet_zimage' // Z-Image: UNETLoader + CLIPLoader(qwen_image) + VAELoader + EmptySD3LatentImage
| 'unet_ernie_image' // ERNIE-Image: UNETLoader + CLIPLoader(flux2) + VAELoader + EmptyFlux2LatentImage + ConditioningZeroOut
| 'unet_qwenimage' // Qwen-Image 2.1: UNETLoader + CLIPLoader(qwen_image) + VAELoader + TextEncodeQwenImage21 (generate and edit)
// The families below came in with the header sniff (Discord 2026-09-28).
// Graphs follow the official Comfy-Org templates, see family-components.ts.
| 'unet_qwenimage1' // Qwen-Image 1 / Edit: CLIPLoader(qwen_image, Qwen2.5-VL) + qwen_image_vae + AuraFlow shift 3.1 (edit: TextEncodeQwenImageEditPlus)
| 'unet_chroma' // Chroma: CLIPLoader(chroma, T5) + ae + AuraFlow shift 1
| 'unet_hidream' // HiDream I1: QuadrupleCLIPLoader + ae + ModelSamplingSD3
| 'unet_sd3' // SD 3.5: TripleCLIPLoader (or the checkpoint's own) + SD3 latent
| 'unet_lumina2' // Lumina 2: CLIPLoader(lumina2, Gemma 2 2B) + ae + AuraFlow shift 6 + system prompt
| 'unet_sdxl' // SDXL transformer in diffusion_models: DualCLIPLoader(sdxl) + sdxl_vae
| 'unet_sd15' // SD 1.5 unet in diffusion_models: CLIPLoader(stable_diffusion) + ft-mse VAE
| 'unet_video' // Wan/Hunyuan: UNETLoader + CLIPLoader + VAELoader + EmptyHunyuanLatentVideo
| 'wan22' // Wan 2.2 TI2V-5B: UNET + CLIP + Wan 2.2 VAE + Wan22ImageToVideoLatent (unified T2V/I2V)
| 'unet_ltx' // LTX Video: UNETLoader + CLIPLoader + EmptyLTXVLatentVideo
| 'ltx25' // LTX 2.5: two pass picture-and-sound graph (distilled), needs ComfyUI 0.32.0
| 'unet_mochi' // Mochi: UNETLoader + CLIPLoader + VAELoader + EmptyMochiLatentVideo
| 'unet_cosmos' // Cosmos: UNETLoader + CLIPLoader(oldt5) + VAELoader + EmptyCosmosLatentVideo
| 'svd' // SVD: ImageOnlyCheckpointLoader + SVD_img2vid_Conditioning
| 'framepack' // FramePack: Kijai wrapper + image input
| 'minimaxh3' // MiniMax H3: UNET + CLIPLoader(minimax) + video VAE + audio VAE, picture and sound in one pass
// cogvideo / pyramidflow / allegro are gone on purpose (2026-07-24). Their
// builders emitted node names no wrapper registers, so those model types now
// resolve to 'unavailable' with an honest reason instead of a ComfyUI 400.
| 'checkpoint' // SDXL/SD1.5: CheckpointLoaderSimple + EmptyLatentImage
| 'animatediff' // AnimateDiff: CheckpointLoaderSimple + ADE_* nodes
| 'unavailable'
interface StrategyResult {
strategy: WorkflowStrategy
reason: string
/**
* When `strategy === 'unavailable'` and the missing piece is an
* installable custom-node pack, this hint tells the UI which one to
* suggest. Surfaces in Create view as a clickable "open install guide"
* link so users like a user (CogVideoX 1.5 5B → UNETLoader
* mismatch on v2.4.3) get a clear next step instead of just a
* blocking error. (Bug #6)
*/
installHint?: { pack: string; url: string }
}
/** The sentence an older ComfyUI gets, per model (not global): the version is
* the release that brought the node the lane cannot run without. Read from the
* ComfyUI tags on 2026-10-02: LTX 2.5 in 0.32.0, FastH3's sparse attention in
* 0.35.0, YuE2 in 0.36.0. "Update ComfyUI" in the text is what Create keys the
* one click update on (needsComfyUpdate). */
export const LTX25_NEEDS_UPDATE = 'LTX 2.5 needs ComfyUI 0.32.0 or newer. Update ComfyUI in Settings.'
/** C78: what Create says for MiniMax H3 Image, a still model on the H3
* layout that LU has no graph of its own for. */
export const MINIMAX_H3_IMAGE_NO_BUILDER =
'LU has no built-in workflow for MiniMax H3 Image. Save the ComfyUI template "MiniMax-H3-Image: Text to Image", '
+ 'import it under Workflows and assign it to this model. Create then runs it with your prompt, size and LoRAs.'
/** GH #192: what Create says for MOSS Image until LU has a graph of its own. */
export const MOSS_IMAGE_NO_BUILDER =
'LU has no built in workflow for MOSS Image. Import a ComfyUI workflow that runs MOSS Image under Workflows and assign it to this model. '
+ 'Create then runs it with your prompt, size and LoRAs.'
/** A step distillation LoRA names its step count (minimax_h3_fl2v_turbo_8step_...). */
const H3_STEP_LORA = /turbo\D*?(\d+)\s*_?steps?/i
export const FASTH3_NEEDS_UPDATE = 'FastH3 needs ComfyUI 0.35.0 or newer. Update ComfyUI in Settings.'
export const YUE2_NEEDS_UPDATE = 'YuE2 needs ComfyUI 0.36.0 or newer. Update ComfyUI in Settings.'
export function determineStrategy(
modelType: ModelType,
isVideo: boolean,
nodes: CategorizedNodes,
models: AvailableModels,
): StrategyResult {
// C78: MiniMax H3 Image has no graph of LU's own. Its workflow is the
// official template; imported under Workflows and assigned to the model,
// Create runs it with the prompt, size and LoRAs (workflows.ts).
if (modelType === 'minimaxh3image') {
return { strategy: 'unavailable', reason: MINIMAX_H3_IMAGE_NO_BUILDER }
}
if (modelType === 'mossimage') {
return { strategy: 'unavailable', reason: MOSS_IMAGE_NO_BUILDER }
}
const hasUNET = nodes.loaders.includes('UNETLoader')
const hasCheckpoint = nodes.loaders.includes('CheckpointLoaderSimple')
const hasCLIPLoader = nodes.loaders.includes('CLIPLoader')
const hasVAELoader = nodes.loaders.includes('VAELoader')
const hasAnimateDiff = nodes.motion.includes('ADE_LoadAnimateDiffModel')
// ERNIE-Image → UNET + CLIPLoader(flux2) + VAE + Flux2LatentImage + ConditioningZeroOut
if (modelType === 'ernie_image') {
if (hasUNET && hasCLIPLoader && hasVAELoader) {
return { strategy: 'unet_ernie_image', reason: 'ERNIE-Image model → UNETLoader + CLIPLoader(flux2) + ConditioningZeroOut' }
}
return { strategy: 'unavailable', reason: 'ERNIE-Image requires UNETLoader + CLIPLoader + VAELoader nodes' }
}
// Qwen-Image 2.1 → UNET + CLIPLoader(qwen_image) + VAE + TextEncodeQwenImage21.
// One model, two graphs: without a reference image it generates, with one it
// edits. Both official Comfy-Org templates route the prompt through
// TextEncodeQwenImage21, so the lane needs that node either way. It arrived
// in ComfyUI 0.37.0 (comfy_extras/nodes_qwen.py); an older install gets the
// update sentence rather than a ComfyUI 400 on an unknown node class.
if (modelType === 'qwenimage') {
const hasQwen21Encode = nodes.textEncoders.includes('TextEncodeQwenImage21')
if (hasUNET && hasCLIPLoader && hasVAELoader && hasQwen21Encode) {
return { strategy: 'unet_qwenimage', reason: 'Qwen-Image 2.1 model → UNETLoader + CLIPLoader(qwen_image) + TextEncodeQwenImage21' }
}
if (hasUNET && hasCLIPLoader && hasVAELoader) {
return {
strategy: 'unavailable',
reason: 'Qwen-Image 2.1 needs ComfyUI 0.37.0 or newer. Update ComfyUI in Settings.',
}
}
return { strategy: 'unavailable', reason: 'Qwen-Image 2.1 requires UNETLoader + CLIPLoader + VAELoader nodes' }
}
// Z-Image → UNET + CLIPLoader(qwen_image) + VAE + SD3LatentImage
if (modelType === 'zimage') {
if (hasUNET && hasCLIPLoader && hasVAELoader) {
return { strategy: 'unet_zimage', reason: 'Z-Image model → UNETLoader + CLIPLoader(qwen_image)' }
}
return { strategy: 'unavailable', reason: 'Z-Image requires UNETLoader + CLIPLoader + VAELoader nodes' }
}
// Header-sniffed families (Discord 2026-09-28). Their graphs are built in
// one place further down; the loaders are checked there, per graph.
const sniffed: Partial<Record<ModelType, WorkflowStrategy>> = {
chroma: 'unet_chroma', hidream: 'unet_hidream', sd3: 'unet_sd3', lumina2: 'unet_lumina2', qwenimage1: 'unet_qwenimage1',
}
const sniffedStrategy = sniffed[modelType]
if (sniffedStrategy) {
if ((hasUNET || hasCheckpoint) && hasVAELoader) {
return { strategy: sniffedStrategy, reason: `${modelType} → its own loader set (official Comfy-Org template)` }
}
return { strategy: 'unavailable', reason: `${modelType} needs UNETLoader and VAELoader. Update ComfyUI in Settings.` }
}
// FLUX 2 → UNET + Flux2LatentImage
if (modelType === 'flux2') {
if (hasUNET && hasCLIPLoader && hasVAELoader) {
return { strategy: 'unet_flux2', reason: 'FLUX 2 model → UNETLoader + EmptyFlux2LatentImage' }
}
return { strategy: 'unavailable', reason: 'FLUX 2 requires UNETLoader + CLIPLoader + VAELoader nodes' }
}
// FLUX 1 → UNET + SD3LatentImage
if (modelType === 'flux') {
if (hasUNET && hasCLIPLoader && hasVAELoader) {
return { strategy: 'unet_flux', reason: 'FLUX model → UNETLoader pipeline' }
}
return { strategy: 'unavailable', reason: 'FLUX requires UNETLoader + CLIPLoader + VAELoader nodes' }
}
// Krea 2 (K9, GH #136) → UNET + CLIPLoader(type="krea2") + VAE + EmptyLatentImage
if (modelType === 'krea2') {
if (hasUNET && hasCLIPLoader && hasVAELoader) {
return { strategy: 'unet_krea2', reason: 'Krea 2 model → UNETLoader + CLIPLoader(krea2)' }
}
return { strategy: 'unavailable', reason: 'Krea 2 requires UNETLoader + CLIPLoader + VAELoader nodes' }
}
// LTX 2.5 → UNET + CLIPLoader(ltxv, Gemma 4) + both VAEs + the two pass graph
// of the official templates. The model patch arrived in ComfyUI 0.32.0
// together with LTXVDualCFGGuider (comfy_extras/nodes_lt.py, PR 15499), and
// that node is the one this lane cannot run without, so its absence is the
// version check: an older install gets the update sentence instead of a 400.
if (modelType === 'ltx25') {
const hasDual = nodes.samplers.includes('LTXVDualCFGGuider')
if (hasUNET && hasCLIPLoader && hasVAELoader && hasDual) {
return { strategy: 'ltx25', reason: 'LTX 2.5 → UNETLoader + CLIPLoader(ltxv) + LTXVDualCFGGuider (two pass, sound)' }
}
if (hasUNET && hasCLIPLoader && hasVAELoader) {
return { strategy: 'unavailable', reason: LTX25_NEEDS_UPDATE }
}
return { strategy: 'unavailable', reason: 'LTX 2.5 requires UNETLoader + CLIPLoader + VAELoader nodes' }
}
// LTX Video → UNET + LTXVLatentVideo (no separate VAE needed)
if (modelType === 'ltx') {
if (hasUNET && hasCLIPLoader) {
return { strategy: 'unet_ltx', reason: 'LTX Video → UNETLoader + EmptyLTXVLatentVideo' }
}
return { strategy: 'unavailable', reason: 'LTX Video requires UNETLoader + CLIPLoader nodes' }
}
// MiniMax H3 → its own encode node, which also builds the joint
// picture-and-sound latent. The nodes arrived with ComfyUI PR #15224, so an
// older install gets the update sentence (fixable in place) instead of a 400.
if (modelType === 'minimaxh3') {
const hasH3 = nodes.latentInit.includes('MiniMaxH3ImageToVideo')
if (hasUNET && hasCLIPLoader && hasVAELoader && hasH3) {
return { strategy: 'minimaxh3', reason: 'MiniMax H3 → UNETLoader + CLIPLoader(minimax) + MiniMaxH3ImageToVideo' }
}
return { strategy: 'unavailable', reason: 'MiniMax H3 needs a newer ComfyUI. Update ComfyUI in Settings.' }
}
// Wan 2.2 TI2V-5B → UNET + CLIP + Wan 2.2 VAE + Wan22ImageToVideoLatent (T2V & I2V)
if (modelType === 'wan22') {
const hasWan22Latent = nodes.latentInit.includes('Wan22ImageToVideoLatent')
if (hasUNET && hasCLIPLoader && hasVAELoader && hasWan22Latent) {
return { strategy: 'wan22', reason: 'Wan 2.2 TI2V-5B → UNETLoader + Wan22ImageToVideoLatent (unified T2V/I2V)' }
}
return {
strategy: 'unavailable',
reason: 'Wan 2.2 TI2V-5B needs the Wan22ImageToVideoLatent node (ComfyUI ≥ v0.3.46). Update ComfyUI, then try again.',
}
}
// Wan / Hunyuan → UNET-based with video latent
if (modelType === 'wan' || modelType === 'hunyuan') {
if (hasUNET && hasCLIPLoader && hasVAELoader) {
return { strategy: 'unet_video', reason: `${modelType} model → UNETLoader + video latent` }
}
return { strategy: 'unavailable', reason: 'Wan/Hunyuan requires UNETLoader + CLIPLoader + VAELoader nodes' }
}
// Mochi → UNET + EmptyMochiLatentVideo (native)
if (modelType === 'mochi') {
if (hasUNET && hasCLIPLoader && hasVAELoader) {
return { strategy: 'unet_mochi', reason: 'Mochi → UNETLoader + EmptyMochiLatentVideo' }
}
return { strategy: 'unavailable', reason: 'Mochi requires UNETLoader + CLIPLoader + VAELoader nodes' }
}
// Cosmos → UNET + EmptyCosmosLatentVideo (native, oldt5 encoder)
if (modelType === 'cosmos') {
if (hasUNET && hasCLIPLoader && hasVAELoader) {
return { strategy: 'unet_cosmos', reason: 'Cosmos → UNETLoader + EmptyCosmosLatentVideo (oldt5)' }
}
return { strategy: 'unavailable', reason: 'Cosmos requires UNETLoader + CLIPLoader + VAELoader nodes' }
}
// SVD → ImageOnlyCheckpointLoader (native, I2V)
if (modelType === 'svd') {
const hasIOCL = nodes.loaders.includes('ImageOnlyCheckpointLoader')
if (hasIOCL) {
return { strategy: 'svd', reason: 'SVD → ImageOnlyCheckpointLoader + SVD_img2vid_Conditioning' }
}
return { strategy: 'unavailable', reason: 'SVD requires ImageOnlyCheckpointLoader node' }
}
// CogVideoX → Kijai wrapper nodes.
//
// 2026-07-24 (D#88 "it says I'm missing custom nodes, but they
// are there"): he was right. The gate looked for `CogVideoXSampler`, which has
// never existed in kijai/ComfyUI-CogVideoXWrapper — the real class is
// `CogVideoSampler` (verified against a real checkout; `git log -S` upstream
// finds the X-name in no commit ever). So a perfect install always failed the
// check and the user was told to go install what they already had.
//
// The gate deliberately STAYS closed rather than being pointed at the real
// name, because buildCogVideoWorkflow below emits the same invented names
// throughout (CogVideoXTextEncode / CogVideoXEmptyLatents / CogVideoXVAEDecode
// — none real). Opening it would only trade this clear message for an opaque
// ComfyUI 400. The lane needs a rebuild against the current wrapper plus a
// real generate E2E; until then say so honestly instead of blaming the setup.
if (modelType === 'cogvideo') {
return {
strategy: 'unavailable',
reason: 'CogVideoX is not supported in this build yet. Its pipeline needs a rebuild against the current wrapper, so please pick another video model such as Wan, LTX or SVD for now.',
}
}
// FramePack → Kijai wrapper nodes (I2V)
if (modelType === 'framepack') {
const hasFPNodes = nodes.samplers.includes('FramePackSampler')
if (hasFPNodes) {
return { strategy: 'framepack', reason: 'FramePack → Kijai wrapper pipeline (I2V)' }
}
return {
strategy: 'unavailable',
reason: 'FramePack needs the ComfyUI-FramePackWrapper custom nodes. Install via ComfyUI Manager (Manager → Install Custom Nodes → search "FramePackWrapper") or git clone the repo into ComfyUI/custom_nodes/.',
installHint: { pack: 'ComfyUI-FramePackWrapper', url: 'https://github.com/kijai/ComfyUI-FramePackWrapper' },
}
}
// Pyramid Flow → Kijai wrapper nodes.
//
// Closed for the same reason as CogVideoX above, found in the same 2026-07-24
// audit. The gate itself was fine (PyramidFlowSampler is real), but
// buildPyramidFlowWorkflow was written against a wrapper nobody checked:
// the loader is registered as PyramidFlowTransformerLoader, decode is
// PyramidFlowVAEDecode and wants a vae input we never wired, the text encoder
// takes clip plus positive_prompt plus negative_prompt rather than a bare
// `text`, and the sampler consumes prompt_embeds plus per stage step strings
// instead of steps and frames. So a correct install got a 400 with no clue
// why. Same deal as CogVideoX: reopen only with a rebuilt builder and a real
// generate behind it.
if (modelType === 'pyramidflow') {
return {
strategy: 'unavailable',
reason: 'Pyramid Flow is not supported in this build yet. Its pipeline needs a rebuild against the current wrapper, so please pick another video model such as Wan, LTX or SVD for now.',
}
}
// Allegro → Community wrapper nodes.
//
// Also closed in the 2026-07-24 audit. Every other wrapper lane in this file
// that was never run turned out to emit invented node names, and Allegro is
// the one we cannot check: the wrapper it points at is a single community
// repo we have never had installed, its bundle was already pulled from the
// catalogue for being diffusers-only, and the builder follows the exact
// Loader/TextEncode/Sampler/Decoder shape that was wrong in both other cases.
// Unverifiable plus unreachable through the catalogue means it stays shut
// rather than shipping a third guess.
if (modelType === 'allegro') {
return {
strategy: 'unavailable',
reason: 'Allegro is not supported in this build. Please pick another video model such as Wan, LTX or SVD.',
}
}
// SDXL / SD1.5 / Unknown
if (isVideo && hasAnimateDiff && hasCheckpoint && models.motionModels.length > 0) {
return { strategy: 'animatediff', reason: 'Video mode → AnimateDiff pipeline' }
}
if (hasCheckpoint) {
return { strategy: 'checkpoint', reason: 'Checkpoint-based pipeline' }
}
// K9: this used to fall back to 'unet_flux' whenever CheckpointLoaderSimple
// was missing (rare, it is a core node, present on virtually every real
// install), on the unstated assumption that any UNET-only file must be a
// FLUX model. For a genuinely unrecognized architecture that is a silent
// guess: it picks FLUX's CLIP type and VAE match patterns for a model that
// may not be FLUX at all, which either fails confusingly or "succeeds"
// with a wrong text encoder. classifyModel returning 'unknown' means LU
// could not name this model's architecture, so say so honestly instead of
// routing it through a guessed pipeline. A real architecture (Krea 2,
// FLUX 2, Z-Image, ...) has its own branch above and never reaches here.
if (hasUNET && hasCLIPLoader && hasVAELoader) {
return {
strategy: 'unavailable',
reason: `LU could not determine this model's architecture, so it will not guess a ComfyUI pipeline for it. If this is a known model family, please report it so LU can recognize it.`,
}
}
return { strategy: 'unavailable', reason: 'No compatible loader nodes found in ComfyUI' }
}
// ─── Dynamic Workflow Builder ───
/**
* Custom Error thrown by `buildDynamicWorkflow` when the active ComfyUI
* lacks the loader nodes for the chosen model architecture (Bug #6:
* CogVideoX 1.5 / LTX / FramePack require Kijai wrapper nodes that aren't
* in ComfyUI core). UI can read `.installHint` to render a one-click
* "open install guide" link instead of just blocking the user.
*/
export class WorkflowUnavailableError extends Error {
readonly strategy: WorkflowStrategy
readonly installHint?: { pack: string; url: string }
/** Companion files LU can download itself; Create offers them in place. */
readonly missing?: ComponentSpec[]
/** The local ComfyUI is too old for this graph; Create offers the update. */
readonly needsComfyUpdate?: boolean
constructor(
message: string,
strategy: WorkflowStrategy,
installHint?: { pack: string; url: string },
extra?: { missing?: ComponentSpec[]; needsComfyUpdate?: boolean },
) {
super(message)
this.name = 'WorkflowUnavailableError'
this.strategy = strategy
this.installHint = installHint
this.missing = extra?.missing
this.needsComfyUpdate = extra?.needsComfyUpdate
}
}
/** The families built from family-components.ts, by strategy. */
const SNIFFED_FAMILY: Partial<Record<WorkflowStrategy, SniffedFamily>> = {
unet_chroma: 'chroma', unet_hidream: 'hidream', unet_sd3: 'sd3', unet_lumina2: 'lumina2',
unet_qwenimage1: 'qwenimage1', unet_sdxl: 'sdxl_unet', unet_sd15: 'sd15_unet',
}
/** Latent spaces that start from EmptySD3LatentImage (16 channels). */
const SD3_LATENT_STRATEGIES = new Set<WorkflowStrategy>(['unet_chroma', 'unet_hidream', 'unet_sd3', 'unet_lumina2', 'unet_qwenimage1'])
/** Verbatim from comfy_extras/nodes_lumina2.py (SYSTEM_PROMPT["superior"]) and
* the negative of the NetaYume Lumina template. */
const LUMINA2_POSITIVE_SYSTEM = 'You are an assistant designed to generate superior images with the superior degree of image-text alignment based on textual prompts or user prompts.'
const LUMINA2_NEGATIVE_SYSTEM = 'You are an assistant designed to generate low-quality images based on textual prompts'
/** A resolver's "download X" message, turned into the registry spec that can
* fetch X, so Create can offer it instead of pointing at the Model Manager. */
function registrySpecsNamedIn(type: ModelType, message: string): ComponentSpec[] {
const req = COMPONENT_REGISTRY[type]
if (!req) return []
return [req.vae, req.clip, req.clipSecondary, req.audioVae, req.upscaler].filter(
(s): s is ComponentSpec => !!s?.downloadUrl && message.includes(s.downloadFilename),
)
}
/**
* Probe ComfyUI for the video output node we need. When neither VHS nor
* SaveAnimatedWEBP is present, the workflow will fall back to SaveImage
* (single frames on disk) — a user's "videos generate as
* .webp" was caused by VHS missing while SaveAnimatedWEBP still produced
* an animated still. UI calls this BEFORE Generate so users see a banner
* rather than discovering after the fact.
*/
export async function checkVideoOutputCapability(): Promise<{ mp4Capable: boolean; webpOnly: boolean; missingNodes: string[] }> {
const allNodes = await getAllNodeInfo()
const cats = categorizeNodes(allNodes)
// The core's CreateVideo + SaveVideo write mp4 on their own (A19), so VHS is
// only missing when the core can't do it either.
const hasCoreMp4 = cats.videoSavers.includes('CreateVideo') && cats.videoSavers.includes('SaveVideo')
const hasVHS = cats.videoSavers.includes('VHS_VideoCombine')
const hasWebp = cats.videoSavers.includes('SaveAnimatedWEBP')
const mp4Capable = hasCoreMp4 || hasVHS
const missing: string[] = []
if (!mp4Capable) missing.push('VHS_VideoCombine (ComfyUI-VideoHelperSuite)')
return {
mp4Capable,
webpOnly: !mp4Capable && hasWebp,
missingNodes: missing,
}
}
/** Multi-LoRA (a user 2026-06-09) — normalize the `lora` param into an
* ordered list. Accepts a single filename, an array, or a comma/semicolon-
* joined string (the most common LLM shape for "use lora A and lora B" —
* exactly the failing case where the joined string used to reach ComfyUI
* verbatim and die with an opaque "Value not in list"). */
export function normalizeLoraList(lora: string | string[] | undefined): string[] {
if (!lora) return []
const arr = Array.isArray(lora) ? lora : lora.split(/[,;]+/)
return arr.map((s) => (typeof s === 'string' ? s.trim() : '')).filter(Boolean)
}
/** One strength per LoRA: a single number applies to all, an array maps by
* index (missing/invalid entries fall back to 0.8). No range clamp — the
* LoraLoader node itself owns its real min/max (no magic numbers here);
* only non-finite garbage is replaced. */
export function normalizeLoraStrengths(
strength: number | number[] | undefined,
count: number,
): number[] {
const fallback = 0.8
const sane = (v: unknown): number =>
typeof v === 'number' && Number.isFinite(v) ? v : fallback
if (typeof strength === 'number') return Array(count).fill(sane(strength))
if (Array.isArray(strength)) return Array.from({ length: count }, (_, i) => sane(strength[i]))
return Array(count).fill(fallback)
}
/** Resolve requested LoRA names against ComfyUI's installed LoraLoader enum.
* Per name: exact → normalized (case/extension/path-separator insensitive)
* → basename → unique substring. A miss throws an actionable error listing
* what IS installed (same pattern as the Fix-C encoder hint) instead of
* letting ComfyUI reject the whole workflow with "Value not in list". */
export function resolveLoraNames(requested: string[], installed: string[]): string[] {
return requested.map((req) => {
const hit = resolveLoaderName(req, installed)
if (!hit) {
const list = installed.length ? installed.slice(0, 12).join(', ') : '(none installed)'
throw new Error(
`LoRA "${req}" is not installed in ComfyUI. Installed LoRAs: ${list}. ` +
`Put the .safetensors file into ComfyUI/models/loras and retry, or drop the lora setting.`,
)
}
return hit
})
}
/**
* Normalize a remembered loader value (path separator, case, an optional
* subfolder prefix) against ComfyUI's live enum for that loader, WITHOUT the
* loose substring tier resolveLoaderName uses for LoRA names below. That
* tier is right for a LoRA name an LLM paraphrased ("pixel art" for
* "pixel-art-xl.safetensors") but wrong here: a short live entry like
* "ae.safetensors" is a substring of almost anything ending in those two
* letters, so "old-2.6.9-remembered-vae.safetensors" would falsely resolve
* to it. K2 (review-create.md Punkt 3) only needs cosmetic drift covered
* (separator, case, subfolder prefix), never a guess at a DIFFERENT file.
*/
function normalizeLoaderValue(req: string, installed: string[]): string | null {
if (installed.includes(req)) return req
const norm = (s: string) => s.toLowerCase().replace(/\\/g, '/')
const rq = norm(req)
const exact = installed.filter((c) => norm(c) === rq)
if (exact.length === 1) return exact[0]
const rqBase = rq.split('/').pop() || rq
const byBase = installed.filter((c) => (norm(c).split('/').pop() || '') === rqBase)
if (byBase.length === 1) return byBase[0]
return null
}
/**
* Fuzzy-match a remembered LoRA name (file name, path separator and case
* left unspecified, or paraphrased by an LLM) against ComfyUI's live enum.
*/
function resolveLoaderName(req: string, installed: string[]): string | null {
if (installed.includes(req)) return req
const norm = (s: string) =>
s.toLowerCase().replace(/\.(safetensors|pt|ckpt|bin)$/i, '').replace(/\\/g, '/')
// Separator-insensitive form: users/LLMs say "pixel art" for
// "pixel-art-xl.safetensors" — spaces, dashes and underscores all collapse.
const loose = (s: string) => norm(s).replace(/[-_\s]+/g, '')
const rq = norm(req)
let hits = installed.filter((c) => norm(c) === rq)
if (hits.length === 1) return hits[0]
// Enum entries can be "subfolder/name.safetensors": try basename equality.
const rqBase = rq.split('/').pop() || rq
hits = installed.filter((c) => (norm(c).split('/').pop() || '') === rqBase)
if (hits.length === 1) return hits[0]
// Unique substring either way round (separator-insensitive).
const rqLoose = loose(req)
hits = installed.filter((c) => loose(c).includes(rqLoose) || rqLoose.includes(loose(c)))
if (hits.length === 1) return hits[0]
return null
}
/**
* The `resolution` widget of TextEncodeQwenImage21, for an edit.
*
* It is not a width. The node reads it as a total pixel budget per reference
* image, resizes each one to about `resolution x resolution` pixels at
* multiples of 32 and keeps its aspect ratio, and the result follows the first
* reference. So the requested canvas is folded into a single side length and
* the edit comes back in the shape of the source at the size the user picked.
* At the default 1024x1024 this is exactly 1024, the node's own default.
*
* Not 0 (the official template's value, meaning "keep the original size"):
* a phone photo is 12 megapixels, far past the model's 2K class, and it would
* be handed straight to the sampler. Clamped to the node's declared range
* (0 to 4096, step 32), with 32 as the floor so a tiny canvas cannot produce
* a zero that would silently switch the node back to original size.
*/
export function qwenEditResolution(width: number, height: number): number {
const px = (v: number) => (Number.isFinite(v) && v > 0 ? v : 1024)
const side = Math.sqrt(px(width) * px(height))
return Math.min(4096, Math.max(32, Math.round(side / 32) * 32))
}
export async function buildDynamicWorkflow(
params: GenerateParams | VideoParams,
modelType?: ModelType,
): Promise<ComfyApiGraph> {
const type = modelType || classifyModel(params.model)
const isVideo = 'frames' in params
const videoParams = params as VideoParams
// Fetch node info (cached)
const allNodes = await getAllNodeInfo()
const nodes = categorizeNodes(allNodes)
const models = detectAvailableModels(allNodes)
// ─── Background removal (RMBG cutout) ───
// A cutout needs no diffusion model, so branch out before strategy detection.
// ComfyUI-RMBG (node class "RMBG"): LoadImage → RMBG → SaveImage. We read the
// node's REAL input schema live and default every widget from it, so we never
// hard-code an enum spelling a future RMBG version could reject with a ComfyUI
// 400 ("Value not in list"). Gated upstream by caps.rmbg.
const gp = params as GenerateParams
if (!isVideo && gp.removebg && gp.inputImage) {
const rmbgMeta = allNodes['RMBG']
if (!rmbgMeta) {
throw new WorkflowUnavailableError(
'The background-removal node (ComfyUI-RMBG) is not installed in ComfyUI. Install it from the Remove Background tab, then try again.',
'unavailable',
{ pack: 'ComfyUI-RMBG', url: 'https://github.com/1038lab/ComfyUI-RMBG' },
)
}
return buildRemoveBgWorkflow(gp, rmbgMeta)
}
// ─── Reference to video (Animate with a Ref2V model, D24) ───
// Before the strategy table: VACE has no entry there (it is a Motion lane
// family), and Phantom/MAGREF classify as plain Wan, whose i2v override
// would feed the picture to WanImageToVideo as a first frame. Without a
// picture Phantom and MAGREF stay the text to video runs they always were;
// VACE has no such run in LU.
const refFamily = isVideo ? ref2vFamily(params.model) : null
// B38: never drop an end image or further references without a word. A
// model that cannot take them refuses, and Create shows why.
if (isVideo && videoParams.endImage && !localEndFrame(params.model)) {
throw new WorkflowUnavailableError(`${params.model} starts from one image and cannot also take an end image. ${LOCAL_END_FRAME_MODELS}`, 'unavailable')
}
if (isVideo && (gp.referenceImages?.length ?? 0) > 0 && localAnimateReferenceSlots(params.model) === 0) {
throw new WorkflowUnavailableError(`${params.model} reads one picture. Several references work with MiniMax H3 Reference (ref2va).`, 'unavailable')
}
if (refFamily && (videoParams.inputImage || refFamily === 'vace')) {
const refusal = ref2vRefusal(params.model)
if (refusal) throw new WorkflowUnavailableError(refusal, 'unavailable')
if (!videoParams.inputImage) {
throw new WorkflowUnavailableError('This reference model needs a picture to work from. Use it on the Animate tab and add the image there.', 'unavailable')
}
try {
return await buildVaceReferenceWorkflow(videoParams, resolveRunSeed(params.seed), nodes, allNodes)
} catch (err) {
if (!(err instanceof Error) || err instanceof WorkflowUnavailableError) throw err
throw new WorkflowUnavailableError(err.message, 'unet_video', undefined, { missing: registrySpecsNamedIn('wan', err.message) })
}
}
const determined = determineStrategy(type, isVideo, nodes, models)
const { reason, installHint } = determined
let strategy = determined.strategy
log.info(`[dynamic-workflow] Strategy: ${strategy} (${reason})`)
if (strategy === 'unavailable') {
// "Update ComfyUI" reasons are fixable in place (lib/render-fixups.ts).
throw new WorkflowUnavailableError(reason, strategy, installHint, { needsComfyUpdate: /update comfyui/i.test(reason) })
}
// The loader follows the FOLDER the file sits in, not what its family
// usually ships as (Discord 2026-09-28). CheckpointLoaderSimple only lists
// models/checkpoints, UNETLoader only diffusion_models/unet, and a name in
// the wrong one is ComfyUI's "Value not in list".
const listedCheckpoints = nodeComboOptions(allNodes, 'CheckpointLoaderSimple', 'ckpt_name')
const listedUnets = [
...nodeComboOptions(allNodes, 'UNETLoader', 'unet_name'),
...nodeComboOptions(allNodes, 'UnetLoaderGGUF', 'unet_name'),
]
const inCheckpoints = listedCheckpoints.includes(params.model)
const inUnets = listedUnets.includes(params.model)
if (strategy === 'checkpoint' && !inCheckpoints && inUnets && (type === 'sdxl' || type === 'sd15')) {
// A bare SDXL / SD 1.5 unet: its text encoders and VAE come separately.
strategy = type === 'sdxl' ? 'unet_sdxl' : 'unet_sd15'
}
// An all-in-one file of a UNET family in models/checkpoints (the FLUX fp8
// and SD 3.5 checkpoints, NetaYume Lumina, CivitAI merges): MODEL comes from
// CheckpointLoaderSimple, and its own CLIP/VAE when it carries them.
const fromCheckpoint = strategy !== 'checkpoint' && strategy !== 'animatediff'
&& listedCheckpoints.length > 0 && inCheckpoints && !inUnets
// Local Edit (mask inpaint) runs on the SDXL/SD1.5 checkpoint pipeline only.
// Reject other strategies explicitly instead of silently dropping the mask —
// the pre-2.5.7 behavior was exactly that: a masked edit fell through to
// plain img2img and repainted the WHOLE image.
//
// Qwen-Image 2.1 stays behind this gate on purpose, although the model
// itself can do local edits. TextEncodeQwenImage21 takes no mask input at
// all (see its schema: clip, prompt, negative_prompt, vae, resolution and
// the image slots), so a painted mask would be dropped exactly the way this
// check exists to prevent. The model's own route for a local change is a
// marking drawn into the picture plus a prompt that names it, which is a
// different surface from the mask editor and is not built in this cut.
const sdCheckpointFamily = strategy === 'checkpoint' || strategy === 'unet_sdxl' || strategy === 'unet_sd15'
if (!isVideo && gp.inputImage && gp.maskImage && !sdCheckpointFamily) {
throw new WorkflowUnavailableError(
'Local image editing needs an SD 1.5 / SDXL checkpoint. Pick a checkpoint model for Edit. FLUX and video models are not wired for local inpaint.',
strategy,
)
}
const seed = resolveRunSeed(params.seed)
// ─── Wrapper Strategies (custom node pipelines — completely different node chains) ───
// A wrapper builder looks up its own encoder and VAEs. A file it cannot
// find has to reach Create as that sentence plus its download, never as a
// reason to try the old checkpoint graph (Discord 2026-09-29 and 10-01:
// "CheckpointLoaderSimple: Value not in list" for MiniMax H3).
const wrapper = async (build: () => Promise<ComfyApiGraph> | ComfyApiGraph) => {
try {
return await build()
} catch (err) {
if (!(err instanceof Error) || err instanceof WorkflowUnavailableError) throw err
throw new WorkflowUnavailableError(err.message, strategy, undefined, { missing: registrySpecsNamedIn(type, err.message) })
}
}
if (strategy === 'svd') {
return wrapper(() => buildSVDWorkflow(params as VideoParams, seed, nodes))
}
if (strategy === 'wan22') {
return wrapper(() => buildWan22Workflow(params as VideoParams, seed, nodes, allNodes))
}
if (strategy === 'framepack') {
return wrapper(() => buildFramePackWorkflow(params as VideoParams, seed, nodes))
}
if (strategy === 'minimaxh3') {
return wrapper(() => buildMiniMaxH3Workflow(params as VideoParams, seed, allNodes))
}
if (strategy === 'ltx25') {
return wrapper(() => buildLtx25Workflow(params as VideoParams, seed, allNodes))
}
// ─── Standard Strategies (UNET/Checkpoint → CLIP → Latent → KSampler → VAEDecode) ───
const workflow: ComfyApiGraph = {}
let n = 1 // node counter
// ─── Phase 1: Model Loading ───
let modelNodeId: string
let clipSourceId: string
let clipOutputSlot: number
let vaeSourceId: string
let vaeOutputSlot: number
let samplerModelId: string
if (strategy === 'checkpoint') {
assertCheckpointListed(params.model, allNodes)
// Single loader: outputs MODEL (0), CLIP (1), VAE (2)
modelNodeId = String(n++)
workflow[modelNodeId] = {
class_type: 'CheckpointLoaderSimple',
inputs: { ckpt_name: params.model },
}
clipSourceId = modelNodeId
clipOutputSlot = 1
vaeSourceId = modelNodeId
vaeOutputSlot = 2
samplerModelId = modelNodeId
} else if (SNIFFED_FAMILY[strategy]) {
// ─── Header-sniffed families (Discord 2026-09-28) ───
const family = SNIFFED_FAMILY[strategy]!
const modelId = String(n++)
const clipId = String(n++)
if (fromCheckpoint) {
workflow[modelId] = { class_type: 'CheckpointLoaderSimple', inputs: { ckpt_name: params.model } }
} else {
addUnetLoader(workflow, modelId, params.model, allNodes)
}
// An all-in-one checkpoint brings its own encoder / VAE. Known from the
// header; when the header was not readable, the separate files are tried
// first and the checkpoint's own outputs are the fallback.
const parts = gp.modelParts
const ownClip = fromCheckpoint && !!parts?.textEncoder
const ownVae = fromCheckpoint && !!parts?.vae
let resolved: { encoders: string[]; vae?: string }
try {
resolved = resolveFamilyParts(family, models.clips, models.vaes, { encoders: !ownClip, vae: !ownVae })
} catch (err) {
if (!(err instanceof MissingComponentsError)) throw err
if (fromCheckpoint && !parts) {
resolved = { encoders: [], vae: undefined }
} else {
throw new WorkflowUnavailableError(err.message, strategy, undefined, { missing: err.missing })
}
}
const useOwnClip = ownClip || (fromCheckpoint && resolved.encoders.length === 0)
const useOwnVae = ownVae || (fromCheckpoint && !resolved.vae)
if (!useOwnClip) {
const [e1, e2, e3, e4] = resolved.encoders
const clipNode: { class_type: string; inputs: ComfyNodeInputs } =
family === 'hidream' ? { class_type: 'QuadrupleCLIPLoader', inputs: { clip_name1: e1, clip_name2: e2, clip_name3: e3, clip_name4: e4 } }
: family === 'sd3' ? { class_type: 'TripleCLIPLoader', inputs: { clip_name1: e1, clip_name2: e2, clip_name3: e3 } }
: family === 'sdxl_unet' ? { class_type: 'DualCLIPLoader', inputs: { clip_name1: e1, clip_name2: e2, type: 'sdxl' } }
: {
class_type: 'CLIPLoader',
inputs: {
clip_name: e1,
type: family === 'chroma' ? 'chroma' : family === 'lumina2' ? 'lumina2' : family === 'qwenimage1' ? 'qwen_image' : 'stable_diffusion',
device: 'default',
},
}
if (!allNodes[clipNode.class_type]) {
throw new WorkflowUnavailableError(
`Your ComfyUI is too old for this model (it has no ${clipNode.class_type} node). Update ComfyUI, then try again.`,
strategy, undefined, { needsComfyUpdate: true },
)
}
if (clipNode.class_type === 'CLIPLoader') assertClipTypeKnown(String(clipNode.inputs.type), type, strategy, allNodes)
workflow[clipId] = clipNode
clipSourceId = clipId
clipOutputSlot = 0
} else {
clipSourceId = modelId
clipOutputSlot = 1
}
if (!useOwnVae) {
const vaeId = String(n++)
workflow[vaeId] = { class_type: 'VAELoader', inputs: { vae_name: resolved.vae! } }
vaeSourceId = vaeId
vaeOutputSlot = 0
} else {
vaeSourceId = modelId
vaeOutputSlot = 2
}
modelNodeId = modelId
samplerModelId = modelId
} else if (strategy === 'unet_flux' || strategy === 'unet_flux2' || strategy === 'unet_krea2' || strategy === 'unet_zimage' || strategy === 'unet_ernie_image' || strategy === 'unet_qwenimage' || strategy === 'unet_video' || strategy === 'unet_ltx'
|| strategy === 'unet_mochi' || strategy === 'unet_cosmos') {
// Separate loaders
const unetId = String(n++)
const clipId = String(n++)
const clipType = type === 'zimage' ? 'qwen_image'
// Verbatim from the official templates: CLIPLoader type stays
// 'qwen_image' for Qwen-Image 2.1, the same widget value Z-Image uses.
: type === 'qwenimage' ? 'qwen_image'
: type === 'ernie_image' ? 'flux2'
: type === 'flux2' ? 'flux2'
: type === 'krea2' ? 'krea2'
: type === 'flux' ? 'flux'
: type === 'ltx' ? 'ltxv'
: (type === 'wan' || type === 'hunyuan') ? 'wan'
: type === 'mochi' ? 'mochi'
: type === 'cosmos' ? 'cosmos'
: 'flux'
// Resolve the text encoder from the LIVE ComfyUI node enum. CRITICAL
// (Bug C / a user "CLIPLoader: Value not in list"): do NOT silently fall
// back to models.clips[0] / '' on a miss — an empty or wrong clip_name makes
// ComfyUI reject the prompt with that exact cryptic error. The resolvers
// throw actionable "download <encoder>" messages; propagate them as a
// WorkflowUnavailableError so the user gets the download hint instead of a
// raw rejection. Pass the active UNet filename so the resolver prefers the
// matching quant tier (fp4 model → fp4 encoder; fp8/bf16 → full precision).
//
// C2 (a user follow-up, v2.5.3 fix #5): modern ComfyUI (v0.12.0 confirmed)
// removed 'flux' from the single CLIPLoader's type enum — FLUX v1 text
// encoding lives in DualCLIPLoader (clip_name1 = T5-XXL, clip_name2 =
// CLIP-L, type 'flux'), which has shipped with every FLUX-era ComfyUI.
// Emit it whenever the instance has the node; the single-CLIPLoader path
// stays as the fallback for pre-FLUX-era instances (whose CLIPLoader enum
// still contains 'flux'). Same pattern as the HunyuanVideo DualCLIPLoader
// below.
const useDualFluxClip = type === 'flux' && nodes.loaders.includes('DualCLIPLoader')
// An all-in-one file in models/checkpoints (see fromCheckpoint): its own
// encoder / VAE are used when the header says it carries them, and are the
// fallback when the header could not be read.
const parts = gp.modelParts
const carriesClip = fromCheckpoint && (parts ? parts.textEncoder : true)
const carriesVae = fromCheckpoint && (parts ? parts.vae : true)
const skipClipLookup = fromCheckpoint && !!parts?.textEncoder
let clip = ''
let fluxPair: { t5: string; clipL: string } | null = null
if (skipClipLookup) {
// nothing to look up
} else if (useDualFluxClip) {
try {
fluxPair = await findFluxCLIPPair()
} catch (clipErr) {
if (!carriesClip) {
const message = clipErr instanceof Error ? clipErr.message : 'Required text encoder not found in ComfyUI.'
throw new WorkflowUnavailableError(message, strategy, undefined, { missing: registrySpecsNamedIn(type, message) })
}
clip = ''
}
} else {
try {
clip = await findMatchingCLIP(type, params.model, params.qwenTextEncoder)
} catch (clipErr) {
if (!carriesClip) {
const message = clipErr instanceof Error ? clipErr.message : 'Required text encoder not found in ComfyUI.'
throw new WorkflowUnavailableError(message, strategy, undefined, { missing: registrySpecsNamedIn(type, message) })
}
clip = ''
}
}
// VAE is only loaded for strategies with a separate VAELoader — LTX bakes it
// into the pipeline, so a missing VAE there is fine. Validate (same
// no-silent-fallback rule) only when it will actually be used.
const needsVAELoader = strategy !== 'unet_ltx'
let vae = ''
if (needsVAELoader && !(fromCheckpoint && parts?.vae)) {
try {
vae = await findMatchingVAE(type)
} catch (vaeErr) {
if (!carriesVae) {
const message = vaeErr instanceof Error ? vaeErr.message : 'Required VAE not found in ComfyUI.'
throw new WorkflowUnavailableError(message, strategy, undefined, { missing: registrySpecsNamedIn(type, message) })
}
}
}
const clipFromFile = !clip && !fluxPair
const vaeFromFile = needsVAELoader && !vae
if (!useDualFluxClip && !clipFromFile) assertClipTypeKnown(clipType, type, strategy, allNodes)
if (fromCheckpoint) {
workflow[unetId] = { class_type: 'CheckpointLoaderSimple', inputs: { ckpt_name: params.model } }
} else {
addUnetLoader(workflow, unetId, params.model, allNodes)
}
if (!clipFromFile) workflow[clipId] = useDualFluxClip && fluxPair
? {
class_type: 'DualCLIPLoader',
inputs: { clip_name1: fluxPair.t5, clip_name2: fluxPair.clipL, type: 'flux' },
}
: {
class_type: 'CLIPLoader',
inputs: { clip_name: clip, type: clipType, device: 'default' },
}
let vaeId: string
if (needsVAELoader && !vaeFromFile) {
vaeId = String(n++)
workflow[vaeId] = {
class_type: 'VAELoader',
inputs: { vae_name: vae },
}
} else {
vaeId = unetId // fallback reference (won't be used for LTX)
}
modelNodeId = unetId
clipSourceId = clipFromFile ? unetId : clipId
clipOutputSlot = clipFromFile ? 1 : 0
vaeSourceId = vaeId
vaeOutputSlot = vaeFromFile ? 2 : 0
samplerModelId = unetId
} else {
// AnimateDiff: checkpoint + motion model
const ckptId = String(n++)
const motionLoadId = String(n++)
const motionApplyId = String(n++)
const evolvedId = String(n++)
workflow[ckptId] = {
class_type: 'CheckpointLoaderSimple',
inputs: { ckpt_name: params.model },
}
workflow[motionLoadId] = {
class_type: 'ADE_LoadAnimateDiffModel',
inputs: { model_name: models.motionModels[0] },
}
workflow[motionApplyId] = {
class_type: 'ADE_ApplyAnimateDiffModelSimple',
inputs: { motion_model: [motionLoadId, 0] },
}
workflow[evolvedId] = {
class_type: 'ADE_UseEvolvedSampling',
inputs: {
model: [ckptId, 0],
m_models: [motionApplyId, 0],
beta_schedule: 'autoselect',
},
}
modelNodeId = ckptId
clipSourceId = ckptId
clipOutputSlot = 1
vaeSourceId = ckptId
vaeOutputSlot = 2
samplerModelId = evolvedId
}
// ─── Phase 1b: Optional LoRA chain + VAE + Skip-CLIP injection (F2 + F3) ───
//
// LoRA chain (GH#4; multi-LoRA 2026-06-09): each
// LoraLoader takes (model, clip) and outputs new (model, clip) — chaining
// N loaders applies the LoRAs in order, exactly like stacking them in the
// ComfyUI graph editor. We rewire both refs after every link so the rest
// of the pipeline sees the fully-stacked versions. Names are resolved
// against ComfyUI's real LoraLoader enum (fuzzy: extension/case optional)
// and a miss throws an actionable error instead of ComfyUI's opaque
// "Value not in list".
//
// VAE override (GH#4): VAELoader replaces vaeSourceId. The
// checkpoint's bundled VAE stays unused.
//
// Skip CLIP (GH#4): CLIPSetLastLayer takes a negative
// `stop_at_clip_layer` index — passing -clipSkip mirrors A1111 /
// ComfyUI conventions.
//
// All three are skipped (no extra nodes) when the corresponding
// param is unset, so workflows without F2/F3 enabled stay byte-
// identical to the previous behaviour.
// FEHLER-Q1 #1 (3.0.9): a fast Wan 14B run gets its lightx2v LoRAs from
// Fast mode below, once per half at the model card's 1.0. The same LoRA
// picked in the stack would go in a second time (0.8 + 1.0 on the high
// half), so in a fast run the stack's speed LoRAs are left out; every
// other stack LoRA stays, and a quality run keeps the stack as it is.
const fastWan = isVideo && type === 'wan' && strategy === 'unet_video' && !fromCheckpoint
&& !!wanSpeedKind(params.model) && isFastSampling(params.steps, params.cfgScale)
const stackNames = normalizeLoraList(params.lora)
const stackStrengths = normalizeLoraStrengths(params.loraStrength, stackNames.length)
const keepInStack = stackNames.map((l) => !(fastWan && isWanSpeedLoraName(l)))
const loraNames = stackNames.filter((_, i) => keepInStack[i])
if (loraNames.length > 0) {
const installed: string[] =
readComboOptions(allNodes?.LoraLoader?.input?.required?.lora_name) ?? []
const resolved = resolveLoraNames(loraNames, installed)
const strengths = stackStrengths.filter((_, i) => keepInStack[i])
resolved.forEach((loraName, i) => {
const loraId = String(n++)
workflow[loraId] = {
class_type: 'LoraLoader',
inputs: {
lora_name: loraName,
strength_model: strengths[i],
strength_clip: strengths[i],
model: [samplerModelId, 0],
clip: [clipSourceId, clipOutputSlot],
},
}
samplerModelId = loraId
clipSourceId = loraId
clipOutputSlot = 1
})
}
if (params.vae && params.vae !== 'auto') {
// K2: this override used to go straight into VAELoader unchecked, so a
// stale remembered pick (a name that existed in an older LU/ComfyUI
// install, a wrong path separator, a subfolder-qualified name ComfyUI's
// enum does not use) reached /prompt as-is and came back "Value not in
// list". `models.vaes` is the live VAELoader enum already read off this
// same /object_info response, validate against it before writing the
// node. Skip the check only when that enum came back empty (an older
// ComfyUI that answered a different schema): saying nothing is safer
// than a false rejection of a value we simply could not verify.
//
// K2 (review-create.md nachbessert, Punkt 3): a straight `includes()`
// rejected an installed file for a purely cosmetic mismatch (backslash
// vs slash, a leftover subfolder prefix, different case) even though
// ComfyUI would have accepted the LIVE spelling just fine. Normalize
// first via normalizeLoaderValue; on a hit, write the LIVE enum's own
// spelling to the node, not the remembered one, and only throw on a
// genuine miss.
let vaeName = params.vae
if (models.vaes.length > 0 && !models.vaes.includes(vaeName)) {
const resolved = normalizeLoaderValue(vaeName, models.vaes)
if (resolved) {
vaeName = resolved
} else {
const list = models.vaes.slice(0, 12).join(', ')
throw new WorkflowUnavailableError(
`VAE "${params.vae}" is not installed in ComfyUI. Installed VAEs: ${list}. ` +
`Put the file into ComfyUI/models/vae and retry, or clear the VAE override.`,
strategy,
)
}
}
const vaeId = String(n++)
workflow[vaeId] = {
class_type: 'VAELoader',
inputs: { vae_name: vaeName },
}
vaeSourceId = vaeId
vaeOutputSlot = 0
}
if (params.clipSkip && params.clipSkip > 0) {
const skipId = String(n++)
workflow[skipId] = {
class_type: 'CLIPSetLastLayer',
inputs: {
stop_at_clip_layer: -Math.abs(params.clipSkip),
clip: [clipSourceId, clipOutputSlot],
},
}
clipSourceId = skipId
clipOutputSlot = 0
}
// ─── Phase 2: Text Encoding ───
// Qwen-Image 2.1 edit: the reference image belongs to the text encoder
// (TextEncodeQwenImage21 sees it AND splices it in as VAE reference
// latents), not to a VAEEncode latent. Decided here, BEFORE the generic
// isI2I test in Phase 3, which would otherwise claim the image and turn an
// edit instruction into ordinary latent img2img.
const isQwenEdit = !isVideo && strategy === 'unet_qwenimage' && !!gp.inputImage
// Qwen-Image-Edit 2509/2511 (official template image_qwen_image_edit_2509):
// the source goes through TextEncodeQwenImageEditPlus on both sides and is
// the latent itself, sampled at denoise 1.0 like the template.
const isQwen1Edit = !isVideo && strategy === 'unet_qwenimage1' && !!gp.inputImage && isQwenImageEditModel(params.model)
// Extra reference images, only for a family that takes them and only as
// many as it has slots for (lib/edit-references); anything else ignores them.
const references = (isQwenEdit || isQwen1Edit)
? (gp.referenceImages ?? []).slice(0, extraReferenceSlots(type, params.model))
: []
// B45 (Discord 30.10.2026): reference images for text to image, read the
// way each family's official template reads them (lib/frame-refs). A model
// without such a path refuses instead of drawing from the prompt alone.
const createRefsAsked = !isVideo && !gp.inputImage ? (gp.referenceImages ?? []) : []
const createRefSupport = createReferenceSupport(type, params.model)
const createRefStrategy = strategy === 'unet_krea2' || strategy === 'unet_qwenimage' || strategy === 'unet_flux2'
if (createRefsAsked.length > 0 && (createRefSupport.slots === 0 || !createRefStrategy)) {
throw new WorkflowUnavailableError(`${params.model} cannot take reference images. ${CREATE_REFERENCE_MODELS}`, strategy)
}
const createRefs = createRefsAsked.slice(0, createRefSupport.slots)
const krea2StyleRef = strategy === 'unet_krea2' && createRefs.length > 0
if (krea2StyleRef) {
requireRelease(allNodes, ['TextEncodeQwenImageEditPlus', 'FluxKontextMultiReferenceLatentMethod', 'ModelSamplingFlux', 'LoraLoaderModelOnly'],
'Reference images with Krea 2 need a newer ComfyUI. Update ComfyUI, then try again.', strategy)
}
if (strategy === 'unet_flux2' && createRefs.length > 0) {
requireRelease(allNodes, ['ReferenceLatent', 'VAEEncode', 'ImageScaleToTotalPixels'],
'Reference images with FLUX.2 need a newer ComfyUI. Update ComfyUI, then try again.', strategy)
}
// The style reference LoRA of the Krea 2 template. Without it the images
// would reach the model but not steer the style, so Create offers the file.
let krea2StyleLora: string | null = null
if (krea2StyleRef) {
krea2StyleLora = nodeComboOptions(allNodes, 'LoraLoaderModelOnly', 'lora_name')
.find((l) => (l.split(/[\\/]/).pop() ?? '').toLowerCase() === KREA2_STYLE_LORA.filename) ?? null
if (!krea2StyleLora) {
throw new WorkflowUnavailableError(
`Reference images with Krea 2 need the Krea 2 style reference LoRA (${KREA2_STYLE_LORA.filename}, 436 MB) in ComfyUI/models/loras.`,
strategy, undefined,
{ missing: [{ matchPatterns: [KREA2_STYLE_LORA.filename], downloadFilename: KREA2_STYLE_LORA.filename, downloadUrl: KREA2_STYLE_LORA.url, subfolder: 'loras', sizeGB: 0.43, sha256: KREA2_STYLE_LORA.sha256 }] },
)
}
}
// The graphics card, read only for an edit with further images: past what
// it carries, ComfyUI 0.37 ends the run in "aimdo memory compile error"
// (lib/comfy-edit-memory). Not on a Mac, where ComfyUI has no such compiler
// and the figure is the shared memory.
const cardGb = (references.length > 0 || (strategy === 'unet_qwenimage' && createRefs.length > 1)) && !isMacOS()
? await getSystemVRAM().catch(() => null)
: null
const fullImages = comfyEditFullImages(cardGb)
// B46 / D8 (Discord 06.11.2026, 3.0.10): the Edit strength of a Qwen edit,
// as guidance between the edit and no edit. Both encoders also give a
// conditioning of the same images without an instruction ("identity",
// the source as it is); every step the sampler follows
// identity + strength x (edit - identity)
// the way InstructPix2Pix scales its text guidance. 1 is the template's
// edit exactly; lower is the same edit taken less far, on one path from
// noise, so nothing is laid over anything. At CFG 1 (Qwen-Image 2.1, its
// Turbo) that is the sampler's own CFG = strength with identity as the
// negative; at a higher CFG (Qwen-Image-Edit 2509/2511 at 4) DualCFGGuider
// in its nested form, so the user's negative still counts:
// negative + cfg x (identity + strength x (edit - identity) - negative)
// 3.0.9 started the sampler from the source at denoise = strength instead:
// these edit models copy their reference unless they start from pure
// noise, so every value below 1 came back as the source (box run 01.11.).
const qwenEditStrength = (isQwenEdit || isQwen1Edit) && Number.isFinite(gp.editStrength) && gp.editStrength! < 1
? Math.max(0.05, gp.editStrength!)
: 1
const qwenStrengthCfg1 = qwenEditStrength < 1 && Math.abs(params.cfgScale - 1) < 1e-6
const qwenStrengthDual = qwenEditStrength < 1 && !qwenStrengthCfg1
// The conditioning without an instruction, set where the encoder is built.
let qwenIdentityRef: [string, number] | null = null
if (qwenStrengthDual) {
requireRelease(allNodes, ['DualCFGGuider', 'SamplerCustomAdvanced', 'RandomNoise', 'KSamplerSelect', 'BasicScheduler'],
'An Edit strength below 1 needs a newer ComfyUI. Update ComfyUI, or set the Edit strength to 1.', strategy)
}
if (isQwen1Edit) {
const over = qwenEditPlusOverCard(1 + references.length, cardGb)
if (over) throw new WorkflowUnavailableError(over, strategy)
}
if (isQwen1Edit && !allNodes['TextEncodeQwenImageEditPlus']) {
throw new WorkflowUnavailableError(
'Qwen-Image-Edit needs a newer ComfyUI (TextEncodeQwenImageEditPlus). Update ComfyUI, then try again.',
strategy, undefined, { needsComfyUpdate: true },
)
}
let qwen1EditImageRef: [string, number] | null = null
const posId = String(n++)
const negId = String(n++)
if (strategy === 'unet_qwenimage') {
// ONE node carries prompt and negative prompt, the reference image and
// the matching empty latent. Outputs: positive 0, negative 1, latent 2.
//
// Every name here is read off the official Comfy-Org templates
// (image_qwen_image_2_1_t2i.json, image_qwen_image_2_1_image_edit.json)
// and the node's own schema in comfy_extras/nodes_qwen.py, checked
// 2026-09-21. The dotted input id is not a typo: the reference slots are
// an Autogrow group called "images" whose entries are named image_1 to
// image_16, and ComfyUI joins the two with a dot for the API format.
//
// The generate path attaches neither image nor vae, exactly as the t2i
// template does, and takes its latent from EmptyLatentImage below.
// negId is allocated but unused on this path; the graph is keyed by id,
// so a gap costs nothing (the I2I override below already leaves one).
// `resolution` is declared REQUIRED by the node (no optional flag on its
// Int input), so it goes on BOTH paths or ComfyUI answers "Required input
// is missing" before anything runs. It only does work when a reference
// image is attached; on the generate path it is inert, exactly as in the
// t2i template, which also carries the widget and never uses it.
const qwenInputs: ComfyNodeInputs = {
clip: [clipSourceId, clipOutputSlot],
// Transparent background: the model writes an alpha channel when the
// prompt is wrapped the way the official template says, and SaveImage
// below keeps it (lib/transparent-image.ts). An edit takes its picture
// from the reference, so the wrapper stays out of it.
// An edit names its images the way the encoder labels them, <image2>,
// however the user spelled them (lib/image-ref-names).
prompt: isQwenEdit
? canonicalImageRefs(params.prompt, 1 + references.length, 'qwen21')
: createRefs.length > 0 ? canonicalImageRefs(params.prompt, createRefs.length, 'qwen21')
: gp.transparent ? transparentPrompt(params.prompt) : params.prompt,
negative_prompt: isQwenEdit
? canonicalImageRefs(params.negativePrompt || '', 1 + references.length, 'qwen21')
: createRefs.length > 0 ? canonicalImageRefs(params.negativePrompt || '', createRefs.length, 'qwen21')
: params.negativePrompt || '',
// With more images in an edit than the card carries at full size
// (four, fewer on a card under 24 GB) they share a pixel budget
// (referenceSide in lib/edit-references, lib/comfy-edit-memory).
// The node takes ONE side for all of them and the result follows the
// first, so such an edit comes out smaller than the canvas.
resolution: isQwenEdit
? referenceSide(qwenEditResolution(params.width, params.height), 1 + references.length, fullImages)
: createRefs.length > 0 ? referenceSide(qwenEditResolution(params.width, params.height), createRefs.length, fullImages)
: qwenEditResolution(params.width, params.height),
}
if (isQwenEdit) {
// The source is image_1 and sets the output shape; the references the
// user added follow as image_2 and up, the names the prompt uses.
const images = [gp.inputImage!, ...references]
for (const [i, image] of images.entries()) {
const loadId = String(n++)
workflow[loadId] = { class_type: 'LoadImage', inputs: { image } }
let imageRef: [string, number] = [loadId, 0]
if (i === 0 && gp.editShape === 'canvas') {
// C75 (Discord feature-requests 11.11.2026): an edit in a shape of
// its own. The node's latent follows the first image and has to
// (any other latent size shifts the edit), so the source itself is
// brought to the shape first: scaled to cover width x height and
// cropped from its centre. The pixel budget below stays the size.
const scaleId = String(n++)
workflow[scaleId] = {
class_type: 'ImageScale',
inputs: {
image: [loadId, 0],
upscale_method: resizeMethod(allNodes, 'ImageScale', false),
width: params.width,
height: params.height,
crop: 'center',
},
_meta: { title: 'Edit shape' },
}
imageRef = [scaleId, 0]
}
qwenInputs[`images.image_${i + 1}`] = imageRef
}
qwenInputs.vae = [vaeSourceId, vaeOutputSlot]
} else if (createRefs.length > 0) {
// B45: references without a source. They are image_1 and up; the
// picture still comes from the empty latent at the canvas size below.
for (const [i, image] of createRefs.entries()) {
const loadId = String(n++)
workflow[loadId] = { class_type: 'LoadImage', inputs: { image } }
qwenInputs[`images.image_${i + 1}`] = [loadId, 0]
}
qwenInputs.vae = [vaeSourceId, vaeOutputSlot]
}
workflow[posId] = { class_type: 'TextEncodeQwenImage21', inputs: qwenInputs }
if (isQwenEdit && qwenEditStrength < 1) {
// The node's negative is the images with the negative prompt, so with
// none it is the identity already; with one, a second encode.
if ((params.negativePrompt || '').trim() === '') {
qwenIdentityRef = [posId, 1]
} else {
const idId = String(n++)
workflow[idId] = { class_type: 'TextEncodeQwenImage21', inputs: { ...qwenInputs, prompt: '', negative_prompt: '' }, _meta: { title: 'Edit strength: the source as it is' } }
qwenIdentityRef = [idId, 0]
}
}
} else if (isQwen1Edit) {
const loadId = String(n++)
workflow[loadId] = { class_type: 'LoadImage', inputs: { image: gp.inputImage } }
qwen1EditImageRef = [loadId, 0]
if (allNodes['FluxKontextImageScale']) {
// The template scales the source to a size the model was trained on.
const scaleId = String(n++)
workflow[scaleId] = { class_type: 'FluxKontextImageScale', inputs: { image: [loadId, 0] } }
qwen1EditImageRef = [scaleId, 0]
}
// References go in unscaled as image2 and image3: the node resizes every
// extra image itself, only image1 sets the canvas.
const refInputs: ComfyNodeInputs = {}
for (const [i, image] of references.entries()) {
const refId = String(n++)
workflow[refId] = { class_type: 'LoadImage', inputs: { image } }
refInputs[`image${i + 2}`] = [refId, 0]
}
const editInputs = (prompt: string): ComfyNodeInputs => ({
clip: [clipSourceId, clipOutputSlot], prompt, vae: [vaeSourceId, vaeOutputSlot], image1: qwen1EditImageRef!, ...refInputs,
})
// The node labels its images "Picture 1: ", "Picture 2: ", so the prompt
// names them that way too (lib/image-ref-names).
const pictures = (text: string) => canonicalImageRefs(text, 1 + references.length, 'qwenEditPlus')
workflow[posId] = { class_type: 'TextEncodeQwenImageEditPlus', inputs: editInputs(pictures(params.prompt)) }
workflow[negId] = { class_type: 'TextEncodeQwenImageEditPlus', inputs: editInputs(pictures(params.negativePrompt || '')) }
if (qwenEditStrength < 1) {
// The same images without an instruction: the negative when it is
// empty, else an encode of its own.
if ((params.negativePrompt || '').trim() === '') {
qwenIdentityRef = [negId, 0]
} else {
const idId = String(n++)
workflow[idId] = { class_type: 'TextEncodeQwenImageEditPlus', inputs: editInputs(''), _meta: { title: 'Edit strength: the source as it is' } }
qwenIdentityRef = [idId, 0]
}
}
} else if (krea2StyleRef) {
// B45: the official Krea 2 style reference template. The images go
// through TextEncodeQwenImageEditPlus (image1 to image3), the reference
// latents are placed with index_timestep_zero, and the negative is the
// zeroed positive at CFG 1, as the template runs it.
const encId = String(n++)
const encInputs: ComfyNodeInputs = {
clip: [clipSourceId, clipOutputSlot],
prompt: canonicalImageRefs(params.prompt, createRefs.length, 'qwenEditPlus'),
vae: [vaeSourceId, vaeOutputSlot],
}
for (const [i, image] of createRefs.entries()) {
const loadId = String(n++)
workflow[loadId] = { class_type: 'LoadImage', inputs: { image } }
encInputs[`image${i + 1}`] = [loadId, 0]
}
workflow[encId] = { class_type: 'TextEncodeQwenImageEditPlus', inputs: encInputs }
workflow[posId] = {
class_type: 'FluxKontextMultiReferenceLatentMethod',
inputs: { conditioning: [encId, 0], reference_latents_method: 'index_timestep_zero' },
}
workflow[negId] = { class_type: 'ConditioningZeroOut', inputs: { conditioning: [posId, 0] } }
} else {
workflow[posId] = {
class_type: 'CLIPTextEncode',
inputs: {
// Lumina 2 is trained on a system prompt ahead of the user's; without
// it the output drifts badly (CLIPTextEncodeLumina2 does the same join).
text: strategy === 'unet_lumina2' ? `${LUMINA2_POSITIVE_SYSTEM} <Prompt Start> ${params.prompt}` : params.prompt,
clip: [clipSourceId, clipOutputSlot],
},
}
if (strategy === 'unet_ernie_image' || (strategy === 'unet_krea2' && params.cfgScale === 1)) {
// ERNIE-Image always, and Krea 2 at CFG 1 (K9, GH #136, LUSTIFY! v10
// Krea2): the negative branch is a no-op at CFG 1, so ConditioningZeroOut
// replaces the wasted CLIPTextEncode pass (NOT a plain negative prompt).
workflow[negId] = {
class_type: 'ConditioningZeroOut',
inputs: { conditioning: [posId, 0] },
}
} else {
workflow[negId] = {
class_type: 'CLIPTextEncode',
inputs: {
text: strategy === 'unet_lumina2'
? `${LUMINA2_NEGATIVE_SYSTEM} <Prompt Start> ${params.negativePrompt || ''}`
: params.negativePrompt || '',
clip: [clipSourceId, clipOutputSlot],
},
}
}
}
// ─── Phase 3: Latent Initialization ───
// Inpaint mode (local Edit): source + painted mask on the checkpoint path.
// Takes precedence over plain I2I — a mask means "repaint THIS area", never
// "repaint everything". Ported 1:1 from the web app's tested builder
// (create-workflows.ts): same node classes, same defaults.
const isInpaint = !isVideo && !!gp.inputImage && !!gp.maskImage && sdCheckpointFamily
// I2I mode: LoadImage → VAEEncode instead of empty latent. A Qwen-Image 2.1
// edit is excluded: its reference image is already wired into the text
// encoder above, and its sampler runs at denoise 1.0 like the official
// template (instruction editing, not a partial re-noise of the source).
const isI2I = !isVideo && !isInpaint && !isQwenEdit && !isQwen1Edit && params.inputImage && (params.denoise ?? 1.0) < 1.0
const latentId = String(n++)
if (strategy === 'unet_video') {
// Wan/Hunyuan video latent
const latentNode = nodes.latentInit.includes('EmptyHunyuanLatentVideo')
? 'EmptyHunyuanLatentVideo'
: 'EmptyLatentImage'
workflow[latentId] = {
class_type: latentNode,
inputs: latentNode === 'EmptyHunyuanLatentVideo'
? { width: params.width, height: params.height, length: videoParams.frames, batch_size: 1 }
: { width: params.width, height: params.height, batch_size: videoParams.frames },
}
} else if (strategy === 'animatediff') {
// AnimateDiff: batch_size = frames
workflow[latentId] = {
class_type: 'EmptyLatentImage',
inputs: { width: params.width, height: params.height, batch_size: videoParams.frames },
}
} else if (strategy === 'unet_mochi') {
// Mochi video latent
const latentNode = nodes.latentInit.includes('EmptyMochiLatentVideo')
? 'EmptyMochiLatentVideo'
: 'EmptyHunyuanLatentVideo'
workflow[latentId] = {
class_type: latentNode,
inputs: { width: params.width, height: params.height, length: videoParams.frames, batch_size: 1 },
}
} else if (strategy === 'unet_cosmos') {
// Cosmos video latent
const latentNode = nodes.latentInit.includes('EmptyCosmosLatentVideo')
? 'EmptyCosmosLatentVideo'
: 'EmptyHunyuanLatentVideo'
workflow[latentId] = {
class_type: latentNode,
inputs: { width: params.width, height: params.height, length: videoParams.frames, batch_size: 1 },
}
} else if (strategy === 'unet_ltx') {
// LTX Video latent — uses length instead of batch_size
workflow[latentId] = {
class_type: 'EmptyLTXVLatentVideo',
inputs: { width: params.width, height: params.height, length: videoParams.frames, batch_size: 1 },
}
} else if (strategy === 'unet_flux2' || strategy === 'unet_ernie_image') {
// FLUX 2 / ERNIE-Image use Flux2 latent node
const latentNode = nodes.latentInit.includes('EmptyFlux2LatentImage')
? 'EmptyFlux2LatentImage'
: 'EmptySD3LatentImage'
workflow[latentId] = {
class_type: latentNode,
inputs: { width: params.width, height: params.height, batch_size: params.batchSize },
}
} else if (strategy === 'unet_qwenimage') {
// Qwen-Image 2.1 generate: plain EmptyLatentImage, the node the official
// t2i template uses. Its autoencoder has 64 channels and compresses 16x
// where this node writes 4 channels at an eighth, but the node reports
// its own downscale_ratio_spacial and ComfyUI repairs an all-zero latent
// to the model's format before sampling, so the canvas comes out at the
// size that was asked for. On the edit path this node is dropped again
// further down: there the latent comes from TextEncodeQwenImage21, so
// the result follows the reference image.
workflow[latentId] = {
class_type: 'EmptyLatentImage',
inputs: { width: params.width, height: params.height, batch_size: params.batchSize },
}
} else if (SD3_LATENT_STRATEGIES.has(strategy)) {
// Chroma, HiDream, SD 3.5, Lumina 2 and Qwen-Image 1: EmptySD3LatentImage,
// as in every one of their official templates.
workflow[latentId] = {
class_type: nodes.latentInit.includes('EmptySD3LatentImage') ? 'EmptySD3LatentImage' : 'EmptyLatentImage',
inputs: { width: params.width, height: params.height, batch_size: params.batchSize },
}
} else if (strategy === 'unet_zimage') {
// Z-Image uses SD3 latent (same architecture family)
const latentNode = nodes.latentInit.includes('EmptySD3LatentImage')
? 'EmptySD3LatentImage'
: 'EmptyLatentImage'
workflow[latentId] = {
class_type: latentNode,
inputs: { width: params.width, height: params.height, batch_size: params.batchSize },
}
} else if (strategy === 'unet_flux') {
// FLUX 1 uses SD3 latent
const latentNode = nodes.latentInit.includes('EmptySD3LatentImage')
? 'EmptySD3LatentImage'
: 'EmptyLatentImage'
workflow[latentId] = {
class_type: latentNode,
inputs: { width: params.width, height: params.height, batch_size: params.batchSize },
}
} else {
// Checkpoint (SDXL/SD1.5)
workflow[latentId] = {
class_type: 'EmptyLatentImage',
inputs: { width: params.width, height: params.height, batch_size: params.batchSize },
}
}
// The sampler consumes these refs; the I2I/inpaint overrides re-point them.
let latentRef: [string, number] = [latentId, 0]
let positiveRef: [string, number] = [posId, 0]
let negativeRef: [string, number] = [negId, 0]
if (strategy === 'unet_qwenimage') {
// One encode node, both conditionings (slots 0 and 1).
negativeRef = [posId, 1]
if (isQwenEdit) {
// ...and, with a reference image attached, the latent too (slot 2): an
// empty latent on the reference's own size, which the node's tooltip
// calls out as required, because any other size shifts the edit.
latentRef = [posId, 2]
delete workflow[latentId]
}
}
if (isQwen1Edit && qwen1EditImageRef) {
const encId = String(n++)
workflow[encId] = { class_type: 'VAEEncode', inputs: { pixels: qwen1EditImageRef, vae: [vaeSourceId, vaeOutputSlot] } }
latentRef = [encId, 0]
delete workflow[latentId]
}
// I2I override: replace empty latent with LoadImage → VAEEncode
if (isI2I) {
const loadImageId = String(n++)
const vaeEncodeId = String(n++)
workflow[loadImageId] = {
class_type: 'LoadImage',
inputs: { image: params.inputImage },
}
workflow[vaeEncodeId] = {
class_type: 'VAEEncode',
inputs: { pixels: [loadImageId, 0], vae: [vaeSourceId, vaeOutputSlot] },
}
latentRef = [vaeEncodeId, 0]
// Remove the empty latent node since we're using the encoded image
delete workflow[latentId]
} else if (isInpaint) {
// Inpaint override: LoadImage + LoadImageMask (channel red — the mask
// editor exports white-where-painted on black), then:
// Path B (InpaintModelConditioning, FLUX-fill/SD3-style) when the node
// exists — rewrites BOTH conditionings and emits the latent on slot 2.
// Path A (core VAEEncodeForInpaint) — works with any SDXL/SD1.5
// checkpoint; grow_mask_by feathers the mask edge.
const loadImageId = String(n++)
const loadMaskId = String(n++)
workflow[loadImageId] = {
class_type: 'LoadImage',
inputs: { image: params.inputImage },
}
workflow[loadMaskId] = {
class_type: 'LoadImageMask',
inputs: { image: gp.maskImage, channel: 'red' },
}
if (allNodes['InpaintModelConditioning']) {
const condId = String(n++)
workflow[condId] = {
class_type: 'InpaintModelConditioning',
inputs: {
positive: positiveRef, negative: negativeRef,
vae: [vaeSourceId, vaeOutputSlot],
pixels: [loadImageId, 0], mask: [loadMaskId, 0], noise_mask: true,
},
_meta: { title: 'Inpaint Path B' },
}
positiveRef = [condId, 0]
negativeRef = [condId, 1]
latentRef = [condId, 2]
} else {
const encId = String(n++)
workflow[encId] = {
class_type: 'VAEEncodeForInpaint',
inputs: {
pixels: [loadImageId, 0], vae: [vaeSourceId, vaeOutputSlot],
mask: [loadMaskId, 0], grow_mask_by: gp.growMaskBy ?? 6,
},
_meta: { title: 'Inpaint Path A' },
}
latentRef = [encId, 0]
}
delete workflow[latentId]
}
// ─── I2V override (Animate — local lane restored, 2026-07-17) ───
// A video request carrying an inputImage swaps the empty latent for the
// family's image-to-video conditioning node. Covers every family core
// ComfyUI can animate on this main path (WAN i2v, Hunyuan i2v, LTX,
// Cosmos); wan22/SVD/FramePack already handle the image in their dedicated
// builders above. Wiring is schema-driven — we only feed inputs the live
// node declares and map outputs by their declared types — so version drift
// in these nodes degrades to a ComfyUI validation error, not a bad graph.
// A later section of a long clip (B18) is an I2V run too: it starts on the
// last frames of the clip so far instead of on one picture.
const continueFrom = isVideo ? videoParams.continueFrom : undefined
let continued: ContinueSource | null = null
const isI2V = isVideo && (!!(params as GenerateParams).inputImage || !!continueFrom)
if (isI2V && ['unet_video', 'unet_ltx', 'unet_cosmos', 'unet_mochi'].includes(strategy)) {
if (strategy === 'unet_mochi') {
throw new WorkflowUnavailableError(
'Mochi is text-to-video only, pick an i2v-capable model (WAN i2v, WAN 2.2 ti2v, SVD, LTX, Cosmos) to animate an image.',
strategy,
)
}
// B38: an end image turns the Wan run into first and last frame
// (WanFirstLastFrameToVideo, the node of the official FLF2V templates).
const endImage = continueFrom ? undefined : videoParams.endImage
const i2vNode =
strategy === 'unet_ltx' ? 'LTXVImgToVideo'
: strategy === 'unet_cosmos' ? 'CosmosImageToVideoLatent'
: type === 'hunyuan' ? 'HunyuanImageToVideo'
: endImage ? 'WanFirstLastFrameToVideo'
: 'WanImageToVideo'
const meta = allNodes[i2vNode]
if (!meta) {
throw new WorkflowUnavailableError(
`Animating with this model family needs the ${i2vNode} node, which your ComfyUI doesn't have. Update ComfyUI, then try again.`,
strategy,
undefined,
{ needsComfyUpdate: true },
)
}
if (continueFrom && i2vNode !== 'WanImageToVideo') {
throw new WorkflowUnavailableError('Continuing a clip in sections works with Wan, Wan 2.2 and LTX 2.5. Pick one of those models, or make this clip in one run.', strategy)
}
let startRef: [string, number]
if (continueFrom) {
requireContinueNodes(allNodes, strategy)
continued = addContinueSource(workflow, n, continueFrom, allNodes)
n = continued.n
startRef = continued.tail
} else {
const loadId = String(n++)
workflow[loadId] = { class_type: 'LoadImage', inputs: { image: (params as GenerateParams).inputImage } }
startRef = [loadId, 0]
}
const required = meta.input?.required ?? {}
const optional = meta.input?.optional ?? {}
const decl = { ...required, ...optional }
const inputs: ComfyNodeInputs = {}
if (decl.positive) inputs.positive = positiveRef
if (decl.negative) inputs.negative = negativeRef
if (decl.vae) inputs.vae = [vaeSourceId, vaeOutputSlot]
if (decl.width) inputs.width = params.width
if (decl.height) inputs.height = params.height
if (decl.length) inputs.length = videoParams.frames
if (decl.batch_size) inputs.batch_size = 1
if (decl.start_image) inputs.start_image = startRef
else if (decl.image) inputs.image = startRef
else if (decl.init_image) inputs.init_image = startRef
if (endImage && decl.end_image) {
const endId = String(n++)
workflow[endId] = { class_type: 'LoadImage', inputs: { image: endImage } }
inputs.end_image = [endId, 0]
}
// SVI-style anti-drift padding (core WanImageToVideo, 2026): the empty
// frames of a continued section are filled with the clip's first picture
// instead of grey, so faces and colours stay where the clip started.
if (continued && decl.ref_pad_image) inputs.ref_pad_image = continued.first
// Remaining REQUIRED widgets we don't model: take the schema default,
// for a combo the first option. Same live-schema pattern as the RMBG
// builder, and the combo read goes through the one shared reader so the
// newer COMBO/options shape cannot leave a required widget unset.
for (const [key, spec] of Object.entries(required)) {
if (inputs[key] !== undefined) continue
const combo = readComboOptions(spec)
if (combo && combo.length) inputs[key] = combo[0]
else {
const dflt = specDefault(spec)
if (dflt !== undefined) inputs[key] = dflt
}
}
const i2vId = String(n++)
workflow[i2vId] = { class_type: i2vNode, inputs, _meta: { title: 'I2V conditioning' } }
// Outputs by declared type: 1st CONDITIONING → positive, 2nd → negative
// (Hunyuan emits only one — its negative stays on the text encoder),
// LATENT → sampler latent. A latent-only node (Cosmos) leaves both
// conditionings untouched.
const outs: string[] = (meta.output ?? []) as string[]
const latSlot = outs.indexOf('LATENT')
latentRef = [i2vId, latSlot >= 0 ? latSlot : 0]
const condSlots = outs.map((t, i) => (t === 'CONDITIONING' ? i : -1)).filter((i) => i >= 0)
if (condSlots.length >= 1) positiveRef = [i2vId, condSlots[0]]
if (condSlots.length >= 2) negativeRef = [i2vId, condSlots[1]]
delete workflow[latentId]
}
// K9 (GH #136), corrected Runde 3 after review: the issue documents TWO
// Krea 2 author recipes that disagree on this exact node. LUSTIFY! v10
// Krea2 carries ModelSamplingAuraFlow at shift 4; FinePorn v4 NVFP4, the
// reporter's only run he actually PROVED working end to end, used NO such
// node and ComfyUI's own default sampling. classifyModel cannot tell a
// LUSTIFY-style checkpoint from a FinePorn-style one (both classify as
// 'krea2'), so forcing shift 4 on every one of them - what this branch
// used to do - applied an unevidenced sigma-schedule change to the one
// variant the issue actually proves works without it. Deliberately absent:
// no ModelSamplingAuraFlow node, ComfyUI's built-in default applies,
// matching the proven recipe. If a future signal can tell the two variants
// apart (filename convention, a CivitAI metadata field, ...), gate this
// node on that signal rather than reintroducing it unconditionally.
// Sampling patches of the header-sniffed families, straight from their
// official templates: AuraFlow shift 1 (Chroma), 6 (Lumina 2), 3.1 / 3
// (Qwen-Image / -Edit); ModelSamplingSD3 shift 3 (HiDream fast/full) or 6
// (dev). Qwen-Image-Edit also runs CFGNorm at strength 1.
// B45: FLUX.2 reads references as ReferenceLatent on the conditioning,
// each image scaled to about a megapixel and encoded, chained one after
// the other on both sides (image_flux2, the Klein edit templates).
if (strategy === 'unet_flux2' && createRefs.length > 0) {
for (const image of createRefs) {
const loadId = String(n++)
const scaleId = String(n++)
const encId = String(n++)
workflow[loadId] = { class_type: 'LoadImage', inputs: { image } }
workflow[scaleId] = { class_type: 'ImageScaleToTotalPixels', inputs: { image: [loadId, 0], upscale_method: 'lanczos', megapixels: 1, resolution_steps: 1 } }
workflow[encId] = { class_type: 'VAEEncode', inputs: { pixels: [scaleId, 0], vae: [vaeSourceId, vaeOutputSlot] } }
const posRefId = String(n++)
const negRefId = String(n++)
workflow[posRefId] = { class_type: 'ReferenceLatent', inputs: { conditioning: positiveRef, latent: [encId, 0] } }
workflow[negRefId] = { class_type: 'ReferenceLatent', inputs: { conditioning: negativeRef, latent: [encId, 0] } }
positiveRef = [posRefId, 0]
negativeRef = [negRefId, 0]
}
}
// B45: the Krea 2 style reference LoRA and the template's flux sampling
// patch (max shift 1.15, base shift 0.5 at the canvas size), after the
// user's own LoRA stack.
if (krea2StyleRef && krea2StyleLora) {
const loraId = String(n++)
const shiftId = String(n++)
workflow[loraId] = { class_type: 'LoraLoaderModelOnly', inputs: { model: [samplerModelId, 0], lora_name: krea2StyleLora, strength_model: 1 }, _meta: { title: 'Krea 2 style reference' } }
workflow[shiftId] = { class_type: 'ModelSamplingFlux', inputs: { model: [loraId, 0], max_shift: 1.15, base_shift: 0.5, width: params.width, height: params.height } }
samplerModelId = shiftId
}
const auraShift = strategy === 'unet_chroma' ? 1
: strategy === 'unet_lumina2' ? 6
: strategy === 'unet_qwenimage1' ? (isQwenImageEditModel(params.model) ? 3 : 3.1)
: null
if (auraShift !== null && allNodes['ModelSamplingAuraFlow']) {
const id = String(n++)
workflow[id] = { class_type: 'ModelSamplingAuraFlow', inputs: { model: [samplerModelId, 0], shift: auraShift } }
samplerModelId = id
}
if (strategy === 'unet_hidream' && allNodes['ModelSamplingSD3']) {
const id = String(n++)
workflow[id] = { class_type: 'ModelSamplingSD3', inputs: { model: [samplerModelId, 0], shift: /dev/i.test(params.model) ? 6 : 3 } }
samplerModelId = id
}
if (isQwen1Edit && allNodes['CFGNorm']) {
const id = String(n++)
workflow[id] = { class_type: 'CFGNorm', inputs: { model: [samplerModelId, 0], strength: 1 } }
samplerModelId = id
}
// Qwen-Image 2.1, full model and Turbo: both official templates put
// QwenImage21Cache ("auto", "default") between the model and the sampler.
// It only sets where the key/value cache of the prompt prefix lives
// (comfy_extras/nodes_qwen.py), so it goes after the LoRA chain: UNET →
// LoRAs → cache → sampler. A ComfyUI without the node runs without it.
if (strategy === 'unet_qwenimage' && allNodes['QwenImage21Cache']) {
const id = String(n++)
workflow[id] = { class_type: 'QwenImage21Cache', inputs: { model: [samplerModelId, 0], device: 'auto', dtype: 'default' } }
samplerModelId = id
}
// Qwen-Image 2.1 Turbo (lib/render/qwen21-turbo): its own eight step
// schedule through SamplerCustomAdvanced, as the official Turbo templates
// run it, for Generate and Edit alike. Steps, sampler and scheduler of the
// sliders do not reach it. CFG does: the Turbo edit template offers cfg as
// a setting of its own (1, "raise it only if you use a negative prompt"),
// and Create presets 1 for a Turbo file and says so when it is higher.
// Without one of the custom sampler nodes the run falls back to a KSampler
// at eight steps, euler, simple.
const qwenTurbo = strategy === 'unet_qwenimage' && isQwenImage21Turbo(params.model)
const qwenTurboChain = qwenTurbo && QWEN21_TURBO_NODES.every((c) => !!allNodes[c])
if (qwenTurbo) {
log.info(`[dynamic-workflow] Qwen-Image 2.1 Turbo: ${qwenTurboChain ? 'SamplerCustomAdvanced on the template sigmas' : 'KSampler fallback, 8 steps'}`)
}
// ─── Phase 4: Sampling ───
// Wan 2.2 A14B (GH #193): the high noise half lays out the clip, the low
// noise half finishes it, the split ComfyUI's own template runs (two
// KSamplerAdvanced, the first returns its leftover noise). Only when the
// picked file is the high half and its partner sits in the same loader
// list; otherwise the one file runs alone as before. LoRAs stay on the
// picked half.
const lowNoisePartner = isVideo && type === 'wan' && !fromCheckpoint && !!allNodes['KSamplerAdvanced']
? wan22LowNoisePartner(params.model, listedUnets)
: null
let highNoiseStage: { id: string; lowId: string; split: number } | null = null
let lowModelRef: [string, number] | null = null
if (lowNoisePartner) {
const lowLoaderId = String(n++)
addUnetLoader(workflow, lowLoaderId, lowNoisePartner, allNodes)
lowModelRef = [lowLoaderId, 0]
}
// Wan (B18, 3.0.9): the sampling shift of the official templates, which the
// main path never set, and the lightx2v speed LoRAs for a fast run (4 steps
// at cfg 1, lib/wan-speed). The LoRAs go on each half its own: the high
// noise LoRA on the high noise model, the low noise one on the low. A fast
// run without its LoRA would come out as mush, so it stops with the file
// names instead.
if (isVideo && type === 'wan' && strategy === 'unet_video' && !fromCheckpoint) {
const kind = wanSpeedKind(params.model)
const fast = !!kind && isFastSampling(params.steps, params.cfgScale)
if (fast && kind) {
const listedLoras = [
...nodeComboOptions(allNodes, 'LoraLoaderModelOnly', 'lora_name'),
...nodeComboOptions(allNodes, 'LoraLoader', 'lora_name'),
]
const halves: Array<'high' | 'low' | 'single'> = kind.startsWith('a14b') ? ['high', 'low'] : ['single']
const picks = halves.map((h) => findWanSpeedLora(kind, h, listedLoras))
if (picks.some((p) => !p) || (kind.startsWith('a14b') && !lowModelRef)) {
const need = wanSpeedLoraNames(kind)
throw new WorkflowUnavailableError(
kind.startsWith('a14b') && !lowModelRef && picks.every(Boolean)
? `Fast mode runs both halves of ${params.model}: the matching low noise file is not installed. Install the whole Wan 2.2 A14B bundle, or switch Speed to Quality.`
: `Fast mode (4 steps) needs the lightx2v speed LoRA${need.length > 1 ? 's' : ''} ${need.join(' and ')} in ComfyUI/models/loras. Download "Wan speed LoRAs" in the Model Manager, or switch Speed to Quality.`,
strategy,
)
}
const loraNode = allNodes['LoraLoaderModelOnly'] ? 'LoraLoaderModelOnly' : null
const patch = (model: [string, number], lora: string): [string, number] => {
const id = String(n++)
workflow[id] = loraNode
? { class_type: loraNode, inputs: { lora_name: lora, strength_model: 1.0, model }, _meta: { title: 'Speed LoRA' } }
: { class_type: 'LoraLoader', inputs: { lora_name: lora, strength_model: 1.0, strength_clip: 0, model, clip: [clipSourceId, clipOutputSlot] }, _meta: { title: 'Speed LoRA' } }
return [id, 0]
}
samplerModelId = patch([samplerModelId, 0], picks[0]!)[0]
if (lowModelRef && picks[1]) lowModelRef = patch(lowModelRef, picks[1])
}
if (allNodes['ModelSamplingSD3']) {
const shift = fast ? WAN_FAST.shift : (wanSamplingFor(params.model, 'quality')?.shift ?? 8)
const shiftOf = (model: [string, number]): [string, number] => {
const id = String(n++)
workflow[id] = { class_type: 'ModelSamplingSD3', inputs: { model, shift } }
return [id, 0]
}
samplerModelId = shiftOf([samplerModelId, 0])[0]
if (lowModelRef) lowModelRef = shiftOf(lowModelRef)
}
}
// One pass past the native length (B18): sliding context windows on the
// model(s), when asked for and the core has the node.
if (isVideo && videoParams.contextWindows && !continueFrom) {
const win = addContextWindows(workflow, n, [samplerModelId, 0], type, videoParams.frames, allNodes)
n = win.n
samplerModelId = win.model[0]
if (lowModelRef) {
const low = addContextWindows(workflow, n, lowModelRef, type, videoParams.frames, allNodes)
n = low.n
lowModelRef = low.model
}
}
if (lowNoisePartner && lowModelRef) {
highNoiseStage = { lowId: lowModelRef[0], id: String(n++), split: Math.max(1, Math.floor(params.steps / 2)) }
const { id, split } = highNoiseStage
workflow[id] = {
class_type: 'KSamplerAdvanced',
inputs: {
model: [samplerModelId, 0], add_noise: 'enable', noise_seed: seed,
steps: params.steps, cfg: params.cfgScale, sampler_name: params.sampler, scheduler: params.scheduler,
positive: positiveRef, negative: negativeRef, latent_image: latentRef,
start_at_step: 0, end_at_step: split, return_with_leftover_noise: 'enable',
},
_meta: { title: 'Wan 2.2 high noise' },
}
log.info(`[dynamic-workflow] Wan 2.2 A14B pair: ${params.model} → ${lowNoisePartner}, split at step ${split}`)
}
// B46 / D8: the Edit strength at CFG 1 is the sampler's CFG, with the
// identity as its negative (see qwenEditStrength above).
const samplerNegative: [string, number] = qwenStrengthCfg1 && qwenIdentityRef ? qwenIdentityRef : negativeRef
const samplerCfg = qwenStrengthCfg1 && qwenIdentityRef ? qwenEditStrength : params.cfgScale
const part = (node: { class_type: string; inputs: ComfyNodeInputs; _meta?: { title: string } }): [string, number] => {
const id = String(n++)
workflow[id] = node
return [id, 0]
}
// ...and at a higher CFG the nested DualCFGGuider.
const dualGuider = (): [string, number] => part({
class_type: 'DualCFGGuider',
inputs: {
model: [samplerModelId, 0], cond1: positiveRef, cond2: qwenIdentityRef!, negative: negativeRef,
cfg_conds: qwenEditStrength, cfg_cond2_negative: params.cfgScale, style: 'nested',
},
_meta: { title: `Edit strength ${qwenEditStrength.toFixed(2)}` },
})
const useDual = qwenStrengthDual && !!qwenIdentityRef
// The four inputs of the Turbo chain besides the latent, one node each.
let qwenTurboCustom: ComfyNodeInputs | null = null
if (qwenTurboChain) {
qwenTurboCustom = {
noise: part({ class_type: 'RandomNoise', inputs: { noise_seed: seed } }),
guider: useDual ? dualGuider() : part({
class_type: 'CFGGuider',
inputs: { model: [samplerModelId, 0], positive: positiveRef, negative: samplerNegative, cfg: samplerCfg },
}),
sampler: part({ class_type: 'KSamplerSelect', inputs: { sampler_name: QWEN21_TURBO_SAMPLING.sampler } }),
sigmas: part({ class_type: 'ManualSigmas', inputs: { sigmas: QWEN21_TURBO_SIGMAS } }),
}
} else if (useDual) {
// A guider needs the custom sampler; its steps are the KSampler's.
qwenTurboCustom = {
noise: part({ class_type: 'RandomNoise', inputs: { noise_seed: seed } }),
guider: dualGuider(),
sampler: part({ class_type: 'KSamplerSelect', inputs: { sampler_name: qwenTurbo ? QWEN21_TURBO_SAMPLING.sampler : params.sampler } }),
sigmas: part({
class_type: 'BasicScheduler',
inputs: {
model: [samplerModelId, 0], scheduler: qwenTurbo ? QWEN21_TURBO_SAMPLING.scheduler : params.scheduler,
steps: qwenTurbo ? QWEN21_TURBO_SAMPLING.steps : params.steps, denoise: 1.0,
},
}),
}
}
const samplerId = String(n++)
workflow[samplerId] = highNoiseStage ? {
class_type: 'KSamplerAdvanced',
inputs: {
model: [highNoiseStage.lowId, 0], add_noise: 'disable', noise_seed: seed,
steps: params.steps, cfg: params.cfgScale, sampler_name: params.sampler, scheduler: params.scheduler,
positive: positiveRef, negative: negativeRef, latent_image: [highNoiseStage.id, 0],
start_at_step: highNoiseStage.split, end_at_step: 10000, return_with_leftover_noise: 'disable',
},
_meta: { title: 'Wan 2.2 low noise' },
} : qwenTurboCustom ? {
class_type: 'SamplerCustomAdvanced',
inputs: {
...qwenTurboCustom,
latent_image: latentRef,
},
_meta: { title: qwenTurboChain ? 'Qwen-Image 2.1 Turbo' : 'Qwen edit' },
} : {
class_type: 'KSampler',
inputs: {
model: [samplerModelId, 0],
positive: positiveRef,
negative: samplerNegative,
latent_image: latentRef,
seed,
steps: qwenTurbo ? QWEN21_TURBO_SAMPLING.steps : params.steps,
cfg: samplerCfg,
sampler_name: qwenTurbo ? QWEN21_TURBO_SAMPLING.sampler : params.sampler,
scheduler: qwenTurbo ? QWEN21_TURBO_SAMPLING.scheduler : params.scheduler,
// Qwen edits: 1.0 like their templates, whatever the Edit strength.
denoise: isInpaint ? (params.denoise ?? 0.85) : isI2I ? (params.denoise ?? 0.7) : 1.0,
},
}
// ─── Phase 5: Decode ───
const decodeId = String(n++)
workflow[decodeId] = isVideo
? videoDecodeNode([samplerId, 0], [vaeSourceId, vaeOutputSlot], nodes.decoders.includes('VAEDecodeTiled'))
: {
class_type: 'VAEDecode',
inputs: {
samples: [samplerId, 0],
vae: [vaeSourceId, vaeOutputSlot],
},
}
// ─── Phase 6: Output ───
if (isVideo) {
// A continued section goes behind the clip so far, without the frames it
// repeats, and the whole clip is saved (B18).
let frames: [string, number] = [decodeId, 0]
if (continued && continueFrom) {
const joined = addStitch(workflow, n, continued.frames, frames, continueFrom.overlap, allNodes)
n = joined.n
frames = joined.images
}
// Video output: core SaveVideo (mp4) > VHS > SaveAnimatedWEBP > SaveImage (A19)
addVideoSave(workflow, n, frames, videoParams.fps, promptFilenamePrefix(params.prompt, true), (c) => nodes.videoSavers.includes(c))
} else {
workflow[String(n)] = {
class_type: 'SaveImage',
inputs: {
images: [decodeId, 0],
filename_prefix: promptFilenamePrefix(params.prompt, false),
},
}
}
log.info(`[dynamic-workflow] Built ${Object.keys(workflow).length} nodes`, {
nodes: Object.entries(workflow).map(([id, node]) => `${id}:${node.class_type}`).join(' → ')
})
return workflow
}
// ─── Wrapper Workflow Builders ───
// Background removal (ComfyUI-RMBG). Self-contained LoadImage → RMBG → SaveImage
// graph. Every RMBG widget is defaulted from the node's LIVE object_info schema
// (`rmbgMeta`) so the graph stays valid across RMBG versions instead of pinning
// input names/enums we'd have to guess. The `background` widget is nudged toward
// a transparent/alpha option so the result is a real RGBA cutout, not a matte.
function buildRemoveBgWorkflow(params: GenerateParams, rmbgMeta: NodeMetadata): ComfyApiGraph {
const workflow: ComfyApiGraph = {}
workflow['1'] = { class_type: 'LoadImage', inputs: { image: params.inputImage } }
// Fill BOTH required AND optional widgets from the live schema. ComfyUI-RMBG
// declares process_res / sensitivity / mask_blur / mask_offset as "optional"
// in INPUT_TYPES but its Python reads them as plain kwargs, so omitting them
// throws "Error in batch processing: 'process_res' (RMBG)". Defaulting every
// widget from object_info keeps the graph valid across RMBG versions.
const required = rmbgMeta.input?.required ?? {}
const optional = rmbgMeta.input?.optional ?? {}
const rmbgInputs: ComfyNodeInputs = { image: ['1', 0] }
for (const [name, spec] of Object.entries({ ...required, ...optional })) {
if (name === 'image') continue
const d = rmbgWidgetDefault(name, spec)
if (d.set) rmbgInputs[name] = d.value
}
workflow['2'] = { class_type: 'RMBG', inputs: rmbgInputs }
// RMBG returns (IMAGE, MASK, …); slot 0 is the cut-out image. SaveImage writes
// the transparent PNG, picked up by extractComfyOutputFiles like any output.
workflow['3'] = {
class_type: 'SaveImage',
inputs: { images: ['2', 0], filename_prefix: promptFilenamePrefix(params.prompt, false) },
}
return workflow
}
// ─── Enhance Image on local ComfyUI (3.0.7) ───
//
// Core nodes only: LoadImage → UpscaleModelLoader + ImageUpscaleWithModel →
// (a resize when the model's own scale is not the factor asked for) →
// SaveImage. ImageUpscaleWithModel tiles on its own and halves the tile when
// the card runs out of memory, so no tile settings are needed here.
export interface UpscaleParams {
/** The source, as ComfyUI's /upload/image named it. */
image: string
/** A file ComfyUI lists for UpscaleModelLoader (models/upscale_models). */
model: string
factor: UpscaleFactor
/** The source's size, for the exact resize when the model's scale is unknown. */
sourceWidth: number
sourceHeight: number
}
const UPSCALE_NODES = ['LoadImage', 'UpscaleModelLoader', 'ImageUpscaleWithModel', 'SaveImage']
/** The resize method: area to go down (a 4x model asked for 2x), lanczos to go
* up. Taken from the node's live list when it can be read, so a ComfyUI that
* renamed one never sees a value it would reject. */
function resizeMethod(allNodes: NodePresence, node: 'ImageScaleBy' | 'ImageScale', down: boolean): string {
const wanted = down ? 'area' : 'lanczos'
const listed = nodeComboOptions(allNodes, node, 'upscale_method')
if (listed.length === 0 || listed.includes(wanted)) return wanted
return listed.includes('bicubic') ? 'bicubic' : listed[0]
}
export function buildUpscaleWorkflow(params: UpscaleParams, allNodes: NodePresence): ComfyApiGraph {
requireNodes(allNodes, UPSCALE_NODES, 'Enhance Image')
const listed = nodeComboOptions(allNodes, 'UpscaleModelLoader', 'model_name')
if (listed.length > 0 && !listed.includes(params.model)) {
throw new WorkflowUnavailableError(
`${params.model} is no longer in ComfyUI's upscale model list. It may have been moved or deleted. Restart ComfyUI after adding files, then try again.`,
'unavailable',
)
}
const workflow: ComfyApiGraph = {}
workflow['1'] = { class_type: 'LoadImage', inputs: { image: params.image } }
workflow['2'] = { class_type: 'UpscaleModelLoader', inputs: { model_name: params.model } }
workflow['3'] = { class_type: 'ImageUpscaleWithModel', inputs: { upscale_model: ['2', 0], image: ['1', 0] } }
let out: [string, number] = ['3', 0]
const native = nativeUpscaleScale(params.model)
if (native !== null && native !== params.factor) {
// A 4x model asked for 2x: the model's result, scaled by 0.5.
requireNodes(allNodes, ['ImageScaleBy'], 'Enhance Image')
const scale = params.factor / native
workflow['4'] = {
class_type: 'ImageScaleBy',
inputs: { image: out, upscale_method: resizeMethod(allNodes, 'ImageScaleBy', scale < 1), scale_by: scale },
}
out = ['4', 0]
} else if (native === null) {
// The name does not say the model's scale: resize to the exact target.
requireNodes(allNodes, ['ImageScale'], 'Enhance Image')
const t = upscaleTarget(params.sourceWidth, params.sourceHeight, params.factor)
workflow['4'] = {
class_type: 'ImageScale',
inputs: { image: out, upscale_method: resizeMethod(allNodes, 'ImageScale', false), width: t.width, height: t.height, crop: 'disabled' },
}
out = ['4', 0]
}
workflow['5'] = {
class_type: 'SaveImage',
inputs: { images: out, filename_prefix: `${promptFilenamePrefix('', false)}_enhanced` },
}
return workflow
}
/** The graph against the running ComfyUI's node list. */
export async function buildLocalUpscaleWorkflow(params: UpscaleParams): Promise<ComfyApiGraph> {
return buildUpscaleWorkflow(params, await getAllNodeInfo())
}
// ─── 3D from one picture (TRELLIS.2, Windows and Linux, 3.1.0) ───
//
// The graph is the TRELLIS.2 branch of ComfyUI's own template
// `3d_pixal3d_trellis2_image_to_model.json`, read as data out of the PyPI
// wheel comfyui_workflow_templates_json 0.1.120 (sha256
// f4f8e94d2c8a94ea894a9d9a18235ea6306268112f9dc267611a04b20d2740be). That is
// the version ComfyUI v0.42.4 pins through comfyui-workflow-templates==0.11.94
// in its requirements.txt. Class names, input names, types and ranges were
// checked against the node code at the tag v0.42.4: comfy_extras/
// nodes_trellis2.py, nodes_bg_removal.py, nodes_images.py (ImageCropToMask),
// nodes_custom_sampler.py (CFGOverride), nodes_model_advanced.py (RescaleCFG,
// ModelSamplingSD3), nodes_mesh_postprocess.py and nodes_save_3d.py.
//
// The node ids are the template's, so a diff against it stays readable. What
// differs from the template, on purpose:
// * The Pixal3D branch is gone (its model, MoGe, the FOV node and the three
// ComfySwitchNode that choose between the two). The template's switch
// "Switch to Trellis2" set to true is exactly this graph.
// * The preview nodes are gone (PreviewImage, MaskPreview, Preview3DAdvanced,
// VoxelToMesh, PaintMesh, RenderUVAtlas, GetMeshInfo, the MeshToFile3D in
// front of each preview). In v0.42.4 PreviewImage and MaskPreview pass
// their input through, so the links run straight from the node before.
// * SaveGLB (mesh in, writes output/3d/*.glb, reports under the key "3d")
// stands in for MeshToFile3D plus Save3DAdvanced, which needs the
// viewport state of the canvas.
// * cutout false skips RemoveBackground and feeds the picture's own mask
// (LoadImage output 1) into ImageCropToMask, the template's "Switch:
// Remove background" set to false. An opaque picture then has an empty
// mask, and ImageCropToMask takes the whole picture (_crop_image_with_mask).
// * pad_factor 1.0 instead of the template's 1.1: the Trellis2Conditioning
// input says "pad_factor=1.0 for TRELLIS.2"; the template shares the crop
// with Pixal3D. Unconfirmed until a run on the box.
// * `detail` sets the cascade resolution, the remesh grid, the face count
// and the texture sizes. 'fine' is the template's values.
export type ThreeDDetail = 'draft' | 'standard' | 'fine'
export interface ThreeDDetailSettings {
/** Trellis2UpsampleStage target_resolution (1024 to 2048, step 128). */
shapeResolution: number
/** RemeshMesh resolution (32 to 2048). */
remeshResolution: number
/** DecimateMesh target_face_count. */
faces: number
/** UnwrapMesh resolution and BakeTextureFromVoxel texture_size (step 256). */
texture: number
/** BakeNormalMapFromMesh resolution (step 64). */
normalMap: number
/** BakeAmbientOcclusion resolution (step 64) and its ray count (step 4). */
occlusion: number
occlusionSamples: number
}
export const THREE_D_DETAIL: Record<ThreeDDetail, ThreeDDetailSettings> = {
draft: { shapeResolution: 1024, remeshResolution: 384, faces: 100_000, texture: 1024, normalMap: 1024, occlusion: 512, occlusionSamples: 32 },
standard: { shapeResolution: 1024, remeshResolution: 512, faces: 300_000, texture: 2048, normalMap: 2048, occlusion: 1024, occlusionSamples: 64 },
fine: { shapeResolution: 1536, remeshResolution: 768, faces: 700_000, texture: 4096, normalMap: 2048, occlusion: 1024, occlusionSamples: 64 },
}
export interface ThreeDParams {
/** The picture, as ComfyUI's /upload/image named it. */
image: string
detail: ThreeDDetail
/** Cut the object out of its background first (BiRefNet). */
cutout: boolean
seed: number
/** Other file names than the catalogue's, for a ComfyUI that lists them so. */
files?: Partial<Record<keyof typeof TRELLIS2_FILES, string>>
}
export const THREE_D_NEEDS_UPDATE = 'Local 3D needs ComfyUI 0.42.4 or newer. Update ComfyUI in Settings.'
/** The core nodes the graph is built from. The TRELLIS.2 ones are the release
* marker: without them the install is older than the lane. */
export const THREE_D_TRELLIS_NODES = [
'EmptyTrellis2LatentStructure', 'Trellis2Conditioning', 'Trellis2ShapeStage', 'Trellis2UpsampleStage',
'Trellis2TextureStage', 'VaeDecodeStructureTrellis2', 'VaeDecodeShapeTrellis', 'VaeDecodeTextureTrellis',
]
export const THREE_D_NODES = [
...THREE_D_TRELLIS_NODES,
'LoadImage', 'ImageCropToMask', 'CLIPVisionLoader', 'UNETLoader', 'VAELoader',
'CFGOverride', 'RescaleCFG', 'ModelSamplingSD3', 'KSampler',
'RemeshMesh', 'DecimateMesh', 'MeshSmoothNormals', 'UnwrapMesh',
'BakeTextureFromVoxel', 'BakeNormalMapFromMesh', 'BakeAmbientOcclusion', 'ApplyTextureToMesh', 'SaveGLB',
]
export const THREE_D_CUTOUT_NODES = ['LoadBackgroundRemovalModel', 'RemoveBackground']
/** The id of the save node, whose history entry carries the model. */
export const THREE_D_SAVE_NODE = '900'
/** The choices of a DynamicCombo input in one node's /object_info entry,
* which ComfyUI serves as ["COMFY_DYNAMICCOMBO_V3", { options: [{ key, inputs }] }]
* (comfy_api/latest/_io.py, DynamicCombo.Input.as_dict). A plain combo
* ([[...choices]]) reads too. Null when the entry says nothing readable,
* so a caller can tell "unknown" from "not offered". */
export function dynamicComboKeys(nodeInfo: unknown, field: string): string[] | null {
if (!nodeInfo || typeof nodeInfo !== 'object') return null
const input = (nodeInfo as { input?: { required?: Record<string, unknown>; optional?: Record<string, unknown> } }).input
const spec = input?.required?.[field] ?? input?.optional?.[field]
if (!Array.isArray(spec)) return null
if (Array.isArray(spec[0])) return spec[0].filter((k): k is string => typeof k === 'string')
const options = (spec[1] as { options?: unknown } | undefined)?.options
if (!Array.isArray(options)) return null
return options.map((o) => (o as { key?: unknown })?.key).filter((k): k is string => typeof k === 'string')
}
/** RemeshMesh's sign_mode choice. 'solid' came with ComfyUI 0.42.0; 0.36 to
* 0.41 have the TRELLIS.2 nodes and RemeshMesh but offer only udf and sdf.
* Sent there, 'solid' matches no option, ComfyUI drops the input without a
* word and the node fails with "execute() missing 1 required positional
* argument: 'sign_mode'" (3.1.0, reported 17.11.2026). */
export const THREE_D_SIGN_MODE = 'solid'
function sampler(
model: [string, number], cond: string, latent: [string, number], seed: number,
steps: number, cfg: number, scheduler: string,
): ComfyNodeInputs {
return {
model, positive: [cond, 0], negative: [cond, 1], latent_image: latent,
seed, steps, cfg, sampler_name: 'euler', scheduler, denoise: 1,
}
}
export function buildThreeDWorkflow(params: ThreeDParams, allNodes: NodePresence): ComfyApiGraph {
requireRelease(allNodes, THREE_D_TRELLIS_NODES, THREE_D_NEEDS_UPDATE, 'unavailable')
requireRelease(allNodes, ['SaveGLB', 'RemeshMesh', 'BakeTextureFromVoxel'], THREE_D_NEEDS_UPDATE, 'unavailable')
requireNodes(allNodes, THREE_D_NODES, 'Local 3D')
// The node is there, but is its remesh choice? Asked of /object_info before
// the run, so an older ComfyUI gets the update offer, not a failed run.
const signModes = dynamicComboKeys(allNodes.RemeshMesh, 'sign_mode')
if (signModes && !signModes.includes(THREE_D_SIGN_MODE)) {
throw new WorkflowUnavailableError(THREE_D_NEEDS_UPDATE, 'unavailable', undefined, { needsComfyUpdate: true })
}
if (params.cutout) requireNodes(allNodes, THREE_D_CUTOUT_NODES, 'Local 3D')
const files = { ...TRELLIS2_FILES, ...params.files }
const d = THREE_D_DETAIL[params.detail] ?? THREE_D_DETAIL.standard
// KSampler takes 0 to 2^64-1; the texture pass gets its own seed as in the
// template (42 for the shape passes, 43 for the texture).
const seed = Math.max(0, Math.floor(params.seed))
const textureSeed = seed + 1 > Number.MAX_SAFE_INTEGER ? 0 : seed + 1
const w: ComfyApiGraph = {}
// The picture, cut out and cropped to 1024 square.
w['122'] = { class_type: 'LoadImage', inputs: { image: params.image } }
let mask: [string, number] = ['122', 1]
if (params.cutout) {
w['193'] = { class_type: 'LoadBackgroundRemovalModel', inputs: { bg_removal_name: files.cutout } }
w['192'] = { class_type: 'RemoveBackground', inputs: { bg_removal_model: ['193', 0], image: ['122', 0] } }
mask = ['192', 0]
}
w['312'] = {
class_type: 'ImageCropToMask',
inputs: { images: ['122', 0], masks: mask, width: 1024, height: 1024, pad_factor: 1.0, grow_mask: 0, background: '#000000' },
}
// Loaders and the two guided model chains of the template.
w['15'] = { class_type: 'CLIPVisionLoader', inputs: { clip_name: files.imageEncoder } }
w['40'] = { class_type: 'UNETLoader', inputs: { unet_name: files.model, weight_dtype: 'default' } }
w['117'] = { class_type: 'VAELoader', inputs: { vae_name: files.shapeVae } }
w['118'] = { class_type: 'VAELoader', inputs: { vae_name: files.textureVae } }
w['199'] = { class_type: 'CFGOverride', inputs: { model: ['40', 0], cfg: 1, start_percent: 0.667, end_percent: 1 } }
w['125'] = { class_type: 'RescaleCFG', inputs: { model: ['199', 0], multiplier: 0.7 } }
w['108'] = { class_type: 'ModelSamplingSD3', inputs: { model: ['125', 0], shift: 5 } }
w['279'] = { class_type: 'CFGOverride', inputs: { model: ['40', 0], cfg: 1, start_percent: 0.769, end_percent: 1 } }
w['126'] = { class_type: 'RescaleCFG', inputs: { model: ['279', 0], multiplier: 0.5 } }
w['299'] = { class_type: 'Trellis2Conditioning', inputs: { clip_vision_model: ['15', 0], image: ['312', 0] } }
// Structure, then shape at 512, then the cascade up to the detail's resolution.
w['87'] = { class_type: 'EmptyTrellis2LatentStructure', inputs: { batch_size: 1 } }
w['3'] = { class_type: 'KSampler', inputs: sampler(['108', 0], '299', ['87', 0], seed, 12, 7.5, 'normal') }
w['119'] = { class_type: 'VaeDecodeStructureTrellis2', inputs: { samples: ['3', 0], vae: ['117', 0], resolution: '32' } }
w['91'] = { class_type: 'Trellis2ShapeStage', inputs: { positive: ['299', 0], negative: ['299', 1], voxel: ['119', 0] } }
w['18'] = { class_type: 'KSampler', inputs: sampler(['126', 0], '91', ['91', 2], seed, 20, 7.5, 'normal') }
w['94'] = {
class_type: 'Trellis2UpsampleStage',
inputs: { positive: ['91', 0], negative: ['91', 1], shape_latent: ['18', 0], vae: ['117', 0], target_resolution: d.shapeResolution },
}
w['23'] = { class_type: 'KSampler', inputs: sampler(['126', 0], '94', ['94', 2], seed, 12, 7.5, 'simple') }
w['92'] = { class_type: 'VaeDecodeShapeTrellis', inputs: { samples: ['23', 0], vae: ['117', 0] } }
// The surface, as voxel colours.
w['98'] = { class_type: 'Trellis2TextureStage', inputs: { positive: ['94', 0], negative: ['94', 1], shape_latent: ['23', 0] } }
w['12'] = { class_type: 'KSampler', inputs: sampler(['40', 0], '98', ['98', 2], textureSeed, 12, 1, 'normal') }
w['93'] = { class_type: 'VaeDecodeTextureTrellis', inputs: { samples: ['12', 0], vae: ['118', 0], shape_subdivides: ['92', 1] } }
// A clean mesh, unwrapped, with the colours baked into textures.
w['241'] = {
class_type: 'RemeshMesh',
inputs: {
mesh: ['92', 0], resolution: d.remeshResolution,
// A DynamicCombo: the choice under its own name, its options as
// "sign_mode.<name>" (comfy_api/latest/_io.py, finalize_prefix).
sign_mode: THREE_D_SIGN_MODE, 'sign_mode.fill': 20, 'sign_mode.qef': false,
band: 1, project_back: 0, fix_poles: false, smooth_iters: 20,
drop_small_components: 0.01, precluster_max_verts: 20_000_000,
},
}
w['186'] = { class_type: 'DecimateMesh', inputs: { mesh: ['241', 0], target_face_count: d.faces, placement_mode: 'midpoint' } }
w['238'] = { class_type: 'MeshSmoothNormals', inputs: { mesh: ['186', 0], crease_angle: 180 } }
w['196'] = { class_type: 'UnwrapMesh', inputs: { mesh: ['238', 0], segmenter: 'pec', resolution: d.texture, padding: 1, weld_distance: 0.0002 } }
w['147'] = {
class_type: 'BakeTextureFromVoxel',
inputs: { mesh: ['196', 0], voxel_colors: ['93', 0], texture_size: d.texture, reference_mesh: ['92', 0] },
}
w['224'] = {
class_type: 'BakeNormalMapFromMesh',
inputs: { low_poly: ['196', 0], high_poly: ['241', 0], resolution: d.normalMap, cage_distance: 0.05, ignore_backfaces: true },
}
w['233'] = {
class_type: 'BakeAmbientOcclusion',
inputs: { low_poly: ['196', 0], high_poly: ['241', 0], resolution: d.occlusion, samples: d.occlusionSamples, max_distance: 0.71, strength: 1, bias: 0.01 },
}
w['210'] = {
class_type: 'ApplyTextureToMesh',
inputs: { mesh: ['196', 0], base_color: ['147', 0], metallic: ['147', 1], roughness: ['147', 2], occlusion: ['233', 0], normal_map: ['224', 0] },
}
w['260'] = { class_type: 'MeshSmoothNormals', inputs: { mesh: ['210', 0], crease_angle: 180 } }
w[THREE_D_SAVE_NODE] = {
class_type: 'SaveGLB',
inputs: { mesh: ['260', 0], filename_prefix: `3d/${promptFilenamePrefix('', false)}_3d` },
}
return w
}
/** The graph against the running ComfyUI's node list. */
export async function buildLocalThreeDWorkflow(params: ThreeDParams): Promise<ComfyApiGraph> {
return buildThreeDWorkflow(params, await getAllNodeInfo())
}
// Resolve a default value for one RMBG widget input from its object_info spec.
// Combo → prefer a transparent option for the background widget, else the
// declared default / first entry. Primitives → their declared default. A
// non-widget connection input (some other IMAGE/MASK) can't be auto-wired, so
// skip it — ComfyUI surfaces a clear error rather than us guessing wrong.
function rmbgWidgetDefault(
name: string,
spec: ComfyInputValue | undefined,
): { set: boolean; value?: ComfyInputValue } {
const { typeName, config: cfg } = specParts(spec)
// A bare (non-array) spec is its own type marker — RMBG has shipped both.
const t = typeName ?? (Array.isArray(spec) ? undefined : spec)
// Both dropdown schemas, through the shared reader: a node that declares its
// combos the newer way (["COMBO", {options: [...]}]) used to fall through to
// "not a widget" here, and RMBG then rejected the graph for the missing
// widget it had just declared.
const options = readComboOptions(spec)
if (options && options.length > 0) {
if (/back\s*ground|(^|_)bg($|_)/i.test(name)) {
const alpha = options.find((o) => /alpha|transparent/i.test(o))
if (alpha) return { set: true, value: alpha }
}
return { set: true, value: cfg?.default ?? options[0] }
}
if (t === 'BOOLEAN') return { set: true, value: cfg?.default ?? false }
if (t === 'INT' || t === 'FLOAT') return { set: true, value: cfg?.default ?? 0 }
if (t === 'STRING' || t === 'COLORCODE') return { set: true, value: cfg?.default ?? '' }
return { set: false }
}
function addVideoOutput(workflow: ComfyApiGraph, n: number, decodeId: string, fps: number, nodes: CategorizedNodes, prompt?: string): number {
return addVideoSave(workflow, n, [decodeId, 0], fps, promptFilenamePrefix(prompt, true), (c) => nodes.videoSavers.includes(c))
}
// buildCogVideoWorkflow deleted 2026-07-24 (D#88). It emitted CogVideoXCLIPLoader,
// CogVideoXTextEncode, CogVideoXEmptyLatents, CogVideoXSampler and
// CogVideoXVAEDecode, none of which are registered by kijai's wrapper, so it
// only ever produced ComfyUI 400s. Kept out of the tree on purpose: leaving a
// known-wrong graph around invites someone to just reopen the gate. Git history
// has it if the lane is ever rebuilt, which needs a real generate to land.
function buildSVDWorkflow(params: VideoParams, seed: number, nodes: CategorizedNodes): ComfyApiGraph {
const workflow: ComfyApiGraph = {}
let n = 1
const loaderId = String(n++)
const imageId = String(n++)
const scaleId = String(n++)
const condId = String(n++)
const guidanceId = String(n++)
const samplerId = String(n++)
const decodeId = String(n++)
workflow[loaderId] = { class_type: 'ImageOnlyCheckpointLoader', inputs: { ckpt_name: params.model } }
workflow[imageId] = { class_type: 'LoadImage', inputs: { image: params.inputImage || 'input_image.png' } }
// Aspect-fill the source into the SVD generation resolution (2026-06-11:
// a portrait/square still fed straight in came back squished and no longer
// matched the input). crop:'center' scales to cover width×height then
// centre-crops — so the conditioning sees the source at the right aspect with
// no distortion, instead of SVD stretching it internally.
workflow[scaleId] = {
class_type: 'ImageScale',
inputs: { image: [imageId, 0], upscale_method: 'lanczos', width: params.width, height: params.height, crop: 'center' },
}
workflow[condId] = {
class_type: 'SVD_img2vid_Conditioning',
inputs: {
clip_vision: [loaderId, 1], init_image: [scaleId, 0], vae: [loaderId, 2],
augmentation_level: 0.0, width: params.width, height: params.height,
video_frames: params.frames,
// Lower motion = stays closer to the source (127 = SVD's high-drift default).
motion_bucket_id: params.motionBucketId ?? 90,
fps: params.fps,
},
}
workflow[guidanceId] = { class_type: 'VideoLinearCFGGuidance', inputs: { model: [loaderId, 0], min_cfg: 1.0 } }
workflow[samplerId] = {
class_type: 'KSampler',
inputs: { model: [guidanceId, 0], positive: [condId, 0], negative: [condId, 1], latent_image: [condId, 2], seed, steps: params.steps, cfg: params.cfgScale, sampler_name: params.sampler, scheduler: params.scheduler, denoise: 1.0 },
}
workflow[decodeId] = videoDecodeNode([samplerId, 0], [loaderId, 2], nodes.decoders.includes('VAEDecodeTiled'))
addVideoOutput(workflow, n, decodeId, params.fps, nodes, params.prompt)
return workflow
}
/**
* Snap a frame count to Wan 2.2's length grid. The Wan 2.2 VAE has a temporal
* stride of 4, so `Wan22ImageToVideoLatent.length` must be 4k+1 (…45, 49, 53…).
* An off-grid length makes ComfyUI error or silently drop the tail frame.
* Exported + pure for the unit tests and the vram-handoff duration math.
*/
export function snapWanLength(frames: number): number {
const f = Number.isFinite(frames) ? Math.round(frames) : 49
const k = Math.max(1, Math.round((f - 1) / 4))
return k * 4 + 1
}
/**
* Wan 2.2 TI2V-5B, one model, both modes. `Wan22ImageToVideoLatent` takes an
* OPTIONAL `start_image`: present is image-to-video (the clip opens on the
* source still), absent is text-to-video. Uses the Wan 2.2 VAE, not the 2.1
* VAE (the 2.2 VAE has 16x spatial / 4x temporal compression, a different
* latent shape) and the shared UMT5-XXL text encoder. `ModelSamplingSD3`
* applies Wan's sampling shift.
*
* I2V faithfulness (2026-06-11): an `ImageScale(crop:center)` aspect-fills
* the source into the generation size, so the first frame matches the still
* instead of being squished, the same fix proven on the SVD path.
*
* K2 (review-create.md nachbessert, Punkt 1): the CLIP/VAE names below used
* to be hardcoded literals, the same failure class as buildS2VWorkflow and
* buildMotionWorkflow (see their own K2 comments) and Node 3 in this builder
* is also the VAELoader, so an unresolved live enum produced the identical
* "Node 3 (VAELoader): Value not in list" here. Wan 2.2 TI2V-5B is the
* default local Animate model, so this is the actual path a customer hits.
* Resolved now via the same findMatchingCLIP/findMatchingVAE live-list
* resolvers Bug C and K2 already use elsewhere, with 'wan22' for the VAE
* (its own compression profile, comfyui.ts:1441) and 'wan' for the CLIP
* (wan22 shares the plain Wan UMT5 encoder, component-registry.ts confirms
* clipType: 'wan' for both wan and wan22).
*/
async function buildWan22Workflow(params: VideoParams, seed: number, nodes: CategorizedNodes, allNodes: NodePresence): Promise<ComfyApiGraph> {
const workflow: ComfyApiGraph = {}
let n = 1
// Wan 2.2 dims snap to 32 (VAE spatial grid); length to 4k+1 (temporal stride 4).
const snap32 = (v: number | undefined, def: number) => Math.max(64, Math.round(((v && v > 0) ? v : def) / 32) * 32)
const width = snap32(params.width, 1024)
const height = snap32(params.height, 576)
const length = snapWanLength(params.frames || 49)
const [wan22Clip, wan22Vae] = await Promise.all([
findMatchingCLIP('wan', params.model),
findMatchingVAE('wan22'),
])
const unetId = String(n++)
const clipId = String(n++)
const vaeId = String(n++)
const posId = String(n++)
const negId = String(n++)
addUnetLoader(workflow, unetId, params.model, allNodes)
workflow[clipId] = { class_type: 'CLIPLoader', inputs: { clip_name: wan22Clip, type: 'wan', device: 'default' } }
workflow[vaeId] = { class_type: 'VAELoader', inputs: { vae_name: wan22Vae } }
workflow[posId] = { class_type: 'CLIPTextEncode', inputs: { text: params.prompt, clip: [clipId, 0] } }
workflow[negId] = { class_type: 'CLIPTextEncode', inputs: { text: params.negativePrompt || '', clip: [clipId, 0] } }
// Optional LoRA chain (D#80): video LoRAs are model-only, so
// patch the UNET with LoraLoaderModelOnly (no clip side) before the sampling
// shift. Guarded on params.lora, a plain Wan 2.2 gen stays byte-identical.
let wanModelSrc = unetId
const wanLoras = normalizeLoraList(params.lora)
if (wanLoras.length > 0) {
const wanStrengths = normalizeLoraStrengths(params.loraStrength, wanLoras.length)
wanLoras.forEach((loraName, i) => {
const loraId = String(n++)
workflow[loraId] = {
class_type: 'LoraLoaderModelOnly',
inputs: { lora_name: loraName, strength_model: wanStrengths[i], model: [wanModelSrc, 0] },
}
wanModelSrc = loraId
})
}
// Wan's recommended sampling shift. ModelSamplingSD3 is a core node (ships since
// SD3), so the sampler reads from it to match the official 5B workflow's motion.
const shiftId = String(n++)
workflow[shiftId] = { class_type: 'ModelSamplingSD3', inputs: { model: [wanModelSrc, 0], shift: 8.0 } }
let samplerModel: [string, number] = [shiftId, 0]
if (params.contextWindows && !params.continueFrom) {
const win = addContextWindows(workflow, n, samplerModel, 'wan22', length, allNodes)
n = win.n
samplerModel = win.model
}
// Unified latent: a start_image is attached ONLY for an I2V request. A
// continued section (B18) attaches the last frames of the clip so far; the
// node masks every latent frame they cover, so the section picks the
// motion up where it stopped.
const latentInputs: ComfyNodeInputs = { vae: [vaeId, 0], width, height, length, batch_size: 1 }
let continued: ContinueSource | null = null
if (params.continueFrom) {
requireContinueNodes(allNodes, 'unet_video')
continued = addContinueSource(workflow, n, params.continueFrom, allNodes)
n = continued.n
const scaleId = String(n++)
workflow[scaleId] = { class_type: 'ImageScale', inputs: { image: continued.tail, upscale_method: 'lanczos', width, height, crop: 'center' } }
latentInputs.start_image = [scaleId, 0]
} else if (params.inputImage) {
const imageId = String(n++)
const scaleId = String(n++)
workflow[imageId] = { class_type: 'LoadImage', inputs: { image: params.inputImage } }
workflow[scaleId] = { class_type: 'ImageScale', inputs: { image: [imageId, 0], upscale_method: 'lanczos', width, height, crop: 'center' } }
latentInputs.start_image = [scaleId, 0]
}
const latentId = String(n++)
workflow[latentId] = { class_type: 'Wan22ImageToVideoLatent', inputs: latentInputs }
const samplerId = String(n++)
workflow[samplerId] = {
class_type: 'KSampler',
inputs: {
model: samplerModel, positive: [posId, 0], negative: [negId, 0], latent_image: [latentId, 0],
seed, steps: params.steps, cfg: params.cfgScale, sampler_name: params.sampler, scheduler: params.scheduler, denoise: 1.0,
},
}
const decodeId = String(n++)
workflow[decodeId] = videoDecodeNode([samplerId, 0], [vaeId, 0], nodes.decoders.includes('VAEDecodeTiled'))
if (continued && params.continueFrom) {
const joined = addStitch(workflow, n, continued.frames, [decodeId, 0], params.continueFrom.overlap, allNodes)
addVideoSave(workflow, joined.n, joined.images, params.fps, promptFilenamePrefix(params.prompt, true), (c) => nodes.videoSavers.includes(c))
return workflow
}
addVideoOutput(workflow, n, decodeId, params.fps, nodes, params.prompt)
return workflow
}
/** MiniMax H3 counts frames in blocks of 17 plus 5 (124 is about five
* seconds at 24 fps). Rounds UP, as the official template does, so a request
* never comes back shorter than asked. */
export function snapMiniMaxH3Length(frames: number): number {
const f = Math.max(5, Number.isFinite(frames) ? Math.round(frames) : 124)
return f + ((5 - (f % 17)) + 17) % 17
}
/**
* MiniMax H3 (Discord, throwaway 2026-09-26: "shows up as an image model").
* One model writes picture and sound together, wired as the official
* Comfy-Org t2v/i2v and r2v templates do: the encode node builds the joint
* latent, BasicGuider and SamplerCustomAdvanced sample it, and VAEDecode and
* VAEDecodeAudio each pull their half back out before CreateVideo muxes them.
*
* Two sets of weights share the family. fl2va takes the source image as the
* first frame; ref2va takes it as a reference the prompt can call
* <Picture 1>.
*/
async function buildMiniMaxH3Workflow(params: VideoParams, seed: number, allNodes: NodePresence): Promise<ComfyApiGraph> {
const fast = isFastH3(params.model)
const isRef2va = !fast && /ref2va/i.test(params.model)
const encodeNode = isRef2va ? 'MiniMaxH3ReferenceToVideo' : 'MiniMaxH3ImageToVideo'
requireNodes(allNodes, [encodeNode, 'BasicGuider', 'SamplerCustomAdvanced', 'VAEDecodeAudio'], 'MiniMax H3')
if (fast) {
// FastH3 runs on FastVideo's sparse attention, which ComfyUI has had since
// 0.35.0 (BlockSparseAttention), and it only distilled text to video.
requireRelease(allNodes, ['BlockSparseAttention', 'MiniMaxH3SigmaShift'], FASTH3_NEEDS_UPDATE, 'minimaxh3')
// Read in comfy_extras/nodes_sparse_attention.py (ComfyUI master, 2026-10-02):
// BlockSparseAttention does NOT use Triton. It calls the compiled sol_attn
// kernels of comfy_kitchen (CUDA sm_80+ on Linux and Windows x64 wheels, or
// HIP). Where they are not available (older GPU, CPU) h3_eligible() returns
// False and the block runs the model's normal dense attention, so the graph
// is valid on every machine and only loses the speed gain. No platform gate.
if (params.inputImage) {
throw new WorkflowUnavailableError('FastH3 makes video from a prompt only. Pick MiniMax H3 to start from an image.', 'minimaxh3')
}
}
const workflow: ComfyApiGraph = {}
let n = 1
const snap32 = (v: number | undefined, def: number) => Math.max(32, Math.round(((v && v > 0) ? v : def) / 32) * 32)
const width = snap32(params.width, 1344)
const height = snap32(params.height, 768)
const length = snapMiniMaxH3Length(params.frames || 124)
const [clipName, vaeName, audioVaeName] = await Promise.all([
findMatchingCLIP('minimaxh3', params.model),
findMatchingVAE('minimaxh3'),
findMiniMaxAudioVAE(),
])
const unetId = String(n++)
const clipId = String(n++)
const vaeId = String(n++)
const audioVaeId = String(n++)
addUnetLoader(workflow, unetId, params.model, allNodes)
workflow[clipId] = { class_type: 'CLIPLoader', inputs: { clip_name: clipName, type: 'minimax', device: 'default' } }
workflow[vaeId] = { class_type: 'VAELoader', inputs: { vae_name: vaeName } }
workflow[audioVaeId] = { class_type: 'VAELoader', inputs: { vae_name: audioVaeName } }
// Video LoRAs (the turbo ones included) patch the model only.
let modelSrc = unetId
const stack = normalizeLoraList(params.lora)
const stackStrengths = normalizeLoraStrengths(params.loraStrength, stack.length)
// FastH3 is already the 8 step distillation. A step LoRA (the H3 turbo one)
// on top of it distils twice, so on FastH3 it is left out; every other LoRA
// in the stack still patches the model.
const keep = stack.map((l) => !(fast && H3_STEP_LORA.test(l)))
const loras = stack.filter((_, i) => keep[i])
const strengths = stackStrengths.filter((_, i) => keep[i])
loras.forEach((loraName, i) => {
const loraId = String(n++)
workflow[loraId] = {
class_type: 'LoraLoaderModelOnly',
inputs: { lora_name: loraName, strength_model: strengths[i], model: [modelSrc, 0] },
}
modelSrc = loraId
})
if (fast) {
// The official template (video_fastvideo_fasth3_t2v) patches the model with
// the distilled schedule's shifts (video 10, audio 3, not the base model's
// 12) and then the VSA sparse attention the checkpoint was trained with
// (keep 10 percent of the video cubes). The template also picks the comfy
// kitchen attention for the dense layers; that choice is left to ComfyUI's
// default because the option is missing on cards that cannot run it.
const shiftId = String(n++)
const sparseId = String(n++)
workflow[shiftId] = { class_type: 'MiniMaxH3SigmaShift', inputs: { model: [modelSrc, 0], shift_video: 10, shift_audio: 3 } }
workflow[sparseId] = {
class_type: 'BlockSparseAttention',
inputs: {
model: [shiftId, 0], selection: 'vsa', 'selection.keep_percent': 10,
start_percent: 0.2, end_percent: 1, dense_blocks: '', min_tokens: 12288, extra_tokens: 256,
sink_conditioning: 'exact_kv_and_rows', verbose: false,
},
}
modelSrc = sparseId
}
const encodeInputs: ComfyNodeInputs = { clip: [clipId, 0], vae: [vaeId, 0], prompt: params.prompt, width, height, length }
if (params.inputImage) {
// The node stretches a first frame to the canvas; a center crop keeps
// the picture's proportions instead.
const imageId = String(n++)
const scaleId = String(n++)
workflow[imageId] = { class_type: 'LoadImage', inputs: { image: params.inputImage } }
workflow[scaleId] = { class_type: 'ImageScale', inputs: { image: [imageId, 0], upscale_method: 'lanczos', width, height, crop: 'center' } }
if (isRef2va) encodeInputs['ref_images.ref_image_0'] = [scaleId, 0]
else encodeInputs.first_frame = [scaleId, 0]
}
// B38: fl2va ends on a second picture (last_frame, center crop like the
// node itself), ref2va takes up to nine references (ref_image_0 to _8).
// The node scales references on its own ("match"), so they go in as they are.
if (params.endImage && !isRef2va) {
const endId = String(n++)
const endScaleId = String(n++)
workflow[endId] = { class_type: 'LoadImage', inputs: { image: params.endImage } }
workflow[endScaleId] = { class_type: 'ImageScale', inputs: { image: [endId, 0], upscale_method: 'lanczos', width, height, crop: 'center' } }
encodeInputs.last_frame = [endScaleId, 0]
}
if (isRef2va) {
const more = params.inputImage ? (params.referenceImages ?? []).slice(0, localAnimateReferenceSlots(params.model)) : []
for (const [i, image] of more.entries()) {
const refId = String(n++)
workflow[refId] = { class_type: 'LoadImage', inputs: { image } }
encodeInputs[`ref_images.ref_image_${i + 1}`] = [refId, 0]
}
// The node numbers its pictures <Picture 1> and up; "image 2" in the
// prompt means the second of them (lib/image-ref-names).
if (more.length > 0) encodeInputs.prompt = canonicalImageRefs(params.prompt, 1 + more.length, 'minimaxH3')
}
if (isRef2va) {
encodeInputs.audio_vae = [audioVaeId, 0]
encodeInputs.ref_image_size = 'match'
}
const encodeId = String(n++)
workflow[encodeId] = { class_type: encodeNode, inputs: encodeInputs }
const guiderId = String(n++)
const schedulerId = String(n++)
const samplerSelectId = String(n++)
const noiseId = String(n++)
const sampleId = String(n++)
workflow[guiderId] = { class_type: 'BasicGuider', inputs: { model: [modelSrc, 0], conditioning: [encodeId, 0] } }
// The H3 turbo LoRA says its step count in its name (minimax_h3_fl2v_turbo_
// 8step_...), and the official template runs it at exactly that (Discord
// 2026-10-02, a user's ComfyUI screenshot: turbo_steps 8). The
// slider's 20 or more would only cost time on a 24 GB model.
const turbo = loras.map((l) => H3_STEP_LORA.exec(l)).find((m) => m)
// FastH3 is the 8 step checkpoint: the template runs exactly 8.
const steps = fast ? 8 : turbo ? Number(turbo[1]) : params.steps
workflow[schedulerId] = { class_type: 'BasicScheduler', inputs: { model: [modelSrc, 0], scheduler: params.scheduler || 'simple', steps, denoise: 1 } }
workflow[samplerSelectId] = { class_type: 'KSamplerSelect', inputs: { sampler_name: params.sampler || 'res_multistep' } }
workflow[noiseId] = { class_type: 'RandomNoise', inputs: { noise_seed: seed } }
workflow[sampleId] = {
class_type: 'SamplerCustomAdvanced',
inputs: { noise: [noiseId, 0], guider: [guiderId, 0], sampler: [samplerSelectId, 0], sigmas: [schedulerId, 0], latent_image: [encodeId, 1] },
}
const decodeId = String(n++)
const decodeAudioId = String(n++)
workflow[decodeId] = { class_type: 'VAEDecode', inputs: { samples: [sampleId, 0], vae: [vaeId, 0] } }
workflow[decodeAudioId] = { class_type: 'VAEDecodeAudio', inputs: { samples: [sampleId, 0], vae: [audioVaeId, 0] } }
addVideoWithAudioOutput(workflow, n, decodeId, params.fps || 24, [decodeAudioId, 0], allNodes, params.prompt)
return workflow
}
/** LTX counts frames in blocks of 8 plus 1 (97 and 121 are the usual ones).
* Rounds to the nearest block, never below 9. */
export function snapLtx25Length(frames: number): number {
const f = Number.isFinite(frames) && frames > 0 ? Math.round(frames) : 121
return Math.max(9, Math.round((f - 1) / 8) * 8 + 1)
}
/** The two sigma ladders of the distilled model: 8 steps on the half size
* picture, then 3 after the latent upscale. Straight from the official
* video_ltx2_5_t2v / _i2v templates. */
const LTX25_SIGMAS_FIRST = '1.0, 0.99375, 0.9875, 0.98125, 0.975, 0.909375, 0.725, 0.421875, 0.0'
const LTX25_SIGMAS_SECOND = '0.85, 0.7250, 0.4219, 0.0'
/**
* LTX 2.5 (Lightricks, ComfyUI 0.32.0). Picture and sound come out of one
* model in two passes, wired as the official Comfy-Org templates
* video_ltx2_5_t2v and video_ltx2_5_i2v do:
*
* pass 1 an empty picture latent at HALF size plus an empty sound latent,
* joined (LTXVConcatAVLatent), sampled with the 8 step ladder
* upscale the picture half is split off, doubled by the latent upscaler and
* joined with the sound half again
* pass 2 3 more steps at full size
* output tiled VAE decode for the frames, the audio VAE for the sound,
* CreateVideo muxes them
*
* A start image (i2v) is cut to the canvas, preprocessed and written into the
* first frame twice: at strength 0.7 on the half size latent, at 1 after the
* upscale. The official template also has a prompt enhancer (a second, 5 GB
* Gemma) and an auto duration head; both are optional there and left out here.
* Multishot needs nothing in the graph: it is the model's own behaviour.
*/
async function buildLtx25Workflow(params: VideoParams, seed: number, allNodes: NodePresence): Promise<ComfyApiGraph> {
requireRelease(allNodes, ['LTXVDualCFGGuider'], LTX25_NEEDS_UPDATE, 'ltx25')
requireNodes(allNodes, [
'LTXVConditioning', 'EmptyLTXVLatentVideo', 'LTXVEmptyLatentAudio', 'LTXVConcatAVLatent', 'LTXVSeparateAVLatent',
'LTXVLatentUpsampler', 'LatentUpscaleModelLoader', 'LTXVAudioVAEDecode', 'ManualSigmas', 'KSamplerSelect',
'RandomNoise', 'SamplerCustomAdvanced', 'VAEDecodeTiled', 'CLIPTextEncode',
], 'LTX 2.5')
if (params.inputImage || params.continueFrom) requireNodes(allNodes, ['LTXVImgToVideoInplace', 'LTXVPreprocess', 'LoadImage', 'ImageScale'], 'LTX 2.5 image to video')
if (params.continueFrom) requireContinueNodes(allNodes, 'ltx25')
// The graph is the distilled one. The dev weights need a different schedule
// and guidance, and running them on this one gives noise.
if (/dev/i.test(params.model) && !/distilled/i.test(params.model)) {
throw new WorkflowUnavailableError(
'LU runs the distilled LTX 2.5 model. Pick the file with "distilled" in its name.',
'ltx25',
)
}
// The first pass runs at half size, so the final canvas must halve onto the
// 32 pixel grid the video VAE works on: multiples of 64.
const snap64 = (v: number | undefined, def: number) => Math.max(256, Math.round(((v && v > 0) ? v : def) / 64) * 64)
const width = snap64(params.width, 1280)
const height = snap64(params.height, 704)
const length = snapLtx25Length(params.frames || 121)
const fps = params.fps || 24
const [clipName, vaeName, audioVaeName] = await Promise.all([
findMatchingCLIP('ltx25', params.model),
findMatchingVAE('ltx25'),
findLtx25AudioVAE(),
])
const upscalerName = nodeComboOptions(allNodes, 'LatentUpscaleModelLoader', 'model_name')
.find((m) => /ltx[._\- ]?2[._\- ]?5/i.test(m) && /spatial/i.test(m))
if (!upscalerName) {
throw new Error('No LTX 2.5 latent upscaler found. Download "ltx-2.5-latent-spatial-upscaler-x2-bf16-1.0.safetensors" from the Model Manager.')
}
const workflow: ComfyApiGraph = {}
let n = 1
const add = (class_type: string, inputs: ComfyNodeInputs): string => {
const id = String(n++)
workflow[id] = { class_type, inputs }
return id
}
// The small variant is a GGUF quant (ComfyUI-GGUF), the full one a safetensors file.
const unetId = String(n++)
addUnetLoader(workflow, unetId, params.model, allNodes)
const clipId = add('CLIPLoader', { clip_name: clipName, type: 'ltxv', device: 'default' })
const vaeId = add('VAELoader', { vae_name: vaeName })
const audioVaeId = add('VAELoader', { vae_name: audioVaeName })
const upscaleLoaderId = add('LatentUpscaleModelLoader', { model_name: upscalerName })
const posId = add('CLIPTextEncode', { text: params.prompt, clip: [clipId, 0] })
const negId = add('CLIPTextEncode', { text: params.negativePrompt || '', clip: [clipId, 0] })
const condId = add('LTXVConditioning', { positive: [posId, 0], negative: [negId, 0], frame_rate: fps })
// A continued section (B18) pins the last frames of the clip so far, an
// 8n+1 run (17 frames are three latent frames), instead of one picture,
// and pins them fully in both passes: they are frames that already exist.
let imageSrc: string | null = null
let continued: ContinueSource | null = null
if (params.continueFrom) {
continued = addContinueSource(workflow, n, params.continueFrom, allNodes)
n = continued.n
const scaleId = add('ImageScale', { image: continued.tail, upscale_method: 'lanczos', width, height, crop: 'center' })
imageSrc = add('LTXVPreprocess', { image: [scaleId, 0], img_compression: 18 })
} else if (params.inputImage) {
const loadId = add('LoadImage', { image: params.inputImage })
const scaleId = add('ImageScale', { image: [loadId, 0], upscale_method: 'lanczos', width, height, crop: 'center' })
imageSrc = add('LTXVPreprocess', { image: [scaleId, 0], img_compression: 18 })
}
const pin = (latent: string, strength: number): string =>
imageSrc
? add('LTXVImgToVideoInplace', { vae: [vaeId, 0], image: [imageSrc, 0], latent: [latent, 0], strength: continued ? 1 : strength, bypass: false })
: latent
// One pass past one window: context windows on the model (LTXVContextWindows).
let model: [string, number] = [unetId, 0]
if (params.contextWindows && !continued) {
const win = addContextWindows(workflow, n, model, 'ltx25', length, allNodes)
n = win.n
model = win.model
}
// Pass 1: half size.
const emptyId = add('EmptyLTXVLatentVideo', { width: width / 2, height: height / 2, length, batch_size: 1 })
const videoLatent1 = pin(emptyId, 0.7)
const audioLatentId = add('LTXVEmptyLatentAudio', { frames_number: length, frame_rate: fps, batch_size: 1, audio_vae: [audioVaeId, 0] })
const joint1 = add('LTXVConcatAVLatent', { video_latent: [videoLatent1, 0], audio_latent: [audioLatentId, 0] })
const guider1 = add('LTXVDualCFGGuider', { model, positive: [condId, 0], negative: [condId, 1], video_cfg: 1, audio_cfg: 1 })
const sampler1 = add('KSamplerSelect', { sampler_name: 'euler_ancestral' })
const sigmas1 = add('ManualSigmas', { sigmas: LTX25_SIGMAS_FIRST })
const noise1 = add('RandomNoise', { noise_seed: seed })
const sample1 = add('SamplerCustomAdvanced', {
noise: [noise1, 0], guider: [guider1, 0], sampler: [sampler1, 0], sigmas: [sigmas1, 0], latent_image: [joint1, 0],
})
const split1 = add('LTXVSeparateAVLatent', { av_latent: [sample1, 0] })
// Upscale the picture half, keep the sound half.
const upscaled = add('LTXVLatentUpsampler', { samples: [split1, 0], upscale_model: [upscaleLoaderId, 0], vae: [vaeId, 0] })
const videoLatent2 = pin(upscaled, 1)
const joint2 = add('LTXVConcatAVLatent', { video_latent: [videoLatent2, 0], audio_latent: [split1, 1] })
// Pass 2: full size.
const guider2 = add('LTXVDualCFGGuider', { model, positive: [condId, 0], negative: [condId, 1], video_cfg: 1, audio_cfg: 1 })
const sampler2 = add('KSamplerSelect', { sampler_name: 'euler_ancestral' })
const sigmas2 = add('ManualSigmas', { sigmas: LTX25_SIGMAS_SECOND })
const noise2 = add('RandomNoise', { noise_seed: seed })
const sample2 = add('SamplerCustomAdvanced', {
noise: [noise2, 0], guider: [guider2, 0], sampler: [sampler2, 0], sigmas: [sigmas2, 0], latent_image: [joint2, 0],
})
const split2 = add('LTXVSeparateAVLatent', { av_latent: [sample2, 0] })
const decodeId = add('VAEDecodeTiled', { samples: [split2, 0], vae: [vaeId, 0], tile_size: 512, overlap: 64, temporal_size: 64, temporal_overlap: 16 })
const audioDecodeId = add('LTXVAudioVAEDecode', { samples: [split2, 1], audio_vae: [audioVaeId, 0] })
if (continued && params.continueFrom) {
const joined = addStitch(workflow, n, continued.frames, [decodeId, 0], params.continueFrom.overlap, allNodes)
n = joined.n
// The sound so far plus the new sound past the overlap. A clip so far
// without sound (made elsewhere) keeps only the new part's sound.
const sound = addAudioStitch(workflow, n, continued.audio, [audioDecodeId, 0], params.continueFrom.overlap / fps, allNodes)
if (sound) n = sound.n
addVideoWithAudioOutput(workflow, n, joined.images[0], fps, sound ? sound.audio : [audioDecodeId, 0], allNodes, params.prompt)
return workflow
}
addVideoWithAudioOutput(workflow, n, decodeId, fps, [audioDecodeId, 0], allNodes, params.prompt)
return workflow
}
// ─── 2.5.8 specialized local lanes (music / talking character / motion) ─────
//
// These intents run on node families that ship with CURRENT ComfyUI cores
// (ACE audio, Wan 2.2 S2V, Wan 2.2 Animate, Wan VACE — verified against the
// July 2026 core). Every builder gates on live node presence and throws
// WorkflowUnavailableError with an "Update ComfyUI" message when the install
// predates the family — REJECT-AND-REPORT, never a broken graph.
export interface LocalOpParams {
op: 'music' | 'lipsync' | 'motion'
model: string
prompt: string
negativePrompt?: string
seed: number
steps: number
cfgScale: number
sampler: string
scheduler: string
width: number
height: number
frames: number
fps: number
/** music: track length in seconds + optional lyrics. */
seconds?: number
lyrics?: string
/** lipsync: speech audio staged in ComfyUI's input dir + the portrait. */
audioFile?: string
refImage?: string
/** motion: driving video staged in ComfyUI's input dir. */
drivingVideo?: string
}
const UPDATE_COMFY_HINT =
'Update ComfyUI (Settings, AI Backends, Update ComfyUI), restart it, then generate again.'
/** The core video nodes a continued section is built from (B18). */
function requireContinueNodes(allNodes: NodePresence, strategy: WorkflowStrategy): void {
requireRelease(allNodes, ['LoadVideo', 'GetVideoComponents', 'ImageFromBatch'], CONTINUE_NEEDS_UPDATE, strategy)
}
function requireNodes(allNodes: NodePresence, needed: string[], lane: string): void {
const missing = needed.filter((n) => !allNodes[n])
if (missing.length > 0) {
throw new WorkflowUnavailableError(
`${lane} needs ComfyUI nodes this install does not have yet (${missing.join(', ')}). ${UPDATE_COMFY_HINT}`,
'unavailable',
undefined,
{ needsComfyUpdate: true },
)
}
}
/** Like requireNodes, for a model that arrived in a known ComfyUI release: the
* missing marker node means an older install, and the answer is the update
* sentence for THAT model (not a list of node names), flagged so Create offers
* the one click update. */
function requireRelease(allNodes: NodePresence, marker: string[], updateSentence: string, strategy: WorkflowStrategy): void {
if (marker.every((m) => allNodes[m])) return
throw new WorkflowUnavailableError(updateSentence, strategy, undefined, { needsComfyUpdate: true })
}
/** UNET loader that understands GGUF quants: .gguf files load through the
* city96 GGUF pack's UnetLoaderGGUF, everything else through core UNETLoader. */
/** Discord 2026-09-26/28: "Node 1
* (CheckpointLoaderSimple): Value not in list". The strategy comes from the
* file NAME, and a name LU cannot place ('unknown') falls to the checkpoint
* pipeline. For a file that sits in diffusion_models that is a guaranteed
* rejection, because CheckpointLoaderSimple only lists models/checkpoints.
* Say what is wrong instead. An unreadable enum stays silent, as before. */
function assertCheckpointListed(model: string, allNodes: NodePresence): void {
const checkpoints = nodeComboOptions(allNodes, 'CheckpointLoaderSimple', 'ckpt_name')
if (checkpoints.length === 0 || checkpoints.includes(model)) return
const unets = [
...nodeComboOptions(allNodes, 'UNETLoader', 'unet_name'),
...nodeComboOptions(allNodes, 'UnetLoaderGGUF', 'unet_name'),
]
throw new WorkflowUnavailableError(
unets.includes(model)
? `LU does not recognize which model family ${model} belongs to, so it has no pipeline for it. It sits in models/diffusion_models, where an SD 1.5 / SDXL checkpoint does not work. Pick another model, or report the file name so LU can learn it.`
: `${model} is no longer in ComfyUI's model list. It may have been moved or deleted. Pick another model, or restart ComfyUI after adding files.`,
'checkpoint',
)
}
/** Discord 2026-09-26: "Node 2 (CLIPLoader): Value not in list".
* Newer model families need a CLIPLoader type an older ComfyUI does not have
* yet (flux2, krea2, qwen_image). Only checked when the enum is readable. */
function assertClipTypeKnown(clipType: string, type: ModelType, strategy: WorkflowStrategy, allNodes: NodePresence): void {
const types = nodeComboOptions(allNodes, 'CLIPLoader', 'type')
if (types.length === 0 || types.includes(clipType)) return
throw new WorkflowUnavailableError(
`Your ComfyUI is too old for ${type} models (its text encoder loader has no "${clipType}" type). Update ComfyUI, then try again.`,
strategy,
undefined,
{ needsComfyUpdate: true },
)
}
function addUnetLoader(workflow: ComfyApiGraph, id: string, model: string, allNodes: NodePresence): void {
if (model.toLowerCase().endsWith('.gguf')) {
if (!allNodes['UnetLoaderGGUF']) {
throw new WorkflowUnavailableError(
'This model is a GGUF quant, which needs the ComfyUI-GGUF node pack. Install it from the model card, or pick the safetensors variant.',
'unavailable',
{ pack: 'ComfyUI-GGUF', url: 'https://github.com/city96/ComfyUI-GGUF' },
)
}
workflow[id] = { class_type: 'UnetLoaderGGUF', inputs: { unet_name: model } }
} else {
workflow[id] = { class_type: 'UNETLoader', inputs: { unet_name: model, weight_dtype: 'default' } }
}
}
/** Sound-carrying video output: core CreateVideo muxes the audio track into
* the frames, SaveVideo writes an mp4. The talking-character / motion clips
* are pointless without their sound, so this path requires the core video
* nodes (same family as the lanes themselves — present on any core new
* enough to run them). */
function addVideoWithAudioOutput(
workflow: ComfyApiGraph,
n: number,
decodeId: string,
fps: number,
audioSrc: [string, number] | null,
allNodes: NodePresence,
prompt?: string,
): number {
requireNodes(allNodes, ['CreateVideo', 'SaveVideo'], 'This video output')
const createId = String(n++)
const inputs: ComfyNodeInputs = { images: [decodeId, 0], fps }
if (audioSrc) inputs.audio = audioSrc
workflow[createId] = { class_type: 'CreateVideo', inputs }
const saveId = String(n++)
workflow[saveId] = {
class_type: 'SaveVideo',
inputs: { video: [createId, 0], filename_prefix: promptFilenamePrefix(prompt, true), format: 'auto', codec: 'auto' },
}
return n
}
/**
* YuE2 (m-a-p, ComfyUI 0.36.0). Songs with vocals from a style and lyrics, the
* graph of the official template audio_yue2_text2music with ABC planning off:
* the checkpoint's own text model writes the music tokens
* (YuE2GenerateMusic, which also reports how many seconds it made), a
* KSampler turns them into audio latents of exactly that length
* (EmptyYuE2LatentAudio) and the checkpoint's VAE decodes them.
*
* The sampler is the template's (32 steps, cfg 1, dpm_2, sgm_uniform) and is
* pinned: the music sliders are tuned for ACE Step. The prompt is the style,
* the lyrics field is the lyrics. An empty ABC input makes the node switch to
* its own "off" mode, as the template does.
*/
function buildYue2Workflow(params: LocalOpParams, seed: number, allNodes: NodePresence): ComfyApiGraph {
requireRelease(allNodes, ['YuE2GenerateMusic', 'EmptyYuE2LatentAudio'], YUE2_NEEDS_UPDATE, 'unavailable')
requireNodes(allNodes, ['ConditioningZeroOut', 'KSampler', 'VAEDecodeAudio', 'SaveAudioMP3'], 'Local music')
const workflow: ComfyApiGraph = {}
let n = 1
const seconds = Math.max(5, Math.min(600, params.seconds || 120))
const ckptId = String(n++)
workflow[ckptId] = { class_type: 'CheckpointLoaderSimple', inputs: { ckpt_name: params.model } }
const musicId = String(n++)
workflow[musicId] = {
class_type: 'YuE2GenerateMusic',
inputs: {
clip: [ckptId, 1], style: params.prompt, lyrics: params.lyrics || '', abc: '', seed, mode: 'full',
max_duration: seconds, temperature: 1, top_p: 0.95, top_k: 100, repetition_penalty: 1.2,
},
}
const negId = String(n++)
workflow[negId] = { class_type: 'ConditioningZeroOut', inputs: { conditioning: [musicId, 0] } }
const latentId = String(n++)
workflow[latentId] = { class_type: 'EmptyYuE2LatentAudio', inputs: { seconds: [musicId, 1], batch_size: 1 } }
const samplerId = String(n++)
workflow[samplerId] = {
class_type: 'KSampler',
inputs: {
model: [ckptId, 0], positive: [musicId, 0], negative: [negId, 0], latent_image: [latentId, 0],
seed, steps: 32, cfg: 1.0, sampler_name: 'dpm_2', scheduler: 'sgm_uniform', denoise: 1.0,
},
}
const decodeId = String(n++)
workflow[decodeId] = { class_type: 'VAEDecodeAudio', inputs: { samples: [samplerId, 0], vae: [ckptId, 2] } }
const saveId = String(n++)
workflow[saveId] = {
class_type: 'SaveAudioMP3',
inputs: { audio: [decodeId, 0], filename_prefix: promptFilenamePrefix(params.prompt, false), quality: 'V0' },
}
return workflow
}
/**
* Music (ACE-Step). All-in-one checkpoint → ACE text encode (tags + lyrics) →
* KSampler → VAEDecodeAudio → SaveAudioMP3. ACE-Step 1.5 checkpoints route
* through the 1.5 encoder/latent pair (different node ids AND different latent
* shape); everything else uses the v1 pair. Negative conditioning: v1 encodes
* the negative prompt (cheap), 1.5 zero-outs the positive instead — its
* encoder runs an LLM pass that would double the cost for no benefit.
*/
export function buildMusicWorkflow(params: LocalOpParams, seed: number, allNodes: NodePresence): ComfyApiGraph {
if (classifyModel(params.model) === 'yue2') return buildYue2Workflow(params, seed, allNodes)
const workflow: ComfyApiGraph = {}
let n = 1
const isAce15 = /1[._-]?5/.test(params.model.toLowerCase().replace(/\.safetensors$/, '').replace(/^.*ace[_-]?step/, ''))
const encodeNode = isAce15 ? 'TextEncodeAceStepAudio1.5' : 'TextEncodeAceStepAudio'
const latentNode = isAce15 ? 'EmptyAceStep1.5LatentAudio' : 'EmptyAceStepLatentAudio'
requireNodes(allNodes, [encodeNode, latentNode, 'VAEDecodeAudio', 'SaveAudioMP3'], 'Local music')
const seconds = Math.max(5, Math.min(600, params.seconds || 120))
const ckptId = String(n++)
workflow[ckptId] = { class_type: 'CheckpointLoaderSimple', inputs: { ckpt_name: params.model } }
const posId = String(n++)
if (isAce15) {
workflow[posId] = {
class_type: encodeNode,
inputs: {
clip: [ckptId, 1], tags: params.prompt, lyrics: params.lyrics || '',
seed, bpm: 120, duration: seconds, timesignature: '4', language: 'en',
keyscale: 'C major', generate_audio_codes: true, cfg_scale: 2.0,
temperature: 0.85, top_p: 0.9, top_k: 0, min_p: 0.0,
},
}
} else {
workflow[posId] = {
class_type: encodeNode,
inputs: { clip: [ckptId, 1], tags: params.prompt, lyrics: params.lyrics || '', lyrics_strength: 1.0 },
}
}
const negId = String(n++)
if (isAce15) {
workflow[negId] = { class_type: 'ConditioningZeroOut', inputs: { conditioning: [posId, 0] } }
} else {
workflow[negId] = {
class_type: encodeNode,
inputs: { clip: [ckptId, 1], tags: params.negativePrompt || '', lyrics: '', lyrics_strength: 1.0 },
}
}
const shiftId = String(n++)
workflow[shiftId] = { class_type: 'ModelSamplingSD3', inputs: { model: [ckptId, 0], shift: 5.0 } }
const latentId = String(n++)
workflow[latentId] = { class_type: latentNode, inputs: { seconds, batch_size: 1 } }
// ACE-Step samples on the flow-match euler/simple pairing, NOT the composer's
// image-model sampler (dpmpp_2m/karras etc. leaks in through the shared knobs).
// And the 1.5 TURBO checkpoint is distilled for ~10 steps at cfg 1.0 — the
// shared 'ace' default (50 steps, cfg 5) overcooks it into near-silence
// (measured: -43 dB mean output vs -18 dB at the turbo recipe, the owner's "quiet
// noise" bug). Pin the turbo recipe by name; other ACE checkpoints keep the
// composer's step/cfg but still sample on euler/simple.
const isTurbo = /turbo/.test(params.model.toLowerCase())
const musicSteps = isTurbo ? Math.min(params.steps || 10, 10) : params.steps
const musicCfg = isTurbo ? 1.0 : params.cfgScale
const samplerId = String(n++)
workflow[samplerId] = {
class_type: 'KSampler',
inputs: {
model: [shiftId, 0], positive: [posId, 0], negative: [negId, 0], latent_image: [latentId, 0],
seed, steps: musicSteps, cfg: musicCfg, sampler_name: 'euler', scheduler: 'simple', denoise: 1.0,
},
}
const decodeId = String(n++)
workflow[decodeId] = { class_type: 'VAEDecodeAudio', inputs: { samples: [samplerId, 0], vae: [ckptId, 2] } }
const saveId = String(n++)
workflow[saveId] = {
class_type: 'SaveAudioMP3',
inputs: { audio: [decodeId, 0], filename_prefix: promptFilenamePrefix(params.prompt, false), quality: 'V0' },
}
return workflow
}
/**
* Talking character (Wan 2.2 S2V, core). Portrait + speech audio → the
* character speaks it. wav2vec2 audio embeddings feed WanSoundImageToVideo;
* the finished frames are muxed WITH the speech track (CreateVideo), because
* a silent talking-head clip is useless. Uses the Wan 2.1 VAE + UMT5 encoder
* (the S2V-14B pairing from the official release).
*
* K2 (a user, Discord "HELP WITH MODELS"/help-18,
* 2026-09-15/17): the CLIP/VAE/audio-encoder filenames below used to be
* written straight into their loader nodes as literal strings, never checked
* against what ComfyUI actually has installed. Whichever one the box didn't
* have failed validation with "Value not in list", specifically Node 3
* (VAELoader) in the reports, because that is the third node this builder
* creates. Resolve
* every one of them against the live enum first (same rule Bug C already
* applied to the FLUX/video lanes in buildDynamicWorkflow), so a mismatch is
* caught before /prompt submission with an actionable "download <file>"
* message instead of ComfyUI's opaque rejection.
*/
export async function buildS2VWorkflow(params: LocalOpParams, seed: number, allNodes: NodePresence): Promise<ComfyApiGraph> {
const workflow: ComfyApiGraph = {}
let n = 1
requireNodes(
allNodes,
['WanSoundImageToVideo', 'AudioEncoderLoader', 'AudioEncoderEncode', 'LoadAudio'],
'Talking character',
)
if (!params.audioFile) throw new Error('Add a voice first. Record, upload or pick an audio track.')
if (!params.refImage) throw new Error('Add the portrait the character should speak from.')
const snap16 = (v: number, def: number) => Math.max(16, Math.round(((v && v > 0) ? v : def) / 16) * 16)
const width = snap16(params.width, 832)
const height = snap16(params.height, 480)
const length = snapWanLength(params.frames || 77)
const [wanClip, wanVae, audioEncoder] = await Promise.all([
findMatchingCLIP('wan', params.model),
findMatchingVAE('wan'),
findMatchingAudioEncoder(),
])
const unetId = String(n++)
addUnetLoader(workflow, unetId, params.model, allNodes)
const clipId = String(n++)
workflow[clipId] = { class_type: 'CLIPLoader', inputs: { clip_name: wanClip, type: 'wan', device: 'default' } }
const vaeId = String(n++)
workflow[vaeId] = { class_type: 'VAELoader', inputs: { vae_name: wanVae } }
const posId = String(n++)
workflow[posId] = { class_type: 'CLIPTextEncode', inputs: { text: params.prompt || 'a person talking naturally, natural expression', clip: [clipId, 0] } }
const negId = String(n++)
workflow[negId] = { class_type: 'CLIPTextEncode', inputs: { text: params.negativePrompt || '', clip: [clipId, 0] } }
const audioLoadId = String(n++)
workflow[audioLoadId] = { class_type: 'LoadAudio', inputs: { audio: params.audioFile } }
const audioEncLoadId = String(n++)
workflow[audioEncLoadId] = { class_type: 'AudioEncoderLoader', inputs: { audio_encoder_name: audioEncoder } }
const audioEncId = String(n++)
workflow[audioEncId] = { class_type: 'AudioEncoderEncode', inputs: { audio_encoder: [audioEncLoadId, 0], audio: [audioLoadId, 0] } }
const imageId = String(n++)
workflow[imageId] = { class_type: 'LoadImage', inputs: { image: params.refImage } }
const scaleId = String(n++)
workflow[scaleId] = { class_type: 'ImageScale', inputs: { image: [imageId, 0], upscale_method: 'lanczos', width, height, crop: 'center' } }
const s2vId = String(n++)
workflow[s2vId] = {
class_type: 'WanSoundImageToVideo',
inputs: {
positive: [posId, 0], negative: [negId, 0], vae: [vaeId, 0],
width, height, length, batch_size: 1,
audio_encoder_output: [audioEncId, 0], ref_image: [scaleId, 0],
},
}
const shiftId = String(n++)
workflow[shiftId] = { class_type: 'ModelSamplingSD3', inputs: { model: [unetId, 0], shift: 8.0 } }
const samplerId = String(n++)
workflow[samplerId] = {
class_type: 'KSampler',
inputs: {
model: [shiftId, 0], positive: [s2vId, 0], negative: [s2vId, 1], latent_image: [s2vId, 2],
seed, steps: params.steps, cfg: params.cfgScale, sampler_name: params.sampler, scheduler: params.scheduler, denoise: 1.0,
},
}
const decodeId = String(n++)
workflow[decodeId] = videoDecodeNode([samplerId, 0], [vaeId, 0], 'VAEDecodeTiled' in allNodes)
addVideoWithAudioOutput(workflow, n, decodeId, params.fps || 16, [audioLoadId, 0], allNodes, params.prompt)
return workflow
}
/**
* Motion control. A character image copies the moves of a driving video.
* Wan 2.2 Animate models take a DWPose skeleton video (pose_video); Wan VACE
* models take the same skeleton as their control_video — both need the
* DWPreprocessor from comfyui_controlnet_aux (one-click install; its CPU
* onnxruntime path works on every Windows box, no GPU wheel roulette).
* The driving clip's own audio is carried over into the result.
*
* K2: same live-list-first fix as buildS2VWorkflow above, since CLIP/VAE
* were hardcoded literals here too.
*/
export async function buildMotionWorkflow(params: LocalOpParams, seed: number, allNodes: NodePresence): Promise<ComfyApiGraph> {
const workflow: ComfyApiGraph = {}
let n = 1
requireNodes(allNodes, ['LoadVideo', 'GetVideoComponents'], 'Motion control')
if (!allNodes['DWPreprocessor']) {
throw new WorkflowUnavailableError(
'Motion control needs the pose extractor (DWPose) from the controlnet_aux node pack. Install it from the card above, then generate again.',
'unavailable',
{ pack: 'comfyui_controlnet_aux', url: 'https://github.com/Fannovel16/comfyui_controlnet_aux' },
)
}
if (!params.drivingVideo) throw new Error('Add the driving video whose motion the character should copy.')
if (!params.refImage) throw new Error('Add the character image that should perform the motion.')
const isVace = classifyModel(params.model) === 'wanvace'
requireNodes(allNodes, isVace ? ['WanVaceToVideo', 'TrimVideoLatent'] : ['WanAnimateToVideo', 'TrimVideoLatent'], 'Motion control')
const snap16 = (v: number, def: number) => Math.max(16, Math.round(((v && v > 0) ? v : def) / 16) * 16)
const width = snap16(params.width, 832)
const height = snap16(params.height, 480)
const length = snapWanLength(params.frames || 77)
const [wanClip, wanVae] = await Promise.all([
findMatchingCLIP('wan', params.model),
findMatchingVAE('wan'),
])
const unetId = String(n++)
addUnetLoader(workflow, unetId, params.model, allNodes)
const clipId = String(n++)
workflow[clipId] = { class_type: 'CLIPLoader', inputs: { clip_name: wanClip, type: 'wan', device: 'default' } }
const vaeId = String(n++)
workflow[vaeId] = { class_type: 'VAELoader', inputs: { vae_name: wanVae } }
const posId = String(n++)
workflow[posId] = { class_type: 'CLIPTextEncode', inputs: { text: params.prompt || 'a person moving naturally, high quality', clip: [clipId, 0] } }
const negId = String(n++)
workflow[negId] = { class_type: 'CLIPTextEncode', inputs: { text: params.negativePrompt || '', clip: [clipId, 0] } }
const videoId = String(n++)
workflow[videoId] = { class_type: 'LoadVideo', inputs: { file: params.drivingVideo } }
const componentsId = String(n++)
workflow[componentsId] = { class_type: 'GetVideoComponents', inputs: { video: [videoId, 0] } }
const poseId = String(n++)
workflow[poseId] = {
class_type: 'DWPreprocessor',
inputs: {
image: [componentsId, 0], detect_hand: 'enable', detect_body: 'enable', detect_face: 'enable',
resolution: Math.min(width, height),
bbox_detector: 'yolox_l.onnx', pose_estimator: 'dw-ll_ucoco_384.onnx',
},
}
const imageId = String(n++)
workflow[imageId] = { class_type: 'LoadImage', inputs: { image: params.refImage } }
const scaleId = String(n++)
workflow[scaleId] = { class_type: 'ImageScale', inputs: { image: [imageId, 0], upscale_method: 'lanczos', width, height, crop: 'center' } }
const condId = String(n++)
if (isVace) {
workflow[condId] = {
class_type: 'WanVaceToVideo',
inputs: {
positive: [posId, 0], negative: [negId, 0], vae: [vaeId, 0],
width, height, length, batch_size: 1, strength: 1.0,
control_video: [poseId, 0], reference_image: [scaleId, 0],
},
}
} else {
workflow[condId] = {
class_type: 'WanAnimateToVideo',
inputs: {
positive: [posId, 0], negative: [negId, 0], vae: [vaeId, 0],
width, height, length, batch_size: 1,
reference_image: [scaleId, 0], pose_video: [poseId, 0],
continue_motion_max_frames: 5, video_frame_offset: 0,
},
}
}
const shiftId = String(n++)
workflow[shiftId] = { class_type: 'ModelSamplingSD3', inputs: { model: [unetId, 0], shift: 8.0 } }
const samplerId = String(n++)
workflow[samplerId] = {
class_type: 'KSampler',
inputs: {
model: [shiftId, 0], positive: [condId, 0], negative: [condId, 1], latent_image: [condId, 2],
seed, steps: params.steps, cfg: params.cfgScale, sampler_name: params.sampler, scheduler: params.scheduler, denoise: 1.0,
},
}
// Both conditioners prepend reference latents — trim them back out so the
// decoded clip starts on the motion, not on a frozen reference frame.
const trimId = String(n++)
workflow[trimId] = { class_type: 'TrimVideoLatent', inputs: { samples: [samplerId, 0], trim_amount: [condId, 3] } }
const decodeId = String(n++)
workflow[decodeId] = videoDecodeNode([trimId, 0], [vaeId, 0], 'VAEDecodeTiled' in allNodes)
addVideoWithAudioOutput(workflow, n, decodeId, params.fps || 16, [componentsId, 1], allNodes, params.prompt)
return workflow
}
/**
* Animate with Wan 2.1 VACE as a reference model (D24): the picture goes into
* WanVaceToVideo as reference_image, with no control video, so the clip is
* made from the prompt around the subject instead of starting on the picture.
* The same conditioner, sampling and trim as the VACE path of
* buildMotionWorkflow above, only without the pose video and its audio.
*/
export async function buildVaceReferenceWorkflow(params: VideoParams, seed: number, nodes: CategorizedNodes, allNodes: NodePresence): Promise<ComfyApiGraph> {
if (!params.inputImage) throw new Error('Add the reference picture first.')
requireNodes(allNodes, ['WanVaceToVideo', 'TrimVideoLatent', 'LoadImage', 'ImageScale'], 'Animate with VACE')
const workflow: ComfyApiGraph = {}
let n = 1
const snap16 = (v: number, def: number) => Math.max(16, Math.round(((v && v > 0) ? v : def) / 16) * 16)
const width = snap16(params.width, 832)
const height = snap16(params.height, 480)
const length = snapWanLength(params.frames || 81)
const [wanClip, wanVae] = await Promise.all([
findMatchingCLIP('wan', params.model),
findMatchingVAE('wan'),
])
const unetId = String(n++)
addUnetLoader(workflow, unetId, params.model, allNodes)
const clipId = String(n++)
workflow[clipId] = { class_type: 'CLIPLoader', inputs: { clip_name: wanClip, type: 'wan', device: 'default' } }
const vaeId = String(n++)
workflow[vaeId] = { class_type: 'VAELoader', inputs: { vae_name: wanVae } }
const posId = String(n++)
workflow[posId] = { class_type: 'CLIPTextEncode', inputs: { text: params.prompt || 'the subject moving naturally, high quality', clip: [clipId, 0] } }
const negId = String(n++)
workflow[negId] = { class_type: 'CLIPTextEncode', inputs: { text: params.negativePrompt || '', clip: [clipId, 0] } }
const imageId = String(n++)
workflow[imageId] = { class_type: 'LoadImage', inputs: { image: params.inputImage } }
const scaleId = String(n++)
workflow[scaleId] = { class_type: 'ImageScale', inputs: { image: [imageId, 0], upscale_method: 'lanczos', width, height, crop: 'center' } }
const condId = String(n++)
workflow[condId] = {
class_type: 'WanVaceToVideo',
inputs: {
positive: [posId, 0], negative: [negId, 0], vae: [vaeId, 0],
width, height, length, batch_size: 1, strength: 1.0,
reference_image: [scaleId, 0],
},
}
const shiftId = String(n++)
workflow[shiftId] = { class_type: 'ModelSamplingSD3', inputs: { model: [unetId, 0], shift: 8.0 } }
const samplerId = String(n++)
workflow[samplerId] = {
class_type: 'KSampler',
inputs: {
model: [shiftId, 0], positive: [condId, 0], negative: [condId, 1], latent_image: [condId, 2],
seed, steps: params.steps, cfg: params.cfgScale, sampler_name: params.sampler, scheduler: params.scheduler, denoise: 1.0,
},
}
// The reference rides in front of the clip as extra latent frames; the trim
// takes them out again so the video does not open on a still of it.
const trimId = String(n++)
workflow[trimId] = { class_type: 'TrimVideoLatent', inputs: { samples: [samplerId, 0], trim_amount: [condId, 3] } }
const decodeId = String(n++)
workflow[decodeId] = videoDecodeNode([trimId, 0], [vaeId, 0], 'VAEDecodeTiled' in allNodes)
addVideoOutput(workflow, n, decodeId, params.fps || 16, nodes, params.prompt)
return workflow
}
/** Entry point for the specialized local lanes — fetches the live node
* catalogue once and dispatches to the lane's builder. */
export async function buildLocalOpWorkflow(params: LocalOpParams): Promise<ComfyApiGraph> {
const allNodes = await getAllNodeInfo()
const seed = resolveRunSeed(params.seed)
switch (params.op) {
case 'music': return buildMusicWorkflow(params, seed, allNodes)
case 'lipsync': return await buildS2VWorkflow(params, seed, allNodes)
case 'motion': return await buildMotionWorkflow(params, seed, allNodes)
}
}
async function buildFramePackWorkflow(params: VideoParams, seed: number, nodes: CategorizedNodes): Promise<ComfyApiGraph> {
const workflow: ComfyApiGraph = {}
let n = 1
const modelId = String(n++)
const clipId = String(n++)
const clipVisionId = String(n++)
const vaeId = String(n++)
const imageId = String(n++)
const posId = String(n++)
const samplerId = String(n++)
const decodeId = String(n++)
// VRAM-safe load (2026-06-11, live OOM on his RTX 3060 12GB):
// `quantization:'disabled' + base_precision:'bf16' + load_device:'main_device'`
// UPCAST the fp8 13B weights to bf16 (~26 GB) and put the whole transformer on
// the GPU at once → torch.OutOfMemoryError in LoadFramePackModel before a single
// step ran. The file is already fp8_e4m3fn, so keep it quantized and load to the
// OFFLOAD (CPU) device — FramePack's section sampler streams it onto the GPU a
// window at a time (gpu_memory_preservation governs the headroom). This is the
// documented low-VRAM combo and is what makes FramePack actually run on 12 GB
// (and down to ~6 GB) instead of OOMing on every consumer card.
workflow[modelId] = { class_type: 'LoadFramePackModel', inputs: { model: params.model, base_precision: 'bf16', quantization: 'fp8_e4m3fn', load_device: 'offload_device' } }
// DualCLIPLoader with type "hunyuan_video": CLIPLoader type "wan" creates Llama2 with
// 128256 vocab but llava_llama3 has 128320 tokens, causing a state_dict size mismatch.
// DualCLIPLoader handles both correctly. K2 (Punkt 2): both names used to be hardcoded
// literals, resolved now via findFramePackCLIPPair against the live CLIP enum.
const framePackClips = await findFramePackCLIPPair()
workflow[clipId] = { class_type: 'DualCLIPLoader', inputs: { clip_name1: framePackClips.clipL, clip_name2: framePackClips.llavaLlama3, type: 'hunyuan_video' } }
// K2: was a hardcoded literal never checked against the live CLIPVisionLoader
// enum, same "Value not in list" failure mode as the VAE below, just for a
// different node. Resolved against the live list like the VAE already is.
workflow[clipVisionId] = { class_type: 'CLIPVisionLoader', inputs: { clip_name: await findMatchingClipVision() } }
// FramePack is a HunyuanVideo 1.0 model. Its sampler allocates the history
// buffer with 16 latent channels, and the HunyuanVideo 1.5 VAE encodes 32, so
// pairing the two dies at the first section with "Expected size 32 but got
// size 16" (D#104). `6fb83d31` pinned this to the 1.5 file while
// fixing unrelated filename typos, which broke every FramePack run since.
//
// Resolved against the disk rather than pinned again: the resolver refuses a
// 1.5 VAE outright and names the file to fetch, so a customer whose bundle
// predates this fix reads "download hunyuan_video_vae_bf16" instead of a raw
// ComfyUI "value not in list" for a filename he never chose.
workflow[vaeId] = { class_type: 'VAELoader', inputs: { vae_name: await findMatchingVAE('framepack') } }
workflow[imageId] = { class_type: 'LoadImage', inputs: { image: params.inputImage || 'input_image.png' } }
// Scale the source to the resolved generation size before encoding (the owner
// 2026-06-11). FramePack otherwise samples at the full source resolution
// (a 1024×1024 still → very slow + heavy on a 12 GB card). resolveI2VResolution
// already picked an aspect-preserving size capped at 768 / snapped to 16;
// crop:'center' fills it without distortion. Feeds BOTH the CLIP-vision and
// VAE encoders so the embeds and latent agree on the framing.
const fpScaleId = String(n++)
workflow[fpScaleId] = {
class_type: 'ImageScale',
inputs: { image: [imageId, 0], upscale_method: 'lanczos', width: params.width || 640, height: params.height || 640, crop: 'center' },
}
// Encode image for CLIP vision embeddings (FramePackSampler image_embeds input)
const clipVisionEncodeId = String(n++)
workflow[clipVisionEncodeId] = { class_type: 'CLIPVisionEncode', inputs: { crop: 'center', clip_vision: [clipVisionId, 0], image: [fpScaleId, 0] } }
// Encode image to latent (FramePackSampler needs LATENT, not IMAGE)
const vaeEncodeId = String(n++)
workflow[vaeEncodeId] = { class_type: 'VAEEncode', inputs: { pixels: [fpScaleId, 0], vae: [vaeId, 0] } }
workflow[posId] = { class_type: 'CLIPTextEncode', inputs: { text: params.prompt, clip: [clipId, 0] } }
const negId = String(n++)
workflow[negId] = { class_type: 'CLIPTextEncode', inputs: { text: '', clip: [clipId, 0] } }
workflow[samplerId] = {
class_type: 'FramePackSampler',
inputs: {
model: [modelId, 0], positive: [posId, 0], negative: [negId, 0],
start_latent: [vaeEncodeId, 0], image_embeds: [clipVisionEncodeId, 0],
steps: params.steps, cfg: params.cfgScale || 1.0,
guidance_scale: 10.0, shift: 3.0, seed, latent_window_size: 9,
// VideoParams carries `frames` (not `numFrames`) — reading the wrong field
// pinned every FramePack clip to the 49-frame default and silently ignored
// the caller's requested length. FramePack is duration-driven, so the clip
// length = frames / fps seconds.
total_second_length: (params.frames || 49) / (params.fps || 16),
gpu_memory_preservation: 6.0, sampler: 'unipc_bh2',
use_teacache: true, teacache_rel_l1_thresh: 0.15,
},
}
workflow[decodeId] = videoDecodeNode([samplerId, 0], [vaeId, 0], nodes.decoders.includes('VAEDecodeTiled'))
addVideoOutput(workflow, n, decodeId, params.fps, nodes, params.prompt)
return workflow
}
// buildPyramidFlowWorkflow and buildAllegroWorkflow deleted 2026-07-24, same
// audit and same reason as buildCogVideoWorkflow above. Pyramid Flow named the
// loader PyramidFlowModelLoader (registered as PyramidFlowTransformerLoader),
// decoded through a PyramidFlowDecode that does not exist, and fed the sampler
// steps and frames where it wants prompt_embeds and per stage step strings.
// Allegro followed the identical invented shape against a wrapper we have never
// had installed. Both are recoverable from git history for a rebuild.