@pipedog/openai 0.0.0 → 0.4.0

package/dist/tts.d.ts

@@ -0,0 +1,86 @@
+import { type Frame, type StartFrame } from "@pipedog/core/frames/frames";
+import { TTSSettings, type TTSSettingsOptions } from "@pipedog/core/services/settings";
+import { TTSService, type TTSServiceOptions } from "@pipedog/core/services/tts_service";
+import { type NotGiven } from "@pipedog/core/utils/types";
+import OpenAI from "openai";
+export type ValidVoice = "alloy" | "ash" | "ballad" | "cedar" | "coral" | "echo" | "fable" | "marin" | "nova" | "onyx" | "sage" | "shimmer" | "verse";
+export declare const VALID_VOICES: Readonly<Record<string, ValidVoice>>;
+export interface OpenAITTSSettingsOptions extends TTSSettingsOptions {
+    /** Instructions to guide voice synthesis behavior. */
+    instructions?: string | null | NotGiven;
+    /** Voice speed control (0.25 to 4.0, default 1.0). */
+    speed?: number | null | NotGiven;
+}
+/**
+ * Settings for OpenAITTSService.
+ *
+ * - `instructions`: instructions to guide voice synthesis behavior.
+ * - `speed`: voice speed control (0.25 to 4.0, default 1.0).
+ */
+export declare class OpenAITTSSettings extends TTSSettings {
+    instructions: string | null | NotGiven;
+    speed: number | null | NotGiven;
+    constructor(options?: OpenAITTSSettingsOptions);
+}
+export interface OpenAITTSServiceOptions extends TTSServiceOptions {
+    /** OpenAI API key for authentication. If null, uses environment variable. */
+    apiKey?: string | null;
+    /** Custom base URL for OpenAI API. If null, uses default. */
+    baseUrl?: string | null;
+    /**
+     * Custom `fetch` for API requests, e.g. one with a longer request timeout.
+     * Defaults to null, which lets the SDK use its own.
+     *
+     * DIVERGENCE: upstream takes an httpx client here.
+     */
+    httpClient?: typeof fetch | null;
+    /** Runtime-updatable settings. */
+    settings?: OpenAITTSSettings | null;
+}
+/**
+ * OpenAI Text-to-Speech service that generates audio from text.
+ *
+ * This service uses the OpenAI TTS API to generate PCM-encoded audio at
+ * 24kHz. Supports multiple voice models and configurable parameters for
+ * high-quality speech synthesis with streaming audio output.
+ */
+export declare class OpenAITTSService extends TTSService {
+    static Settings: typeof OpenAITTSSettings;
+    protected _settings: OpenAITTSSettings;
+    protected _client: OpenAI;
+    /**
+     * Initialize OpenAI TTS service.
+     *
+     * @param options.apiKey OpenAI API key for authentication. If null, uses
+     *   environment variable.
+     * @param options.baseUrl Custom base URL for OpenAI API. If null, uses default.
+     * @param options.httpClient Custom `fetch` for API requests.
+     * @param options.sampleRate Output audio sample rate in Hz. If null, uses
+     *   OpenAI's default 24kHz.
+     * @param options.settings Runtime-updatable settings. Its given fields
+     *   override the defaults (model "gpt-4o-mini-tts", voice "alloy").
+     *   Other options are passed to TTSService.
+     */
+    constructor(options?: OpenAITTSServiceOptions);
+    /**
+     * Check if this service can generate processing metrics.
+     *
+     * @returns True, as OpenAI TTS service supports metrics generation.
+     */
+    canGenerateMetrics(): boolean;
+    /**
+     * Start the OpenAI TTS service.
+     *
+     * @param frame The start frame containing initialization parameters.
+     */
+    start(frame: StartFrame): Promise<void>;
+    /**
+     * Generate speech from text using OpenAI's TTS API.
+     *
+     * @param text The text to synthesize into speech.
+     * @param contextId The context ID for tracking audio frames.
+     * @returns Audio frames containing the synthesized speech data.
+     */
+    runTts(text: string, contextId: string): AsyncGenerator<Frame, void>;
+}
+//# sourceMappingURL=tts.d.ts.map

package/dist/tts.js

