@elizaos/plugin-local-inference 2.0.0-beta.1 → 2.0.11-beta.7

package/src/services/voice/audio-frame-consumer.d.ts

@@ -0,0 +1,212 @@
+/**
+ * AudioFrameConsumer — turn the Android `audioFrame` PCM stream into live,
+ * VAD-segmented, speaker-attributed voice turns.
+ *
+ * The Android native capture path (`plugin-native-talkmode`) streams an
+ * `audioFrame` Capacitor event: base64 little-endian s16 mono PCM at 16 kHz,
+ * 20 ms per frame, plus `{ sampleRate, channels, samples, rms, timestamp,
+ * frameIndex }`. This module is the platform-agnostic consumer that subscribes
+ * to that stream (wherever the bun:ffi voice libs are present) and runs:
+ *
+ *   audioFrame (base64 LE-s16) → decode → VadDetector (turn segmentation)
+ *     → on speech-end: VoiceAttributionPipeline.attribute(turn PCM)
+ *       → handleLiveVoiceAttribution → VOICE_TURN_OBSERVED + voiceTurnSignal
+ *
+ * Design notes:
+ *  - It does NOT reinvent VAD: it drives the existing `VadDetector` state
+ *    machine (`speech-start` / `speech-pause` / `speech-end`), reusing its
+ *    Silero onset/offset/hangover logic. It buffers the turn's PCM between
+ *    `speech-start` and `speech-end`, then attributes the whole utterance.
+ *  - Every native dependency (`VadDetector`, `VoiceAttributionPipeline`, the
+ *    runtime) is INJECTED, so the consumer is fully unit-testable with fakes
+ *    and has no static import of bun:ffi. A `build*` factory in the smoke
+ *    harness wires the real ggml-backed deps.
+ *  - The decode boundary (`decodeAudioFramePcm`) is the ONLY place that knows
+ *    the wire format (base64 LE-s16). Internally everything is Float32 [-1,1].
+ *
+ * What this module does NOT do: it does not transcribe (ASR text is the
+ * separate streaming-ASR path) and it does not own the WebView→agent
+ * transport — see `android/AUDIO_FRAMES.md` and `LIVE_PIPELINE.md` for the
+ * remaining device wiring.
+ */
+import { type EmitVoiceTurnObservedArgs, type HandleLiveVoiceAttributionOptions } from "../../runtime/voice-entity-binding.js";
+import type { VoiceTurnSignal } from "./eot-classifier.js";
+import type { VoiceAttributionOutput, VoiceAttributionPipeline } from "./speaker/attribution-pipeline.js";
+import type { PcmFrame, VadEvent, VoiceInputSource } from "./types.js";
+/**
+ * The `audioFrame` event payload, mirroring `TalkModeAudioFrameEvent` in
+ * `@elizaos/capacitor-talkmode`. Re-declared structurally here so this
+ * package does not take a build dep on the Capacitor plugin.
+ */
+export interface AudioFrameEvent {
+    /** Base64-encoded little-endian signed 16-bit mono PCM for this frame. */
+    pcm16: string;
+    /** Sample rate of the captured PCM in Hz (e.g. 16000). */
+    sampleRate: number;
+    /** Channel count (always 1 — mono). */
+    channels: number;
+    /** Number of PCM samples in this frame (`pcm16` byte length / 2). */
+    samples: number;
+    /** RMS amplitude of this frame, normalized 0..1. */
+    rms: number;
+    /** Monotonic capture timestamp for this frame, ms. */
+    timestamp: number;
+    /** Running index of this frame since capture started (0-based). */
+    frameIndex: number;
+}
+/** The sample rate every voice model in this pipeline is dimensioned for. */
+export declare const AUDIO_FRAME_PIPELINE_SAMPLE_RATE = 16000;
+export declare class AudioFrameDecodeError extends Error {
+    constructor(message: string);
+}
+/**
+ * Decode an `audioFrame` payload into a Float32 [-1, 1] window. This is the
+ * single boundary that understands the base64 LE-s16 wire format.
+ *
+ * The native capture path only ever produces 16 kHz mono; this asserts that
+ * invariant rather than resampling silently (the downstream Silero/WeSpeaker
+ * graphs are 16 kHz-only — a wrong rate is a bug to surface, not paper over).
+ */
+export declare function decodeAudioFramePcm(frame: AudioFrameEvent): Float32Array;
+/**
+ * The structural slice of `VadDetector` the consumer needs. Taking the
+ * structural view (not the concrete class) keeps the consumer testable with a
+ * fake VAD and avoids pulling the optional native VAD surface into callers
+ * that only want to feed frames.
+ */
+export interface VadSegmenter {
+    /** True while a speech segment (incl. its pause hangover) is open. */
+    readonly inSpeech: boolean;
+    /** Subscribe to the authoritative VAD timeline. Returns an unsubscribe fn. */
+    onVadEvent(listener: (event: VadEvent) => void): () => void;
+    /** Feed one mic frame; resolves once its windows are processed. */
+    pushFrame(frame: PcmFrame): Promise<void>;
+    /** Flush trailing samples and finalize any open segment. */
+    flush(): Promise<void>;
+    /** Clear all state at a hard boundary. */
+    reset(): void;
+}
+/**
+ * The structural slice of `VoiceAttributionPipeline` the consumer needs.
+ */
+export interface AttributionPipelineLike {
+    attribute(req: Parameters<VoiceAttributionPipeline["attribute"]>[0]): Promise<VoiceAttributionOutput>;
+}
+/**
+ * The structural slice of `IAgentRuntime` the consumer needs:
+ * `handleLiveVoiceAttribution` calls `emitEvent`.
+ */
+export interface RuntimeEventSink {
+    emitEvent(type: unknown, payload: Record<string, unknown>): Promise<void>;
+}
+export interface AudioFrameConsumerDeps {
+    /** Turn-segmentation VAD (drives speech-start/pause/end). */
+    vad: VadSegmenter;
+    /** Diarization + speaker-attribution pipeline. */
+    pipeline: AttributionPipelineLike;
+    /** Runtime event sink for VOICE_TURN_OBSERVED. */
+    runtime: RuntimeEventSink;
+}
+export interface AudioFrameConsumerConfig {
+    /** Source metadata stamped onto every attributed turn. */
+    source?: VoiceInputSource;
+    /** Gating options forwarded to `handleLiveVoiceAttribution` per turn. */
+    attributionOptions?: HandleLiveVoiceAttributionOptions;
+    /**
+     * Hard cap on a single buffered turn, in seconds. A speaker who never
+     * triggers `speech-end` (e.g. continuous noise) must not grow the buffer
+     * without bound. When exceeded the turn is force-finalized. Default 30 s.
+     */
+    maxTurnSeconds?: number;
+    /**
+     * Pre-roll seconds of audio kept before `speech-start` so the onset of the
+     * first word (which the VAD only confirms a window or two in) is not clipped
+     * out of the attribution buffer. Default 0.3 s.
+     */
+    preRollSeconds?: number;
+}
+/** A finalized, attributed turn the consumer surfaces to its caller. */
+export interface AttributedTurn {
+    turnId: string;
+    output: VoiceAttributionOutput;
+    signal: VoiceTurnSignal;
+    /** Turn span in the mic-clock (frame `timestamp`) domain. */
+    startedAtMs: number;
+    endedAtMs: number;
+    /** Total buffered turn samples that were attributed. */
+    samples: number;
+}
+export type AttributedTurnListener = (turn: AttributedTurn) => void;
+/**
+ * Drives the `audioFrame` → VAD turn-segmentation → attribution → signal
+ * pipeline. One instance per capture session.
+ *
+ * Frame ingestion is serialized through the injected VAD's `pushFrame`
+ * (which itself serializes the Silero forward pass), so `onAudioFrame` is
+ * safe to fire-and-forget from a Capacitor event listener; turns surface in
+ * order via `onTurn`.
+ */
+export declare class AudioFrameConsumer {
+    private readonly vad;
+    private readonly pipeline;
+    private readonly runtime;
+    private readonly source;
+    private readonly attributionOptions;
+    private readonly maxTurnSamples;
+    private readonly preRollSamples;
+    private readonly unsubscribeVad;
+    private readonly turnListeners;
+    /** Float32 chunks of the in-flight turn, oldest first. */
+    private turnChunks;
+    private turnSamples;
+    /** Rolling pre-roll ring (frames captured before speech-start). */
+    private preRoll;
+    private preRollSampleCount;
+    private capturing;
+    private turnSeq;
+    private turnStartedAtMs;
+    private lastFrameEndMs;
+    /** Serialized attribution chain so turns finalize one at a time, in order. */
+    private attributing;
+    private closed;
+    /** Count of frames that failed to decode (surfaced via getters, not thrown). */
+    droppedFrames: number;
+    constructor(deps: AudioFrameConsumerDeps, config?: AudioFrameConsumerConfig);
+    /** True while a turn is being buffered (between speech-start and speech-end). */
+    get inTurn(): boolean;
+    /** Subscribe to finalized attributed turns. Returns an unsubscribe fn. */
+    onTurn(listener: AttributedTurnListener): () => void;
+    /**
+     * Feed one decoded-or-raw `audioFrame`. Accepts either the wire-format
+     * `AudioFrameEvent` (decoded here) or a pre-decoded Float32 window with the
+     * frame's mic-clock timestamp. Resolves once the frame's VAD windows are
+     * processed.
+     */
+    onAudioFrame(frame: AudioFrameEvent): Promise<void>;
+    /**
+     * Feed a pre-decoded Float32 16 kHz window with its mic-clock timestamp
+     * (ms). The decode boundary already ran; used by transports that decode
+     * upstream and by the host harness.
+     */
+    pushDecodedFrame(pcm: Float32Array, timestampMs: number): Promise<void>;
+    /**
+     * Flush the VAD (finalize any open segment) and await all pending
+     * attribution. Call at end-of-capture so a trailing utterance is not lost.
+     */
+    flush(): Promise<void>;
+    /** Release listeners and clear all buffers. Idempotent. */
+    close(): Promise<void>;
+    private onVadEvent;
+    private beginTurn;
+    private finalizeTurn;
+    private attributeTurn;
+    private appendTurnChunk;
+    private appendPreRoll;
+}
+/**
+ * Re-export of the producer's emit args, so a consumer caller can construct a
+ * VOICE_TURN_OBSERVED payload directly when wiring a custom transport without
+ * importing the runtime subpath twice.
+ */
+export type { EmitVoiceTurnObservedArgs };
+//# sourceMappingURL=audio-frame-consumer.d.ts.map

