@juspay/neurolink 13.7.0 → 13.8.1

package/dist/voice/transcribe.js

@@ -15,16 +15,63 @@
 import { promises as fs } from "fs";
 import { extname } from "path";
 import { fileURLToPath } from "url";
+import { guardEngineResult, promptTermsOf, runTranscribeStream, } from "./transcribeStream.js";
+import { ENGINE_SAMPLE_RATE } from "./streaming/endpointer.js";
+import { alignWordsToText } from "./correction/align.js";
+import { normalizeLanguageCode } from "./languages.js";
+import { outputLanguagesOf, renderOutputs } from "./output/render.js";
 import { logger } from "../utils/logger.js";
 import { SpanSerializer, SpanStatus, SpanType, getMetricsAggregator, } from "../observability/index.js";
 import { detectAudioFormat } from "./audio-utils.js";
-import { correctTranscript, correctTranscriptLines, isCorrectionEnabled, } from "./correction/index.js";
+import { correctTranscript, correctTranscriptLines, correctTranscriptSentences, isCorrectionEnabled, } from "./correction/index.js";
+import { STTError } from "./errors.js";
+/** Audio the language probe gets to hear; a verdict needs a few seconds, not the file. */
+const PROBE_SECONDS = 8;
+/**
+ * The first `seconds` of a PCM WAV as a smaller WAV, so a language probe
+ * uploads kilobytes instead of the whole recording. Anything that is not a
+ * plain RIFF/WAVE with a readable `fmt ` and `data` chunk is returned as is.
+ */
+export function wavHead(buffer, seconds) {
+    if (buffer.length < 44 ||
+        buffer.toString("ascii", 0, 4) !== "RIFF" ||
+        buffer.toString("ascii", 8, 12) !== "WAVE") {
+        return buffer;
+    }
+    let offset = 12;
+    let byteRate = 0;
+    let blockAlign = 0;
+    while (offset + 8 <= buffer.length) {
+        const id = buffer.toString("ascii", offset, offset + 4);
+        const size = buffer.readUInt32LE(offset + 4);
+        const body = offset + 8;
+        if (id === "fmt " && body + 16 <= buffer.length) {
+            byteRate = buffer.readUInt32LE(body + 8);
+            blockAlign = buffer.readUInt16LE(body + 12);
+        }
+        else if (id === "data") {
+            if (!byteRate || !blockAlign) {
+                return buffer;
+            }
+            const available = Math.min(size, buffer.length - body);
+            const wanted = Math.floor((byteRate * seconds) / blockAlign) * blockAlign;
+            if (available <= wanted) {
+                return buffer;
+            }
+            const head = Buffer.from(buffer.subarray(0, body + wanted));
+            head.writeUInt32LE(head.length - 8, 4);
+            head.writeUInt32LE(wanted, offset + 4);
+            return head;
+        }
+        offset = body + size + (size % 2);
+    }
+    return buffer;
+}
 /** `NEUROLINK_STT_CORRECT_WHOLE=1` forces one whole-transcript rewrite even for segmented results. */
 function correctionLinesDisabled() {
     const v = process.env.NEUROLINK_STT_CORRECT_WHOLE?.trim().toLowerCase();
     return v === "1" || v === "true";
 }
-import { STTError } from "./errors.js";
 /** Default timeout for fetching an `http(s)://` audio input. */
 const URL_FETCH_TIMEOUT_MS = 60_000;
 /** Container names an extension or magic number can map to. */
