Cadence Retime for ComfyUI

Motion-aware cadence normalization and editable variable retiming for ComfyUI IMAGE batches.

Cadence Retime can smooth uneven generated motion, build reusable source-frame maps, apply creative speed curves, and keep optional audio synchronized. Motion analysis runs directly on the loaded IMAGE batch. It does not require After Effects, an external video decoder, or a CSV round trip.

Features

• Linearize uneven camera or subject motion with in-memory optical-flow analysis.
• Preserve intentional static starts and end settles when requested.
• Build retimes from presets, a source-time graph, or an editable speed graph.
• Sample exact frames from the untouched source and fractional frames from an optional dense RIFE/GMFSS interpolation batch.
• Retime audio with the same picture map using synchronized varispeed.
• Import legacy frame maps from text, JSON, CSV content, or a local CSV path.
• Run without additional Python packages beyond ComfyUI itself.

Nodes

Node	Purpose
Cadence: Normalize Motion	Analyze and normalize a shot in one node.
Cadence: Analyze Motion	Build an inspectable and reusable motion map.
Cadence: Apply Frame Map	Apply a legacy or externally supplied frame map.
Cadence: Retime Preset	Create a map from common timing presets.
Cadence: Source-Time Curve	Draw output-time to source-time mapping directly.
Cadence: Speed Curve	Draw playback speed over the duration of the shot.
Cadence: Apply Retime	Apply any Cadence time map to an IMAGE batch.
Cadence: Apply Retime + Audio	Apply a map to picture and optional audio.

The nodes appear under Cadence Retime, with Analysis, Maps, and Apply subcategories.

Install

1. Place this repository in:

   ComfyUI/custom_nodes/ComfyUI-Cadence-Retime
   

2. Restart ComfyUI.

3. Search for Cadence: in the node menu.

No separate requirements install is needed.

Normalize a shot

Use Cadence: Normalize Motion for the compact workflow:

1. Load the untouched video as an IMAGE batch.
2. Connect it directly to source_images.
3. Optionally send the same source through RIFE or GMFSS at x4 and connect the result to motion_interpolated_images.
4. Send retimed_images to Video Combine and connect output_fps to its frame rate input.

Recommended first pass:

• source_fps: source clip frame rate
• output_fps: delivery frame rate
• strength: standard
• protect_static_edges: off for full-move linearization; enable it only for an intentional static start or end settle
• minimum_static_frames: 3
• analysis_resolution: 256
• sampling_mode: auto
• motion_multiplier: 0 for automatic detection, or 4 for an explicit x4 RIFE/GMFSS branch

x4 interpolation is the normal working setting. Try x8 only when difficult parallax, occlusion, or a large correction still shows temporal stepping.

Inspect or reuse the analysis

Use the two-node version when the timing map needs to be inspected, saved, or overridden:

1. Connect the untouched IMAGE batch to Cadence: Analyze Motion.
2. Connect cadence_map to Cadence: Apply Retime.
3. Optionally connect an x4/x8 RIFE or GMFSS batch to motion_interpolated_images.
4. Connect retimed_images and output_fps to Video Combine.

Cadence: Analyze Motion also returns CSV text for diagnostics and interchange. The CSV is optional in a normal ComfyUI graph.

Analysis behavior

• Motion is measured from the loaded IMAGE batch instead of reopening the source file.
• Dense optical flow estimates screen displacement and builds a monotonic, fractional source-frame map.
• gentle, standard, and strong progressively approach constant screen travel.
• Protected static edges must last at least minimum_static_frames; brief accidental holds remain part of the analyzed move.
• preserve_start_seconds and preserve_end_seconds add explicit protected regions.
• analysis_resolution affects analysis cost only, not output resolution.

This is apparent-motion normalization, not semantic shot understanding. Cuts, large independent foreground motion, or unrelated moving subjects can influence the measured curve.

Build a creative retime

All three map builders connect to either Cadence: Apply Retime or Cadence: Apply Retime + Audio.

Retime Preset

Cadence: Retime Preset provides linear, ease-in, ease-out, ease-in/out, and slow-middle starting curves.

Source-Time Curve

Cadence: Source-Time Curve directly maps output progress on the horizontal axis to source progress on the vertical axis. Click to add points, drag to shape the move, and double-click or right-click to remove interior points. The curve remains monotonic so it cannot accidentally reverse the shot.

Speed Curve

Cadence: Speed Curve combines presets with an editable playback-speed graph:

• Horizontal axis: progress through the shot.
• Vertical axis: playback speed from 0.25x to 4x on a logarithmic scale.
• Center line: 1x speed.
• Above center: faster.
• Below center: slower.

With output_frames set to 0, the speed curve determines the resulting duration. Enable lock_duration to preserve source duration while retaining the relative speed changes, or set output_frames explicitly.

Sampling modes

• auto: use the connected dense interpolation batch, otherwise blend source frames linearly.
• optical-flow batch: require and sample a connected dense RIFE/GMFSS batch.
• linear frame blend: blend adjacent untouched source frames.
• nearest frame: select whole source frames without interpolation.

When a dense interpolation batch is connected, exact whole-frame positions come from the untouched source batch. Only fractional positions use the dense batch. This keeps unretimed frames sharp while providing extra temporal samples where the map needs them.

Keep audio synchronized

Use Cadence: Apply Retime + Audio when the loaded clip includes audio:

1. Connect the source IMAGE batch to source_images.
2. Connect a Cadence map to time_map.
3. Connect the Load Video audio output to audio.
4. Optionally connect an x4/x8 interpolation batch.
5. Connect retimed_images, output_fps, and retimed_audio to Video Combine.

retime (varispeed) follows the picture map and changes pitch with speed. passthrough leaves the original audio untouched.

Legacy frame maps

Cadence: Apply Frame Map accepts comma- or newline-delimited frame positions, JSON, pasted Cadence CSV data, a local CSV path, a direct FL Load CSV connection, or a CADENCE_MAP. The legacy internal workflow ID is retained so existing saved graphs continue to load.

Development

Run the test suite from the repository root:

python -m unittest discover -s tests -v

License

MIT. See LICENSE.