package/src/services/voice/audio-frame-consumer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"audio-frame-consumer.d.ts","sourceRoot":"","sources":["audio-frame-consumer.ts"],"names":[],"mappings":"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"}

package/src/services/voice/audio-frame-consumer.test.ts

@@ -0,0 +1,343 @@
+/**
+ * AudioFrameConsumer unit tests (no models, fully injected deps).
+ *
+ * Drives the consumer with:
+ *   - a REAL `VadDetector` backed by a deterministic scripted fake Silero, so
+ *     the turn-segmentation state machine (speech-start → speech-end) is the
+ *     real one, exercised deterministically;
+ *   - a fake `AttributionPipelineLike` that records the PCM it was handed and
+ *     returns a canned `VoiceAttributionOutput`;
+ *   - a fake `RuntimeEventSink` that records `emitEvent` calls.
+ *
+ * Asserts: the wire-format decode boundary; one turn segmented per
+ * speech-start/speech-end pair; the buffered PCM handed to attribution; the
+ * VOICE_TURN_OBSERVED emission and the folded voiceTurnSignal surfaced via
+ * `onTurn`; the runaway-turn cap; pre-roll inclusion.
+ */
+
+import { describe, expect, it } from "vitest";
+import {
+	type AttributionPipelineLike,
+	AudioFrameConsumer,
+	AudioFrameDecodeError,
+	type AudioFrameEvent,
+	decodeAudioFramePcm,
+	type RuntimeEventSink,
+} from "./audio-frame-consumer";
+import type { VoiceAttributionOutput } from "./speaker/attribution-pipeline";
+import { VadDetector } from "./vad";
+
+const SR = 16_000;
+const FRAME = 512; // one Silero window
+
+/** Deterministic fake Silero: scripted probability per processed window. */
+class ScriptedSilero {
+	readonly sampleRate = SR;
+	readonly windowSamples = FRAME;
+	private idx = 0;
+	constructor(private readonly probs: readonly number[]) {}
+	async process(window: Float32Array): Promise<number> {
+		expect(window.length).toBe(FRAME);
+		const p = this.probs[this.idx] ?? this.probs[this.probs.length - 1] ?? 0;
+		this.idx++;
+		return p;
+	}
+	reset(): void {}
+}
+
+/** Records the attribute() inputs and returns a canned output. */
+class FakePipeline implements AttributionPipelineLike {
+	readonly calls: Array<{ turnId: string; pcm: Float32Array }> = [];
+	constructor(private readonly entityId: string | null = "entity-x") {}
+	async attribute(
+		req: Parameters<AttributionPipelineLike["attribute"]>[0],
+	): Promise<VoiceAttributionOutput> {
+		this.calls.push({ turnId: req.turnId, pcm: req.pcm });
+		return {
+			turnId: req.turnId,
+			primarySpeaker: {
+				id: "spk",
+				imprintClusterId: "cluster-1",
+				entityId: this.entityId ?? undefined,
+				confidence: 0.5,
+			},
+			segments: [],
+			turn: { turnId: req.turnId },
+			observation: {
+				profileId: "prof-1",
+				imprintClusterId: "cluster-1",
+				entityId: this.entityId,
+				embedding: new Float32Array(256),
+				embeddingModel: "wespeaker",
+				confidence: 0.5,
+			},
+		};
+	}
+}
+
+class FakeRuntime implements RuntimeEventSink {
+	readonly emitted: Array<{ type: unknown; payload: Record<string, unknown> }> =
+		[];
+	async emitEvent(
+		type: unknown,
+		payload: Record<string, unknown>,
+	): Promise<void> {
+		this.emitted.push({ type, payload });
+	}
+}
+
+/** A 20 ms (320-sample) audioFrame at 16 kHz, encoded as base64 LE-s16. */
+function makeFrame(opts: {
+	amplitude: number;
+	timestamp: number;
+	frameIndex: number;
+	samples?: number;
+}): AudioFrameEvent {
+	const samples = opts.samples ?? 320;
+	const buf = Buffer.alloc(samples * 2);
+	for (let i = 0; i < samples; i++) {
+		const v = Math.round(
+			opts.amplitude * Math.sin((2 * Math.PI * 220 * i) / SR) * 32767,
+		);
+		buf.writeInt16LE(Math.max(-32768, Math.min(32767, v)), i * 2);
+	}
+	return {
+		pcm16: buf.toString("base64"),
+		sampleRate: SR,
+		channels: 1,
+		samples,
+		rms: opts.amplitude / Math.SQRT2,
+		timestamp: opts.timestamp,
+		frameIndex: opts.frameIndex,
+	};
+}
+
+/**
+ * Build a consumer whose REAL VadDetector is fed by a scripted Silero. Returns
+ * the consumer plus the recorders so tests can assert on them.
+ */
+function buildHarness(
+	probs: readonly number[],
+	entityId: string | null = "entity-x",
+) {
+	const silero = new ScriptedSilero(probs);
+	const vad = new VadDetector(silero, {
+		onsetThreshold: 0.5,
+		// Short hangovers so a finite scripted run finalizes the turn.
+		pauseHangoverMs: 64,
+		endHangoverMs: 128,
+		minSpeechMs: 32,
+	});
+	const pipeline = new FakePipeline(entityId);
+	const runtime = new FakeRuntime();
+	const consumer = new AudioFrameConsumer(
+		{ vad, pipeline, runtime },
+		{
+			source: { kind: "device", deviceId: "pixel" },
+			attributionOptions: {
+				ownerEntityId: "entity-x",
+				knownSpeakerEntityIds: ["entity-x"],
+				endOfTurnProbability: 0.95,
+			},
+			preRollSeconds: 0, // deterministic buffering for assertions
+			maxTurnSeconds: 30,
+		},
+	);
+	return { consumer, pipeline, runtime, vad };
+}
+
+describe("decodeAudioFramePcm", () => {
+	it("decodes base64 LE-s16 mono → Float32 [-1,1]", () => {
+		const frame = makeFrame({ amplitude: 0.5, timestamp: 0, frameIndex: 0 });
+		const pcm = decodeAudioFramePcm(frame);
+		expect(pcm).toBeInstanceOf(Float32Array);
+		expect(pcm.length).toBe(320);
+		// Peak ≈ amplitude; all in range.
+		let max = 0;
+		for (const v of pcm) {
+			expect(v).toBeGreaterThanOrEqual(-1);
+			expect(v).toBeLessThanOrEqual(1);
+			if (Math.abs(v) > max) max = Math.abs(v);
+		}
+		expect(max).toBeGreaterThan(0.45);
+		expect(max).toBeLessThan(0.55);
+	});
+
+	it("round-trips a known s16 sample exactly", () => {
+		const buf = Buffer.alloc(4);
+		buf.writeInt16LE(16384, 0); // +0.5
+		buf.writeInt16LE(-32768, 2); // -1.0
+		const pcm = decodeAudioFramePcm({
+			pcm16: buf.toString("base64"),
+			sampleRate: SR,
+			channels: 1,
+			samples: 2,
+			rms: 0,
+			timestamp: 0,
+			frameIndex: 0,
+		});
+		expect(pcm[0]).toBeCloseTo(0.5, 5);
+		expect(pcm[1]).toBeCloseTo(-1.0, 5);
+	});
+
+	it("rejects non-mono and wrong sample rate (no silent resample)", () => {
+		const base = makeFrame({ amplitude: 0.1, timestamp: 0, frameIndex: 0 });
+		expect(() => decodeAudioFramePcm({ ...base, channels: 2 })).toThrow(
+			AudioFrameDecodeError,
+		);
+		expect(() => decodeAudioFramePcm({ ...base, sampleRate: 48000 })).toThrow(
+			AudioFrameDecodeError,
+		);
+	});
+});
+
+describe("AudioFrameConsumer", () => {
+	it("segments one turn from speech-start..speech-end and attributes it", async () => {
+		// 320-sample frames re-window into the VAD as 512-sample windows. Script
+		// ~24 speech windows (loud) then ~12 silence windows to force speech-end.
+		const probs = [...Array(24).fill(0.9), ...Array(12).fill(0.0)];
+		const { consumer, pipeline, runtime } = buildHarness(probs);
+		const turns: Array<{ turnId: string }> = [];
+		consumer.onTurn((t) => turns.push({ turnId: t.turnId }));
+
+		// Feed enough loud frames to cover the speech windows, then silence.
+		let ts = 1000;
+		let idx = 0;
+		for (let i = 0; i < 40; i++) {
+			await consumer.onAudioFrame(
+				makeFrame({ amplitude: 0.6, timestamp: ts, frameIndex: idx++ }),
+			);
+			ts += 20;
+		}
+		for (let i = 0; i < 24; i++) {
+			await consumer.onAudioFrame(
+				makeFrame({ amplitude: 0.0, timestamp: ts, frameIndex: idx++ }),
+			);
+			ts += 20;
+		}
+		await consumer.flush();
+
+		expect(pipeline.calls.length).toBe(1);
+		expect(turns.length).toBe(1);
+		// The attributed PCM is the buffered turn (non-empty, real samples).
+		expect(pipeline.calls[0].pcm.length).toBeGreaterThan(SR * 0.4);
+		// VOICE_TURN_OBSERVED was emitted for the attributed (bound) speaker.
+		expect(runtime.emitted.length).toBe(1);
+		expect(runtime.emitted[0].payload.matchedEntityId).toBe("entity-x");
+	});
+
+	it("produces a voiceTurnSignal: enrolled owner → agent speaks", async () => {
+		const probs = [...Array(24).fill(0.9), ...Array(12).fill(0.0)];
+		const { consumer } = buildHarness(probs, "entity-x");
+		let signal: {
+			agentShouldSpeak: boolean | null;
+			nextSpeaker: string;
+		} | null = null;
+		consumer.onTurn((t) => {
+			signal = {
+				agentShouldSpeak: t.signal.agentShouldSpeak,
+				nextSpeaker: t.signal.nextSpeaker,
+			};
+		});
+		let ts = 1000;
+		for (let i = 0; i < 40; i++) {
+			await consumer.onAudioFrame(
+				makeFrame({ amplitude: 0.6, timestamp: ts, frameIndex: i }),
+			);
+			ts += 20;
+		}
+		for (let i = 0; i < 24; i++) {
+			await consumer.onAudioFrame(
+				makeFrame({ amplitude: 0.0, timestamp: ts, frameIndex: 40 + i }),
+			);
+			ts += 20;
+		}
+		await consumer.flush();
+		expect(signal).not.toBeNull();
+		expect(signal!.agentShouldSpeak).toBe(true);
+		expect(signal!.nextSpeaker).toBe("agent");
+	});
+
+	it("stamps the signal onto the attribution output turn metadata", async () => {
+		const probs = [...Array(24).fill(0.9), ...Array(12).fill(0.0)];
+		const { consumer } = buildHarness(probs);
+		let metaSignal: unknown;
+		consumer.onTurn((t) => {
+			metaSignal = (
+				t.output.turn.metadata as { voiceTurnSignal?: unknown } | undefined
+			)?.voiceTurnSignal;
+		});
+		let ts = 1000;
+		for (let i = 0; i < 40; i++) {
+			await consumer.onAudioFrame(
+				makeFrame({ amplitude: 0.6, timestamp: ts, frameIndex: i }),
+			);
+			ts += 20;
+		}
+		for (let i = 0; i < 24; i++) {
+			await consumer.onAudioFrame(
+				makeFrame({ amplitude: 0.0, timestamp: ts, frameIndex: 40 + i }),
+			);
+			ts += 20;
+		}
+		await consumer.flush();
+		expect(metaSignal).toBeTruthy();
+	});
+
+	it("does not segment a turn from pure silence", async () => {
+		const { consumer, pipeline } = buildHarness(Array(40).fill(0.0));
+		let ts = 1000;
+		for (let i = 0; i < 40; i++) {
+			await consumer.onAudioFrame(
+				makeFrame({ amplitude: 0.0, timestamp: ts, frameIndex: i }),
+			);
+			ts += 20;
+		}
+		await consumer.flush();
+		expect(pipeline.calls.length).toBe(0);
+	});
+
+	it("counts a frame that fails to decode as dropped (and rethrows)", async () => {
+		const { consumer } = buildHarness(Array(10).fill(0.0));
+		const bad = makeFrame({ amplitude: 0.1, timestamp: 0, frameIndex: 0 });
+		await expect(
+			consumer.onAudioFrame({ ...bad, channels: 2 }),
+		).rejects.toBeInstanceOf(AudioFrameDecodeError);
+		expect(consumer.droppedFrames).toBe(1);
+	});
+
+	it("force-finalizes a runaway turn at the max-turn cap", async () => {
+		// Never-ending speech: every window is loud. A tiny 1 s cap exercises the
+		// runaway path quickly.
+		const silero = new ScriptedSilero(Array(2000).fill(0.95));
+		const vad = new VadDetector(silero, {
+			onsetThreshold: 0.5,
+			pauseHangoverMs: 64,
+			endHangoverMs: 128,
+			minSpeechMs: 32,
+		});
+		const pl = new FakePipeline("entity-x");
+		const rt = new FakeRuntime();
+		const c = new AudioFrameConsumer(
+			{ vad, pipeline: pl, runtime: rt },
+			{ preRollSeconds: 0, maxTurnSeconds: 1 }, // 1 s cap
+		);
+		let finalized = 0;
+		c.onTurn(() => finalized++);
+		let ts = 1000;
+		// Feed ~2 s of loud audio (100 frames * 20 ms) — the cap must fire mid-stream.
+		for (let i = 0; i < 100; i++) {
+			await c.onAudioFrame(
+				makeFrame({ amplitude: 0.7, timestamp: ts, frameIndex: i }),
+			);
+			ts += 20;
+		}
+		await c.flush();
+		expect(finalized).toBeGreaterThanOrEqual(1);
+		expect(pl.calls.length).toBeGreaterThanOrEqual(1);
+		// Each finalized turn must not exceed the cap by more than one frame.
+		for (const call of pl.calls) {
+			expect(call.pcm.length).toBeLessThanOrEqual(SR * 1 + 512);
+		}
+	});
+});