@@ -0,0 +1,238 @@
+// Copyright (c) 2024-2026, Daily
+// Copyright (c) 2026, pipedog contributors
+// SPDX-License-Identifier: BSD-2-Clause
+//
+// Ported from pipecat: src/pipecat/services/openai/tts.py
+/**
+ * OpenAI text-to-speech service implementation.
+ *
+ * This module provides integration with OpenAI's text-to-speech API for
+ * generating high-quality synthetic speech from text input.
+ *
+ * Porting notes:
+ * - The client is `OpenAI` from the `openai` JS SDK (fetch based). The
+ *   streamed body is read from the `Response` the SDK returns, re-chunked to
+ *   `chunkSize` bytes as `iter_bytes(chunk_size)` does.
+ * - `httpClient` is the SDK's `fetch` option (upstream: an httpx client).
+ * - Deprecated APIs are not ported: `OpenAITTSService.InputParams` and the
+ *   `voice`, `model`, `instructions`, `speed` and `params` constructor
+ *   options.
+ */
+import { abortable, currentSignal, rethrowIfCancelled } from "@pipedog/asyncio";
+import { ErrorFrame, TTSAudioRawFrame, } from "@pipedog/core/frames/frames";
+import { TTSSettings } from "@pipedog/core/services/settings";
+import { TTSService } from "@pipedog/core/services/tts_service";
+import { logger } from "@pipedog/core/utils/logger";
+import { installTracedTts } from "@pipedog/core/utils/tracing/service_decorators";
+import { assertGiven, NOT_GIVEN } from "@pipedog/core/utils/types";
+import OpenAI, { BadRequestError } from "openai";
+import { OPENAI_SAMPLE_RATE } from "./_constants.js";
+export const VALID_VOICES = {
+    alloy: "alloy",
+    ash: "ash",
+    ballad: "ballad",
+    cedar: "cedar",
+    coral: "coral",
+    echo: "echo",
+    fable: "fable",
+    marin: "marin",
+    nova: "nova",
+    onyx: "onyx",
+    sage: "sage",
+    shimmer: "shimmer",
+    verse: "verse",
+};
+/**
+ * Settings for OpenAITTSService.
+ *
+ * - `instructions`: instructions to guide voice synthesis behavior.
+ * - `speed`: voice speed control (0.25 to 4.0, default 1.0).
+ */
+export class OpenAITTSSettings extends TTSSettings {
+    instructions = NOT_GIVEN;
+    speed = NOT_GIVEN;
+    constructor(options = {}) {
+        super(options);
+        this._assignOptions(options);
+    }
+}
+/** Yield the bytes of a body stream in chunks of exactly `chunkSize` (the last may be shorter). */
+async function* iterBytes(body, chunkSize) {
+    if (!body)
+        return;
+    const reader = body.getReader();
+    let buffer = new Uint8Array(0);
+    try {
+        while (true) {
+            const { done, value } = await abortable(reader.read());
+            if (done)
+                break;
+            if (!value || value.length === 0)
+                continue;
+            const merged = new Uint8Array(buffer.length + value.length);
+            merged.set(buffer);
+            merged.set(value, buffer.length);
+            buffer = merged;
+            while (buffer.length >= chunkSize) {
+                yield buffer.slice(0, chunkSize);
+                buffer = buffer.slice(chunkSize);
+            }
+        }
+        if (buffer.length > 0) {
+            yield buffer;
+        }
+    }
+    finally {
+        try {
+            await reader.cancel();
+        }
+        catch (e) {
+            rethrowIfCancelled(e);
+        }
+    }
+}
+/**
+ * OpenAI Text-to-Speech service that generates audio from text.
+ *
+ * This service uses the OpenAI TTS API to generate PCM-encoded audio at
+ * 24kHz. Supports multiple voice models and configurable parameters for
+ * high-quality speech synthesis with streaming audio output.
+ */
+export class OpenAITTSService extends TTSService {
+    static Settings = OpenAITTSSettings;
+    static {
+        installTracedTts(OpenAITTSService.prototype, "runTts");
+    }
+    _client;
+    /**
+     * Initialize OpenAI TTS service.
+     *
+     * @param options.apiKey OpenAI API key for authentication. If null, uses
+     *   environment variable.
+     * @param options.baseUrl Custom base URL for OpenAI API. If null, uses default.
+     * @param options.httpClient Custom `fetch` for API requests.
+     * @param options.sampleRate Output audio sample rate in Hz. If null, uses
+     *   OpenAI's default 24kHz.
+     * @param options.settings Runtime-updatable settings. Its given fields
+     *   override the defaults (model "gpt-4o-mini-tts", voice "alloy").
+     *   Other options are passed to TTSService.
+     */
+    constructor(options = {}) {
+        const sampleRate = options.sampleRate ?? null;
+        if (sampleRate && sampleRate !== OPENAI_SAMPLE_RATE) {
+            logger.warning(`OpenAI TTS only supports ${OPENAI_SAMPLE_RATE}Hz sample rate. ` +
+                `Current rate of ${sampleRate}Hz may cause issues.`);
+        }
+        // 1. Initialize default_settings with hardcoded defaults
+        const defaultSettings = new new.target.Settings({
+            model: "gpt-4o-mini-tts",
+            voice: "alloy",
+            language: null,
+            instructions: null,
+            speed: null,
+        });
+        // 2. Apply settings delta (canonical API, always wins)
+        if (options.settings !== undefined && options.settings !== null) {
+            defaultSettings.applyUpdate(options.settings);
+        }
+        super({
+            ...options,
+            sampleRate,
+            pushStartFrame: true,
+            pushStopFrames: true,
+            settings: defaultSettings,
+        });
+        this._client = new OpenAI({
+            apiKey: options.apiKey ?? undefined,
+            baseURL: options.baseUrl ?? undefined,
+            ...(options.httpClient ? { fetch: options.httpClient } : {}),
+        });
+    }
+    /**
+     * Check if this service can generate processing metrics.
+     *
+     * @returns True, as OpenAI TTS service supports metrics generation.
+     */
+    canGenerateMetrics() {
+        return true;
+    }
+    /**
+     * Start the OpenAI TTS service.
+     *
+     * @param frame The start frame containing initialization parameters.
+     */
+    async start(frame) {
+        await super.start(frame);
+        if (this.sampleRate !== OPENAI_SAMPLE_RATE) {
+            logger.warning(`OpenAI TTS requires ${OPENAI_SAMPLE_RATE}Hz sample rate. ` +
+                `Current rate of ${this.sampleRate}Hz may cause issues.`);
+        }
+    }
+    /**
+     * Generate speech from text using OpenAI's TTS API.
+     *
+     * @param text The text to synthesize into speech.
+     * @param contextId The context ID for tracking audio frames.
+     * @returns Audio frames containing the synthesized speech data.
+     */
+    async *runTts(text, contextId) {
+        const voice = assertGiven(this._settings.voice);
+        if (voice === null) {
+            yield new ErrorFrame({ error: "OpenAI TTS voice must be specified" });
+            return;
+        }
+        if (!Object.hasOwn(VALID_VOICES, voice)) {
+            yield new ErrorFrame({
+                error: `OpenAI TTS voice '${voice}' is not supported ` +
+                    `(must be one of: ${Object.keys(VALID_VOICES).sort().join(", ")})`,
+            });
+            return;
+        }
+        try {
+            // Setup API parameters
+            const createParams = {
+                input: text,
+                model: this._settings.model,
+                voice: VALID_VOICES[voice],
+                response_format: "pcm",
+            };
+            if (this._settings.instructions) {
+                createParams.instructions = this._settings.instructions;
+            }
+            if (this._settings.speed) {
+                createParams.speed = this._settings.speed;
+            }
+            const r = await abortable(this._client.audio.speech.create(createParams, { signal: currentSignal() }));
+            if (r.status !== 200) {
+                const error = await abortable(r.text());
+                logger.error(`${this} error getting audio (status: ${r.status}, error: ${error})`);
+                yield new ErrorFrame({
+                    error: `Error getting audio (status: ${r.status}, error: ${error})`,
+                });
+                return;
+            }
+            await this.startTtsUsageMetrics(text);
+            const CHUNK_SIZE = this.chunkSize;
+            for await (const chunk of iterBytes(r.body, CHUNK_SIZE)) {
+                if (chunk.length > 0) {
+                    await this.stopTtfbMetrics();
+                    const frame = new TTSAudioRawFrame({
+                        audio: chunk,
+                        sampleRate: this.sampleRate,
+                        numChannels: 1,
+                        contextId,
+                    });
+                    yield frame;
+                }
+            }
+        }
+        catch (e) {
+            if (e instanceof BadRequestError) {
+                yield new ErrorFrame({ error: `Unknown error occurred: ${e.message}` });
+                return;
+            }
+            throw e;
+        }
+    }
+}
+//# sourceMappingURL=tts.js.map

