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.
JavaScript 3d-generationai-agentsanimationavatardigital-humangenerative-aiglbgltfimage-to-3dllmmcpmcp-servermodel-context-protocolsolanatext-to-3dthreejsweb-componentswebglwebxrx402
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.jsindex 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.mdindex 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 sameway 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 thecontinuity test is. Compared on local rotations, a clip whose joints are 2.9 cm apartdiff --git a/tests/motion-seed.test.js b/tests/motion-seed.test.jsindex 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);