@juspay/neurolink 12.48.1 → 12.49.0

package/dist/voice/errors.js

@@ -171,6 +171,51 @@ export class STTError extends VoiceError {
             context: { provider, availableProviders },
         });
     }
+    /**
+     * Create an error for a provider name that is neither a shipped STT
+     * provider nor a registered handler. Lists what is configured and what
+     * would configure the rest, so the caller can act on the message alone.
+     */
+    static unknownProvider(provider, configuredProviders, howToConfigure) {
+        const configured = configuredProviders.length > 0
+            ? `Configured: ${configuredProviders.join(", ")}.`
+            : "No STT provider is configured.";
+        return new STTError({
+            code: STT_ERROR_CODES.PROVIDER_NOT_SUPPORTED,
+            message: `STT provider "${provider}" is not supported. ${configured}` +
+                (howToConfigure ? ` To configure another, set ${howToConfigure}.` : ""),
+            category: ErrorCategory.VALIDATION,
+            severity: ErrorSeverity.HIGH,
+            retriable: false,
+            context: { provider, configuredProviders },
+        });
+    }
+    /**
+     * Create an error for audio that could not be read (a missing file, a URL
+     * that failed, an input of the wrong kind).
+     */
+    static audioLoadFailed(reason, originalError) {
+        return new STTError({
+            code: STT_ERROR_CODES.INVALID_AUDIO_FORMAT,
+            message: `Could not load audio: ${reason}`,
+            category: ErrorCategory.VALIDATION,
+            severity: ErrorSeverity.MEDIUM,
+            retriable: false,
+            originalError,
+        });
+    }
+    /**
+     * Create an error for a stream of frames handed to a batch entry point.
+     */
+    static streamInputNotSupported() {
+        return new STTError({
+            code: STT_ERROR_CODES.STREAMING_NOT_SUPPORTED,
+            message: "transcribe() takes a whole recording (bytes, a path or a URL); for an async stream of audio frames use transcribeStream()",
+            category: ErrorCategory.VALIDATION,
+            severity: ErrorSeverity.MEDIUM,
+            retriable: false,
+        });
+    }
     /**
      * Create an error for stream processing failure
      */

package/dist/voice/index.d.ts

@@ -18,6 +18,7 @@
  *
  * @module voice
  */
+import type { STTCredentials, STTHandler } from "../types/index.js";
 export { AUDIO_FORMAT_DETAILS, DEFAULT_REALTIME_CONFIG, DEFAULT_STT_OPTIONS, isSTTResult, isTranscriptionSegment, isValidRealtimeConfig, isValidSTTOptions, REALTIME_ERROR_CODES, STT_ERROR_CODES, VOICE_ERROR_CODES, } from "../types/index.js";
 export { RealtimeError, STTError, VoiceError } from "./errors.js";
 export { BaseRealtimeHandler, RealtimeProcessor } from "./RealtimeVoiceAPI.js";
@@ -35,16 +36,33 @@ export { DeepgramSTT, DeepgramSTT as DeepgramSTTHandler, } from "./providers/Dee
 export { ElevenLabsSTT, ElevenLabsSTT as ElevenLabsSTTHandler, } from "./providers/ElevenLabsSTT.js";
 export { GoogleSTT, GoogleSTT as GoogleSTTHandler, } from "./providers/GoogleSTT.js";
 export { OpenAISTT, OpenAISTTHandler, WhisperSTT, WhisperSTTHandler, } from "./providers/OpenAISTT.js";
+export { WhistleSTT, WhistleSTT as WhistleSTTHandler, } from "./providers/WhistleSTT.js";
 export { GeminiLive, GeminiLive as GeminiLiveHandler, } from "./providers/GeminiLive.js";
 export { OpenAIRealtime, OpenAIRealtime as OpenAIRealtimeHandler, } from "./providers/OpenAIRealtime.js";
