@elevenlabs/elevenlabs-js 2.19.0 → 2.20.1

package/dist/wrapper/ElevenLabsClient.js

@@ -38,6 +38,7 @@ const Client_1 = require("../Client");
 const errors = __importStar(require("../errors"));
 const webhooks_1 = require("./webhooks");
 const music_1 = require("./music");
+const speechToText_1 = require("./speechToText");
 class ElevenLabsClient extends Client_1.ElevenLabsClient {
     constructor(options = {}) {
         var _a;
@@ -56,12 +57,18 @@ class ElevenLabsClient extends Client_1.ElevenLabsClient {
         }
         return this._customWebhooks;
     }
-    // @ts-expect-error - Intentionally overriding parent getter with custom Music wrapper
+    // @ts-expect-error - Intentionally overriding with wrapper Music that has enhanced composeDetailed
     get music() {
         if (!this._customMusic) {
             this._customMusic = new music_1.Music(this._options);
         }
         return this._customMusic;
     }
+    get speechToText() {
+        if (!this._customSpeechToText) {
+            this._customSpeechToText = new speechToText_1.SpeechToText(this._options);
+        }
+        return this._customSpeechToText;
+    }
 }
 exports.ElevenLabsClient = ElevenLabsClient;

package/dist/wrapper/index.d.ts

@@ -2,3 +2,5 @@ export { ElevenLabsClient } from "./ElevenLabsClient";
 export { Music, type SongMetadata, type MultipartResponse } from "./music";
 export { play } from "./play";
 export { stream } from "./stream";
+export { SpeechToText } from "./speechToText";
+export { RealtimeConnection, RealtimeEvents, AudioFormat, CommitStrategy, type AudioOptions, type UrlOptions } from "./realtime";

package/dist/wrapper/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.stream = exports.play = exports.Music = exports.ElevenLabsClient = void 0;
+exports.CommitStrategy = exports.AudioFormat = exports.RealtimeEvents = exports.RealtimeConnection = exports.SpeechToText = exports.stream = exports.play = exports.Music = exports.ElevenLabsClient = void 0;
 var ElevenLabsClient_1 = require("./ElevenLabsClient");
 Object.defineProperty(exports, "ElevenLabsClient", { enumerable: true, get: function () { return ElevenLabsClient_1.ElevenLabsClient; } });
 var music_1 = require("./music");
@@ -9,3 +9,10 @@ var play_1 = require("./play");
 Object.defineProperty(exports, "play", { enumerable: true, get: function () { return play_1.play; } });
 var stream_1 = require("./stream");
 Object.defineProperty(exports, "stream", { enumerable: true, get: function () { return stream_1.stream; } });
+var speechToText_1 = require("./speechToText");
+Object.defineProperty(exports, "SpeechToText", { enumerable: true, get: function () { return speechToText_1.SpeechToText; } });
+var realtime_1 = require("./realtime");
+Object.defineProperty(exports, "RealtimeConnection", { enumerable: true, get: function () { return realtime_1.RealtimeConnection; } });
+Object.defineProperty(exports, "RealtimeEvents", { enumerable: true, get: function () { return realtime_1.RealtimeEvents; } });
+Object.defineProperty(exports, "AudioFormat", { enumerable: true, get: function () { return realtime_1.AudioFormat; } });
+Object.defineProperty(exports, "CommitStrategy", { enumerable: true, get: function () { return realtime_1.CommitStrategy; } });

package/dist/wrapper/music.d.ts

@@ -1,6 +1,7 @@
 import { Music as GeneratedMusic } from "../api/resources/music/client/Client";
 import type * as ElevenLabs from "../api";
 import type { CompositionPlan } from "../api/resources/music/resources/compositionPlan/client/Client";
