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
/**
* three.ws — LipSyncAnalyser unit tests
*
* Exercises the spectral analyser without WebAudio by injecting a fake
* AnalyserNode whose `getByteFrequencyData()` writes a deterministic
* frequency spectrum. The module under test does an `instanceof AnalyserNode`
* check, so we shim a real constructor on globalThis before importing.
*/
import { describe, it, expect, beforeAll } from 'vitest';
// Shim AnalyserNode globally before the SUT is imported. The SUT uses
// `audioSource instanceof AnalyserNode` to route to its analyser branch,
// so the stub must extend this class.
class FakeAnalyserNode {
constructor({ binCount = 128, sampleRate = 44100 } = {}) {
this.fftSize = binCount * 2;
this.frequencyBinCount = binCount;
this.smoothingTimeConstant = 0.7;
this.context = { sampleRate };
this._spectrum = new Uint8Array(binCount);
}
setSpectrum(buf) {
this._spectrum.set(buf.subarray(0, this._spectrum.length));
}
fillRange(start, end, value) {
for (let i = start; i < Math.min(end, this._spectrum.length); i++) {
this._spectrum[i] = value;
}
}
clear() {
this._spectrum.fill(0);
}
getByteFrequencyData(out) {
out.set(this._spectrum.subarray(0, out.length));
}
disconnect() {}
}
globalThis.AnalyserNode = FakeAnalyserNode;
let LipSyncAnalyser;
let VISEMES;
beforeAll(async () => {
const mod = await import('../../src/lip-sync-analyser.js');
LipSyncAnalyser = mod.LipSyncAnalyser;
VISEMES = mod.VISEMES;
});
const EXPECTED_VISEMES = [
'viseme_aa', 'viseme_O', 'viseme_E', 'viseme_I', 'viseme_nn',
'viseme_SS', 'viseme_FF', 'viseme_CH', 'viseme_PP',
];
describe('three.ws LipSyncAnalyser — constructor', () => {
it('initialises inactive with all nine viseme weights at zero', () => {
const a = new LipSyncAnalyser();
expect(a._active).toBe(false);
for (const k of EXPECTED_VISEMES) {
expect(a._out[k]).toBe(0);
}
// Sanity — the exported VISEMES list must match the 9 we contract on.
expect(VISEMES.slice().sort()).toEqual(EXPECTED_VISEMES.slice().sort());
});
it('exposes a zero amplitude before any sample()', () => {
const a = new LipSyncAnalyser();
expect(a.getAmplitude()).toBe(0);
});
});
describe('three.ws LipSyncAnalyser — sample() lifecycle', () => {
it('returns null when sample() is called before connect()', () => {
const a = new LipSyncAnalyser();
expect(a.sample()).toBeNull();
});
it('returns a viseme map with all nine keys and weights in [0,1] after connect()', () => {
const a = new LipSyncAnalyser();
const stub = new FakeAnalyserNode();
// Known pattern — linear ramp 0..255 across the bins.
for (let i = 0; i < stub.frequencyBinCount; i++) {
stub._spectrum[i] = Math.floor((i / (stub.frequencyBinCount - 1)) * 255);
}
a.connect(stub);
const out = a.sample();
expect(out).not.toBeNull();
expect(typeof out).toBe('object');
for (const k of EXPECTED_VISEMES) {
expect(out).toHaveProperty(k);
expect(out[k]).toBeGreaterThanOrEqual(0);
expect(out[k]).toBeLessThanOrEqual(1);
}
});
});
describe('three.ws LipSyncAnalyser — spectral mapping', () => {
it('decays every viseme toward zero on silence', () => {
const a = new LipSyncAnalyser();
const stub = new FakeAnalyserNode();
a.connect(stub);
// Prime the EMA with a non-zero frame, then go silent for many frames.
stub.fillRange(0, stub.frequencyBinCount, 200);
a.sample();
stub.clear();
let out;
for (let n = 0; n < 30; n++) out = a.sample();
for (const k of EXPECTED_VISEMES) {
expect(out[k]).toBeLessThan(0.1);
}
expect(a.getAmplitude()).toBeLessThan(0.1);
});
it('drives viseme_aa and viseme_O on low-band energy', () => {
const a = new LipSyncAnalyser();
const stub = new FakeAnalyserNode();
a.connect(stub);
// Concentrate energy in the low band — bins covering 0..500 Hz.
// At 44.1 kHz / fft=256, binHz ≈ 172, so lowEnd ≈ 3 bins.
// Saturate the entire low band to 255, leave the rest at 0.
stub.fillRange(0, a._lowEnd, 255);
// Drive the EMA to steady state.
let out;
for (let n = 0; n < 40; n++) out = a.sample();
expect(out.viseme_aa).toBeGreaterThan(0.3);
expect(out.viseme_O).toBeGreaterThan(0.3);
// High-band visemes must stay quiet.
expect(out.viseme_SS).toBeLessThan(out.viseme_aa);
expect(out.viseme_FF).toBeLessThan(out.viseme_aa);
});
it('drives viseme_SS and viseme_FF on high-band energy', () => {
const a = new LipSyncAnalyser();
const stub = new FakeAnalyserNode();
a.connect(stub);
// Concentrate energy in the high band — bins covering 2k..8k Hz.
stub.fillRange(a._midEnd, a._highEnd, 255);
let out;
for (let n = 0; n < 40; n++) out = a.sample();
expect(out.viseme_SS).toBeGreaterThan(0.3);
expect(out.viseme_FF).toBeGreaterThan(0.3);
// Low-band visemes must stay quiet.
expect(out.viseme_aa).toBeLessThan(out.viseme_SS);
expect(out.viseme_O).toBeLessThan(out.viseme_SS);
});
});
describe('three.ws LipSyncAnalyser — disconnect()', () => {
it('resets _active, zeroes the viseme map, and makes subsequent sample() return null', () => {
const a = new LipSyncAnalyser();
const stub = new FakeAnalyserNode();
a.connect(stub);
// Prime with energy so the output map is non-zero before disconnecting.
stub.fillRange(0, stub.frequencyBinCount, 255);
for (let n = 0; n < 10; n++) a.sample();
// At least one viseme is non-zero now.
expect(EXPECTED_VISEMES.some((k) => a._out[k] > 0)).toBe(true);
a.disconnect();
expect(a._active).toBe(false);
for (const k of EXPECTED_VISEMES) {
expect(a._out[k]).toBe(0);
}
expect(a.getAmplitude()).toBe(0);
expect(a.sample()).toBeNull();
});
});