@speech-sdk/core 0.6.1 → 0.7.0

package/dist/generate-conversation.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"generate-conversation.d.ts","sourceRoot":"","sources":["../src/generate-conversation.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,yBAAyB,CAAC;AAK3E,OAAO,KAAK,EAAiB,KAAK,EAAE,MAAM,sBAAsB,CAAC;AACjE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAGvD,YAAY,EACV,gBAAgB,EAChB,2BAA2B,GAC5B,MAAM,yBAAyB,CAAC;AAMjC,wBAAsB,oBAAoB,CAAC,CAAC,SAAS,KAAK,GAAG,KAAK,EAChE,OAAO,EAAE,2BAA2B,CAAC,CAAC,CAAC,GACtC,OAAO,CAAC,YAAY,CAAC,CAuEvB"}
+{"version":3,"file":"generate-conversation.d.ts","sourceRoot":"","sources":["../src/generate-conversation.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,yBAAyB,CAAC;AAO3E,OAAO,EAGL,KAAK,KAAK,EACX,MAAM,sBAAsB,CAAC;AAC9B,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAMvD,OAAO,EACL,sBAAsB,EACtB,uBAAuB,EACvB,sBAAsB,GACvB,MAAM,0BAA0B,CAAC;AAClC,YAAY,EACV,gBAAgB,EAChB,2BAA2B,GAC5B,MAAM,yBAAyB,CAAC;AAMjC,wBAAsB,oBAAoB,CAAC,CAAC,SAAS,KAAK,GAAG,KAAK,EAChE,OAAO,EAAE,2BAA2B,CAAC,CAAC,CAAC,GACtC,OAAO,CAAC,YAAY,CAAC,CAwFvB"}

package/dist/generate-conversation.js

@@ -1,10 +1,16 @@
 import pRetry from "p-retry";
 import { computeAudioDuration } from "./audio-duration.js";
 import { chooseConversationPath } from "./conversation/dispatch.js";
+import { ConversationInputError } from "./conversation/errors.js";
 import { validateConversationInput } from "./conversation/validate.js";
+import { deriveTimestampsViaSTT } from "./derive-timestamps.js";
 import { ApiError, NoSpeechGeneratedError } from "./errors.js";
+import { debug } from "./logger.js";
 import { resolveModel } from "./resolve-provider.js";
+import { modelDeclaresNativeTimestamps, } from "./speech-provider.js";
 import { DefaultGeneratedAudioFile } from "./speech-result.js";
+// biome-ignore lint/performance/noBarrelFile: public entry point — re-export error classes so callers get fn + types + errors from one import
+export { ConversationInputError, DialogueConstraintError, StitchUnsupportedError, } from "./conversation/errors.js";
 const DEFAULT_GAP_MS = 300;
 const DEFAULT_MAX_CONCURRENCY = 6;
 const DEFAULT_MAX_RETRIES = 2;
@@ -22,6 +28,16 @@ export async function generateConversation(options) {
         turns: options.turns,
     });
     if (path.kind === "native") {
+        // The native-dialogue path renders the entire script in a single provider
+        // API call, so per-turn providerOptions have no well-defined meaning —
+        // silently collapsing them to a single blob would lie to the caller. Fail
+        // loudly and let them move providerOptions to the top level (where it's
+        // forwarded once to the dialogue call) or pick a model that routes
+        // through the stitch path.
+        const turnWithOpts = options.turns.findIndex((t) => t.providerOptions !== undefined);
+        if (turnWithOpts !== -1) {
+            throw new ConversationInputError(`turns[${turnWithOpts}].providerOptions is set, but ${path.resolved.provider.id}/${path.resolved.modelId} dispatched to the native dialogue path, which renders all turns in one API call. Per-turn providerOptions are not supported on this path; move them to the top-level providerOptions instead.`);
+        }
         return await runNative({
             options,
             resolved: path.resolved,
@@ -45,6 +61,8 @@ export async function generateConversation(options) {
         volumeDbfs: options.volumeDbfs,
         abortSignal: options.abortSignal,
         headers: options.headers,
+        timestamps: options.timestamps ?? "auto",
+        timestampProvider: options.timestampProvider,
     });
     if (stitched.audio.length === 0) {
         throw new NoSpeechGeneratedError();
@@ -68,6 +86,7 @@ export async function generateConversation(options) {
         metadata,
         providerMetadata: { turns: stitched.providerMetadataPerTurn },
         warnings: stitched.warnings.length > 0 ? [...stitched.warnings] : undefined,
+        timestamps: stitched.timestamps,
     };
 }
 async function runNative(args) {
@@ -97,12 +116,30 @@ async function runNative(args) {
     const dialogueProviderOptions = stitchOpts
         ? { ...options.providerOptions, ...stitchOpts.providerOptions }
         : options.providerOptions;
+    const timestampMode = options.timestamps ?? "auto";
+    const hasNativeDialogueTimestamps = modelDeclaresNativeTimestamps(resolved);
+    const shouldRequestNative = (timestampMode === "on" || timestampMode === "auto") &&
+        hasNativeDialogueTimestamps;
+    const dialogueId = `${resolved.provider.id}/${resolved.modelId}`;
+    if (timestampMode === "off") {
+        debug(`${dialogueId} (dialogue): timestamps: "off" — skipping alignment.`);
+    }
+    else if (shouldRequestNative) {
+        debug(`${dialogueId} (dialogue): timestamps: "${timestampMode}" — requesting native dialogue alignment.`);
+    }
+    else if (timestampMode === "auto") {
+        debug(`${dialogueId} (dialogue): timestamps: "auto" — dialogue endpoint has no native alignment; skipping. Pass timestamps: "on" to derive from the mixed audio via STT (flat list, no speaker labels).`);
+    }
+    else {
+        debug(`${dialogueId} (dialogue): timestamps: "on" but no native dialogue alignment — will transcribe mixed audio via STT after rendering (adds a round-trip).`);
+    }
     const result = await pRetry(() => generateDialogue({
         modelId: resolved.modelId,
         turns: options.turns.map((t) => ({ voice: t.voice, text: t.text })),
         providerOptions: dialogueProviderOptions,
         abortSignal: options.abortSignal,
         headers: options.headers,
+        includeTimestamps: shouldRequestNative,
     }), {
         retries: maxRetries,
         signal: options.abortSignal,
@@ -136,6 +173,15 @@ async function runNative(args) {
     });
     const computedDuration = await computeAudioDuration(audio.uint8Array, outputMediaType);
     const audioDurationMs = computedDuration ?? result.audioDurationMs;
+    const timestamps = await resolveNativeDialogueTimestamps({
+        timestampMode,
+        nativeTimestamps: result.timestamps,
+        audio: audio.uint8Array,
+        mediaType: outputMediaType,
+        ttsModel: `${resolved.provider.id}/${resolved.modelId}`,
+        timestampProvider: options.timestampProvider,
+        abortSignal: options.abortSignal,
+    });
     const inputChars = options.turns.reduce((n, t) => n + t.text.length, 0);
     const metadata = {
         latencyMs,
@@ -149,6 +195,32 @@ async function runNative(args) {
         metadata,
         providerMetadata: result.providerMetadata,
         warnings: warnings.length > 0 ? warnings : undefined,
+        timestamps,
     };
 }
+// Resolves timestamps for the native dialogue path:
+//   - "off"                            → undefined
+//   - native alignment returned        → pass through
+//   - "on" without native              → STT fallback on the mixed audio
+//     (flat WordTimestamp[] without speaker labels — limitation of one-call
+//     dialogue rendering)
+//   - "auto" without native            → undefined
+async function resolveNativeDialogueTimestamps(args) {
+    if (args.timestampMode === "off") {
+        return;
+    }
+    if (args.nativeTimestamps && args.nativeTimestamps.length > 0) {
+        return args.nativeTimestamps;
+    }
+    if (args.timestampMode === "on") {
+        return await deriveTimestampsViaSTT({
+            ttsModel: args.ttsModel,
+            audio: args.audio,
+            mediaType: args.mediaType,
+            timestampProvider: args.timestampProvider,
+            abortSignal: args.abortSignal,
+        });
+    }
+    return;
+}
 //# sourceMappingURL=generate-conversation.js.map

package/dist/generate-conversation.js.map

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

package/dist/generate-speech.d.ts

@@ -1,5 +1,7 @@
-import type { ResolvedModel, Voice } from "./speech-provider.js";
+import { type ResolvedModel, type Voice } from "./speech-provider.js";
 import type { SpeechResult } from "./speech-result.js";
+import type { ResolvedSTTModel } from "./speech-to-text-provider.js";
+import type { TimestampMode } from "./timestamps.js";
 export declare function generateSpeech<V extends Voice = Voice>(options: {
     model: string | ResolvedModel<V>;
     text: string;
@@ -19,5 +21,20 @@ export declare function generateSpeech<V extends Voice = Voice>(options: {
      * if the provider doesn't expose a decodable output mode.
      */
     volumeDbfs?: number;
+    /**
+     * Controls whether the returned `SpeechResult` includes word-level
+     * timestamps. Default `"auto"` — return natively when the TTS provider
+     * supplies alignment, otherwise omit. `"on"` forces word timestamps
+     * (falling back to STT round-trip when necessary). `"off"` suppresses
+     * them even for providers that would return them free.
+     */
+    timestamps?: TimestampMode;
+    /**
+     * Override the STT provider used for the derived-timestamps path. Construct
+     * via a factory (e.g. `createOpenAISTT({ apiKey })("whisper-1")`). Only
+     * consulted when timestamps are requested AND the TTS provider can't supply
+     * them natively. Defaults to OpenAI Whisper read from `OPENAI_API_KEY`.
+     */
+    timestampProvider?: ResolvedSTTModel;
 }): Promise<SpeechResult>;
 //# sourceMappingURL=generate-speech.d.ts.map

package/dist/generate-speech.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"generate-speech.d.ts","sourceRoot":"","sources":["../src/generate-speech.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,aAAa,EAAE,KAAK,EAAE,MAAM,sBAAsB,CAAC;AACjE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAGvD,wBAAsB,cAAc,CAAC,CAAC,SAAS,KAAK,GAAG,KAAK,EAAE,OAAO,EAAE;IACrE,KAAK,EAAE,MAAM,GAAG,aAAa,CAAC,CAAC,CAAC,CAAC;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,CAAC,CAAC;IACT,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC1C,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC;;;;;;;;OAQG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB,GAAG,OAAO,CAAC,YAAY,CAAC,CAwHxB"}
+{"version":3,"file":"generate-speech.d.ts","sourceRoot":"","sources":["../src/generate-speech.ts"],"names":[],"mappings":"AAYA,OAAO,EAEL,KAAK,aAAa,EAClB,KAAK,KAAK,EACX,MAAM,sBAAsB,CAAC;AAC9B,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAEvD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAC;AACrE,OAAO,KAAK,EAAE,aAAa,EAAiB,MAAM,iBAAiB,CAAC;AAEpE,wBAAsB,cAAc,CAAC,CAAC,SAAS,KAAK,GAAG,KAAK,EAAE,OAAO,EAAE;IACrE,KAAK,EAAE,MAAM,GAAG,aAAa,CAAC,CAAC,CAAC,CAAC;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,CAAC,CAAC;IACT,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC1C,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC;;;;;;;;OAQG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;;;;OAMG;IACH,UAAU,CAAC,EAAE,aAAa,CAAC;IAC3B;;;;;OAKG;IACH,iBAAiB,CAAC,EAAE,gBAAgB,CAAC;CACtC,GAAG,OAAO,CAAC,YAAY,CAAC,CAuJxB"}

package/dist/generate-speech.js

@@ -1,11 +1,14 @@
 import pRetry from "p-retry";
 import { computeAudioDuration } from "./audio-duration.js";
 import { detectAudioTags, stripAudioTags } from "./audio-tags.js";
+import { deriveTimestampsViaSTT } from "./derive-timestamps.js";
 import { ApiError, NoSpeechGeneratedError, VolumeAdjustmentUnsupportedError, } from "./errors.js";
+import { debug } from "./logger.js";
 import { resolveModel } from "./resolve-provider.js";
+import { modelDeclaresNativeTimestamps, } from "./speech-provider.js";
 import { DefaultGeneratedAudioFile } from "./speech-result.js";
 export async function generateSpeech(options) {
-    const { model, voice, abortSignal, headers, volumeDbfs } = options;
+    const { model, voice, abortSignal, headers, volumeDbfs, timestamps: timestampMode = "auto", timestampProvider, } = options;
     const maxRetries = options.maxRetries ?? 2;
     const resolved = resolveModel(model, { apiKey: options.apiKey });
     const modelIdentifier = `${resolved.provider.id}/${resolved.modelId}`;
@@ -23,26 +26,23 @@ export async function generateSpeech(options) {
             ...stitchOpts.providerOptions,
         };
     }
-    let processedText;
-    let warnings;
-    if (resolved.provider.processAudioTags) {
-        ({ text: processedText, warnings } = resolved.provider.processAudioTags(options.text, resolved.modelId));
-    }
-    else {
-        const tags = detectAudioTags(options.text);
-        if (tags.length > 0) {
-            ({ text: processedText, warnings } = stripAudioTags(options.text, modelIdentifier));
-        }
-        else {
-            processedText = options.text;
-            warnings = [];
-        }
-    }
+    const { text: processedText, warnings } = preprocessText(resolved, options.text, modelIdentifier);
     if (processedText.trim().length === 0) {
         throw new NoSpeechGeneratedError(warnings.length > 0
             ? `Text is empty after removing unsupported audio tags for ${modelIdentifier}.`
             : "Text must not be empty.");
     }
+    const hasNativeTimestamps = modelDeclaresNativeTimestamps(resolved);
+    // For "on" we still ask the provider natively first — if it has native
+    // alignment, we skip the STT round-trip.
+    const shouldRequestNative = (timestampMode === "on" || timestampMode === "auto") && hasNativeTimestamps;
+    logTimestampDecision({
+        modelIdentifier,
+        mode: timestampMode,
+        hasNative: hasNativeTimestamps,
+        willRequestNative: shouldRequestNative,
+        timestampProvider,
+    });
     const startTime = performance.now();
     const result = await pRetry(() => resolved.provider.generate({
         modelId: resolved.modelId,
@@ -51,6 +51,7 @@ export async function generateSpeech(options) {
         providerOptions,
         abortSignal,
         headers,
+        includeTimestamps: shouldRequestNative,
     }), {
         retries: maxRetries,
         signal: abortSignal,
@@ -83,6 +84,23 @@ export async function generateSpeech(options) {
     });
     const audioDurationMs = (await computeAudioDuration(audio.uint8Array, outputMediaType)) ??
         result.audioDurationMs;
+    let timestamps;
+    if (timestampMode !== "off") {
+        if (result.timestamps && result.timestamps.length > 0) {
+            debug(`${modelIdentifier}: returned ${result.timestamps.length} native word timestamps.`);
+            timestamps = result.timestamps;
+        }
+        else if (timestampMode === "on") {
+            timestamps = await deriveTimestampsViaSTT({
+                ttsModel: modelIdentifier,
+                audio: audio.uint8Array,
+                mediaType: outputMediaType,
+                timestampProvider,
+                abortSignal,
+            });
+            debug(`${modelIdentifier}: derived ${timestamps.length} word timestamps via STT fallback.`);
+        }
+    }
     const metadata = {
         latencyMs,
         inputChars: processedText.length,
@@ -95,6 +113,45 @@ export async function generateSpeech(options) {
         metadata,
         providerMetadata: result.providerMetadata,
         warnings: warnings.length > 0 ? warnings : undefined,
+        timestamps,
     };
 }
+function preprocessText(resolved, rawText, modelIdentifier) {
+    if (resolved.provider.processAudioTags) {
+        return resolved.provider.processAudioTags(rawText, resolved.modelId);
+    }
+    const tags = detectAudioTags(rawText);
+    if (tags.length > 0) {
+        return stripAudioTags(rawText, modelIdentifier);
+    }
+    return { text: rawText, warnings: [] };
+}
+/**
+ * Logs the timestamp routing decision at debug level so developers can see
+ * why they are / aren't getting alignment data. Silent unless `DEBUG`
+ * includes `speech-sdk` (or `*`).
+ */
+function logTimestampDecision(args) {
+    const { modelIdentifier, mode, willRequestNative } = args;
+    if (mode === "off") {
+        debug(`${modelIdentifier}: timestamps: "off" — skipping alignment.`);
+        return;
+    }
+    if (willRequestNative) {
+        debug(`${modelIdentifier}: timestamps: "${mode}" — requesting native alignment from the provider.`);
+        return;
+    }
+    if (mode === "auto") {
+        debug(`${modelIdentifier}: timestamps: "auto" — model has no native alignment; skipping. Pass timestamps: "on" to derive via STT (adds a round-trip of the synthesized audio through Whisper by default).`);
+        return;
+    }
+    // mode === "on" and no native support → will fall back to STT
+    debug(`${modelIdentifier}: timestamps: "on" but no native alignment available — will pipe synthesized audio through ${describeSTTTarget(args.timestampProvider)} for word timestamps (adds a round-trip).`);
+}
+function describeSTTTarget(provider) {
+    if (provider) {
+        return `${provider.provider.id}/${provider.modelId}`;
+    }
+    return "openai/whisper-1 (default)";
+}
 //# sourceMappingURL=generate-speech.js.map

package/dist/generate-speech.js.map

@@ -1 +1 @@
-{"version":3,"file":"generate-speech.js","sourceRoot":"","sources":["../src/generate-speech.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"generate-speech.js","sourceRoot":"","sources":["../src/generate-speech.ts"],"names":[],"mappings":"AAAA,OAAO,MAAM,MAAM,SAAS,CAAC;AAC7B,OAAO,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAC3D,OAAO,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAClE,OAAO,EAAE,sBAAsB,EAAE,MAAM,wBAAwB,CAAC;AAChE,OAAO,EACL,QAAQ,EACR,sBAAsB,EACtB,gCAAgC,GACjC,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AAEpC,OAAO,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AACrD,OAAO,EACL,6BAA6B,GAG9B,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EAAE,yBAAyB,EAAE,MAAM,oBAAoB,CAAC;AAI/D,MAAM,CAAC,KAAK,UAAU,cAAc,CAA0B,OAkC7D;IACC,MAAM,EACJ,KAAK,EACL,KAAK,EACL,WAAW,EACX,OAAO,EACP,UAAU,EACV,UAAU,EAAE,aAAa,GAAG,MAAM,EAClC,iBAAiB,GAClB,GAAG,OAAO,CAAC;IACZ,MAAM,UAAU,GAAG,OAAO,CAAC,UAAU,IAAI,CAAC,CAAC;IAE3C,MAAM,QAAQ,GAAG,YAAY,CAAC,KAAK,EAAE,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IACjE,MAAM,eAAe,GAAG,GAAG,QAAQ,CAAC,QAAQ,CAAC,EAAE,IAAI,QAAQ,CAAC,OAAO,EAAE,CAAC;IAEtE,IAAI,eAAe,GAAG,OAAO,CAAC,eAAe,CAAC;IAE9C,IAAI,UAAU,IAAI,IAAI,EAAE,CAAC;QACvB,MAAM,UAAU,GAAG,QAAQ,CAAC,QAAQ,CAAC,gBAAgB,EAAE,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;QAC1E,IAAI,CAAC,UAAU,EAAE,CAAC;YAChB,MAAM,IAAI,gCAAgC,CAAC,eAAe,CAAC,CAAC;QAC9D,CAAC;QACD,sEAAsE;QACtE,wEAAwE;QACxE,mEAAmE;QACnE,eAAe,GAAG;YAChB,GAAG,OAAO,CAAC,eAAe;YAC1B,GAAG,UAAU,CAAC,eAAe;SAC9B,CAAC;IACJ,CAAC;IAED,MAAM,EAAE,IAAI,EAAE,aAAa,EAAE,QAAQ,EAAE,GAAG,cAAc,CACtD,QAAQ,EACR,OAAO,CAAC,IAAI,EACZ,eAAe,CAChB,CAAC;IAEF,IAAI,aAAa,CAAC,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACtC,MAAM,IAAI,sBAAsB,CAC9B,QAAQ,CAAC,MAAM,GAAG,CAAC;YACjB,CAAC,CAAC,2DAA2D,eAAe,GAAG;YAC/E,CAAC,CAAC,yBAAyB,CAC9B,CAAC;IACJ,CAAC;IAED,MAAM,mBAAmB,GAAG,6BAA6B,CAAC,QAAQ,CAAC,CAAC;IAEpE,uEAAuE;IACvE,yCAAyC;IACzC,MAAM,mBAAmB,GACvB,CAAC,aAAa,KAAK,IAAI,IAAI,aAAa,KAAK,MAAM,CAAC,IAAI,mBAAmB,CAAC;IAE9E,oBAAoB,CAAC;QACnB,eAAe;QACf,IAAI,EAAE,aAAa;QACnB,SAAS,EAAE,mBAAmB;QAC9B,iBAAiB,EAAE,mBAAmB;QACtC,iBAAiB;KAClB,CAAC,CAAC;IAEH,MAAM,SAAS,GAAG,WAAW,CAAC,GAAG,EAAE,CAAC;IAEpC,MAAM,MAAM,GAAG,MAAM,MAAM,CACzB,GAAG,EAAE,CACH,QAAQ,CAAC,QAAQ,CAAC,QAAQ,CAAC;QACzB,OAAO,EAAE,QAAQ,CAAC,OAAO;QACzB,IAAI,EAAE,aAAa;QACnB,KAAK;QACL,eAAe;QACf,WAAW;QACX,OAAO;QACP,iBAAiB,EAAE,mBAAmB;KACvC,CAAC,EACJ;QACE,OAAO,EAAE,UAAU;QACnB,MAAM,EAAE,WAAW;QACnB,WAAW,EAAE,CAAC,EAAE,KAAK,EAAE,EAAE,EAAE;YACzB,IAAI,KAAK,YAAY,QAAQ,IAAI,KAAK,CAAC,UAAU,GAAG,GAAG,EAAE,CAAC;gBACxD,OAAO,KAAK,CAAC;YACf,CAAC;YACD,OAAO,IAAI,CAAC;QACd,CAAC;KACF,CACF,CAAC;IAEF,MAAM,SAAS,GAAG,IAAI,CAAC,KAAK,CAAC,WAAW,CAAC,GAAG,EAAE,GAAG,SAAS,CAAC,CAAC;IAE5D,MAAM,SAAS,GAAG,MAAM,CAAC,KAAK,CAAC;IAE/B,IAAI,SAAS,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC3B,MAAM,IAAI,sBAAsB,EAAE,CAAC;IACrC,CAAC;IAED,IAAI,WAAW,GAAwB,SAAS,CAAC;IACjD,IAAI,eAAe,GAAG,MAAM,CAAC,SAAS,CAAC;IAEvC,IAAI,UAAU,IAAI,IAAI,EAAE,CAAC;QACvB,MAAM,EAAE,YAAY,EAAE,GAAG,MAAM,MAAM,CAAC,oBAAoB,CAAC,CAAC;QAC5D,WAAW,GAAG,MAAM,YAAY,CAAC;YAC/B,KAAK,EAAE,SAAS;YAChB,SAAS,EAAE,MAAM,CAAC,SAAS;YAC3B,UAAU;SACX,CAAC,CAAC;QACH,eAAe,GAAG,WAAW,CAAC;IAChC,CAAC;IAED,MAAM,KAAK,GAAG,IAAI,yBAAyB,CAAC;QAC1C,IAAI,EAAE,WAAW;QACjB,SAAS,EAAE,eAAe;KAC3B,CAAC,CAAC;IAEH,MAAM,eAAe,GACnB,CAAC,MAAM,oBAAoB,CAAC,KAAK,CAAC,UAAU,EAAE,eAAe,CAAC,CAAC;QAC/D,MAAM,CAAC,eAAe,CAAC;IAEzB,IAAI,UAAgD,CAAC;IACrD,IAAI,aAAa,KAAK,KAAK,EAAE,CAAC;QAC5B,IAAI,MAAM,CAAC,UAAU,IAAI,MAAM,CAAC,UAAU,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACtD,KAAK,CACH,GAAG,eAAe,cAAc,MAAM,CAAC,UAAU,CAAC,MAAM,0BAA0B,CACnF,CAAC;YACF,UAAU,GAAG,MAAM,CAAC,UAAU,CAAC;QACjC,CAAC;aAAM,IAAI,aAAa,KAAK,IAAI,EAAE,CAAC;YAClC,UAAU,GAAG,MAAM,sBAAsB,CAAC;gBACxC,QAAQ,EAAE,eAAe;gBACzB,KAAK,EAAE,KAAK,CAAC,UAAU;gBACvB,SAAS,EAAE,eAAe;gBAC1B,iBAAiB;gBACjB,WAAW;aACZ,CAAC,CAAC;YACH,KAAK,CACH,GAAG,eAAe,aAAa,UAAU,CAAC,MAAM,oCAAoC,CACrF,CAAC;QACJ,CAAC;IACH,CAAC;IAED,MAAM,QAAQ,GAAmB;QAC/B,SAAS;QACT,UAAU,EAAE,aAAa,CAAC,MAAM;QAChC,QAAQ,EAAE,QAAQ,CAAC,QAAQ,CAAC,EAAE;QAC9B,KAAK,EAAE,QAAQ,CAAC,OAAO;QACvB,GAAG,CAAC,eAAe,IAAI,IAAI,IAAI,EAAE,eAAe,EAAE,CAAC;KACpD,CAAC;IAEF,OAAO;QACL,KAAK;QACL,QAAQ;QACR,gBAAgB,EAAE,MAAM,CAAC,gBAAgB;QACzC,QAAQ,EAAE,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,SAAS;QACpD,UAAU;KACX,CAAC;AACJ,CAAC;AAED,SAAS,cAAc,CACrB,QAAuB,EACvB,OAAe,EACf,eAAuB;IAEvB,IAAI,QAAQ,CAAC,QAAQ,CAAC,gBAAgB,EAAE,CAAC;QACvC,OAAO,QAAQ,CAAC,QAAQ,CAAC,gBAAgB,CAAC,OAAO,EAAE,QAAQ,CAAC,OAAO,CAAC,CAAC;IACvE,CAAC;IACD,MAAM,IAAI,GAAG,eAAe,CAAC,OAAO,CAAC,CAAC;IACtC,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACpB,OAAO,cAAc,CAAC,OAAO,EAAE,eAAe,CAAC,CAAC;IAClD,CAAC;IACD,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,QAAQ,EAAE,EAAE,EAAE,CAAC;AACzC,CAAC;AAED;;;;GAIG;AACH,SAAS,oBAAoB,CAAC,IAM7B;IACC,MAAM,EAAE,eAAe,EAAE,IAAI,EAAE,iBAAiB,EAAE,GAAG,IAAI,CAAC;IAC1D,IAAI,IAAI,KAAK,KAAK,EAAE,CAAC;QACnB,KAAK,CAAC,GAAG,eAAe,2CAA2C,CAAC,CAAC;QACrE,OAAO;IACT,CAAC;IACD,IAAI,iBAAiB,EAAE,CAAC;QACtB,KAAK,CACH,GAAG,eAAe,kBAAkB,IAAI,oDAAoD,CAC7F,CAAC;QACF,OAAO;IACT,CAAC;IACD,IAAI,IAAI,KAAK,MAAM,EAAE,CAAC;QACpB,KAAK,CACH,GAAG,eAAe,kLAAkL,CACrM,CAAC;QACF,OAAO;IACT,CAAC;IACD,8DAA8D;IAC9D,KAAK,CACH,GAAG,eAAe,8FAA8F,iBAAiB,CAAC,IAAI,CAAC,iBAAiB,CAAC,2CAA2C,CACrM,CAAC;AACJ,CAAC;AAED,SAAS,iBAAiB,CAAC,QAAsC;IAC/D,IAAI,QAAQ,EAAE,CAAC;QACb,OAAO,GAAG,QAAQ,CAAC,QAAQ,CAAC,EAAE,IAAI,QAAQ,CAAC,OAAO,EAAE,CAAC;IACvD,CAAC;IACD,OAAO,4BAA4B,CAAC;AACtC,CAAC"}

package/dist/index.d.ts

@@ -1,11 +1,15 @@
 export { detectAudioTags, stripAudioTags } from "./audio-tags.js";
-export { ApiError, NoSpeechGeneratedError, SpeechSDKError, StreamingNotSupportedError, } from "./errors.js";
+export type { CaptionFormat, CaptionsOptions } from "./captions.js";
+export { timestampsToCaptions } from "./captions.js";
+export { ApiError, NoSpeechGeneratedError, SpeechSDKError, StreamingNotSupportedError, TimestampKeyMissingError, } from "./errors.js";
 export { generateSpeech } from "./generate-speech.js";
 export type { SpeechMetadata } from "./metadata.js";
-export type { Feature, ModelInfo, ResolvedModel, SpeechProvider, Voice, } from "./speech-provider.js";
+export type { Feature, ModelInfo, ResolvedModel, SpeechProvider, TimestampsFeature, Voice, } from "./speech-provider.js";
 export { FEATURES, getFeature, hasFeature, } from "./speech-provider.js";
 export type { GeneratedAudioFile, SpeechResult } from "./speech-result.js";
+export type { ResolvedSTTModel, SpeechToTextProvider, STTModelInfo, } from "./speech-to-text-provider.js";
 export { streamSpeech } from "./stream-speech.js";
 export type { StreamSpeechResult } from "./stream-speech-result.js";
+export type { TimestampMode, WordTimestamp } from "./timestamps.js";
 export type { GenerateSpeechOptions } from "./types.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAClE,OAAO,EACL,QAAQ,EACR,sBAAsB,EACtB,cAAc,EACd,0BAA0B,GAC3B,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACtD,YAAY,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AACpD,YAAY,EACV,OAAO,EACP,SAAS,EACT,aAAa,EACb,cAAc,EACd,KAAK,GACN,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EACL,QAAQ,EACR,UAAU,EACV,UAAU,GACX,MAAM,sBAAsB,CAAC;AAC9B,YAAY,EAAE,kBAAkB,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAC3E,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,YAAY,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AACpE,YAAY,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAClE,YAAY,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AACpE,OAAO,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAC;AACrD,OAAO,EACL,QAAQ,EACR,sBAAsB,EACtB,cAAc,EACd,0BAA0B,EAC1B,wBAAwB,GACzB,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACtD,YAAY,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AACpD,YAAY,EACV,OAAO,EACP,SAAS,EACT,aAAa,EACb,cAAc,EACd,iBAAiB,EACjB,KAAK,GACN,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EACL,QAAQ,EACR,UAAU,EACV,UAAU,GACX,MAAM,sBAAsB,CAAC;AAC9B,YAAY,EAAE,kBAAkB,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAC3E,YAAY,EACV,gBAAgB,EAChB,oBAAoB,EACpB,YAAY,GACb,MAAM,8BAA8B,CAAC;AACtC,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,YAAY,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AACpE,YAAY,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AACpE,YAAY,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -1,6 +1,7 @@
 // biome-ignore lint/performance/noBarrelFile: intentional public API barrel
 export { detectAudioTags, stripAudioTags } from "./audio-tags.js";
-export { ApiError, NoSpeechGeneratedError, SpeechSDKError, StreamingNotSupportedError, } from "./errors.js";
+export { timestampsToCaptions } from "./captions.js";
+export { ApiError, NoSpeechGeneratedError, SpeechSDKError, StreamingNotSupportedError, TimestampKeyMissingError, } from "./errors.js";
 export { generateSpeech } from "./generate-speech.js";
 export { FEATURES, getFeature, hasFeature, } from "./speech-provider.js";
 export { streamSpeech } from "./stream-speech.js";

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,4EAA4E;AAC5E,OAAO,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAClE,OAAO,EACL,QAAQ,EACR,sBAAsB,EACtB,cAAc,EACd,0BAA0B,GAC3B,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAStD,OAAO,EACL,QAAQ,EACR,UAAU,EACV,UAAU,GACX,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,4EAA4E;AAC5E,OAAO,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAElE,OAAO,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAC;AACrD,OAAO,EACL,QAAQ,EACR,sBAAsB,EACtB,cAAc,EACd,0BAA0B,EAC1B,wBAAwB,GACzB,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAUtD,OAAO,EACL,QAAQ,EACR,UAAU,EACV,UAAU,GACX,MAAM,sBAAsB,CAAC;AAO9B,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC"}

package/dist/logger.d.ts

@@ -0,0 +1,2 @@
+export declare function debug(message: string): void;
+//# sourceMappingURL=logger.d.ts.map

package/dist/logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../src/logger.ts"],"names":[],"mappings":"AAsCA,wBAAgB,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAK3C"}

package/dist/logger.js

@@ -0,0 +1,40 @@
+/**
+ * Minimal debug-level logger. Emits a namespaced message only when the
+ * `DEBUG` env var opts in (convention borrowed from the `debug` npm
+ * package, without the dependency). Matches any of:
+ *   DEBUG=*              enables everything
+ *   DEBUG=speech-sdk     enables the SDK
+ *   DEBUG=speech-sdk:*   same (wildcard namespace)
+ *   DEBUG=foo,speech-sdk comma list
+ */
+const NAMESPACE = "speech-sdk";
+function debugEnabled() {
+    if (typeof process === "undefined" || !process.env?.DEBUG) {
+        return false;
+    }
+    const raw = process.env.DEBUG;
+    if (raw === "*") {
+        return true;
+    }
+    for (const entry of raw.split(",")) {
+        const trimmed = entry.trim();
+        if (trimmed === NAMESPACE ||
+            trimmed === `${NAMESPACE}:*` ||
+            trimmed.startsWith(`${NAMESPACE}:`)) {
+            return true;
+        }
+    }
+    return false;
+}
+// Evaluated once at module load; avoids reading env on every call in hot
+// paths. Developers toggling DEBUG mid-process would need to re-import —
+// acceptable trade-off since debug logging is an operator concern set at
+// startup, not a runtime setting.
+const ENABLED = debugEnabled();
+export function debug(message) {
+    if (!ENABLED) {
+        return;
+    }
+    console.debug(`[${NAMESPACE}] ${message}`);
+}
+//# sourceMappingURL=logger.js.map

package/dist/logger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.js","sourceRoot":"","sources":["../src/logger.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,MAAM,SAAS,GAAG,YAAY,CAAC;AAE/B,SAAS,YAAY;IACnB,IAAI,OAAO,OAAO,KAAK,WAAW,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,KAAK,EAAE,CAAC;QAC1D,OAAO,KAAK,CAAC;IACf,CAAC;IACD,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC;IAC9B,IAAI,GAAG,KAAK,GAAG,EAAE,CAAC;QAChB,OAAO,IAAI,CAAC;IACd,CAAC;IACD,KAAK,MAAM,KAAK,IAAI,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC;QACnC,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC;QAC7B,IACE,OAAO,KAAK,SAAS;YACrB,OAAO,KAAK,GAAG,SAAS,IAAI;YAC5B,OAAO,CAAC,UAAU,CAAC,GAAG,SAAS,GAAG,CAAC,EACnC,CAAC;YACD,OAAO,IAAI,CAAC;QACd,CAAC;IACH,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,yEAAyE;AACzE,yEAAyE;AACzE,yEAAyE;AACzE,kCAAkC;AAClC,MAAM,OAAO,GAAG,YAAY,EAAE,CAAC;AAE/B,MAAM,UAAU,KAAK,CAAC,OAAe;IACnC,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,OAAO;IACT,CAAC;IACD,OAAO,CAAC,KAAK,CAAC,IAAI,SAAS,KAAK,OAAO,EAAE,CAAC,CAAC;AAC7C,CAAC"}

package/dist/provider-utils.d.ts

@@ -1,4 +1,12 @@
 export declare const SDK_USER_AGENT = "jellypod-speech-sdk";
+/**
+ * Split a `"provider/model"` spec into its parts. Spec with no slash is
+ * treated as a bare provider name (caller falls back to `defaultModel`).
+ */
+export declare function parseProviderModelSpec(spec: string): {
+    providerName: string;
+    modelId: string | undefined;
+};
 export declare function resolveApiKey(stored: string | undefined, envVar: string, providerName: string): string;
 export declare function handleErrorResponse(response: Response, model: string): Promise<void>;
 //# sourceMappingURL=provider-utils.d.ts.map

package/dist/provider-utils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"provider-utils.d.ts","sourceRoot":"","sources":["../src/provider-utils.ts"],"names":[],"mappings":"AAMA,eAAO,MAAM,cAAc,wBAAwB,CAAC;AAEpD,wBAAgB,aAAa,CAC3B,MAAM,EAAE,MAAM,GAAG,SAAS,EAC1B,MAAM,EAAE,MAAM,EACd,YAAY,EAAE,MAAM,GACnB,MAAM,CAUR;AA+BD,wBAAsB,mBAAmB,CACvC,QAAQ,EAAE,QAAQ,EAClB,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,IAAI,CAAC,CAcf"}
+{"version":3,"file":"provider-utils.d.ts","sourceRoot":"","sources":["../src/provider-utils.ts"],"names":[],"mappings":"AAMA,eAAO,MAAM,cAAc,wBAAwB,CAAC;AAEpD;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,MAAM,GAAG;IACpD,YAAY,EAAE,MAAM,CAAC;IACrB,OAAO,EAAE,MAAM,GAAG,SAAS,CAAC;CAC7B,CASA;AAED,wBAAgB,aAAa,CAC3B,MAAM,EAAE,MAAM,GAAG,SAAS,EAC1B,MAAM,EAAE,MAAM,EACd,YAAY,EAAE,MAAM,GACnB,MAAM,CAQR;AA+BD,wBAAsB,mBAAmB,CACvC,QAAQ,EAAE,QAAQ,EAClB,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,IAAI,CAAC,CAcf"}

package/dist/provider-utils.js

@@ -1,14 +1,28 @@
-import { ApiError } from "./errors.js";
+import { ApiError, MissingApiKeyError } from "./errors.js";
 // Identifies traffic originating from this SDK so providers can bucket
 // usage by integration. Sent as `X-User-Agent` because `User-Agent` is
 // a forbidden header name in browser fetch. Callers may override via
 // options.headers.
 export const SDK_USER_AGENT = "jellypod-speech-sdk";
+/**
+ * Split a `"provider/model"` spec into its parts. Spec with no slash is
+ * treated as a bare provider name (caller falls back to `defaultModel`).
+ */
+export function parseProviderModelSpec(spec) {
+    const slashIndex = spec.indexOf("/");
+    if (slashIndex === -1) {
+        return { providerName: spec, modelId: undefined };
+    }
+    return {
+        providerName: spec.slice(0, slashIndex),
+        modelId: spec.slice(slashIndex + 1) || undefined,
+    };
+}
 export function resolveApiKey(stored, envVar, providerName) {
     const key = stored ??
         (typeof process === "undefined" ? undefined : process.env?.[envVar]);
     if (!key) {
-        throw new Error(`${providerName} API key is required. Pass it via apiKey option or set the ${envVar} environment variable.`);
+        throw new MissingApiKeyError({ providerName, envVar });
     }
     return key;
 }

package/dist/provider-utils.js.map

@@ -1 +1 @@
-{"version":3,"file":"provider-utils.js","sourceRoot":"","sources":["../src/provider-utils.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAEvC,uEAAuE;AACvE,uEAAuE;AACvE,qEAAqE;AACrE,mBAAmB;AACnB,MAAM,CAAC,MAAM,cAAc,GAAG,qBAAqB,CAAC;AAEpD,MAAM,UAAU,aAAa,CAC3B,MAA0B,EAC1B,MAAc,EACd,YAAoB;IAEpB,MAAM,GAAG,GACP,MAAM;QACN,CAAC,OAAO,OAAO,KAAK,WAAW,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,OAAO,CAAC,GAAG,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC;IACvE,IAAI,CAAC,GAAG,EAAE,CAAC;QACT,MAAM,IAAI,KAAK,CACb,GAAG,YAAY,8DAA8D,MAAM,wBAAwB,CAC5G,CAAC;IACJ,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED,SAAS,mBAAmB,CAAC,IAAwB;IACnD,IAAI,CAAC,IAAI,EAAE,CAAC;QACV,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,IAAI,CAAC;QACH,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QAC9B,+BAA+B;QAC/B,IAAI,OAAO,IAAI,CAAC,KAAK,KAAK,QAAQ,EAAE,CAAC;YACnC,OAAO,IAAI,CAAC,KAAK,CAAC;QACpB,CAAC;QACD,IAAI,OAAO,IAAI,CAAC,KAAK,EAAE,OAAO,KAAK,QAAQ,EAAE,CAAC;YAC5C,OAAO,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC;QAC5B,CAAC;QACD,IAAI,OAAO,IAAI,CAAC,OAAO,KAAK,QAAQ,EAAE,CAAC;YACrC,OAAO,IAAI,CAAC,OAAO,CAAC;QACtB,CAAC;QACD,IAAI,OAAO,IAAI,CAAC,MAAM,KAAK,QAAQ,EAAE,CAAC;YACpC,OAAO,IAAI,CAAC,MAAM,CAAC;QACrB,CAAC;IACH,CAAC;IAAC,MAAM,CAAC;QACP,qCAAqC;QACrC,IAAI,IAAI,CAAC,MAAM,GAAG,GAAG,EAAE,CAAC;YACtB,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,GAAG,CAAC;QAClC,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC;IACD,OAAO,IAAI,CAAC,MAAM,GAAG,GAAG,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC;AAC7D,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,mBAAmB,CACvC,QAAkB,EAClB,KAAa;IAEb,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;QACjB,MAAM,YAAY,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;QAClE,MAAM,MAAM,GAAG,mBAAmB,CAAC,YAAY,CAAC,CAAC;QACjD,MAAM,OAAO,GAAG,MAAM;YACpB,CAAC,CAAC,GAAG,KAAK,cAAc,QAAQ,CAAC,MAAM,KAAK,MAAM,EAAE;YACpD,CAAC,CAAC,GAAG,KAAK,cAAc,QAAQ,CAAC,MAAM,EAAE,CAAC;QAE5C,MAAM,IAAI,QAAQ,CAAC,OAAO,EAAE;YAC1B,UAAU,EAAE,QAAQ,CAAC,MAAM;YAC3B,KAAK;YACL,YAAY;SACb,CAAC,CAAC;IACL,CAAC;AACH,CAAC"}
+{"version":3,"file":"provider-utils.js","sourceRoot":"","sources":["../src/provider-utils.ts"],"names":[],"mappings":"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"}

package/dist/providers/cartesia/alignment.d.ts

@@ -0,0 +1,24 @@
+import type { WordTimestamp } from "../../timestamps.js";
+/**
+ * Shape of the `word_timestamps` block inside a Cartesia SSE/WebSocket
+ * `type: "timestamps"` message. Three parallel arrays — index N is the Nth
+ * word's text (`words[N]`), start time (`start[N]`, seconds), and end time
+ * (`end[N]`, seconds).
+ *
+ * Cartesia emits these messages incrementally — each message covers a span
+ * of words synthesized so far in the current `context_id`. The SDK
+ * accumulates them in arrival order and flattens at end-of-stream.
+ */
+export interface CartesiaWordTimestamps {
+    readonly end: readonly number[];
+    readonly start: readonly number[];
+    readonly words: readonly string[];
+}
+/**
+ * Flatten a sequence of `word_timestamps` messages — collected as the SSE
+ * stream emitted them — into a single `WordTimestamp[]`. Skips entries past
+ * the shortest array length so a malformed message can't produce undefined
+ * start/end values.
+ */
+export declare function mergeWordTimestampMessages(messages: readonly CartesiaWordTimestamps[]): WordTimestamp[];
+//# sourceMappingURL=alignment.d.ts.map

package/dist/providers/cartesia/alignment.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"alignment.d.ts","sourceRoot":"","sources":["../../../src/providers/cartesia/alignment.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEzD;;;;;;;;;GASG;AACH,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,GAAG,EAAE,SAAS,MAAM,EAAE,CAAC;IAChC,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;CACnC;AAED;;;;;GAKG;AACH,wBAAgB,0BAA0B,CACxC,QAAQ,EAAE,SAAS,sBAAsB,EAAE,GAC1C,aAAa,EAAE,CAejB"}

package/dist/providers/cartesia/alignment.js

@@ -0,0 +1,23 @@
+/**
+ * Flatten a sequence of `word_timestamps` messages — collected as the SSE
+ * stream emitted them — into a single `WordTimestamp[]`. Skips entries past
+ * the shortest array length so a malformed message can't produce undefined
+ * start/end values.
+ */
+export function mergeWordTimestampMessages(messages) {
+    const out = [];
+    for (const msg of messages) {
+        const len = Math.min(msg.words.length, msg.start.length, msg.end.length);
+        for (let i = 0; i < len; i++) {
+            const text = msg.words[i];
+            const start = msg.start[i];
+            const end = msg.end[i];
+            if (text == null || start == null || end == null) {
+                continue;
+            }
+            out.push({ text, start, end });
+        }
+    }
+    return out;
+}
+//# sourceMappingURL=alignment.js.map

package/dist/providers/cartesia/alignment.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"alignment.js","sourceRoot":"","sources":["../../../src/providers/cartesia/alignment.ts"],"names":[],"mappings":"AAkBA;;;;;GAKG;AACH,MAAM,UAAU,0BAA0B,CACxC,QAA2C;IAE3C,MAAM,GAAG,GAAoB,EAAE,CAAC;IAChC,KAAK,MAAM,GAAG,IAAI,QAAQ,EAAE,CAAC;QAC3B,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,KAAK,CAAC,MAAM,EAAE,GAAG,CAAC,KAAK,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;QACzE,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,GAAG,EAAE,CAAC,EAAE,EAAE,CAAC;YAC7B,MAAM,IAAI,GAAG,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;YAC1B,MAAM,KAAK,GAAG,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;YAC3B,MAAM,GAAG,GAAG,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;YACvB,IAAI,IAAI,IAAI,IAAI,IAAI,KAAK,IAAI,IAAI,IAAI,GAAG,IAAI,IAAI,EAAE,CAAC;gBACjD,SAAS;YACX,CAAC;YACD,GAAG,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC,CAAC;QACjC,CAAC;IACH,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC"}

package/dist/providers/cartesia/index.d.ts

@@ -1,4 +1,5 @@
 import { type ResolvedModel, type SpeechProvider } from "../../speech-provider.js";
+import type { WordTimestamp } from "../../timestamps.js";
 export interface CartesiaSpeechProviderConfig {
     apiKey?: string;
     baseURL?: string;
@@ -11,12 +12,18 @@ export declare class CartesiaSpeechProvider implements SpeechProvider<string, st
         readonly id: "sonic-3";
         readonly releaseDate: "2025-10-27";
         readonly languages: readonly ["en", "fr", "de", "es", "pt", "zh", "ja", "hi", "it", "ko", "nl", "pl", "ru", "sv", "tr", "tl", "bg", "ro", "ar", "cs", "el", "fi", "hr", "ms", "sk", "da", "ta", "uk", "hu", "no", "vi", "bn", "th", "he", "ka", "id", "te", "gu", "kn", "ml", "mr", "pa"];
-        readonly features: readonly ["streaming", "audio-tags", "inline-voice-cloning"];
+        readonly features: readonly ["streaming", "audio-tags", "inline-voice-cloning", {
+            readonly id: "timestamps";
+            readonly mode: "native";
+        }];
     }, {
         readonly id: "sonic-2";
         readonly releaseDate: "2025-03-13";
         readonly languages: readonly ["en"];
-        readonly features: readonly ["streaming"];
+        readonly features: readonly ["streaming", {
+            readonly id: "timestamps";
+            readonly mode: "native";
+        }];
     }];
     private static readonly PASSTHROUGH_TAGS;
     private static readonly EMOTIONS;
@@ -35,11 +42,14 @@ export declare class CartesiaSpeechProvider implements SpeechProvider<string, st
         providerOptions?: Record<string, unknown>;
         abortSignal?: AbortSignal;
         headers?: Record<string, string>;
+        includeTimestamps?: boolean;
     }): Promise<{
         audio: Uint8Array;
         mediaType: string;
         providerMetadata?: Record<string, unknown>;
+        timestamps?: WordTimestamp[];
     }>;
+    private generateWithTimestamps;
     stream(options: {
         modelId: string;
         text: string;