@tychenjiajun/pi-voice 0.6.0 → 0.8.0

package/src/chunking.ts

@@ -0,0 +1,319 @@
+import { CAPTURE_CHUNK_SAMPLES as FRAME, CAPTURE_SAMPLE_RATE as RATE } from "./audio-constants.js";
+import { getCatalogModel, type CatalogModel } from "./catalog.js";
+import { log } from "./log.js";
+import type { TranscribeSettings } from "./settings.js";
+import type { DictationStream } from "./transcription.js";
+
+// Long audio is decoded in chunks cut at pauses, except for models that handle
+// long audio themselves and streaming models, which never see a whole clip.
+const TARGET_SECONDS = 30;
+/** Audio up to this many samples is decoded in one piece; longer audio is cut. */
+export const MAX_CHUNK_SAMPLES = 40 * RATE;
+const MIN_CHUNK = 5 * RATE;
+// Live, a cut is only final once MIN_CHUNK past the window is scored: then no
+// cut it allows can leave a short rest, so live cuts match the offline plan.
+const LOOKAHEAD = MIN_CHUNK;
+
+// Silero's segmentation, as VadSession.run applies it.
+const THRESHOLD = 0.5;
+const NEG_THRESHOLD = THRESHOLD - 0.15;
+const MIN_SPEECH = (250 * RATE) / 1000;
+const MIN_SILENCE = (100 * RATE) / 1000;
+const SPEECH_PAD = (30 * RATE) / 1000;
+
+/**
+ * Models or families that window or chunk long audio themselves
+ */
+const HANDLES_LONG_AUDIO: ReadonlyArray<{ family: string } | { id: string }> = [
+  { family: "whisper" },
+  { id: "parakeet-ultra" }, // Other Parakeets don't.
+];
+
+function handlesLongAudio(model: CatalogModel): boolean {
+  return HANDLES_LONG_AUDIO.some((entry) =>
+    "family" in entry ? entry.family === model.family : entry.id === model.id);
+}
+
+/** Models outside the catalog are chunked: nothing says they handle long audio. */
+export function chunksTranscription(settings: Pick<TranscribeSettings, "longformChunking"> & { model?: { id: string } }): boolean {
+  if (!settings.longformChunking) return false;
+  // Remote settings carry no local model and never chunk.
+  if (!settings.model) return false;
+  const model = getCatalogModel(settings.model.id);
+  if (!model) return true;
+  return !handlesLongAudio(model) && !model.capabilities.streaming;
+}
+
+export type SpeechSegment = { start: number; end: number };
+
+/**
+ * Speech segments, in samples, from per-frame Silero probabilities: Silero
+ * 6.2.3's get_speech_timestamps as transcribe.cpp ports it
+ * (vad_probs_to_segments), without a maximum speech length.
+ */
+export function speechSegments(probs: ArrayLike<number>, samples: number): SpeechSegment[] {
+  const segments: SpeechSegment[] = [];
+  let triggered = false;
+  let start = 0;
+  let tempEnd = 0;
+  for (let i = 0; i < probs.length; i++) {
+    const prob = probs[i]!;
+    const at = i * FRAME;
+    if (prob >= THRESHOLD && tempEnd !== 0) tempEnd = 0;
+    if (prob >= THRESHOLD && !triggered) {
+      triggered = true;
+      start = at;
+      continue;
+    }
+    if (prob < NEG_THRESHOLD && triggered) {
+      if (tempEnd === 0) tempEnd = at;
+      if (at - tempEnd < MIN_SILENCE) continue;
+      if (tempEnd - start > MIN_SPEECH) segments.push({ start, end: tempEnd });
+      triggered = false;
+      tempEnd = 0;
+    }
+  }
+  if (triggered && samples - start > MIN_SPEECH) segments.push({ start, end: samples });
+
+  for (let i = 0; i < segments.length; i++) {
+    const segment = segments[i]!;
+    if (i === 0) segment.start = Math.max(0, segment.start - SPEECH_PAD);
+    const next = segments[i + 1];
+    if (!next) {
+      segment.end = Math.min(samples, segment.end + SPEECH_PAD);
+      continue;
+    }
+    const silence = next.start - segment.end;
+    const pad = silence < 2 * SPEECH_PAD ? Math.floor(silence / 2) : SPEECH_PAD;
+    segment.end = Math.min(samples, segment.end + pad);
+    next.start = Math.max(0, next.start - pad);
+  }
+  return segments;
+}
+
+export type CutCandidate = { cut: number; gapSeconds: number };
+
+/** One candidate in the middle of each pause, lead-in and tail included. */
+export function cutCandidates(segments: readonly SpeechSegment[], samples: number): CutCandidate[] {
+  const candidates: CutCandidate[] = [];
+  let silenceStart = 0;
+  for (const { start, end } of [...segments, { start: samples, end: samples }]) {
+    if (start > silenceStart) {
+      candidates.push({ cut: Math.floor((silenceStart + start) / 2), gapSeconds: (start - silenceStart) / RATE });
+    }
+    silenceStart = Math.max(silenceStart, end);
+  }
+  return candidates;
+}
+
+/**
+ * Greedy, left to right from `from`: each cut is the best-scoring pause
+ * 5-40 s after the previous one, preferring long pauses near 30 s and ones
+ * that leave at least 5 s after them. With no pause, it is a hard cut at 40 s,
+ * or halfway when that would leave under 5 s. Audio of 40 s or less is never cut.
+ */
+export function planCuts(candidates: readonly CutCandidate[], samples: number, from = 0): number[] {
+  const cuts: number[] = [];
+  let start = from;
+  // Candidates are in order, and each window starts after the last.
+  let first = 0;
+  while (samples - start > MAX_CHUNK_SAMPLES) {
+    while (first < candidates.length && candidates[first]!.cut < start + MIN_CHUNK) first++;
+    // A pause that leaves under 5 s is only used when no other pause will do.
+    let best: number | undefined;
+    let bestScore = -Infinity;
+    let fallback: number | undefined;
+    let fallbackScore = -Infinity;
+    for (let i = first; i < candidates.length && candidates[i]!.cut <= start + MAX_CHUNK_SAMPLES; i++) {
+      const { cut, gapSeconds } = candidates[i]!;
+      const position = (cut - start) / RATE;
+      const score = Math.min(gapSeconds, 1) - (position > TARGET_SECONDS
+        ? 0.1 * (position - TARGET_SECONDS)
+        : 0.05 * (TARGET_SECONDS - position));
+      if (samples - cut >= MIN_CHUNK && score > bestScore) {
+        best = cut;
+        bestScore = score;
+      }
+      if (score > fallbackScore) {
+        fallback = cut;
+        fallbackScore = score;
+      }
+    }
+    const hardCut = samples - start < MAX_CHUNK_SAMPLES + MIN_CHUNK
+      ? start + Math.floor((samples - start) / 2)
+      : start + MAX_CHUNK_SAMPLES;
+    start = best ?? fallback ?? hardCut;
+    cuts.push(start);
+  }
+  return cuts;
+}
+
+// Scripts written without spaces between words, and CJK punctuation.
+const UNSPACED = /[\p{Script=Han}\p{Script=Hiragana}\p{Script=Katakana}\p{Script=Bopomofo}\p{Script=Thai}\p{Script=Lao}\p{Script=Khmer}\p{Script=Myanmar}\u3000-\u303f\uff00-\uffef]/u;
+
+/** Chunk texts in order: a space between two chunks unless either side is unspaced script. */
+export function joinTranscripts(texts: readonly string[]): string {
+  let joined = "";
+  // Whole code points: astral Han (CJK Extension B+) is a surrogate pair.
+  let last: string | undefined;
+  for (const raw of texts) {
+    const text = raw.trim();
+    if (!text) continue;
+    if (last !== undefined && !UNSPACED.test(last) && !UNSPACED.test(String.fromCodePoint(text.codePointAt(0)!))) {
+      joined += " ";
+    }
+    joined += text;
+    last = Array.from(text).at(-1);
+  }
+  return joined;
+}
+
+/** Decodes one chunk; `clip` is all audio so far, for choosing a language. */
+export type ChunkDecoder = (chunk: Float32Array, clip: Float32Array) => Promise<string>;
+
+/**
+ * Buffers audio and its Silero probabilities and decodes it in chunks, in
+ * order, one at a time. Pushed live, each chunk is decoded as soon as its cut
+ * is certain; `finish` cuts and decodes the rest. Pushed all at once, the
+ * cuts are exactly the offline plan's.
+ */
+export class ChunkedTranscriber {
+  private audio: Float32Array = new Float32Array(0);
+  private length = 0;
+  private readonly probs: number[] = [];
+  /** False once audio arrives without probabilities: no more cuts. */
+  private scored = true;
+  private start = 0;
+  private readonly texts: string[] = [];
+  private decoding: Promise<void> = Promise.resolve();
+  private failure: { error: unknown } | undefined;
+
+  constructor(private readonly decode: ChunkDecoder) {}
+
+  get samples(): number { return this.length; }
+
+  /** `probs` scores each whole 512-sample frame of `pcm`, in order. */
+  push(pcm: Float32Array, probs?: readonly number[]): void {
+    if (pcm.length === 0) return;
+    this.trackScores(pcm.length, probs);
+    this.append(pcm);
+    if (!this.scored || this.length - this.start <= MAX_CHUNK_SAMPLES + LOOKAHEAD) return;
+    const segments = speechSegments(this.probs, this.length);
+    // A pause still open at the end moves its midpoint as it grows: wait for speech.
+    if (segments.at(-1)?.end !== this.length) return;
+    // One plan, committed while each cut's whole window plus the lookahead is scored.
+    for (const cut of planCuts(cutCandidates(segments, this.length), this.length, this.start)) {
+      if (this.length - this.start <= MAX_CHUNK_SAMPLES + LOOKAHEAD) break;
+      this.commit(cut);
+    }
+  }
+
+  /** The joined transcript, once every chunk is decoded. */
+  async finish(): Promise<string> {
+    const samples = this.length;
+    if (!this.scored && samples - this.start > MAX_CHUNK_SAMPLES) {
+      log.info(`no voice activity for the last ${seconds(samples - this.start)} s; decoding it in one piece`);
+    }
+    const cuts = this.scored ? planCuts(this.candidates(), samples, this.start) : [];
+    for (const cut of cuts) this.commit(cut);
+    // An empty clip still reaches the decoder, which rejects it.
+    if (samples > this.start || this.texts.length === 0) this.commit(samples);
+    await this.decoding;
+    if (this.failure) throw this.failure.error;
+    if (this.texts.length > 1) log.info(`decoded ${seconds(samples)} s in ${this.texts.length} chunks`);
+    return joinTranscripts(this.texts);
+  }
+
+  /** Settles once no chunk is decoding; never rejects. */
+  idle(): Promise<void> {
+    return this.decoding;
+  }
+
+  private trackScores(samples: number, probs: readonly number[] | undefined): void {
+    if (!this.scored) return;
+    const aligned = this.length % FRAME === 0 && probs !== undefined &&
+      (probs.length === Math.floor(samples / FRAME) || probs.length === Math.ceil(samples / FRAME));
+    if (aligned) {
+      for (const prob of probs) this.probs.push(prob);
+      return;
+    }
+    this.scored = false;
+    log.debug(`voice activity missing after ${seconds(this.length)} s; no more chunk cuts`);
+  }
+
+  private candidates(): CutCandidate[] {
+    return cutCandidates(speechSegments(this.probs, this.length), this.length);
+  }
+
+  private append(pcm: Float32Array): void {
+    if (this.length === 0 && this.audio.length === 0) {
+      this.audio = pcm; // One push of a whole clip is never copied.
+      this.length = pcm.length;
+      return;
+    }
+    if (this.length + pcm.length > this.audio.length) {
+      const grown = new Float32Array(Math.max(this.length + pcm.length, this.audio.length * 2, RATE * 60));
+      grown.set(this.audio.subarray(0, this.length));
+      this.audio = grown;
+    }
+    this.audio.set(pcm, this.length);
+    this.length += pcm.length;
+  }
+
+  private commit(end: number): void {
+    const index = this.texts.length;
+    const chunk = this.audio.subarray(this.start, end);
+    const clip = this.audio.subarray(0, this.length);
+    log.debug(`chunk ${index + 1}: ${seconds(this.start)}-${seconds(end)} s`);
+    this.start = end;
+    this.texts.push("");
+    this.decoding = this.decoding.then(async () => {
+      if (this.failure) return;
+      try {
+        this.texts[index] = await this.decode(chunk, clip);
+      } catch (error) {
+        this.failure = { error };
+      }
+    });
+  }
+}
+
+/** Dictation through a ChunkedTranscriber: chunks decode while the user speaks. */
+export class ChunkedDictationStream implements DictationStream {
+  private readonly transcriber: ChunkedTranscriber;
+  private closed = false;
+
+  constructor(decode: ChunkDecoder, private readonly abort: () => void) {
+    this.transcriber = new ChunkedTranscriber(decode);
+  }
+
+  async feed(chunk: Float32Array, probs?: readonly number[]): Promise<void> {
+    if (this.closed) throw new Error("Dictation stream is closed");
+    this.transcriber.push(chunk, probs);
+  }
+
+  async finalize(audio?: Float32Array): Promise<string> {
+    if (this.closed) throw new Error("Dictation stream is closed");
+    this.closed = true;
+    // Feeding is optional, so the submitted take can hold audio this stream
+    // never saw; the batch path then transcribes the whole take.
+    if (audio && audio.length !== this.transcriber.samples) {
+      throw new Error(`the stream got ${this.transcriber.samples} of ${audio.length} samples`);
+    }
+    return this.transcriber.finish();
+  }
+
+  reset(): void {
+    this.closed = true;
+    this.abort();
+  }
+
+  /** Settles once no chunk is decoding, so the model is free. */
+  idle(): Promise<void> {
+    return this.transcriber.idle();
+  }
+}
+
+function seconds(samples: number): string {
+  return (samples / RATE).toFixed(1);
+}