package/package.json

@@ -1,12 +1,58 @@
 {
   "name": "@pipedog/openai",
-  "version": "0.0.0",
-  "description": "Placeholder for @pipedog/openai. Releases are published from GitHub Actions; see https://github.com/polvallverdu/pipedog/tree/main/packages/openai#readme",
+  "version": "0.4.0",
+  "description": "OpenAI services (LLM, Responses, Realtime, Live, STT, TTS, image) for pipedog.",
   "license": "BSD-2-Clause",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/polvallverdu/pipedog.git",
     "directory": "packages/openai"
   },
-  "homepage": "https://github.com/polvallverdu/pipedog/tree/main/packages/openai#readme"
+  "homepage": "https://github.com/polvallverdu/pipedog/tree/main/packages/openai#readme",
+  "bugs": {
+    "url": "https://github.com/polvallverdu/pipedog/issues"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./*": {
+      "types": "./dist/*.d.ts",
+      "default": "./dist/*.js"
+    }
+  },
+  "files": [
+    "dist",
+    "LICENSE",
+    "NOTICE"
+  ],
+  "scripts": {
+    "test": "bun test"
+  },
+  "dependencies": {
+    "@pipedog/asyncio": "0.4.0",
+    "@pipedog/core": "0.4.0",
+    "@pipedog/whisper": "0.4.0",
+    "fast-png": "^8.0.0",
+    "openai": "^6.49.0"
+  },
+  "pipecat": {
+    "runtimes": [
+      "bun",
+      "node",
+      "deno",
+      "workerd"
+    ],
+    "upstream": [
+      "src/pipecat/services/openai",
+      "src/pipecat/adapters/services/open_ai_live_adapter.py",
+      "src/pipecat/adapters/services/open_ai_realtime_adapter.py",
+      "src/pipecat/adapters/services/open_ai_responses_adapter.py"
+    ]
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts"
 }

package/README.md

@@ -1,5 +0,0 @@
-# @pipedog/openai
-
-Placeholder version. Install a released version instead: `npm install @pipedog/openai@latest`.
-
-Part of [pipedog](https://github.com/polvallverdu/pipedog).