Skip to content

Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.

fix(motion): pick the blend length that actually closes the seam instead of giving up

nirholasdcb8799c57d9
diff --git a/api/_lib/motion-seed.js b/api/_lib/motion-seed.js
index 55548b209..0578e1e1f 100644
--- a/api/_lib/motion-seed.js
+++ b/api/_lib/motion-seed.js
@@ -802,9 +802,12 @@ export const LOOP_SEAM = Object.freeze({
// Never cut away more than this fraction of the clip hunting for a cycle: a
// clip trimmed to a third of its length is a different clip.
MAX_TRIM_FRACTION: 0.35,
- // Frames blended back toward the start. Long enough to hide the correction,
- // short enough not to smear the motion.
- BLEND_FRAMES: 8,
+ // Frames blended back toward the start, tried shortest first. A short blend
+ // keeps the motion crisp; a long one spreads a big correction over enough
+ // frames that it does not read as a pop. A clip with a wide seam needs the
+ // longer end, and the alternative to accepting some smear is rejecting the
+ // clip outright.
+ BLEND_LADDER: Object.freeze([8, 16, 24, 36, 48]),
// A seam this small is already invisible; authored loops sit at 0.000.
TARGET: 0.02,
// A trim must beat the untrimmed seam by at least this much to be worth
@@ -831,15 +834,17 @@ export const LOOP_SEAM = Object.freeze({
* work with is returned unchanged, so this is always safe to call.
*/
export function closeLoopSeam(clip, opts = {}) {
- const blendFrames = opts.blendFrames ?? LOOP_SEAM.BLEND_FRAMES;
+ const ladder = opts.blendFrames ? [opts.blendFrames] : LOOP_SEAM.BLEND_LADDER;
const maxTrim = opts.maxTrimFraction ?? LOOP_SEAM.MAX_TRIM_FRACTION;
const frames = frameCount(clip);
- if (frames < blendFrames * 3) return { clip, trimmedFrames: 0, seamBefore: 0, seamAfter: 0 };
+ const shortest = ladder[0];
+ if (frames < shortest * 3) return { clip, trimmedFrames: 0, seamBefore: 0, seamAfter: 0 };
const seamBefore = seamDistanceBetween(clip, 0, frames - 1);
+ const original = worldMotionMetrics(clip);
// 1. Find the best cycle end in the tail.
- const earliest = Math.max(blendFrames * 2, Math.floor(frames * (1 - maxTrim)));
+ const earliest = Math.max(shortest * 2, Math.floor(frames * (1 - maxTrim)));
let bestEnd = frames - 1;
let bestDistance = seamBefore;
for (let k = earliest; k < frames; k += 1) {
@@ -854,8 +859,49 @@ export function closeLoopSeam(clip, opts = {}) {
bestEnd = frames - 1;
}
- // 2. Rebuild the clip up to that frame, blending the tail back to the start.
+ // 2. Blend the tail back onto the opening pose, shortest blend first, taking
+ // the first one that closes the seam without costing more continuity than
+ // the gate allows. Spreading a wide correction over more frames is what
+ // keeps it from reading as a pop.
const keep = bestEnd + 1;
+ const fps = frames > 1 ? (frames - 1) / Math.max(clip.duration, 1e-6) : 30;
+ let fallback = null;
+
+ for (const blendFrames of ladder) {
+ const closed = rebuildWithBlend(clip, keep, blendFrames, fps);
+ const after = worldMotionMetrics(closed);
+ const result = {
+ clip: closed,
+ trimmedFrames: frames - keep,
+ seamBefore,
+ seamAfter: loopSeamDistance(closed),
+ blendFrames,
+ };
+ if (after.continuity <= MOTION_GATE.MAX_WORLD_STEP_RATIO) return result;
+ // Keep the least-bad attempt in case every rung overshoots.
+ if (!fallback || after.continuity < fallback.continuity) {
+ fallback = { ...result, continuity: after.continuity };
+ }
+ }
+
+ // Every blend length cost more continuity than the gate allows. If the clip
+ // was fine before, leave it alone and say why; if it was not, the closed clip
+ // is still the better of two bad options.
+ if (original.continuity <= MOTION_GATE.MAX_WORLD_STEP_RATIO) {
+ return {
+ clip,
+ trimmedFrames: 0,
+ seamBefore,
+ seamAfter: seamBefore,
+ rejected: 'closing the seam would have cost more continuity than it bought',
+ };
+ }
+ const { continuity, ...rest } = fallback;
+ return rest;
+}
+
+/** Rebuild a clip trimmed to `keep` frames with its tail blended onto frame 0. */
+function rebuildWithBlend(clip, keep, blendFrames, fps) {
const tracks = [];
for (const track of clip.tracks ?? []) {
const stride = track.type === 'quaternion' ? 4 : 3;
@@ -868,47 +914,19 @@ export function closeLoopSeam(clip, opts = {}) {
const blend = Math.min(blendFrames, n - 1);
for (let i = 0; i < blend; i += 1) {
const index = n - blend + i;
- // Ramp to a full match on the final frame.
const t = (i + 1) / blend;
const at = index * stride;
if (track.type === 'quaternion') {
const blended = slerp(values.slice(at, at + 4), first, t);
for (let c = 0; c < 4; c += 1) values[at + c] = blended[c];
} else {
- // Height and depth-of-stance are matched; horizontal travel is kept,
- // so a travelling loop still covers ground.
+ // Height is matched; horizontal travel is kept, so a travelling loop
+ // still covers ground.
values[at + 1] += (first[1] - values[at + 1]) * t;
}
}
tracks.push({ ...track, times, values });
}
-
- const fps = frames > 1 ? (frames - 1) / Math.max(clip.duration, 1e-6) : 30;
- const closed = { ...clip, duration: (keep - 1) / fps, tracks };
-
- // Self-verify. Closing a seam moves joints, and on a clip that barely needed
- // it the correction can cost more than the seam did. If the result is less
- // continuous than the gate allows while the original was fine, keep the
- // original and say so rather than publishing a clip this made worse.
- const after = worldMotionMetrics(closed);
- const original = worldMotionMetrics(clip);
- if (
- after.continuity > MOTION_GATE.MAX_WORLD_STEP_RATIO &&
- original.continuity <= MOTION_GATE.MAX_WORLD_STEP_RATIO
- ) {
- return {
- clip,
- trimmedFrames: 0,
- seamBefore,
- seamAfter: seamBefore,
- rejected: 'closing the seam would have cost more continuity than it bought',
- };
- }
-
- return {
- clip: closed,
- trimmedFrames: frames - keep,
- seamBefore,
- seamAfter: loopSeamDistance(closed),
- };
+ return { ...clip, duration: (keep - 1) / fps, tracks };
}
+
diff --git a/docs/animation-seeding.md b/docs/animation-seeding.md
index 48604dff1..31002eddf 100644
--- a/docs/animation-seeding.md
+++ b/docs/animation-seeding.md
@@ -104,12 +104,20 @@ as-is, every one of those clips would visibly pop once a cycle.
holds at frame 0, so the seam closes exactly. The root's height is matched the same
way while its horizontal travel is preserved, so a travelling walk still travels.
-It **self-verifies**: closing a seam moves joints, and on a clip that barely needed it
-the correction can cost more than the seam did. If the result is less continuous than
-the gate allows while the original was fine, the original is returned untouched.
-
-Measured on four real clips: seams of 0.029, 0.171, 0.251 and 0.267 m all close to
-**0.000**, and all four pass the gate as loops.
+The blend length is **adaptive**. Blending is tried shortest first (8 frames, then 16,
+24, 36, 48) and the first length that closes the seam without costing more continuity
+than the gate allows is taken. A short blend keeps the motion crisp; a wide seam needs
+a longer one, because spreading a big correction over more frames is exactly what stops
+it reading as a pop. A fixed 8-frame blend left a 0.378 m seam on a sneaking walk and
+the clip was rejected; at 36 frames the same clip closes to 0.000 and passes.
+
+It **self-verifies**: if every blend length still costs more continuity than the gate
+allows and the clip was fine to begin with, the original is returned untouched with a
+reason attached, rather than publishing something this made worse.
+
+Measured on seven real clips, seams from 0.029 m to 0.378 m all close to **0.000** and
+all seven pass the gate as loops. On one live batch this took the accepted share of
+loop prompts from 3 of 6 to 6 of 6.
Seam distance is measured in world space, hips-relative, for the same reason the
continuity test is. Compared on local rotations, a clip whose joints are 2.9 cm apart
diff --git a/tests/motion-seed.test.js b/tests/motion-seed.test.js
index 9b708e333..236e09077 100644
--- a/tests/motion-seed.test.js
+++ b/tests/motion-seed.test.js
@@ -400,6 +400,32 @@ describe('loop seams', () => {
expect(verdict.reasons.some((r) => r.startsWith('world_discontinuity'))).toBe(false);
});
+ it('spreads a wider correction over more frames rather than giving up', () => {
+ // A short blend cannot absorb a wide seam without popping, so the ladder
+ // should reach for a longer one instead of returning the clip unclosed.
+ const wide = buildClip({
+ frames: 150,
+ mutate: (c) => {
+ for (const track of c.tracks) {
+ if (track.type !== 'quaternion') continue;
+ const n = track.values.length / 4;
+ for (let i = Math.floor(n * 0.5); i < n; i += 1) {
+ const q = quatX(1.4);
+ for (let k = 0; k < 4; k += 1) track.values[i * 4 + k] = q[k];
+ }
+ }
+ },
+ });
+ const result = closeLoopSeam(wide);
+ expect(result.seamAfter).toBeLessThanOrEqual(LOOP_SEAM.TARGET);
+ expect(LOOP_SEAM.BLEND_LADDER).toContain(result.blendFrames);
+ });
+
+ it('tries the shortest blend first, so a small seam is not over-smoothed', () => {
+ const result = closeLoopSeam(openSeam());
+ expect(result.blendFrames).toBe(LOOP_SEAM.BLEND_LADDER[0]);
+ });
+
it('is safe to call on a clip too short to work with', () => {
const tiny = { name: 't', duration: 0.1, tracks: [], uuid: 'u', blendMode: 0 };
expect(closeLoopSeam(tiny).clip).toBe(tiny);