@framers/agentos-ext-streaming-tts-elevenlabs 0.2.0

package/dist/ElevenLabsTTSSession.js

@@ -0,0 +1,334 @@
+/**
+ * @file ElevenLabsTTSSession.ts
+ * @description Active TTS session backed by the ElevenLabs WebSocket Streaming API.
+ *
+ * {@link ElevenLabsTTSSession} implements the `StreamingTTSSession` interface
+ * (EventEmitter) and provides the following events:
+ *
+ * | Event                | Payload                    | Description                                          |
+ * |----------------------|----------------------------|------------------------------------------------------|
+ * | `'audio_chunk'`      | `EncodedAudioChunk`        | MP3 audio buffer from ElevenLabs, ready for playback |
+ * | `'utterance_complete'`| `{ text, durationMs }`    | ElevenLabs signalled end of audio generation         |
+ * | `'cancelled'`        | `{ remaining: string }`    | Session cancelled; remaining text not rendered       |
+ * | `'error'`            | `Error`                    | WebSocket or protocol error                          |
+ * | `'close'`            | —                          | Session fully terminated                             |
+ *
+ * ### Protocol Overview
+ *
+ * The ElevenLabs WebSocket streaming protocol works as follows:
+ *
+ * 1. Open WSS connection to the voice/model endpoint.
+ * 2. Send a BOS (Beginning-Of-Stream) message: `{ text: " ", voice_settings: {...}, xi_api_key }`.
+ * 3. Stream text tokens as `{ text: "..." }` JSON messages.
+ * 4. To generate audio for accumulated text, include `flush: true` in the text message.
+ * 5. To end the stream, send an EOS (End-Of-Stream) message: `{ text: "" }`.
+ * 6. The server returns binary messages (MP3 audio chunks) and JSON status messages.
+ * 7. When all audio has been generated the server sends `{ isFinal: true }`.
+ *
+ * @module streaming-tts-elevenlabs/ElevenLabsTTSSession
+ */
+import { EventEmitter } from 'node:events';
+import WebSocket from 'ws';
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+/** ElevenLabs WebSocket API base URL. */
+const ELEVENLABS_WS_BASE = 'wss://api.elevenlabs.io';
+/** Default voice ID — Rachel (a neutral, clear English voice). */
+const DEFAULT_VOICE_ID = '21m00Tcm4TlvDq8ikWAM';
+/** Default model — ElevenLabs Turbo v2, optimized for low latency. */
+const DEFAULT_MODEL_ID = 'eleven_turbo_v2';
+/** MP3 output format at 44.1 kHz / 128 kbps. */
+const OUTPUT_FORMAT = 'mp3_44100_128';
+/** Sample rate that matches the OUTPUT_FORMAT specifier. */
+const SAMPLE_RATE_HZ = 44_100;
+/**
+ * Rough estimate of spoken word rate used to compute {@link EncodedAudioChunk.durationMs}.
+ * 150 words per minute.
+ */
+const WORDS_PER_MS = 150 / 60_000;
+/** Regex matching sentence-final punctuation. */
+const SENTENCE_BOUNDARY_RE = /[.?!]/;
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+/**
+ * Estimate the spoken duration in milliseconds for a piece of text.
+ *
+ * Uses a simple word-count heuristic (150 WPM).  Callers should treat the result
+ * as a hint rather than a precise measurement.
+ *
+ * @param text - The text to estimate duration for.
+ * @returns Estimated playback duration in milliseconds (minimum 200 ms).
+ */
+function estimateDurationMs(text) {
+    const wordCount = text.trim().split(/\s+/).filter(Boolean).length;
+    return Math.max(200, Math.round(wordCount / WORDS_PER_MS));
+}
+// ---------------------------------------------------------------------------
+// Main class
+// ---------------------------------------------------------------------------
+/**
+ * Active streaming TTS session backed by the ElevenLabs WebSocket Streaming API.
+ *
+ * Construct via {@link ElevenLabsStreamingTTS.startSession} rather than directly.
+ *
+ * @example
+ * ```ts
+ * const session = new ElevenLabsTTSSession(
+ *   { apiKey: process.env.ELEVENLABS_API_KEY! },
+ *   {},
+ * );
+ *
+ * session.on('audio_chunk', (chunk) => audioPlayer.enqueue(chunk.audio));
+ * session.on('utterance_complete', ({ text, durationMs }) => {
+ *   console.log(`Synthesis complete ~${durationMs} ms`);
+ * });
+ *
+ * llm.on('token', (tok) => session.pushTokens(tok));
+ * llm.on('end',   ()    => session.flush());
+ * ```
+ */
+export class ElevenLabsTTSSession extends EventEmitter {
+    providerConfig;
+    // -------------------------------------------------------------------------
+    // Resolved config
+    // -------------------------------------------------------------------------
+    /** ElevenLabs voice ID. */
+    voiceId;
+    /** ElevenLabs model ID. */
+    modelId;
+    /** Voice stability (0.0 – 1.0). */
+    stability;
+    /** Similarity boost (0.0 – 1.0). */
+    similarityBoost;
+    /** Style exaggeration (0.0 – 1.0). */
+    style;
+    /** Whether to enable speaker boost. */
+    useSpeakerBoost;
+    // -------------------------------------------------------------------------
+    // Internal state
+    // -------------------------------------------------------------------------
+    /** Live WebSocket connection to the ElevenLabs streaming endpoint. */
+    ws;
+    /**
+     * Text that has been pushed since the last sentence-boundary flush.
+     *
+     * Accumulated so that `cancel()` can report the remaining un-synthesised text.
+     */
+    pendingText = '';
+    /** `true` after {@link close} or {@link cancel} is called. */
+    closed = false;
+    /**
+     * Whether the BOS (beginning-of-stream) message has been sent.
+     *
+     * The BOS is sent once on `ws.open`; subsequent messages are plain text sends.
+     */
+    bosAcknowledged = false;
+    /**
+     * Queue of text segments that need to be sent once the WebSocket opens.
+     *
+     * If `pushTokens` or `flush` is called before the socket is open, messages
+     * are queued here and drained on `ws.open`.
+     */
+    sendQueue = [];
+    // -------------------------------------------------------------------------
+    // Constructor
+    // -------------------------------------------------------------------------
+    /**
+     * @param providerConfig - ElevenLabs-specific configuration (apiKey required).
+     * @param _sessionConfig - Generic voice-pipeline session config (reserved for
+     *   future `language` forwarding).
+     */
+    constructor(providerConfig, _sessionConfig) {
+        super();
+        this.providerConfig = providerConfig;
+        // Apply defaults.
+        this.voiceId = providerConfig.voiceId ?? DEFAULT_VOICE_ID;
+        this.modelId = providerConfig.modelId ?? DEFAULT_MODEL_ID;
+        this.stability = providerConfig.stability ?? 0.5;
+        this.similarityBoost = providerConfig.similarityBoost ?? 0.75;
+        this.style = providerConfig.style ?? 0.0;
+        this.useSpeakerBoost = providerConfig.useSpeakerBoost ?? true;
+        // Build the WebSocket endpoint URL.
+        const wsUrl = `${ELEVENLABS_WS_BASE}/v1/text-to-speech/${this.voiceId}/stream-input` +
+            `?model_id=${this.modelId}&output_format=${OUTPUT_FORMAT}`;
+        this.ws = new WebSocket(wsUrl);
+        this._wireWebSocket();
+    }
+    // -------------------------------------------------------------------------
+    // StreamingTTSSession interface
+    // -------------------------------------------------------------------------
+    /**
+     * Push LLM output token(s) into the stream.
+     *
+     * Text is accumulated in an internal buffer.  When a sentence boundary
+     * (`.`, `?`, `!`) is detected the accumulated segment is sent to ElevenLabs
+     * with `flush: true` so the server generates audio immediately.  Mid-sentence
+     * tokens are sent with a trailing space continuation to avoid falling intonation
+     * on partial phrases.
+     *
+     * @param text - One or more LLM token characters to append.
+     */
+    pushTokens(text) {
+        if (this.closed)
+            return;
+        this.pendingText += text;
+        // Check for sentence-boundary punctuation.
+        const hasBoundary = SENTENCE_BOUNDARY_RE.test(text);
+        if (hasBoundary) {
+            // Send the accumulated text with flush: true so ElevenLabs generates audio.
+            const segment = this.pendingText;
+            this.pendingText = '';
+            this._send({ text: segment, flush: true });
+        }
+        else {
+            // Send the token chunk without flush; include a space continuation to hint
+            // that the phrase is mid-sentence (prevents falling prosody on partial text).
+            this._send({ text });
+        }
+    }
+    /**
+     * Flush any remaining buffered text and signal EOS to ElevenLabs.
+     *
+     * Call this when the LLM stream has ended.  Sends an EOS (end-of-stream)
+     * message (`{ text: "" }`) which instructs ElevenLabs to finalise audio
+     * generation for all remaining buffered text and close the stream.
+     *
+     * @returns Promise that resolves when the EOS message is queued for sending.
+     */
+    async flush() {
+        if (this.closed)
+            return;
+        // If there is buffered text that has not been sent, send it with flush: true first.
+        if (this.pendingText.trim().length > 0) {
+            const segment = this.pendingText;
+            this.pendingText = '';
+            this._send({ text: segment, flush: true });
+        }
+        // Send EOS — empty string signals end of stream to ElevenLabs.
+        this._send({ text: '' });
+    }
+    /**
+     * Cancel the session immediately.
+     *
+     * Closes the WebSocket, discards any unsent text, and emits a `'cancelled'`
+     * event carrying the remaining un-synthesised text.
+     */
+    cancel() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        const remaining = this.pendingText;
+        this.pendingText = '';
+        this.ws.close();
+        this.emit('cancelled', { remaining });
+    }
+    /**
+     * Close the session cleanly.
+     *
+     * Sends a WebSocket close frame and emits a `'close'` event.
+     * Idempotent — safe to call multiple times.
+     */
+    close() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        this.ws.close();
+        this.emit('close');
+    }
+    // -------------------------------------------------------------------------
+    // Internal — WebSocket wiring
+    // -------------------------------------------------------------------------
+    /**
+     * Attach event listeners to the WebSocket instance and handle the full
+     * message lifecycle.
+     */
+    _wireWebSocket() {
+        this.ws.on('open', () => {
+            // Send BOS message immediately on connection open.
+            const bosMessage = {
+                text: ' ',
+                voice_settings: {
+                    stability: this.stability,
+                    similarity_boost: this.similarityBoost,
+                    style: this.style,
+                    use_speaker_boost: this.useSpeakerBoost,
+                },
+                xi_api_key: this.providerConfig.apiKey,
+            };
+            // Use the raw WS send to bypass the queue (BOS must be first).
+            this.ws.send(JSON.stringify(bosMessage));
+            this.bosAcknowledged = true;
+            // Drain any messages queued before the socket opened.
+            for (const queued of this.sendQueue) {
+                this.ws.send(JSON.stringify(queued));
+            }
+            this.sendQueue.length = 0;
+        });
+        this.ws.on('message', (data, isBinary) => {
+            if (this.closed)
+                return;
+            if (isBinary) {
+                // Binary message: MP3 audio chunk.
+                const audio = Buffer.isBuffer(data)
+                    ? data
+                    : Buffer.from(data);
+                const durationMs = estimateDurationMs(this.pendingText);
+                const chunk = {
+                    audio,
+                    format: 'mp3',
+                    sampleRate: SAMPLE_RATE_HZ,
+                    durationMs,
+                    text: '',
+                };
+                this.emit('audio_chunk', chunk);
+            }
+            else {
+                // Text (JSON) message: parse for protocol signals.
+                try {
+                    const msg = JSON.parse(data.toString());
+                    if (msg['isFinal'] === true) {
+                        // ElevenLabs has finished generating all audio for this stream.
+                        const durationMs = estimateDurationMs(this.pendingText);
+                        this.emit('utterance_complete', { text: this.pendingText, durationMs });
+                    }
+                    // Other JSON messages (e.g. alignment data) are silently ignored for now.
+                }
+                catch {
+                    // Malformed JSON from the server — emit a non-fatal error.
+                    this.emit('error', new Error(`ElevenLabs: unexpected non-JSON text message: ${String(data)}`));
+                }
+            }
+        });
+        this.ws.on('error', (err) => {
+            if (!this.closed) {
+                this.emit('error', err);
+            }
+        });
+        this.ws.on('close', () => {
+            if (!this.closed) {
+                this.closed = true;
+                this.emit('close');
+            }
+        });
+    }
+    /**
+     * Send a JSON message over the WebSocket.
+     *
+     * If the socket is not yet open, the message is queued and will be sent once
+     * the `open` event fires (after the BOS message is dispatched).
+     *
+     * @param msg - The message object to serialise and send.
+     */
+    _send(msg) {
+        if (this.bosAcknowledged && this.ws.readyState === WebSocket.OPEN) {
+            this.ws.send(JSON.stringify(msg));
+        }
+        else {
+            // Queue for post-open delivery.
+            this.sendQueue.push(msg);
+        }
+    }
+}
+//# sourceMappingURL=ElevenLabsTTSSession.js.map

