VQ Motion Smoothness

There's a specific failure mode in AI video where every frame is sharp and the colors are great, but the motion feels like a robot doing tai chi - stiff, jittery, unnatural. PSNR won't catch it, SSIM won't catch it, even CLIP's aesthetic score will shrug. This node is built for exactly that: it measures motion smoothness, the fluidity of movement over time, with no reference video required.

You reach for it when a generated clip looks right frame-by-frame but "doesn't move right," or when you're comparing two workflows and want a number for how cinematic the motion is. It's also the natural partner to the warping-error node: warping catches objects melting, this one catches motion that's technically stable but mechanically stiff.

How it works

The core concept is jerk - the third derivative of position, i.e. how fast the acceleration is changing. Smooth, natural motion has low jerk; robotic or jittery motion spikes it. The node computes optical flow between consecutive frames with a pretrained RAFT model (~20 MB, auto-downloaded on first use), normalizes the flow by the image diagonal so the score doesn't depend on resolution, then takes the second difference of the flow to approximate jerk. The raw mean_jerk value comes out of that, and smoothness_score is a mapping of it onto a 0–1 scale where 1.0 is buttery and 0.0 is a slideshow.

Inputs and outputs

Required:

• video_frames (IMAGE) - your [T, H, W, 3] tensor. Needs at least 3 frames to compute acceleration; below that it bails out with a perfect score of 1.0 and zero jerk, which is misleading, so don't feed it stills.

No optional inputs.

Outputs:

• smoothness_score (FLOAT) - 0–1, higher is smoother. Above ~0.8 is genuinely smooth; below 0.4 you've got visible jitter.
• mean_jerk (FLOAT) - the raw jerk magnitude, lower is better. Under 0.1 is smooth, over 0.7 is erratic.
• summary (STRING) - report with an assessment ("Very smooth motion", "Robotic, unnatural motion", and so on) for a text display.

Installing

Part of ComfyUI-VideoQuality-Metrics:

cd ComfyUI/custom_nodes
git clone https://github.com/jajos12/ComfyUI-VideoQuality-Metrics
pip install -r ComfyUI-VideoQuality-Metrics/requirements.txt

Restart ComfyUI and it appears under VideoQuality/Temporal. ComfyUI Manager can install the pack too - search "VideoQuality Metrics".

Common issues

• Smoothness reads 1.0 on everything - you're feeding it fewer than 3 frames, so it returns the bail-out values. Feed a real clip.
• First run downloads RAFT weights and stalls briefly. Normal.
• Old torchvision silently uses a weaker flow estimator (Lucas-Kanade fallback), which makes the jerk numbers noisier. Keep torchvision ≥ 0.15.
• Short clips give shaky numbers. Jerk is a derivative; with only 3–4 frames there's barely any signal. The score stabilizes as clip length grows, so score longer clips for decisions that matter.