@elizaos/plugin-local-inference 2.0.3-beta.2 → 2.0.3-beta.4

package/src/services/voice/e2e-harness.security-echo.test.ts

@@ -0,0 +1,103 @@
+import { describe, expect, it } from "vitest";
+import {
+	type EchoRejectionSample,
+	type OwnerSecuritySample,
+	scoreEchoRejection,
+	scoreOwnerSecurity,
+} from "./e2e-harness";
+
+// #9147 — self-echo rejection ("did the agent talk to itself?") and owner-vs-
+// impostor gating are two of the three heavy voice cases the issue calls out as
+// having scorers that "do not run anywhere that gates merges". These scorers are
+// pure + GGUF-independent, so pin their decision math here so the gate runs.
+
+const echo = (
+	isAgentEcho: boolean,
+	responded: boolean,
+): EchoRejectionSample => ({
+	isAgentEcho,
+	responded,
+});
+
+describe("scoreEchoRejection (#9147)", () => {
+	it("passes when every agent-echo turn is suppressed", () => {
+		const r = scoreEchoRejection([echo(true, false), echo(true, false)]);
+		expect(r.total).toBe(2);
+		expect(r.rejected).toBe(2);
+		expect(r.rejectionRate).toBe(1);
+		expect(r.passed).toBe(true);
+	});
+
+	it("scores ONLY agent-echo turns (real turns are ignored here)", () => {
+		// 2 echo (one leaked) + 2 real turns the agent answered (must not count).
+		const r = scoreEchoRejection([
+			echo(true, false),
+			echo(true, true),
+			echo(false, true),
+			echo(false, true),
+		]);
+		expect(r.total).toBe(2);
+		expect(r.rejected).toBe(1);
+		expect(r.rejectionRate).toBe(0.5);
+		expect(r.passed).toBe(false); // 0.5 < default 0.9 floor
+	});
+
+	it("fails closed when there are no echo samples to prove rejection", () => {
+		const r = scoreEchoRejection([echo(false, true)]);
+		expect(r.total).toBe(0);
+		expect(r.rejectionRate).toBe(0);
+		expect(r.passed).toBe(false);
+	});
+
+	it("honors a custom minRejectionRate floor", () => {
+		const samples = [echo(true, false), echo(true, false), echo(true, true)];
+		expect(scoreEchoRejection(samples).passed).toBe(false); // 0.6667 < 0.9
+		expect(scoreEchoRejection(samples, { minRejectionRate: 0.6 }).passed).toBe(
+			true,
+		); // 0.6667 >= 0.6
+	});
+});
+
+const sec = (
+	predictedOwner: boolean,
+	expectedOwner: boolean,
+): OwnerSecuritySample => ({
+	predictedOwner,
+	expectedOwner,
+});
+
+describe("scoreOwnerSecurity (#9147)", () => {
+	it("passes only when accuracy is high AND no impostor is accepted", () => {
+		const r = scoreOwnerSecurity([sec(true, true), sec(false, false)]);
+		expect(r.accuracy).toBe(1);
+		expect(r.impostorAcceptRate).toBe(0);
+		expect(r.passed).toBe(true);
+	});
+
+	it("FAILS on a single impostor-accept even at high overall accuracy", () => {
+		// 9 correct + 1 stranger let in as owner → accuracy 0.9 but a real breach.
+		const samples = [
+			...Array.from({ length: 9 }, () => sec(true, true)),
+			sec(true, false),
+		];
+		const r = scoreOwnerSecurity(samples);
+		expect(r.accuracy).toBe(0.9);
+		expect(r.impostorAcceptRate).toBeGreaterThan(0);
+		expect(r.passed).toBe(false); // default maxImpostorAcceptRate is 0
+	});
+
+	it("treats rejecting the real owner as friction, not a security failure", () => {
+		// owner rejected once (friction) but no impostor accepted.
+		const r = scoreOwnerSecurity(
+			[sec(false, true), sec(false, false), sec(false, false)],
+			{ minAccuracy: 0.6 },
+		);
+		expect(r.ownerRejectRate).toBe(1);
+		expect(r.impostorAcceptRate).toBe(0);
+		expect(r.passed).toBe(true); // 2/3 accuracy >= 0.6 floor, no impostor in
+	});
+
+	it("fails closed on an empty sample set", () => {
+		expect(scoreOwnerSecurity([]).passed).toBe(false);
+	});
+});