@@ -190,7 +237,7 @@ function mergeVocabulary(vocabulary, dictionary) {
  * the correction context rides along in the prompt for engines that take one.
  */
 export function buildEngineOptions(options, format, model) {
-    const { provider: _provider, model: _model, language, format: _format, prompt, dictionary, correction, fallback: _fallback, streaming: _streaming, credentials: _credentials, vocabulary, ...rest } = options;
+    const { provider: _provider, model: _model, language, format: _format, prompt, dictionary, correction, fallback: _fallback, routing: _routing, chunking: _chunking, output: _output, streaming: _streaming, credentials: _credentials, vocabulary, ...rest } = options;
     const contextPrompt = [prompt?.trim(), correction?.context?.trim()]
         .filter((part) => !!part)
         .join(" ");
@@ -288,6 +335,243 @@ export async function runTranscribe(options, deps) {
         throw error;
     }
 }
+/** 100 ms of 16 kHz PCM16 per frame when a recording is replayed through the live pipeline. */
+const UTTERANCE_FRAME_BYTES = 3200;
+/** Finals in flight at once on the file path when the caller sets no `streaming.concurrency`. */
+const DEFAULT_FILE_CONCURRENCY = 3;
+/** Per-engine-call timeout on the file path when the caller sets none. */
+const FILE_ENGINE_TIMEOUT_MS = 180_000;
+/** File-mode utterance cuts: shorter than live, so a long-form engine stays in its comfortable range and more utterances run in parallel. */
+const FILE_MAX_UTTERANCE_SECONDS = 20;
+const FILE_SOFT_CUT_SECONDS = 12;
+/**
+ * The stream options a recording gets when it goes through the live
+ * pipeline, whether by `chunking: "utterances"` or over the WebSocket with
+ * `mode: "file"`: no interim passes, several utterances at a time, one retry
+ * of a failed final, file-sized engine timeouts and shorter cuts. Anything
+ * the caller set explicitly is kept.
+ */
+export function fileModeStreamOptions(options) {
+    return {
+        ...options,
+        streaming: {
+            ...options.streaming,
+            // No interim passes on a file: an infinite cadence disables them.
+            intervalMs: Number.POSITIVE_INFINITY,
+            concurrency: options.streaming?.concurrency ?? DEFAULT_FILE_CONCURRENCY,
+            finalRetries: options.streaming?.finalRetries ?? 1,
+            maxUtteranceSeconds: options.streaming?.maxUtteranceSeconds ?? FILE_MAX_UTTERANCE_SECONDS,
+            softCutSeconds: options.streaming?.softCutSeconds ?? FILE_SOFT_CUT_SECONDS,
+        },
+        // Engines get a file-sized timeout: an utterance may be 20 s of audio on
+        // a busy gateway, and the live default (30 s) is cut for captions.
+        timeoutMs: options.timeoutMs ?? FILE_ENGINE_TIMEOUT_MS,
+    };
+}
+/**
+ * The file path that behaves like live captions: the recording is cut into
+ * utterances by the endpointer, every utterance gets the language probe and
+ * its own engine, the dictionary and the per-sentence correction, several
+ * utterances at a time, and the result has one segment per utterance. No
+ * interim passes are run; the stream is fed as fast as the engines take it.
+ */
+async function transcribeUtterances(buffer, format, options, deps, startedAt) {
+    const { decodeToWhistlePcm } = await import("./whistle/audio.js");
+    const samples = await decodeToWhistlePcm(buffer, format, ENGINE_SAMPLE_RATE);
+    const pcm = Buffer.alloc(samples.length * 2);
+    for (let i = 0; i < samples.length; i++) {
+        pcm.writeInt16LE(Math.round(Math.max(-1, Math.min(1, samples[i])) * 32767), i * 2);
+    }
+    const duration = samples.length / ENGINE_SAMPLE_RATE;
+    async function* frames() {
+        for (let at = 0; at < pcm.length; at += UTTERANCE_FRAME_BYTES) {
+            yield pcm.subarray(at, Math.min(pcm.length, at + UTTERANCE_FRAME_BYTES));
+            await new Promise((resolve) => setImmediate(resolve));
+        }
+    }
+    const { audio: _audio, chunking: _chunking, format: _format, ...rest } = options;
+    const provider = deps.resolveProvider(options.provider);
+    const fileOptions = fileModeStreamOptions(rest);
+    const events = runTranscribeStream({
+        ...fileOptions,
+        audio: frames(),
+        streaming: {
+            ...fileOptions.streaming,
+            mode: "chunked",
+            sampleRate: ENGINE_SAMPLE_RATE,
+        },
+    }, deps);
+    const finals = new Map();
+    const corrections = new Map();
+    const outputEvents = new Map();
+    let lastOutputAt = startedAt;
+    const silences = [];
+    const errors = [];
+    let lastFinalAt = startedAt;
+    let lastCorrectedAt = startedAt;
+    let fatal;
+    for await (const ev of events) {
+        if (ev.type === "final") {
+            finals.set(ev.utterance, ev);
+            lastFinalAt = Date.now();
+        }
+        else if (ev.type === "corrected") {
+            corrections.set(ev.utterance, ev);
+            lastCorrectedAt = Date.now();
+        }
+        else if (ev.type === "output") {
+            const byUtterance = outputEvents.get(ev.language) ?? new Map();
+            byUtterance.set(ev.utterance, ev);
+            outputEvents.set(ev.language, byUtterance);
+            lastOutputAt = Date.now();
+        }
+        else if (ev.type === "silence") {
+            silences.push({ utterance: ev.utterance, seconds: ev.seconds });
+        }
+        else if (ev.type === "error") {
+            errors.push(ev.message);
+            if (!ev.recoverable) {
+                fatal = ev.message;
+            }
+        }
+    }
+    // The same contract as a whole-file call: an engine that could not run is
+    // an error, not an empty transcript.
+    const nothingRead = finals.size === 0 && errors.length > 0;
+    if (fatal !== undefined || nothingRead) {
+        throw STTError.transcriptionFailed(fatal ?? errors[errors.length - 1] ?? "every utterance failed", provider);
+    }
+    const ids = [...finals.keys()].sort((a, b) => a - b);
+    const segments = ids.map((id, index) => {
+        const f = finals.get(id);
+        const c = corrections.get(id);
+        return {
+            ...f.segment,
+            index,
+            text: c?.text.trim() ? c.text : f.text,
+            isFinal: true,
+            ...(f.language ? { language: f.language } : {}),
+        };
+    });
+    const raw = ids
+        .map((id) => finals.get(id)?.text ?? "")
+        .filter(Boolean)
+        .join(" ");
+    const text = segments
+        .map((seg) => seg.text)
+        .filter(Boolean)
+        .join(" ");
+    const decisions = ids.flatMap((id) => corrections.get(id)?.decisions ?? []);
+    const handedOver = ids.filter((id) => finals.get(id)?.fallbackUsed).length;
+    const fallbackProvider = handedOver
+        ? (ids.map((id) => finals.get(id)).find((f) => f?.fallbackUsed)?.engine ??
+            options.fallback?.provider)
+        : undefined;
+    const languages = ids
+        .map((id) => finals.get(id)?.language)
+        .filter((l) => !!l && l !== "und");
+    const language = languages.length
+        ? [...new Set(languages)].sort((a, b) => languages.filter((l) => l === b).length -
+            languages.filter((l) => l === a).length)[0]
+        : undefined;
+    const unsure = ids.some((id) => finals.get(id)?.languageDetected === false &&
+        !finals.get(id)?.fallbackUsed);
+    const anyDetected = ids.some((id) => finals.get(id)?.languageDetected !== undefined);
+    const steps = [
+        `transcribed ${provider} per utterance (${ids.length} utterance${ids.length === 1 ? "" : "s"}${handedOver ? `, ${handedOver} by ${fallbackProvider}` : ""})`,
+        ...(silences.length
+            ? [
+                `${silences.length} utterance(s) no engine could read (${silences.map((g) => `${g.seconds.toFixed(1)} s`).join(", ")}), reported as silence`,
+            ]
+            : []),
+        ...(corrections.size
+            ? [`corrected ${corrections.size}/${ids.length} utterances`]
+            : []),
+        ...(errors.length ? [`${errors.length} recoverable error(s)`] : []),
+    ];
+    const decideMs = sumTimings(corrections, "decideMs");
+    const rewriteMs = sumTimings(corrections, "rewriteMs");
+    const outputs = collectUtteranceOutputs(outputLanguagesOf(options.output), ids, outputEvents);
+    if (outputs) {
+        steps.push(describeOutputs(outputs));
+    }
+    const result = {
+        text,
+        confidence: 0,
+        ...(language ? { language } : {}),
+        duration,
+        segments,
+        raw,
+        ...(text !== raw ? { corrected: text } : {}),
+        ...(anyDetected ? { languageDetected: !unsure } : {}),
+        ...(decisions.length ? { decisions } : {}),
+        engine: {
+            provider,
+            ...(handedOver ? { fallbackUsed: true } : {}),
+        },
+        timings: {
+            transcribeMs: lastFinalAt - startedAt,
+            ...(decideMs !== undefined ? { decideMs } : {}),
+            ...(rewriteMs !== undefined ? { rewriteMs } : {}),
+            ...(corrections.size
+                ? { correctionMs: Math.max(0, lastCorrectedAt - lastFinalAt) }
+                : {}),
+            ...(outputs
+                ? { outputMs: Math.max(0, lastOutputAt - lastCorrectedAt) }
+                : {}),
+            totalMs: Date.now() - startedAt,
+        },
+        steps,
+        ...(outputs ? { outputs } : {}),
+    };
+    return result;
+}
+/** One rendering per language from the per-utterance `output` events, in utterance order. */
+function collectUtteranceOutputs(languages, ids, events) {
+    if (languages.length === 0) {
+        return undefined;
+    }
+    const out = {};
+    for (const tag of languages) {
+        const byUtterance = events.get(tag) ?? new Map();
+        const parts = ids.map((id) => byUtterance.get(id));
+        const good = parts.filter((p) => p && (p.status === "ok" || p.status === "same-language"));
+        const failure = parts.find((p) => p && p.status !== "ok" && p.status !== "same-language");
+        const status = good.length === ids.length
+            ? good.every((p) => p?.status === "same-language")
+                ? "same-language"
+                : "ok"
+            : good.length > 0
+                ? "partial"
+                : (failure?.status ?? "error");
+        out[tag] = {
+            language: tag,
+            text: parts
+                .map((p) => p?.text ?? "")
+                .filter(Boolean)
+                .join(" "),
+            status,
+            ms: Math.max(0, ...parts.map((p) => p?.ms ?? 0)),
+            segments: parts.map((p, index) => ({ index, text: p?.text ?? "" })),
+            ...(status !== "ok" && status !== "same-language" && failure?.reason
+                ? { reason: failure.reason }
+                : {}),
+        };
+    }
+    return out;
+}
+/** "outputs es ok · fr timeout" */
+function describeOutputs(outputs) {
+    return `outputs ${Object.values(outputs)
+        .map((o) => `${o.language} ${o.status}`)
+        .join(" · ")}`;
+}
+function sumTimings(corrections, key) {
+    const values = [...corrections.values()]
+        .map((c) => c.timings[key])
+        .filter((v) => typeof v === "number");
+    return values.length ? values.reduce((a, b) => a + b, 0) : undefined;
+}
 async function transcribeLayers(options, deps, startedAt) {
     const steps = [];
     // 1. Audio, and its container when the caller did not name one.
@@ -296,6 +580,9 @@ async function transcribeLayers(options, deps, startedAt) {
         throw STTError.audioEmpty(options.provider);
     }
     const format = options.format ?? formatHint ?? audioFormatFromBytes(buffer);
+    if (options.chunking === "utterances") {
+        return transcribeUtterances(buffer, format, options, deps, startedAt);
+    }
     // 2. Engines. A model from the environment only applies to the provider
     // the environment picked; an explicit provider gets only an explicit model.
     const explicitProvider = !!options.provider?.trim();
@@ -307,8 +594,13 @@ async function transcribeLayers(options, deps, startedAt) {
         language: options.language ?? process.env.NEUROLINK_STT_LANGUAGE,
     };
     const optionsFor = (model) => buildEngineOptions(engineBase, format, model);
-    // 3. Primary and second opinion, in parallel.
-    const secondOpinionSpec = options.correction?.secondOpinion;
+    // 3. Primary and second opinion, in parallel. "auto" names the fallback.
+    const secondSetting = options.correction?.secondOpinion;
+    const secondOpinionSpec = secondSetting === "auto"
+        ? options.fallback
+            ? { provider: options.fallback.provider, model: options.fallback.model }
+            : undefined
+        : secondSetting;
     const secondProvider = secondOpinionSpec
         ? deps.resolveProvider(secondOpinionSpec.provider)
         : undefined;
@@ -324,13 +616,59 @@ async function transcribeLayers(options, deps, startedAt) {
     const fallbackProvider = fallback
         ? deps.resolveProvider(fallback.provider)
         : undefined;
+    // 3b. Language probe. With a fallback and no pinned language, an engine
+    // that can answer "which language is this" without transcribing (its
+    // `languageProbeModel`) is asked first, in a fraction of a full pass. When
+    // it is unsure, the fallback transcribes instead of the primary, so an
+    // English recording never pays for a full Indic pass that would come back
+    // as noise; the primary still runs if the fallback has nothing.
+    let probed;
+    const pinnedLanguage = typeof engineBase.language === "string" &&
+        engineBase.language.trim() !== "" &&
+        engineBase.language.trim().toLowerCase() !== "auto";
+    // The verdict only matters when an unsure primary hands over.
+    const probeModel = fallbackProvider &&
+        fallbackWhen.has("unsure") &&
+        options.routing?.probe !== false &&
+        !pinnedLanguage
+        ? deps.getHandler(provider)?.languageProbeModel?.()
+        : undefined;
+    if (probeModel && fallbackProvider !== provider) {
+        const probeStarted = Date.now();
+        try {
+            const verdict = await deps.transcribe(wavHead(buffer, PROBE_SECONDS), provider, optionsFor(probeModel));
+            const detected = readLanguageDetected(verdict);
+            probed = detected === false ? "unsure" : "confident";
+            steps.push(`language probe ${probed}${verdict.language ? ` (${verdict.language})` : ""} · ${Date.now() - probeStarted} ms`);
+        }
+        catch (error) {
+            steps.push("language probe failed · transcribing with the primary");
+            if (logger.shouldLog("debug")) {
+                logger.debug(`[transcribe] language probe failed: ${errorMessage(error)}`);
+            }
+        }
+    }
     let primary;
     let primaryError;
-    try {
-        primary = await deps.transcribe(buffer, provider, optionsFor(primaryModel));
+    let probedFallback;
+    if (probed === "unsure" && fallbackProvider && fallbackWhen.has("unsure")) {
+        try {
+            probedFallback = await deps.transcribe(buffer, fallbackProvider, optionsFor(fallback?.model));
+        }
+        catch (error) {
+            steps.push(`fallback ${fallbackProvider} failed · trying the primary`);
+            if (logger.shouldLog("debug")) {
+                logger.debug(`[transcribe] probed fallback ${fallbackProvider} failed: ${errorMessage(error)}`);
+            }
+        }
     }
-    catch (error) {
-        primaryError = error;
+    if (!probedFallback?.text.trim()) {
+        try {
+            primary = await deps.transcribe(buffer, provider, optionsFor(primaryModel));
+        }
+        catch (error) {
+            primaryError = error;
+        }
     }
     // 4. Fallback: on error, on an empty transcript, or when the engine said
     // it could not identify the language — whichever `when` asks for.
@@ -349,7 +687,14 @@ async function transcribeLayers(options, deps, startedAt) {
                 fallbackWhen.has("unsure")
                 ? "unsure"
                 : undefined;
-    if (fallback && fallbackProvider && fallbackReason) {
+    if (probedFallback?.text.trim() && fallbackProvider) {
+        chosen = probedFallback;
+        chosenProvider = fallbackProvider;
+        chosenModel = fallback?.model;
+        fallbackUsed = true;
+        steps.push(`fallback ${fallbackProvider} (probe said unsure)`);
+    }
+    else if (fallback && fallbackProvider && fallbackReason) {
         if (fallbackProvider === provider && fallback.model === primaryModel) {
             steps.push(`fallback skipped · same engine as primary`);
         }
@@ -375,6 +720,46 @@ async function transcribeLayers(options, deps, startedAt) {
             }
         }
     }
+    // 4b. Language routing: a transcript whose language belongs to another
+    // engine is read again by that engine, and kept when it reads the language.
+    const routes = options.routing?.engines;
+    const chosenLanguage = chosen
+        ? normalizeLanguageCode(chosen.language)
+        : undefined;
+    if (chosen && routes && chosenLanguage && !pinnedLanguage) {
+        const routeName = Object.entries(routes).find(([lang]) => normalizeLanguageCode(lang) === chosenLanguage)?.[1] ?? routes["*"];
+        let target;
+        try {
+            target = routeName ? deps.resolveProvider(routeName) : undefined;
+        }
+        catch {
+            steps.push(`routing ${chosenLanguage} → ${routeName} unavailable`);
+        }
+        if (target && target !== chosenProvider) {
+            try {
+                const routed = await deps.transcribe(buffer, target, {
+                    ...optionsFor(target === fallbackProvider ? fallback?.model : undefined),
+                    languagePrior: chosenLanguage,
+                });
+                if (routed.text.trim() && readLanguageDetected(routed) !== false) {
+                    chosen = {
+                        ...routed,
+                        language: routed.language ?? chosen.language,
+                    };
+                    chosenProvider = target;
+                    chosenModel =
+                        target === fallbackProvider ? fallback?.model : undefined;
+                    steps.push(`routed ${chosenLanguage} → ${target}`);
+                }
+                else {
+                    steps.push(`routing ${chosenLanguage} → ${target} heard nothing · kept ${chosenProvider}`);
+                }
+            }
+            catch {
+                steps.push(`routing ${chosenLanguage} → ${target} failed · kept ${chosenProvider}`);
+            }
+        }
+    }
     if (!chosen) {
         // Primary failed and nothing replaced it. Let the second opinion settle
         // first so its request is not left running unobserved.
@@ -409,6 +794,9 @@ async function transcribeLayers(options, deps, startedAt) {
             }
         }
     }
+    // 5b. Guards on the engine output: a decoding loop is collapsed and a
+    // prompt echo is emptied before the correction layer sees the text.
+    chosen = guardEngineResult(chosen, promptTermsOf(options), (note) => steps.push(note));
     // 6. Correction. The primary text leads unless the primary engine said it
     // could not identify the language and a second opinion exists.
     const languageDetected = readLanguageDetected(chosen);
@@ -427,14 +815,20 @@ async function transcribeLayers(options, deps, startedAt) {
     let correctedSegments;
     if (correctionWanted(options) && perSegment && chosen.segments) {
         try {
-            const corrected = await correctTranscriptLines(segmentTexts, options.dictionary, options.correction, deps);
+            const corrected = await correctTranscriptLines(segmentTexts, options.dictionary, options.correction, deps, chosen.language);
             decisions = corrected.decisions;
             steps.push(...corrected.steps);
             Object.assign(correctionTimings, corrected.timings);
-            correctedSegments = chosen.segments.map((seg, i) => ({
-                ...seg,
-                text: corrected.lines[i]?.trim() || seg.text,
-            }));
+            correctedSegments = chosen.segments.map((seg, i) => {
+                const text = corrected.lines[i]?.trim() || seg.text;
+                if (text === seg.text || !seg.words?.length) {
+                    return { ...seg, text };
+                }
+                const words = alignWordsToText(seg.words, text);
+                return words.length
+                    ? { ...seg, text, words }
+                    : { ...seg, text, words: undefined };
+            });
             const joined = correctedSegments
                 .map((seg) => seg.text)
                 .filter(Boolean)
@@ -456,12 +850,18 @@ async function transcribeLayers(options, deps, startedAt) {
     }
     else if (correctionWanted(options)) {
         try {
-            const corrected = await correctTranscript({
+            const correctFn = options.correction?.perSentence === false
+                ? correctTranscript
+                : correctTranscriptSentences;
+            const corrected = await correctFn({
                 text: engineText,
                 ...(secondText ? { secondOpinion: secondText } : {}),
                 ...(options.dictionary ? { dictionary: options.dictionary } : {}),
                 ...(options.correction ? { options: options.correction } : {}),
                 ...(languageDetected !== undefined ? { languageDetected } : {}),
+                ...(chosen.language && languageDetected !== false
+                    ? { language: chosen.language }
+                    : {}),
             }, deps);
             decisions = corrected.decisions;
             steps.push(...corrected.steps);
@@ -483,11 +883,50 @@ async function transcribeLayers(options, deps, startedAt) {
     else if (secondLeads) {
         steps.push("second opinion leads (primary language unsure)");
     }
-    // 7. Result.
-    const { text: _engineText, ...chosenRest } = chosen;
+    // 7. Output languages, from the settled text: per segment when the
+    // transcript has several (so renderings keep the timings), else whole.
+    let outputs;
+    let outputMs;
+    const outputLanguages = outputLanguagesOf(options.output);
+    if (outputLanguages.length > 0) {
+        const outputStarted = Date.now();
+        const segs = chosen.segments ?? [];
+        let source;
+        let corrected;
+        if (correctedSegments && segs.length === correctedSegments.length) {
+            source = segs.map((seg) => seg.text);
+            corrected = correctedSegments.map((seg) => seg.text);
+        }
+        else if (segs.length > 1 && finalText === raw) {
+            source = segs.map((seg) => seg.text);
+        }
+        else {
+            source = [raw];
+            corrected = finalText !== raw ? [finalText] : undefined;
+        }
+        outputs = await renderOutputs({
+            source,
+            ...(corrected ? { corrected } : {}),
+            ...(chosen.language && languageDetected !== false
+                ? { language: chosen.language }
+                : {}),
+            languages: outputLanguages,
+            ...(options.dictionary ? { dictionary: options.dictionary } : {}),
+            options: options.output,
+        }, deps);
+        outputMs = Date.now() - outputStarted;
+        steps.push(describeOutputs(outputs));
+    }
+    // Word timings follow the corrected text.
+    const words = finalText !== raw && chosen.words?.length && !correctedSegments
+        ? alignWordsToText(chosen.words, finalText)
+        : chosen.words;
+    // 8. Result.
+    const { text: _engineText, words: _engineWords, ...chosenRest } = chosen;
     const result = {
         ...chosenRest,
         ...(correctedSegments ? { segments: correctedSegments } : {}),
+        ...(words?.length ? { words } : {}),
         text: finalText,
         raw,
         ...(finalText !== raw ? { corrected: finalText } : {}),
@@ -508,9 +947,11 @@ async function transcribeLayers(options, deps, startedAt) {
             transcribeMs,
             ...(secondOpinionMs !== undefined ? { secondOpinionMs } : {}),
             ...correctionTimings,
+            ...(outputMs !== undefined ? { outputMs } : {}),
             totalMs: Date.now() - startedAt,
         },
         steps,
+        ...(outputs ? { outputs } : {}),
     };
     if (logger.shouldLog("debug")) {
         logger.debug(`[transcribe] ${chosenProvider}: ${raw.length} chars raw, ${finalText.length} final in ${result.timings.totalMs}ms`, { steps });

package/dist/voice/transcribeStream.d.ts

@@ -1,4 +1,21 @@
-import type { TranscribeDeps, TranscribeStreamEvent, TranscribeStreamOptions } from "../types/index.js";
+import type { STTDictionaryEntry, STTResult, TranscribeDeps, TranscribeStreamEvent, TranscribeStreamOptions } from "../types/index.js";
 /** Float samples in [-1, 1] → 16 kHz mono PCM16 WAV. */
 export declare function encodeWav16k(pcm: Float32Array): Buffer;
+/**
+ * Engine options for one provider: the caller's pass-through `STTOptions`,
+ * dictionary terms as vocabulary and appended to the prompt, `"auto"`
+ * language left to the engine.
+ */
+/** The words an engine is prompted with (dictionary terms, the caller's vocabulary, the fixed phrasing). */
+export declare function promptTermsOf(options: {
+    dictionary?: STTDictionaryEntry[];
+    vocabulary?: string[];
+}): string[];
+/**
+ * Engine output through the guards: a looping phrase is collapsed and the
+ * share of words it took is recorded on `metadata.loopShare`; an output
+ * that is only the prompt echoed back becomes empty. `note` receives a
+ * human-readable line for each guard that fired.
+ */
+export declare function guardEngineResult(res: STTResult, promptTerms: readonly string[], note: (line: string) => void): STTResult;
 export declare function runTranscribeStream(options: TranscribeStreamOptions, deps: TranscribeDeps): AsyncIterable<TranscribeStreamEvent>;