+/**
+ * A fresh STT handler for a shipped provider name or alias, built from
+ * `credentials` with the environment as fallback. Used for per-call
+ * credentials, where the registry's shared instance (built from the
+ * environment at registration time) is the wrong one.
+ *
+ * @throws STTError when the name is not a shipped STT provider
+ */
+export declare function createSTTHandler(provider: string, credentials?: STTCredentials): STTHandler;
 /**
  * Register every shipped TTS handler whose backing credentials are
  * present in the environment. Safe to call multiple times.
  */
 export declare function registerDefaultTTSHandlers(): void;
 /**
- * Register every shipped STT handler whose backing credentials are
- * present in the environment. Safe to call multiple times.
+ * Register every shipped STT handler whose backing credentials are present in
+ * the ENVIRONMENT, plus the built-in local engine (Whistle), which is always
+ * registered because it is what a transcription with nothing configured falls
+ * back to, plus the env-declared named endpoints (`NEUROLINK_STT_ENDPOINTS`).
+ * Safe to call multiple times; a name that is already registered is left
+ * alone. Deliberately takes no credentials: the registry is process-wide, so
+ * a handler built from one caller's keys or base URL would be served to every
+ * later caller — per-call and per-instance credentials are resolved at call
+ * time by `STTProcessor.resolveHandler` / `createSTTHandler` instead.
  */
 export declare function registerDefaultSTTHandlers(): void;
 /**

package/dist/voice/index.js

@@ -19,6 +19,7 @@
  * @module voice
  */
 import { MEDIA_HANDLER_CATALOG } from "../factories/mediaHandlerCatalog.js";
+import { resolveCallSTTEndpoints, resolveSTTEndpoints, resolveSTTProviderName, } from "../factories/sttDescriptors.js";
 import { logger } from "../utils/logger.js";
 import { STTProcessor } from "../utils/sttProcessor.js";
 import { TTSProcessor } from "../utils/ttsProcessor.js";
@@ -34,6 +35,7 @@ isSTTResult, isTranscriptionSegment, isValidRealtimeConfig, isValidSTTOptions, R
 // ERRORS
 // ============================================================================
 export { RealtimeError, STTError, VoiceError } from "./errors.js";
+import { STTError } from "./errors.js";
 // ============================================================================
 // REALTIME VOICE API
 // ============================================================================
@@ -64,6 +66,7 @@ export { DeepgramSTT, DeepgramSTT as DeepgramSTTHandler, } from "./providers/Dee
 export { ElevenLabsSTT, ElevenLabsSTT as ElevenLabsSTTHandler, } from "./providers/ElevenLabsSTT.js";
 export { GoogleSTT, GoogleSTT as GoogleSTTHandler, } from "./providers/GoogleSTT.js";
 export { OpenAISTT, OpenAISTTHandler, WhisperSTT, WhisperSTTHandler, } from "./providers/OpenAISTT.js";
+export { WhistleSTT, WhistleSTT as WhistleSTTHandler, } from "./providers/WhistleSTT.js";
 // ============================================================================
 // REALTIME PROVIDERS
 // ============================================================================
@@ -83,6 +86,7 @@ import { DeepgramSTT } from "./providers/DeepgramSTT.js";
 import { ElevenLabsSTT } from "./providers/ElevenLabsSTT.js";
 import { GoogleSTT } from "./providers/GoogleSTT.js";
 import { OpenAISTT } from "./providers/OpenAISTT.js";
+import { WhistleSTT } from "./providers/WhistleSTT.js";
 import { GeminiLive } from "./providers/GeminiLive.js";
 import { OpenAIRealtime } from "./providers/OpenAIRealtime.js";
 // Provider names + aliases are the Task-8 catalog's job — only the factory
@@ -104,13 +108,21 @@ const TTS_HANDLER_CANDIDATES = MEDIA_HANDLER_CATALOG.filter((entry) => entry.kin
     }
     return { name: entry.name, aliases: entry.aliases, factory };
 });
