@juspay/neurolink 13.7.0 → 13.8.1

package/dist/types/transcribe.d.ts

@@ -26,6 +26,7 @@
  *
  * @module types/transcribe
  */
+import type { ZodUnknownSchema } from "./aliases.js";
 import type { TTSAudioFormat } from "./tts.js";
 import type { STTHandler, STTOptions, STTResult, TranscriptionSegment, WordTiming } from "./stt.js";
 /**
@@ -62,32 +63,61 @@ export type STTCorrectionOptions = {
      * `false` disables it (dictionary-only correction). `provider`/`model` name
      * any text provider; the instance default is used when omitted.
      */
-    rewrite?: false | {
+    rewrite?: false | "auto" | {
         provider?: string;
         model?: string;
         /** On expiry the un-rewritten text is kept. Default 12000. */
         timeoutMs?: number;
+        /** `"auto"` (the default) runs the rewrite only when there is something for it to do; `"always"` runs it on every text. */
+        mode?: "auto" | "always";
     };
+    /**
+     * Correct a final utterance sentence by sentence (split on terminal
+     * punctuation and the danda): each sentence decides its own script and
+     * whether it needs the rewrite, and sentences are corrected in parallel.
+     * Default true. A second opinion is whole-utterance and keeps one pass.
+     */
+    perSentence?: boolean;
     /**
      * How Indic-script text is written: `"latin"` the way people type on phones
-     * (Hinglish / Tanglish — the default), `"native"` keeps the script. Never a translation.
+     * (Hinglish / Tanglish), `"native"` keeps the script. Never a translation.
+     * Unset, Indian languages default to `"latin"` and every other language
+     * keeps its own script (Arabic, CJK, Cyrillic … are never romanized unless
+     * asked for). For any other rendering of the text, see `output.languages`.
      */
     transliterate?: "latin" | "native";
     /** Add punctuation and capitalization in the rewrite. Default true. */
     punctuate?: boolean;
+    /**
+     * `"verbatim"` (the default) keeps every word, fillers and stutters
+     * included. `"clean"` lets the rewrite remove fillers ("um", "like" as a
+     * filler) and stutters ("they they they"), never content, and allows the
+     * rewrite to drop up to half the words to do so.
+     */
+    cleanup?: "verbatim" | "clean";
     /**
      * A second engine run on the same audio; the rewrite reconciles both
      * transcripts (Indian-language words from an Indic engine, English words
-     * from an English-oriented one).
+     * from an English-oriented one). `"auto"` uses the `fallback` engine as the
+     * second opinion on every utterance the primary leads, so code-mixed speech
+     * gets both readings without naming a provider twice.
      */
     secondOpinion?: {
         provider: string;
         model?: string;
-    };
+    } | "auto";
     /** One sentence about who is talking and about what; sent to the engines and the guard. */
     context?: string;
     /** A rewrite that drops more than this share of the words is discarded. Default 0.25. */
     maxDropRatio?: number;
