Violinet-tech/seamless-loop-video

Seamless looping video from a still

Two stages, and keeping them separate is the whole trick:

1. make-loop.py renders motion. It does NOT try to loop.
2. The loop is closed with REAL frames (bridge take, cut point, or flow in-betweens) composed in Remotion/HyperFrames. Avoid crossfades for closing the loop; they ghost on directional motion.
3. chain.py joins several short takes into one long loop, for when a single render cannot be both long and fast (§5).

The three scripts are in scripts/. Set COMFY_URL if your ComfyUI is not on http://127.0.0.1:8188. Everything below was learned by getting it wrong first; each rule has the measurement that produced it.

python make-loop.py <image> "<prompt>" --width 544 --height 800 --length 73 --steps 8 --physics 80 --seed 11
python seamless.py  <raw.mp4> <out.mp4> --fade 20
python chain.py     <out.mp4> --fade 14 <a.mp4> <b.mp4> <c.mp4>

---

1. Getting motion at all

The first renders had no wind, no atmosphere and no walk. Every one of these was set to the motion-suppressing value:

Setting	Wrong	Right	Why
last_frame	= first_frame	omit it	Pinning the end to the opening still is an instruction to return to where it started, so the model buys the loop by refusing to move. This is the single biggest cause.
steps	4	8	The turbo LoRA is marketed as 4-step. Both published i2v graphs use 8 (euler) or 20 (res_multistep). Four is the floor for a coherent picture, not for movement.
shift_video	12.0 (node default)	6.0	Every reference workflow passes 6.
LoRA stack	turbo only	turbo + wushu_spatial_physics_v2	A spatial-physics adapter. This is what puts weight behind cloth, water and a walking figure.
prompt	"gentle", "subtle", "camera perfectly still"	active physics verbs	Asking for subtlety gets subtlety.

Measured effect of fixing all five, same source image:

                    before   after
median frame step     1.73  →  4.55     2.6x
cumulative movement    133  →   325     2.4x

Write prompts as physics, not mood. Name what moves and how: "she walks forward, her hair and dress blown by strong wind; petals tear loose and tumble spinning; the splash surges and ripples; mist rolls across the ground". Avoid "ambient", "gentle", "subtle", "slow", "camera locked" — they all cost motion.

Length, and the trap in it

--length sits on the model's 17k+5 grid (5, 22, 39, 56, 73 … 192, 243). The node snaps up silently otherwise. The model's trained range is ~124-362 frames (its own tooltip), so 73 is below what it was trained on and 192 is exactly 8.0s.

But length does not buy motion, and assuming it does is a wasted render. Same image, same prompt, same settings, only the frame count changed:

 73 frames   median frame step 4.55   cumulative movement 325
192 frames   median frame step 1.25   cumulative movement 293

Identical journey, 2.6x the time — i.e. slow motion. The model paces whatever the prompt describes across whatever duration it is given; motion-per-second x duration is roughly constant for a given prompt.

So the two levers are independent and both are needed:

• Duration comes from --length.
• Speed comes from the PROMPT having enough to do. A scene description ("wind blows, petals drift") is about three seconds of material; stretched to eight it crawls.

For a long clip that still moves, write sequential beats and say so explicitly: "she strides forward and keeps striding, never pausing; a hard gust tears through; petals rip loose and burst into a swirling cloud; the splash surges up and crashes back; the lattice flares and pulses rapidly; mist sweeps across and clears. Continuous rapid movement from first frame to last, no stillness, no slow motion."

Slow pacing is not always wrong — for a scrimmed background it can be better than frantic. Judge it per surface: heroes want speed, plates want drift.

192 frames is ~2.6x the VRAM-time of 73: 662s at 544x800 on a 12 GB RTX 3060, which held with 1.7 GB spare. Drop resolution rather than length to fit.

Models this uses (all local, all must be installed in your ComfyUI)

UNET    minimax_h3_fl_or_ref2va_w4a8_pruned_a.safetensors
LoRA 1  minimax_h3_fl2v_turbo_4step_v1.2_768p.safetensors      1.0
LoRA 2  Minimax H3\wushu_spatial_physics_v2_1000_pruned.safetensors  0.8
CLIP    minimaxH3Fl2vaPruned_fl2vaPrunedFp8Scaled_txt.safetensors   type "minimax"
VAE     minimax_h3_video_vae_fp16.safetensors

Do not reach for qwen3vl_32b_minimax_h3_nvfp4_awq as the text encoder on a 12 GB card; the fp8 pruned one above is what fits. ~5.5 min per 73-frame clip at 608x896 on an RTX 3060.

---

2. Closing the loop: prefer real frames over a crossfade

A fade or cross-dissolve ghosts anything with directional motion (a walking figure, drifting fog). seamless.py and chain.py do crossfade, so treat them as the quick option and build the seam from real frames when quality matters, using any compositor that gives hard cuts (Remotion, HyperFrames, ffmpeg, a video editor):

