@speech-sdk/core 0.6.1 → 0.7.0

package/dist/__tests__/e2e/_save-audio.d.ts

@@ -1,11 +1,60 @@
+import { generateConversation as _generateConversation } from "../../generate-conversation.js";
+import { generateSpeech as _generateSpeech } from "../../generate-speech.js";
+import type { WordTimestamp } from "../../timestamps.js";
 /**
  * Write a test-generated audio file to `SPEECH_SDK_E2E_OUTPUT_DIR` if the env
  * var is set. No-op otherwise, so normal CI runs don't produce artifacts.
- * Intended to let conversation e2e tests double as a way to sample provider
- * output (e.g. `SPEECH_SDK_E2E_OUTPUT_DIR=~/Downloads/convos pnpm test:e2e`).
+ * Usually you don't need to call this directly — use the `generateSpeech`,
+ * `generateConversation`, and `collectStreamAndSave` helpers exported from
+ * this module, which autosave using the current test name.
+ *
+ * Output layout: `$SPEECH_SDK_E2E_OUTPUT_DIR/<provider-file>/<test-slug>.<ext>`.
+ * If the same test saves multiple times, subsequent files are suffixed `-2`,
+ * `-3`, etc.
  */
 export declare function maybeSaveAudio(name: string, audio: {
     uint8Array: Uint8Array;
     mediaType: string;
 }): Promise<void>;
+/**
+ * Like {@link maybeSaveAudio}, plus — when `timestamps` is non-empty — also
+ * writes the raw alignment JSON and rendered SRT/VTT caption files alongside
+ * the audio. All four files share the same stem so they stay paired across
+ * multi-call tests. Still a no-op when `SPEECH_SDK_E2E_OUTPUT_DIR` is unset.
+ *
+ * Output layout (when timestamps present):
+ * ```
+ * <dir>/<bucket>/<slug>.<audio-ext>
+ * <dir>/<bucket>/<slug>.timestamps.json
+ * <dir>/<bucket>/<slug>.srt
+ * <dir>/<bucket>/<slug>.vtt
+ * ```
+ */
+export declare function maybeSaveResult(name: string, audio: {
+    uint8Array: Uint8Array;
+    mediaType: string;
+}, timestamps?: readonly WordTimestamp[]): Promise<void>;
+/**
+ * Drop-in replacement for `generateSpeech` that autosaves to
+ * `SPEECH_SDK_E2E_OUTPUT_DIR` using the current vitest test name. When the
+ * result includes word timestamps, also writes paired `.timestamps.json`,
+ * `.srt`, and `.vtt` files.
+ */
+export declare const generateSpeech: typeof _generateSpeech;
+/**
+ * Drop-in replacement for `generateConversation` that autosaves to
+ * `SPEECH_SDK_E2E_OUTPUT_DIR` using the current vitest test name. When the
+ * result includes word timestamps, also writes paired `.timestamps.json`,
+ * `.srt`, and `.vtt` files.
+ */
+export declare const generateConversation: typeof _generateConversation;
+/**
+ * Collects a streamed `streamSpeech` result into bytes AND autosaves them to
+ * `SPEECH_SDK_E2E_OUTPUT_DIR` using the current vitest test name. Use in place
+ * of `collectStream(result.audio)` in e2e tests.
+ */
+export declare function collectStreamAndSave(result: {
+    audio: ReadableStream<Uint8Array>;
+    mediaType: string;
+}): Promise<Uint8Array>;
 //# sourceMappingURL=_save-audio.d.ts.map