+    /**
+     * Corrected utterances before this one that the rewrite sees as read-only
+     * context, so names, spellings and script stay consistent across a
+     * conversation. Streaming and `chunking: "utterances"` only. Default 0
+     * (off): a rewrite may copy context into its answer, which the added-words
+     * guard rejects, so it is opt-in until measured.
+     */
+    contextUtterances?: number;
 };
 /**
  * Where an utterance goes when the primary engine cannot read it. `when`
@@ -99,6 +129,34 @@ export type STTFallbackOptions = {
     model?: string;
     when?: Array<"unsure" | "empty" | "error">;
 };
+/**
+ * How the engines share an utterance. With a `fallback` set, the default is
+ * to probe: the first pass of every utterance runs the primary and the
+ * fallback in parallel, and whichever reads the language leads from then on,
+ * so a sentence in the "wrong" language never waits for the slow takeover.
+ */
+export type STTRoutingOptions = {
+    /**
+     * Streaming: run the fallback engine beside the primary on the first pass
+     * of each utterance and lead with the one that reads the language.
+     * Batch: ask the primary for a language verdict first (its
+     * `languageProbeModel`, when it has one) and transcribe with the engine
+     * that fits. Default: on whenever a fallback is set.
+     */
+    probe?: boolean;
+    /** Streaming: passes both engines keep running before the utterance's engine locks. Default 2. */
+    lockAfterPasses?: number;
+    /** Carry the last confidently detected language into the next utterance's detection (`"carry"`, default) or start each utterance cold (`"none"`). */
+    prior?: "carry" | "none";
+    /**
+     * Which engine transcribes which language: `{ hi: "indic", ta: "indic",
+     * en: "spark", "*": "spark" }`. A final whose detected language belongs to
+     * another engine than the one that produced it is transcribed again by
+     * that engine, and its text is used when it reads the language. `"*"` is
+     * the engine for every language not listed. Values are provider names.
+     */
+    engines?: Record<string, string>;
+};
 /** Client-side streaming for engines without a native stream (and tuning for the adapter). */
 export type STTStreamingOptions = {
     /** `"auto"` uses the handler's native stream when it has one, else the chunked adapter. */
@@ -119,6 +177,84 @@ export type STTStreamingOptions = {
     prerollMs?: number;
     /** Shortest utterance worth a pass. Default 250. */
     minSpeechMs?: number;
+    /**
+     * Engine passes allowed in flight at once. Live streaming keeps 1 (the
+     * default), so a caption never shows a stale pass; the file path
+     * (`chunking: "utterances"`) raises it so utterances are transcribed and
+     * corrected in parallel.
+     */
+    concurrency?: number;
+    /**
+     * Times a failed final pass is tried again before the utterance is
+     * reported as silence. Live streaming keeps 0 (a stale retry would delay
+     * the next utterance); the file path uses 1.
+     */
+    finalRetries?: number;
+    /** Which speech detector finds utterances, and its thresholds. Default: Silero when it loads, else the energy gate. */
+    vad?: STTVadOptions;
+    /**
+     * Raise quiet utterances to a speech level before an engine hears them
+     * (gain only goes up, capped at 8×, peaks limited). Far-field and
+     * low-gain microphones are the usual case. Default true.
+     */
+    normalize?: boolean;
+};
+/**
+ * The detector that decides where utterances start and end in a chunked
+ * stream. `"silero"` is the Silero VAD model (a 2.3 MB ONNX file shipped
+ * with the package, run through the optional `onnxruntime-node`); `"energy"`
+ * is the RMS gate with a noise-floor estimate; `"auto"` (the default) is
+ * Silero when its model and runtime load and the energy gate otherwise.
+ * `NEUROLINK_STT_VAD` sets the default.
+ */
+export type STTVadEngine = "auto" | "silero" | "energy";
+/** Speech-detector choice and tuning (`streaming.vad`). */
+export type STTVadOptions = {
+    engine?: STTVadEngine;
+    /** Speech probability at or above which an utterance may open. Default 0.6. */
+    onset?: number;
+    /** Probability at or above which an open utterance counts a block as speech. Default 0.35. */
+    sustain?: number;
+    /**
+     * Consecutive milliseconds at or above `onset` before an utterance opens,
+     * so a click or a cough does not. Default 120; the pre-roll keeps the
+     * confirmation audio, so nothing is clipped.
+     */
+    startMs?: number;
+    /** Directory holding `silero_vad.onnx`. Default: `NEUROLINK_VAD_DIR`, `NEUROLINK_MODEL_DIR/silero-vad`, the package's own copy, then `~/.neurolink/models/silero-vad`. */
+    modelDir?: string;
+    /** Whether a missing model file may be downloaded (`NEUROLINK_VAD_AUTO_DOWNLOAD`). Default true. */
+    autoDownload?: boolean;
+};
+/**
+ * A frame-level speech detector: `frameSamples` of 16 kHz mono float audio
+ * in, the probability that the frame is speech out. It keeps state across
+ * calls (`reset()` starts a new stream), and one instance serves one stream.
+ */
+export type STTSpeechDetector = {
+    /** Name reported on events (`vad`): `"silero"`, or whatever a caller's own detector calls itself. */
+    readonly name: string;
+    /** Samples per `score()` call at 16 kHz (Silero: 512, 32 ms). */
+    readonly frameSamples: number;
+    score(frame16k: Float32Array): Promise<number> | number;
+    reset(): void;
+};
+/**
+ * The slice of onnxruntime-node's API the Silero detector uses, typed here
+ * so a typecheck does not need the optional dependency installed.
+ */
+export type STTOnnxTensor = {
+    readonly data: Float32Array | BigInt64Array;
+    readonly dims: readonly number[];
+};
+export type STTOnnxSession = {
+    run(feeds: Record<string, STTOnnxTensor>): Promise<Record<string, STTOnnxTensor>>;
+};
+export type STTOnnxRuntime = {
+    InferenceSession: {
+        create(path: string, options?: Record<string, unknown>): Promise<STTOnnxSession>;
+    };
+    Tensor: new (type: "float32" | "int64", data: Float32Array | BigInt64Array, dims: readonly number[]) => STTOnnxTensor;
 };
 /**
  * Options for `neurolink.transcribe()`. `provider` defaults to
@@ -139,11 +275,153 @@ export type TranscribeOptions = Omit<STTOptions, "enabled" | "provider" | "langu
     dictionary?: STTDictionaryEntry[];
     correction?: STTCorrectionOptions;
     fallback?: STTFallbackOptions;
+    routing?: STTRoutingOptions;
     streaming?: STTStreamingOptions;
+    /**
+     * How a recording is cut. `"engine"` (the default) hands the whole file to
+     * the engine in one request. `"utterances"` runs the recording through the
+     * same pipeline as live captions: the endpointer cuts it into utterances,
+     * each utterance gets the language probe, its own engine choice, the
+     * dictionary and the per-sentence correction, several utterances at a
+     * time, and the result carries one segment per utterance with its
+     * language and engine. Needs WAV, or ffmpeg for other containers.
+     */
+    chunking?: "engine" | "utterances";
     /** Whole-call timeout. */
     timeoutMs?: number;
     /** Per-call credentials; the `stt` slice reaches the handlers. */
     credentials?: STTCredentialsCarrier;
+    /** Renderings of the transcript in other languages or scripts (see `STTOutputOptions`). */
+    output?: STTOutputOptions;
+};
+/** A live list of output languages, read once per utterance (a session's subscribers, a socket's control frames). */
+export type STTOutputLanguageSource = {
+    current(): readonly string[];
+};
+/**
+ * Renderings of every utterance in other languages and scripts. Each entry
+ * of `languages` is a BCP-47 tag: `"es"`, `"fr-CA"`, `"ta"` translate;
+ * `"hi-Latn"` is Hindi written in Latin letters (romanized when Hindi was
+ * spoken, translated into Hinglish when something else was); `"source"` is
+ * the transcript itself. One model call renders all of them, from the
+ * native-script transcript and its corrected form, with earlier utterances
+ * as context. A rendering never touches `text`: a failed one is reported with
+ * its status and the transcript is unchanged.
+ */
+export type STTOutputOptions = {
+    languages: readonly string[] | STTOutputLanguageSource;
+    /** Text provider for the rendering; default `NEUROLINK_STT_OUTPUT_PROVIDER`, then the rewrite's. */
+    provider?: string;
+    /** Default `NEUROLINK_STT_OUTPUT_MODEL`, then the rewrite's. */
+    model?: string;
+    /** Per call; on expiry the rendering is reported as `"timeout"`. Default 15000. */
+    timeoutMs?: number;
+    /** Earlier utterances (and their renderings) given as context. Default 3; 0 turns it off. */
+    contextUtterances?: number;
+    /** Keep dictionary terms exactly as written in every language. Default true. */
+    glossary?: boolean;
+};
+export type STTOutputStatus = 
+/** Rendered by the model and accepted by the guards. */
+"ok"
+/** The target is the transcript's own language and script: the corrected text, no model call. */
+ | "same-language" | "timeout" | "error"
+/** The model answered, and the guards refused it (empty, wrong script, untranslated). */
+ | "rejected"
+/** A long transcript where some batches rendered and others did not. */
+ | "partial";
+/** The transcript in one output language. `text` is empty unless the status is `ok`, `same-language` or `partial`. */
+export type STTOutputRendering = {
+    language: string;
+    text: string;
+    status: STTOutputStatus;
+    ms: number;
+    /** Per segment (or utterance), in order, when the transcript has more than one. */
+    segments?: Array<{
+        index: number;
+        text: string;
+    }>;
+    /** Why a rendering was refused or failed. */
+    reason?: string;
+};
+/** One rendering request: lines of one transcript and the targets they go to. */
+export type STTOutputRenderInput = {
+    /** The text as the engine wrote it (native script, dictionary applied), one entry per line. */
+    source: readonly string[];
+    /** The corrected text of the same lines, when correction changed it. */
+    corrected?: readonly string[];
+    /** Detected language of the speech, when known. */
+    language?: string;
+    languages: readonly string[];
+    /** Earlier lines, oldest first, with their renderings per target. */
+    previous?: ReadonlyArray<{
+        text: string;
+        outputs: Record<string, string>;
+    }>;
+    dictionary?: readonly STTDictionaryEntry[];
+    options?: Omit<STTOutputOptions, "languages">;
+};
+/** What one rendering request produced for one target. */
+export type STTOutputBatchOutcome = {
+    lines?: string[];
+    status: STTOutputStatus;
+    reason?: string;
+};
+/** One aligned position of two readings: a word from either side, or both when they line up. */
+export type STTWordPair = {
+    /** The Indic engine's word (native script). */
+    indic?: string;
+    /** The English-oriented engine's word. */
+    latin?: string;
+    /** Both present and phonetically alike: the speaker said the same thing in both readings. */
+    alike: boolean;
+};
+/** How two readings of one utterance relate (see `analyzeCodeMix`). */
+export type STTCodeMixAnalysis = {
+    /** Share of the Indic reading's words with a phonetic partner in the English reading (0–1). */
+    englishShare: number;
+    /** Words in the Indic reading. */
+    words: number;
+    pairs: STTWordPair[];
+};
+/** ISO 15924 scripts the output guards recognise. */
+export type ScriptCode = "Latn" | "Deva" | "Beng" | "Guru" | "Gujr" | "Orya" | "Taml" | "Telu" | "Knda" | "Mlym" | "Sinh" | "Arab" | "Cyrl" | "Grek" | "Hebr" | "Thai" | "Hang" | "Jpan" | "Hani" | "Geor" | "Armn" | "Ethi";
+/** One output target, parsed: `"hi-Latn"` → `{ language: "hi", script: "Latn" }`. */
+export type ParsedOutputTag = {
+    tag: string;
+    language: string;
+    /** The script the text must be written in: the subtag, else the language's own. */
+    script: ScriptCode;
+    /** True when the tag names a script (`hi-Latn`), not just a language. */
+    explicitScript: boolean;
+};
+export type TranscriptionSessionOptions = {
+    id?: string;
+    /** Utterances kept for listeners who join late. Default 50. */
+    backlog?: number;
+    /** Distinct output languages a session renders at once. Default 8. */
+    maxLanguages?: number;
+    /** Rendering settings shared by every speaker; the languages come from the listeners. */
+    output?: Omit<STTOutputOptions, "languages">;
+};
+/** A stream event from one speaker of a session. */
+export type TranscriptionSessionEvent = TranscribeStreamEvent & {
+    speaker: string;
+};
+export type TranscriptionSubscriberOptions = {
+    /** Output languages this listener reads. Empty: the transcript only. */
+    languages?: readonly string[];
+    /** Speakers to follow; omitted, every speaker. */
+    speakers?: readonly string[];
+    /** Replay the backlog on subscribe. Default true. */
+    backlog?: boolean;
+    /** Also deliver `interim` captions. Default true. */
+    interim?: boolean;
+};
+export type TranscriptionSubscription = {
+    readonly languages: readonly string[];
+    update(options: Pick<TranscriptionSubscriberOptions, "languages" | "speakers">): void;
+    close(): void;
 };
 /** `transcribeStream()` takes frames instead of a whole buffer. */
 export type TranscribeStreamOptions = Omit<TranscribeOptions, "audio"> & {
@@ -189,6 +467,8 @@ export type TranscribeTimings = {
     decideMs?: number;
     rewriteMs?: number;
     correctionMs?: number;
+    /** Rendering into the output languages. */
+    outputMs?: number;
     totalMs: number;
 };
 /** The result of `transcribe()`: an `STTResult` plus what the layers did to it. */
@@ -205,6 +485,8 @@ export type TranscribeResult = STTResult & {
     timings: TranscribeTimings;
     /** Human-readable trail of what happened ("dictionary 2/2", "rewrite timed out · kept text"). */
     steps: string[];
+    /** One rendering per `output.languages` entry, keyed by the tag as given. */
+    outputs?: Record<string, STTOutputRendering>;
 };
 export type TranscribeStreamEvent = {
     type: "interim";
@@ -235,6 +517,19 @@ export type TranscribeStreamEvent = {
     engine: string;
     fallbackUsed?: boolean;
     seconds: number;
+    /** The detector that found this utterance: `"silero"`, `"energy"`, or a caller's own. */
+    vad?: string;
+    /** Seconds the detector counted as speech inside the utterance. */
+    speechSeconds?: number;
+    /**
+     * The other engine's reading of the same utterance, when the two
+     * disagreed on its language and the final ran both: code-mixed speech
+     * is reconciled from both readings (`secondOpinion: "auto"`).
+     */
+    alternative?: {
+        engine: string;
+        text: string;
+    };
 } | {
     /** Partial text of the streamed rewrite, in order. */
     type: "correcting";
@@ -248,11 +543,26 @@ export type TranscribeStreamEvent = {
     decisions: STTDecisionRecord[];
     steps: string[];
     timings: TranscribeTimings;
+} | {
+    /**
+     * The utterance in one output language. Follows `corrected` when
+     * correction runs (`basedOn: "corrected"`), else the `final`.
+     */
+    type: "output";
+    utterance: number;
+    language: string;
+    text: string;
+    status: STTOutputStatus;
+    basedOn: "final" | "corrected";
+    ms: number;
+    reason?: string;
 } | {
     /** An utterance no engine could read; its audio length is reported so nothing disappears silently. */
     type: "silence";
     utterance: number;
     seconds: number;
+    vad?: string;
+    speechSeconds?: number;
 } | {
     type: "error";
     utterance?: number;
@@ -260,6 +570,18 @@ export type TranscribeStreamEvent = {
     /** `true` when the stream continues with the next utterance. */
     recoverable: boolean;
 };
+/** The `final` event of a stream, as a named type for code that collects them. */
+export type TranscribeStreamFinalEvent = Extract<TranscribeStreamEvent, {
+    type: "final";
+}>;
+/** The `corrected` event of a stream. */
+export type TranscribeStreamCorrectedEvent = Extract<TranscribeStreamEvent, {
+    type: "corrected";
+}>;
+/** The `output` event of a stream. */
+export type TranscribeStreamOutputEvent = Extract<TranscribeStreamEvent, {
+    type: "output";
+}>;
 /**
  * One OpenAI-compatible `/audio/transcriptions` endpoint registered under a
  * name of its own, so several self-hosted engines can be told apart — and
@@ -271,6 +593,22 @@ export type STTEndpointConfig = {
     apiKey?: string;
     model?: string;
     timeoutMs?: number;
+    /**
+     * How this server takes a language prior in its `language` field, as a
+     * template with `{lang}` (the IndicConformer wrapper: `"auto-{lang}"`).
+     * Unset, no prior is ever sent: a server that does not understand one
+     * would refuse the request.
+     */
+    priorLanguageForm?: string;
+    /** A model name this server runs in language-identification-only mode (see `STTHandler.languageProbeModel`). */
+    lidModel?: string;
+    /**
+     * Whether the dictionary terms travel to this server as a "Names and
+     * terms used: …" prompt. Whisper biases on it; Qwen3-ASR and most others
+     * ignore it and some echo it back on a pause. Default `true`; set `false`
+     * for a server that echoes it.
+     */
+    vocabularyPrompt?: boolean;
 };
 /** Credential slices for STT handlers; `credentials.stt.<key>` beats the env var. */
 export type STTCredentials = {
@@ -281,6 +619,12 @@ export type STTCredentials = {
         timeoutMs?: number;
         /** Default model name sent to the endpoint (`whisper-1` when omitted). */
         model?: string;
+        /** See `STTEndpointConfig.priorLanguageForm`. Env: `OPENAI_STT_PRIOR_LANGUAGE_FORM`. */
+        priorLanguageForm?: string;
+        /** See `STTEndpointConfig.lidModel`. Env: `OPENAI_STT_LID_MODEL`. */
+        lidModel?: string;
+        /** See `STTEndpointConfig.vocabularyPrompt`. Env: `OPENAI_STT_VOCABULARY_PROMPT`. */
+        vocabularyPrompt?: boolean;
     };
     /**
      * Extra OpenAI-compatible endpoints, each registered as a provider under
@@ -366,6 +710,19 @@ export type STTCorrectionDeps = {
         timeoutMs: number;
         onPartial?: (text: string) => void;
     }) => Promise<string>;
+    /**
+     * A structured text call for output rendering: the parsed object the
+     * schema describes. Absent, renderings report `"error"`.
+     */
+    render?: (opts: {
+        system: string;
+        user: string;
+        schema: ZodUnknownSchema;
+        provider?: string;
+        model?: string;
+        maxTokens: number;
+        timeoutMs: number;
+    }) => Promise<unknown>;
 };
 /** Input to the correction layer, independent of where the text came from. */
 export type STTCorrectionInput = {
@@ -376,6 +733,10 @@ export type STTCorrectionInput = {
     options?: STTCorrectionOptions;
     /** `false` when the primary engine reported a low language score: the second opinion then leads. */
     languageDetected?: boolean;
+    /** Detected language of the speech; picks the rewrite's rules and script default. */
+    language?: string;
+    /** Corrected utterances before this one, oldest first: read-only context for the rewrite. */
+    previous?: readonly string[];
     onPartial?: (text: string) => void;
 };
 /** A dictionary alias found in a transcript: a candidate substitution for the guard to judge. */
@@ -387,7 +748,7 @@ export type STTDictionaryCandidate = {
 /** What one rewrite call did; `text` is always usable (the input when the rewrite was not kept). */
 export type STTRewriteOutcome = {
     text: string;
-    status: "ok" | "timeout" | "error" | "empty" | "dropped";
+    status: "ok" | "timeout" | "error" | "empty" | "dropped" | "added";
     ms: number;
     /** Share of words the rewrite dropped, when `status` is `"dropped"`. */
     dropRatio?: number;
@@ -432,6 +793,24 @@ export type STTEndpointerConfig = {
     prerollMs: number;
     minSpeechMs: number;
 };
+/**
+ * A speech detector's verdicts as the endpointer reads them: the thresholds
+ * and a lookup of the probability at a point on the stream clock. Attached,
+ * it replaces the RMS rules; the energy gate stays as the fallback.
+ */
+export type STTEndpointerSpeechConfig = {
+    onset: number;
+    sustain: number;
+    startMs: number;
+    /** Speech probability of the frame covering `seconds`; `undefined` before the first scored frame. */
+    probabilityAt(seconds: number): number | undefined;
+};
+/** One block waiting in the endpointer's pre-roll: its samples, RMS and speech probability. */
+export type STTEndpointerPreBlock = {
+    block: Float32Array;
+    rms: number;
+    speech: number;
+};
 /** One utterance as the energy gate builds it, at the input rate. */
 export type STTEndpointerUtterance = {
     /** 1-based, in order of onset. A dropped cough consumes an id, so ids can skip. */
@@ -442,6 +821,8 @@ export type STTEndpointerUtterance = {
     blocks: Float32Array[];
     /** RMS of each block, parallel to `blocks`. */
     rms: number[];
+    /** Speech probability of each block, parallel to `blocks`, when a detector is attached. */
+    speech?: number[];
     /** Total samples in `blocks`. */
     length: number;
     speechMs: number;
@@ -485,6 +866,14 @@ export type STTChunkedPassOptions = {
     engine: STTStreamEngineRole;
     /** Audio length of the utterance so far. */
     seconds: number;
+    /** The last confidently detected language of this stream, for engines that take a prior. */
+    languagePrior?: string;
+    /**
+     * Transcribe in this language rather than detecting one: set on the
+     * fallback role once the utterance (or the stream) is settled as that
+     * language, so a short pass cannot drift into another script.
+     */
+    languageHint?: string;
 };
 /** One engine pass over a whole utterance, 16 kHz mono float samples in. */
 export type STTChunkedRun = (pcm16k: Float32Array, options: STTChunkedPassOptions) => Promise<STTResult>;
@@ -497,6 +886,13 @@ export type STTChunkedStreamOptions = STTStreamingOptions & {
         label: string;
         when?: STTFallbackOptions["when"];
     };
+    /** Probe, lock and prior behaviour (see `STTRoutingOptions`); the defaults apply when omitted. */
+    routing?: STTRoutingOptions;
+    /**
+     * A speech detector of the caller's own, used instead of what `vad`
+     * would load; `null` keeps the energy gate. Omitted, `vad` decides.
+     */
+    speechDetector?: STTSpeechDetector | null;
     /**
      * Called once per utterance, synchronously, when it ends and before its
      * final pass is queued, with the utterance audio at 16 kHz and the role

package/dist/voice/audioLevel.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Speech level for the engines: a quiet utterance (a far-field speaker, a
+ * low-gain microphone) is raised to a normal speech level before an engine
+ * hears it. Recognisers are trained on speech near -20 dBFS and lose words,
+ * and language-ID confidence, well below it.
+ *
+ * Gain only ever goes up, is capped, and is limited by the peak so nothing
+ * clips; digital silence stays silence (zero times any gain is zero), so the
+ * silence pad an engine relies on is untouched.
+ *
+ * @module voice/audioLevel
+ */
+/** `pcm` with its speech raised to the target level, or `pcm` itself when it is loud enough already. */
+export declare function normalizeSpeechLevel(pcm: Float32Array): Float32Array;

package/dist/voice/audioLevel.js

@@ -0,0 +1,60 @@
+/**
+ * Speech level for the engines: a quiet utterance (a far-field speaker, a
+ * low-gain microphone) is raised to a normal speech level before an engine
+ * hears it. Recognisers are trained on speech near -20 dBFS and lose words,
+ * and language-ID confidence, well below it.
+ *
+ * Gain only ever goes up, is capped, and is limited by the peak so nothing
+ * clips; digital silence stays silence (zero times any gain is zero), so the
+ * silence pad an engine relies on is untouched.
+ *
+ * @module voice/audioLevel
+ */
+/** RMS the speech is raised to: about -22 dBFS. */
+const TARGET_SPEECH_RMS = 0.08;
+/** Most gain applied to any utterance. */
+const MAX_GAIN = 8;
+/** Peak after gain; leaves headroom for the engine's own resampling. */
+const PEAK_LIMIT = 0.95;
+/** Blocks quieter than this do not count as speech when measuring the level. */
+const SPEECH_FLOOR_RMS = 0.002;
+/** 20 ms at 16 kHz. */
+const BLOCK = 320;
+/** Gain below this is not worth a copy of the audio. */
+const MIN_USEFUL_GAIN = 1.1;
+/** `pcm` with its speech raised to the target level, or `pcm` itself when it is loud enough already. */
+export function normalizeSpeechLevel(pcm) {
+    let sum = 0;
+    let count = 0;
+    let peak = 0;
+    for (let at = 0; at < pcm.length; at += BLOCK) {
+        const end = Math.min(pcm.length, at + BLOCK);
+        let block = 0;
+        for (let i = at; i < end; i++) {
+            const v = pcm[i];
+            block += v * v;
+            const a = Math.abs(v);
+            if (a > peak) {
+                peak = a;
+            }
+        }
+        const rms = Math.sqrt(block / Math.max(1, end - at));
+        if (rms >= SPEECH_FLOOR_RMS) {
+            sum += block;
+            count += end - at;
+        }
+    }
+    if (count === 0 || peak === 0) {
+        return pcm;
+    }
+    const speechRms = Math.sqrt(sum / count);
+    const gain = Math.min(MAX_GAIN, TARGET_SPEECH_RMS / speechRms, PEAK_LIMIT / peak);
+    if (!(gain >= MIN_USEFUL_GAIN)) {
+        return pcm;
+    }
+    const out = new Float32Array(pcm.length);
+    for (let i = 0; i < pcm.length; i++) {
+        out[i] = pcm[i] * gain;
+    }
+    return out;
+}

package/dist/voice/codeMix.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Code-mix analysis between two engines' readings of the same speech.
+ *
+ * An Indic engine writes English words phonetically in its own script
+ * ("मीटिंग" for "meeting"); an English-oriented engine writes Indian-language
+ * words as English-sounding guesses ("page dinner" for "भेज देना"). Brought
+ * to one rough phonetic form — Indic text romanized, both reduced to a
+ * consonant skeleton with voicing and aspiration folded — the two sequences
+ * line up word for word wherever the speaker spoke English, and stop lining
+ * up where they spoke an Indian language. The share of the Indic engine's
+ * words that find a phonetic partner is therefore an estimate of how much of
+ * the utterance was English, independent of either engine's own (accent-
+ * sensitive) language score; the alignment itself is what a word-level
+ * combination of the two readings is built on.
+ *
+ * @module voice/codeMix
+ */
+import type { STTCodeMixAnalysis, STTWordPair } from "../types/index.js";
+/** Indic-script text in rough Latin letters; anything else passes through. */
+export declare function romanizeIndic(text: string): string;
+/**
+ * A word's consonant skeleton: digraphs folded, voicing pairs merged
+ * (t/d, k/g, p/b are where an accent and a script disagree most), vowels and
+ * h dropped, repeats collapsed. "meeting" and "मीटिंग" both give "mtnk".
+ */
+export declare function phoneticKey(word: string): string;
+/** Whether two skeletons sound alike: equal, or one edit apart on three or more consonants (two on six). */
+export declare function soundsAlike(a: string, b: string): boolean;
+/**
+ * Align two readings word by word (Needleman–Wunsch on skeletons): a pair
+ * for every word of either side, matched where the words sound alike.
+ */
+export declare function alignReadings(indic: readonly string[], latin: readonly string[]): STTWordPair[];
+/**
+ * How much of an utterance two readings agree is English: the share of the
+ * Indic engine's words with a phonetic partner in the English-oriented
+ * engine's text. Near 1 for English an Indic engine wrote phonetically; well
+ * under it for code-mixed speech, where the Indian-language words find none.
+ */
+export declare function analyzeCodeMix(indicText: string, latinText: string): STTCodeMixAnalysis;