package/src/services/voice/e2e-harness.test.ts

@@ -44,10 +44,10 @@ describe("voice E2E harness artifact validation", () => {
 		expect(() =>
 			assertRequiredVoiceArtifacts(
 				[
-					{ kind: "bundle-root", path: "/models/eliza-1-0_8b.bundle" },
+					{ kind: "bundle-root", path: "/models/eliza-1-2b.bundle" },
 					{
 						kind: "asr-model",
-						path: "/models/eliza-1-0_8b.bundle/asr/eliza-1-asr.gguf",
+						path: "/models/eliza-1-2b.bundle/asr/eliza-1-asr.gguf",
 						magic: "GGUF",
 					},
 				],

package/src/services/voice/e2e-harness.ts

@@ -13,6 +13,11 @@
 export { normalizeWerText, wordErrorRate } from "@elizaos/shared/voice-wer";
 
 import { normalizeWerText, wordErrorRate } from "@elizaos/shared/voice-wer";
+import {
+	computeDiarizationErrorRate,
+	type DiarizationSegment,
+} from "./diarization-error-rate";
+import { percentile, round1, round4 } from "./metric-math";
 
 export type VoiceE2eHarnessErrorCode =
 	| "missing-artifact"
@@ -572,6 +577,66 @@ export function scoreDiarization(
 	};
 }
 
+/** One scored turn for timeline DER: its speech span + predicted/true speaker. */
+export interface DiarizationTurnSample {
+	/** Ground-truth speaker label (the diarization reference). */
+	expectedLabel: string;
+	/** Predicted speaker label from a real attributor, or null when it missed. */
+	predictedLabel: string | null;
+	/** Speech-region start of this turn (ms into the stream). */
+	startMs: number;
+	/** Speech-region end of this turn (ms; must be ≥ startMs). */
+	endMs: number;
+}
+
+/**
+ * Score diarization with the frame-based, label-agnostic {@link
+ * computeDiarizationErrorRate} (#9147) rather than a per-turn string compare.
+ * The predicted labels are an arbitrary cluster-id space (the attributor never
+ * knows the ground-truth names) — DER finds the optimal cluster→speaker mapping,
+ * so a correct partition scores 0 no matter how clusters are named, and a merged
+ * or swapped speaker shows up as real error. `confusions`/`misses` are turn-level
+ * tallies derived from that optimal mapping, for the report.
+ */
+export function scoreDiarizationTimeline(
+	turns: ReadonlyArray<DiarizationTurnSample>,
+	opts: { maxDer?: number } = {},
+): DiarizationResult {
+	const maxDer = opts.maxDer ?? 0.2;
+	const reference: DiarizationSegment[] = turns.map((t) => ({
+		speaker: t.expectedLabel,
+		startMs: t.startMs,
+		endMs: t.endMs,
+	}));
+	const hypothesis: DiarizationSegment[] = turns
+		.filter((t) => t.predictedLabel !== null)
+		.map((t) => ({
+			speaker: t.predictedLabel as string,
+			startMs: t.startMs,
+			endMs: t.endMs,
+		}));
+	const result = computeDiarizationErrorRate(reference, hypothesis);
+	// Turn-level tallies under the optimal mapping (the report's headline is `der`).
+	let confusions = 0;
+	let misses = 0;
+	for (const t of turns) {
+		if (t.predictedLabel === null) {
+			misses += 1;
+		} else if (result.mapping[t.predictedLabel] !== t.expectedLabel) {
+			confusions += 1;
+		}
+	}
+	return {
+		kind: "diarization",
+		total: turns.length,
+		der: round4(result.der),
+		confusions,
+		misses,
+		maxDer,
+		passed: turns.length > 0 && result.der <= maxDer,
+	};
+}
+
 // ── Entity extraction: inferred name/entity match (precision / recall / F1) ──
 
 export interface EntityExtractionInput {
@@ -655,13 +720,113 @@ export function scoreVoiceEntityMatch(
 	};
 }
 
-/** Nearest-rank percentile over a sample (null when empty). */
-function percentile(values: ReadonlyArray<number>, p: number): number | null {
-	const finite = values.filter((v) => Number.isFinite(v));
-	if (finite.length === 0) return null;
-	const sorted = [...finite].sort((a, b) => a - b);
-	const rank = Math.ceil((p / 100) * sorted.length);
-	return round1(sorted[Math.min(sorted.length - 1, Math.max(0, rank - 1))]);
+// ── Echo / self-voice rejection: the agent's own TTS must not be a user turn ─
+
+export interface EchoRejectionSample {
+	/** Ground truth: this turn is the agent's own TTS echoed back through the mic. */
+	isAgentEcho: boolean;
+	/** The agent responded to (i.e. failed to suppress) this turn. */
+	responded: boolean;
+}
+
+export interface EchoRejectionResult {
+	kind: "echo-rejection";
+	/** Number of agent-echo turns scored. */
+	total: number;
+	/** Echo turns correctly suppressed (no response). */
+	rejected: number;
+	rejectionRate: number;
+	minRejectionRate: number;
+	passed: boolean;
+}
+
+/**
+ * Score self-echo rejection over the agent-echo turns only: each must be
+ * suppressed (no response). Real turns are scored by {@link scoreRespondDecision}
+ * — this isolates "did the agent talk to itself?".
+ */
+export function scoreEchoRejection(
+	samples: ReadonlyArray<EchoRejectionSample>,
+	opts: { minRejectionRate?: number } = {},
+): EchoRejectionResult {
+	const minRejectionRate = opts.minRejectionRate ?? 0.9;
+	const echo = samples.filter((s) => s.isAgentEcho);
+	const total = echo.length;
+	let rejected = 0;
+	for (const s of echo) if (!s.responded) rejected += 1;
+	const rejectionRate = total > 0 ? rejected / total : 0;
+	return {
+		kind: "echo-rejection",
+		total,
+		rejected,
+		rejectionRate: round4(rejectionRate),
+		minRejectionRate,
+		passed: total > 0 && rejectionRate >= minRejectionRate,
+	};
+}
+
+// ── Owner security: owner vs. intruder gating (never accept an impostor) ──────
+
+export interface OwnerSecuritySample {
+	/** The system judged this turn to be the device owner. */
+	predictedOwner: boolean;
+	/** Ground truth: this turn IS the owner. */
+	expectedOwner: boolean;
+}
+
+export interface OwnerSecurityResult {
+	kind: "owner-security";
+	total: number;
+	accuracy: number;
+	/** Accepted a non-owner AS the owner (the dangerous false-accept). */
+	impostorAcceptRate: number;
+	/** Rejected the real owner (a friction false-reject). */
+	ownerRejectRate: number;
+	minAccuracy: number;
+	maxImpostorAcceptRate: number;
+	passed: boolean;
+}
+
+/**
+ * Score owner-vs-intruder gating. Passing requires both high overall accuracy
+ * AND an impostor-accept rate at/below the (strict, default 0) ceiling —
+ * letting a stranger in is the failure mode that matters for security, so it is
+ * gated separately from plain accuracy.
+ */
+export function scoreOwnerSecurity(
+	samples: ReadonlyArray<OwnerSecuritySample>,
+	opts: { minAccuracy?: number; maxImpostorAcceptRate?: number } = {},
+): OwnerSecurityResult {
+	const minAccuracy = opts.minAccuracy ?? 0.9;
+	const maxImpostorAcceptRate = opts.maxImpostorAcceptRate ?? 0;
+	const total = samples.length;
+	let correct = 0;
+	let impostorAccept = 0;
+	let ownerReject = 0;
+	let owners = 0;
+	let nonOwners = 0;
+	for (const s of samples) {
+		if (s.predictedOwner === s.expectedOwner) correct += 1;
+		if (s.expectedOwner) owners += 1;
+		else nonOwners += 1;
+		if (s.predictedOwner && !s.expectedOwner) impostorAccept += 1;
+		if (!s.predictedOwner && s.expectedOwner) ownerReject += 1;
+	}
+	const accuracy = total > 0 ? correct / total : 0;
+	const impostorAcceptRate = nonOwners > 0 ? impostorAccept / nonOwners : 0;
+	return {
+		kind: "owner-security",
+		total,
+		accuracy: round4(accuracy),
+		impostorAcceptRate: round4(impostorAcceptRate),
+		ownerRejectRate: round4(owners > 0 ? ownerReject / owners : 0),
+		minAccuracy,
+		maxImpostorAcceptRate,
+		passed:
+			total > 0 &&
+			accuracy >= minAccuracy &&
+			impostorAcceptRate <= maxImpostorAcceptRate,
+	};
 }
 
 export type VoiceE2eCaseResult =
@@ -674,7 +839,9 @@ export type VoiceE2eCaseResult =
 	| RespondDecisionResult
 	| DiarizationResult
 	| EntityExtractionResult
-	| VoiceEntityMatchResult;
+	| VoiceEntityMatchResult
+	| EchoRejectionResult
+	| OwnerSecurityResult;
 
 export interface VoiceE2eSummary {
 	passed: boolean;
@@ -733,11 +900,3 @@ function missingMeasurement(name: string): VoiceE2eHarnessError {
 		{ name },
 	);
 }
-
-function round1(value: number): number {
-	return Math.round(value * 10) / 10;
-}
-
-function round4(value: number): number {
-	return Math.round(value * 10000) / 10000;
-}

package/src/services/voice/echo-delay.test.ts

@@ -0,0 +1,118 @@
+import { describe, expect, it } from "vitest";
+import {
+	DEFAULT_PLAYBACK_DELAY_MS,
+	estimateEchoDelaySamples,
+	PLATFORM_PLAYBACK_DELAY_DEFAULTS,
+	platformPlaybackDelayMs,
+	platformPlaybackDelaySamples,
+} from "./echo-delay.ts";
+
+/** Deterministic PRNG so fixtures are reproducible across runs/CI. */
+function mulberry32(seed: number): () => number {
+	let a = seed >>> 0;
+	return () => {
+		a |= 0;
+		a = (a + 0x6d2b79f5) | 0;
+		let t = Math.imul(a ^ (a >>> 15), 1 | a);
+		t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
+		return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+	};
+}
+
+function whiteNoise(n: number, amp: number, rng: () => number): Float32Array {
+	const out = new Float32Array(n);
+	for (let i = 0; i < n; i++) out[i] = (rng() * 2 - 1) * amp;
+	return out;
+}
+
+describe("estimateEchoDelaySamples (#9583)", () => {
+	it("recovers a known playback→mic delay", () => {
+		const rng = mulberry32(7);
+		const far = whiteNoise(8000, 0.5, rng);
+		const delay = 137;
+		const gain = 0.6;
+		const near = new Float32Array(far.length);
+		for (let i = delay; i < far.length; i++) {
+			near[i] = gain * far[i - delay] + (rng() * 2 - 1) * 0.01; // tiny near noise
+		}
+
+		const est = estimateEchoDelaySamples(near, far, { maxLagSamples: 400 });
+		expect(est.lagSamples).toBe(delay);
+		// Scale-invariant correlation: the 0.6 gain does not lower confidence.
+		expect(est.confidence).toBeGreaterThan(0.9);
+	});
+
+	it("recovers a zero delay (synchronous reference)", () => {
+		const rng = mulberry32(3);
+		const far = whiteNoise(8000, 0.5, rng);
+		const near = new Float32Array(far.length);
+		for (let i = 0; i < far.length; i++) near[i] = 0.7 * far[i];
+
+		const est = estimateEchoDelaySamples(near, far, { maxLagSamples: 200 });
+		expect(est.lagSamples).toBe(0);
+		expect(est.confidence).toBeGreaterThan(0.95);
+	});
+
+	it("reports low confidence when near is independent of far (no echo)", () => {
+		const far = whiteNoise(8000, 0.5, mulberry32(1));
+		const near = whiteNoise(8000, 0.5, mulberry32(2)); // independent signal
+
+		const est = estimateEchoDelaySamples(near, far, { maxLagSamples: 400 });
+		expect(est.confidence).toBeLessThan(0.3);
+	});
+
+	it("returns zero on empty input", () => {
+		expect(
+			estimateEchoDelaySamples(new Float32Array(0), new Float32Array(0)),
+		).toEqual({ lagSamples: 0, confidence: 0 });
+	});
+
+	it("honors a minLagSamples floor", () => {
+		const rng = mulberry32(9);
+		const far = whiteNoise(8000, 0.5, rng);
+		const delay = 40;
+		const near = new Float32Array(far.length);
+		for (let i = delay; i < far.length; i++) near[i] = 0.5 * far[i - delay];
+
+		// Floor above the true delay forces the search to start past it.
+		const est = estimateEchoDelaySamples(near, far, {
+			minLagSamples: 100,
+			maxLagSamples: 400,
+		});
+		expect(est.lagSamples).toBeGreaterThanOrEqual(100);
+	});
+});
+
+describe("platformPlaybackDelaySamples seed (#9583)", () => {
+	it("maps known platforms to their seed delay (ms)", () => {
+		expect(platformPlaybackDelayMs("darwin")).toBe(20);
+		expect(platformPlaybackDelayMs("ios")).toBe(25);
+		expect(platformPlaybackDelayMs("android")).toBe(45);
+		expect(platformPlaybackDelayMs("win32")).toBe(30);
+		expect(platformPlaybackDelayMs("linux")).toBe(30);
+	});
+
+	it("falls back to the default seed for an unrecognized platform", () => {
+		expect(platformPlaybackDelayMs("haiku")).toBe(DEFAULT_PLAYBACK_DELAY_MS);
+		// The table must not accidentally carry the unknown key.
+		expect("haiku" in PLATFORM_PLAYBACK_DELAY_DEFAULTS).toBe(false);
+	});
+
+	it("converts the seed to samples at 16 kHz by default", () => {
+		// 20 ms * 16000 / 1000 = 320 samples
+		expect(platformPlaybackDelaySamples("darwin")).toBe(320);
+		// unknown → 25 ms default → 400 samples
+		expect(platformPlaybackDelaySamples("unknown")).toBe(400);
+	});
+
+	it("honours a custom sample rate", () => {
+		// 30 ms * 48000 / 1000 = 1440 samples
+		expect(platformPlaybackDelaySamples("win32", 48_000)).toBe(1440);
+	});
+
+	it("never returns a negative seed", () => {
+		for (const p of ["darwin", "ios", "android", "win32", "linux", "??"]) {
+			expect(platformPlaybackDelaySamples(p)).toBeGreaterThanOrEqual(0);
+		}
+	});
+});

package/src/services/voice/echo-delay.ts

@@ -0,0 +1,135 @@
+/**
+ * Playback→mic echo-delay calibration (#9583, follow-up to #9455).
+ *
+ * The NLMS echo canceller's adaptive taps model only the room impulse response;
+ * the bulk transport delay between TTS playback and the mic capture window
+ * (audio-HAL buffering, Bluetooth, resampling, …) should be removed FIRST so the
+ * finite tap span (and the adaptation budget) isn't spent modelling pure
+ * latency. This finds that bulk lag by normalized cross-correlation of the mic
+ * (near-end) against the playback reference (far-end): the lag that maximizes
+ * correlation is the playback→mic delay, which the caller then applies as a
+ * fixed pre-alignment before the adaptive filter.
+ *
+ * Pure DSP — no FFI, no device. The per-platform default delay still needs to be
+ * tuned on hardware, but the estimator itself is deterministic and testable.
+ */
+
+export interface EchoDelayEstimate {
+	/** Best playback→mic delay in samples (far leads near by this much). */
+	lagSamples: number;
+	/** Peak normalized cross-correlation at that lag, in [0, 1]. */
+	confidence: number;
+}
+
+export interface EchoDelayOptions {
+	/** Largest lag to search, in samples. Default 4800 (300 ms @ 16 kHz). */
+	maxLagSamples?: number;
+	/** Smallest lag to search, in samples. Default 0. */
+	minLagSamples?: number;
+}
+
+/**
+ * Estimate the bulk playback→mic delay: the lag `d` (in samples) that best
+ * aligns the far-end reference into the near-end mic signal, i.e.
+ * `near[n] ≈ g · far[n - d]`. Returns that lag plus its normalized
+ * cross-correlation as a `[0, 1]` confidence.
+ *
+ * Normalized correlation is scale-invariant, so the playback gain `g` does not
+ * bias the result. A low confidence (e.g. `< 0.3`) means no detectable echo
+ * (the signals are independent) — the caller should keep its previous
+ * calibration rather than trust a spurious peak.
+ */
+export function estimateEchoDelaySamples(
+	near: Float32Array,
+	far: Float32Array,
+	options: EchoDelayOptions = {},
+): EchoDelayEstimate {
+	const maxLag = Math.max(0, Math.floor(options.maxLagSamples ?? 4800));
+	const minLag = Math.max(0, Math.floor(options.minLagSamples ?? 0));
+	const n = Math.min(near.length, far.length);
+	if (n === 0 || minLag > maxLag) {
+		return { lagSamples: 0, confidence: 0 };
+	}
+
+	// Per-lag normalized cross-correlation over the overlapping window. O((maxLag
+	// − minLag) · n) — fine for a short calibration burst (a few hundred ms of
+	// audio, run rarely, not per-frame).
+	let bestLag = minLag;
+	let bestCorr = -Infinity;
+	for (let lag = minLag; lag <= maxLag; lag++) {
+		let dot = 0;
+		let nearEnergy = 0;
+		let farEnergy = 0;
+		for (let i = lag; i < n; i++) {
+			const a = near[i];
+			const b = far[i - lag];
+			dot += a * b;
+			nearEnergy += a * a;
+			farEnergy += b * b;
+		}
+		const denom = Math.sqrt(nearEnergy * farEnergy);
+		const corr = denom > 0 ? dot / denom : 0;
+		if (corr > bestCorr) {
+			bestCorr = corr;
+			bestLag = lag;
+		}
+	}
+
+	return {
+		lagSamples: bestLag,
+		confidence: bestCorr === -Infinity ? 0 : Math.max(0, Math.min(1, bestCorr)),
+	};
+}
+
+/**
+ * Per-platform SEED playback→mic delay, in milliseconds. This is the initial
+ * pre-alignment applied *before* any echo has been observed; the adaptive
+ * {@link estimateEchoDelaySamples} cross-correlation refines it at runtime once
+ * enough playback-active audio is seen. Until then a platform-appropriate seed
+ * converges faster than starting from zero — most visibly on iOS/macOS, where
+ * the CoreAudio / AVAudioEngine transport delay is small but non-zero and a
+ * 0-sample seed leaves the first barge-in's echo un-aligned.
+ *
+ * These are conservative starting points (they still benefit from per-device
+ * tuning); the goal is only to put the adaptive filter in the right ballpark on
+ * the first turn, not to be exact.
+ */
+export const PLATFORM_PLAYBACK_DELAY_DEFAULTS: Readonly<
+	Record<string, number>
+> = {
+	/** macOS CoreAudio — low, stable hardware path. */
+	darwin: 20,
+	/** iOS AVAudioEngine (when its voice-processing IO AEC is not the source). */
+	ios: 25,
+	/** Android AudioTrack/AudioRecord — variable; a mid seed. */
+	android: 45,
+	/** Windows WASAPI shared-mode. */
+	win32: 30,
+	/** Desktop Linux ALSA/PulseAudio/PipeWire. */
+	linux: 30,
+};
+
+/** Fallback seed (ms) for an unrecognized platform id. */
+export const DEFAULT_PLAYBACK_DELAY_MS = 25;
+
+/**
+ * Seed playback→mic delay in milliseconds for a platform id (e.g.
+ * `process.platform`, or the `"ios"` / `"android"` ids the mobile shells
+ * report). Unknown ids fall back to {@link DEFAULT_PLAYBACK_DELAY_MS}.
+ */
+export function platformPlaybackDelayMs(platform: string): number {
+	return (
+		PLATFORM_PLAYBACK_DELAY_DEFAULTS[platform] ?? DEFAULT_PLAYBACK_DELAY_MS
+	);
+}
+
+/**
+ * Seed playback→mic delay in samples for a platform id. `sampleRate` defaults to
+ * the 16 kHz voice-pipeline rate.
+ */
+export function platformPlaybackDelaySamples(
+	platform: string,
+	sampleRate = 16_000,
+): number {
+	return Math.round((platformPlaybackDelayMs(platform) / 1000) * sampleRate);
+}

package/src/services/voice/echo-metrics.test.ts

@@ -0,0 +1,17 @@
+import { describe, expect, it } from "vitest";
+import { computeErle } from "./echo-metrics";
+
+describe("computeErle", () => {
+	it("returns dB and handles edge cases", () => {
+		const near = new Float32Array([1, 1, 1, 1]);
+		const halfResidual = new Float32Array([0.5, 0.5, 0.5, 0.5]);
+
+		expect(computeErle(near, halfResidual)).toBeCloseTo(6.0206, 2);
+		expect(
+			computeErle(new Float32Array([0, 0]), new Float32Array([1, 1])),
+		).toBe(0);
+		expect(
+			computeErle(new Float32Array([1, 1]), new Float32Array([0, 0])),
+		).toBe(Number.POSITIVE_INFINITY);
+	});
+});

package/src/services/voice/echo-metrics.ts

@@ -0,0 +1,20 @@
+/**
+ * Echo-return-loss-enhancement in dB: 10*log10(sum(near^2) / sum(residual^2)).
+ * Higher is better. Returns +Infinity when the residual is silent and 0 when
+ * there is no near-end energy to enhance.
+ */
+export function computeErle(
+	nearEnd: Float32Array,
+	residual: Float32Array,
+): number {
+	let nearEnergy = 0;
+	let residualEnergy = 0;
+	const len = Math.min(nearEnd.length, residual.length);
+	for (let i = 0; i < len; i++) {
+		nearEnergy += nearEnd[i] * nearEnd[i];
+		residualEnergy += residual[i] * residual[i];
+	}
+	if (nearEnergy === 0) return 0;
+	if (residualEnergy === 0) return Number.POSITIVE_INFINITY;
+	return 10 * Math.log10(nearEnergy / residualEnergy);
+}