@kuralle-syrinx/openai-tts 4.2.0

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 Kuralle
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

package/README.md

@@ -0,0 +1,73 @@
+# @kuralle-syrinx/openai-tts
+
+OpenAI-compatible streaming TTS plugin for Syrinx.
+
+Supports any provider that implements the OpenAI `POST /audio/speech` endpoint with `stream: true` and returns raw mono s16le PCM. Configurable `base_url`, `api_key`, `model`, `voice`, `response_format`, `source_sample_rate_hz`, `sample_rate`, `tempo`, and `extra_body`.
+
+Includes a built-in WSOLA time-stretcher for pitch-preserving tempo control (e.g. `tempo: 0.9` to slow speech by 10%).
+
+## Usage
+
+### OpenAI (default)
+
+```ts
+import { OpenAICompatibleTTSPlugin } from "@kuralle-syrinx/openai-tts";
+
+const plugin = new OpenAICompatibleTTSPlugin();
+session.registerPlugin("tts", plugin);
+```
+
+Configuration:
+
+```ts
+{
+  api_key: "sk-...",                // or set OPENAI_API_KEY env
+  model: "gpt-4o-mini-tts",         // default
+  voice: "alloy",
+  response_format: "pcm",           // default
+  sample_rate: 16000,               // engine rate; default 16000
+  tempo: 1.0,                       // WSOLA stretch; default 1.0
+}
+```
+
+### Zeta (internal Sinhala TTS)
+
+Zeta is used purely via config — no special factory or import.
+
+```ts
+import { OpenAICompatibleTTSPlugin } from "@kuralle-syrinx/openai-tts";
+
+const plugin = new OpenAICompatibleTTSPlugin();
+session.registerPlugin("zeta", plugin);
+```
+
+Configuration:
+
+```ts
+{
+  base_url: "https://asyncdotengineering--zeta-tts-api-zetattsapi.us-east.modal.direct/v1",
+  api_key: "",                      // Zeta is unauthenticated
+  model: "zeta",
+  source_sample_rate_hz: 48000,     // Zeta outputs 48 kHz PCM
+  sample_rate: 24000,               // engine rate
+  tempo: 0.9,                       // 10% slower — Zeta prosody rushes
+  extra_body: {
+    task_type: "Base",
+    num_steps: 8,
+  },
+}
+```
+
+## Config reference
+
+| Key | Type | Default | Description |
+|---|---|---|---|
+| `base_url` | `string` | `https://api.openai.com/v1` | Provider base URL (must include `/v1`). Falls back to `OPENAI_BASE_URL` env. |
+| `api_key` | `string` | — | Bearer token. Falls back to `OPENAI_API_KEY` env. |
+| `model` | `string` | `gpt-4o-mini-tts` | TTS model name. |
+| `voice` | `string` | — | Voice identifier. Included in the request body only when set. |
+| `response_format` | `string` | `pcm` | Audio format. |
+| `source_sample_rate_hz` | `number` | `24000` | Provider's output PCM sample rate. |
+| `sample_rate` | `number` | `16000` | Engine sample rate to resample to. |
+| `tempo` | `number` | `1.0` | WSOLA time-stretch factor (`0.5`–`1.5`). |
+| `extra_body` | `object` | — | Merged into the request JSON body last (overrides defaults). |

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@kuralle-syrinx/openai-tts",
+  "version": "4.2.0",
+  "private": false,
+  "description": "OpenAI-compatible streaming TTS plugin for Syrinx",
+  "keywords": [
+    "voice",
+    "voice-agent",
+    "speech",
+    "syrinx",
+    "openai",
+    "text-to-speech",
+    "tts"
+  ],
+  "license": "MIT",
+  "homepage": "https://github.com/kuralle/syrinx#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kuralle/syrinx.git",
+    "directory": "packages/openai-tts"
+  },
+  "bugs": {
+    "url": "https://github.com/kuralle/syrinx/issues"
+  },
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "dependencies": {
+    "@kuralle-syrinx/core": "4.2.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.7.0",
+    "vitest": "^2.1.0"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  }
+}

package/src/index.test.ts

@@ -0,0 +1,393 @@
+// 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/index.ts