+/**
+ * One factory per STT descriptor name. Each takes the request's (or
+ * instance's) `credentials.stt` and hands its own slice to the handler; the
+ * handler fills whatever the slice leaves out from the environment.
+ */
 const STT_HANDLER_FACTORIES = {
-    whisper: () => new OpenAISTT(),
-    deepgram: () => new DeepgramSTT(),
-    "google-stt": () => new GoogleSTT(),
-    "azure-stt": () => new AzureSTT(),
-    "elevenlabs-stt": () => new ElevenLabsSTT(),
+    whisper: (credentials) => new OpenAISTT(credentials?.whisper),
+    deepgram: (credentials) => new DeepgramSTT(credentials?.deepgram),
+    "elevenlabs-stt": (credentials) => new ElevenLabsSTT(credentials?.elevenlabs),
+    "google-stt": (credentials) => new GoogleSTT(credentials?.google),
+    "azure-stt": (credentials) => new AzureSTT(credentials?.azure),
+    whistle: (credentials) => new WhistleSTT(credentials?.whistle),
 };
+/** Registered even when `isConfigured()` is false: it is the no-config default. */
+const ALWAYS_REGISTERED_STT = new Set(["whistle"]);
 const STT_HANDLER_CANDIDATES = MEDIA_HANDLER_CATALOG.filter((entry) => entry.kind === "stt").map((entry) => {
     const factory = STT_HANDLER_FACTORIES[entry.name];
     if (!factory) {
@@ -118,6 +130,28 @@ const STT_HANDLER_CANDIDATES = MEDIA_HANDLER_CATALOG.filter((entry) => entry.kin
     }
     return { name: entry.name, aliases: entry.aliases, factory };
 });
+/**
+ * A fresh STT handler for a shipped provider name or alias, built from
+ * `credentials` with the environment as fallback. Used for per-call
+ * credentials, where the registry's shared instance (built from the
+ * environment at registration time) is the wrong one.
+ *
+ * @throws STTError when the name is not a shipped STT provider
+ */
+export function createSTTHandler(provider, credentials) {
+    // A named endpoint in the caller's credentials wins over everything and
+    // never touches the shared registry.
+    const endpoint = resolveCallSTTEndpoints(credentials)[provider.trim().toLowerCase()];
+    if (endpoint) {
+        return endpointHandler(endpoint);
+    }
+    const canonical = resolveSTTProviderName(provider);
+    const factory = canonical ? STT_HANDLER_FACTORIES[canonical] : undefined;
+    if (!factory) {
+        throw STTError.providerNotSupported(provider, Object.keys(STT_HANDLER_FACTORIES));
+    }
+    return factory(credentials);
+}
 const REALTIME_HANDLER_FACTORIES = {
     "openai-realtime": () => new OpenAIRealtime(),
     "gemini-live": () => new GeminiLive(),
@@ -152,7 +186,10 @@ function registerCandidates(candidates, supports, getRegistered, register, scope
             }
             if (!handler) {
                 handler = factory();
-                if (requireConfigured && !handler.isConfigured()) {
+                const mustBeConfigured = typeof requireConfigured === "function"
+                    ? requireConfigured(name)
+                    : requireConfigured;
+                if (mustBeConfigured && !handler.isConfigured()) {
                     continue;
                 }
             }
@@ -176,11 +213,40 @@ export function registerDefaultTTSHandlers() {
     registerCandidates(TTS_HANDLER_CANDIDATES, (name) => TTSProcessor.supports(name), (name) => TTSProcessor.getHandler(name), (name, handler) => TTSProcessor.registerHandler(name, handler), "voice/tts", true);
 }
 /**
- * Register every shipped STT handler whose backing credentials are
- * present in the environment. Safe to call multiple times.
+ * Register every shipped STT handler whose backing credentials are present in
+ * the ENVIRONMENT, plus the built-in local engine (Whistle), which is always
+ * registered because it is what a transcription with nothing configured falls
+ * back to, plus the env-declared named endpoints (`NEUROLINK_STT_ENDPOINTS`).
+ * Safe to call multiple times; a name that is already registered is left
+ * alone. Deliberately takes no credentials: the registry is process-wide, so
+ * a handler built from one caller's keys or base URL would be served to every
+ * later caller — per-call and per-instance credentials are resolved at call
+ * time by `STTProcessor.resolveHandler` / `createSTTHandler` instead.
  */
 export function registerDefaultSTTHandlers() {
-    registerCandidates(STT_HANDLER_CANDIDATES, (name) => STTProcessor.supports(name), (name) => STTProcessor.getHandler(name), (name, handler) => STTProcessor.registerHandler(name, handler), "voice/stt", true);
+    registerCandidates(STT_HANDLER_CANDIDATES.map((candidate) => ({
+        name: candidate.name,
+        aliases: candidate.aliases,
+        factory: () => candidate.factory(),
+    })), (name) => STTProcessor.supports(name), (name) => STTProcessor.getHandler(name), (name, handler) => STTProcessor.registerHandler(name, handler), "voice/stt", (name) => !ALWAYS_REGISTERED_STT.has(name));
+    // Named OpenAI-compatible endpoints become providers of their own, so two
+    // self-hosted engines can be told apart and used as each other's fallback.
+    for (const [name, endpoint] of Object.entries(resolveSTTEndpoints())) {
+        if (!STTProcessor.supports(name)) {
+            STTProcessor.registerHandler(name, endpointHandler(endpoint));
+        }
+    }
+}
+/** The OpenAI-compatible handler for one named endpoint. */
+function endpointHandler(endpoint) {
+    // A named endpoint sends its own key or none: it never borrows the
+    // `whisper` provider's env keys, which belong to a different host.
+    return new OpenAISTT({
+        apiKey: endpoint.apiKey ?? "",
+        baseURL: endpoint.baseURL,
+        timeoutMs: endpoint.timeoutMs,
+        model: endpoint.model,
+    });
 }
 /**
  * Register every shipped Realtime handler. Realtime handlers don't gate

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

@@ -5,7 +5,7 @@
  *
  * @module voice/providers/AzureSTT
  */
-import type { TTSAudioFormat, STTHandler, STTLanguage, STTOptions, STTResult, TranscriptionSegment } from "../../types/index.js";
+import type { TTSAudioFormat, STTCredentials, STTHandler, STTLanguage, STTOptions, STTResult } from "../../types/index.js";
 /**
  * Azure Cognitive Services Speech-to-Text Handler
  *
@@ -24,18 +24,21 @@ export declare class AzureSTT implements STTHandler {
      */
     readonly maxAudioDuration = 60;
     /**
-     * Azure STT implementation buffers chunks via REST — not true streaming
+     * REST short-audio recognition has no stream. `transcribeStream()` on the
+     * SDK streams this handler through the generic chunked adapter.
      */
     readonly supportsStreaming = false;
-    constructor(apiKey?: string, region?: string);
+    /**
+     * @param apiKeyOrCredentials - The `credentials.stt.azure` slice (`apiKey`,
+     *   `region`), or an API key (the original positional form).
+     *   `AZURE_SPEECH_KEY` / `AZURE_SPEECH_REGION` fill whatever is left out.
+     * @param region - Region, positional form only.
+     */
+    constructor(apiKeyOrCredentials?: string | STTCredentials["azure"], region?: string);
     isConfigured(): boolean;
     getSupportedFormats(): TTSAudioFormat[];
     getSupportedLanguages(): Promise<STTLanguage[]>;
     transcribe(audio: Buffer | ArrayBuffer, options?: STTOptions): Promise<STTResult>;
-    /**
-     * Streaming transcription (placeholder - requires SDK)
-     */
-    transcribeStream(audioStream: AsyncIterable<Buffer>, options: STTOptions): AsyncIterable<TranscriptionSegment>;
     /**
      * Get Content-Type header for audio format
      */

package/dist/voice/providers/AzureSTT.js

@@ -25,13 +25,28 @@ export class AzureSTT {
      */
     maxAudioDuration = 60;
     /**
-     * Azure STT implementation buffers chunks via REST — not true streaming
+     * REST short-audio recognition has no stream. `transcribeStream()` on the
+     * SDK streams this handler through the generic chunked adapter.
      */
     supportsStreaming = false;
-    constructor(apiKey, region) {
-        const resolvedKey = (apiKey ?? process.env.AZURE_SPEECH_KEY ?? "").trim();
+    /**
+     * @param apiKeyOrCredentials - The `credentials.stt.azure` slice (`apiKey`,
+     *   `region`), or an API key (the original positional form).
+     *   `AZURE_SPEECH_KEY` / `AZURE_SPEECH_REGION` fill whatever is left out.
+     * @param region - Region, positional form only.
+     */
+    constructor(apiKeyOrCredentials, region) {
+        // `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, region }
+            : { region, ...(apiKeyOrCredentials ?? {}) };
+        const resolvedKey = (slice.apiKey ??
+            process.env.AZURE_SPEECH_KEY ??
+            "").trim();
         this.apiKey = resolvedKey.length > 0 ? resolvedKey : null;
-        const resolvedRegion = (region ??
+        const resolvedRegion = (slice.region ??
             process.env.AZURE_SPEECH_REGION ??
             "").trim();
         this.region = resolvedRegion.length > 0 ? resolvedRegion : "eastus";
@@ -148,7 +163,10 @@ export class AzureSTT {
         try {
             // Build the URL with query parameters
             const params = new URLSearchParams();
-            params.set("language", options.language ?? "en-US");
+            // Azure needs a language; "auto" (no pin) falls back to the default.
+            params.set("language", options.language && options.language.toLowerCase() !== "auto"
+                ? options.language
+                : "en-US");
             // Add detailed output format
             if (azureOptions.detailed || options.wordTimestamps) {
                 params.set("format", "detailed");
@@ -251,76 +269,6 @@ export class AzureSTT {
             throw STTError.transcriptionFailed(errorMessage, "azure-stt", err instanceof Error ? err : undefined);
         }
     }
-    /**
-     * Streaming transcription (placeholder - requires SDK)
-     */
-    async *transcribeStream(audioStream, options) {
-        // Azure streaming requires the Microsoft Speech SDK
-        // For now, buffer and transcribe in chunks
-        const chunks = [];
-        let chunkIndex = 0;
-        // Track buffered byte count incrementally — `chunks.reduce()` per incoming
-        // chunk is O(n²) over long streams (Copilot/CodeRabbit review). Reset to 0
-        // every time we flush.
-        let bufferedBytes = 0;
-        for await (const chunk of audioStream) {
-            chunks.push(chunk);
-            bufferedBytes += chunk.length;
-            // Process every ~5 seconds of audio
-            const bytesPerSecond = (options.sampleRate ?? 16000) * 2;
-            if (bufferedBytes >= bytesPerSecond * 5) {
-                const audio = Buffer.concat(chunks);
-                chunks.length = 0;
-                bufferedBytes = 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. Without this, an expired API key
-                    // would silently retry every chunk for the entire stream.
-                    const msg = err instanceof Error ? err.message : String(err);
-                    const isPermanent = /\b(401|403|404|Forbidden|Unauthorized|Invalid.*subscription|Invalid.*key|Wrong.*key|InvalidAudioFormat)\b/i.test(msg);
-                    if (isPermanent) {
-                        logger.error(`[AzureSTTHandler] Permanent chunk error — terminating stream: ${msg}`);
-                        throw err;
-                    }
-                    logger.warn(`[AzureSTTHandler] 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) {
-                // Mirror the permanent-vs-transient split from the chunk loop above so
-                // auth/format failures don't masquerade as a successful empty
-                // transcription on short streams (≤5s buffer flush).
-                const msg = err instanceof Error ? err.message : String(err);
-                const isPermanent = /\b(401|403|404|Forbidden|Unauthorized|Invalid.*subscription|Invalid.*key|Wrong.*key|InvalidAudioFormat)\b/i.test(msg);
-                if (isPermanent) {
-                    logger.error(`[AzureSTTHandler] Permanent final-chunk error — surfacing: ${msg}`);
-                    throw err;
-                }
-                logger.warn(`[AzureSTTHandler] Final chunk transcription failed (transient): ${msg}`);
-            }
-        }
-    }
     /**
      * Get Content-Type header for audio format
      */

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

@@ -5,7 +5,7 @@
  *
  * @module voice/providers/DeepgramSTT
  */
-import type { TTSAudioFormat, STTHandler, STTLanguage, STTOptions, STTResult, TranscriptionSegment } from "../../types/index.js";
+import type { TTSAudioFormat, STTCredentials, STTHandler, STTLanguage, STTOptions, STTResult, TranscriptionSegment } from "../../types/index.js";
 /**
  * Deepgram Speech-to-Text Handler
  *
@@ -24,7 +24,16 @@ export declare class DeepgramSTT implements STTHandler {
      * Deepgram supports streaming
      */
     readonly supportsStreaming = true;
-    constructor(apiKey?: string);
+    /**
+     * @param apiKeyOrCredentials - The `credentials.stt.deepgram` slice
+     *   (`apiKey`, `baseURL`), or an API key (the original positional form).
+     *   `DEEPGRAM_API_KEY` / `DEEPGRAM_BASE_URL` fill whatever is left out.
+     */
+    constructor(apiKeyOrCredentials?: string | STTCredentials["deepgram"]);
+    /** The streaming endpoint: the REST base URL on the WebSocket scheme. */
+    private get wsBaseUrl();
+    /** A language the caller pinned, or `undefined` for "let Deepgram detect". */
+    private static pinnedLanguage;
     isConfigured(): boolean;
     getSupportedFormats(): TTSAudioFormat[];
     getSupportedLanguages(): Promise<STTLanguage[]>;
@@ -33,6 +42,12 @@ export declare class DeepgramSTT implements STTHandler {
      * Streaming transcription using WebSocket
      */
     transcribeStream(audioStream: AsyncIterable<Buffer>, options: STTOptions): AsyncIterable<TranscriptionSegment>;
+    /**
+     * Timing, words and speaker of one live result, taken only from fields the
+     * payload actually carries. The segment's speaker is its words' speaker
+     * when they all agree.
+     */
+    private static streamSegmentDetails;
     /**
      * Get MIME type for audio format
      */

package/dist/voice/providers/DeepgramSTT.js

@@ -7,6 +7,8 @@
  */
 import { logger } from "../../utils/logger.js";
 import { STTError } from "../errors.js";
+const DEFAULT_BASE_URL = "https://api.deepgram.com/v1";
+const DEFAULT_TIMEOUT_MS = 30_000;
 /**
  * Deepgram Speech-to-Text Handler
  *
@@ -16,7 +18,7 @@ import { STTError } from "../errors.js";
  */
 export class DeepgramSTT {
     apiKey;
-    baseUrl = "https://api.deepgram.com/v1";
+    baseUrl;
     /**
      * Maximum audio duration in seconds (2 hours)
      */
@@ -25,12 +27,45 @@ export class DeepgramSTT {
      * Deepgram supports streaming
      */
     supportsStreaming = true;
-    constructor(apiKey) {
+    /**
+     * @param apiKeyOrCredentials - The `credentials.stt.deepgram` slice
+     *   (`apiKey`, `baseURL`), or an API key (the original positional form).
+     *   `DEEPGRAM_API_KEY` / `DEEPGRAM_BASE_URL` fill whatever is left out.
+     */
+    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 ?? {});
         // Normalize: trim surrounding whitespace and treat empty string as null
         // so isConfigured() and transcribe()/transcribeStream() agree on the
         // contract (other voice providers all do this — Deepgram was missed).
-        const resolvedKey = (apiKey ?? process.env.DEEPGRAM_API_KEY ?? "").trim();
+        const resolvedKey = (slice.apiKey ??
+            process.env.DEEPGRAM_API_KEY ??
+            "").trim();
         this.apiKey = resolvedKey.length > 0 ? resolvedKey : null;
+        const baseURL = ("baseURL" in slice ? slice.baseURL : undefined) ??
+            process.env.DEEPGRAM_BASE_URL ??
+            DEFAULT_BASE_URL;
+        // Linear trailing-slash strip; a `/\/+$/` regex is quadratic on a long
+        // run of slashes in a caller-supplied URL (CodeQL js/polynomial-redos).
+        let end = baseURL.trim().length;
+        const trimmed = baseURL.trim();
+        while (end > 0 && trimmed.charCodeAt(end - 1) === 47) {
+            end--;
+        }
+        this.baseUrl = trimmed.slice(0, end) || DEFAULT_BASE_URL;
+    }
+    /** The streaming endpoint: the REST base URL on the WebSocket scheme. */
+    get wsBaseUrl() {
+        return this.baseUrl.replace(/^http(s?):\/\//i, (_m, secure) => secure ? "wss://" : "ws://");
+    }
+    /** A language the caller pinned, or `undefined` for "let Deepgram detect". */
+    static pinnedLanguage(language) {
+        const trimmed = language?.trim();
+        return trimmed && trimmed.toLowerCase() !== "auto" ? trimmed : undefined;
     }
     isConfigured() {
         return this.apiKey !== null;
@@ -142,9 +177,13 @@ export class DeepgramSTT {
             const params = new URLSearchParams();
             // Add model
             params.set("model", deepgramOptions.model ?? "nova-2");
-            // Add language
-            if (options.language) {
-                params.set("language", options.language);
+            // Add language, or ask Deepgram to detect it
+            const language = DeepgramSTT.pinnedLanguage(options.language);
+            if (language) {
+                params.set("language", language);
+            }
+            else {
+                params.set("detect_language", "true");
             }
             // Add punctuation
             if (options.punctuation !== false) {
@@ -176,7 +215,9 @@ export class DeepgramSTT {
             if (deepgramOptions.fillerWords) {
                 params.set("filler_words", "true");
             }
-            // Add keywords
+            // Add keywords. Generic `vocabulary` maps onto the same boost when
+            // the caller gave no Deepgram-specific list; Nova-3 takes it as
+            // `keyterm`, earlier models as `keywords`.
             if (deepgramOptions.keywords && deepgramOptions.keywords.length > 0) {
                 for (const keyword of deepgramOptions.keywords) {
                     params.append("keywords", keyword);
@@ -185,6 +226,16 @@ export class DeepgramSTT {
                     params.set("keyword_boost", deepgramOptions.keywordBoost);
                 }
             }
+            else if (options.vocabulary && options.vocabulary.length > 0) {
+                const param = (deepgramOptions.model ?? "nova-2").startsWith("nova-3")
+                    ? "keyterm"
+                    : "keywords";
+                for (const term of options.vocabulary) {
+                    if (term.trim()) {
+                        params.append(param, term.trim());
+                    }
+                }
+            }
             // Add redaction
             if (deepgramOptions.redact && deepgramOptions.redact.length > 0) {
                 for (const redactType of deepgramOptions.redact) {
@@ -197,7 +248,10 @@ export class DeepgramSTT {
             }
             const url = `${this.baseUrl}/listen?${params.toString()}`;
             const controller = new AbortController();
-            const timeoutId = setTimeout(() => controller.abort(), 30000);
+            const timeoutMs = typeof options.timeoutMs === "number" && options.timeoutMs > 0
+                ? options.timeoutMs
+                : DEFAULT_TIMEOUT_MS;
+            const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
             let response;
             try {
                 response = await fetch(url, {
@@ -212,7 +266,7 @@ export class DeepgramSTT {
             }
             catch (fetchErr) {
                 if (fetchErr instanceof Error && fetchErr.name === "AbortError") {
-                    throw STTError.transcriptionFailed("Deepgram STT request timed out after 30 seconds", "deepgram", fetchErr);
+                    throw STTError.transcriptionFailed(`Deepgram STT request timed out after ${Math.round(timeoutMs / 1000)} seconds`, "deepgram", fetchErr);
                 }
                 throw fetchErr;
             }
@@ -252,13 +306,18 @@ export class DeepgramSTT {
             const result = {
                 text: firstAlternative.transcript,
                 confidence: firstAlternative.confidence,
-                language: options.language,
+                language: typeof firstChannel.detected_language === "string"
+                    ? firstChannel.detected_language
+                    : options.language,
                 duration: data.metadata?.duration,
                 metadata: {
                     latency,
                     provider: "deepgram",
                     model: deepgramOptions.model ?? "nova-2",
                     requestId: data.metadata?.request_id,
+                    ...(typeof firstChannel.language_confidence === "number"
+                        ? { languageConfidence: firstChannel.language_confidence }
+                        : {}),
                 },
             };
             // Add word timings
@@ -316,8 +375,11 @@ export class DeepgramSTT {
         // Build query parameters
         const params = new URLSearchParams();
         params.set("model", deepgramOptions.model ?? "nova-2");
-        if (options.language) {
-            params.set("language", options.language);
+        // The live endpoint has no `detect_language`; an unpinned stream runs on
+        // the model's default language.
+        const streamLanguage = DeepgramSTT.pinnedLanguage(options.language);
+        if (streamLanguage) {
+            params.set("language", streamLanguage);
         }
         if (options.punctuation !== false) {
             params.set("punctuate", "true");
@@ -330,7 +392,7 @@ export class DeepgramSTT {
         }
         // Indicate interim results
         params.set("interim_results", "true");
-        const wsUrl = `wss://api.deepgram.com/v1/listen?${params.toString()}`;
+        const wsUrl = `${this.wsBaseUrl}/listen?${params.toString()}`;
         // Create WebSocket connection
         const WebSocket = (await import("ws")).default;
         const ws = new WebSocket(wsUrl, {
@@ -358,6 +420,7 @@ export class DeepgramSTT {
                             text: alt.transcript,
                             isFinal: response.is_final ?? false,
                             confidence: alt.confidence ?? 0,
+                            ...DeepgramSTT.streamSegmentDetails(response, alt.words),
                         };
                         if (resolveNext) {
                             resolveNext({ value: segment, done: false });
@@ -534,6 +597,39 @@ export class DeepgramSTT {
             }
         }
     }
+    /**
+     * Timing, words and speaker of one live result, taken only from fields the
+     * payload actually carries. The segment's speaker is its words' speaker
+     * when they all agree.
+     */
+    static streamSegmentDetails(response, words) {
+        const details = {};
+        if (typeof response.start === "number") {
+            details.startTime = response.start;
+            if (typeof response.duration === "number") {
+                details.endTime = response.start + response.duration;
+            }
+        }
+        if (Array.isArray(words) && words.length > 0) {
+            details.words = words.map((word) => {
+                const timing = {
+                    word: word.punctuated_word ?? word.word,
+                    startTime: word.start,
+                    endTime: word.end,
+                    confidence: word.confidence,
+                };
+                if (word.speaker !== undefined) {
+                    timing.speaker = `Speaker ${word.speaker}`;
+                }
+                return timing;
+            });
+            const speakers = new Set(details.words.map((w) => w.speaker).filter((s) => s !== undefined));
+            if (speakers.size === 1) {
+                details.speaker = [...speakers][0];
+            }
+        }
+        return details;
+    }
     /**
      * Get MIME type for audio format
      */