@pico-brief/speech-services-parallel 1.0.0

package/dist/concurrency.js

@@ -0,0 +1,84 @@
+/**
+ * Semaphore-based concurrency control for parallel operations.
+ *
+ * Provides {@link mapWithConcurrency}, a `Promise.all`-like helper that caps the
+ * number of in-flight promises at any given time. Result order always matches
+ * the input order regardless of completion order.
+ */
+/**
+ * A counting semaphore that limits the number of concurrent operations.
+ *
+ * When the maximum number of permits is reached, further {@link acquire} calls
+ * will wait in a FIFO queue until a permit is freed via {@link release}.
+ */
+class Semaphore {
+    max;
+    /** Queue of callers waiting for a permit. */
+    queue = [];
+    /** Number of permits currently held. */
+    active = 0;
+    /**
+     * @param max - Maximum number of concurrent permits.
+     */
+    constructor(max) {
+        this.max = max;
+    }
+    /**
+     * Acquires a permit. Resolves immediately if one is available,
+     * otherwise waits until a permit is released.
+     */
+    acquire() {
+        if (this.active < this.max) {
+            this.active++;
+            return Promise.resolve();
+        }
+        return new Promise(resolve => this.queue.push(resolve));
+    }
+    /**
+     * Releases a permit. If callers are waiting in the queue, the next one
+     * is resolved immediately (the active count stays the same).
+     */
+    release() {
+        const next = this.queue.shift();
+        if (next) {
+            // Pass the permit directly to the next waiter (active count unchanged)
+            next();
+        }
+        else {
+            this.active--;
+        }
+    }
+}
+/**
+ * Maps items through an async function with optional concurrency limiting.
+ *
+ * Behaves like `Promise.all(items.map(fn))` but ensures at most `maxConcurrency`
+ * calls to `fn` are in flight at any time. If `maxConcurrency` is `undefined`
+ * or greater than or equal to `items.length`, falls back to plain `Promise.all`.
+ *
+ * Results are always returned in the same order as the input items.
+ *
+ * @typeParam T - Input item type.
+ * @typeParam R - Return type of the async mapper function.
+ * @param items - The items to process.
+ * @param fn - Async function called for each item with its index.
+ * @param maxConcurrency - Optional cap on the number of concurrent `fn` calls.
+ * @returns Array of results in the same order as `items`.
+ */
+export async function mapWithConcurrency(items, fn, maxConcurrency) {
+    // No limit needed — use plain Promise.all for maximum throughput
+    if (maxConcurrency === undefined || maxConcurrency >= items.length) {
+        return Promise.all(items.map((item, i) => fn(item, i)));
+    }
+    const semaphore = new Semaphore(maxConcurrency);
+    return Promise.all(items.map(async (item, i) => {
+        await semaphore.acquire();
+        try {
+            return await fn(item, i);
+        }
+        finally {
+            semaphore.release();
+        }
+    }));
+}
+//# sourceMappingURL=concurrency.js.map

package/dist/concurrency.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"concurrency.js","sourceRoot":"","sources":["../src/concurrency.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;;;;GAKG;AACH,MAAM,SAAS;IASkB;IAR7B,6CAA6C;IACrC,KAAK,GAAmB,EAAE,CAAC;IACnC,wCAAwC;IAChC,MAAM,GAAG,CAAC,CAAC;IAEnB;;OAEG;IACH,YAA6B,GAAW;QAAX,QAAG,GAAH,GAAG,CAAQ;IAAG,CAAC;IAE5C;;;OAGG;IACH,OAAO;QACH,IAAI,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;YACzB,IAAI,CAAC,MAAM,EAAE,CAAC;YACd,OAAO,OAAO,CAAC,OAAO,EAAE,CAAC;QAC7B,CAAC;QACD,OAAO,IAAI,OAAO,CAAO,OAAO,CAAC,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC;IAClE,CAAC;IAED;;;OAGG;IACH,OAAO;QACH,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC;QAChC,IAAI,IAAI,EAAE,CAAC;YACP,uEAAuE;YACvE,IAAI,EAAE,CAAC;QACX,CAAC;aAAM,CAAC;YACJ,IAAI,CAAC,MAAM,EAAE,CAAC;QAClB,CAAC;IACL,CAAC;CACJ;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CACpC,KAAU,EACV,EAA0C,EAC1C,cAAuB;IAEvB,iEAAiE;IACjE,IAAI,cAAc,KAAK,SAAS,IAAI,cAAc,IAAI,KAAK,CAAC,MAAM,EAAE,CAAC;QACjE,OAAO,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC,EAAE,EAAE,CAAC,EAAE,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;IAC5D,CAAC;IAED,MAAM,SAAS,GAAG,IAAI,SAAS,CAAC,cAAc,CAAC,CAAC;IAChD,OAAO,OAAO,CAAC,GAAG,CACd,KAAK,CAAC,GAAG,CAAC,KAAK,EAAE,IAAI,EAAE,CAAC,EAAE,EAAE;QACxB,MAAM,SAAS,CAAC,OAAO,EAAE,CAAC;QAC1B,IAAI,CAAC;YACD,OAAO,MAAM,EAAE,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC;QAC7B,CAAC;gBAAS,CAAC;YACP,SAAS,CAAC,OAAO,EAAE,CAAC;QACxB,CAAC;IACL,CAAC,CAAC,CACL,CAAC;AACN,CAAC"}