package/dist/ElevenLabsTTSSession.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ElevenLabsTTSSession.js","sourceRoot":"","sources":["../src/ElevenLabsTTSSession.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,81 @@
+/**
+ * @file index.ts
+ * @description Pack factory for the ElevenLabs Streaming TTS extension pack.
+ *
+ * Exports the main {@link createElevenLabsStreamingTTS} factory function and the
+ * {@link createExtensionPack} bridge function conforming to the AgentOS manifest
+ * factory convention.
+ *
+ * ### Usage (direct)
+ * ```ts
+ * import { createElevenLabsStreamingTTS } from '@framers/agentos-ext-streaming-tts-elevenlabs';
+ *
+ * const tts = createElevenLabsStreamingTTS(process.env.ELEVENLABS_API_KEY!);
+ * const session = await tts.startSession();
+ *
+ * session.on('audio_chunk', (chunk) => audioPlayer.enqueue(chunk.audio));
+ * llm.on('token', (tok) => session.pushTokens(tok));
+ * llm.on('end',   ()    => session.flush());
+ * ```
+ *
+ * ### Usage (manifest-driven)
+ * ```json
+ * { "packs": [{ "module": "@framers/agentos-ext-streaming-tts-elevenlabs" }] }
+ * ```
+ *
+ * @module streaming-tts-elevenlabs
+ */
+import { ElevenLabsStreamingTTS } from './ElevenLabsStreamingTTS.js';
+import type { ElevenLabsStreamingTTSConfig } from './types.js';
+/** Subset of ExtensionDescriptor required by this pack. */
+interface ExtensionDescriptor {
+    id: string;
+    kind: string;
+    payload: unknown;
+    enableByDefault?: boolean;
+    metadata?: Record<string, unknown>;
+}
+/** Subset of ExtensionPack required by this pack. */
+interface ExtensionPack {
+    id: string;
+    descriptors: ExtensionDescriptor[];
+}
+/** Subset of ExtensionPackContext required by this pack. */
+interface ExtensionPackContext {
+    getSecret?: (id: string) => string | undefined;
+    options?: Record<string, unknown>;
+}
+/**
+ * Create a standalone {@link ElevenLabsStreamingTTS} instance.
+ *
+ * Use this when composing the provider programmatically outside of the
+ * AgentOS extension system.
+ *
+ * @param apiKey - ElevenLabs API key.
+ * @param options - Optional provider configuration overrides.
+ * @returns Configured {@link ElevenLabsStreamingTTS}.
+ */
+export declare function createElevenLabsStreamingTTS(apiKey: string, options?: Omit<ElevenLabsStreamingTTSConfig, 'apiKey'>): ElevenLabsStreamingTTS;
+/**
+ * AgentOS manifest factory function.
+ *
+ * Reads the `ELEVENLABS_API_KEY` secret from the context and returns an
+ * {@link ExtensionPack} containing a single `streaming-tts-provider`
+ * descriptor backed by {@link ElevenLabsStreamingTTS}.
+ *
+ * Provider-level defaults can be overridden via `context.options`:
+ * - `voiceId`        — ElevenLabs voice ID.
+ * - `modelId`        — Model ID (default `'eleven_turbo_v2'`).
+ * - `stability`      — Voice stability 0.0–1.0.
+ * - `similarityBoost`— Similarity boost 0.0–1.0.
+ * - `style`          — Style exaggeration 0.0–1.0.
+ * - `useSpeakerBoost`— Speaker boost.
+ *
+ * @param context - Pack context supplied by the extension manager.
+ * @returns A fully configured {@link ExtensionPack}.
+ */
+export declare function createExtensionPack(context: ExtensionPackContext): ExtensionPack;
+export * from './types.js';
+export { ElevenLabsStreamingTTS } from './ElevenLabsStreamingTTS.js';
+export { ElevenLabsTTSSession } from './ElevenLabsTTSSession.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,EAAE,sBAAsB,EAAE,MAAM,6BAA6B,CAAC;AACrE,OAAO,KAAK,EAAE,4BAA4B,EAAE,MAAM,YAAY,CAAC;AAM/D,2DAA2D;AAC3D,UAAU,mBAAmB;IAC3B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,OAAO,CAAC;IACjB,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAED,qDAAqD;AACrD,UAAU,aAAa;IACrB,EAAE,EAAE,MAAM,CAAC;IACX,WAAW,EAAE,mBAAmB,EAAE,CAAC;CACpC;AAED,4DAA4D;AAC5D,UAAU,oBAAoB;IAC5B,SAAS,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,MAAM,GAAG,SAAS,CAAC;IAC/C,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACnC;AASD;;;;;;;;;GASG;AACH,wBAAgB,4BAA4B,CAC1C,MAAM,EAAE,MAAM,EACd,OAAO,CAAC,EAAE,IAAI,CAAC,4BAA4B,EAAE,QAAQ,CAAC,GACrD,sBAAsB,CAExB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,oBAAoB,GAAG,aAAa,CAkBhF;AAMD,cAAc,YAAY,CAAC;AAC3B,OAAO,EAAE,sBAAsB,EAAE,MAAO,6BAA6B,CAAC;AACtE,OAAO,EAAE,oBAAoB,EAAE,MAAS,2BAA2B,CAAC"}