1. Bridge take (preferred). Render a second MiniMax H3 clip with first_frame = the loop clip's LAST frame and last_frame = its FIRST frame. Join A + bridge with hard cuts in Remotion or HyperFrames. The motion carries the wrap; nothing dissolves.
2. Pick a real loop point. Search the clip for a late/early frame pair that is within ~1.5x the median frame step and cut there.
3. Motion-compensated in-betweens (optical flow: RIFE/FILM, ffmpeg minterpolate mci, or Resolve Speed Warp) only when the end-to-start gap is small; over a big gap they morph.

Compose and export the final loop in Remotion or HyperFrames (hard cuts, <Loop>/looping composition), then measure the wrap as in section 3.

3. Measuring it — where every mistake was made

Three separate measurement bugs each rejected a loop that was fine. If a loop "fails", suspect the measurement before re-rendering.

Compare the seam to the clip's own frame-step distribution, not to zero and not to one sample. A seam is invisible when it is no bigger than the changes around it.

1. A single mid-clip sample is not "normal". Motion is uneven; the middle is often the quiet part. Sampling one transition there passed a clip whose wrap was genuinely its largest jump. Read every interior step in one pass: ffmpeg -vf "tblend=all_mode=difference,signalstats,metadata=print".
2. A percentile alone is harsh on a tight distribution. A seam 27% above the median can sit at the 98th percentile and still be smaller than the largest ordinary step. Judge on both: inside the observed range AND within ~1.5x the median.
3. Measure a LOSSLESS encode, not the shipped file. The output's frame 0 is an I-frame; its neighbours are P-frames, so differencing against it measures two encodings on top of two pictures.

   same loop, lossless : seam 2.99
   same loop, CRF 26   : seam 4.65    <- 1.66 of pure codec
   

   The tell: the number does not move when you trim the clip. Content- independent constant = artifact, not content.

seamless.py now builds a lossless twin purely to measure and ships the CRF 26 file. Its verdict line is the thing to read.

metadata=print needs -v info

It logs at info level, so -v error silently removes the only output the measurement reads and every number comes back nan.

---

4. When the wrap genuinely fails

SEAM VISIBLE after the lossless fix means directional motion — a figure walking one way, fog accumulating — and a longer --fade will not fix it. Verified: fades of 16, 24 and 30 all left the seam unchanged.

In order of preference:

1. Shorten the loop — but only after checking it is not the codec (above). Fewer source frames means less accumulated drift. Note this trades against the length rule: a shorter loop makes the fade more frequent, so prefer re-prompting over trimming when the clip is already under ~6s.
2. Re-prompt for cyclical rather than one-way motion — gusting wind, swirling petals, rippling water, pulsing light. Drop the walk and the building fog.
3. Render longer (243 frames) so there is more material to find a loop in, and a wider fade costs proportionally less of it.

---

5. Long AND fast: chain short takes

One render cannot give you both — see the length section above. chain.py gets there by joining several short fast takes, crossfading each clip's tail into the next clip's head, cyclically, so the wrap closes on consecutive frames of one clip.

segment[i] = crossfade(clip[i-1] tail K, clip[i] head K) ++ clip[i][K : F-K]
output length = N x (F - K)

Three 73-frame takes at a 14-frame fade give ~7.4s. Measured, three takes of the same image at seeds 7 / 11 / 23 / 41 all land within median 4.36-5.04, so the takes are interchangeable in energy while differing in detail.

This is also the real fix for a loop that feels tiring. A 2.2s loop repeats 27 times a minute; what the eye catches is not the seam — that measures clean — but the REPETITION of the same footage. Different takes remove the repetition; the joins become dissolves between genuinely different content, which read as transitions rather than stutters.

All clips must be the same size. blend fails with Error reinitializing filters!, naming neither the cause nor the file. chain.py checks up front and refuses rather than rescaling — mismatched sizes mean a mistake about which renders belong together, and stretching one hides it.

Resolution costs nothing in motion: 544x800 takes measured the same as 608x896 ones, so render the chain small and spend the budget on takes.

6. Loops you did not make

Check them. An asset already in use with loop on it is not necessarily a loop: a hand-and-flowers background carried into one project measured a wrap of 29.95 against a median step of 4.65 — a 6.4x jump that had been cutting visibly wherever it was used. seamless.py fixed it to 4.98 without a re-render, because crossfading needs only the file.

7. Putting it on a page

<video class="plate" id="plateLoop" autoplay loop muted playsinline
       preload="auto" poster="assets/still.webp" aria-hidden="true">
  <source src="assets/loop.mp4" type="video/mp4">
</video>

• autoplay alone is not enough. It is silently refused inside an iframe without an autoplay grant, and before the page has user activation. The rejection leaves the poster up, which looks like a still nobody animated. Retry on canplay and on the first pointerdown/keydown/scroll/ touchstart, and pause under prefers-reduced-motion.
• poster carries the sharp still so a blocked autoplay or a slow connection shows the original art rather than black.
• Remove any CSS drift/ken-burns from the same element. Two competing motions, and the transform amplifies upscale softness.
• A 600px-wide clip covering a 1920 viewport is a ~3x upscale and visibly softer than the still. Acceptable under a scrim; for a crisp full-width header render at ~900px+ with 20 steps and res_multistep.

Budget: ~500 KB per 2.2s clip at CRF 26.