@kuralle-syrinx/browser-client 4.2.0 → 4.4.0

package/src/jitter-buffer.test.ts

@@ -1,275 +0,0 @@
-// SPDX-License-Identifier: MIT
-// WT-03: Client jitter buffer tests
-
-import { beforeEach, describe, expect, it, vi } from "vitest";
-import { AudioJitterBuffer } from "./audio.js";
-
-// Mock AudioContext for testing
-class MockAudioContext {
-  public currentTime = 0;
-  public destination = {};
-  private nextBufferId = 1;
-
-  createBuffer(channels: number, length: number, sampleRate: number): MockAudioBuffer {
-    return new MockAudioBuffer(channels, length, sampleRate, this.nextBufferId++);
-  }
-
-  createBufferSource(): MockAudioBufferSource {
-    return new MockAudioBufferSource();
-  }
-}
-
-class MockAudioBuffer {
-  constructor(
-    public numberOfChannels: number,
-    public length: number,
-    public sampleRate: number,
-    public _id: number
-  ) {}
-
-  get duration(): number {
-    return this.length / this.sampleRate;
-  }
-
-  copyToChannel(_data: Float32Array, _channel: number): void {
-    // Mock implementation
-  }
-}
-
-class MockAudioBufferSource {
-  public buffer: MockAudioBuffer | null = null;
-  public onended: (() => void) | null = null;
-  private connected = false;
-  private started = false;
-  private startTime = 0;
-
-  connect(_destination: unknown): void {
-    this.connected = true;
-  }
-
-  start(when = 0): void {
-    this.started = true;
-    this.startTime = when;
-    
-    // Simulate completion after buffer duration
-    if (this.buffer && this.onended) {
-      setTimeout(() => {
-        this.onended?.();
-      }, this.buffer.duration * 1000);
-    }
-  }
-
-  stop(): void {
-    this.started = false;
-  }
-}
-
-describe("AudioJitterBuffer", () => {
-  let mockContext: MockAudioContext;
-  let jitterBuffer: AudioJitterBuffer;
-
-  beforeEach(() => {
-    vi.useFakeTimers();
-    mockContext = new MockAudioContext();
-    jitterBuffer = new AudioJitterBuffer(mockContext as any, { 
-      sampleRateHz: 16000,
-      targetBufferMs: 100 
-    });
-  });
-
-  it("enqueues and schedules audio frames with target buffer delay", () => {
-    const pcm16Data = new Int16Array(320); // 20ms at 16kHz
-    pcm16Data.fill(1000);
-
-    mockContext.currentTime = 1.0;
-    jitterBuffer.enqueue(pcm16Data.buffer, "test-context");
-
-    // Should schedule audio ~100ms + frame duration in the future
-    expect(jitterBuffer.bufferedDurationMs).toBeCloseTo(120, -1);
-  });
-
-  it("schedules multiple frames contiguously", () => {
-    const frameData = new Int16Array(320); // 20ms at 16kHz
-    frameData.fill(1000);
-
-    mockContext.currentTime = 1.0;
-    
-    // Enqueue 3 frames
-    jitterBuffer.enqueue(frameData.buffer, "test-context");
-    jitterBuffer.enqueue(frameData.buffer, "test-context");
-    jitterBuffer.enqueue(frameData.buffer, "test-context");
-
-    // Should buffer ~160ms total (100ms initial + 3*20ms)
-    expect(jitterBuffer.bufferedDurationMs).toBeCloseTo(160, -1);
-  });
-
-  it("tracks active context IDs", () => {
-    const frameData = new Int16Array(320);
-    frameData.fill(1000);
-
-    jitterBuffer.enqueue(frameData.buffer, "context-1");
-    jitterBuffer.enqueue(frameData.buffer, "context-2");
-
-    expect(jitterBuffer.activeContextIds).toContain("context-1");
-    expect(jitterBuffer.activeContextIds).toContain("context-2");
-    expect(jitterBuffer.activeContextIds).toHaveLength(2);
-  });
-
-  it("reports played-out ms clamped to the scheduled window (heard clock)", () => {
-    const frameData = new Int16Array(320); // 20ms at 16kHz
-    frameData.fill(1000);
-    mockContext.currentTime = 1.0;
-    jitterBuffer.enqueue(frameData.buffer, "ctx"); // scheduled at 1.1, ends 1.12
-
-    // Before the frame starts playing → nothing heard yet.
-    expect(jitterBuffer.playedOutMs("ctx")).toBe(0);
-    expect(jitterBuffer.isPlayoutComplete("ctx")).toBe(false);
-
-    // Halfway through the 20ms frame → ~10ms heard.
-    mockContext.currentTime = 1.11;
-    expect(jitterBuffer.playedOutMs("ctx")).toBeCloseTo(10, 0);
-
-    // Past the end → clamped to the full 20ms, and complete.
-    mockContext.currentTime = 1.2;
-    expect(jitterBuffer.playedOutMs("ctx")).toBeCloseTo(20, 0);
-    expect(jitterBuffer.isPlayoutComplete("ctx")).toBe(true);
-
-    // Unknown context reports 0.
-    expect(jitterBuffer.playedOutMs("nope")).toBe(0);
-  });
-
-  it("clears specific context frames on context-specific clear", () => {
-    const frameData = new Int16Array(320);
-    frameData.fill(1000);
-
-    jitterBuffer.enqueue(frameData.buffer, "context-1");
-    jitterBuffer.enqueue(frameData.buffer, "context-2");
-    jitterBuffer.enqueue(frameData.buffer, "context-1");
-
-    expect(jitterBuffer.activeContextIds).toHaveLength(2);
-
-    jitterBuffer.clear("context-1");
-
-    expect(jitterBuffer.activeContextIds).toContain("context-2");
-    expect(jitterBuffer.activeContextIds).not.toContain("context-1");
-    expect(jitterBuffer.activeContextIds).toHaveLength(1);
-  });
-
-  it("resets schedule baseline after context-specific clear", () => {
-    const frameData = new Int16Array(320);
-    frameData.fill(1000);
-
-    mockContext.currentTime = 1.0;
-    for (let i = 0; i < 50; i += 1) {
-      jitterBuffer.enqueue(frameData.buffer, "assistant");
-    }
-    expect(jitterBuffer.bufferedDurationMs).toBeGreaterThan(1000);
-
-    jitterBuffer.clear("assistant");
-    expect(jitterBuffer.bufferedDurationMs).toBe(0);
-
-    mockContext.currentTime = 1.05;
-    jitterBuffer.enqueue(frameData.buffer, "user-barge");
-    expect(jitterBuffer.bufferedDurationMs).toBeCloseTo(120, -1);
-  });
-
-  it("zeros buffered duration when the cleared context was the only one scheduled", () => {
-    const frameData = new Int16Array(320);
-    frameData.fill(1000);
-
-    mockContext.currentTime = 2.0;
-    jitterBuffer.enqueue(frameData.buffer, "solo-context");
-    jitterBuffer.enqueue(frameData.buffer, "solo-context");
-    expect(jitterBuffer.bufferedDurationMs).toBeGreaterThan(0);
-
-    jitterBuffer.clear("solo-context");
-    expect(jitterBuffer.activeContextIds).toHaveLength(0);
-    expect(jitterBuffer.bufferedDurationMs).toBe(0);
-
-    mockContext.currentTime = 8.0;
-    jitterBuffer.enqueue(frameData.buffer, "next-context");
-    expect(jitterBuffer.bufferedDurationMs).toBeCloseTo(120, -1);
-  });
-
-  it("clears all frames on global clear", () => {
-    const frameData = new Int16Array(320);
-    frameData.fill(1000);
-
-    jitterBuffer.enqueue(frameData.buffer, "context-1");
-    jitterBuffer.enqueue(frameData.buffer, "context-2");
-
-    expect(jitterBuffer.activeContextIds).toHaveLength(2);
-
-    jitterBuffer.clear();
-
-    expect(jitterBuffer.activeContextIds).toHaveLength(0);
-    expect(jitterBuffer.bufferedDurationMs).toBe(0);
-  });
-
-  it("establishes new baseline when buffer is empty", () => {
-    const frameData = new Int16Array(320);
-    frameData.fill(1000);
-
-    mockContext.currentTime = 1.0;
-    jitterBuffer.enqueue(frameData.buffer, "context-1");
-
-    const initialBuffer = jitterBuffer.bufferedDurationMs;
-
-    // Clear and advance time
-    jitterBuffer.clear();
-    mockContext.currentTime = 2.0;
-
-    jitterBuffer.enqueue(frameData.buffer, "context-2");
-
-    // Should establish new baseline at current time + target buffer
-    expect(jitterBuffer.bufferedDurationMs).toBeCloseTo(initialBuffer, -1);
-  });
-
-  it("handles PCM16 to Float32 conversion correctly", () => {
-    // Test with known values
-    const pcm16Data = new Int16Array([0, 16383, -16384, 32767, -32768]);
-    const expectedFloat32 = [0, 0.5, -0.5, 1.0, -1.0];
-
-    let capturedFloat32: Float32Array | null = null;
-    
-    // Mock copyToChannel to capture the converted data
-    MockAudioBuffer.prototype.copyToChannel = function(data: Float32Array, _channel: number) {
-      capturedFloat32 = new Float32Array(data);
-    };
-
-    jitterBuffer.enqueue(pcm16Data.buffer);
-
-    expect(capturedFloat32).not.toBeNull();
-    expect(capturedFloat32![0]).toBeCloseTo(expectedFloat32[0]!, 5);
-    expect(capturedFloat32![1]).toBeCloseTo(expectedFloat32[1]!, 3);
-    expect(capturedFloat32![2]).toBeCloseTo(expectedFloat32[2]!, 3);
-    expect(capturedFloat32![3]).toBeCloseTo(expectedFloat32[3]!, 3);
-    expect(capturedFloat32![4]).toBeCloseTo(expectedFloat32[4]!, 3);
-  });
-
-  it("handles empty or invalid audio data gracefully", () => {
-    const emptyData = new ArrayBuffer(0);
-    
-    expect(() => {
-      jitterBuffer.enqueue(emptyData, "test-context");
-    }).not.toThrow();
-
-    expect(jitterBuffer.activeContextIds).toHaveLength(0);
-  });
-
-  it("advances scheduled time correctly for consecutive frames", () => {
-    const frame1 = new Int16Array(160).fill(1000); // 10ms at 16kHz
-    const frame2 = new Int16Array(320).fill(1000); // 20ms at 16kHz
-
-    mockContext.currentTime = 0;
-    
-    jitterBuffer.enqueue(frame1.buffer, "context-1");
-    const buffer1 = jitterBuffer.bufferedDurationMs;
-    
-    jitterBuffer.enqueue(frame2.buffer, "context-1");
-    const buffer2 = jitterBuffer.bufferedDurationMs;
-
-    // Second frame should add its duration to the buffer
-    expect(buffer2 - buffer1).toBeCloseTo(20, -1);
-  });
-});