package/dist/__tests__/e2e/_save-audio.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"_save-audio.d.ts","sourceRoot":"","sources":["../../../src/__tests__/e2e/_save-audio.ts"],"names":[],"mappings":"AAyBA;;;;;GAKG;AACH,wBAAsB,cAAc,CAClC,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE;IAAE,UAAU,EAAE,UAAU,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,GACnD,OAAO,CAAC,IAAI,CAAC,CAYf"}
+{"version":3,"file":"_save-audio.d.ts","sourceRoot":"","sources":["../../../src/__tests__/e2e/_save-audio.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,oBAAoB,IAAI,qBAAqB,EAAE,MAAM,gCAAgC,CAAC;AAC/F,OAAO,EAAE,cAAc,IAAI,eAAe,EAAE,MAAM,0BAA0B,CAAC;AAC7E,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AA8FzD;;;;;;;;;;GAUG;AACH,wBAAsB,cAAc,CAClC,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE;IAAE,UAAU,EAAE,UAAU,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,GACnD,OAAO,CAAC,IAAI,CAAC,CAEf;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,eAAe,CACnC,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE;IAAE,UAAU,EAAE,UAAU,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,EACpD,UAAU,CAAC,EAAE,SAAS,aAAa,EAAE,GACpC,OAAO,CAAC,IAAI,CAAC,CA8Bf;AAOD;;;;;GAKG;AACH,eAAO,MAAM,cAAc,EAAE,OAAO,eAMR,CAAC;AAE7B;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB,EAAE,OAAO,qBAMR,CAAC;AAEnC;;;;GAIG;AACH,wBAAsB,oBAAoB,CAAC,MAAM,EAAE;IACjD,KAAK,EAAE,cAAc,CAAC,UAAU,CAAC,CAAC;IAClC,SAAS,EAAE,MAAM,CAAC;CACnB,GAAG,OAAO,CAAC,UAAU,CAAC,CAOtB"}

package/dist/__tests__/e2e/_save-audio.js

@@ -1,5 +1,10 @@
 import { mkdir, writeFile } from "node:fs/promises";
-import { join } from "node:path";
+import { basename, join } from "node:path";
+import { expect } from "vitest";
+import { timestampsToCaptions } from "../../captions.js";
+import { generateConversation as _generateConversation } from "../../generate-conversation.js";
+import { generateSpeech as _generateSpeech } from "../../generate-speech.js";
+import { collectStream } from "./_collect-stream.js";
 function extFor(mediaType) {
     if (mediaType.includes("wav")) {
         return "wav";
@@ -21,23 +26,146 @@ function extFor(mediaType) {
     }
     return "bin";
 }
+const NON_SLUG_CHARS = /[^a-zA-Z0-9._-]+/g;
+const LEADING_OR_TRAILING_UNDERSCORES = /^_+|_+$/g;
+const E2E_TEST_SUFFIX = /\.e2e\.test\.(ts|tsx|js|mjs)$/;
+function slugify(name) {
+    return name
+        .replace(NON_SLUG_CHARS, "_")
+        .replace(LEADING_OR_TRAILING_UNDERSCORES, "");
+}
+function resolveOutputDir() {
+    const dir = process.env.SPEECH_SDK_E2E_OUTPUT_DIR;
+    if (!dir) {
+        return null;
+    }
+    return dir.startsWith("~") ? join(process.env.HOME ?? "", dir.slice(1)) : dir;
+}
+function currentTestContext() {
+    // biome-ignore lint/suspicious/noMisplacedAssertion: reading vitest state, not asserting
+    const state = expect.getState();
+    return {
+        currentTestName: state.currentTestName,
+        testPath: state.testPath,
+    };
+}
+/**
+ * Derives the subdirectory for a given test file. e2e tests are named like
+ * `openai.e2e.test.ts` / `conversation-google.e2e.test.ts`; we strip the
+ * `.e2e.test.ts` suffix and use that as the per-provider bucket so a full run
+ * doesn't dump 100+ files into a single flat directory.
+ */
+function providerBucket(testPath) {
+    if (!testPath) {
+        return "unknown";
+    }
+    const base = basename(testPath).replace(E2E_TEST_SUFFIX, "");
+    return slugify(base) || "unknown";
+}
+// Counter keyed by `${bucket}/${slug}` so multiple generate/stream calls
+// within a single test don't overwrite each other. Vitest isolates modules
+// per file, so this resets per test file — collisions are only meaningful
+// within the same `it`.
+const callCounts = new Map();
+/**
+ * Reserves a filename stem (without extension) for the next save call.
+ * First call returns `slug`; subsequent calls return `slug-2`, `slug-3`, etc.
+ * A single stem is shared across all sibling outputs from one logical save
+ * (audio + timestamps + captions), so they remain paired even across
+ * multiple saves within the same test.
+ */
+function nextStem(bucket, slug) {
+    const key = `${bucket}/${slug}`;
+    const n = (callCounts.get(key) ?? 0) + 1;
+    callCounts.set(key, n);
+    return n === 1 ? slug : `${slug}-${n}`;
+}
+async function writeAndLog(file, data) {
+    await writeFile(file, data);
+    console.log(`[e2e-save] wrote ${file}`);
+}
 /**
  * Write a test-generated audio file to `SPEECH_SDK_E2E_OUTPUT_DIR` if the env
  * var is set. No-op otherwise, so normal CI runs don't produce artifacts.
- * Intended to let conversation e2e tests double as a way to sample provider
- * output (e.g. `SPEECH_SDK_E2E_OUTPUT_DIR=~/Downloads/convos pnpm test:e2e`).
+ * Usually you don't need to call this directly — use the `generateSpeech`,
+ * `generateConversation`, and `collectStreamAndSave` helpers exported from
+ * this module, which autosave using the current test name.
+ *
+ * Output layout: `$SPEECH_SDK_E2E_OUTPUT_DIR/<provider-file>/<test-slug>.<ext>`.
+ * If the same test saves multiple times, subsequent files are suffixed `-2`,
+ * `-3`, etc.
  */
 export async function maybeSaveAudio(name, audio) {
-    const dir = process.env.SPEECH_SDK_E2E_OUTPUT_DIR;
+    await maybeSaveResult(name, audio);
+}
+/**
+ * Like {@link maybeSaveAudio}, plus — when `timestamps` is non-empty — also
+ * writes the raw alignment JSON and rendered SRT/VTT caption files alongside
+ * the audio. All four files share the same stem so they stay paired across
+ * multi-call tests. Still a no-op when `SPEECH_SDK_E2E_OUTPUT_DIR` is unset.
+ *
+ * Output layout (when timestamps present):
+ * ```
+ * <dir>/<bucket>/<slug>.<audio-ext>
+ * <dir>/<bucket>/<slug>.timestamps.json
+ * <dir>/<bucket>/<slug>.srt
+ * <dir>/<bucket>/<slug>.vtt
+ * ```
+ */
+export async function maybeSaveResult(name, audio, timestamps) {
+    const dir = resolveOutputDir();
     if (!dir) {
         return;
     }
-    const expanded = dir.startsWith("~")
-        ? join(process.env.HOME ?? "", dir.slice(1))
-        : dir;
-    await mkdir(expanded, { recursive: true });
-    const file = join(expanded, `${name}.${extFor(audio.mediaType)}`);
-    await writeFile(file, audio.uint8Array);
-    console.log(`[maybeSaveAudio] wrote ${file}`);
+    const { testPath } = currentTestContext();
+    const bucket = providerBucket(testPath);
+    const bucketDir = join(dir, bucket);
+    await mkdir(bucketDir, { recursive: true });
+    const stem = nextStem(bucket, slugify(name));
+    await writeAndLog(join(bucketDir, `${stem}.${extFor(audio.mediaType)}`), audio.uint8Array);
+    if (timestamps && timestamps.length > 0) {
+        await writeAndLog(join(bucketDir, `${stem}.timestamps.json`), `${JSON.stringify(timestamps, null, 2)}\n`);
+        await writeAndLog(join(bucketDir, `${stem}.srt`), timestampsToCaptions(timestamps));
+        await writeAndLog(join(bucketDir, `${stem}.vtt`), timestampsToCaptions(timestamps, { format: "vtt" }));
+    }
+}
+function currentTestSlug() {
+    const { currentTestName } = currentTestContext();
+    return slugify(currentTestName ?? "unnamed") || "unnamed";
+}
+/**
+ * Drop-in replacement for `generateSpeech` that autosaves to
+ * `SPEECH_SDK_E2E_OUTPUT_DIR` using the current vitest test name. When the
+ * result includes word timestamps, also writes paired `.timestamps.json`,
+ * `.srt`, and `.vtt` files.
+ */
+export const generateSpeech = (async (options) => {
+    const result = await _generateSpeech(options);
+    await maybeSaveResult(currentTestSlug(), result.audio, result.timestamps);
+    return result;
+});
+/**
+ * Drop-in replacement for `generateConversation` that autosaves to
+ * `SPEECH_SDK_E2E_OUTPUT_DIR` using the current vitest test name. When the
+ * result includes word timestamps, also writes paired `.timestamps.json`,
+ * `.srt`, and `.vtt` files.
+ */
+export const generateConversation = (async (options) => {
+    const result = await _generateConversation(options);
+    await maybeSaveResult(currentTestSlug(), result.audio, result.timestamps);
+    return result;
+});
+/**
+ * Collects a streamed `streamSpeech` result into bytes AND autosaves them to
+ * `SPEECH_SDK_E2E_OUTPUT_DIR` using the current vitest test name. Use in place
+ * of `collectStream(result.audio)` in e2e tests.
+ */
+export async function collectStreamAndSave(result) {
+    const bytes = await collectStream(result.audio);
+    await maybeSaveAudio(currentTestSlug(), {
+        uint8Array: bytes,
+        mediaType: result.mediaType,
+    });
+    return bytes;
 }
 //# sourceMappingURL=_save-audio.js.map

package/dist/__tests__/e2e/_save-audio.js.map

@@ -1 +1 @@
-{"version":3,"file":"_save-audio.js","sourceRoot":"","sources":["../../../src/__tests__/e2e/_save-audio.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAEjC,SAAS,MAAM,CAAC,SAAiB;IAC/B,IAAI,SAAS,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;QAC9B,OAAO,KAAK,CAAC;IACf,CAAC;IACD,IAAI,SAAS,CAAC,QAAQ,CAAC,MAAM,CAAC,IAAI,SAAS,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;QAC5D,OAAO,KAAK,CAAC;IACf,CAAC;IACD,IAAI,SAAS,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;QAC9B,OAAO,KAAK,CAAC;IACf,CAAC;IACD,IAAI,SAAS,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC;QAC/B,OAAO,MAAM,CAAC;IAChB,CAAC;IACD,IAAI,SAAS,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC;QAC/B,OAAO,MAAM,CAAC;IAChB,CAAC;IACD,IAAI,SAAS,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;QAC9B,OAAO,KAAK,CAAC;IACf,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAClC,IAAY,EACZ,KAAoD;IAEpD,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,yBAAyB,CAAC;IAClD,IAAI,CAAC,GAAG,EAAE,CAAC;QACT,OAAO;IACT,CAAC;IACD,MAAM,QAAQ,GAAG,GAAG,CAAC,UAAU,CAAC,GAAG,CAAC;QAClC,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,IAAI,EAAE,EAAE,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;QAC5C,CAAC,CAAC,GAAG,CAAC;IACR,MAAM,KAAK,CAAC,QAAQ,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAC3C,MAAM,IAAI,GAAG,IAAI,CAAC,QAAQ,EAAE,GAAG,IAAI,IAAI,MAAM,CAAC,KAAK,CAAC,SAAS,CAAC,EAAE,CAAC,CAAC;IAClE,MAAM,SAAS,CAAC,IAAI,EAAE,KAAK,CAAC,UAAU,CAAC,CAAC;IACxC,OAAO,CAAC,GAAG,CAAC,0BAA0B,IAAI,EAAE,CAAC,CAAC;AAChD,CAAC"}
+{"version":3,"file":"_save-audio.js","sourceRoot":"","sources":["../../../src/__tests__/e2e/_save-audio.ts"],"names":[],"mappings":"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"}

package/dist/audio-utils.d.ts

@@ -9,4 +9,6 @@ export declare function parseMediaTypeParam(mediaType: string, name: string): nu
  * does not require the WebCodecs encoder.
  */
 export declare function wrapPcm16Mono(pcm: Uint8Array, sampleRate: number): Promise<Uint8Array>;
+/** Decode a base64 string into raw bytes. */
+export declare function base64ToUint8Array(b64: string): Uint8Array;
 //# sourceMappingURL=audio-utils.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"audio-utils.d.ts","sourceRoot":"","sources":["../src/audio-utils.ts"],"names":[],"mappings":"AAUA;;;GAGG;AACH,wBAAgB,mBAAmB,CACjC,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,MAAM,GACX,MAAM,GAAG,SAAS,CAcpB;AAED;;;;GAIG;AACH,wBAAsB,aAAa,CACjC,GAAG,EAAE,UAAU,EACf,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,UAAU,CAAC,CA2BrB"}
+{"version":3,"file":"audio-utils.d.ts","sourceRoot":"","sources":["../src/audio-utils.ts"],"names":[],"mappings":"AAUA;;;GAGG;AACH,wBAAgB,mBAAmB,CACjC,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,MAAM,GACX,MAAM,GAAG,SAAS,CAcpB;AAED;;;;GAIG;AACH,wBAAsB,aAAa,CACjC,GAAG,EAAE,UAAU,EACf,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,UAAU,CAAC,CA2BrB;AAED,6CAA6C;AAC7C,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,UAAU,CAO1D"}

package/dist/audio-utils.js

@@ -50,4 +50,13 @@ export async function wrapPcm16Mono(pcm, sampleRate) {
     }
     return new Uint8Array(buffer);
 }
+/** Decode a base64 string into raw bytes. */
+export function base64ToUint8Array(b64) {
+    const binary = atob(b64);
+    const bytes = new Uint8Array(binary.length);
+    for (let i = 0; i < binary.length; i++) {
+        bytes[i] = binary.charCodeAt(i);
+    }
+    return bytes;
+}
 //# sourceMappingURL=audio-utils.js.map

package/dist/audio-utils.js.map

@@ -1 +1 @@
-{"version":3,"file":"audio-utils.js","sourceRoot":"","sources":["../src/audio-utils.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,YAAY,EACZ,wBAAwB,EACxB,aAAa,EACb,MAAM,EACN,eAAe,GAChB,MAAM,YAAY,CAAC;AAEpB,MAAM,iBAAiB,GAAG,IAAI,GAAG,EAAkB,CAAC;AAEpD;;;GAGG;AACH,MAAM,UAAU,mBAAmB,CACjC,SAAiB,EACjB,IAAY;IAEZ,IAAI,EAAE,GAAG,iBAAiB,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IACrC,IAAI,CAAC,EAAE,EAAE,CAAC;QACR,sEAAsE;QACtE,oDAAoD;QACpD,EAAE,GAAG,IAAI,MAAM,CAAC,cAAc,IAAI,oBAAoB,EAAE,GAAG,CAAC,CAAC;QAC7D,iBAAiB,CAAC,GAAG,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;IAClC,CAAC;IACD,MAAM,KAAK,GAAG,SAAS,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;IAClC,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;IAC/B,OAAO,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC;AACjE,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CACjC,GAAe,EACf,UAAkB;IAElB,MAAM,MAAM,GAAG,IAAI,MAAM,CAAC;QACxB,MAAM,EAAE,IAAI,eAAe,EAAE;QAC7B,MAAM,EAAE,IAAI,YAAY,EAAE;KAC3B,CAAC,CAAC;IACH,MAAM,MAAM,GAAG,IAAI,wBAAwB,CAAC,SAAS,CAAC,CAAC;IACvD,MAAM,CAAC,aAAa,CAAC,MAAM,CAAC,CAAC;IAC7B,MAAM,MAAM,CAAC,KAAK,EAAE,CAAC;IAErB,4BAA4B;IAC5B,MAAM,UAAU,GAAG,GAAG,CAAC,MAAM,GAAG,CAAC,CAAC;IAClC,MAAM,eAAe,GAAG,UAAU,GAAG,UAAU,CAAC;IAChD,MAAM,MAAM,GAAG,IAAI,aAAa,CAAC,GAAG,EAAE,KAAK,EAAE,CAAC,EAAE,eAAe,EAAE,CAAC,CAAC,CAAC;IACpE,MAAM,MAAM,CAAC,GAAG,CAAC,MAAM,EAAE;QACvB,aAAa,EAAE;YACb,KAAK,EAAE,SAAS;YAChB,gBAAgB,EAAE,CAAC;YACnB,UAAU;SACX;KACF,CAAC,CAAC;IAEH,MAAM,MAAM,CAAC,QAAQ,EAAE,CAAC;IACxB,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC;IACpC,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,MAAM,IAAI,KAAK,CAAC,iDAAiD,CAAC,CAAC;IACrE,CAAC;IACD,OAAO,IAAI,UAAU,CAAC,MAAM,CAAC,CAAC;AAChC,CAAC"}
+{"version":3,"file":"audio-utils.js","sourceRoot":"","sources":["../src/audio-utils.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,YAAY,EACZ,wBAAwB,EACxB,aAAa,EACb,MAAM,EACN,eAAe,GAChB,MAAM,YAAY,CAAC;AAEpB,MAAM,iBAAiB,GAAG,IAAI,GAAG,EAAkB,CAAC;AAEpD;;;GAGG;AACH,MAAM,UAAU,mBAAmB,CACjC,SAAiB,EACjB,IAAY;IAEZ,IAAI,EAAE,GAAG,iBAAiB,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IACrC,IAAI,CAAC,EAAE,EAAE,CAAC;QACR,sEAAsE;QACtE,oDAAoD;QACpD,EAAE,GAAG,IAAI,MAAM,CAAC,cAAc,IAAI,oBAAoB,EAAE,GAAG,CAAC,CAAC;QAC7D,iBAAiB,CAAC,GAAG,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;IAClC,CAAC;IACD,MAAM,KAAK,GAAG,SAAS,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;IAClC,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;IAC/B,OAAO,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC;AACjE,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CACjC,GAAe,EACf,UAAkB;IAElB,MAAM,MAAM,GAAG,IAAI,MAAM,CAAC;QACxB,MAAM,EAAE,IAAI,eAAe,EAAE;QAC7B,MAAM,EAAE,IAAI,YAAY,EAAE;KAC3B,CAAC,CAAC;IACH,MAAM,MAAM,GAAG,IAAI,wBAAwB,CAAC,SAAS,CAAC,CAAC;IACvD,MAAM,CAAC,aAAa,CAAC,MAAM,CAAC,CAAC;IAC7B,MAAM,MAAM,CAAC,KAAK,EAAE,CAAC;IAErB,4BAA4B;IAC5B,MAAM,UAAU,GAAG,GAAG,CAAC,MAAM,GAAG,CAAC,CAAC;IAClC,MAAM,eAAe,GAAG,UAAU,GAAG,UAAU,CAAC;IAChD,MAAM,MAAM,GAAG,IAAI,aAAa,CAAC,GAAG,EAAE,KAAK,EAAE,CAAC,EAAE,eAAe,EAAE,CAAC,CAAC,CAAC;IACpE,MAAM,MAAM,CAAC,GAAG,CAAC,MAAM,EAAE;QACvB,aAAa,EAAE;YACb,KAAK,EAAE,SAAS;YAChB,gBAAgB,EAAE,CAAC;YACnB,UAAU;SACX;KACF,CAAC,CAAC;IAEH,MAAM,MAAM,CAAC,QAAQ,EAAE,CAAC;IACxB,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC;IACpC,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,MAAM,IAAI,KAAK,CAAC,iDAAiD,CAAC,CAAC;IACrE,CAAC;IACD,OAAO,IAAI,UAAU,CAAC,MAAM,CAAC,CAAC;AAChC,CAAC;AAED,6CAA6C;AAC7C,MAAM,UAAU,kBAAkB,CAAC,GAAW;IAC5C,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC;IACzB,MAAM,KAAK,GAAG,IAAI,UAAU,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IAC5C,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACvC,KAAK,CAAC,CAAC,CAAC,GAAG,MAAM,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC;IAClC,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/captions.d.ts

@@ -0,0 +1,137 @@
+import type { WordTimestamp } from "./timestamps.js";
+/**
+ * Sanitizes caption-body text: strips C0 control characters (U+0000–U+001F
+ * minus whitespace, plus U+007F DEL), folds non-ASCII typography (curly
+ * quotes, en/em dashes, ellipsis) to ASCII equivalents, and collapses
+ * whitespace runs to a single space. Exported for testing.
+ */
+export declare function normalizeTypography(text: string): string;
+/**
+ * Escapes characters that would otherwise be interpreted as inline WebVTT
+ * markup. Applied only to the VTT render path; SRT passes raw text through.
+ * Exported for testing; not part of the public API.
+ */
+export declare function escapeVttText(text: string): string;
+/**
+ * Formats a number of seconds as an SRT timestamp: `HH:MM:SS,mmm`.
+ * Negative inputs are clamped to zero. Milliseconds are rounded.
+ * Exported for testing; not part of the public API.
+ */
+export declare function formatSrtTime(seconds: number): string;
+/**
+ * Formats a number of seconds as a WebVTT timestamp: `HH:MM:SS.mmm`.
+ * Negative inputs are clamped to zero. Milliseconds are rounded.
+ * Exported for testing; not part of the public API.
+ */
+export declare function formatVttTime(seconds: number): string;
+/**
+ * Groups a flat list of word timestamps into sentences using terminator
+ * punctuation attached to the trailing word. Supported terminators:
+ *
+ * - ASCII: `.`, `!`, `?`
+ * - CJK: `。`, `！`, `？`
+ * - Devanagari (Hindi, Sanskrit, Marathi): `।`, `॥`
+ * - Arabic: `؟`, `۔`
+ *
+ * A trailing closing quote (`"`, `'`, curly variants, or CJK corner
+ * bracket `」` / `』`) attached to the terminator is tolerated.
+ *
+ * Known limitations:
+ * - Abbreviations like "Dr." or "e.g." are treated as sentence ends.
+ * - Thai and other scripts without word-level whitespace or inline
+ *   terminators fall through to char/duration-based hard breaks.
+ *
+ * Exported for testing; not part of the public API.
+ */
+export declare function groupIntoSentences(words: readonly WordTimestamp[]): WordTimestamp[][];
+interface CueSplitOptions {
+    readonly longPhraseCommaBreakChars: number;
+    readonly maxCharsPerCue: number;
+    readonly maxCueDurationMs: number;
+}
+/**
+ * Subdivides a sentence (an ordered list of words) into one or more cues.
+ * Breaks are chosen in this priority order:
+ *   1. Hard: character budget exceeded → break before the offending word.
+ *   2. Hard: duration exceeded → break before the offending word.
+ *   3. Soft: comma in a word that leaves the current cue above
+ *      `longPhraseCommaBreakChars` → break after that word.
+ *
+ * Exported for testing; not part of the public API.
+ */
+export declare function splitSentenceIntoCues(sentence: readonly WordTimestamp[], options: CueSplitOptions): WordTimestamp[][];
+interface WrapOptions {
+    readonly maxLineLength: number;
+    readonly maxLines: number;
+}
+/**
+ * Wraps a sequence of words into up to `maxLines` lines, trying to keep
+ * each line at or below `maxLineLength` characters. A word longer than
+ * `maxLineLength` is placed on its own line rather than split. If words
+ * remain after the final line is full, they are appended to that final
+ * line (accept overflow; cue splitter is expected to have prevented this
+ * in normal flow).
+ *
+ * Exported for testing; not part of the public API.
+ */
+export declare function wrapCueText(words: readonly string[], options: WrapOptions): string;
+/**
+ * Supported caption output formats.
+ *
+ * - `"srt"` — SubRip (`.srt`). Comma-decimal timestamps, numeric cue IDs,
+ *   plain text bodies. Widely supported by media players and upload tools.
+ * - `"vtt"` — WebVTT (`.vtt`). Period-decimal timestamps, `WEBVTT` header,
+ *   HTML-escaped bodies (`&`, `<`, `>`). Required for HTML `<track>`.
+ */
+export type CaptionFormat = "srt" | "vtt";
+/**
+ * Options for {@link timestampsToCaptions}.
+ */
+export interface CaptionsOptions {
+    /** Output format. Default `"srt"`. */
+    readonly format?: CaptionFormat;
+    /**
+     * Minimum cue-char-count at which a trailing comma triggers a soft cue
+     * break. Prevents tiny fragments after every comma. Default `60`.
+     */
+    readonly longPhraseCommaBreakChars?: number;
+    /** Max total chars per cue. Default `maxLineLength * maxLinesPerCue`. */
+    readonly maxCharsPerCue?: number;
+    /** Max cue duration in milliseconds. Default `7000`. */
+    readonly maxCueDurationMs?: number;
+    /**
+     * Max chars per line (word-boundary wrap). Default `42` — the common
+     * broadcast convention for Latin-alphabet subtitles.
+     *
+     * Character counts use JavaScript `string.length` (UTF-16 code units).
+     * For CJK (Japanese, Chinese, Korean) content, each character is roughly
+     * twice the visual width of an ASCII character in monospaced players;
+     * pass a smaller value (e.g. `16`) to match Japanese broadcast norms.
+     */
+    readonly maxLineLength?: number;
+    /** Max lines per cue. Default `2`. */
+    readonly maxLinesPerCue?: number;
+}
+/**
+ * Converts word-level timestamps into a caption string in SRT or WebVTT
+ * format.
+ *
+ * Sentence boundaries (`.`, `!`, `?` in word text, optionally followed
+ * by a closing quote) create cue breaks; long sentences are subdivided
+ * by character count, duration, and soft comma breaks. Each cue is
+ * greedily wrapped into up to `maxLinesPerCue` lines of `maxLineLength`
+ * characters.
+ *
+ * Returns the empty string for empty input.
+ *
+ * @example
+ * ```ts
+ * const { timestamps } = await generateSpeech({ ... });
+ *
+ * const srt = timestampsToCaptions(timestamps ?? []);
+ * const vtt = timestampsToCaptions(timestamps ?? [], { format: "vtt" });
+ * ```
+ */
+export declare function timestampsToCaptions(timestamps: readonly WordTimestamp[], options?: CaptionsOptions): string;
+export {};
+//# sourceMappingURL=captions.d.ts.map

package/dist/captions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"captions.d.ts","sourceRoot":"","sources":["../src/captions.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAwBrD;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAMxD;AAQD;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAMlD;AAeD;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAErD;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAErD;AAWD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,SAAS,aAAa,EAAE,GAC9B,aAAa,EAAE,EAAE,CAcnB;AAOD,UAAU,eAAe;IACvB,QAAQ,CAAC,yBAAyB,EAAE,MAAM,CAAC;IAC3C,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;CACnC;AA0BD;;;;;;;;;GASG;AACH,wBAAgB,qBAAqB,CACnC,QAAQ,EAAE,SAAS,aAAa,EAAE,EAClC,OAAO,EAAE,eAAe,GACvB,aAAa,EAAE,EAAE,CAgCnB;AAED,UAAU,WAAW;IACnB,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAED;;;;;;;;;GASG;AACH,wBAAgB,WAAW,CACzB,KAAK,EAAE,SAAS,MAAM,EAAE,EACxB,OAAO,EAAE,WAAW,GACnB,MAAM,CAmBR;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,aAAa,GAAG,KAAK,GAAG,KAAK,CAAC;AAE1C;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,sCAAsC;IACtC,QAAQ,CAAC,MAAM,CAAC,EAAE,aAAa,CAAC;IAChC;;;OAGG;IACH,QAAQ,CAAC,yBAAyB,CAAC,EAAE,MAAM,CAAC;IAC5C,yEAAyE;IACzE,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC,wDAAwD;IACxD,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IACnC;;;;;;;;OAQG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,sCAAsC;IACtC,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;CAClC;AAWD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,oBAAoB,CAClC,UAAU,EAAE,SAAS,aAAa,EAAE,EACpC,OAAO,GAAE,eAAoB,GAC5B,MAAM,CAkER"}