package/dist/index.js

@@ -0,0 +1,88 @@
+/**
+ * @file index.ts
+ * @description Pack factory for the ElevenLabs Streaming TTS extension pack.
+ *
+ * Exports the main {@link createElevenLabsStreamingTTS} factory function and the
+ * {@link createExtensionPack} bridge function conforming to the AgentOS manifest
+ * factory convention.
+ *
+ * ### Usage (direct)
+ * ```ts
+ * import { createElevenLabsStreamingTTS } from '@framers/agentos-ext-streaming-tts-elevenlabs';
+ *
+ * const tts = createElevenLabsStreamingTTS(process.env.ELEVENLABS_API_KEY!);
+ * const session = await tts.startSession();
+ *
+ * session.on('audio_chunk', (chunk) => audioPlayer.enqueue(chunk.audio));
+ * llm.on('token', (tok) => session.pushTokens(tok));
+ * llm.on('end',   ()    => session.flush());
+ * ```
+ *
+ * ### Usage (manifest-driven)
+ * ```json
+ * { "packs": [{ "module": "@framers/agentos-ext-streaming-tts-elevenlabs" }] }
+ * ```
+ *
+ * @module streaming-tts-elevenlabs
+ */
+import { ElevenLabsStreamingTTS } from './ElevenLabsStreamingTTS.js';
+/** Kind constant matching packages/agentos/src/extensions/types.ts. */
+const EXTENSION_KIND_STREAMING_TTS = 'streaming-tts-provider';
+// ---------------------------------------------------------------------------
+// Factories
+// ---------------------------------------------------------------------------
+/**
+ * Create a standalone {@link ElevenLabsStreamingTTS} instance.
+ *
+ * Use this when composing the provider programmatically outside of the
+ * AgentOS extension system.
+ *
+ * @param apiKey - ElevenLabs API key.
+ * @param options - Optional provider configuration overrides.
+ * @returns Configured {@link ElevenLabsStreamingTTS}.
+ */
+export function createElevenLabsStreamingTTS(apiKey, options) {
+    return new ElevenLabsStreamingTTS({ apiKey, ...options });
+}
+/**
+ * AgentOS manifest factory function.
+ *
+ * Reads the `ELEVENLABS_API_KEY` secret from the context and returns an
+ * {@link ExtensionPack} containing a single `streaming-tts-provider`
+ * descriptor backed by {@link ElevenLabsStreamingTTS}.
+ *
+ * Provider-level defaults can be overridden via `context.options`:
+ * - `voiceId`        — ElevenLabs voice ID.
+ * - `modelId`        — Model ID (default `'eleven_turbo_v2'`).
+ * - `stability`      — Voice stability 0.0–1.0.
+ * - `similarityBoost`— Similarity boost 0.0–1.0.
+ * - `style`          — Style exaggeration 0.0–1.0.
+ * - `useSpeakerBoost`— Speaker boost.
+ *
+ * @param context - Pack context supplied by the extension manager.
+ * @returns A fully configured {@link ExtensionPack}.
+ */
+export function createExtensionPack(context) {
+    const apiKey = context.getSecret?.('ELEVENLABS_API_KEY') ?? '';
+    const opts = (context.options ?? {});
+    const tts = new ElevenLabsStreamingTTS({ apiKey, ...opts });
+    return {
+        id: 'streaming-tts-elevenlabs',
+        descriptors: [
+            {
+                id: 'elevenlabs-streaming-tts',
+                kind: EXTENSION_KIND_STREAMING_TTS,
+                payload: tts,
+                enableByDefault: true,
+                metadata: { providerId: 'elevenlabs-streaming-tts' },
+            },
+        ],
+    };
+}
+// ---------------------------------------------------------------------------
+// Re-exports
+// ---------------------------------------------------------------------------
+export * from './types.js';
+export { ElevenLabsStreamingTTS } from './ElevenLabsStreamingTTS.js';
+export { ElevenLabsTTSSession } from './ElevenLabsTTSSession.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,EAAE,sBAAsB,EAAE,MAAM,6BAA6B,CAAC;AA4BrE,uEAAuE;AACvE,MAAM,4BAA4B,GAAG,wBAAwB,CAAC;AAE9D,8EAA8E;AAC9E,YAAY;AACZ,8EAA8E;AAE9E;;;;;;;;;GASG;AACH,MAAM,UAAU,4BAA4B,CAC1C,MAAc,EACd,OAAsD;IAEtD,OAAO,IAAI,sBAAsB,CAAC,EAAE,MAAM,EAAE,GAAG,OAAO,EAAE,CAAC,CAAC;AAC5D,CAAC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,mBAAmB,CAAC,OAA6B;IAC/D,MAAM,MAAM,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC,oBAAoB,CAAC,IAAI,EAAE,CAAC;IAC/D,MAAM,IAAI,GAAK,CAAC,OAAO,CAAC,OAAO,IAAI,EAAE,CAAiD,CAAC;IAEvF,MAAM,GAAG,GAAG,IAAI,sBAAsB,CAAC,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,CAAC,CAAC;IAE5D,OAAO;QACL,EAAE,EAAE,0BAA0B;QAC9B,WAAW,EAAE;YACX;gBACE,EAAE,EAAe,0BAA0B;gBAC3C,IAAI,EAAa,4BAA4B;gBAC7C,OAAO,EAAU,GAAG;gBACpB,eAAe,EAAE,IAAI;gBACrB,QAAQ,EAAS,EAAE,UAAU,EAAE,0BAA0B,EAAE;aAC5D;SACF;KACF,CAAC;AACJ,CAAC;AAED,8EAA8E;AAC9E,aAAa;AACb,8EAA8E;AAE9E,cAAc,YAAY,CAAC;AAC3B,OAAO,EAAE,sBAAsB,EAAE,MAAO,6BAA6B,CAAC;AACtE,OAAO,EAAE,oBAAoB,EAAE,MAAS,2BAA2B,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,120 @@
+/**
+ * @file types.ts
+ * @description ElevenLabs-specific configuration types for the streaming TTS extension pack.
+ *
+ * These types define provider configuration for the ElevenLabs WebSocket Streaming API and
+ * the shared audio chunk shape emitted by the session.
+ *
+ * @module streaming-tts-elevenlabs/types
+ */
+/**
+ * ElevenLabs-specific configuration for the streaming TTS session.
+ *
+ * All fields except `apiKey` are optional — sensible defaults are applied when omitted.
+ * The `apiKey` field is required and must be a valid ElevenLabs API key (xi-api-key).
+ */
+export interface ElevenLabsStreamingTTSConfig {
+    /**
+     * ElevenLabs API key (xi-api-key).  Must be set to a non-empty string; the pack reads
+     * this from the `ELEVENLABS_API_KEY` secret when constructed via {@link createExtensionPack}.
+     */
+    apiKey: string;
+    /**
+     * ElevenLabs voice ID to use for synthesis.
+     *
+     * Find voice IDs in the ElevenLabs voice library or via the Voices API.
+     * @defaultValue '21m00Tcm4TlvDq8ikWAM' (Rachel — a neutral English voice)
+     * @see {@link https://elevenlabs.io/voice-library}
+     */
+    voiceId?: string;
+    /**
+     * ElevenLabs model ID to use for synthesis.
+     *
+     * - `eleven_turbo_v2` — optimized for low latency (~250 ms to first chunk).
+     * - `eleven_multilingual_v2` — highest quality, supports 29 languages.
+     * - `eleven_monolingual_v1` — English-only, balanced latency/quality.
+     *
+     * @defaultValue 'eleven_turbo_v2'
+     * @see {@link https://elevenlabs.io/docs/speech-synthesis/models}
+     */
+    modelId?: string;
+    /**
+     * Voice stability (0.0 – 1.0).
+     *
+     * Lower values produce more expressive and varied speech; higher values are more
+     * consistent and monotone.
+     * @defaultValue 0.5
+     */
+    stability?: number;
+    /**
+     * Similarity boost (0.0 – 1.0).
+     *
+     * Higher values cause the output to sound more similar to the original voice clone.
+     * Too high a value can introduce artefacts.
+     * @defaultValue 0.75
+     */
+    similarityBoost?: number;
+    /**
+     * Style exaggeration (0.0 – 1.0).
+     *
+     * Amplifies the style of the original speaker.  Increasing this setting may reduce
+     * overall generation speed.  Only available for v2 models.
+     * @defaultValue 0.0
+     */
+    style?: number;
+    /**
+     * Speaker boost.
+     *
+     * Boosts similarity to the original speaker.  Recommended when a cloned voice is
+     * used and maximum fidelity is needed.
+     * @defaultValue true
+     */
+    useSpeakerBoost?: boolean;
+}
+/**
+ * Generic streaming TTS session config forwarded from the voice pipeline.
+ *
+ * This is the provider-agnostic shape the AgentOS voice pipeline passes to
+ * {@link ElevenLabsStreamingTTS.startSession}.
+ */
+export interface StreamingTTSConfig {
+    /** Language / locale hint (e.g. `'en-US'`). Currently informational only for ElevenLabs. */
+    language?: string;
+    /** Provider-specific options forwarded verbatim to the adapter. */
+    providerOptions?: Record<string, unknown>;
+}
+/**
+ * A single chunk of synthesized audio emitted by {@link ElevenLabsTTSSession}.
+ *
+ * The `audio` field holds raw MP3 bytes returned by the ElevenLabs WebSocket stream.
+ * The `format` field is always `'mp3'` for this provider.
+ */
+export interface EncodedAudioChunk {
+    /** Raw audio bytes encoded as MP3. */
+    audio: Buffer;
+    /**
+     * Codec / container format.  Always `'mp3'` for ElevenLabs streaming output.
+     */
+    format: string;
+    /**
+     * Nominal sample rate of the audio, in Hz.
+     *
+     * ElevenLabs streaming returns 44.1 kHz MP3 audio when `output_format=mp3_44100_128`.
+     */
+    sampleRate: number;
+    /**
+     * Rough estimated playback duration in milliseconds.
+     *
+     * Computed heuristically from the current text buffer word count (~150 WPM) rather than
+     * decoding the audio, so callers should treat this as a hint rather than a precise value.
+     */
+    durationMs: number;
+    /**
+     * The input text associated with this audio chunk.
+     *
+     * For mid-stream binary chunks this is an empty string; ElevenLabs does not embed
+     * alignment data in the binary WebSocket messages.
+     */
+    text: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH;;;;;GAKG;AACH,MAAM,WAAW,4BAA4B;IAC3C;;;OAGG;IACH,MAAM,EAAE,MAAM,CAAC;IAEf;;;;;;OAMG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB;;;;;;;;;OASG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB;;;;;;OAMG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB;;;;;;OAMG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IAEzB;;;;;;OAMG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf;;;;;;OAMG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B;AAED;;;;;GAKG;AACH,MAAM,WAAW,kBAAkB;IACjC,4FAA4F;IAC5F,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,mEAAmE;IACnE,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC3C;AAED;;;;;GAKG;AACH,MAAM,WAAW,iBAAiB;IAChC,sCAAsC;IACtC,KAAK,EAAE,MAAM,CAAC;IAEd;;OAEG;IACH,MAAM,EAAE,MAAM,CAAC;IAEf;;;;OAIG;IACH,UAAU,EAAE,MAAM,CAAC;IAEnB;;;;;OAKG;IACH,UAAU,EAAE,MAAM,CAAC;IAEnB;;;;;OAKG;IACH,IAAI,EAAE,MAAM,CAAC;CACd"}

package/dist/types.js

@@ -0,0 +1,11 @@
+/**
+ * @file types.ts
+ * @description ElevenLabs-specific configuration types for the streaming TTS extension pack.
+ *
+ * These types define provider configuration for the ElevenLabs WebSocket Streaming API and
+ * the shared audio chunk shape emitted by the session.
+ *
+ * @module streaming-tts-elevenlabs/types
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG"}

package/manifest.json

@@ -0,0 +1,8 @@
+{
+  "name": "@framers/agentos-ext-streaming-tts-elevenlabs",
+  "version": "0.1.0",
+  "description": "Streaming TTS via ElevenLabs WebSocket API",
+  "kind": "streaming-tts-provider",
+  "extensionId": "streaming-tts-elevenlabs",
+  "entryPoint": "./dist/index.js"
+}