package/dist/errors.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Error classification for deciding whether to retry a failed request.
+ *
+ * Errors are classified as either **terminal** (do not retry — the request
+ * is fundamentally invalid) or **retryable** (transient failure that may
+ * succeed on a subsequent attempt, possibly with a different credential).
+ *
+ * Classification rules:
+ * - Known `SpeechServiceError` codes like `INVALID_INPUT` or `VOICE_NOT_FOUND` → terminal
+ * - HTTP 400, 401, 403, 404, 422 → terminal (bad request or bad credentials)
+ * - HTTP 429, 500, 502, 503, 504 → retryable (rate limit or server error)
+ * - Unknown errors (not a `SpeechServiceError`) → retryable (safer to retry)
+ */
+/**
+ * Classifies an error as `"terminal"` (do not retry) or `"retryable"`.
+ *
+ * Non-`SpeechServiceError` exceptions default to `"retryable"` since they may
+ * be caused by transient issues like network timeouts.
+ *
+ * @param error - The caught error to classify.
+ * @returns `"terminal"` if the error should not be retried, `"retryable"` otherwise.
+ */
+export declare function classifyError(error: unknown): "terminal" | "retryable";
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAkBH;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,UAAU,GAAG,WAAW,CAWtE"}

package/dist/errors.js

