@runtypelabs/persona 3.34.1 → 3.35.0

package/src/voice/voice-factory.ts

@@ -19,9 +19,26 @@ export function createVoiceProvider(config: VoiceConfig): VoiceProvider {
       }
       return new BrowserVoiceProvider(config.browser || {});
     
-    case 'custom':
-      throw new Error('Custom voice providers not yet implemented');
-    
+    case 'custom': {
+      // Bring-your-own provider: `custom` is either a ready VoiceProvider
+      // instance or a `() => VoiceProvider` factory (deferred construction, so
+      // resources like a WebSocket or AudioContext are only created when voice
+      // is actually set up). Resolve and sanity-check the shape.
+      const custom = config.custom;
+      if (!custom) {
+        throw new Error(
+          'Custom voice provider requires a `custom` provider instance or factory'
+        );
+      }
+      const provider = typeof custom === 'function' ? custom() : custom;
+      if (!provider || typeof provider.startListening !== 'function') {
+        throw new Error(
+          'Custom voice provider `custom` must be a VoiceProvider (or a factory returning one)'
+        );
+      }
+      return provider;
+    }
+
     default:
       throw new Error(`Unknown voice provider type: ${config.type}`);
   }
@@ -29,11 +46,16 @@ export function createVoiceProvider(config: VoiceConfig): VoiceProvider {
 
 // Auto-select the best available provider
 export function createBestAvailableVoiceProvider(config?: Partial<VoiceConfig>): VoiceProvider {
+  // Honor an explicit bring-your-own provider before any built-in.
+  if (config?.type === 'custom' && config.custom) {
+    return createVoiceProvider({ type: 'custom', custom: config.custom });
+  }
+
   // Prefer Runtype if configured
   if (config?.type === 'runtype' && config.runtype) {
     return createVoiceProvider({ type: 'runtype', runtype: config.runtype });
   }
-  
+
   // Fall back to browser if supported
   if (BrowserVoiceProvider.isSupported()) {
     return createVoiceProvider({ 

package/src/voice/voice.test.ts

@@ -1,5 +1,5 @@
 // Voice SDK Tests
-import { describe, it, expect, beforeAll, afterAll } from 'vitest';
+import { describe, it, expect, beforeAll, afterAll, beforeEach, afterEach, vi } from 'vitest';
 import type { VoiceConfig } from '../types';
 import { RuntypeVoiceProvider } from './runtype-voice-provider';
 import { BrowserVoiceProvider } from './browser-voice-provider';
@@ -32,6 +32,20 @@ function mockBrowserSupport(supported: boolean) {
   }
 }
 
+/** Minimal VoiceProvider-shaped object for the bring-your-own (`custom`) tests. */
+function makeFakeProvider() {
+  return {
+    type: 'custom' as const,
+    connect: async () => {},
+    disconnect: async () => {},
+    startListening: async () => {},
+    stopListening: async () => {},
+    onResult: () => {},
+    onError: () => {},
+    onStatusChange: () => {},
+  };
+}
+
 describe('BrowserVoiceProvider', () => {
   it('should check browser support', () => {
     // Test supported
@@ -86,15 +100,43 @@ describe('Voice Factory', () => {
     expect(() => createVoiceProvider(config)).toThrow('Browser speech recognition not supported');
   });
   
-  it('should throw error for custom provider', () => {
+  it('should throw when a custom provider is configured without `custom`', () => {
     const config: VoiceConfig = {
+      type: 'custom'
+    };
+
+    expect(() => createVoiceProvider(config)).toThrow('requires a `custom` provider');
+  });
+
+  it('should return a bring-your-own custom provider instance', () => {
+    const byo = makeFakeProvider();
+    const provider = createVoiceProvider({ type: 'custom', custom: byo });
+    expect(provider).toBe(byo);
+  });
+
+  it('should resolve a custom provider factory', () => {
+    const byo = makeFakeProvider();
+    let calls = 0;
+    const provider = createVoiceProvider({
       type: 'custom',
-      custom: {}
+      custom: () => {
+        calls += 1;
+        return byo;
+      },
+    });
+    expect(provider).toBe(byo);
+    expect(calls).toBe(1);
+  });
+
+  it('should throw when a custom factory returns a non-provider', () => {
+    const config = {
+      type: 'custom' as const,
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      custom: (() => ({})) as any,
     };
-    
-    expect(() => createVoiceProvider(config)).toThrow('Custom voice providers not yet implemented');
+    expect(() => createVoiceProvider(config)).toThrow('must be a VoiceProvider');
   });
-  
+
   it('should throw error for unknown provider type', () => {
     const config = {
       type: 'unknown' as any
@@ -163,7 +205,279 @@ describe('Voice Support Check', () => {
   it('should return false when no voice support available', () => {
     // Mock no browser support
     mockBrowserSupport(false);
-    
+
     expect(isVoiceSupported()).toBe(false);
   });
+});
+
+// ---------------------------------------------------------------------------
+// Realtime streaming protocol (RuntypeVoiceProvider rewrite)
+// ---------------------------------------------------------------------------
+
+const WS_OPEN = 1;
+
+class MockWebSocket {
+  static OPEN = WS_OPEN;
+  static instances: MockWebSocket[] = [];
+
+  url: string;
+  protocols: string | string[] | undefined;
+  binaryType = '';
+  readyState = 0;
+  sent: ArrayBuffer[] = [];
+  closeCalls: Array<{ code?: number; reason?: string }> = [];
+  onopen: (() => void) | null = null;
+  onmessage: ((ev: { data: unknown }) => void) | null = null;
+  onclose: ((ev: { code: number; reason?: string; wasClean: boolean }) => void) | null = null;
+  onerror: ((ev: unknown) => void) | null = null;
+
+  constructor(url: string, protocols?: string | string[]) {
+    this.url = url;
+    this.protocols = protocols;
+    MockWebSocket.instances.push(this);
+  }
+
+  send(data: ArrayBuffer) {
+    this.sent.push(data);
+  }
+
+  close(code?: number, reason?: string) {
+    this.readyState = 3;
+    this.closeCalls.push({ code, reason });
+    this.onclose?.({ code: code ?? 1000, reason, wasClean: (code ?? 1000) === 1000 });
+  }
+
+  // --- test triggers ---
+  triggerOpen() {
+    this.readyState = WS_OPEN;
+    this.onopen?.();
+  }
+  triggerMessage(data: unknown) {
+    this.onmessage?.({ data });
+  }
+  triggerClose(code: number, reason?: string) {
+    this.readyState = 3;
+    this.onclose?.({ code, reason, wasClean: code === 1000 });
+  }
+  triggerError() {
+    this.onerror?.({});
+  }
+}
+
+class MockAudioContext {
+  state = 'running';
+  destination = {};
+  sampleRate: number;
+  constructor(opts?: { sampleRate?: number }) {
+    this.sampleRate = opts?.sampleRate ?? 44100;
+  }
+  async resume() {
+    this.state = 'running';
+  }
+  async close() {
+    this.state = 'closed';
+  }
+  createMediaStreamSource() {
+    return { connect() {}, disconnect() {} };
+  }
+  createScriptProcessor() {
+    return { connect() {}, disconnect() {}, onaudioprocess: null as unknown };
+  }
+}
+
+function makeStream() {
+  const track = { stopped: false, stop() { track.stopped = true; } };
+  return { stream: { getTracks: () => [track] }, track };
+}
+
+function makeFakeEngine() {
+  const engine = {
+    enqueued: [] as Uint8Array[],
+    streamEnded: false,
+    flushed: false,
+    destroyed: false,
+    finishedCb: null as null | (() => void),
+    enqueue(p: Uint8Array) { engine.enqueued.push(p); },
+    markStreamEnd() { engine.streamEnded = true; },
+    flush() { engine.flushed = true; },
+    onFinished(cb: () => void) { engine.finishedCb = cb; },
+    destroy() { engine.destroyed = true; },
+  };
+  return engine;
+}
+
+/** Build a WAV-wrapped frame: 44-byte RIFF header + the given PCM bytes. */
+function makeWavFrame(pcmBytes: number[]): ArrayBuffer {
+  const buf = new ArrayBuffer(44 + pcmBytes.length);
+  const view = new DataView(buf);
+  view.setUint32(0, 0x52494646, false); // "RIFF"
+  new Uint8Array(buf).set(pcmBytes, 44);
+  return buf;
+}
+
+describe('RuntypeVoiceProvider (realtime streaming)', () => {
+  let getUserMedia: ReturnType<typeof vi.fn>;
+  let currentStream: ReturnType<typeof makeStream>;
+
+  beforeEach(() => {
+    MockWebSocket.instances = [];
+    currentStream = makeStream();
+    getUserMedia = vi.fn(async () => currentStream.stream);
+
+    vi.stubGlobal('WebSocket', MockWebSocket);
+    vi.stubGlobal('navigator', { mediaDevices: { getUserMedia } });
+    (globalThis as any).window.AudioContext = MockAudioContext;
+    (globalThis as any).window.webkitAudioContext = MockAudioContext;
+    (globalThis as any).window.location = { protocol: 'https:' };
+  });
+
+  afterEach(() => {
+    vi.unstubAllGlobals();
+    delete (globalThis as any).window.AudioContext;
+    delete (globalThis as any).window.webkitAudioContext;
+    delete (globalThis as any).window.location;
+  });
+
+  const baseConfig = () => ({
+    agentId: 'a1',
+    clientToken: 'ct_secret',
+    host: 'https://api.example.com',
+  });
+
+  const lastWs = () => MockWebSocket.instances[MockWebSocket.instances.length - 1];
+
+  it('connects to /voice with subprotocol auth and arraybuffer (no token in URL)', async () => {
+    const provider = new RuntypeVoiceProvider(baseConfig());
+    await provider.startListening();
+
+    const ws = lastWs();
+    expect(ws.url).toBe('wss://api.example.com/ws/agents/a1/voice');
+    expect(ws.protocols).toEqual(['runtype.bearer', 'ct_secret']);
+    expect(ws.binaryType).toBe('arraybuffer');
+    expect(ws.url).not.toContain('token=');
+    expect(ws.url).not.toContain('ct_secret');
+  });
+
+  it.each([
+    ['https://api.example.com', 'wss://api.example.com'],
+    ['http://localhost:8787', 'ws://localhost:8787'],
+    ['wss://api.example.com', 'wss://api.example.com'],
+    ['api.example.com', 'wss://api.example.com'], // bare host → window.location.protocol
+  ])('derives ws base %s -> %s', async (host, expected) => {
+    const provider = new RuntypeVoiceProvider({ ...baseConfig(), host });
+    await provider.startListening();
+    expect(lastWs().url).toBe(`${expected}/ws/agents/a1/voice`);
+  });
+
+  it('drives status + onTranscript from control frames', async () => {
+    const statuses: string[] = [];
+    const transcripts: Array<[string, string, boolean]> = [];
+    const provider = new RuntypeVoiceProvider(baseConfig());
+    provider.onStatusChange((s) => statuses.push(s));
+    provider.onTranscript((role, text, isFinal) => transcripts.push([role, text, isFinal]));
+
+    await provider.startListening();
+    lastWs().triggerOpen();
+    lastWs().triggerMessage(JSON.stringify({ type: 'transcript_interim', text: 'hel' }));
+    lastWs().triggerMessage(JSON.stringify({ type: 'transcript_final', role: 'user', text: 'hello' }));
+    lastWs().triggerMessage(JSON.stringify({ type: 'transcript_final', role: 'assistant', text: 'hi there' }));
+
+    expect(transcripts).toEqual([
+      ['user', 'hel', false],
+      ['user', 'hello', true],
+      ['assistant', 'hi there', true],
+    ]);
+    expect(statuses).toContain('listening'); // ws open + interim
+    expect(statuses).toContain('processing'); // user final
+    expect(statuses).toContain('speaking'); // assistant final
+  });
+
+  it('strips the WAV header, enqueues raw PCM, and drains on audio_end', async () => {
+    const engine = makeFakeEngine();
+    const provider = new RuntypeVoiceProvider({ ...baseConfig(), createPlaybackEngine: () => engine });
+    await provider.startListening();
+    lastWs().triggerOpen();
+
+    lastWs().triggerMessage(makeWavFrame([1, 2, 3, 4]));
+    expect(engine.enqueued).toHaveLength(1);
+    expect(Array.from(engine.enqueued[0])).toEqual([1, 2, 3, 4]); // 44-byte header stripped
+
+    lastWs().triggerMessage(JSON.stringify({ type: 'audio_end' }));
+    expect(engine.streamEnded).toBe(true);
+  });
+
+  it('treats a non-WAV binary frame as raw PCM', async () => {
+    const engine = makeFakeEngine();
+    const provider = new RuntypeVoiceProvider({ ...baseConfig(), createPlaybackEngine: () => engine });
+    await provider.startListening();
+    lastWs().triggerOpen();
+
+    const raw = new Uint8Array([9, 8, 7, 6]).buffer;
+    lastWs().triggerMessage(raw);
+    expect(Array.from(engine.enqueued[0])).toEqual([9, 8, 7, 6]);
+  });
+
+  it('emits onMetrics with camelCase from the snake_case frame', async () => {
+    const metrics: unknown[] = [];
+    const provider = new RuntypeVoiceProvider(baseConfig());
+    provider.onMetrics((m) => metrics.push(m));
+    await provider.startListening();
+    lastWs().triggerOpen();
+    // Raw JSON string: the wire frame is snake_case (decoded to camelCase by
+    // the provider); a literal avoids the no-snake_case-property lint rule.
+    lastWs().triggerMessage(
+      '{"type":"metrics","llm_ms":120,"tts_ms":80,"first_audio_ms":200,"total_ms":400}',
+    );
+    expect(metrics).toEqual([{ llmMs: 120, ttsMs: 80, firstAudioMs: 200, totalMs: 400 }]);
+  });
+
+  it('reports barge-in semantics while the call is live', async () => {
+    const provider = new RuntypeVoiceProvider(baseConfig());
+    expect(provider.getInterruptionMode()).toBe('barge-in');
+    expect(provider.isBargeInActive()).toBe(false);
+    await provider.startListening();
+    expect(provider.isBargeInActive()).toBe(true);
+    await provider.stopListening();
+    expect(provider.isBargeInActive()).toBe(false);
+  });
+
+  it('hangs up cleanly and drops late frames after teardown', async () => {
+    const engine = makeFakeEngine();
+    const provider = new RuntypeVoiceProvider({ ...baseConfig(), createPlaybackEngine: () => engine });
+    await provider.startListening();
+    lastWs().triggerOpen();
+    const ws = lastWs();
+
+    await provider.stopListening();
+
+    expect(ws.closeCalls).toEqual([{ code: 1000, reason: 'client ended call' }]);
+    expect(currentStream.track.stopped).toBe(true);
+    expect(engine.destroyed).toBe(true);
+
+    // A frame arriving after teardown is dropped by the generation guard.
+    const before = engine.enqueued.length;
+    ws.triggerMessage(makeWavFrame([1, 2]));
+    expect(engine.enqueued.length).toBe(before);
+  });
+
+  it('startListening is idempotent while a call is live', async () => {
+    const provider = new RuntypeVoiceProvider(baseConfig());
+    await provider.startListening();
+    await provider.startListening();
+    expect(MockWebSocket.instances).toHaveLength(1);
+    expect(getUserMedia).toHaveBeenCalledTimes(1);
+  });
+
+  it('returns to listening when playback drains (call stays open)', async () => {
+    const engine = makeFakeEngine();
+    const statuses: string[] = [];
+    const provider = new RuntypeVoiceProvider({ ...baseConfig(), createPlaybackEngine: () => engine });
+    provider.onStatusChange((s) => statuses.push(s));
+    await provider.startListening();
+    lastWs().triggerOpen();
+    lastWs().triggerMessage(makeWavFrame([1, 2])); // → speaking
+    statuses.length = 0;
+    engine.finishedCb?.(); // playback drained
+    expect(statuses).toEqual(['listening']);
+  });
 });

package/src/voice/worklet-playback-engine.ts

@@ -0,0 +1,272 @@
+// Jitter-buffered AudioWorklet PCM player.
+//
+// A reusable playback primitive for raw PCM16 / 24 kHz / mono streams. A
+// worklet-side sample queue is drained continuously by the audio thread, with a
+// configurable prebuffer "waterline" that absorbs network jitter. On underrun it
+// goes silent and re-buffers (the audio thread outputs pre-zeroed silence)
+// rather than snapping a schedule clock — so a late chunk produces a clean pause,
+// not a click. This is the production-grade alternative to hand-scheduling
+// AudioBufferSourceNodes (`AudioPlaybackManager`), which is simpler but clicks
+// under jitter.
+//
+// Two consumers:
+//   - The realtime `runtype` voice provider, via `createWorkletPlaybackEngine`
+//     (injected through `voiceRecognition.provider.runtype.createPlaybackEngine`).
+//   - Any hosted `SpeechEngine` (e.g. server/ElevenLabs/OpenAI TTS), via
+//     `createPcmStreamPlayer({ prebufferMs })` — same engine, plus pause/resume
+//     and a tunable prebuffer for bursty HTTP-streamed audio.
+//
+// Shipped from a separate subpath (`@runtypelabs/persona/voice-worklet-player`)
+// so the worklet source stays out of the main bundle.
+
+import type { PcmStreamPlayer, VoicePlaybackEngine } from "../types";
+
+const PLAYBACK_SAMPLE_RATE = 24000;
+// Default prebuffer: ~150ms. Enough for realtime, server-paced audio; HTTP-pulled
+// TTS is burstier and should pass a larger `prebufferMs`.
+const DEFAULT_PREBUFFER_MS = 150;
+
+// The worklet reads its waterline from `processorOptions.waterlineSamples`, so a
+// single registered processor serves any prebuffer size.
+const WORKLET_SOURCE = `
+class PersonaPcmPlayerProcessor extends AudioWorkletProcessor {
+  constructor(options) {
+    super()
+    const opts = (options && options.processorOptions) || {}
+    this.waterline = opts.waterlineSamples > 0 ? opts.waterlineSamples : 3600
+    this.chunks = []
+    this.readOffset = 0
+    this.buffered = 0
+    this.waiting = true
+    // 'drained' must mean "the reply finished playing", not "momentary
+    // underrun": a jitter gap empties the buffer mid-reply too, and firing
+    // there would flap the UI status and race the audio_end handler. Only
+    // report drained once eos has been signalled.
+    this.eosSeen = false
+    // Fire 'started' once, when the prebuffer first releases into playback, so a
+    // consumer can flip UI from loading→playing only when audio is truly audible.
+    // A mid-reply underrun re-buffers (waiting=true) but must NOT re-signal.
+    this.startedSignaled = false
+    this.port.onmessage = (e) => {
+      const msg = e.data
+      if (msg.type === 'push') {
+        this.eosSeen = false
+        this.chunks.push(msg.samples)
+        this.buffered += msg.samples.length
+        if (this.waiting && this.buffered >= this.waterline) {
+          this.waiting = false
+          this.signalStarted()
+        }
+      } else if (msg.type === 'eos') {
+        this.eosSeen = true
+        if (this.waiting && this.buffered > 0) {
+          this.waiting = false
+          this.signalStarted()
+        }
+        if (this.buffered === 0) {
+          this.eosSeen = false
+          this.port.postMessage({ type: 'drained' })
+        }
+      } else if (msg.type === 'clear') {
+        this.chunks = []
+        this.readOffset = 0
+        this.buffered = 0
+        this.waiting = true
+        this.eosSeen = false
+        this.startedSignaled = false
+      }
+    }
+  }
+  signalStarted() {
+    if (!this.startedSignaled) {
+      this.startedSignaled = true
+      this.port.postMessage({ type: 'started' })
+    }
+  }
+  process(inputs, outputs) {
+    const out = outputs[0][0]
+    if (!out || this.waiting) return true // outputs are pre-zeroed: silence
+    let i = 0
+    while (i < out.length && this.buffered > 0) {
+      const chunk = this.chunks[0]
+      out[i++] = chunk[this.readOffset++]
+      this.buffered--
+      if (this.readOffset >= chunk.length) {
+        this.chunks.shift()
+        this.readOffset = 0
+      }
+    }
+    if (this.buffered === 0) {
+      this.waiting = true // mid-reply underrun: re-buffer silently
+      if (this.eosSeen) {
+        this.eosSeen = false
+        this.port.postMessage({ type: 'drained' })
+      }
+    }
+    return true
+  }
+}
+registerProcessor('persona-pcm-player', PersonaPcmPlayerProcessor)
+`;
+
+/** Convert raw PCM16 LE mono to Float32 samples in [-1, 1]. */
+function pcm16ToFloat32(pcm: Uint8Array): Float32Array {
+  const count = pcm.length >> 1;
+  const out = new Float32Array(count);
+  const view = new DataView(pcm.buffer, pcm.byteOffset, pcm.byteLength);
+  for (let i = 0; i < count; i++) {
+    out[i] = view.getInt16(i * 2, true) / 0x8000;
+  }
+  return out;
+}
+
+export interface PcmStreamPlayerOptions {
+  /**
+   * Audio (ms) to buffer before the first sample, and to re-buffer after an
+   * underrun. Higher = smoother on bursty/jittery streams, at the cost of a
+   * slightly later first sound (latency ↔ smoothness). Default 150 — good for
+   * realtime, server-paced audio; HTTP-pulled TTS often wants ~400–600.
+   */
+  prebufferMs?: number;
+}
+
+/**
+ * Create a jitter-buffered AudioWorklet PCM player with pause/resume.
+ *
+ * Feed it raw PCM16 / 24 kHz / mono via `enqueue()`; it handles prebuffering,
+ * gapless playback, and graceful underrun. Reuse it inside a hosted
+ * {@link SpeechEngine} so streamed TTS plays smoothly:
+ *
+ * @example
+ * import { createPcmStreamPlayer } from '@runtypelabs/persona/voice-worklet-player'
+ * const player = await createPcmStreamPlayer({ prebufferMs: 500 })
+ * // for each streamed chunk: player.enqueue(pcmChunk)
+ * player.markStreamEnd()
+ */
+export async function createPcmStreamPlayer(
+  options: PcmStreamPlayerOptions = {},
+): Promise<PcmStreamPlayer> {
+  const prebufferMs = options.prebufferMs ?? DEFAULT_PREBUFFER_MS;
+  const waterlineSamples = Math.max(
+    1,
+    Math.round((PLAYBACK_SAMPLE_RATE * prebufferMs) / 1000),
+  );
+
+  const AudioCtx =
+    (window as any).AudioContext || (window as any).webkitAudioContext;
+  // Match the context rate to the PCM rate so the worklet maps samples 1:1;
+  // the browser resamples to the hardware rate at the output.
+  const context: AudioContext = new AudioCtx({ sampleRate: PLAYBACK_SAMPLE_RATE });
+  if (context.state === "suspended") {
+    await context.resume().catch(() => {});
+  }
+
+  const moduleUrl = URL.createObjectURL(
+    new Blob([WORKLET_SOURCE], { type: "application/javascript" }),
+  );
+  try {
+    await context.audioWorklet.addModule(moduleUrl);
+  } catch (err) {
+    context.close().catch(() => {});
+    throw err;
+  } finally {
+    URL.revokeObjectURL(moduleUrl);
+  }
+
+  const node = new AudioWorkletNode(context, "persona-pcm-player", {
+    numberOfInputs: 0,
+    numberOfOutputs: 1,
+    outputChannelCount: [1],
+    processorOptions: { waterlineSamples },
+  });
+  node.connect(context.destination);
+
+  let finishedCallbacks: (() => void)[] = [];
+  let startedCallbacks: (() => void)[] = [];
+  // Carry an orphaned odd byte across chunks so a sample split at a frame
+  // boundary isn't dropped.
+  let remainder: Uint8Array | null = null;
+
+  node.port.onmessage = (e: MessageEvent) => {
+    const type = e.data?.type;
+    if (type === "started") {
+      const cbs = startedCallbacks.slice();
+      startedCallbacks = [];
+      cbs.forEach((cb) => cb());
+    } else if (type === "drained") {
+      const cbs = finishedCallbacks.slice();
+      finishedCallbacks = [];
+      cbs.forEach((cb) => cb());
+    }
+  };
+
+  return {
+    enqueue(pcm: Uint8Array) {
+      let data = pcm;
+      if (remainder) {
+        const merged = new Uint8Array(remainder.length + pcm.length);
+        merged.set(remainder);
+        merged.set(pcm, remainder.length);
+        data = merged;
+        remainder = null;
+      }
+      if (data.length % 2 !== 0) {
+        remainder = new Uint8Array([data[data.length - 1]]);
+        data = data.subarray(0, data.length - 1);
+      }
+      if (data.length === 0) return;
+      const samples = pcm16ToFloat32(data);
+      if (samples.length === 0) return;
+      node.port.postMessage({ type: "push", samples }, [samples.buffer]);
+    },
+    markStreamEnd() {
+      node.port.postMessage({ type: "eos" });
+    },
+    flush() {
+      remainder = null;
+      finishedCallbacks = [];
+      startedCallbacks = [];
+      node.port.postMessage({ type: "clear" });
+    },
+    onFinished(callback: () => void) {
+      finishedCallbacks.push(callback);
+    },
+    onStarted(callback: () => void) {
+      startedCallbacks.push(callback);
+    },
+    pause() {
+      // Suspending the context freezes the audio clock; queued samples stay put
+      // and resume() continues exactly where playback left off.
+      if (context.state === "running") void context.suspend();
+    },
+    resume() {
+      if (context.state === "suspended") void context.resume();
+    },
+    destroy() {
+      node.port.onmessage = null;
+      try {
+        node.disconnect();
+      } catch {
+        // ignore
+      }
+      return context.close().catch(() => {});
+    },
+  };
+}
+
+/**
+ * Realtime-named alias of {@link createPcmStreamPlayer} (default prebuffer),
+ * typed as a plain {@link VoicePlaybackEngine}. Pass it to the realtime voice
+ * provider's `createPlaybackEngine`:
+ *
+ * @example
+ * import { createWorkletPlaybackEngine } from '@runtypelabs/persona/voice-worklet-player'
+ *
+ * initAgentWidget({ config: { voiceRecognition: { enabled: true, provider: {
+ *   type: 'runtype',
+ *   runtype: { agentId, createPlaybackEngine: createWorkletPlaybackEngine },
+ * } } } })
+ */
+export function createWorkletPlaybackEngine(): Promise<VoicePlaybackEngine> {
+  return createPcmStreamPlayer();
+}