IAMCCS_Ltx2HelperModules Keyframe Timeline

Every long video model has a drift problem: keep extending, and the character slowly stops being your character, the color wanders, the camera forgets where it was. The fix the community settled on is refresh - periodically re-anchoring the generation onto reference frames so it can't wander too far. The question is when. Ltx2HelperModules KeyframeTimeline is the scheduling node: it decides, for each segment of an LTX-2 project, whether this segment needs a refresh, and what kind.

It's pure decision-making - no pixels are touched here. It reads the planner_payload to know where the current segment sits in the timeline, applies your refresh rules, and hands a keyframe_payload to RefreshPolicy, which turns the decision into concrete numbers for the extension nodes.

How it works

Three kinds of refresh get scheduled, and this node figures out which apply to the current segment:

• Keyframe-triggered - you provide keyframe_positions (a list in global_frames, global_seconds, or global_ratio), which get converted to the segment's local frames. Positions too close to the segment head (protected_head_frames, default 9) or too close together (min_keyframe_spacing_frames) are skipped.
• Periodic - refresh_interval_segments (default 2) refreshes every N segments, on top of any explicit keyframes.
• Reanchor cadence - reanchor_every_segments (default 3) marks a segment as a full reanchor (stronger, FLF-based refresh) rather than a lighter continuity refresh.

The refresh_mode_policy decides the style: auto (default) picks based on the situation - reanchor segments get flf_blend, otherwise tail_refresh or anchor_only; or force anchor_only, tail_refresh, flf_blend, or disabled. prefer_tail_refresh (default true) biases auto toward refreshing the tail region, which is cheaper and usually sufficient. settling_frames_default is how many frames at the tail get left for the refresh to work with.

The inputs and outputs that matter

For most projects you set keyframe_positions_mode + keyframe_positions (if you have specific beats to lock), and leave the interval/cadence defaults alone. The outputs you'll actually use:

• has_refresh - BOOLEAN, "this segment needs a refresh."
• is_reanchor_segment - BOOLEAN, "this is a full reanchor, not a light refresh."
• recommended_refresh_mode - STRING telling RefreshPolicy what style to use.
• protected_head_frames_out and preferred_tail_start - the actual frame indices for the refresh region.

Plus keyframe_payload, contract, linx, and report.

Installing it

Ships in IAMCCS-nodes under IAMCCS/Ltx2 Helper Modules. Manager → "IAMCCS" → install, or:

cd ComfyUI/custom_nodes
git clone https://github.com/IAMCCS/IAMCCS-nodes.git

Restart ComfyUI. No models, no extra dependencies.

Common issues

The most common mistake is treating keyframes as absolute guarantees: the node silently drops keyframes that land inside the protected head or too close to another keyframe (that's the spacing rules doing their job - you don't want a refresh slamming in during the first 9 frames). If a keyframe you set never fires, check min_keyframe_spacing_frames and protected_head_frames. Second: on the very first segment (segment_index 0) both periodic and reanchor logic are skipped by design - the first clip is your anchor; it can't reanchor to itself. And remember the output is advice, not action: KeyframeTimeline recommends, RefreshPolicy decides the strength, and ReanchorLatent/Continuity actually execute. Wiring its output straight into a sampler does nothing.