CineTimeline｜关键帧注入

CineTimelineH3KeyframeConditioning goes and fetches its keyframe stills itself, straight out of your input folder. CineTimelineKeyframeApplyGuides ("CineTimeline｜关键帧注入") is the sibling that refuses to do any of that - you hand it the images over real wires, and it pins them into whatever H3 positive conditioning and latent you already built.

It's the difference between "the plan has an asset path, go load it" and "I have the tensors right here in my graph, use these". If your conditioning doesn't come from the audio-T8 builder the other node leans on - say you're on a plainer ComfyUI H3 path - or if you've already got processed stills (masked, cropped, colour-graded) that you don't want re-read from disk, this is the node you reach for.

How it works

Inputs are positive (CONDITIONING), latent (LATENT), vae, plan_json, plus up to twelve optional image sockets, image_1 through image_12. For each guide in the plan it runs ComfyUI core's MiniMaxH3AddGuide - the same mechanism the auto-loading node uses - encoding the image with your VAE and injecting it into the conditioning at the guide's local_frame. No conditioning building here, no audio VAE, no latent creation. It assumes you already did that upstream.

Order is a contract, not a suggestion: the plan node sorts keyframes by frame before it writes the JSON, so image_1 is always the earliest keyframe and the last image is the one nearest the shot's end. Wire them in that order. If the plan has more guides than you connected, you get a hard TimelineValidationError - "keyframe image_N is required" - rather than a silent partial apply. Twelve sockets matches the twelve-slot ceiling, so a plan beyond that won't fit through this door anyway.

What comes out

• positive - your conditioning, now carrying every keyframe guide at its correct frame. Straight into your H3 sampler.
• guide_map - a text table that's more useful than it looks: one line per image, like image_1: global 0 -> local 0. When a shot comes out wrong and you're trying to figure out whether the still landed where you thought it did, this is your first stop.

When you'd actually use it

Honestly, for the stock CineTimeline keyframe workflow you'll usually reach for the auto-loading node and never touch this one's sockets. ApplyGuides earns its keep when you want control over which tensors get pinned - mid-workflow images, outputs of an earlier pass, assets you generated rather than imported. It also keeps working if the audio-T8 plugin isn't installed, since it only depends on ComfyUI's own H3 nodes. That's a real advantage: one less heavyweight custom node in the chain.

Where people get burned: mixing sources. If you wire this node in but leave the auto-loading conditioning node's output feeding the sampler too, you can end up with keyframes applied twice in slightly different forms. Pick one injection path per segment.

Installing

Same pack, same install - the plugin itself has no pip dependencies:

# ComfyUI Manager: search "ComfyUI-CineTimeline"
# or:
cd ComfyUI/custom_nodes
git clone https://github.com/bo341805sg/ComfyUI-CineTimeline

Restart ComfyUI afterwards. What this node needs at runtime is a ComfyUI build with H3 support (for MiniMaxH3AddGuide) and the H3 model chain behind it - the node itself stays lean. And yes, despite the model-neutral look of the inputs, every guide still goes through H3's MiniMaxH3AddGuide, so it only ever applies to H3 conditioning. The pack's design goal is model-neutral timelines, but this particular node is firmly on H3's side of the fence.