package/src/dictation-controller.ts

@@ -17,6 +17,19 @@ export type CaptureSinks = {
   onAudio(chunk: Float32Array): void;
   onFailure(error: Error): void;
 };
+/** Voice activity detection for one take: passes on only the speech. */
+export type SpeechFilter = {
+  push(chunk: Float32Array): void;
+  /** All kept audio, once every pushed chunk is decided. */
+  finish(): Promise<Float32Array>;
+  discard(): void;
+};
+/** Kept audio, with its Silero frame probabilities when it has them. */
+export type OnSpeech = (chunk: Float32Array, probs?: readonly number[]) => void;
+export type CreateSpeechFilter = (
+  settings: TranscribeSettings,
+  onSpeech: OnSpeech,
+) => SpeechFilter | undefined;
 /** Opens a microphone and starts recording; resolves once audio is flowing. */
 export type OpenCapture = (microphone: MicrophoneSetting, sinks: CaptureSinks) => Promise<Capture>;
 export type DictationResult = {
@@ -27,6 +40,8 @@ export type DictationResult = {
   interruption?: Error;
   /** Audio lost inside the recording because it wasn't read in time. */
   droppedFrames?: number;
+  /** Language detection fallback, never part of the text. */
+  warning?: string;
 };
 export type DictationState =
   | { phase: "idle" | "ready" | "starting" | "listening" | "transcribing" | "cancelling" | "disposed" }
@@ -37,12 +52,15 @@ export type DictationControllerOptions = {
   now?: () => number;
   onChange?: (state: DictationState) => void;
   onAudio?: (chunk: Float32Array) => void;
+  /** Without a filter, every chunk is transcribed. */
+  createSpeechFilter?: CreateSpeechFilter;
 };
 type Take = {
   settings: TranscribeSettings;
   reservation: DictationReservation;
   abort: AbortController;
   chunker: PcmChunker;
+  filter?: SpeechFilter;
   capture?: Capture;
   interruption?: Error;
   stopping?: Promise<CapturedAudio>;
@@ -106,8 +124,13 @@ export class DictationController {
     }
     const take: Take = {
       settings, reservation, abort: new AbortController(),
-      chunker: new PcmChunker((chunk) => reservation.feed(chunk)),
+      chunker: new PcmChunker((chunk, probs) => reservation.feed(chunk, probs)),
     };
+    try {
+      take.filter = this.options.createSpeechFilter?.(settings, (chunk, probs) => this.feedStream(take, chunk, probs));
+    } catch (cause) {
+      log.warn(`voice activity detection unavailable: ${describeError(cause)}`);
+    }
     this.take = take;
     void reservation.ready.then(
       () => {
@@ -133,7 +156,7 @@ export class DictationController {
   prepare(settings: TranscribeSettings): void {
     if (this.disposed || ["starting", "listening", "transcribing", "cancelling"].includes(this.current.phase)) return;
     if (this.take?.settings === settings && this.readiness !== "failed") return;
-    this.take?.reservation.cancel();
+    if (this.take) this.release(this.take);
     this.take = undefined;
     if (this.reserve(settings)) this.setState({ phase: "ready" });
   }
@@ -149,7 +172,7 @@ export class DictationController {
     if (["listening", "transcribing", "cancelling"].includes(this.current.phase)) return Promise.resolve();
     let take = this.take?.settings === settings && this.readiness !== "failed" ? this.take : undefined;
     if (!take) {
-      this.take?.reservation.cancel();
+      if (this.take) this.release(this.take);
       this.take = undefined;
     }
     const generation = this.generation;
@@ -183,8 +206,7 @@ export class DictationController {
         if (!current()) return; // Cancelled meanwhile; cancel() released the take.
         if (take) {
           this.take = undefined;
-          take.chunker.discard();
-          take.reservation.cancel();
+          this.release(take);
         }
         this.setState({ phase: "error", stage: "capture", cause });
         return;
@@ -221,8 +243,20 @@ export class DictationController {
   }
 
   private feed(take: Take, chunk: Float32Array): void {
+    if (take.filter) take.filter.push(chunk);
+    else this.feedStream(take, chunk);
+  }
+
+  private feedStream(take: Take, chunk: Float32Array, probs?: readonly number[]): void {
     // A failed stream feed falls back to submitting the whole recording.
-    try { take.chunker.push(chunk); } catch { /* The recording keeps the audio. */ }
+    try { take.chunker.push(chunk, probs); } catch { /* The recording keeps the audio. */ }
+  }
+
+  /** Drops a take that will never be submitted. */
+  private release(take: Take): void {
+    take.filter?.discard();
+    take.chunker.discard();
+    take.reservation.cancel();
   }
 
   private stopCapture(take: Take): Promise<CapturedAudio> {
@@ -248,30 +282,40 @@ export class DictationController {
     take.submission = this.stopCapture(take).then(async (captured) => {
       // Cancellation while the native microphone is stopping must never submit.
       if (this.take !== take || take.abort.signal.aborted) return undefined;
-      const { pcm } = captured;
+      const recorded = captured.pcm;
       const interruption = captured.interruption ?? take.interruption;
-      if (interruption && pcm.length === 0) throw interruption;
+      if (interruption && recorded.length === 0) throw interruption;
+      const pcm = take.filter ? await take.filter.finish() : recorded;
+      if (this.take !== take || take.abort.signal.aborted) return undefined;
       take.chunker.flush();
-      stage = "transcription";
-      logStep("transcribing", `${(pcm.length / CAPTURE_SAMPLE_RATE).toFixed(1)} s of audio`);
-      const text = await take.reservation.submit(pcm, take.abort.signal);
+      let text: string;
+      let warning: string | undefined;
+      if (take.filter && pcm.length === 0) {
+        take.reservation.cancel(); // No speech, nothing to transcribe.
+        text = "";
+      } else {
+        stage = "transcription";
+        logStep("transcribing", `${(pcm.length / CAPTURE_SAMPLE_RATE).toFixed(1)} s of audio`);
+        ({ text, warning } = await take.reservation.submit(pcm, take.abort.signal));
+      }
       if (this.disposed || this.take !== take || take.abort.signal.aborted) return undefined;
       const result = {
         text,
-        speechSeconds: pcm.length / CAPTURE_SAMPLE_RATE,
+        speechSeconds: recorded.length / CAPTURE_SAMPLE_RATE,
         transcribeSeconds: Math.max(0, (this.now() - stoppedAt) / 1000),
         ...(interruption ? { interruption } : {}),
         ...(captured.droppedFrames ? { droppedFrames: captured.droppedFrames } : {}),
+        ...(warning ? { warning } : {}),
       };
       this.take = undefined;
-      const empty = text ? "" : "; no speech detected";
-      log.info(
-        `transcribed ${result.speechSeconds.toFixed(1)} s of audio in ${result.transcribeSeconds.toFixed(1)} s${empty}`,
-      );
+      log.info(text
+        ? `transcribed ${(pcm.length / CAPTURE_SAMPLE_RATE).toFixed(1)} s of audio in ${result.transcribeSeconds.toFixed(1)} s`
+        : "no speech detected");
       logStep("idle");
       this.setState({ phase: "result", result });
       return result;
     }).catch((cause: unknown) => {
+      take.filter?.discard();
       take.reservation.cancel(); // Releases the lane if stop failed before submit.
       if (this.disposed || this.take !== take || take.abort.signal.aborted) return undefined;
       this.take = undefined;
@@ -291,8 +335,7 @@ export class DictationController {
     if (!take && !opening) return this.cleanup;
     if (take) {
       take.abort.abort();
-      take.chunker.discard();
-      take.reservation.cancel();
+      this.release(take);
     }
     if (opening) log.info("start cancelled");
     else if (take?.submission) log.info("transcription cancelled");

package/src/file-audio.ts

@@ -3,7 +3,7 @@ import { spawn } from "node:child_process";
 export const FILE_SAMPLE_RATE = 16_000;
 
 const BYTES_PER_SAMPLE = Float32Array.BYTES_PER_ELEMENT;
-const MAX_DECODED_BYTES = 128 * 1024 * 1024;
+const MAX_DECODED_BYTES = 512 * 1024 * 1024;
 const MAX_STDERR_CHARS = 8 * 1024;
 
 type FfmpegConfiguration = {
@@ -109,7 +109,7 @@ export async function decodeFileAudio(
       byteLength += chunk.length;
       if (byteLength > MAX_DECODED_BYTES) {
         terminalError = new Error(
-          "Decoded audio exceeds the 128 MiB safety limit (about 35 minutes at 16 kHz mono). Split the media file into smaller parts and retry.",
+          "Decoded audio exceeds the 512 MiB safety limit (about 2.3 hours at 16 kHz mono). Split the media file into smaller parts and retry.",
         );
         child.kill("SIGTERM");
         return;

package/src/file-transcription.ts

@@ -25,6 +25,7 @@ type FileTranscriptionDetails = {
   seconds: number;
   truncation?: TruncationResult;
   fullTranscriptPath?: string;
+  warning?: string;
 };
 
 type FileTranscriptionOptions = {
@@ -155,7 +156,7 @@ export function registerFileTranscriptionTool(
                 seconds: audio.seconds,
               },
             });
-            const rawTranscript = await service.transcribeFile(
+            const { text: rawTranscript, warning } = await service.transcribeFile(
               configured,
               audio.pcm,
               operationSignal,
@@ -173,14 +174,16 @@ export function registerFileTranscriptionTool(
               inputPath,
               modelId: modelLabel,
               seconds: audio.seconds,
+              ...(warning ? { warning } : {}),
             };
+            const warningText = warning ? `\n\n[Language detection: ${warning}]` : "";
 
             if (!transcript) {
               return {
                 content: [
                   {
                     type: "text" as const,
-                    text: `No speech detected in ${audio.seconds.toFixed(1)}s of audio from ${inputPath}`,
+                    text: `No speech detected in ${audio.seconds.toFixed(1)}s of audio from ${inputPath}${warningText}`,
                   },
                 ],
                 details,
@@ -204,7 +207,7 @@ export function registerFileTranscriptionTool(
             }
 
             return {
-              content: [{ type: "text" as const, text: resultText }],
+              content: [{ type: "text" as const, text: resultText + warningText }],
               details,
             };
           }, operationSignal);

package/src/language-detection-policy.ts

@@ -0,0 +1,127 @@
+import type { LangIdResult } from "transcribe-cpp";
+import { CAPTURE_SAMPLE_RATE } from "./audio-constants.js";
+import { LANGUAGE_DETECTION_MODEL, displayLanguage, getCatalogModel, languageIdentity, resolveModelLanguage } from "./catalog.js";
+import { describeError, log } from "./log.js";
+import type { TranscribeSettings } from "./settings.js";
+
+type LanguageModel = {
+  readonly languages: readonly string[];
+  readonly capabilities: { readonly languageDetection: boolean };
+};
+
+export type DetectPolicy = { kind: "detect"; languages: string[]; allowed: string[] };
+/** What a take does about language. Auto is never `fixed`; `unsupported` hides it. */
+export type AutoLanguagePolicy =
+  | { kind: "native" }
+  | { kind: "fixed"; language: string }
+  | DetectPolicy
+  | { kind: "unsupported" };
+
+const detectorCodes = new Map<string, string>(
+  LANGUAGE_DETECTION_MODEL.languages.map((code) => [languageIdentity(code), code]),
+);
+
+/** Return the detector's own label (iw/jw/tl/no included). */
+export function detectorLanguageCode(language: string): string | undefined {
+  return detectorCodes.get(languageIdentity(language));
+}
+
+/** Whether this ASR model needs the external detector for Auto, independent of preferences. */
+export function requiresLanguageDetector(model: LanguageModel): boolean {
+  return !model.capabilities.languageDetection &&
+    new Set(model.languages.map(languageIdentity)).size > 1;
+}
+
+/** Preferred languages this model supports, in preference order, one per identity. */
+function compatiblePreferences(model: LanguageModel, preferred: readonly string[]): string[] {
+  const byIdentity = new Map<string, string>();
+  for (const preference of preferred) {
+    const language = resolveModelLanguage(model, preference);
+    if (language !== undefined && !byIdentity.has(languageIdentity(language))) {
+      byIdentity.set(languageIdentity(language), language);
+    }
+  }
+  return [...byIdentity.values()];
+}
+
+/** Supported preferred languages the external detector cannot identify (e.g. Irish). */
+export function undetectablePreferences(model: LanguageModel, preferred: readonly string[]): string[] {
+  if (!requiresLanguageDetector(model)) return [];
+  return compatiblePreferences(model, preferred).filter((language) => detectorLanguageCode(language) === undefined);
+}
+
+/**
+ * Resolve Auto. Without native detection, Auto exists only when at least two
+ * preferred languages are supported and every one of them is detectable.
+ */
+export function autoLanguagePolicy(
+  model: LanguageModel,
+  preferred: readonly string[],
+): AutoLanguagePolicy {
+  // Native detection retains its existing unrestricted semantics.
+  if (model.capabilities.languageDetection) return { kind: "native" };
+
+  const languages = compatiblePreferences(model, preferred);
+  const allowed = languages.map(detectorLanguageCode);
+  if (languages.length < 2 || allowed.includes(undefined)) return { kind: "unsupported" };
+  return { kind: "detect", languages, allowed: allowed as string[] };
+}
+
+/** The policy a take runs with: an explicit language is fixed. */
+export function settingsLanguagePolicy(settings: TranscribeSettings): AutoLanguagePolicy {
+  if (settings.transcriptionLanguage !== "auto") {
+    return { kind: "fixed", language: settings.transcriptionLanguage };
+  }
+  const model = settings.model ? getCatalogModel(settings.model.id) : undefined;
+  // Test/injected backends may use noncatalog ids. Persisted settings never do.
+  // Remote settings carry no model; the endpoint detects the language itself.
+  return model ? autoLanguagePolicy(model, settings.preferredLanguages) : { kind: "native" };
+}
+
+const WINDOW_SAMPLES = 7 * CAPTURE_SAMPLE_RATE;
+const MIN_SAMPLES = CAPTURE_SAMPLE_RATE / 2;
+// Log a pick as uncertain when it is less than 1.5x as likely as the
+// runner-up (with two languages: p < 0.6). The pick is used either way.
+const UNSURE_RATIO = 1.5;
+
+/** Shown once per session when Auto runs without the detector on disk. */
+export function missingDetectorWarning(fallback: string): string {
+  return `The language detector isn't downloaded. Transcribed as ${displayLanguage(fallback)}. ` +
+    "To download it, open /voice-settings and choose Auto detect as the transcription language.";
+}
+
+/**
+ * Pick one language for a whole clip from its first seven seconds: always the
+ * top candidate. Skipped (< 500 ms), failed, or malformed detection falls back
+ * to the first preferred language; only the last two warn.
+ */
+export async function detectLanguage(
+  policy: DetectPolicy,
+  pcm: Float32Array,
+  identify: (pcm: Float32Array, allowed: readonly string[]) => Promise<LangIdResult>,
+): Promise<{ language: string; warning?: string }> {
+  const fallback = policy.languages[0]!;
+  const seconds = (pcm.length / CAPTURE_SAMPLE_RATE).toFixed(2);
+  if (pcm.length < MIN_SAMPLES) {
+    log.info(`language detection: skipped, the ${seconds} s clip is under the ` +
+      `${MIN_SAMPLES / CAPTURE_SAMPLE_RATE} s minimum; transcribing as ${fallback}, the first preferred language`);
+    return { language: fallback };
+  }
+  const transcribedAs = `Transcribed as ${displayLanguage(fallback)}.`;
+  try {
+    const result = await identify(pcm.subarray(0, WINDOW_SAMPLES), policy.allowed);
+    const [first, second] = result.candidates;
+    const language = policy.languages[policy.allowed.indexOf(result.code ?? "")];
+    const scores = result.candidates.map((c) => `${c.code} ${(c.p * 100).toFixed(1)}%`).join(", ");
+    const unsure = first && second && first.p < UNSURE_RATIO * second.p ? ", uncertain" : "";
+    log.info(`language detection: ${language ?? "none"} (${scores}; ` +
+      `${seconds} s, allowed mass ${(result.allowedMass * 100).toFixed(1)}%${unsure})`);
+    if (!language || !first || !Number.isFinite(first.p)) {
+      return { language: fallback, warning: `Couldn't detect the language. ${transcribedAs}` };
+    }
+    return { language };
+  } catch (error) {
+    log.warn(`Language detection failed: ${describeError(error)}`);
+    return { language: fallback, warning: `Language detection failed (${describeError(error)}). ${transcribedAs}` };
+  }
+}