@@ -0,0 +1,287 @@
+// SPDX-License-Identifier: MIT
+//
+// Syrinx Kernel v2 — OpenAI-Compatible HTTP Streaming TTS Plugin
+//
+// Generic plugin for any OpenAI-compatible POST /audio/speech endpoint with
+// stream:true returning raw mono s16le PCM. Configurable base_url, api_key,
+// model, voice, response_format, source_sample_rate_hz, sample_rate, tempo,
+// and extra_body. Supports WSOLA time-stretch for tempo control.
+
+import type { PipelineBus } from "@kuralle-syrinx/core";
+import {
+  Route,
+  StreamingPcm16Resampler,
+  type PluginConfig,
+  type TextToSpeechAudioPacket,
+  type TextToSpeechEndPacket,
+  type TtsErrorPacket,
+  type VoicePlugin,
+  categorizeTtsError,
+  isRecoverable,
+  optionalStringConfig,
+} from "@kuralle-syrinx/core";
+
+import { WsolaTimeStretch } from "./wsola.js";
+export { WsolaTimeStretch } from "./wsola.js";
+
+const EMPTY = new Uint8Array(0);
+const DEFAULT_BASE_URL = "https://api.openai.com/v1";
+const DEFAULT_MODEL = "gpt-4o-mini-tts";
+const DEFAULT_RESPONSE_FORMAT = "pcm";
+const DEFAULT_SOURCE_SAMPLE_RATE_HZ = 24_000;
+const DEFAULT_ENGINE_RATE_HZ = 16_000;
+const DEFAULT_TEMPO = 1.0;
+const TEMPO_MIN = 0.5;
+const TEMPO_MAX = 1.5;
+
+export class OpenAICompatibleTTSPlugin implements VoicePlugin {
+  private bus: PipelineBus | null = null;
+  private baseUrl = DEFAULT_BASE_URL;
+  private apiKey = "";
+  private model = DEFAULT_MODEL;
+  private voice: string | undefined;
+  private responseFormat = DEFAULT_RESPONSE_FORMAT;
+  private sourceSampleRateHz = DEFAULT_SOURCE_SAMPLE_RATE_HZ;
+  private sampleRate = DEFAULT_ENGINE_RATE_HZ;
+  private tempo = DEFAULT_TEMPO;
+  private extraBody: Record<string, unknown> | undefined;
+  private disposers: Array<() => void> = [];
+  private inflight = new Set<AbortController>();
+
+  async initialize(bus: PipelineBus, config: PluginConfig): Promise<void> {
+    this.bus = bus;
+    this.baseUrl = stripTrailingSlash(
+      optionalStringConfig(config, "base_url") ??
+        processEnv("OPENAI_BASE_URL") ??
+        DEFAULT_BASE_URL,
+    );
+    this.apiKey =
+      optionalStringConfig(config, "api_key") ?? processEnv("OPENAI_API_KEY") ?? "";
+    this.model = optionalStringConfig(config, "model") ?? DEFAULT_MODEL;
+    this.voice = optionalStringConfig(config, "voice");
+    this.responseFormat = optionalStringConfig(config, "response_format") ?? DEFAULT_RESPONSE_FORMAT;
+    this.sourceSampleRateHz = readPositiveInteger(
+      config["source_sample_rate_hz"],
+      DEFAULT_SOURCE_SAMPLE_RATE_HZ,
+    );
+    this.sampleRate = readPositiveInteger(config["sample_rate"], DEFAULT_ENGINE_RATE_HZ);
+    this.tempo = readClampedTempo(config["tempo"], DEFAULT_TEMPO);
+    this.extraBody = readPlainObject(config["extra_body"]);
+
+    this.disposers.push(
+      bus.on("tts.text", async (pkt: unknown) => {
+        const textPkt = pkt as { text: string; contextId: string };
+        await this.synth(textPkt.text, textPkt.contextId);
+      }),
+      bus.on("interrupt.tts", () => {
+        this.abortInflight();
+      }),
+    );
+  }
+
+  async close(): Promise<void> {
+    this.abortInflight();
+    for (const dispose of this.disposers.splice(0)) dispose();
+    this.bus = null;
+  }
+
+  private abortInflight(): void {
+    for (const controller of this.inflight) {
+      controller.abort();
+    }
+    this.inflight.clear();
+  }
+
+  private async synth(text: string, contextId: string): Promise<void> {
+    if (!text.trim()) return;
+
+    const controller = new AbortController();
+    this.inflight.add(controller);
+
+    const speechUrl = `${this.baseUrl}/audio/speech`;
+    const headers: Record<string, string> = {
+      "Content-Type": "application/json",
+    };
+    if (this.apiKey) {
+      headers["Authorization"] = `Bearer ${this.apiKey}`;
+    }
+
+    const body: Record<string, unknown> = {
+      model: this.model,
+      input: text,
+      response_format: this.responseFormat,
+      stream: true,
+      ...this.extraBody,
+    };
+    if (this.voice !== undefined) {
+      body.voice = this.voice;
+    }
+
+    try {
+      const response = await fetch(speechUrl, {
+        method: "POST",
+        headers,
+        body: JSON.stringify(body),
+        signal: controller.signal,
+      });
+
+      if (!response.ok) {
+        if (response.status === 503) {
+          console.error(
+            "[openai-tts] cold start (HTTP 503) — provider may be warming up; keep-warm required for production",
+          );
+        }
+        const err = Object.assign(
+          new Error(
+            `OpenAI-compatible TTS HTTP ${String(response.status)}: ${response.statusText || "request failed"}`,
+          ),
+          { status: response.status },
+        );
+        this.emitError(contextId, err);
+        return;
+      }
+
+      const responseBody = response.body;
+      if (!responseBody) {
+        this.emitError(contextId, new Error("OpenAI-compatible TTS response body is null"));
+        return;
+      }
+
+      const reader = responseBody.getReader();
+      const resampler = new StreamingPcm16Resampler(this.sourceSampleRateHz, this.sampleRate);
+      const stretch =
+        Math.abs(this.tempo - 1) >= 1e-6
+          ? new WsolaTimeStretch(this.tempo, this.sampleRate)
+          : null;
+      let carry: Uint8Array = EMPTY;
+
+      while (true) {
+        if (controller.signal.aborted) return;
+        const { done, value } = await reader.read();
+        if (done) break;
+        if (!value || value.byteLength === 0) continue;
+
+        const frame = value instanceof Uint8Array ? value : new Uint8Array(value);
+        const buf = carry.byteLength === 0 ? frame : concatBytes(carry, frame);
+        const evenLen = buf.byteLength - (buf.byteLength % 2);
+        if (evenLen > 0) {
+          const pcmBytes = buf.subarray(0, evenLen);
+          const samples = bytesToInt16LE(pcmBytes);
+          const resampled = resampler.process(samples);
+          const stretched = stretch ? stretch.process(resampled) : resampled;
+          if (stretched.length > 0) {
+            this.emitAudio(contextId, stretched);
+          }
+        }
+        carry = evenLen < buf.byteLength ? buf.subarray(evenLen) : EMPTY;
+      }
+
+      if (controller.signal.aborted) return;
+      if (stretch) {
+        const tail = stretch.flush();
+        if (tail.length > 0) {
+          this.emitAudio(contextId, tail);
+        }
+      }
+      this.emitEnd(contextId);
+    } catch (err) {
+      if (isAbortError(err) || controller.signal.aborted) return;
+      this.emitError(contextId, err instanceof Error ? err : new Error(String(err)));
+    } finally {
+      this.inflight.delete(controller);
+    }
+  }
+
+  private emitError(contextId: string, err: Error): void {
+    const category = categorizeTtsError(err);
+    const packet: TtsErrorPacket = {
+      kind: "tts.error",
+      contextId,
+      timestampMs: Date.now(),
+      component: "tts",
+      category,
+      cause: err,
+      isRecoverable: isRecoverable(category),
+    };
+    this.bus?.push(Route.Critical, packet);
+  }
+
+  private emitAudio(contextId: string, samples: Int16Array): void {
+    const audio = int16ToBytes(samples);
+    const packet: TextToSpeechAudioPacket = {
+      kind: "tts.audio",
+      contextId,
+      timestampMs: Date.now(),
+      audio,
+      sampleRateHz: this.sampleRate,
+      provider: { name: "openai", model: this.model, cancelled: false },
+    };
+    this.bus?.push(Route.Main, packet);
+  }
+
+  private emitEnd(contextId: string): void {
+    this.bus?.push(Route.Main, {
+      kind: "tts.end",
+      contextId,
+      timestampMs: Date.now(),
+    } satisfies TextToSpeechEndPacket);
+  }
+}
+
+function processEnv(key: string): string | undefined {
+  try {
+    const value = (globalThis as { process?: { env?: Record<string, string | undefined> } }).process
+      ?.env?.[key];
+    return typeof value === "string" && value.trim().length > 0 ? value : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function stripTrailingSlash(url: string): string {
+  return url.endsWith("/") ? url.slice(0, -1) : url;
+}
+
+function readPositiveInteger(value: unknown, fallback: number): number {
+  if (typeof value !== "number" || !Number.isFinite(value)) return fallback;
+  const integer = Math.floor(value);
+  return integer > 0 ? integer : fallback;
+}
+
+function readClampedTempo(value: unknown, fallback: number): number {
+  if (typeof value !== "number" || !Number.isFinite(value)) return fallback;
+  if (value < TEMPO_MIN) return TEMPO_MIN;
+  if (value > TEMPO_MAX) return TEMPO_MAX;
+  return value;
+}
+
+function readPlainObject(value: unknown): Record<string, unknown> | undefined {
+  if (value !== null && typeof value === "object" && !Array.isArray(value)) {
+    return value as Record<string, unknown>;
+  }
+  return undefined;
+}
+
+function concatBytes(a: Uint8Array, b: Uint8Array): Uint8Array {
+  const out = new Uint8Array(a.byteLength + b.byteLength);
+  out.set(a, 0);
+  out.set(b, a.byteLength);
+  return out;
+}
+
+/** Copy into an owned ArrayBuffer so Int16Array is always 2-byte aligned. */
+function bytesToInt16LE(bytes: Uint8Array): Int16Array {
+  const ab = new ArrayBuffer(bytes.byteLength);
+  new Uint8Array(ab).set(bytes);
+  return new Int16Array(ab);
+}
+
+function int16ToBytes(samples: Int16Array): Uint8Array {
+  return new Uint8Array(samples.buffer, samples.byteOffset, samples.byteLength);
+}
+
+function isAbortError(err: unknown): boolean {
+  if (!err || typeof err !== "object") return false;
+  const name = (err as { name?: unknown }).name;
+  return name === "AbortError" || name === "TimeoutError";
+}

package/src/wsola.test.ts

@@ -0,0 +1,116 @@
+// 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/src/wsola.ts

@@ -0,0 +1,274 @@
+// SPDX-License-Identifier: MIT
+//
+// Streaming WSOLA (Waveform Similarity Overlap-Add) time-stretch.
+// Pitch-preserving tempo control: tempo < 1 slows, > 1 speeds, 1.0 passthrough.
+// Matches the intent of ffmpeg atempo without an ffmpeg runtime dependency.
+
+const PASSTHROUGH_EPS = 1e-6;
+const FRAME_MS = 0.03;
+const SEARCH_MS = 0.01;
+const INT16_MIN = -32768;
+const INT16_MAX = 32767;
+
+export class WsolaTimeStretch {
+  private readonly passthrough: boolean;
+  private readonly frame: number;
+  private readonly hs: number;
+  private readonly ha: number;
+  private readonly searchRadius: number;
+  private readonly window: Float64Array;
+
+  /** Accumulated input samples (float). */
+  private input: Float64Array = new Float64Array(0);
+  private inputLen = 0;
+  /** Absolute sample index of input[0] in the stream. */
+  private inputOrigin = 0;
+
+  /** Overlap-add synthesis buffer (float). */
+  private ola: Float64Array = new Float64Array(0);
+  private olaLen = 0;
+  /** Absolute synthesis index of ola[0]. */
+  private olaOrigin = 0;
+  /**
+   * Absolute synthesis index up to which samples are final (no further OLA).
+   * After placing a frame at absSynth, samples in [0, absSynth) are complete.
+   */
+  private emitThrough = 0;
+
+  /** Ideal analysis position (absolute input sample index). */
+  private analysisPos = 0;
+  /** Absolute synthesis index for the next frame. */
+  private synthPos = 0;
+  private havePrev = false;
+  /** Natural continuation of previous frame (hs samples) for waveform matching. */
+  private prevContinuation: Float64Array;
+
+  constructor(tempo: number, sampleRateHz: number) {
+    if (!(sampleRateHz > 0) || !Number.isFinite(sampleRateHz)) {
+      throw new RangeError(`WsolaTimeStretch: invalid sampleRateHz ${String(sampleRateHz)}`);
+    }
+    if (!Number.isFinite(tempo) || tempo <= 0) {
+      throw new RangeError(`WsolaTimeStretch: invalid tempo ${String(tempo)}`);
+    }
+
+    this.passthrough = Math.abs(tempo - 1) < PASSTHROUGH_EPS;
+    this.frame = Math.max(2, Math.round(FRAME_MS * sampleRateHz));
+    this.hs = Math.max(1, Math.floor(this.frame / 2));
+    this.ha = Math.max(1, Math.round(this.hs * tempo));
+    this.searchRadius = Math.max(0, Math.round(SEARCH_MS * sampleRateHz));
+    this.window = hann(this.frame);
+    this.prevContinuation = new Float64Array(this.hs);
+  }
+
+  process(input: Int16Array): Int16Array {
+    if (this.passthrough) return input;
+    if (input.length > 0) this.appendInput(input);
+    return this.extractReady(false);
+  }
+
+  flush(): Int16Array {
+    if (this.passthrough) return new Int16Array(0);
+    return this.extractReady(true);
+  }
+
+  private appendInput(samples: Int16Array): void {
+    this.ensureInputCapacity(this.inputLen + samples.length);
+    for (let i = 0; i < samples.length; i++) {
+      this.input[this.inputLen + i] = samples[i]!;
+    }
+    this.inputLen += samples.length;
+  }
+
+  private extractReady(flushing: boolean): Int16Array {
+    while (this.tryAddFrame(flushing)) {
+      // keep consuming frames while input allows
+    }
+
+    if (flushing) {
+      this.emitThrough = this.olaOrigin + this.olaLen;
+    }
+
+    const ready = this.emitThrough - this.olaOrigin;
+    if (ready <= 0) return new Int16Array(0);
+
+    const out = new Int16Array(ready);
+    for (let i = 0; i < ready; i++) {
+      out[i] = clampInt16(this.ola[i]!);
+    }
+
+    const remaining = this.olaLen - ready;
+    if (remaining > 0) {
+      this.ola.copyWithin(0, ready, this.olaLen);
+    }
+    this.ola.fill(0, remaining, this.olaLen);
+    this.olaLen = remaining;
+    this.olaOrigin += ready;
+
+    if (flushing) {
+      this.inputLen = 0;
+      this.inputOrigin = this.analysisPos;
+    } else {
+      this.compactInput();
+    }
+
+    return out;
+  }
+
+  /**
+   * Place one more synthesis frame via WSOLA.
+   * @returns false when more input is needed or the stream is exhausted.
+   */
+  private tryAddFrame(flushing: boolean): boolean {
+    const frame = this.frame;
+    const hs = this.hs;
+    const search = this.searchRadius;
+    const inputEnd = this.inputOrigin + this.inputLen;
+
+    if (!this.havePrev) {
+      if (inputEnd < frame) return false;
+      const localStart = 0;
+      this.olaAddFrame(localStart, 0);
+      this.storeContinuation(localStart);
+      this.havePrev = true;
+      this.analysisPos = this.ha;
+      this.synthPos = hs;
+      // Samples [0, hs) still receive the next frame's OLA contribution.
+      this.emitThrough = 0;
+      return true;
+    }
+
+    // Need a full frame at some position in [ideal - search, ideal + search].
+    const ideal = this.analysisPos;
+    if (!flushing) {
+      // Require full right-side search room so offsets are unbiased while streaming.
+      if (inputEnd < ideal + frame + search) return false;
+    } else {
+      // On flush, accept any position that can hold a frame near the ideal.
+      if (inputEnd < ideal - search + frame && inputEnd < frame) return false;
+      if (inputEnd - this.inputOrigin < frame) return false;
+      // If even the earliest searchable start cannot fit a frame, stop.
+      const latestStart = inputEnd - frame;
+      if (latestStart < Math.max(this.inputOrigin, ideal - search)) return false;
+    }
+
+    const bestLocal = this.findBestOffset(ideal);
+    const absSynth = this.synthPos;
+    this.olaAddFrame(bestLocal, absSynth);
+    this.storeContinuation(bestLocal);
+    this.analysisPos = ideal + this.ha;
+    this.synthPos = absSynth + hs;
+    // After placing frame at absSynth, no future frame touches [0, absSynth).
+    this.emitThrough = absSynth;
+    return true;
+  }
+
+  private findBestOffset(idealAbs: number): number {
+    const frame = this.frame;
+    const hs = this.hs;
+    const search = this.searchRadius;
+    const inputEnd = this.inputOrigin + this.inputLen;
+    const earliest = Math.max(this.inputOrigin, idealAbs - search);
+    const latest = Math.min(inputEnd - frame, idealAbs + search);
+
+    if (latest < earliest) {
+      const fallbackAbs = Math.min(
+        Math.max(idealAbs, this.inputOrigin),
+        Math.max(this.inputOrigin, inputEnd - frame),
+      );
+      return fallbackAbs - this.inputOrigin;
+    }
+
+    let bestLocal = earliest - this.inputOrigin;
+    let bestScore = -Infinity;
+
+    for (let abs = earliest; abs <= latest; abs++) {
+      const local = abs - this.inputOrigin;
+      let score = 0;
+      for (let i = 0; i < hs; i++) {
+        score += this.input[local + i]! * this.prevContinuation[i]!;
+      }
+      if (score > bestScore) {
+        bestScore = score;
+        bestLocal = local;
+      }
+    }
+    return bestLocal;
+  }
+
+  private olaAddFrame(localStart: number, absSynth: number): void {
+    const frame = this.frame;
+    const localOla = absSynth - this.olaOrigin;
+    const needLen = localOla + frame;
+    this.ensureOlaCapacity(needLen);
+    if (needLen > this.olaLen) {
+      if (this.olaLen < localOla) {
+        this.ola.fill(0, this.olaLen, localOla);
+      }
+      this.olaLen = needLen;
+    }
+    for (let i = 0; i < frame; i++) {
+      const sample = localStart + i < this.inputLen ? this.input[localStart + i]! : 0;
+      this.ola[localOla + i]! += sample * this.window[i]!;
+    }
+  }
+
+  private storeContinuation(localStart: number): void {
+    const hs = this.hs;
+    for (let i = 0; i < hs; i++) {
+      const idx = localStart + hs + i;
+      this.prevContinuation[i] = idx < this.inputLen ? this.input[idx]! : 0;
+    }
+  }
+
+  private compactInput(): void {
+    const keepFromAbs = Math.max(0, this.analysisPos - this.searchRadius);
+    if (keepFromAbs <= this.inputOrigin) return;
+    const drop = keepFromAbs - this.inputOrigin;
+    if (drop <= 0) return;
+    if (drop >= this.inputLen) {
+      this.inputLen = 0;
+      this.inputOrigin = keepFromAbs;
+      return;
+    }
+    this.input.copyWithin(0, drop, this.inputLen);
+    this.inputLen -= drop;
+    this.inputOrigin = keepFromAbs;
+  }
+
+  private ensureInputCapacity(needed: number): void {
+    if (needed <= this.input.length) return;
+    const cap = Math.max(needed, this.input.length > 0 ? this.input.length * 2 : 1024);
+    const next = new Float64Array(cap);
+    next.set(this.input.subarray(0, this.inputLen));
+    this.input = next;
+  }
+
+  private ensureOlaCapacity(needed: number): void {
+    if (needed <= this.ola.length) return;
+    const cap = Math.max(needed, this.ola.length > 0 ? this.ola.length * 2 : 1024);
+    const next = new Float64Array(cap);
+    next.set(this.ola.subarray(0, this.olaLen));
+    this.ola = next;
+  }
+}
+
+/** Symmetric Hann window; 50% overlap is COLA (overlapping windows sum ≈ 1). */
+function hann(n: number): Float64Array {
+  const w = new Float64Array(n);
+  if (n === 1) {
+    w[0] = 1;
+    return w;
+  }
+  const denom = n - 1;
+  for (let i = 0; i < n; i++) {
+    w[i] = 0.5 * (1 - Math.cos((2 * Math.PI * i) / denom));
+  }
+  return w;
+}
+
+function clampInt16(x: number): number {
+  const r = Math.round(x);
+  if (r < INT16_MIN) return INT16_MIN;
+  if (r > INT16_MAX) return INT16_MAX;
+  return r;
+}

package/tsconfig.json

@@ -0,0 +1,21 @@
+{
+  "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"]
+}