@juspay/neurolink 12.48.1 → 12.49.0

package/dist/voice/providers/ElevenLabsSTT.d.ts

@@ -7,7 +7,7 @@
  *
  * @module voice/providers/ElevenLabsSTT
  */
-import type { TTSAudioFormat, STTHandler, STTLanguage, STTOptions, STTResult } from "../../types/index.js";
+import type { TTSAudioFormat, STTCredentials, STTHandler, STTLanguage, STTOptions, STTResult } from "../../types/index.js";
 /**
  * ElevenLabs Scribe Speech-to-Text Handler
  *
@@ -20,15 +20,25 @@ import type { TTSAudioFormat, STTHandler, STTLanguage, STTOptions, STTResult } f
 export declare class ElevenLabsSTT implements STTHandler {
     private readonly apiKey;
     private readonly baseUrl;
+    private readonly defaultTimeoutMs;
     /** Scribe accepts files up to 1 GB / ~4.5 hours; 2 hours is a conservative cap. */
     readonly maxAudioDuration = 7200;
     readonly supportsStreaming = false;
-    constructor(apiKey?: string);
+    /**
+     * @param apiKeyOrCredentials - The `credentials.stt.elevenlabs` slice
+     *   (`apiKey`, `baseURL`, `timeoutMs`), or an API key (the original
+     *   positional form). The environment fills whatever is left out:
+     *   `ELEVENLABS_API_KEY`, and `ELEVENLABS_STT_BASE_URL` before the
+     *   account-wide `ELEVENLABS_BASE_URL`.
+     */
+    constructor(apiKeyOrCredentials?: string | STTCredentials["elevenlabs"]);
     isConfigured(): boolean;
     getSupportedFormats(): TTSAudioFormat[];
     getSupportedLanguages(): Promise<STTLanguage[]>;
     transcribe(audio: Buffer | ArrayBuffer, options?: STTOptions): Promise<STTResult>;
     private toSTTResult;
+    /** A usable timeout: a finite, positive number of milliseconds. */
+    private static validTimeout;
     /** A finite number clamped to [0, 1]; `undefined` for anything else. */
     private static unitInterval;
     /** Mean `exp(logprob)` over the words that carry a finite one, clamped to [0, 1]; `undefined` when none does. */

package/dist/voice/providers/ElevenLabsSTT.js

