Live Preview:
PaintAPlate_LivePreview lets you watch a video shot develop while the video model is still sampling, rather than waiting for the finished render. It uses a small, lightweight decoder to turn the model’s current predictions into a looping animation displayed on the Paint a plate page. Previewing starts at the first sampling step and can repeat periodically, helping you assess the emerging composition and motion early. To reduce the work involved, the node can shrink the internal video representation before decoding and prepares the animation file in the background. It also supports a tone-mapped view of ACEScct material for checking an SDR-to-HDR pass. These animations are approximate progress checks, not final-quality renders: the model’s predictions are returned unchanged, and errors caught during preview decoding disable previews for that shot instead of interrupting sampling.
Live Preview Input Parameters:
model
A required MODEL connection containing the video model you want to monitor. The node attaches preview behavior to a clone of this model, so your downstream sampling process can periodically show its current predictions without changing those predictions. Connect this node between your model preparation nodes and the sampler that will generate the shot; connecting it elsewhere without sending its result to the sampler will not enable previews for that sampler. The implementation includes handling for nested predictions and packed video-and-audio latents, including the LTX 2.5 arrangement described in the source, but this does not establish compatibility with every video model. There is no default value or numeric range.
decoder
A required STRING naming the tiny video decoder file to load from ComfyUI’s models/vae_approx directory. The default is taeltx2_3.safetensors. This decoder converts intermediate video predictions into visible preview frames; it is not a replacement for your final decoding stage. Use a decoder compatible with your video model’s internal representation. When previews are enabled but the file cannot be found, the node returns the original model without enabling previews, allowing the shot to render normally. A decoder that exists but cannot be loaded can cause an execution error because loading happens before the protected sampling callback. Loaded decoders are cached by file path for reuse. No predefined options or length limits are declared.
frames
A required INT specifying the number of frames belonging to the shot, with a default of 121, a minimum of 1, and a maximum of 4096. This setting determines how much of the internal video sequence is included in preview decoding so that additional guide frames after the shot are excluded. The implementation converts the requested count into a latent-frame count using (frames - 1) // 8 + 1, reflecting the temporal compression expected by this workflow. Set it to the shot length used by your generation workflow rather than counting guide frames. It controls preview selection, not the number of frames your sampler generates; an incorrect value can omit part of the shot or include unwanted guide content.
fps
A required FLOAT setting the playback speed of the preview animation, with a default of 24.0, a minimum of 1.0, and a maximum of 120.0. The animation is saved with a frame duration of approximately 1000 / fps milliseconds, rounded to whole milliseconds. Matching this value to your intended shot frame rate makes the preview’s apparent motion easier to judge. A lower value plays the same preview more slowly, while a higher value plays it faster. This parameter does not change the sampler’s frame count, generation speed, or final video frame rate.
every
A required INT controlling how often previews are attempted during sampling, with a default of 0, a minimum of 0, and a maximum of 100. A value of 0 disables previewing entirely and returns the original model without loading the tiny decoder. Positive values enable a preview at step 1 and then every specified number of steps afterward; for example, 5 schedules previews at steps 1, 6, 11, and so on. Lower values provide more frequent visual feedback but add more decoding and file-writing work. A scheduled preview is skipped if the preceding animation is still being prepared, so this setting is a target interval rather than a guarantee that every scheduled update will appear. When the sampler does not expose its step schedule, the node uses callback counts instead, and the total step count is unknown.
size
A required INT setting the long side of the saved preview animation in pixels, with a default of 320, a minimum of 64, and a maximum of 1280. The other dimension is scaled proportionally to preserve the decoded image’s aspect ratio, subject to pixel rounding. The node also uses this setting when deciding whether to spatially shrink the internal video representation before decoding, aiming to decode at roughly twice the final preview size. Smaller values generally reduce preview processing and animation file size; larger values make more detail visible but increase the work involved. This setting affects previews only and does not change the final shot’s resolution.
transfer
An optional COMBO describing the color encoding of the decoded preview values. The available options are sRGB and ACEScct, with sRGB as the default. Choose sRGB for decoded values intended for ordinary sRGB display. Choose ACEScct when the decoded values represent ACEScct codes, such as during the SDR-to-HDR pass; the node then applies its ACEScct preview conversion to produce a tone-mapped display image. This choice controls preview interpretation rather than converting the generated shot itself. Selecting a mode that does not match the decoded values can make brightness, contrast, and color misleading.
Live Preview Output Parameters:
model
A MODEL connection intended for the downstream sampler. When previewing is enabled and the decoder file is found and loaded, this is a clone of the incoming model with a post-guidance sampling callback attached. The callback observes the model’s current predictions, prepares previews when scheduled, and returns the predictions unchanged, so the output is a model prepared for monitoring rather than a modified creative result. When previewing is disabled or the decoder file cannot be found, the original model is returned directly. Preview animations are not provided through an IMAGE or VIDEO output: they are saved as temporary looping WebP files and announced to the Paint a plate page through the paintaplate.live server event.
Live Preview Usage Tips:
- Connect the model preparation chain to this node, then connect its
modeloutput to the sampler. The sampler must use this output for the preview callback to run. - Start with
everyset to 5 andsizeset to 320 for periodic progress checks. The defaulteveryvalue of 0 means previews are off, even when all other settings are configured. - For quick composition and motion checks, try
sizeof 160–320 with a largereveryinterval. Increase the preview size when you need to inspect finer details, remembering that the final decode remains the appropriate place to judge image quality. - Place the compatible tiny decoder in
models/vae_approxand enter its filename exactly. The default filename istaeltx2_3.safetensors; do not assume that an unrelated image or video decoder will work. - Match
framesto the generated shot length, excluding any extra guide frames, and matchfpsto the intended playback rate. For the default 121-frame shot at 24 fps, the requested shot duration is approximately five seconds. - Use
transferset toACEScctonly when previewing ACEScct-coded predictions. KeepsRGBfor ordinary sRGB-coded previews; this choice is about viewing the current material correctly, not enabling HDR generation. - View updates in the Paint a plate page, available through the Extensions menu or at
/extensions/ainvfx-paintaplate/paintaplate.html. This node does not expose an image socket for a standard image-preview node. - If sampling becomes noticeably slower, increase
everyor reducesize. Animation encoding runs in the background, but decoding the current predictions still takes place during the sampling callback.
Live Preview Common Errors and Solutions:
No preview appears and no error is shown
- Explanation: Previewing is disabled by default because
everyis 0. The node also silently returns the original model when the decoder filename cannot be resolved, and its callback cannot run if the sampler bypasses its output. - Solution: Set
everyto a positive value, verify the decoder is present inmodels/vae_approx, and check that the sampler receives this node’smodeloutput. Open the Paint a plate page to see the animation.
Paint a plate Live Preview is off for this shot: ...
- Explanation: This is the warning prefix used when the preview callback catches an exception. The text after the colon contains the underlying problem, which may involve incompatible prediction shapes, decoder incompatibility, insufficient memory, or another decoding-stage failure. The node disables further preview attempts for that shot and returns the sampling predictions unchanged.
- Solution: Read the full warning in the ComfyUI log. Check that your model and tiny decoder are compatible, reduce
sizeif the message indicates a memory problem, and run the workflow again after correcting the cause. Seteveryto 0 if you want to render without previewing.
Decoder loading fails before sampling starts
- Explanation: This is a troubleshooting symptom rather than a fixed error message from this node. A decoder file may be found but fail while being read or initialized, for example because it is damaged or is not a suitable decoder checkpoint. Decoder loading happens outside the callback’s exception handler, so this failure can stop node execution rather than merely disable previews.
- Solution: Check the loader error in the ComfyUI log, verify the decoder file and its compatibility, and replace an incomplete or damaged download. Set
everyto 0 to bypass decoder loading and continue without previews.
Preview updates are less frequent than expected
- Explanation: This is normally a scheduling limitation rather than an error. The node skips a scheduled preview when the preceding animation is still being prepared. If the sampler does not provide its step schedule, the node counts callback calls instead, which may not match the step numbering you expect.
- Solution: Reduce
sizeto make previews quicker to prepare, or increaseeveryto give each update more time. Do not rely on receiving one animation for every scheduled interval or a guaranteed preview at the final sampling step.
Preview colors or brightness look incorrect
- Explanation: The
transfersetting may not match the decoded values. ACEScct-coded material needs the node’s tone-mapped preview conversion, while ordinary sRGB material should use the sRGB path. The tiny decoder also produces an approximate preview, so differences from the final render are possible. - Solution: Select
ACEScctfor the ACEScct SDR-to-HDR pass andsRGBfor sRGB-coded predictions. Confirm important color decisions using your final decoding and color-management workflow.
Preview shows too little of the shot or includes guide content
- Explanation: The
framesvalue controls the internal sequence portion selected for previewing. A value below the intended shot length can cut the preview short, while an excessive value can include latent frames intended as guides. The selection uses the workflow’s expected eight-frame temporal compression. - Solution: Match
framesto the shot’s generation settings and exclude appended guide frames. If the video model uses a different temporal representation, verify that it is compatible with this preview implementation.
Preview file cannot be written or the page receives no animation
- Explanation: The node saves WebP animations under
paintaplate_livein ComfyUI’s temporary directory and sends a server event to the connected client. File-writing failures, WebP encoding problems, or a disconnected page can prevent display. Animation saving occurs in a background task, so its failures are not covered by the callback’s “Live Preview is off” warning handler. - Solution: Check available disk space and write permissions for ComfyUI’s temporary directory, inspect the logs for relevant file or image-encoding errors, and confirm that the Paint a plate page is connected to the same ComfyUI server. Reconnect the page and start another run after resolving the issue.
