CineTimeline Studio｜关键帧模式

If you've opened a keyframe-mode CineTimeline workflow, you've met this node: a text box full of JSON that looks like the setup for a database assignment. It kind of is. That JSON is a whole short film - frames, shots, prompts, pinned stills - and CineTimelineKeyframePlan is the node that turns one slice of it into something a video model can actually run.

CineTimeline is a multi-shot, multi-reference timeline plugin aimed at AI film work. Its regular CineTimelinePlan node compiles shot references the Ref2VA way: here are the character, scene and video references for this shot. Keyframe mode is the pack's other philosophy - you steer the movie with stills pinned at specific frames, storyboard style. This node (shown in the UI as "CineTimeline Studio｜关键帧模式") is the keyframe-mode compiler.

What it actually does

Pure planning. It takes your MODEL and passes it straight through untouched - no sampling, no model math - reads the timeline, pulls out the one shot you're rendering, and emits everything the rest of the chain needs as structured JSON. You can compile plans all day and never touch your VRAM budget.

The big timeline_state widget holds the whole movie: fps, total_frames, an array of shots with start_frame/end_frame and local prompts, plus image references that each carry a keyframe_frame. When you run it, the node finds the target shot, sorts that shot's image references by frame, and stamps roles: the image on the shot's start frame becomes first, one on the final frame becomes last, everything between is a plain guide.

Then it validates your storyboard like an editor would. The first keyframe must sit exactly on the shot's start frame. With two or more images, the last one must sit on the final frame. Middle frames just have to be unique and inside the shot. Violate any of that and you get a TimelineValidationError naming the rule you broke - these errors read like a producer yelling, and that's deliberate. If the shot has no keyframe images at all, it compiles as plain text-to-video instead.

The inputs that matter

• timeline_state - where the movie lives. Multiline JSON with a sensible one-shot default you can read as the schema.
• timeline_json - an optional alternate feed, used when a full workflow run has no specific shot targeted.
• render_target_shot_id - which shot this run compiles. Leave it empty and the node recovers the target from timeline metadata, so a targeted run stays correct even when widgets aren't serialized.
• model - a pass-through, but it keeps the node honest: the plan knows what model family it's planning for.

Outputs worth wiring

The star is keyframe_plan_json: the per-shot plan with a guides[] array - each still's asset_id plus its global_frame and local_frame (frame minus shot start). Everything downstream reads from it. Also out: segment_prompt (global + local prompt joined), frame_count, and a couple of routing flags.

Here's where the frame math lives. H3 lengths land on a 17k+5 frame grid, and a shot that continues the previous one via motion context adds a 22-frame lead-in. So frame_count is the generation length - bigger than the visible shot - and video_extension_plan carries the previous shot's verified latent path and SHA-256 so the next segment never silently grabs stale context. Downstream, CineTimelineKeyframeFinalize uses the same plan JSON to trim everything back to the true shot length.

Wire keyframe_plan_json into CineTimelineH3KeyframeConditioning (auto-loads the stills itself) or CineTimelineKeyframeApplyGuides (you supply the stills as image wires).

Installing

The pack ships no Python dependencies at all - pyproject.toml declares an empty list, and this node is pure JSON parsing. Install once, use it on every node in the pack:

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

Then restart ComfyUI. Note that planning needs nothing but ComfyUI - the H3 requirements (big model, qwen3vl text encoder, plenty of VRAM) only bite once you hit the keyframe conditioning and sampler nodes downstream.

Reality check

This is bleeding edge - keyframe mode landed in the pack's most recent commit (Sept 2026), the README documents the newer mainline workflow and doesn't cover keyframe mode yet, and the DOM timeline editor that used to live inside this node is keyed to an older class name that's no longer shipped. So today you get the raw JSON widget rather than a clickable storyboard. Don't fight it; the JSON is the product, and the validation errors are your UI.