@@ -28,13 +28,36 @@ const DEFAULT_MODEL = "scribe_v2";
 export class ElevenLabsSTT {
     apiKey;
     baseUrl;
+    defaultTimeoutMs;
     /** Scribe accepts files up to 1 GB / ~4.5 hours; 2 hours is a conservative cap. */
     maxAudioDuration = 7200;
     supportsStreaming = false;
-    constructor(apiKey) {
-        const resolvedKey = (apiKey ?? process.env.ELEVENLABS_API_KEY ?? "").trim();
+    /**
+     * @param apiKeyOrCredentials - The `credentials.stt.elevenlabs` slice
+     *   (`apiKey`, `baseURL`, `timeoutMs`), or an API key (the original
+     *   positional form). The environment fills whatever is left out:
+     *   `ELEVENLABS_API_KEY`, and `ELEVENLABS_STT_BASE_URL` before the
+     *   account-wide `ELEVENLABS_BASE_URL`.
+     */
+    constructor(apiKeyOrCredentials) {
+        // `typeof x === "string"` narrows the same way with and without
+        // strictNullChecks (the react-hooks build runs tsc without it); an
+        // `=== undefined` test does not.
+        const slice = typeof apiKeyOrCredentials === "string"
+            ? { apiKey: apiKeyOrCredentials }
+            : (apiKeyOrCredentials ?? {});
+        const resolvedKey = (slice.apiKey ??
+            process.env.ELEVENLABS_API_KEY ??
+            "").trim();
         this.apiKey = resolvedKey.length > 0 ? resolvedKey : null;
-        this.baseUrl = ElevenLabsSTT.normalizeBaseUrl(process.env.ELEVENLABS_BASE_URL ?? DEFAULT_BASE_URL);
+        this.baseUrl = ElevenLabsSTT.normalizeBaseUrl(("baseURL" in slice ? slice.baseURL : undefined) ??
+            process.env.ELEVENLABS_STT_BASE_URL ??
+            process.env.ELEVENLABS_BASE_URL ??
+            DEFAULT_BASE_URL);
+        const sliceTimeout = "timeoutMs" in slice ? slice.timeoutMs : undefined;
+        this.defaultTimeoutMs = ElevenLabsSTT.validTimeout(sliceTimeout)
+            ? Math.min(sliceTimeout, MAX_TIMEOUT_MS)
+            : DEFAULT_TIMEOUT_MS;
     }
     isConfigured() {
         return this.apiKey !== null;
@@ -146,7 +169,8 @@ export class ElevenLabsSTT {
             // otherwise, and an injected default would pin every request to one
             // language. (STTProcessor passes options through untouched, so a caller
             // who leaves `language` unset reaches here with it unset.)
-            if (options.language) {
+            if (options.language &&
+                options.language.trim().toLowerCase() !== "auto") {
                 formData.append("language_code", this.toScribeLanguageCode(options.language));
             }
             // ElevenLabs defaults this to true; a plain transcript is the better
@@ -160,11 +184,9 @@ export class ElevenLabsSTT {
             const baseUrl = elevenOptions.baseUrl
                 ? ElevenLabsSTT.normalizeBaseUrl(elevenOptions.baseUrl)
                 : this.baseUrl;
-            const timeoutMs = typeof elevenOptions.timeoutMs === "number" &&
-                Number.isFinite(elevenOptions.timeoutMs) &&
-                elevenOptions.timeoutMs > 0
+            const timeoutMs = ElevenLabsSTT.validTimeout(elevenOptions.timeoutMs)
                 ? Math.min(elevenOptions.timeoutMs, MAX_TIMEOUT_MS)
-                : DEFAULT_TIMEOUT_MS;
+                : this.defaultTimeoutMs;
             // The timer covers the response headers AND the JSON body: a server
             // that stalls mid-body used to hold the transcription — and the
             // generate() it fed — until undici's own ~5-minute body timeout, long
@@ -298,6 +320,10 @@ export class ElevenLabsSTT {
         }
         return result;
     }
+    /** A usable timeout: a finite, positive number of milliseconds. */
+    static validTimeout(value) {
+        return typeof value === "number" && Number.isFinite(value) && value > 0;
+    }
     /** A finite number clamped to [0, 1]; `undefined` for anything else. */
     static unitInterval(value) {
         return typeof value === "number" && Number.isFinite(value)

package/dist/voice/providers/GoogleSTT.d.ts

@@ -5,7 +5,7 @@
  *
  * @module voice/providers/GoogleSTT
  */
-import type { TTSAudioFormat, STTHandler, STTLanguage, STTOptions, STTResult, TranscriptionSegment } from "../../types/index.js";
+import type { TTSAudioFormat, STTCredentials, STTHandler, STTLanguage, STTOptions, STTResult } from "../../types/index.js";
 /**
  * Google Cloud Speech-to-Text Handler
  *
@@ -23,19 +23,21 @@ export declare class GoogleSTT implements STTHandler {
      */
     readonly maxAudioDuration = 60;
     /**
-     * True streaming requires gRPC (not yet implemented).
-     * transcribeStream() uses a chunk-and-batch workaround.
+     * True streaming requires gRPC (not implemented). `transcribeStream()` on
+     * the SDK streams this handler through the generic chunked adapter.
      */
     readonly supportsStreaming = false;
-    constructor(apiKey?: string, credentialsPath?: string);
+    /**
+     * @param apiKeyOrCredentials - The `credentials.stt.google` slice
+     *   (`apiKey`, `credentialsPath`), or an API key (the original positional
+     *   form). The environment fills whatever is left out.
+     * @param credentialsPath - Service-account file, positional form only.
+     */
+    constructor(apiKeyOrCredentials?: string | STTCredentials["google"], credentialsPath?: string);
     isConfigured(): boolean;
     getSupportedFormats(): TTSAudioFormat[];
     getSupportedLanguages(): Promise<STTLanguage[]>;
     transcribe(audio: Buffer | ArrayBuffer, options?: STTOptions): Promise<STTResult>;
-    /**
-     * Streaming transcription (placeholder - requires WebSocket/gRPC)
-     */
-    transcribeStream(audioStream: AsyncIterable<Buffer>, options: STTOptions): AsyncIterable<TranscriptionSegment>;
     /**
      * Get encoding string for audio format
      */

package/dist/voice/providers/GoogleSTT.js

@@ -24,21 +24,33 @@ export class GoogleSTT {
      */
     maxAudioDuration = 60;
     /**
-     * True streaming requires gRPC (not yet implemented).
-     * transcribeStream() uses a chunk-and-batch workaround.
+     * True streaming requires gRPC (not implemented). `transcribeStream()` on
+     * the SDK streams this handler through the generic chunked adapter.
      */
     supportsStreaming = false;
-    constructor(apiKey, credentialsPath) {
+    /**
+     * @param apiKeyOrCredentials - The `credentials.stt.google` slice
+     *   (`apiKey`, `credentialsPath`), or an API key (the original positional
+     *   form). The environment fills whatever is left out.
+     * @param credentialsPath - Service-account file, positional form only.
+     */
+    constructor(apiKeyOrCredentials, credentialsPath) {
+        // `typeof x === "string"` narrows the same way with and without
+        // strictNullChecks (the react-hooks build runs tsc without it); an
+        // `=== undefined` test does not.
+        const slice = typeof apiKeyOrCredentials === "string"
+            ? { apiKey: apiKeyOrCredentials, credentialsPath }
+            : { credentialsPath, ...(apiKeyOrCredentials ?? {}) };
         // Accept GOOGLE_AI_API_KEY / GEMINI_API_KEY as aliases since `.env.example`
         // documents those as the canonical Google credentials and forcing users to
         // also set GOOGLE_API_KEY just for STT was a footgun (Copilot review).
-        const resolvedKey = (apiKey ??
+        const resolvedKey = (slice.apiKey ??
             process.env.GOOGLE_API_KEY ??
             process.env.GOOGLE_AI_API_KEY ??
             process.env.GEMINI_API_KEY ??
             "").trim();
         this.apiKey = resolvedKey.length > 0 ? resolvedKey : null;
-        const resolvedCreds = (credentialsPath ??
+        const resolvedCreds = (slice.credentialsPath ??
             process.env.GOOGLE_APPLICATION_CREDENTIALS ??
             "").trim();
         this.credentialsPath = resolvedCreds.length > 0 ? resolvedCreds : null;
@@ -166,7 +178,10 @@ export class GoogleSTT {
                     : options.sampleRate
                         ? { sampleRateHertz: options.sampleRate }
                         : {}),
-                languageCode: options.language ?? "en-US",
+                // Google needs a language; "auto" (no pin) falls back to the default.
+                languageCode: options.language && options.language.toLowerCase() !== "auto"
+                    ? options.language
+                    : "en-US",
                 enableAutomaticPunctuation: options.punctuation ?? true,
                 enableWordTimeOffsets: options.wordTimestamps ?? false,
                 enableWordConfidence: true,
@@ -313,75 +328,6 @@ export class GoogleSTT {
             throw STTError.transcriptionFailed(errorMessage, "google-stt", err instanceof Error ? err : undefined);
         }
     }
-    /**
-     * Streaming transcription (placeholder - requires WebSocket/gRPC)
-     */
-    async *transcribeStream(audioStream, options) {
-        // Google streaming STT requires gRPC or WebSocket connection
-        // For now, buffer and transcribe in chunks
-        const chunks = [];
-        let chunkIndex = 0;
-        for await (const chunk of audioStream) {
-            chunks.push(chunk);
-            // Process every ~5 seconds of audio (assuming 16kHz, 16-bit)
-            const bytesPerSecond = 16000 * 2; // 16kHz * 2 bytes
-            const totalBytes = chunks.reduce((sum, c) => sum + c.length, 0);
-            if (totalBytes >= bytesPerSecond * 5) {
-                const audio = Buffer.concat(chunks);
-                chunks.length = 0;
-                try {
-                    const result = await this.transcribe(audio, options);
-                    yield {
-                        index: chunkIndex++,
-                        text: result.text,
-                        isFinal: false,
-                        confidence: result.confidence,
-                    };
-                }
-                catch (err) {
-                    // M5: distinguish permanent (auth, schema, 4xx) from transient
-                    // (5xx, 429, network) errors. Permanent errors retry indefinitely
-                    // and racks up failed API calls; rethrow to terminate the stream.
-                    // Transient errors get logged and skipped so a multi-minute audio
-                    // stream can recover from a transient hiccup.
-                    const msg = err instanceof Error ? err.message : String(err);
-                    const isPermanent = /\b(401|403|404|UNAUTHENTICATED|PERMISSION_DENIED|INVALID_ARGUMENT|UNAUTHORIZED|FORBIDDEN|invalid.*credential|invalid.*key)\b/i.test(msg);
-                    if (isPermanent) {
-                        logger.error(`[GoogleSTTHandler] Permanent chunk error — terminating stream: ${msg}`);
-                        throw err;
-                    }
-                    logger.warn(`[GoogleSTTHandler] Transient chunk failure (skipping): ${msg}`);
-                }
-            }
-        }
-        // Process remaining audio
-        if (chunks.length > 0) {
-            const audio = Buffer.concat(chunks);
-            try {
-                const result = await this.transcribe(audio, options);
-                yield {
-                    index: chunkIndex,
-                    text: result.text,
-                    isFinal: true,
-                    confidence: result.confidence,
-                };
-            }
-            catch (err) {
-                // Don't swallow the final chunk's terminal errors — auth/config/4xx
-                // failures here would otherwise look like a successful empty
-                // transcription, hiding the root cause from callers (CodeRabbit
-                // review). Mirror the permanent-vs-transient split used in the
-                // chunk loop above (Azure/Google share this taxonomy).
-                const msg = err instanceof Error ? err.message : String(err);
-                const isPermanent = /\b(401|403|404|Forbidden|Unauthorized|Invalid.*credential|Invalid.*key|Permission|PERMISSION_DENIED|UNAUTHENTICATED|INVALID_ARGUMENT)\b/i.test(msg);
-                if (isPermanent) {
-                    logger.error(`[GoogleSTTHandler] Permanent final-chunk error — surfacing: ${msg}`);
-                    throw err;
-                }
-                logger.warn(`[GoogleSTTHandler] Final chunk transcription failed (transient): ${msg}`);
-            }
-        }
-    }
     /**
      * Get encoding string for audio format
      */

package/dist/voice/providers/OpenAISTT.d.ts

@@ -5,17 +5,13 @@
  *
  * @module voice/providers/OpenAISTT
  */
-import type { TTSAudioFormat, STTHandler, STTLanguage, STTOptions, STTResult } from "../../types/index.js";
-/**
- * OpenAI Whisper Speech-to-Text Handler
- *
- * Supports transcription and translation using OpenAI's Whisper model.
- *
- * @see https://platform.openai.com/docs/api-reference/audio
- */
+import type { TTSAudioFormat, STTCredentials, STTHandler, STTLanguage, STTOptions, STTResult } from "../../types/index.js";
 export declare class OpenAISTT implements STTHandler {
     private readonly apiKey;
     private readonly baseUrl;
+    private readonly defaultTimeoutMs;
+    /** The `model` sent when the request names none. */
+    private readonly defaultModel;
     /**
      * Maximum audio duration in seconds (25 minutes)
      */
@@ -24,11 +20,36 @@ export declare class OpenAISTT implements STTHandler {
      * Whisper does not support streaming
      */
     readonly supportsStreaming = false;
-    constructor(apiKey?: string);
+    /**
+     * @param apiKeyOrCredentials - The `credentials.stt.whisper` slice
+     *   (`apiKey`, `baseURL`, `timeoutMs`), or — the original positional form —
+     *   an API key. Anything left out falls back to the environment.
+     * @param baseUrl - Base URL, positional form only.
+     */
+    constructor(apiKeyOrCredentials?: string | STTCredentials["whisper"], baseUrl?: string);
+    /** True when pointed at OpenAI itself rather than a compatible server. */
+    private get isOfficialEndpoint();
+    /**
+     * OpenAI itself needs a key. A compatible server at another base URL may
+     * not (a self-hosted engine on the local network), so a base URL alone
+     * configures the handler and the request goes without an Authorization header.
+     */
     isConfigured(): boolean;
     getSupportedFormats(): TTSAudioFormat[];
     getSupportedLanguages(): Promise<STTLanguage[]>;
     transcribe(audio: Buffer | ArrayBuffer, options?: STTOptions): Promise<STTResult>;
+    /**
+     * The context prompt: the caller's own text, then the vocabulary as one
+     * sentence. Whisper-style decoders treat the prompt as preceding text, so a
+     * plain list of names biases spelling without being read as an instruction.
+     */
+    private static buildPrompt;
+    /**
+     * Optional language-identification fields a self-hosted server may add to
+     * `verbose_json`. Each is read only when it has the expected shape; a
+     * server that sends none (OpenAI itself) contributes nothing.
+     */
+    private static readLanguageExtensions;
     /**
      * Get MIME type for audio format. Whisper auto-detects from headers, but
      * sending a correct MIME helps providers / proxies that sniff Content-Type.

package/dist/voice/providers/OpenAISTT.js

@@ -7,16 +7,62 @@
  */
 import { logger } from "../../utils/logger.js";
 import { STTError } from "../errors.js";
+const OPENAI_STT_DEFAULT_BASE_URL = "https://api.openai.com/v1";
+const DEFAULT_TIMEOUT_MS = 30_000;
 /**
  * OpenAI Whisper Speech-to-Text Handler
  *
- * Supports transcription and translation using OpenAI's Whisper model.
+ * Supports transcription and translation using OpenAI's Whisper model, and
+ * any server that speaks the same `/audio/transcriptions` wire format: vLLM
+ * serving an ASR model, LiteLLM, or NeuroLink's diarization sidecar. Point it
+ * elsewhere with the `baseUrl` constructor argument or `OPENAI_STT_BASE_URL`;
+ * the key then comes from `OPENAI_STT_API_KEY` (falling back to
+ * `OPENAI_API_KEY`), so a keyless local server can use a placeholder without
+ * touching the real OpenAI credential. Set `OPENAI_STT_TIMEOUT_MS` for long
+ * recordings — a local server transcribing a whole meeting needs minutes.
  *
  * @see https://platform.openai.com/docs/api-reference/audio
  */
+/**
+ * Trailing slashes off a caller-supplied URL, in one linear pass. A `/\/+$/`
+ * regex retries from every slash of a long run and is quadratic on hostile
+ * input (CodeQL js/polynomial-redos).
+ */
+function stripTrailingSlashes(url) {
+    let end = url.length;
+    while (end > 0 && url.charCodeAt(end - 1) === 47) {
+        end--;
+    }
+    return url.slice(0, end);
+}
+const MIN_TIMEOUT_MS = 1_000;
+const MAX_TIMEOUT_MS = 60 * 60 * 1_000;
+/**
+ * A finite timeout within [1 s, 1 h], else the handler's own default. Written
+ * as explicit range checks: the value can come from a request body and ends
+ * up in a timer, and a comparison against a constant bound is what static
+ * analysis recognises as bounding it.
+ */
+function clampTimeoutMs(requested, fallback) {
+    if (typeof requested !== "number" ||
+        !Number.isFinite(requested) ||
+        requested <= 0) {
+        return fallback;
+    }
+    if (requested > MAX_TIMEOUT_MS) {
+        return MAX_TIMEOUT_MS;
+    }
+    if (requested < MIN_TIMEOUT_MS) {
+        return MIN_TIMEOUT_MS;
+    }
+    return Math.floor(requested);
+}
 export class OpenAISTT {
     apiKey;
-    baseUrl = "https://api.openai.com/v1";
+    baseUrl;
+    defaultTimeoutMs;
+    /** The `model` sent when the request names none. */
+    defaultModel;
     /**
      * Maximum audio duration in seconds (25 minutes)
      */
@@ -25,12 +71,54 @@ export class OpenAISTT {
      * Whisper does not support streaming
      */
     supportsStreaming = false;
-    constructor(apiKey) {
-        const resolvedKey = (apiKey ?? process.env.OPENAI_API_KEY ?? "").trim();
+    /**
+     * @param apiKeyOrCredentials - The `credentials.stt.whisper` slice
+     *   (`apiKey`, `baseURL`, `timeoutMs`), or — the original positional form —
+     *   an API key. Anything left out falls back to the environment.
+     * @param baseUrl - Base URL, positional form only.
+     */
+    constructor(apiKeyOrCredentials, baseUrl) {
+        // `typeof x === "string"` narrows the same way with and without
+        // strictNullChecks (the react-hooks build runs tsc without it); an
+        // `=== undefined` test does not.
+        const slice = typeof apiKeyOrCredentials === "string"
+            ? { apiKey: apiKeyOrCredentials, baseURL: baseUrl }
+            : { baseURL: baseUrl, ...(apiKeyOrCredentials ?? {}) };
+        this.baseUrl = stripTrailingSlashes((slice.baseURL ??
+            process.env.OPENAI_STT_BASE_URL ??
+            OPENAI_STT_DEFAULT_BASE_URL).trim());
+        // A dedicated STT key wins so a local endpoint never borrows the real
+        // OpenAI credential; the plain key keeps working for api.openai.com.
+        // `OPENAI_API_KEY` is OpenAI's credential and goes only to api.openai.com;
+        // a custom base URL takes the dedicated STT key or the slice's own, so a
+        // self-hosted or proxied endpoint never receives the real OpenAI key.
+        const resolvedKey = (slice.apiKey ??
+            process.env.OPENAI_STT_API_KEY ??
+            (this.isOfficialEndpoint ? process.env.OPENAI_API_KEY : undefined) ??
+            "").trim();
         this.apiKey = resolvedKey.length > 0 ? resolvedKey : null;
+        const envTimeout = Number(process.env.OPENAI_STT_TIMEOUT_MS);
+        const sliceTimeout = "timeoutMs" in slice ? Number(slice.timeoutMs) : Number.NaN;
+        this.defaultTimeoutMs =
+            Number.isFinite(sliceTimeout) && sliceTimeout > 0
+                ? sliceTimeout
+                : Number.isFinite(envTimeout) && envTimeout > 0
+                    ? envTimeout
+                    : DEFAULT_TIMEOUT_MS;
+        this.defaultModel =
+            slice.model ?? process.env.OPENAI_STT_MODEL ?? "whisper-1";
     }
+    /** True when pointed at OpenAI itself rather than a compatible server. */
+    get isOfficialEndpoint() {
+        return this.baseUrl === OPENAI_STT_DEFAULT_BASE_URL;
+    }
+    /**
+     * OpenAI itself needs a key. A compatible server at another base URL may
+     * not (a self-hosted engine on the local network), so a base URL alone
+     * configures the handler and the request goes without an Authorization header.
+     */
     isConfigured() {
-        return this.apiKey !== null;
+        return this.apiKey !== null || !this.isOfficialEndpoint;
     }
     getSupportedFormats() {
         // OpenAI Whisper transcription API accepts: flac, m4a, mp3, mp4, mpeg,
@@ -128,7 +216,7 @@ export class OpenAISTT {
         ];
     }
     async transcribe(audio, options = {}) {
-        if (!this.apiKey) {
+        if (!this.isConfigured()) {
             throw STTError.providerNotConfigured("whisper");
         }
         const audioBuffer = Buffer.isBuffer(audio) ? audio : Buffer.from(audio);
@@ -146,13 +234,16 @@ export class OpenAISTT {
             });
             formData.append("file", audioBlob, `audio.${options.format ?? "wav"}`);
             // Add model
-            formData.append("model", whisperOptions.model ?? "whisper-1");
-            // Add optional parameters
-            if (options.language) {
-                formData.append("language", options.language);
+            formData.append("model", whisperOptions.model ?? this.defaultModel);
+            // Add optional parameters. No language (or "auto") leaves detection to
+            // the server; sending a guess would pin every request to it.
+            const language = options.language?.trim();
+            if (language && language.toLowerCase() !== "auto") {
+                formData.append("language", language);
             }
-            if (whisperOptions.prompt) {
-                formData.append("prompt", whisperOptions.prompt);
+            const prompt = OpenAISTT.buildPrompt(whisperOptions.prompt, options.vocabulary);
+            if (prompt) {
+                formData.append("prompt", prompt);
             }
             if (whisperOptions.temperature !== undefined) {
                 formData.append("temperature", whisperOptions.temperature.toString());
@@ -165,26 +256,39 @@ export class OpenAISTT {
                 formData.append("timestamp_granularities[]", "word");
                 formData.append("timestamp_granularities[]", "segment");
             }
+            // OpenAI's own API rejects fields it does not know, so the diarization
+            // switch is sent only to compatible servers that advertise speakers on
+            // their segments (e.g. the NeuroLink diarization sidecar).
+            if (options.speakerDiarization && !this.isOfficialEndpoint) {
+                formData.append("diarize", "true");
+                if (options.speakerCount !== undefined) {
+                    formData.append("max_speakers", String(options.speakerCount));
+                }
+            }
             // Choose endpoint based on translation option
             const endpoint = whisperOptions.translate
                 ? `${this.baseUrl}/audio/translations`
                 : `${this.baseUrl}/audio/transcriptions`;
+            // A request-supplied timeout is bounded (1 s … 1 h): it reaches a timer,
+            // and an unbounded value from a route body could pin a slot for ever
+            // or abort at once (CodeQL js/resource-exhaustion).
+            const timeoutMs = clampTimeoutMs(whisperOptions.timeoutMs, this.defaultTimeoutMs);
             const controller = new AbortController();
-            const timeoutId = setTimeout(() => controller.abort(), 30000);
+            const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
             let response;
             try {
                 response = await fetch(endpoint, {
                     method: "POST",
-                    headers: {
-                        Authorization: `Bearer ${this.apiKey}`,
-                    },
+                    headers: this.apiKey
+                        ? { Authorization: `Bearer ${this.apiKey}` }
+                        : undefined,
                     body: formData,
                     signal: controller.signal,
                 });
             }
             catch (fetchErr) {
                 if (fetchErr instanceof Error && fetchErr.name === "AbortError") {
-                    throw STTError.transcriptionFailed("OpenAI STT request timed out after 30 seconds", "whisper", fetchErr);
+                    throw STTError.transcriptionFailed(`OpenAI STT request timed out after ${Math.round(timeoutMs / 1000)} seconds`, "whisper", fetchErr);
                 }
                 throw fetchErr;
             }
@@ -197,6 +301,23 @@ export class OpenAISTT {
                     .catch(() => Object.create(null));
                 const errorMessage = errorData.error?.message ||
                     `HTTP ${response.status}`;
+                // Some OpenAI-compatible servers (vLLM behind a gateway, for one) serve
+                // a model that cannot produce `verbose_json` and say so with a 400.
+                // Ask once more for plain `json` — the text is what matters; segments
+                // and word timings are simply absent — rather than failing the call.
+                if (response.status === 400 &&
+                    responseFormat === "verbose_json" &&
+                    !whisperOptions.responseFormat &&
+                    /verbose_json|response_format/i.test(errorMessage)) {
+                    if (logger.shouldLog("debug")) {
+                        logger.debug("[OpenAISTT] server refused verbose_json; retrying with json", { endpoint, errorMessage });
+                    }
+                    return this.transcribe(audio, {
+                        ...options,
+                        responseFormat: "json",
+                        wordTimestamps: false,
+                    });
+                }
                 throw STTError.transcriptionFailed(errorMessage, "whisper");
             }
             const latency = Date.now() - startTime;
@@ -209,7 +330,7 @@ export class OpenAISTT {
                     metadata: {
                         latency,
                         provider: "whisper",
-                        model: whisperOptions.model ?? "whisper-1",
+                        model: whisperOptions.model ?? this.defaultModel,
                     },
                 };
             }
@@ -223,8 +344,9 @@ export class OpenAISTT {
                 metadata: {
                     latency,
                     provider: "whisper",
-                    model: whisperOptions.model ?? "whisper-1",
+                    model: whisperOptions.model ?? this.defaultModel,
                     task: data.task,
+                    ...OpenAISTT.readLanguageExtensions(data),
                 },
             };
             // Add word timings if available
@@ -235,17 +357,26 @@ export class OpenAISTT {
                     endTime: word.end,
                 }));
             }
-            // Add segments
+            // Add segments. OpenAI-compatible servers may omit the decoder stats
+            // and may label each segment with a speaker; both are passed through.
             if (data.segments && data.segments.length > 0) {
                 result.segments = data.segments.map((segment, index) => ({
                     index,
                     text: segment.text,
                     isFinal: true,
-                    confidence: Math.exp(segment.avg_logprob), // Convert log prob to confidence
+                    ...(typeof segment.avg_logprob === "number"
+                        ? { confidence: Math.exp(segment.avg_logprob) } // log prob -> confidence
+                        : {}),
                     startTime: segment.start,
                     endTime: segment.end,
+                    ...(segment.speaker !== undefined
+                        ? { speaker: segment.speaker }
+                        : {}),
                 }));
             }
+            if (data.speakers && data.speakers.length > 0) {
+                result.speakers = data.speakers;
+            }
             logger.info(`[WhisperSTTHandler] Transcribed ${data.duration?.toFixed(1) ?? "?"}s audio in ${latency}ms`);
             return result;
         }
@@ -258,6 +389,50 @@ export class OpenAISTT {
             throw STTError.transcriptionFailed(errorMessage, "whisper", err instanceof Error ? err : undefined);
         }
     }
+    /**
+     * The context prompt: the caller's own text, then the vocabulary as one
+     * sentence. Whisper-style decoders treat the prompt as preceding text, so a
+     * plain list of names biases spelling without being read as an instruction.
+     */
+    static buildPrompt(prompt, vocabulary) {
+        const terms = (vocabulary ?? [])
+            .map((term) => term.trim())
+            .filter((term) => term.length > 0);
+        const parts = [
+            prompt?.trim(),
+            terms.length > 0 ? `Names and terms used: ${terms.join(", ")}.` : "",
+        ].filter((part) => !!part);
+        return parts.length > 0 ? parts.join(" ") : undefined;
+    }
+    /**
+     * Optional language-identification fields a self-hosted server may add to
+     * `verbose_json`. Each is read only when it has the expected shape; a
+     * server that sends none (OpenAI itself) contributes nothing.
+     */
+    static readLanguageExtensions(data) {
+        const out = {};
+        if (typeof data.language_detected === "boolean") {
+            out.languageDetected = data.language_detected;
+        }
+        if (typeof data.language_confidence === "number" &&
+            Number.isFinite(data.language_confidence)) {
+            out.languageConfidence = data.language_confidence;
+        }
+        if (Array.isArray(data.language_scores)) {
+            const scores = data.language_scores.filter((entry) => typeof entry === "object" &&
+                entry !== null &&
+                typeof entry.language === "string" &&
+                typeof entry.score === "number" &&
+                Number.isFinite(entry.score));
+            if (scores.length > 0) {
+                out.languageScores = scores.map(({ language, score }) => ({
+                    language,
+                    score,
+                }));
+            }
+        }
+        return out;
+    }
     /**
      * Get MIME type for audio format. Whisper auto-detects from headers, but
      * sending a correct MIME helps providers / proxies that sniff Content-Type.