package/src/studio-page.test.ts

@@ -1,69 +0,0 @@
-// SPDX-License-Identifier: MIT
-
-// Guards the standalone studio page (packages/voice-client-browser/index.html), which is
-// served raw by the review studio. Its assistant-audio decoder is PCM16-only (no Opus
-// decoder), so it must declare a pcm_s16le downlink capability on connect — otherwise the
-// server streams Opus envelopes it rejects with "PCM16 payload must contain an even number
-// of bytes" / "durationMs mismatch". Regression guard for that contract.
-
-import { readFileSync } from "node:fs";
-import { fileURLToPath } from "node:url";
-import { describe, expect, it } from "vitest";
-
-const html = readFileSync(fileURLToPath(new URL("../index.html", import.meta.url)), "utf8");
-
-describe("studio index.html downlink codec negotiation", () => {
-  it("declares pcm_s16le downlink capability on connect", () => {
-    // The page has no Opus decoder, so it must negotiate PCM downlink.
-    expect(html).not.toMatch(/OpusDecoder|decodeOpus/);
-    const open = html.slice(html.indexOf('addEventListener("open"'), html.indexOf('addEventListener("close"'));
-    expect(open).toMatch(/"codec_capability"/);
-    expect(open).toMatch(/downlinkEncoding:\s*"pcm_s16le"/);
-  });
-
-  it("rejects a non-pcm_s16le downlink encoding loudly instead of failing as cryptic PCM", () => {
-    // If the server ever sends a non-PCM envelope (codec negotiation failure), the decoder
-    // must branch on metadata.encoding and surface a clear error — not the misleading
-    // "PCM16 payload must contain an even number of bytes" the byte invariants would throw.
-    const decode = html.slice(html.indexOf("function decodeAssistantAudio"), html.indexOf("function hasPrefix"));
-    expect(decode).toMatch(/metadata\.encoding\s*&&\s*metadata\.encoding\s*!==\s*"pcm_s16le"/);
-  });
-});
-
-describe("studio index.html capture turn lifecycle", () => {
-  it("keeps the capture context open across VAD speech_ended until the server commits the turn", () => {
-    const speechEnded = html.slice(
-      html.indexOf('message.type === "speech_ended"'),
-      html.indexOf('message.type === "audio_clear"'),
-    );
-    expect(speechEnded).toMatch(/drainPcmQueue\(turn\.id\)/);
-    expect(speechEnded).not.toMatch(/activeTurn\s*=\s*null/);
-
-    const turnComplete = html.slice(
-      html.indexOf('message.type === "turn_complete"'),
-      html.indexOf('message.type === "agent_tool_call"'),
-    );
-    expect(turnComplete).toMatch(/activeTurn\?\.id\s*===\s*turn\.id/);
-    expect(turnComplete).toMatch(/activeTurn\s*=\s*null/);
-  });
-});
-
-describe("studio index.html local speech-start barge-in", () => {
-  it("flushes local assistant playout before sending a server client_interrupt", () => {
-    const handler = html.slice(
-      html.indexOf("function handleLocalSpeechStart"),
-      html.indexOf("function createCaptureTurn"),
-    );
-    expect(handler).toMatch(/flushOutputAudio\(\)[\s\S]*sendClientInterrupt/);
-    expect(handler).toMatch(/local_vad_speech_start/);
-  });
-
-  it("does not use browser speech_ended or silence as an EOS signal", () => {
-    const capture = html.slice(
-      html.indexOf("processorNode.onaudioprocess"),
-      html.indexOf("sourceNode.connect"),
-    );
-    expect(capture).toMatch(/handleLocalSpeechStart/);
-    expect(capture).not.toMatch(/eos\.turn_complete|turn_complete|client_eos|speech_ended/);
-  });
-});