@@ -0,0 +1,48 @@
+/**
+ * Error classification for deciding whether to retry a failed request.
+ *
+ * Errors are classified as either **terminal** (do not retry — the request
+ * is fundamentally invalid) or **retryable** (transient failure that may
+ * succeed on a subsequent attempt, possibly with a different credential).
+ *
+ * Classification rules:
+ * - Known `SpeechServiceError` codes like `INVALID_INPUT` or `VOICE_NOT_FOUND` → terminal
+ * - HTTP 400, 401, 403, 404, 422 → terminal (bad request or bad credentials)
+ * - HTTP 429, 500, 502, 503, 504 → retryable (rate limit or server error)
+ * - Unknown errors (not a `SpeechServiceError`) → retryable (safer to retry)
+ */
+import { SpeechServiceError } from "@pico-brief/speech-services";
+/** Error codes that indicate a permanent, non-retryable problem. */
+const TERMINAL_CODES = new Set([
+    "INVALID_INPUT",
+    "UNKNOWN_PROVIDER",
+    "NOT_CONFIGURED",
+    "VOICE_NOT_FOUND",
+]);
+/** HTTP status codes that indicate a permanent client error. */
+const TERMINAL_STATUS_CODES = new Set([400, 401, 403, 404, 422]);
+/** HTTP status codes that indicate a transient server-side problem. */
+const RETRYABLE_STATUS_CODES = new Set([429, 500, 502, 503, 504]);
+/**
+ * Classifies an error as `"terminal"` (do not retry) or `"retryable"`.
+ *
+ * Non-`SpeechServiceError` exceptions default to `"retryable"` since they may
+ * be caused by transient issues like network timeouts.
+ *
+ * @param error - The caught error to classify.
+ * @returns `"terminal"` if the error should not be retried, `"retryable"` otherwise.
+ */
+export function classifyError(error) {
+    if (!(error instanceof SpeechServiceError))
+        return "retryable";
+    if (TERMINAL_CODES.has(error.code))
+        return "terminal";
+    if (error.statusCode !== undefined) {
+        if (TERMINAL_STATUS_CODES.has(error.statusCode))
+            return "terminal";
+        if (RETRYABLE_STATUS_CODES.has(error.statusCode))
+            return "retryable";
+    }
+    return "retryable";
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,kBAAkB,EAAE,MAAM,6BAA6B,CAAC;AAEjE,oEAAoE;AACpE,MAAM,cAAc,GAAG,IAAI,GAAG,CAAC;IAC3B,eAAe;IACf,kBAAkB;IAClB,gBAAgB;IAChB,iBAAiB;CACpB,CAAC,CAAC;AAEH,gEAAgE;AAChE,MAAM,qBAAqB,GAAG,IAAI,GAAG,CAAC,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC,CAAC;AAEjE,uEAAuE;AACvE,MAAM,sBAAsB,GAAG,IAAI,GAAG,CAAC,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC,CAAC;AAElE;;;;;;;;GAQG;AACH,MAAM,UAAU,aAAa,CAAC,KAAc;IACxC,IAAI,CAAC,CAAC,KAAK,YAAY,kBAAkB,CAAC;QAAE,OAAO,WAAW,CAAC;IAE/D,IAAI,cAAc,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC;QAAE,OAAO,UAAU,CAAC;IAEtD,IAAI,KAAK,CAAC,UAAU,KAAK,SAAS,EAAE,CAAC;QACjC,IAAI,qBAAqB,CAAC,GAAG,CAAC,KAAK,CAAC,UAAU,CAAC;YAAE,OAAO,UAAU,CAAC;QACnE,IAAI,sBAAsB,CAAC,GAAG,CAAC,KAAK,CAAC,UAAU,CAAC;YAAE,OAAO,WAAW,CAAC;IACzE,CAAC;IAED,OAAO,WAAW,CAAC;AACvB,CAAC"}

package/dist/helpers.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Small utility functions shared across the library.
+ */
+/**
+ * Returns a promise that resolves after `ms` milliseconds.
+ * Used for backoff delays between retry attempts.
+ *
+ * @param ms - Number of milliseconds to sleep.
+ */
+export declare function sleepAsync(ms: number): Promise<void>;
+/**
+ * Generates a random alphanumeric string, used for creating unique temporary file prefixes.
+ *
+ * @param length - Length of the string to generate. @default 12
+ * @returns A lowercase alphanumeric string of the given length.
+ */
+export declare function generateRandomString(length?: number): string;
+/**
+ * Converts seconds to `HH:MM:SS.mmm` format for ffmpeg `-ss` / `-to` arguments.
+ *
+ * @param seconds - Time value in seconds (can include fractions).
+ * @returns A zero-padded timestamp string like `"01:23:45.678"`.
+ *
+ * @example
+ * ```ts
+ * formatTimestamp(3661.5); // "01:01:01.500"
+ * ```
+ */
+export declare function formatTimestamp(seconds: number): string;
+/**
+ * Normalizes an unknown thrown value to a human-readable string message.
+ *
+ * @param error - The caught value (may be an `Error`, a string, or anything else).
+ * @returns The error's message, the string itself, or `String(error)`.
+ */
+export declare function extractErrorMessage(error: unknown): string;
+/**
+ * Safely extracts an `ArrayBuffer` from a Node.js `Buffer`.
+ *
+ * Node.js `Buffer` objects may share an underlying `ArrayBuffer` (from the
+ * memory pool), so a naive `.buffer` access can return data from other buffers.
+ * This function slices to the exact byte range owned by `buf`.
+ *
+ * @param buf - The Node.js Buffer to convert.
+ * @returns A standalone `ArrayBuffer` containing only `buf`'s data.
+ */
+export declare function bufferToArrayBuffer(buf: Buffer): ArrayBuffer;
+//# sourceMappingURL=helpers.d.ts.map

package/dist/helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"helpers.d.ts","sourceRoot":"","sources":["../src/helpers.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAEpD;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,SAAK,GAAG,MAAM,CAOxD;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAQvD;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAI1D;AAED;;;;;;;;;GASG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,MAAM,GAAG,WAAW,CAE5D"}

package/dist/helpers.js

@@ -0,0 +1,73 @@
+/**
+ * Small utility functions shared across the library.
+ */
+/**
+ * Returns a promise that resolves after `ms` milliseconds.
+ * Used for backoff delays between retry attempts.
+ *
+ * @param ms - Number of milliseconds to sleep.
+ */
+export function sleepAsync(ms) {
+    return new Promise(resolve => setTimeout(resolve, ms));
+}
+/**
+ * Generates a random alphanumeric string, used for creating unique temporary file prefixes.
+ *
+ * @param length - Length of the string to generate. @default 12
+ * @returns A lowercase alphanumeric string of the given length.
+ */
+export function generateRandomString(length = 12) {
+    const chars = "abcdefghijklmnopqrstuvwxyz0123456789";
+    let result = "";
+    for (let i = 0; i < length; i++) {
+        result += chars[Math.floor(Math.random() * chars.length)];
+    }
+    return result;
+}
+/**
+ * Converts seconds to `HH:MM:SS.mmm` format for ffmpeg `-ss` / `-to` arguments.
+ *
+ * @param seconds - Time value in seconds (can include fractions).
+ * @returns A zero-padded timestamp string like `"01:23:45.678"`.
+ *
+ * @example
+ * ```ts
+ * formatTimestamp(3661.5); // "01:01:01.500"
+ * ```
+ */
+export function formatTimestamp(seconds) {
+    const h = Math.floor(seconds / 3600);
+    const m = Math.floor((seconds % 3600) / 60);
+    const s = seconds % 60;
+    const hh = String(h).padStart(2, "0");
+    const mm = String(m).padStart(2, "0");
+    const ss = s.toFixed(3).padStart(6, "0");
+    return `${hh}:${mm}:${ss}`;
+}
+/**
+ * Normalizes an unknown thrown value to a human-readable string message.
+ *
+ * @param error - The caught value (may be an `Error`, a string, or anything else).
+ * @returns The error's message, the string itself, or `String(error)`.
+ */
+export function extractErrorMessage(error) {
+    if (error instanceof Error)
+        return error.message;
+    if (typeof error === "string")
+        return error;
+    return String(error);
+}
+/**
+ * Safely extracts an `ArrayBuffer` from a Node.js `Buffer`.
+ *
+ * Node.js `Buffer` objects may share an underlying `ArrayBuffer` (from the
+ * memory pool), so a naive `.buffer` access can return data from other buffers.
+ * This function slices to the exact byte range owned by `buf`.
+ *
+ * @param buf - The Node.js Buffer to convert.
+ * @returns A standalone `ArrayBuffer` containing only `buf`'s data.
+ */
+export function bufferToArrayBuffer(buf) {
+    return buf.buffer.slice(buf.byteOffset, buf.byteOffset + buf.byteLength);
+}
+//# sourceMappingURL=helpers.js.map

package/dist/helpers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"helpers.js","sourceRoot":"","sources":["../src/helpers.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;;;;GAKG;AACH,MAAM,UAAU,UAAU,CAAC,EAAU;IACjC,OAAO,IAAI,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,CAAC;AAC3D,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,oBAAoB,CAAC,MAAM,GAAG,EAAE;IAC5C,MAAM,KAAK,GAAG,sCAAsC,CAAC;IACrD,IAAI,MAAM,GAAG,EAAE,CAAC;IAChB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QAC9B,MAAM,IAAI,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,EAAE,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC;IAC9D,CAAC;IACD,OAAO,MAAM,CAAC;AAClB,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,eAAe,CAAC,OAAe;IAC3C,MAAM,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,GAAG,IAAI,CAAC,CAAC;IACrC,MAAM,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,OAAO,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC;IAC5C,MAAM,CAAC,GAAG,OAAO,GAAG,EAAE,CAAC;IACvB,MAAM,EAAE,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;IACtC,MAAM,EAAE,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;IACtC,MAAM,EAAE,GAAG,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;IACzC,OAAO,GAAG,EAAE,IAAI,EAAE,IAAI,EAAE,EAAE,CAAC;AAC/B,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,mBAAmB,CAAC,KAAc;IAC9C,IAAI,KAAK,YAAY,KAAK;QAAE,OAAO,KAAK,CAAC,OAAO,CAAC;IACjD,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IAC5C,OAAO,MAAM,CAAC,KAAK,CAAC,CAAC;AACzB,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,mBAAmB,CAAC,GAAW;IAC3C,OAAO,GAAG,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,UAAU,EAAE,GAAG,CAAC,UAAU,GAAG,GAAG,CAAC,UAAU,CAAgB,CAAC;AAC5F,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * @module @pico-brief/speech-services-parallel
+ *
+ * Parallel orchestration for Speech-to-Text and Text-to-Speech operations.
+ *
+ * This module re-exports the two main entry points — {@link transcribeParallel}
+ * and {@link synthesizeParallel} — along with the {@link KeyManager} class for
+ * standalone credential rotation, and every public type used by the API.
+ */
+export { transcribeParallel } from "./transcribeParallel.js";
+export { synthesizeParallel } from "./synthesizeParallel.js";
+export { KeyManager } from "./KeyManager.js";
+export type { TranscribeParallelParams, SynthesizeParallelParams, SynthesizeParallelResult, SynthesizeChunkInput, SynthesizeChunkResult, } from "./types.js";
+export type { ChunkBoundary } from "./merge.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;;;;;;;;GAQG;AAEH,OAAO,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAC7D,OAAO,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAC7D,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAE7C,YAAY,EACR,wBAAwB,EACxB,wBAAwB,EACxB,wBAAwB,EACxB,oBAAoB,EACpB,qBAAqB,GACxB,MAAM,YAAY,CAAC;AAEpB,YAAY,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,13 @@
+/**
+ * @module @pico-brief/speech-services-parallel
+ *
+ * Parallel orchestration for Speech-to-Text and Text-to-Speech operations.
+ *
+ * This module re-exports the two main entry points — {@link transcribeParallel}
+ * and {@link synthesizeParallel} — along with the {@link KeyManager} class for
+ * standalone credential rotation, and every public type used by the API.
+ */
+export { transcribeParallel } from "./transcribeParallel.js";
+export { synthesizeParallel } from "./synthesizeParallel.js";
+export { KeyManager } from "./KeyManager.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;;;;;;;;GAQG;AAEH,OAAO,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAC7D,OAAO,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAC7D,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC"}

package/dist/merge.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Merging logic for transcription results from overlapping audio chunks.
+ *
+ * When audio is split into overlapping chunks, each chunk may transcribe words
+ * that fall in the overlap region. This module filters words by ownership
+ * boundaries so that each word appears exactly once in the merged output.
+ */
+import type { TranscribeResult } from "@pico-brief/speech-services";
+/**
+ * Defines the ownership range for a single chunk's transcription result.
+ *
+ * Words whose `startTime` falls within `[ownedStart, ownedEnd)` are kept;
+ * words outside that range (i.e. in the overlap zone) are discarded to
+ * prevent duplicates.
+ */
+export interface ChunkBoundary {
+    /** The transcription result for this chunk. */
+    result: TranscribeResult;
+    /** Inclusive lower bound of the time range this chunk "owns" (seconds). */
+    ownedStart: number;
+    /** Exclusive upper bound; set to `Infinity` for the last chunk. */
+    ownedEnd: number;
+}
+/**
+ * Merges multiple chunk transcription results into a single unified result.
+ *
+ * For each chunk, only words whose `startTime` falls within the chunk's owned
+ * range are included. The combined words are sorted by timestamp, and the
+ * full text is reconstructed by joining word texts with spaces.
+ *
+ * @param chunks - Array of chunk results with their ownership boundaries.
+ * @returns A single merged {@link TranscribeResult} with deduplicated, sorted words.
+ */
+export declare function mergeTranscribeResults(chunks: ChunkBoundary[]): TranscribeResult;
+//# sourceMappingURL=merge.d.ts.map

package/dist/merge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"merge.d.ts","sourceRoot":"","sources":["../src/merge.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAmB,MAAM,6BAA6B,CAAC;AAErF;;;;;;GAMG;AACH,MAAM,WAAW,aAAa;IAC1B,+CAA+C;IAC/C,MAAM,EAAE,gBAAgB,CAAC;IACzB,2EAA2E;IAC3E,UAAU,EAAE,MAAM,CAAC;IACnB,mEAAmE;IACnE,QAAQ,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;;;GASG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,aAAa,EAAE,GAAG,gBAAgB,CAsBhF"}

package/dist/merge.js

@@ -0,0 +1,37 @@
+/**
+ * Merging logic for transcription results from overlapping audio chunks.
+ *
+ * When audio is split into overlapping chunks, each chunk may transcribe words
+ * that fall in the overlap region. This module filters words by ownership
+ * boundaries so that each word appears exactly once in the merged output.
+ */
+/**
+ * Merges multiple chunk transcription results into a single unified result.
+ *
+ * For each chunk, only words whose `startTime` falls within the chunk's owned
+ * range are included. The combined words are sorted by timestamp, and the
+ * full text is reconstructed by joining word texts with spaces.
+ *
+ * @param chunks - Array of chunk results with their ownership boundaries.
+ * @returns A single merged {@link TranscribeResult} with deduplicated, sorted words.
+ */
+export function mergeTranscribeResults(chunks) {
+    const allWords = [];
+    for (const { result, ownedStart, ownedEnd } of chunks) {
+        for (const word of result.words) {
+            // Only keep words that fall within this chunk's owned time range
+            if (word.startTime >= ownedStart && word.startTime < ownedEnd) {
+                allWords.push(word);
+            }
+        }
+    }
+    // Sort all words by their start time for correct ordering
+    allWords.sort((a, b) => a.startTime - b.startTime);
+    const text = allWords.map(w => w.text).join(" ");
+    // Duration is the end time of the last word (safe against Infinity from ownedEnd)
+    const duration = allWords.length > 0 ? allWords[allWords.length - 1].endTime : 0;
+    // Use the language detected by the first chunk
+    const language = chunks.length > 0 ? chunks[0].result.language : "";
+    return { text, words: allWords, language, duration };
+}
+//# sourceMappingURL=merge.js.map

package/dist/merge.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"merge.js","sourceRoot":"","sources":["../src/merge.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAoBH;;;;;;;;;GASG;AACH,MAAM,UAAU,sBAAsB,CAAC,MAAuB;IAC1D,MAAM,QAAQ,GAAsB,EAAE,CAAC;IAEvC,KAAK,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,QAAQ,EAAE,IAAI,MAAM,EAAE,CAAC;QACpD,KAAK,MAAM,IAAI,IAAI,MAAM,CAAC,KAAK,EAAE,CAAC;YAC9B,iEAAiE;YACjE,IAAI,IAAI,CAAC,SAAS,IAAI,UAAU,IAAI,IAAI,CAAC,SAAS,GAAG,QAAQ,EAAE,CAAC;gBAC5D,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YACxB,CAAC;QACL,CAAC;IACL,CAAC;IAED,0DAA0D;IAC1D,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,SAAS,GAAG,CAAC,CAAC,SAAS,CAAC,CAAC;IAEnD,MAAM,IAAI,GAAG,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACjD,kFAAkF;IAClF,MAAM,QAAQ,GAAG,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC;IACjF,+CAA+C;IAC/C,MAAM,QAAQ,GAAG,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC;IAEpE,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,QAAQ,EAAE,CAAC;AACzD,CAAC"}

package/dist/retry.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Retry loop with exponential backoff, credential rotation, and error classification.
+ *
+ * On each transient failure the current credential is placed on cool-down
+ * (via {@link KeyManager.reportError}) and a fresh credential is selected for
+ * the next attempt. Terminal errors (bad input, invalid keys) are thrown
+ * immediately without retry.
+ */
+import type { KeyManager } from "./KeyManager.js";
+/** Options that control retry behavior. */
+export interface WithRetryOptions<TCredential> {
+    /** The key manager used for credential rotation between attempts. */
+    keyManager: KeyManager<TCredential>;
+    /** Maximum wall-clock time (ms) to keep retrying before giving up. */
+    retryTimeoutMs: number;
+    /** Optional abort signal — checked before each attempt and after each sleep. */
+    signal?: AbortSignal;
+    /** Human-readable label for error messages (e.g. `"Transcription"`). */
+    operationName: string;
+}
+/**
+ * Executes `fn` with automatic retry on transient errors.
+ *
+ * - **Credential rotation**: a fresh credential is obtained from the key manager on every attempt.
+ * - **Exponential backoff**: delay doubles each attempt (1 s → 2 s → 4 s → …) capped at 60 s, plus 30 % jitter.
+ * - **Deadline enforcement**: retries stop once `retryTimeoutMs` has elapsed.
+ * - **Abort support**: the loop checks `signal.aborted` before each attempt and after each sleep.
+ * - **Terminal errors**: errors classified as terminal (e.g. 401, 403) are thrown immediately.
+ *
+ * @typeParam TCredential - Credential type managed by the key manager.
+ * @typeParam TResult - Return type of the wrapped function.
+ * @param options - Retry configuration (key manager, timeout, signal, operation name).
+ * @param fn - The async function to execute. Receives a credential and should return a result.
+ * @returns The result of `fn` on the first successful attempt.
+ * @throws On terminal error, timeout, or abort.
+ */
+export declare function withRetry<TCredential, TResult>(options: WithRetryOptions<TCredential>, fn: (credential: TCredential) => Promise<TResult>): Promise<TResult>;
+//# sourceMappingURL=retry.d.ts.map

package/dist/retry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"retry.d.ts","sourceRoot":"","sources":["../src/retry.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAElD,2CAA2C;AAC3C,MAAM,WAAW,gBAAgB,CAAC,WAAW;IACzC,qEAAqE;IACrE,UAAU,EAAE,UAAU,CAAC,WAAW,CAAC,CAAC;IACpC,sEAAsE;IACtE,cAAc,EAAE,MAAM,CAAC;IACvB,gFAAgF;IAChF,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,wEAAwE;IACxE,aAAa,EAAE,MAAM,CAAC;CACzB;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,SAAS,CAAC,WAAW,EAAE,OAAO,EAChD,OAAO,EAAE,gBAAgB,CAAC,WAAW,CAAC,EACtC,EAAE,EAAE,CAAC,UAAU,EAAE,WAAW,KAAK,OAAO,CAAC,OAAO,CAAC,GAClD,OAAO,CAAC,OAAO,CAAC,CA+ClB"}

package/dist/retry.js

@@ -0,0 +1,68 @@
+/**
+ * Retry loop with exponential backoff, credential rotation, and error classification.
+ *
+ * On each transient failure the current credential is placed on cool-down
+ * (via {@link KeyManager.reportError}) and a fresh credential is selected for
+ * the next attempt. Terminal errors (bad input, invalid keys) are thrown
+ * immediately without retry.
+ */
+import { classifyError } from "./errors.js";
+import { sleepAsync, extractErrorMessage } from "./helpers.js";
+/**
+ * Executes `fn` with automatic retry on transient errors.
+ *
+ * - **Credential rotation**: a fresh credential is obtained from the key manager on every attempt.
+ * - **Exponential backoff**: delay doubles each attempt (1 s → 2 s → 4 s → …) capped at 60 s, plus 30 % jitter.
+ * - **Deadline enforcement**: retries stop once `retryTimeoutMs` has elapsed.
+ * - **Abort support**: the loop checks `signal.aborted` before each attempt and after each sleep.
+ * - **Terminal errors**: errors classified as terminal (e.g. 401, 403) are thrown immediately.
+ *
+ * @typeParam TCredential - Credential type managed by the key manager.
+ * @typeParam TResult - Return type of the wrapped function.
+ * @param options - Retry configuration (key manager, timeout, signal, operation name).
+ * @param fn - The async function to execute. Receives a credential and should return a result.
+ * @returns The result of `fn` on the first successful attempt.
+ * @throws On terminal error, timeout, or abort.
+ */
+export async function withRetry(options, fn) {
+    const { keyManager, retryTimeoutMs, signal, operationName } = options;
+    const deadline = Date.now() + retryTimeoutMs;
+    let attempt = 0;
+    while (true) {
+        // Check for cancellation before each attempt
+        if (signal?.aborted) {
+            throw new Error(`${operationName} aborted`);
+        }
+        const credential = keyManager.getKey();
+        try {
+            return await fn(credential);
+        }
+        catch (e) {
+            // Terminal errors (bad input, invalid key, etc.) are not retryable
+            if (classifyError(e) === "terminal")
+                throw e;
+            // Mark the credential as failed so the key manager avoids it temporarily
+            keyManager.reportError(credential);
+            // Check if we've exceeded the retry deadline
+            if (Date.now() >= deadline) {
+                throw new Error(`${operationName} timed out after ${retryTimeoutMs}ms: ${extractErrorMessage(e)}`);
+            }
+            // Exponential backoff: min(1000 * 2^attempt, 60000) + 30% jitter
+            const base = Math.min(1000 * Math.pow(2, attempt), 60000);
+            const jitter = base * 0.3 * Math.random();
+            const delay = base + jitter;
+            // Don't sleep past the deadline
+            const remaining = deadline - Date.now();
+            if (remaining <= 0) {
+                throw new Error(`${operationName} timed out after ${retryTimeoutMs}ms: ${extractErrorMessage(e)}`);
+            }
+            await sleepAsync(Math.min(delay, remaining));
+            // Check for cancellation after sleeping
+            if (signal?.aborted) {
+                throw new Error(`${operationName} aborted`);
+            }
+            attempt++;
+        }
+    }
+}
+//# sourceMappingURL=retry.js.map

package/dist/retry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"retry.js","sourceRoot":"","sources":["../src/retry.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,UAAU,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AAe/D;;;;;;;;;;;;;;;GAeG;AACH,MAAM,CAAC,KAAK,UAAU,SAAS,CAC3B,OAAsC,EACtC,EAAiD;IAEjD,MAAM,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,EAAE,aAAa,EAAE,GAAG,OAAO,CAAC;IACtE,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,cAAc,CAAC;IAC7C,IAAI,OAAO,GAAG,CAAC,CAAC;IAEhB,OAAO,IAAI,EAAE,CAAC;QACV,6CAA6C;QAC7C,IAAI,MAAM,EAAE,OAAO,EAAE,CAAC;YAClB,MAAM,IAAI,KAAK,CAAC,GAAG,aAAa,UAAU,CAAC,CAAC;QAChD,CAAC;QAED,MAAM,UAAU,GAAG,UAAU,CAAC,MAAM,EAAE,CAAC;QACvC,IAAI,CAAC;YACD,OAAO,MAAM,EAAE,CAAC,UAAU,CAAC,CAAC;QAChC,CAAC;QAAC,OAAO,CAAC,EAAE,CAAC;YACT,mEAAmE;YACnE,IAAI,aAAa,CAAC,CAAC,CAAC,KAAK,UAAU;gBAAE,MAAM,CAAC,CAAC;YAE7C,yEAAyE;YACzE,UAAU,CAAC,WAAW,CAAC,UAAU,CAAC,CAAC;YAEnC,6CAA6C;YAC7C,IAAI,IAAI,CAAC,GAAG,EAAE,IAAI,QAAQ,EAAE,CAAC;gBACzB,MAAM,IAAI,KAAK,CAAC,GAAG,aAAa,oBAAoB,cAAc,OAAO,mBAAmB,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;YACvG,CAAC;YAED,iEAAiE;YACjE,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,OAAO,CAAC,EAAE,KAAK,CAAC,CAAC;YAC1D,MAAM,MAAM,GAAG,IAAI,GAAG,GAAG,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC;YAC1C,MAAM,KAAK,GAAG,IAAI,GAAG,MAAM,CAAC;YAE5B,gCAAgC;YAChC,MAAM,SAAS,GAAG,QAAQ,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;YACxC,IAAI,SAAS,IAAI,CAAC,EAAE,CAAC;gBACjB,MAAM,IAAI,KAAK,CAAC,GAAG,aAAa,oBAAoB,cAAc,OAAO,mBAAmB,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;YACvG,CAAC;YAED,MAAM,UAAU,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,EAAE,SAAS,CAAC,CAAC,CAAC;YAE7C,wCAAwC;YACxC,IAAI,MAAM,EAAE,OAAO,EAAE,CAAC;gBAClB,MAAM,IAAI,KAAK,CAAC,GAAG,aAAa,UAAU,CAAC,CAAC;YAChD,CAAC;YAED,OAAO,EAAE,CAAC;QACd,CAAC;IACL,CAAC;AACL,CAAC"}

package/dist/synthesizeParallel.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Parallel text-to-speech synthesis with audio concatenation.
+ *
+ * Each text chunk is synthesized independently (with retry and credential
+ * rotation), written to a temporary file to keep memory usage low, and then
+ * concatenated into a single audio buffer via ffmpeg (or `Buffer.concat` as
+ * a fallback). The result includes per-chunk metadata with timing offsets.
+ */
+import type { SynthesizeParallelParams, SynthesizeParallelResult } from "./types.js";
+/**
+ * Synthesizes multiple text chunks into a single audio buffer in parallel.
+ *
+ * Chunks are processed concurrently (optionally limited by `maxConcurrency`),
+ * each with automatic retry and credential rotation. The resulting audio
+ * segments are concatenated via ffmpeg into one continuous file.
+ *
+ * @param params - Configuration including provider, credentials, text chunks, and options.
+ * @returns Combined audio buffer, format string, and per-chunk metadata with timing offsets.
+ *
+ * @example
+ * ```ts
+ * const result = await synthesizeParallel({
+ *   provider: "openai",
+ *   credentials: [{ apiKey: "sk-..." }],
+ *   chunks: [{ text: "Hello" }, { text: "World" }],
+ *   ffmpegPath: "ffmpeg",
+ * });
+ * fs.writeFileSync("output.mp3", result.audio);
+ * ```
+ */
+export declare function synthesizeParallel(params: SynthesizeParallelParams): Promise<SynthesizeParallelResult>;
+//# sourceMappingURL=synthesizeParallel.d.ts.map

package/dist/synthesizeParallel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"synthesizeParallel.d.ts","sourceRoot":"","sources":["../src/synthesizeParallel.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAeH,OAAO,KAAK,EACR,wBAAwB,EACxB,wBAAwB,EAI3B,MAAM,YAAY,CAAC;AAOpB;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAsB,kBAAkB,CAAC,MAAM,EAAE,wBAAwB,GAAG,OAAO,CAAC,wBAAwB,CAAC,CAwH5G"}