@kuralle-syrinx/openai-tts 4.2.0 → 4.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kuralle-syrinx/openai-tts",
-  "version": "4.2.0",
+  "version": "4.4.0",
   "private": false,
   "description": "OpenAI-compatible streaming TTS plugin for Syrinx",
   "keywords": [
@@ -26,11 +26,11 @@
   "main": "./src/index.ts",
   "types": "./src/index.ts",
   "dependencies": {
-    "@kuralle-syrinx/core": "4.2.0"
+    "@kuralle-syrinx/core": "4.4.0"
   },
   "devDependencies": {
     "typescript": "^5.7.0",
-    "vitest": "^2.1.0"
+    "vitest": "^3.2.6"
   },
   "scripts": {
     "typecheck": "tsc --noEmit",

package/src/index.ts

@@ -85,6 +85,26 @@ export class OpenAICompatibleTTSPlugin implements VoicePlugin {
     this.bus = null;
   }
 
+  async prewarm(): Promise<void> {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), 8_000);
+    try {
+      const headers: Record<string, string> = {};
+      if (this.apiKey) {
+        headers["Authorization"] = `Bearer ${this.apiKey}`;
+      }
+      await fetch(`${this.baseUrl}/models`, {
+        method: "GET",
+        headers,
+        signal: controller.signal,
+      });
+    } catch {
+      // best-effort
+    } finally {
+      clearTimeout(timeout);
+    }
+  }
+
   private abortInflight(): void {
     for (const controller of this.inflight) {
       controller.abort();
@@ -183,6 +203,7 @@ export class OpenAICompatibleTTSPlugin implements VoicePlugin {
           this.emitAudio(contextId, tail);
         }
       }
+      this.emitUsage(contextId, text.length);
       this.emitEnd(contextId);
     } catch (err) {
       if (isAbortError(err) || controller.signal.aborted) return;
@@ -219,6 +240,19 @@ export class OpenAICompatibleTTSPlugin implements VoicePlugin {
     this.bus?.push(Route.Main, packet);
   }
 
+  private emitUsage(contextId: string, characters: number): void {
+    if (characters <= 0) return;
+    this.bus?.push(Route.Background, {
+      kind: "usage.recorded",
+      contextId,
+      timestampMs: Date.now(),
+      stage: "tts",
+      provider: "openai",
+      model: this.model,
+      characters,
+    });
+  }
+
   private emitEnd(contextId: string): void {
     this.bus?.push(Route.Main, {
       kind: "tts.end",

package/src/index.test.ts

@@ -1,393 +0,0 @@
-// SPDX-License-Identifier: MIT
-
-import { afterEach, describe, expect, it, vi } from "vitest";
-import {
-  PipelineBusImpl,
-  Route,
-  type TextToSpeechAudioPacket,
-  type TextToSpeechEndPacket,
-  type TtsErrorPacket,
-} from "@kuralle-syrinx/core";
-
-import { OpenAICompatibleTTSPlugin } from "./index.js";
-
-function startBus(bus: PipelineBusImpl): Promise<void> {
-  return bus.start();
-}
-
-async function waitForCondition(predicate: () => boolean, timeoutMs = 2000): Promise<void> {
-  const startedAt = Date.now();
-  while (Date.now() - startedAt < timeoutMs) {
-    if (predicate()) return;
-    await new Promise((resolve) => setTimeout(resolve, 10));
-  }
-  throw new Error("Timed out waiting for openai-tts test condition");
-}
-
-/** Minimal mono s16le silence: `sampleCount` samples (`sampleCount * 2` bytes). */
-function pcmSilence(sampleCount: number): Uint8Array {
-  return new Uint8Array(sampleCount * 2);
-}
-
-function streamFromChunks(chunks: Uint8Array[]): ReadableStream<Uint8Array> {
-  let i = 0;
-  return new ReadableStream({
-    pull(controller) {
-      if (i >= chunks.length) {
-        controller.close();
-        return;
-      }
-      controller.enqueue(chunks[i]!);
-      i += 1;
-    },
-  });
-}
-
-afterEach(() => {
-  vi.unstubAllGlobals();
-  vi.restoreAllMocks();
-});
-
-describe("OpenAICompatibleTTSPlugin", () => {
-  it("POSTs speech body with stream, pcm, and extra_body merged", async () => {
-    const fetchMock = vi.fn(async (_url: string | URL | Request, init?: RequestInit) => {
-      return new Response(streamFromChunks([pcmSilence(8)]), {
-        status: 200,
-        headers: { "Content-Type": "application/octet-stream" },
-      });
-    });
-    vi.stubGlobal("fetch", fetchMock);
-
-    const bus = new PipelineBusImpl();
-    const started = startBus(bus);
-    const plugin = new OpenAICompatibleTTSPlugin();
-    const ends: TextToSpeechEndPacket[] = [];
-    bus.on("tts.end", (pkt) => {
-      ends.push(pkt as TextToSpeechEndPacket);
-    });
-
-    await plugin.initialize(bus, {
-      base_url: "https://zeta.test/v1",
-      sample_rate: 16000,
-      extra_body: { task_type: "Base", num_steps: 8 },
-    });
-
-    bus.push(Route.Main, {
-      kind: "tts.text",
-      contextId: "turn-1",
-      timestampMs: Date.now(),
-      text: "ආයුබෝවන්",
-    });
-    await waitForCondition(() => ends.length >= 1);
-
-    expect(fetchMock).toHaveBeenCalledTimes(1);
-    const [url, init] = fetchMock.mock.calls[0]!;
-    expect(String(url)).toBe("https://zeta.test/v1/audio/speech");
-    expect(init?.method).toBe("POST");
-    const body = JSON.parse(String(init?.body)) as Record<string, unknown>;
-    expect(body).toEqual({
-      model: "gpt-4o-mini-tts",
-      input: "ආයුබෝවන්",
-      response_format: "pcm",
-      stream: true,
-      task_type: "Base",
-      num_steps: 8,
-    });
-    expect((init?.headers as Record<string, string>)["Content-Type"]).toBe("application/json");
-
-    await plugin.close();
-    bus.stop();
-    await started;
-  });
-
-  it("includes voice in body only when configured", async () => {
-    const fetchMock = vi.fn(async (_url: string | URL | Request, init?: RequestInit) => {
-      return new Response(streamFromChunks([pcmSilence(8)]), {
-        status: 200,
-        headers: { "Content-Type": "application/octet-stream" },
-      });
-    });
-    vi.stubGlobal("fetch", fetchMock);
-
-    const bus = new PipelineBusImpl();
-    const started = startBus(bus);
-    const plugin = new OpenAICompatibleTTSPlugin();
-    const ends: TextToSpeechEndPacket[] = [];
-    bus.on("tts.end", (pkt) => {
-      ends.push(pkt as TextToSpeechEndPacket);
-    });
-
-    await plugin.initialize(bus, {
-      base_url: "https://openai.test/v1",
-      api_key: "sk-test",
-      voice: "alloy",
-      sample_rate: 16000,
-    });
-
-    bus.push(Route.Main, {
-      kind: "tts.text",
-      contextId: "turn-voice",
-      timestampMs: Date.now(),
-      text: "hello",
-    });
-    await waitForCondition(() => ends.length >= 1);
-
-    const [_url, init] = fetchMock.mock.calls[0]!;
-    const body = JSON.parse(String(init?.body)) as Record<string, unknown>;
-    expect(body.voice).toBe("alloy");
-    expect((init?.headers as Record<string, string>)["Authorization"]).toBe("Bearer sk-test");
-
-    await plugin.close();
-    bus.stop();
-    await started;
-  });
-
-  it("omits voice key when voice is not configured", async () => {
-    const fetchMock = vi.fn(async (_url: string | URL | Request, init?: RequestInit) => {
-      return new Response(streamFromChunks([pcmSilence(8)]), {
-        status: 200,
-        headers: { "Content-Type": "application/octet-stream" },
-      });
-    });
-    vi.stubGlobal("fetch", fetchMock);
-
-    const bus = new PipelineBusImpl();
-    const started = startBus(bus);
-    const plugin = new OpenAICompatibleTTSPlugin();
-    const ends: TextToSpeechEndPacket[] = [];
-    bus.on("tts.end", (pkt) => {
-      ends.push(pkt as TextToSpeechEndPacket);
-    });
-
-    await plugin.initialize(bus, {
-      base_url: "https://openai.test/v1",
-      sample_rate: 16000,
-    });
-
-    bus.push(Route.Main, {
-      kind: "tts.text",
-      contextId: "turn-no-voice",
-      timestampMs: Date.now(),
-      text: "hi",
-    });
-    await waitForCondition(() => ends.length >= 1);
-
-    const [_url, init] = fetchMock.mock.calls[0]!;
-    const body = JSON.parse(String(init?.body)) as Record<string, unknown>;
-    expect(body).not.toHaveProperty("voice");
-
-    await plugin.close();
-    bus.stop();
-    await started;
-  });
-
-  it("streams PCM into tts.audio at engine sampleRateHz then tts.end", async () => {
-    // Two chunks with an odd-byte split so the plugin must carry across frames.
-    const full = pcmSilence(48); // 96 bytes
-    const chunkA = full.subarray(0, 15); // odd
-    const chunkB = full.subarray(15);
-
-    vi.stubGlobal(
-      "fetch",
-      vi.fn(async () => {
-        return new Response(streamFromChunks([chunkA, chunkB]), {
-          status: 200,
-          headers: { "Content-Type": "application/octet-stream" },
-        });
-      }),
-    );
-
-    const bus = new PipelineBusImpl();
-    const started = startBus(bus);
-    const plugin = new OpenAICompatibleTTSPlugin();
-    const audio: TextToSpeechAudioPacket[] = [];
-    const ends: TextToSpeechEndPacket[] = [];
-    bus.on("tts.audio", (pkt) => {
-      audio.push(pkt as TextToSpeechAudioPacket);
-    });
-    bus.on("tts.end", (pkt) => {
-      ends.push(pkt as TextToSpeechEndPacket);
-    });
-
-    await plugin.initialize(bus, {
-      base_url: "https://openai.test/v1",
-      sample_rate: 16000,
-    });
-
-    bus.push(Route.Main, {
-      kind: "tts.text",
-      contextId: "turn-2",
-      timestampMs: Date.now(),
-      text: "hello",
-    });
-    await waitForCondition(() => ends.length >= 1);
-
-    expect(audio.length).toBeGreaterThanOrEqual(1);
-    for (const pkt of audio) {
-      expect(pkt.kind).toBe("tts.audio");
-      expect(pkt.contextId).toBe("turn-2");
-      expect(pkt.sampleRateHz).toBe(16000);
-      expect(pkt.audio.byteLength % 2).toBe(0);
-      expect(pkt.audio.byteLength).toBeGreaterThan(0);
-    }
-    expect(ends).toEqual([expect.objectContaining({ kind: "tts.end", contextId: "turn-2" })]);
-
-    await plugin.close();
-    bus.stop();
-    await started;
-  });
-
-  it("source_sample_rate_hz drives the resampler output length", async () => {
-    // 96 bytes = 48 samples. Different source rates → different resampled lengths.
-    const pcm48k = pcmSilence(48);
-
-    async function collectAudioBytes(sourceRate: number): Promise<number> {
-      vi.stubGlobal(
-        "fetch",
-        vi.fn(async () => {
-          return new Response(streamFromChunks([pcm48k]), {
-            status: 200,
-            headers: { "Content-Type": "application/octet-stream" },
-          });
-        }),
-      );
-
-      const bus = new PipelineBusImpl();
-      const started = startBus(bus);
-      const plugin = new OpenAICompatibleTTSPlugin();
-      let totalBytes = 0;
-      const ends: TextToSpeechEndPacket[] = [];
-      bus.on("tts.audio", (pkt) => {
-        totalBytes += (pkt as TextToSpeechAudioPacket).audio.byteLength;
-      });
-      bus.on("tts.end", (pkt) => {
-        ends.push(pkt as TextToSpeechEndPacket);
-      });
-
-      await plugin.initialize(bus, {
-        base_url: "https://openai.test/v1",
-        sample_rate: 16000,
-        source_sample_rate_hz: sourceRate,
-      });
-
-      bus.push(Route.Main, {
-        kind: "tts.text",
-        contextId: `rate-${String(sourceRate)}`,
-        timestampMs: Date.now(),
-        text: "test",
-      });
-      await waitForCondition(() => ends.length >= 1);
-
-      await plugin.close();
-      bus.stop();
-      await started;
-      vi.unstubAllGlobals();
-      return totalBytes;
-    }
-
-    const bytesAt48k = await collectAudioBytes(48_000);
-    const bytesAt24k = await collectAudioBytes(24_000);
-    expect(bytesAt48k).toBeGreaterThan(0);
-    expect(bytesAt24k).toBeGreaterThan(bytesAt48k);
-  });
-
-  it("tempo: 0.9 produces more tts.audio bytes than tempo: 1.0 for the same PCM stream", async () => {
-    // ~100 ms of 24 kHz silence → enough samples after resample for WSOLA to stretch.
-    const pcm = pcmSilence(2400);
-
-    async function collectAudioBytes(tempo: number): Promise<number> {
-      vi.stubGlobal(
-        "fetch",
-        vi.fn(async () => {
-          return new Response(streamFromChunks([pcm]), {
-            status: 200,
-            headers: { "Content-Type": "application/octet-stream" },
-          });
-        }),
-      );
-
-      const bus = new PipelineBusImpl();
-      const started = startBus(bus);
-      const plugin = new OpenAICompatibleTTSPlugin();
-      let totalBytes = 0;
-      const ends: TextToSpeechEndPacket[] = [];
-      bus.on("tts.audio", (pkt) => {
-        totalBytes += (pkt as TextToSpeechAudioPacket).audio.byteLength;
-      });
-      bus.on("tts.end", (pkt) => {
-        ends.push(pkt as TextToSpeechEndPacket);
-      });
-
-      await plugin.initialize(bus, {
-        base_url: "https://openai.test/v1",
-        sample_rate: 16000,
-        tempo,
-      });
-
-      bus.push(Route.Main, {
-        kind: "tts.text",
-        contextId: `tempo-${String(tempo)}`,
-        timestampMs: Date.now(),
-        text: "slow",
-      });
-      await waitForCondition(() => ends.length >= 1);
-
-      await plugin.close();
-      bus.stop();
-      await started;
-      vi.unstubAllGlobals();
-      return totalBytes;
-    }
-
-    const bytesAt1 = await collectAudioBytes(1.0);
-    const bytesAt09 = await collectAudioBytes(0.9);
-    expect(bytesAt1).toBeGreaterThan(0);
-    expect(bytesAt09).toBeGreaterThan(bytesAt1);
-  });
-
-  it("maps HTTP 503 to a recoverable tts.error", async () => {
-    const errorLog = vi.spyOn(console, "error").mockImplementation(() => {});
-    vi.stubGlobal(
-      "fetch",
-      vi.fn(async () => new Response("Service Unavailable", { status: 503 })),
-    );
-
-    const bus = new PipelineBusImpl();
-    const started = startBus(bus);
-    const plugin = new OpenAICompatibleTTSPlugin();
-    const errors: TtsErrorPacket[] = [];
-    bus.on("tts.error", (pkt) => {
-      errors.push(pkt as TtsErrorPacket);
-    });
-
-    await plugin.initialize(bus, {
-      base_url: "https://openai.test/v1",
-      sample_rate: 16000,
-    });
-
-    bus.push(Route.Main, {
-      kind: "tts.text",
-      contextId: "turn-cold",
-      timestampMs: Date.now(),
-      text: "cold",
-    });
-    await waitForCondition(() => errors.length >= 1);
-
-    expect(errors).toEqual([
-      expect.objectContaining({
-        kind: "tts.error",
-        contextId: "turn-cold",
-        component: "tts",
-        isRecoverable: true,
-      }),
-    ]);
-    expect(errorLog).toHaveBeenCalledWith(
-      expect.stringContaining("[openai-tts] cold start"),
-    );
-
-    await plugin.close();
-    bus.stop();
-    await started;
-    errorLog.mockRestore();
-  });
-});

package/src/wsola.test.ts

@@ -1,116 +0,0 @@
-// SPDX-License-Identifier: MIT
-
-import { describe, expect, it } from "vitest";
-import { WsolaTimeStretch } from "./wsola.js";
-
-const SR = 24_000;
-const FREQ_HZ = 220;
-const DURATION_S = 1;
-
-function sinePcm16(sampleRateHz: number, freqHz: number, durationS: number): Int16Array {
-  const n = Math.round(sampleRateHz * durationS);
-  const out = new Int16Array(n);
-  const amp = 16000;
-  for (let i = 0; i < n; i++) {
-    out[i] = Math.round(amp * Math.sin((2 * Math.PI * freqHz * i) / sampleRateHz));
-  }
-  return out;
-}
-
-/** Mean period (samples) between successive rising zero-crossings. */
-function meanRisingZeroCrossingPeriod(samples: Int16Array): number {
-  const crossings: number[] = [];
-  for (let i = 1; i < samples.length; i++) {
-    const prev = samples[i - 1]!;
-    const cur = samples[i]!;
-    if (prev < 0 && cur >= 0) {
-      // Linear interpolate fractional index
-      const frac = prev === cur ? 0 : prev / (prev - cur);
-      crossings.push(i - 1 + frac);
-    }
-  }
-  if (crossings.length < 2) {
-    throw new Error(`too few zero-crossings: ${String(crossings.length)}`);
-  }
-  let sum = 0;
-  for (let i = 1; i < crossings.length; i++) {
-    sum += crossings[i]! - crossings[i - 1]!;
-  }
-  return sum / (crossings.length - 1);
-}
-
-function stretchAll(tempo: number, input: Int16Array, sampleRateHz = SR): Int16Array {
-  const s = new WsolaTimeStretch(tempo, sampleRateHz);
-  const a = s.process(input);
-  const b = s.flush();
-  const out = new Int16Array(a.length + b.length);
-  out.set(a, 0);
-  out.set(b, a.length);
-  return out;
-}
-
-function stretchChunked(tempo: number, input: Int16Array, chunkSize: number, sampleRateHz = SR): Int16Array {
-  const s = new WsolaTimeStretch(tempo, sampleRateHz);
-  const parts: Int16Array[] = [];
-  for (let i = 0; i < input.length; i += chunkSize) {
-    const chunk = input.subarray(i, Math.min(i + chunkSize, input.length));
-    const out = s.process(chunk);
-    if (out.length > 0) parts.push(out);
-  }
-  const tail = s.flush();
-  if (tail.length > 0) parts.push(tail);
-  let total = 0;
-  for (const p of parts) total += p.length;
-  const out = new Int16Array(total);
-  let off = 0;
-  for (const p of parts) {
-    out.set(p, off);
-    off += p.length;
-  }
-  return out;
-}
-
-describe("WsolaTimeStretch", () => {
-  const input = sinePcm16(SR, FREQ_HZ, DURATION_S);
-  const frame = Math.round(0.03 * SR);
-
-  it("length scaling: tempo=0.9 lengthens output ≈ input/tempo (±1 frame)", () => {
-    const out = stretchAll(0.9, input);
-    const expected = input.length / 0.9;
-    expect(Math.abs(out.length - expected)).toBeLessThanOrEqual(frame);
-  });
-
-  it("length scaling: tempo=1.2 shortens output ≈ input/tempo (±1 frame)", () => {
-    const out = stretchAll(1.2, input);
-    const expected = input.length / 1.2;
-    expect(Math.abs(out.length - expected)).toBeLessThanOrEqual(frame);
-  });
-
-  it("pitch preserved: tempo=0.9 zero-crossing period matches input within 5%", () => {
-    const out = stretchAll(0.9, input);
-    // Skip a short edge region where OLA windowing is incomplete
-    const skip = frame;
-    const inPeriod = meanRisingZeroCrossingPeriod(input.subarray(skip, input.length - skip));
-    const outPeriod = meanRisingZeroCrossingPeriod(out.subarray(skip, out.length - skip));
-    const relErr = Math.abs(outPeriod - inPeriod) / inPeriod;
-    expect(relErr).toBeLessThanOrEqual(0.05);
-  });
-
-  it("passthrough: tempo=1.0 returns input samples unchanged", () => {
-    const s = new WsolaTimeStretch(1.0, SR);
-    const out = s.process(input);
-    expect(out.length).toBe(input.length);
-    expect(out).toBe(input); // same reference — zero-cost passthrough
-    for (let i = 0; i < input.length; i++) {
-      expect(out[i]).toBe(input[i]);
-    }
-    const tail = s.flush();
-    expect(tail.length).toBe(0);
-  });
-
-  it("streaming invariance: one chunk vs many small chunks → same total length (±1 frame)", () => {
-    const one = stretchAll(0.9, input);
-    const many = stretchChunked(0.9, input, 64);
-    expect(Math.abs(one.length - many.length)).toBeLessThanOrEqual(frame);
-  });
-});

package/tsconfig.json

@@ -1,21 +0,0 @@
-{
-  "compilerOptions": {
-    "target": "ES2022",
-    "module": "NodeNext",
-    "moduleResolution": "NodeNext",
-    "lib": ["ES2022", "DOM"],
-    "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"]
-}