+import * as core from "../core";
 export declare namespace Music {
     interface Options extends GeneratedMusic.Options {
     }
@@ -22,14 +23,84 @@ export interface MultipartResponse {
     audio: Buffer;
     filename: string;
 }
-export declare class Music extends GeneratedMusic {
+export declare class Music {
+    private _client;
     constructor(options?: Music.Options);
+    /**
+     * Get the composition plan client
+     */
+    get compositionPlan(): CompositionPlan;
+    /**
+     * Compose a song from a prompt or a composition plan.
+     * @throws {@link ElevenLabs.UnprocessableEntityError}
+     */
+    compose(request?: ElevenLabs.BodyComposeMusicV1MusicPost, requestOptions?: Music.RequestOptions): core.HttpResponsePromise<ReadableStream<Uint8Array>>;
     /**
      * Compose a song from a prompt or a composition plan with detailed response parsing.
-     * This method calls the original composeDetailed and then parses the stream response.
+     *
+     * Unlike the standard `compose()` method which returns a raw audio stream, this method
+     * automatically parses the multipart response to extract both the audio file and rich
+     * metadata about the generated composition.
+     *
+     * @param request - The music composition request containing either:
+     *   - `prompt`: A text description of the desired music (e.g., "upbeat electronic dance music")
+     *   - `compositionPlan`: A detailed composition plan object created via `compositionPlan.create()`
+     *   - `musicLengthMs`: Optional duration in milliseconds (10000-300000ms)
+     *
+     * @param requestOptions - Optional request configuration (e.g., timeout, signal, headers)
+     *
+     * @returns A promise that resolves to a `MultipartResponse` containing:
+     *   - `json.compositionPlan`: The detailed composition plan structure including sections,
+     *     styles, and lyrics
+     *   - `json.songMetadata`: Metadata about the generated song (title, description, genres,
+     *     languages, explicit content flag)
+     *   - `audio`: Buffer containing the complete audio file (MP3 format)
+     *   - `filename`: Suggested filename for the audio file
+     *
+     * @throws {@link ElevenLabs.UnprocessableEntityError} If the request parameters are invalid
+     *   or the music generation fails
+     *
+     * @example
+     * ```typescript
+     * const client = new ElevenLabs({ apiKey: "your-api-key" });
+     *
+     * // Generate music from a text prompt
+     * const response = await client.music.composeDetailed({
+     *   prompt: "Epic orchestral music with dramatic strings and powerful brass",
+     *   musicLengthMs: 60000 // 60 seconds
+     * });
+     *
+     * console.log("Title:", response.json.songMetadata.title);
+     * console.log("Genres:", response.json.songMetadata.genres);
+     *
+     * // Save the audio to a file
+     * fs.writeFileSync(response.filename, response.audio);
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Generate music from a composition plan
+     * const plan = await client.music.compositionPlan.create({
+     *   prompt: "A progressive rock song about space exploration"
+     * });
+     *
+     * const response = await client.music.composeDetailed({
+     *   compositionPlan: plan.compositionPlan
+     * });
+     *
+     * // Access detailed section information
+     * for (const section of response.json.compositionPlan.sections) {
+     *   console.log(`${section.sectionName}: ${section.durationMs}ms`);
+     * }
+     * ```
+     */
+    composeDetailed(request?: ElevenLabs.BodyComposeMusicWithADetailedResponseV1MusicDetailedPost, requestOptions?: Music.RequestOptions): core.HttpResponsePromise<MultipartResponse>;
+    private _composeDetailed;
+    /**
+     * Stream a composed song from a prompt or a composition plan.
      * @throws {@link ElevenLabs.UnprocessableEntityError}
      */
-    composeDetailed(request?: ElevenLabs.BodyComposeMusicWithADetailedResponseV1MusicDetailedPost, requestOptions?: Music.RequestOptions): Promise<MultipartResponse>;
+    stream(request?: ElevenLabs.BodyStreamComposedMusicV1MusicStreamPost, requestOptions?: Music.RequestOptions): core.HttpResponsePromise<ReadableStream<Uint8Array>>;
     /**
      * Reads a ReadableStream containing multipart data and parses it into JSON and audio parts
      * @param stream - ReadableStream from ElevenLabs music API response

package/dist/wrapper/music.js

@@ -1,4 +1,37 @@
 "use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
 var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
     function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
     return new (P || (P = Promise))(function (resolve, reject) {
@@ -11,28 +44,108 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Music = void 0;
 const Client_1 = require("../api/resources/music/client/Client");
-class Music extends Client_1.Music {
+const core = __importStar(require("../core"));
+class Music {
     constructor(options = {}) {
-        super(options);
+        this._client = new Client_1.Music(options);
     }
     /**
-     * Compose a song from a prompt or a composition plan with detailed response parsing.
-     * This method calls the original composeDetailed and then parses the stream response.
+     * Get the composition plan client
+     */
+    get compositionPlan() {
+        return this._client.compositionPlan;
+    }
+    /**
+     * Compose a song from a prompt or a composition plan.
      * @throws {@link ElevenLabs.UnprocessableEntityError}
      */
-    // @ts-expect-error - Intentionally overriding parent method with different return type
-    composeDetailed() {
-        const _super = Object.create(null, {
-            composeDetailed: { get: () => super.composeDetailed }
-        });
+    compose(request = {}, requestOptions) {
+        return this._client.compose(request, requestOptions);
+    }
+    /**
+     * Compose a song from a prompt or a composition plan with detailed response parsing.
+     *
+     * Unlike the standard `compose()` method which returns a raw audio stream, this method
+     * automatically parses the multipart response to extract both the audio file and rich
+     * metadata about the generated composition.
+     *
+     * @param request - The music composition request containing either:
+     *   - `prompt`: A text description of the desired music (e.g., "upbeat electronic dance music")
+     *   - `compositionPlan`: A detailed composition plan object created via `compositionPlan.create()`
+     *   - `musicLengthMs`: Optional duration in milliseconds (10000-300000ms)
+     *
+     * @param requestOptions - Optional request configuration (e.g., timeout, signal, headers)
+     *
+     * @returns A promise that resolves to a `MultipartResponse` containing:
+     *   - `json.compositionPlan`: The detailed composition plan structure including sections,
+     *     styles, and lyrics
+     *   - `json.songMetadata`: Metadata about the generated song (title, description, genres,
+     *     languages, explicit content flag)
+     *   - `audio`: Buffer containing the complete audio file (MP3 format)
+     *   - `filename`: Suggested filename for the audio file
+     *
+     * @throws {@link ElevenLabs.UnprocessableEntityError} If the request parameters are invalid
+     *   or the music generation fails
+     *
+     * @example
+     * ```typescript
+     * const client = new ElevenLabs({ apiKey: "your-api-key" });
+     *
+     * // Generate music from a text prompt
+     * const response = await client.music.composeDetailed({
+     *   prompt: "Epic orchestral music with dramatic strings and powerful brass",
+     *   musicLengthMs: 60000 // 60 seconds
+     * });
+     *
+     * console.log("Title:", response.json.songMetadata.title);
+     * console.log("Genres:", response.json.songMetadata.genres);
+     *
+     * // Save the audio to a file
+     * fs.writeFileSync(response.filename, response.audio);
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Generate music from a composition plan
+     * const plan = await client.music.compositionPlan.create({
+     *   prompt: "A progressive rock song about space exploration"
+     * });
+     *
+     * const response = await client.music.composeDetailed({
+     *   compositionPlan: plan.compositionPlan
+     * });
+     *
+     * // Access detailed section information
+     * for (const section of response.json.compositionPlan.sections) {
+     *   console.log(`${section.sectionName}: ${section.durationMs}ms`);
+     * }
+     * ```
+     */
+    composeDetailed(request = {}, requestOptions) {
+        return core.HttpResponsePromise.fromPromise(this._composeDetailed(request, requestOptions));
+    }
+    _composeDetailed() {
         return __awaiter(this, arguments, void 0, function* (request = {}, requestOptions) {
-            // Call the parent method to get the stream
-            const response = yield _super.composeDetailed.call(this, request, requestOptions);
-            // Parse the stream using your existing parsing method
-            const parsedResponse = yield this.parseMultipart(response);
-            return parsedResponse;
+            // Call the base client method to get the stream with raw response
+            try {
+                const { data: stream, rawResponse } = yield this._client.composeDetailed(request, requestOptions).withRawResponse();
+                // Parse the stream using the existing parsing method
+                const parsedResponse = yield this.parseMultipart(stream);
+                return { data: parsedResponse, rawResponse };
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                throw new Error(`Failed to parse detailed composition response: ${message}`);
+            }
         });
     }
+    /**
+     * Stream a composed song from a prompt or a composition plan.
+     * @throws {@link ElevenLabs.UnprocessableEntityError}
+     */
+    stream(request = {}, requestOptions) {
+        return this._client.stream(request, requestOptions);
+    }
     /**
      * Reads a ReadableStream containing multipart data and parses it into JSON and audio parts
      * @param stream - ReadableStream from ElevenLabs music API response

package/dist/wrapper/realtime/connection.d.ts

@@ -0,0 +1,179 @@
+import WebSocket from "ws";
+import type { ChildProcess } from "node:child_process";
+/**
+ * Events emitted by the RealtimeConnection.
+ */
+export declare enum RealtimeEvents {
+    /** Emitted when the session is successfully started */
+    SESSION_STARTED = "session_started",
+    /** Emitted when a partial (interim) transcript is available */
+    PARTIAL_TRANSCRIPT = "partial_transcript",
+    /** Emitted when a final transcript is available */
+    FINAL_TRANSCRIPT = "final_transcript",
+    /** Emitted when a final transcript with timestamps is available */
+    FINAL_TRANSCRIPT_WITH_TIMESTAMPS = "final_transcript_with_timestamps",
+    /** Emitted when an error occurs */
+    ERROR = "error",
+    /** Emitted when the WebSocket connection is opened */
+    OPEN = "open",
+    /** Emitted when the WebSocket connection is closed */
+    CLOSE = "close"
+}
+/**
+ * Manages a real-time transcription WebSocket connection.
+ *
+ * @remarks
+ * **Node.js only**: This class uses Node.js-specific WebSocket implementation.
+ *
+ * @example
+ * ```typescript
+ * const connection = await client.speechToText.realtime.connect({
+ *     modelId: "scribe_realtime_v2",
+ *     audioFormat: AudioFormat.PCM_16000,
+ *     sampleRate: 16000,
+ * });
+ *
+ * connection.on(RealtimeEvents.SESSION_STARTED, (data) => {
+ *     console.log("Session started");
+ * });
+ *
+ * connection.on(RealtimeEvents.PARTIAL_TRANSCRIPT, (data) => {
+ *     console.log("Partial:", data.transcript);
+ * });
+ *
+ * connection.on(RealtimeEvents.FINAL_TRANSCRIPT, (data) => {
+ *     console.log("Final:", data.transcript);
+ *     connection.close();
+ * });
+ *
+ * // Send audio data
+ * connection.send({ audioBase64: base64String });
+ *
+ * // Commit and close
+ * connection.commit();
+  * ```
+ */
+export declare class RealtimeConnection {
+    private websocket;
+    private eventEmitter;
+    private ffmpegProcess;
+    private currentSampleRate;
+    constructor(sampleRate: number);
+    /**
+     * @internal
+     * Used internally by ScribeRealtime to attach the WebSocket after connection is created.
+     */
+    setWebSocket(websocket: WebSocket): void;
+    /**
+     * @internal
+     * Used internally by ScribeRealtime to attach ffmpeg process for cleanup.
+     */
+    setFfmpegProcess(ffmpegProcess: ChildProcess): void;
+    /**
+     * Attaches an event listener for the specified event.
+     *
+     * @param event - The event to listen for (use RealtimeEvents enum)
+     * @param listener - The callback function to execute when the event fires
+     *
+     * @example
+     * ```typescript
+     * connection.on(RealtimeEvents.SESSION_STARTED, (data) => {
+     *     console.log("Session started", data);
+     * });
+     *
+     * connection.on(RealtimeEvents.PARTIAL_TRANSCRIPT, (data) => {
+     *     console.log("Partial:", data.transcript);
+     * });
+     *
+     * connection.on(RealtimeEvents.FINAL_TRANSCRIPT, (data) => {
+     *     console.log("Final:", data.transcript);
+     * });
+     * ```
+     */
+    on(event: RealtimeEvents, listener: (...args: unknown[]) => void): void;
+    /**
+     * Removes an event listener for the specified event.
+     *
+     * @param event - The event to stop listening for
+     * @param listener - The callback function to remove
+     *
+     * @example
+     * ```typescript
+     * const handler = (data) => console.log(data);
+     * connection.on(RealtimeEvents.PARTIAL_TRANSCRIPT, handler);
+     *
+     * // Later, remove the listener
+     * connection.off(RealtimeEvents.PARTIAL_TRANSCRIPT, handler);
+     * ```
+     */
+    off(event: RealtimeEvents, listener: (...args: unknown[]) => void): void;
+    /**
+     * Sends audio data to the transcription service.
+     *
+     * @param data - Audio data configuration
+     * @param data.audioBase64 - Base64-encoded audio data
+     * @param data.commit - Whether to commit the transcription after this chunk. You likely want to use connection.commit() instead (default: false)
+     * @param data.sampleRate - Sample rate of the audio (default: configured sample rate)
+     *
+     * @throws {Error} If the WebSocket connection is not open
+     *
+     * @example
+     * ```typescript
+     * // Send audio chunk without committing
+     * connection.send({
+     *     audioBase64: base64EncodedAudio,
+     * });
+     *
+     * // Send audio chunk with custom sample rate
+     * connection.send({
+     *     audioBase64: base64EncodedAudio,
+     *     sampleRate: 16000,
+     * });
+     * ```
+     */
+    send(data: {
+        audioBase64: string;
+        commit?: boolean;
+        sampleRate?: number;
+    }): void;
+    /**
+     * Commits the transcription, signaling that all audio has been sent.
+     * This finalizes the transcription and triggers a FINAL_TRANSCRIPT event.
+     *
+     * @throws {Error} If the WebSocket connection is not open
+     *
+     * @remarks
+     * Only needed when using CommitStrategy.MANUAL.
+     * When using CommitStrategy.VAD, commits are handled automatically by the server.
+     *
+     * @example
+     * ```typescript
+     * // Send all audio chunks
+     * for (const chunk of audioChunks) {
+     *     connection.send({ audioBase64: chunk });
+     * }
+     *
+     * // Finalize the transcription
+     * connection.commit();
+     * ```
+     */
+    commit(): void;
+    /**
+     * Closes the WebSocket connection and cleans up resources.
+     * This will terminate any ongoing transcription and stop ffmpeg processes if running.
+     *
+     * @remarks
+     * After calling close(), this connection cannot be reused.
+     * Create a new connection if you need to start transcribing again.
+     *
+     * @example
+     * ```typescript
+     * connection.on(RealtimeEvents.FINAL_TRANSCRIPT, (data) => {
+     *     console.log("Final:", data.transcript);
+     *     connection.close();
+     * });
+     * ```
+     */
+    close(): void;
+    private cleanup;
+}