@pico-brief/speech-services-parallel 1.0.0

package/README.md

@@ -0,0 +1,372 @@
+# @pico-brief/speech-services-parallel
+
+Transcribe audio to text and generate speech from text — fast — by running multiple requests at the same time.
+
+This library takes long audio files, splits them into smaller pieces, and transcribes every piece in parallel. It does the same thing in reverse for text-to-speech: you give it chunks of text, it turns them all into audio at once, and stitches the results together into a single file. Under the hood it handles retries, rotates through your API keys so you don't hit rate limits, and lets you control how many requests run at once.
+
+Built on top of [`@pico-brief/speech-services`](https://github.com/PicoBrief/speech-services).
+
+## Supported Providers
+
+| Provider | Speech-to-Text | Text-to-Speech |
+|---|:---:|:---:|
+| Azure | ✅ | ✅ |
+| AssemblyAI | ✅ | |
+| Cartesia | | ✅ |
+| Deepgram | ✅ | ✅ |
+| ElevenLabs | ✅ | ✅ |
+| Google | ✅ | ✅ |
+| OpenAI | ✅ | ✅ |
+| PlayHT | | ✅ |
+| Rev AI | ✅ | |
+| Speechmatics | ✅ | |
+
+## Install
+
+```bash
+npm install @pico-brief/speech-services-parallel
+```
+
+You also need [ffmpeg](https://ffmpeg.org/) installed on your system. It's used to split and join audio files.
+
+## Requirements
+
+- Node.js >= 18
+- ffmpeg binary available on your system
+
+## Quick Start
+
+### Transcribe audio to text
+
+```ts
+import { transcribeParallel } from "@pico-brief/speech-services-parallel";
+import { readFileSync } from "fs";
+
+const audio = readFileSync("interview.mp3");
+
+const result = await transcribeParallel({
+  provider: "openai",
+  credentials: [{ apiKey: "sk-..." }],
+  targetChunkDuration: 300, // 5-minute chunks
+  chunkOverlap: 30,         // 30 seconds of overlap
+  audio,
+  ffmpegPath: "ffmpeg",
+});
+
+console.log(result.text);
+// "Hello and welcome to the show..."
+
+console.log(result.duration);
+// 1823.5 (seconds)
+
+console.log(result.words);
+// [{ word: "Hello", start: 0.0, end: 0.42 }, { word: "and", start: 0.42, end: 0.58 }, ...]
+```
+
+If the audio is longer than 5 minutes, it is automatically split into chunks and each chunk is transcribed in parallel. The results are merged back together with word-level timestamps.
+
+### Generate speech from text
+
+```ts
+import { synthesizeParallel } from "@pico-brief/speech-services-parallel";
+import { writeFileSync } from "fs";
+
+const result = await synthesizeParallel({
+  provider: "openai",
+  credentials: [{ apiKey: "sk-..." }],
+  chunks: [
+    { text: "Chapter one. It was a dark and stormy night." },
+    { text: "Chapter two. The sun rose over the hills." },
+  ],
+  ffmpegPath: "ffmpeg",
+});
+
+writeFileSync("audiobook.mp3", result.audio);
+
+console.log(result.format);
+// "mp3"
+
+console.log(result.chunks);
+// [{ chunkIndex: 0, startTime: 0, duration: 3.2, voice: "alloy", ... }, ...]
+```
+
+Each chunk of text is synthesized in parallel and the audio is concatenated into a single file.
+
+## Basic Usage
+
+### Picking a provider
+
+Every call requires a `provider` name and a `credentials` array. The shape of each credential depends on the provider:
+
+```ts
+// OpenAI / Deepgram / ElevenLabs / Google / AssemblyAI / Rev AI / Cartesia
+{ apiKey: "..." }
+
+// Azure
+{ subscriptionKey: "...", region: "eastus" }
+
+// PlayHT
+{ apiKey: "...", userId: "..." }
+
+// Speechmatics
+{ apiKey: "...", region: "eu" }  // region is optional
+```
+
+### Specifying a language
+
+Pass a `languages` array to help the provider pick the right model or voice:
+
+```ts
+const result = await transcribeParallel({
+  provider: "deepgram",
+  credentials: [{ apiKey: "..." }],
+  audio,
+  ffmpegPath: "ffmpeg",
+  languages: ["en"],
+});
+```
+
+### Choosing a voice
+
+For text-to-speech, set a default voice for all chunks, or override it per chunk:
+
+```ts
+const result = await synthesizeParallel({
+  provider: "elevenlabs",
+  credentials: [{ apiKey: "..." }],
+  voice: "rachel",
+  chunks: [
+    { text: "Narrated by Rachel." },
+    { text: "Except this part.", voice: "bella" }, // override for this chunk
+    { text: "Back to Rachel." },
+  ],
+  ffmpegPath: "ffmpeg",
+});
+```
+
+## Advanced Usage
+
+### Credential rotation
+
+If you have multiple API keys, pass them all in the `credentials` array. The library picks the least-recently-used key for each request and automatically rotates to another key when one hits a rate limit or fails:
+
+```ts
+const result = await transcribeParallel({
+  provider: "openai",
+  credentials: [
+    { apiKey: "sk-key-1" },
+    { apiKey: "sk-key-2" },
+    { apiKey: "sk-key-3" },
+  ],
+  audio,
+  ffmpegPath: "ffmpeg",
+});
+```
+
+When a key fails, it goes into a cool-down period so it isn't immediately retried.
+
+### Limiting concurrency
+
+By default, all chunks are processed at the same time. If you want to limit how many run in parallel (for example, to stay under a provider's rate limit), use `maxConcurrency`:
+
+```ts
+const result = await synthesizeParallel({
+  provider: "elevenlabs",
+  credentials: [{ apiKey: "..." }],
+  chunks: fiftyChunks,
+  maxConcurrency: 5, // only 5 requests at a time
+  ffmpegPath: "ffmpeg",
+});
+```
+
+### Tracking progress
+
+Pass an `onProgress` callback to get notified as chunks complete:
+
+```ts
+const result = await transcribeParallel({
+  provider: "deepgram",
+  credentials: [{ apiKey: "..." }],
+  audio: longAudio,
+  ffmpegPath: "ffmpeg",
+  onProgress: (completed, total) => {
+    console.log(`${completed}/${total} chunks done`);
+  },
+});
+```
+
+### Controlling chunk size
+
+For transcription, the library splits audio into 5-minute chunks by default with a 15-second overlap between chunks (so words at the boundary aren't lost). You can change both values:
+
+```ts
+const result = await transcribeParallel({
+  provider: "assemblyai",
+  credentials: [{ apiKey: "..." }],
+  audio,
+  ffmpegPath: "ffmpeg",
+  targetChunkDuration: 120, // 2-minute chunks
+  chunkOverlap: 30,         // 30 seconds of overlap
+});
+```
+
+### Retry timeout
+
+Failed requests are retried automatically with exponential backoff. The default deadline is 5 minutes. You can change it:
+
+```ts
+const result = await synthesizeParallel({
+  provider: "azure",
+  credentials: [
+    { subscriptionKey: "key-1", region: "eastus" },
+    { subscriptionKey: "key-2", region: "westus" },
+  ],
+  chunks: textChunks,
+  retryTimeoutMs: 10 * 60 * 1000, // 10 minutes
+  ffmpegPath: "ffmpeg",
+});
+```
+
+Errors like invalid API keys (401, 403) or bad input (400, 422) are **not** retried — only transient errors (429, 500, 502, 503, 504) are.
+
+### Cancellation
+
+Pass an `AbortSignal` to cancel an in-progress operation:
+
+```ts
+const controller = new AbortController();
+
+const promise = transcribeParallel({
+  provider: "google",
+  credentials: [{ apiKey: "..." }],
+  audio,
+  ffmpegPath: "ffmpeg",
+  signal: controller.signal,
+});
+
+// Cancel after 30 seconds
+setTimeout(() => controller.abort(), 30_000);
+```
+
+### Provider-specific options
+
+Each provider supports extra options through `providerOptions`. These are passed directly to the underlying provider client:
+
+```ts
+const result = await synthesizeParallel({
+  provider: "openai",
+  credentials: [{ apiKey: "..." }],
+  chunks: [
+    { text: "High quality audio.", providerOptions: { model: "tts-1-hd" } },
+    { text: "Standard quality.", providerOptions: { model: "tts-1" } },
+  ],
+  ffmpegPath: "ffmpeg",
+});
+```
+
+You can also set default `providerOptions` at the top level, and override them per chunk.
+
+### Using KeyManager directly
+
+If you need credential rotation for your own code, you can use the `KeyManager` class on its own:
+
+```ts
+import { KeyManager } from "@pico-brief/speech-services-parallel";
+
+const manager = new KeyManager(["key-1", "key-2", "key-3"]);
+
+// Get the least-recently-used key
+const key = manager.getKey();
+
+try {
+  await callSomeApi(key);
+} catch (error) {
+  // Put this key on cool-down so it isn't picked again right away
+  manager.reportError(key);
+
+  // Or set a custom cool-down (in milliseconds)
+  manager.reportError(key, 60_000); // 1 minute
+}
+```
+
+## API Reference
+
+### `transcribeParallel(params)`
+
+Transcribes audio with automatic chunking and parallel processing.
+
+**Parameters:**
+
+| Name | Type | Required | Default | Description |
+|---|---|---|---|---|
+| `provider` | `string` | Yes | — | Provider name (see supported providers above) |
+| `credentials` | `ProviderConfig[]` | Yes | — | One or more credential objects for the provider |
+| `audio` | `Buffer` | Yes | — | The audio data to transcribe |
+| `ffmpegPath` | `string` | Yes | — | Path to the ffmpeg binary |
+| `languages` | `string[]` | No | — | Language hints for the provider |
+| `targetChunkDuration` | `number` | No | `300` | Target chunk length in seconds |
+| `chunkOverlap` | `number` | No | `15` | Overlap between chunks in seconds |
+| `retryTimeoutMs` | `number` | No | `300000` | Max time to keep retrying (ms) |
+| `maxConcurrency` | `number` | No | — | Max parallel requests |
+| `signal` | `AbortSignal` | No | — | Signal to cancel the operation |
+| `onProgress` | `(completed, total) => void` | No | — | Progress callback |
+| `providerOptions` | `object` | No | — | Provider-specific options |
+
+**Returns:** `Promise<TranscribeResult>` with `text`, `words`, `language`, and `duration`.
+
+---
+
+### `synthesizeParallel(params)`
+
+Synthesizes multiple text chunks into audio in parallel.
+
+**Parameters:**
+
+| Name | Type | Required | Default | Description |
+|---|---|---|---|---|
+| `provider` | `string` | Yes | — | Provider name (see supported providers above) |
+| `credentials` | `ProviderConfig[]` | Yes | — | One or more credential objects for the provider |
+| `chunks` | `SynthesizeChunkInput[]` | Yes | — | Text chunks to synthesize |
+| `ffmpegPath` | `string` | No | — | Path to ffmpeg (for concatenation) |
+| `gender` | `"male" \| "female"` | No | — | Default voice gender |
+| `voice` | `string` | No | — | Default voice ID or name |
+| `languages` | `string[]` | No | — | Default language hints |
+| `retryTimeoutMs` | `number` | No | `300000` | Max time to keep retrying (ms) |
+| `maxConcurrency` | `number` | No | — | Max parallel requests |
+| `signal` | `AbortSignal` | No | — | Signal to cancel the operation |
+| `onProgress` | `(completed, total) => void` | No | — | Progress callback |
+| `providerOptions` | `object` | No | — | Default provider-specific options |
+
+**Returns:** `Promise<SynthesizeParallelResult>`
+
+```ts
+{
+  audio: Buffer;       // The combined audio data
+  format: string;      // Audio format (e.g. "mp3")
+  chunks: [{
+    chunkIndex: number;
+    startTime: number; // Offset in combined audio (seconds)
+    duration: number;  // Duration of this chunk (seconds)
+    voice: string;     // Voice that was used
+    language?: string;
+    format: string;
+    provider: string;
+  }];
+}
+```
+
+---
+
+### `KeyManager<T>`
+
+Generic credential rotation manager using a least-recently-used strategy.
+
+```ts
+new KeyManager(credentials: T[])  // requires at least one credential
+manager.getKey(): T                // returns the least-recently-used credential
+manager.reportError(key: T, coolDownMs?: number): void  // puts a key on cool-down
+```
+
+## License
+
+MIT

package/dist/KeyManager.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Generic credential rotation manager using a Least-Recently-Used (LRU) strategy.
+ *
+ * Credentials that fail are placed on a cool-down so they are temporarily skipped.
+ * If every credential is cooling down, the cool-down is ignored and the LRU
+ * credential is returned anyway (better to retry than to block forever).
+ *
+ * @typeParam TCredential - The shape of a single credential (e.g. `{ apiKey: string }`).
+ *
+ * @example
+ * ```ts
+ * const km = new KeyManager([{ apiKey: "a" }, { apiKey: "b" }]);
+ * const key = km.getKey();        // returns least-recently-used key
+ * km.reportError(key);            // puts it on 3-minute cool-down
+ * const next = km.getKey();       // returns the other key
+ * ```
+ */
+export declare class KeyManager<TCredential> {
+    /** Internal bookkeeping: tracks usage time and cool-down expiry for each credential. */
+    private entries;
+    /**
+     * Create a new KeyManager.
+     * @param credentials - Array of credentials to rotate through. Must contain at least one.
+     * @throws {Error} If the credentials array is empty.
+     */
+    constructor(credentials: TCredential[]);
+    /**
+     * Returns the credential with the oldest last-use time, skipping credentials in cool-down.
+     * Falls back to all credentials if every one is cooling down.
+     * The returned credential's `lastUsedAt` is updated to `Date.now()`.
+     */
+    getKey(): TCredential;
+    /**
+     * Marks a credential as failed so it is temporarily excluded from selection.
+     *
+     * @param credential - The exact credential reference returned by {@link getKey}.
+     * @param coolDownMs - How long to exclude this credential, in milliseconds. @default 180000 (3 minutes)
+     */
+    reportError(credential: TCredential, coolDownMs?: number): void;
+}
+//# sourceMappingURL=KeyManager.d.ts.map

package/dist/KeyManager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"KeyManager.d.ts","sourceRoot":"","sources":["../src/KeyManager.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,UAAU,CAAC,WAAW;IAC/B,wFAAwF;IACxF,OAAO,CAAC,OAAO,CAA2E;IAE1F;;;;OAIG;gBACS,WAAW,EAAE,WAAW,EAAE;IAKtC;;;;OAIG;IACH,MAAM,IAAI,WAAW;IAiBrB;;;;;OAKG;IACH,WAAW,CAAC,UAAU,EAAE,WAAW,EAAE,UAAU,GAAE,MAAsB,GAAG,IAAI;CAIjF"}

package/dist/KeyManager.js

@@ -0,0 +1,61 @@
+/**
+ * Generic credential rotation manager using a Least-Recently-Used (LRU) strategy.
+ *
+ * Credentials that fail are placed on a cool-down so they are temporarily skipped.
+ * If every credential is cooling down, the cool-down is ignored and the LRU
+ * credential is returned anyway (better to retry than to block forever).
+ *
+ * @typeParam TCredential - The shape of a single credential (e.g. `{ apiKey: string }`).
+ *
+ * @example
+ * ```ts
+ * const km = new KeyManager([{ apiKey: "a" }, { apiKey: "b" }]);
+ * const key = km.getKey();        // returns least-recently-used key
+ * km.reportError(key);            // puts it on 3-minute cool-down
+ * const next = km.getKey();       // returns the other key
+ * ```
+ */
+export class KeyManager {
+    /** Internal bookkeeping: tracks usage time and cool-down expiry for each credential. */
+    entries;
+    /**
+     * Create a new KeyManager.
+     * @param credentials - Array of credentials to rotate through. Must contain at least one.
+     * @throws {Error} If the credentials array is empty.
+     */
+    constructor(credentials) {
+        if (credentials.length === 0)
+            throw new Error("KeyManager requires at least one credential");
+        this.entries = credentials.map(credential => ({ credential, lastUsedAt: 0, coolDownUntil: 0 }));
+    }
+    /**
+     * Returns the credential with the oldest last-use time, skipping credentials in cool-down.
+     * Falls back to all credentials if every one is cooling down.
+     * The returned credential's `lastUsedAt` is updated to `Date.now()`.
+     */
+    getKey() {
+        const now = Date.now();
+        // Filter to credentials whose cool-down has expired
+        let available = this.entries.filter(e => e.coolDownUntil <= now);
+        // If all credentials are on cool-down, use them all anyway
+        if (available.length === 0)
+            available = [...this.entries];
+        // Sort by oldest usage first (LRU)
+        available.sort((a, b) => a.lastUsedAt - b.lastUsedAt);
+        const entry = available[0];
+        entry.lastUsedAt = now;
+        return entry.credential;
+    }
+    /**
+     * Marks a credential as failed so it is temporarily excluded from selection.
+     *
+     * @param credential - The exact credential reference returned by {@link getKey}.
+     * @param coolDownMs - How long to exclude this credential, in milliseconds. @default 180000 (3 minutes)
+     */
+    reportError(credential, coolDownMs = 3 * 60 * 1000) {
+        const entry = this.entries.find(e => e.credential === credential);
+        if (entry)
+            entry.coolDownUntil = Date.now() + coolDownMs;
+    }
+}
+//# sourceMappingURL=KeyManager.js.map

package/dist/KeyManager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"KeyManager.js","sourceRoot":"","sources":["../src/KeyManager.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,OAAO,UAAU;IACnB,wFAAwF;IAChF,OAAO,CAA2E;IAE1F;;;;OAIG;IACH,YAAY,WAA0B;QAClC,IAAI,WAAW,CAAC,MAAM,KAAK,CAAC;YAAE,MAAM,IAAI,KAAK,CAAC,6CAA6C,CAAC,CAAC;QAC7F,IAAI,CAAC,OAAO,GAAG,WAAW,CAAC,GAAG,CAAC,UAAU,CAAC,EAAE,CAAC,CAAC,EAAE,UAAU,EAAE,UAAU,EAAE,CAAC,EAAE,aAAa,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;IACpG,CAAC;IAED;;;;OAIG;IACH,MAAM;QACF,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QAEvB,oDAAoD;QACpD,IAAI,SAAS,GAAG,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,aAAa,IAAI,GAAG,CAAC,CAAC;QAEjE,2DAA2D;QAC3D,IAAI,SAAS,CAAC,MAAM,KAAK,CAAC;YAAE,SAAS,GAAG,CAAC,GAAG,IAAI,CAAC,OAAO,CAAC,CAAC;QAE1D,mCAAmC;QACnC,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,UAAU,GAAG,CAAC,CAAC,UAAU,CAAC,CAAC;QAEtD,MAAM,KAAK,GAAG,SAAS,CAAC,CAAC,CAAC,CAAC;QAC3B,KAAK,CAAC,UAAU,GAAG,GAAG,CAAC;QACvB,OAAO,KAAK,CAAC,UAAU,CAAC;IAC5B,CAAC;IAED;;;;;OAKG;IACH,WAAW,CAAC,UAAuB,EAAE,aAAqB,CAAC,GAAG,EAAE,GAAG,IAAI;QACnE,MAAM,KAAK,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,UAAU,KAAK,UAAU,CAAC,CAAC;QAClE,IAAI,KAAK;YAAE,KAAK,CAAC,aAAa,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,UAAU,CAAC;IAC7D,CAAC;CACJ"}

package/dist/audioFormat.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Audio format detection by inspecting file magic bytes.
+ *
+ * Used to determine the correct file extension when writing temporary chunk
+ * files to disk. Supports FLAC, OGG, WAV, M4A/MP4, and MP3 (including ID3-tagged files).
+ */
+/** Recognized audio formats, plus `"unknown"` as a fallback. */
+export type AudioFormat = "mp3" | "wav" | "ogg" | "flac" | "m4a" | "unknown";
+/**
+ * Detects the audio format of a buffer by inspecting its leading bytes (magic bytes).
+ *
+ * @param buffer - Raw audio data (at least 12 bytes for reliable detection).
+ * @returns The detected {@link AudioFormat}, or `"unknown"` if no signature matches.
+ */
+export declare function detectAudioFormat(buffer: Buffer): AudioFormat;
+/**
+ * Maps an {@link AudioFormat} to a file extension string.
+ * Falls back to `"mp3"` for `"unknown"` formats.
+ *
+ * @param format - The detected audio format.
+ * @returns A file extension string (without the leading dot).
+ */
+export declare function audioFormatToExtension(format: AudioFormat): string;
+//# sourceMappingURL=audioFormat.d.ts.map

package/dist/audioFormat.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"audioFormat.d.ts","sourceRoot":"","sources":["../src/audioFormat.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,gEAAgE;AAChE,MAAM,MAAM,WAAW,GAAG,KAAK,GAAG,KAAK,GAAG,KAAK,GAAG,MAAM,GAAG,KAAK,GAAG,SAAS,CAAC;AAE7E;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,WAAW,CAmC7D;AAED;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,WAAW,GAAG,MAAM,CAGlE"}

package/dist/audioFormat.js

@@ -0,0 +1,52 @@
+/**
+ * Audio format detection by inspecting file magic bytes.
+ *
+ * Used to determine the correct file extension when writing temporary chunk
+ * files to disk. Supports FLAC, OGG, WAV, M4A/MP4, and MP3 (including ID3-tagged files).
+ */
+/**
+ * Detects the audio format of a buffer by inspecting its leading bytes (magic bytes).
+ *
+ * @param buffer - Raw audio data (at least 12 bytes for reliable detection).
+ * @returns The detected {@link AudioFormat}, or `"unknown"` if no signature matches.
+ */
+export function detectAudioFormat(buffer) {
+    if (buffer.length < 12)
+        return "unknown";
+    // FLAC: starts with "fLaC" (0x66 0x4C 0x61 0x43)
+    if (buffer[0] === 0x66 && buffer[1] === 0x4C && buffer[2] === 0x61 && buffer[3] === 0x43) {
+        return "flac";
+    }
+    // OGG: starts with "OggS" (0x4F 0x67 0x67 0x53)
+    if (buffer[0] === 0x4F && buffer[1] === 0x67 && buffer[2] === 0x67 && buffer[3] === 0x53) {
+        return "ogg";
+    }
+    // WAV: starts with "RIFF" at offset 0 and "WAVE" at offset 8
+    if (buffer[0] === 0x52 && buffer[1] === 0x49 && buffer[2] === 0x46 && buffer[3] === 0x46 &&
+        buffer[8] === 0x57 && buffer[9] === 0x41 && buffer[10] === 0x56 && buffer[11] === 0x45) {
+        return "wav";
+    }
+    // M4A/MP4: "ftyp" at offset 4 (0x66 0x74 0x79 0x70)
+    if (buffer[4] === 0x66 && buffer[5] === 0x74 && buffer[6] === 0x79 && buffer[7] === 0x70) {
+        return "m4a";
+    }
+    // MP3: either a frame sync word (0xFF followed by 0xE0+) or an ID3 tag header ("ID3")
+    if ((buffer[0] === 0xFF && (buffer[1] & 0xE0) === 0xE0) ||
+        (buffer[0] === 0x49 && buffer[1] === 0x44 && buffer[2] === 0x33)) {
+        return "mp3";
+    }
+    return "unknown";
+}
+/**
+ * Maps an {@link AudioFormat} to a file extension string.
+ * Falls back to `"mp3"` for `"unknown"` formats.
+ *
+ * @param format - The detected audio format.
+ * @returns A file extension string (without the leading dot).
+ */
+export function audioFormatToExtension(format) {
+    if (format === "unknown")
+        return "mp3";
+    return format;
+}
+//# sourceMappingURL=audioFormat.js.map

package/dist/audioFormat.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"audioFormat.js","sourceRoot":"","sources":["../src/audioFormat.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAKH;;;;;GAKG;AACH,MAAM,UAAU,iBAAiB,CAAC,MAAc;IAC5C,IAAI,MAAM,CAAC,MAAM,GAAG,EAAE;QAAE,OAAO,SAAS,CAAC;IAEzC,iDAAiD;IACjD,IAAI,MAAM,CAAC,CAAC,CAAC,KAAK,IAAI,IAAI,MAAM,CAAC,CAAC,CAAC,KAAK,IAAI,IAAI,MAAM,CAAC,CAAC,CAAC,KAAK,IAAI,IAAI,MAAM,CAAC,CAAC,CAAC,KAAK,IAAI,EAAE,CAAC;QACvF,OAAO,MAAM,CAAC;IAClB,CAAC;IAED,gDAAgD;IAChD,IAAI,MAAM,CAAC,CAAC,CAAC,KAAK,IAAI,IAAI,MAAM,CAAC,CAAC,CAAC,KAAK,IAAI,IAAI,MAAM,CAAC,CAAC,CAAC,KAAK,IAAI,IAAI,MAAM,CAAC,CAAC,CAAC,KAAK,IAAI,EAAE,CAAC;QACvF,OAAO,KAAK,CAAC;IACjB,CAAC;IAED,6DAA6D;IAC7D,IACI,MAAM,CAAC,CAAC,CAAC,KAAK,IAAI,IAAI,MAAM,CAAC,CAAC,CAAC,KAAK,IAAI,IAAI,MAAM,CAAC,CAAC,CAAC,KAAK,IAAI,IAAI,MAAM,CAAC,CAAC,CAAC,KAAK,IAAI;QACpF,MAAM,CAAC,CAAC,CAAC,KAAK,IAAI,IAAI,MAAM,CAAC,CAAC,CAAC,KAAK,IAAI,IAAI,MAAM,CAAC,EAAE,CAAC,KAAK,IAAI,IAAI,MAAM,CAAC,EAAE,CAAC,KAAK,IAAI,EACxF,CAAC;QACC,OAAO,KAAK,CAAC;IACjB,CAAC;IAED,oDAAoD;IACpD,IAAI,MAAM,CAAC,CAAC,CAAC,KAAK,IAAI,IAAI,MAAM,CAAC,CAAC,CAAC,KAAK,IAAI,IAAI,MAAM,CAAC,CAAC,CAAC,KAAK,IAAI,IAAI,MAAM,CAAC,CAAC,CAAC,KAAK,IAAI,EAAE,CAAC;QACvF,OAAO,KAAK,CAAC;IACjB,CAAC;IAED,sFAAsF;IACtF,IACI,CAAC,MAAM,CAAC,CAAC,CAAC,KAAK,IAAI,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,KAAK,IAAI,CAAC;QACnD,CAAC,MAAM,CAAC,CAAC,CAAC,KAAK,IAAI,IAAI,MAAM,CAAC,CAAC,CAAC,KAAK,IAAI,IAAI,MAAM,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC,EAClE,CAAC;QACC,OAAO,KAAK,CAAC;IACjB,CAAC;IAED,OAAO,SAAS,CAAC;AACrB,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,sBAAsB,CAAC,MAAmB;IACtD,IAAI,MAAM,KAAK,SAAS;QAAE,OAAO,KAAK,CAAC;IACvC,OAAO,MAAM,CAAC;AAClB,CAAC"}

package/dist/clientFactory.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Factory for creating speech service clients from a provider name and credential.
+ *
+ * This is a thin wrapper around `createSpeechClient` from `@pico-brief/speech-services`
+ * that maps a `(provider, credential)` pair to the config shape expected by the
+ * underlying library.
+ */
+import type { SpeechClient } from "@pico-brief/speech-services";
+/**
+ * Creates a {@link SpeechClient} from a provider name and its corresponding credential object.
+ *
+ * The credential must match the config type for that provider from `@pico-brief/speech-services`:
+ *
+ * | Provider       | Config Type          | Shape                                         |
+ * |----------------|----------------------|-----------------------------------------------|
+ * | `azure`        | `AzureConfig`        | `{ region: string; subscriptionKey: string }`  |
+ * | `playht`       | `PlayHTConfig`       | `{ userId: string; apiKey: string }`           |
+ * | `speechmatics` | `SpeechmaticsConfig` | `{ apiKey: string; region?: string }`          |
+ * | All others     | `*Config`            | `{ apiKey: string }`                           |
+ *
+ * @param provider - The provider name (e.g. `"openai"`, `"azure"`).
+ * @param credential - The credential object for that provider.
+ * @returns A configured {@link SpeechClient} ready for transcription or synthesis calls.
+ */
+export declare function createClientFromCredential(provider: string, credential: object): SpeechClient;
+//# sourceMappingURL=clientFactory.d.ts.map

package/dist/clientFactory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"clientFactory.d.ts","sourceRoot":"","sources":["../src/clientFactory.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAgB,MAAM,6BAA6B,CAAC;AAE9E;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,0BAA0B,CAAC,QAAQ,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,YAAY,CAE7F"}

package/dist/clientFactory.js

@@ -0,0 +1,28 @@
+/**
+ * Factory for creating speech service clients from a provider name and credential.
+ *
+ * This is a thin wrapper around `createSpeechClient` from `@pico-brief/speech-services`
+ * that maps a `(provider, credential)` pair to the config shape expected by the
+ * underlying library.
+ */
+import { createSpeechClient } from "@pico-brief/speech-services";
+/**
+ * Creates a {@link SpeechClient} from a provider name and its corresponding credential object.
+ *
+ * The credential must match the config type for that provider from `@pico-brief/speech-services`:
+ *
+ * | Provider       | Config Type          | Shape                                         |
+ * |----------------|----------------------|-----------------------------------------------|
+ * | `azure`        | `AzureConfig`        | `{ region: string; subscriptionKey: string }`  |
+ * | `playht`       | `PlayHTConfig`       | `{ userId: string; apiKey: string }`           |
+ * | `speechmatics` | `SpeechmaticsConfig` | `{ apiKey: string; region?: string }`          |
+ * | All others     | `*Config`            | `{ apiKey: string }`                           |
+ *
+ * @param provider - The provider name (e.g. `"openai"`, `"azure"`).
+ * @param credential - The credential object for that provider.
+ * @returns A configured {@link SpeechClient} ready for transcription or synthesis calls.
+ */
+export function createClientFromCredential(provider, credential) {
+    return createSpeechClient({ [provider]: credential });
+}
+//# sourceMappingURL=clientFactory.js.map

package/dist/clientFactory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"clientFactory.js","sourceRoot":"","sources":["../src/clientFactory.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,kBAAkB,EAAE,MAAM,6BAA6B,CAAC;AAGjE;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,0BAA0B,CAAC,QAAgB,EAAE,UAAkB;IAC3E,OAAO,kBAAkB,CAAC,EAAE,CAAC,QAAQ,CAAC,EAAE,UAAU,EAAkB,CAAC,CAAC;AAC1E,CAAC"}

package/dist/concurrency.d.ts

@@ -0,0 +1,25 @@
+/**
+ * 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.
+ */
+/**
+ * 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 declare function mapWithConcurrency<T, R>(items: T[], fn: (item: T, index: number) => Promise<R>, maxConcurrency?: number): Promise<R[]>;
+//# sourceMappingURL=concurrency.d.ts.map

package/dist/concurrency.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"concurrency.d.ts","sourceRoot":"","sources":["../src/concurrency.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AA8CH;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,kBAAkB,CAAC,CAAC,EAAE,CAAC,EACzC,KAAK,EAAE,CAAC,EAAE,EACV,EAAE,EAAE,CAAC,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,EAC1C,cAAc,CAAC,EAAE,MAAM,GACxB,OAAO,CAAC,CAAC,EAAE,CAAC,CAiBd"}