package/src/transport.test.ts

@@ -1,233 +0,0 @@
-// SPDX-License-Identifier: MIT
-
-import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
-import { Decoder as OpusDecoder, Encoder as OpusEncoder } from "@evan/opus";
-import { decodeSyrinxAudioEnvelope } from "@kuralle-syrinx/core";
-import { pcm16BytesToSamples, pcm16SamplesToBytes } from "@kuralle-syrinx/core/audio";
-import { SyrinxBrowserClient } from "./index.js";
-import type { ClientTransport, ClientTransportHandlers } from "./transport.js";
-import * as browserOpus from "./browser-opus.js";
-import { pickBrowserWireCodec, createBrowserOpusCodec } from "./browser-opus.js";
-
-async function pollUntil(predicate: () => boolean, timeoutMs: number, label: string): Promise<void> {
-  const deadline = Date.now() + timeoutMs;
-  while (Date.now() < deadline) {
-    if (predicate()) return;
-    await new Promise((resolve) => setTimeout(resolve, 10));
-  }
-  throw new Error(`Timed out waiting for ${label}`);
-}
-
-class FakeTransport implements ClientTransport {
-  readonly sent: unknown[] = [];
-  private handlers: ClientTransportHandlers = {};
-  private open = false;
-
-  get connected(): boolean {
-    return this.open;
-  }
-
-  setHandlers(handlers: ClientTransportHandlers): void {
-    this.handlers = handlers;
-  }
-
-  connect(_url: string): void {
-    this.open = true;
-    this.handlers.onOpen?.();
-  }
-
-  disconnect(): void {
-    this.open = false;
-    this.handlers.onClose?.(1000, "");
-  }
-
-  sendAudio(data: Uint8Array | ArrayBuffer): void {
-    this.sent.push(data);
-  }
-
-  sendJson(value: unknown): void {
-    this.sent.push(JSON.stringify(value));
-  }
-
-  emitMessage(data: string): void {
-    this.handlers.onMessage?.(data);
-  }
-
-  emitAudio(data: ArrayBuffer): void {
-    this.handlers.onAudio?.(data);
-  }
-}
-
-describe("ClientTransport seam", () => {
-  it("drives SyrinxBrowserClient through an injected fake transport", () => {
-    const transport = new FakeTransport();
-    const client = new SyrinxBrowserClient({
-      url: "ws://unused/ws",
-      transport,
-      reconnect: false,
-      keepaliveIntervalMs: false,
-    });
-    const events: string[] = [];
-    client.on((event) => events.push(event.type));
-    client.connect();
-
-    expect(events).toContain("open");
-    transport.emitMessage(JSON.stringify({
-      type: "ready",
-      sessionId: "sess-fake",
-      audio: {
-        inputSampleRateHz: 16000,
-        outputSampleRateHz: 16000,
-        encoding: "pcm_s16le",
-        channels: 1,
-      },
-    }));
-    client.sendAudioPcm(new Uint8Array([1, 0, 2, 0]), 16000);
-    expect(transport.sent.length).toBeGreaterThan(0);
-  });
-});
-
-describe("browser opus negotiation", () => {
-  it("prefers opus when the server advertises it", () => {
-    expect(pickBrowserWireCodec(["pcm_s16le", "opus"], true)).toBe("opus");
-    expect(pickBrowserWireCodec(["pcm_s16le", "opus"], false)).toBe("pcm_s16le");
-    expect(pickBrowserWireCodec(["pcm_s16le"], true)).toBe("pcm_s16le");
-  });
-
-  it("produces opus frames and decodes them back to PCM16 samples", async () => {
-    const codec = await createBrowserOpusCodec(48000);
-    const pcm = new Int16Array(960);
-    pcm[0] = 1000;
-    const wire = codec.encodePcm16Frame(pcm, true)[0]!;
-    expect(wire.byteLength).toBeGreaterThan(0);
-    expect(codec.decodeOpusFrame(wire).length).toBeGreaterThan(0);
-  });
-
-  it("flushes pre-ready uplink audio in negotiated opus, not pcm", async () => {
-    const transport = new FakeTransport();
-    const client = new SyrinxBrowserClient({
-      url: "ws://unused/ws",
-      transport,
-      reconnect: false,
-      keepaliveIntervalMs: false,
-    });
-    client.connect();
-
-    const pcm = new Uint8Array(640);
-    pcm[0] = 1;
-    pcm[1] = 0;
-    client.sendAudioPcm(pcm, 16000, { contextId: "turn-early" });
-
-    expect(transport.sent.filter((entry) => entry instanceof Uint8Array)).toHaveLength(0);
-
-    transport.emitMessage(JSON.stringify({
-      type: "ready",
-      sessionId: "sess-opus-early",
-      audio: {
-        inputSampleRateHz: 16000,
-        outputSampleRateHz: 16000,
-        encoding: "opus",
-        supportedInputCodecs: ["pcm_s16le", "opus"],
-        channels: 1,
-        binaryEnvelope: "syrinx.audio.v1",
-      },
-    }));
-
-    await pollUntil(
-      () => transport.sent.some((entry) => {
-        if (typeof entry !== "string") return false;
-        return (JSON.parse(entry) as { type?: string }).type === "codec_capability";
-      }),
-      3_000,
-      "codec_capability",
-    );
-
-    const uplink = transport.sent.filter((entry): entry is Uint8Array => entry instanceof Uint8Array);
-    expect(uplink.length).toBeGreaterThan(0);
-    for (const frame of uplink) {
-      expect(decodeSyrinxAudioEnvelope(frame).header.encoding).toBe("opus");
-    }
-    expect(decodeSyrinxAudioEnvelope(uplink[0]!).header.contextId).toBe("turn-early");
-  });
-
-  it("encodes uplink envelopes as opus after ready negotiation", async () => {
-    const transport = new FakeTransport();
-    const client = new SyrinxBrowserClient({
-      url: "ws://unused/ws",
-      transport,
-      reconnect: false,
-      keepaliveIntervalMs: false,
-    });
-    client.connect();
-    transport.emitMessage(JSON.stringify({
-      type: "ready",
-      sessionId: "sess-opus",
-      audio: {
-        inputSampleRateHz: 16000,
-        outputSampleRateHz: 16000,
-        encoding: "opus",
-        supportedInputCodecs: ["pcm_s16le", "opus"],
-        channels: 1,
-        binaryEnvelope: "syrinx.audio.v1",
-      },
-    }));
-
-    await vi.waitFor(() => transport.sent.length > 0, { timeout: 50 }).catch(() => undefined);
-
-    const pcm = new Uint8Array(640);
-    pcm[0] = 1;
-    pcm[1] = 0;
-    client.sendAudioPcm(pcm, 16000, { contextId: "turn-opus" });
-
-    await vi.waitFor(() => transport.sent.some((entry) => {
-      if (!(entry instanceof Uint8Array)) return false;
-      return decodeSyrinxAudioEnvelope(entry).header.encoding === "opus";
-    }), { timeout: 3_000 });
-
-    const envelopeBytes = transport.sent.find((entry): entry is Uint8Array => {
-      if (!(entry instanceof Uint8Array)) return false;
-      return decodeSyrinxAudioEnvelope(entry).header.encoding === "opus";
-    })!;
-    const envelope = decodeSyrinxAudioEnvelope(envelopeBytes);
-    expect(envelope.header.sampleRateHz).toBe(48000);
-    const reference = pcm16BytesToSamples(
-      new OpusDecoder({ channels: 1, sample_rate: 48000 }).decode(envelope.audio),
-    );
-    expect(reference.length).toBeGreaterThan(0);
-  });
-});
-
-describe("browser downlink codec capability", () => {
-  it("reports pcm downlink when opus load fails", async () => {
-    vi.spyOn(browserOpus, "createBrowserOpusCodec").mockRejectedValue(new Error("opus unavailable"));
-
-    const transport = new FakeTransport();
-    const client = new SyrinxBrowserClient({
-      url: "ws://unused/ws",
-      transport,
-      reconnect: false,
-      keepaliveIntervalMs: false,
-    });
-    client.connect();
-    transport.emitMessage(JSON.stringify({
-      type: "ready",
-      sessionId: "sess-pcm-downlink",
-      audio: {
-        inputSampleRateHz: 16000,
-        outputSampleRateHz: 16000,
-        encoding: "opus",
-        supportedInputCodecs: ["pcm_s16le", "opus"],
-        channels: 1,
-        binaryEnvelope: "syrinx.audio.v1",
-      },
-    }));
-
-    await vi.waitFor(() => transport.sent.some((entry) => {
-      if (typeof entry !== "string") return false;
-      const message = JSON.parse(entry) as { type?: string; downlinkEncoding?: string };
-      return message.type === "codec_capability" && message.downlinkEncoding === "pcm_s16le";
-    }), { timeout: 3_000 });
-
-    vi.restoreAllMocks();
-  });
-});

package/tsconfig.json

@@ -1,21 +0,0 @@
-{
-  "compilerOptions": {
-    "target": "ES2022",
-    "module": "NodeNext",
-    "moduleResolution": "NodeNext",
-    "lib": ["ES2022", "DOM", "DOM.Iterable"],
-    "strict": true,
-    "noUncheckedIndexedAccess": true,
-    "noImplicitReturns": true,
-    "declaration": true,
-    "declarationMap": true,
-    "sourceMap": true,
-    "outDir": "./dist",
-    "rootDir": "./src",
-    "esModuleInterop": true,
-    "skipLibCheck": true,
-    "forceConsistentCasingInFileNames": true
-  },
-  "include": ["src/**/*.ts"],
-  "exclude": ["node_modules", "dist"]
-}