extract speech-to-text into its own plugin

Moves platform STT out into a plugin that owns the whole whisper.cpp contract: sidecar,
config (a JSON file under DATA_PATH/transcribe/, validated against the server before
storing), a thin proxy router, a skill so an agent knows the contract without being told,
and a script-mode file-browser task (not agentic — no model turn per audio file).

sidecar/transcribe.ts and its test moved unchanged from src/servers/api/stt/ — every
constant in it has a reason attached and none of it was touched.

The platform-side removal (routes, dead useAudioRecording path, Settings screen, locale
keys) lands in a separate, uncommitted change in the platform repo for review.

Not yet reachable from the file browser: the platform does not load tasks from a plugin's
directory yet (skills/affordances/notifications do). Ships anyway per instructions.

Officer-Session: 656f5c85-e49a-4f1f-b9f3-042a04b4d043

sidecar/config.ts

@@ -0,0 +1,87 @@
+import { join } from 'node:path';
+import { mkdir } from 'node:fs/promises';
+import { DATA_PATH } from '@@/data-path';
+
+// The Whisper connection — a single URL, kept in a JSON file rather than a database row.
+//
+// There is only ever one whisper.cpp server for the whole install: unlike `photos_config` or
+// `jellyfin_servers`, nobody has a reason to keep more than one on hand, so a file the owner can also
+// edit by hand (or drop in with a provisioning script) is simpler than a table that will only ever hold
+// one row. See `plugins/music/sidecar/indexer.ts` for the same `DATA_PATH/<plugin>/` convention.
+//
+// Not committed anywhere: this file lives under DATA_PATH, outside both the platform's and this plugin's
+// git repositories. Config is data, not definition.
+
+const CONFIG_DIR = join(DATA_PATH, 'transcribe');
+const CONFIG_PATH = join(CONFIG_DIR, 'config.json');
+
+export type TranscribeConfig = { url: string };
+
+// Cached across requests; invalidated only by `setConfig`. A single small file re-read on every
+// transcription would be a needless stat + parse on the hot path.
+let cache: TranscribeConfig | null | undefined;
+
+async function loadConfig(): Promise<TranscribeConfig | null> {
+  const file = Bun.file(CONFIG_PATH);
+  if (!(await file.exists())) return null;
+  try {
+    const parsed = (await file.json()) as Partial<TranscribeConfig>;
+    return typeof parsed.url === 'string' && parsed.url ? { url: parsed.url } : null;
+  } catch {
+    return null;
+  }
+}
+
+export async function getConfig(): Promise<TranscribeConfig | null> {
+  if (cache === undefined) cache = await loadConfig();
+  return cache;
+}
+
+export async function setConfig(config: TranscribeConfig): Promise<void> {
+  await mkdir(CONFIG_DIR, { recursive: true });
+  await Bun.write(CONFIG_PATH, JSON.stringify(config, null, 2));
+  cache = config;
+}
+
+/**
+ * The URL as the browser is allowed to see it.
+ *
+ * A whisper.cpp URL is never expected to carry credentials — the server has no auth of its own — but if
+ * an owner points this at something behind a reverse proxy with basic auth baked into the URL, userinfo
+ * (`user:pass@`) must not round-trip back out to `GET /config`. Stripped rather than trusted to stay
+ * absent.
+ */
+export function redactUrl(url: string): string {
+  try {
+    const parsed = new URL(url);
+    parsed.username = '';
+    parsed.password = '';
+    return parsed.toString();
+  } catch {
+    return url;
+  }
+}
+
+export type ProbeResult = { ok: true } | { ok: false; error: string };
+
+/**
+ * Ask a whisper.cpp server whether it is really there.
+ *
+ * Mirrors the platform's old `POST /server-settings/stt/test`: an empty multipart body to `/inference`
+ * always fails on the Whisper side, but ANY response — including its error — means the server exists and
+ * speaks the expected protocol. A network-level failure (wrong host, nothing listening, timeout) is the
+ * only thing that means "not reachable".
+ */
+export async function probeWhisper(url: string): Promise<ProbeResult> {
+  const base = url.replace(/\/+$/, '');
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), 5000);
+  try {
+    await fetch(`${base}/inference`, { method: 'POST', body: new FormData(), signal: controller.signal });
+    return { ok: true };
+  } catch (err) {
+    return { ok: false, error: err instanceof Error ? err.message : 'could not reach the server' };
+  } finally {
+    clearTimeout(timeout);
+  }
+}

sidecar/index.ts

@@ -0,0 +1,170 @@
+import type { SidecarCommand, SidecarEvent } from '@@/sidecar/protocol';
+import { createSidecarConnector } from '@@/sidecar/connect';
+import { API_URL } from '@@/officer-url.mjs';
+import { getConfig, setConfig, redactUrl, probeWhisper } from './config';
+import { transcribeAudio } from './transcribe';
+
+// The officer-transcribe sidecar. Owns the whole whisper.cpp contract for Officer: the server URL and
+// the request tuning that makes it usable for a person talking into a phone (see transcribe.ts — moved
+// here unchanged from the platform, and every constant in it has a reason attached in its own comments).
+//
+// The platform API is a thin auth-gated forwarder (../api/router.ts) holding no Whisper knowledge at all.
+//
+// ─────────────────────────────────────────────────────────────────────────────────────────────────
+// HTTP CONTRACT — the platform strips its /api/transcribe mount prefix before forwarding.
+//
+//   GET  /_health    { ok, configured, url? }
+//   GET  /config      { configured, url }               — url has its userinfo stripped, never a secret
+//   PUT  /config      { url }                            — validated against the server before storing
+//   POST /transcribe  multipart: file, spokenLanguages[] → { text, detectedLanguage }
+//
+//   anything else     404
+//
+// Every route needs `X-Officer-User`, which the platform proxy sets after authenticating the caller. We
+// bind loopback only, so its presence is the trust signal — a request without it did not come through
+// the platform.
+// ─────────────────────────────────────────────────────────────────────────────────────────────────
+
+/** Grab an ephemeral free port by briefly binding one and releasing it. */
+function getFreePort(): number {
+  const probeServer = Bun.serve({ port: 0, hostname: '127.0.0.1', fetch: () => new Response('') });
+  const p = probeServer.port;
+  probeServer.stop(true);
+  if (p == null) throw new Error('failed to acquire a free port');
+  return p;
+}
+
+const port = getFreePort();
+
+async function handleConfigGet(): Promise<Response> {
+  const cfg = await getConfig();
+  return Response.json({ configured: !!cfg, url: cfg ? redactUrl(cfg.url) : null });
+}
+
+function isHttpUrl(url: string): boolean {
+  return /^https?:\/\//i.test(url);
+}
+
+async function handleConfigPut(req: Request): Promise<Response> {
+  const body = ((await req.json().catch(() => null)) as { url?: unknown } | null) ?? {};
+  const url = typeof body.url === 'string' ? body.url.trim() : '';
+  if (!url) return Response.json({ error: 'url is required' }, { status: 400 });
+  if (!isHttpUrl(url)) return Response.json({ error: 'url must start with http:// or https://' }, { status: 400 });
+
+  const probe = await probeWhisper(url);
+  if (!probe.ok) return Response.json({ error: probe.error }, { status: 400 });
+
+  await setConfig({ url });
+  return Response.json({ configured: true, url: redactUrl(url) });
+}
+
+async function handleTranscribe(req: Request): Promise<Response> {
+  const cfg = await getConfig();
+  if (!cfg) {
+    return Response.json({ error: 'Whisper not configured — PUT /api/transcribe/config first' }, { status: 400 });
+  }
+
+  const body = await req.formData().catch(() => null);
+  const file = body?.get('file');
+  if (!file || !(file instanceof File)) return Response.json({ error: 'file is required' }, { status: 400 });
+
+  const spokenLanguages = (body?.getAll('spokenLanguages') ?? []).map(String);
+
+  try {
+    const result = await transcribeAudio({ file, whisperUrl: cfg.url, spokenLanguages });
+    return Response.json(result);
+  } catch (err) {
+    console.error('[transcribe] transcription failed', err);
+    return Response.json(
+      { error: err instanceof Error ? err.message : 'Transcription failed' },
+      { status: 502 },
+    );
+  }
+}
+
+const server = Bun.serve({
+  port,
+  hostname: '127.0.0.1',
+  // A phone's voice memo is small; this just needs to be well above any single recording.
+  maxRequestBodySize: 1024 * 1024 * 1024,
+  async fetch(req) {
+    const url = new URL(req.url);
+
+    const officerUser = req.headers.get('X-Officer-User');
+    const userId = Number(officerUser);
+    if (!officerUser || !Number.isInteger(userId) || userId <= 0) {
+      return Response.json({ error: 'missing or invalid X-Officer-User' }, { status: 401 });
+    }
+
+    if (url.pathname === '/_health') {
+      const cfg = await getConfig();
+      if (!cfg) return Response.json({ ok: false, configured: false }, { status: 503 });
+      const probe = await probeWhisper(cfg.url);
+      if (!probe.ok) return Response.json({ ok: false, configured: true, error: probe.error }, { status: 502 });
+      return Response.json({ ok: true, configured: true, url: redactUrl(cfg.url) });
+    }
+
+    if (url.pathname === '/config') {
+      try {
+        if (req.method === 'GET') return await handleConfigGet();
+        if (req.method === 'PUT' || req.method === 'POST') return await handleConfigPut(req);
+        return Response.json({ error: 'method not allowed' }, { status: 405 });
+      } catch (err) {
+        console.error(`[transcribe] ${req.method} /config failed`, err);
+        return Response.json({ error: 'internal error' }, { status: 500 });
+      }
+    }
+
+    if (url.pathname === '/transcribe') {
+      if (req.method !== 'POST') return Response.json({ error: 'method not allowed' }, { status: 405 });
+      return handleTranscribe(req);
+    }
+
+    return Response.json({ error: 'not found' }, { status: 404 });
+  },
+});
+
+console.log(`[transcribe] listening on 127.0.0.1:${port} (whisper.cpp URL configured from PUT /config)`);
+
+type ReplyFn = (msg: SidecarEvent) => void;
+
+function handleCommand(cmd: SidecarCommand, reply: ReplyFn) {
+  switch (cmd.type) {
+    case 'ping':
+      reply({ type: 'pong', id: cmd.id });
+      break;
+    default:
+      reply({
+        type: 'error',
+        id: (cmd as SidecarCommand).id,
+        error: `Unknown command type: ${(cmd as Record<string, unknown>).type}`,
+      });
+  }
+}
+
+const connection = createSidecarConnector({
+  apiUrl: `${API_URL}/api/sidecar/register`,
+  name: 'transcribe',
+  handles: ['transcribe'],
+  onCommand(cmd, reply) {
+    handleCommand(cmd as SidecarCommand, reply as ReplyFn);
+  },
+  onConnected() {
+    connection.send({ type: 'transcribe:server', port });
+    console.log(`[transcribe] reported server port ${port} to API`);
+  },
+});
+
+function shutdown(signal: string) {
+  console.log(`[transcribe] ${signal} received, shutting down...`);
+  try {
+    server.stop(true);
+  } catch {
+    /* already stopped */
+  }
+  connection.destroy();
+  process.exit(0);
+}
+
+process.on('SIGTERM', () => shutdown('SIGTERM'));
+process.on('SIGINT', () => shutdown('SIGINT'));

sidecar/transcribe.test.ts

@@ -0,0 +1,78 @@
+import { describe, expect, it } from 'bun:test';
+import { toParagraphs } from './transcribe';
+import type { WhisperSegment } from './transcribe';
+
+// Whisper's own shape: leading space on every segment, times in seconds.
+const seg = (text: string, start: number, end: number, extra: Partial<WhisperSegment> = {}): WhisperSegment => ({
+  text,
+  start,
+  end,
+  ...extra,
+});
+
+describe('toParagraphs', () => {
+  it('joins segments spoken without a real pause into one paragraph', () => {
+    const out = toParagraphs([seg(' I went to the shop.', 0, 2), seg(' It was closed.', 2.2, 4)]);
+    expect(out).toBe('I went to the shop. It was closed.');
+  });
+
+  it('starts a new paragraph after a long silence', () => {
+    const out = toParagraphs([seg(' First thought.', 0, 2), seg(' Second thought.', 5, 7)]);
+    expect(out).toBe('First thought.\n\nSecond thought.');
+  });
+
+  it('does not break on a breath-length pause', () => {
+    const out = toParagraphs([seg(' Hang on,', 0, 1), seg(' let me think.', 1.5, 3)]);
+    expect(out).toBe('Hang on, let me think.');
+  });
+
+  // The lone "." lines in the old response_format=text output came from segments like this.
+  it('attaches stranded punctuation without a space in front of it', () => {
+    const out = toParagraphs([seg(' See you tomorrow morning', 0, 2), seg(' .', 2.1, 2.2)]);
+    expect(out).toBe('See you tomorrow morning.');
+  });
+
+  it('drops segments that are probably silence decoded with low confidence', () => {
+    const out = toParagraphs([
+      seg(' Real speech here.', 0, 2),
+      seg(' Thanks for watching!', 2.1, 3, { no_speech_prob: 0.95, avg_logprob: -1.8 }),
+      seg(' More real speech.', 3.1, 5),
+    ]);
+    expect(out).toBe('Real speech here. More real speech.');
+  });
+
+  it('keeps a confident segment even when it looks like silence', () => {
+    const out = toParagraphs([seg(' Definitely said.', 0, 2, { no_speech_prob: 0.95, avg_logprob: -0.2 })]);
+    expect(out).toBe('Definitely said.');
+  });
+
+  it('keeps segments that report neither probability', () => {
+    const out = toParagraphs([seg(' No metadata at all.', 0, 2)]);
+    expect(out).toBe('No metadata at all.');
+  });
+
+  it('measures the pause from the last kept segment, not the dropped one', () => {
+    const out = toParagraphs([
+      seg(' Before.', 0, 2),
+      seg(' Hallucinated.', 2.1, 9, { no_speech_prob: 0.9, avg_logprob: -2 }),
+      seg(' After.', 9.1, 11),
+    ]);
+    // The gap that matters is 2 -> 9.1, so these are separate thoughts.
+    expect(out).toBe('Before.\n\nAfter.');
+  });
+
+  it('collapses internal whitespace and ignores empty segments', () => {
+    const out = toParagraphs([seg('  Too   many\n spaces. ', 0, 2), seg('   ', 2.1, 2.2)]);
+    expect(out).toBe('Too many spaces.');
+  });
+
+  it('returns an empty string when every segment is filtered out', () => {
+    expect(toParagraphs([])).toBe('');
+    expect(toParagraphs([seg('  ', 0, 1)])).toBe('');
+  });
+
+  it('falls back to no break when segments carry no timings', () => {
+    const out = toParagraphs([{ text: ' One.' }, { text: ' Two.' }]);
+    expect(out).toBe('One. Two.');
+  });
+});

sidecar/transcribe.ts

@@ -0,0 +1,416 @@
+// Whisper transcription, always in the audio's own language.
+//
+// Detect the language first, then transcribe in it. Whisper's translate mode is English-only, so it
+// cannot honour "translate into <language>" for anything else — rather than silently returning a
+// rough English rendering of Portuguese audio, transcription is always faithful to the source.
+//
+// The detection must win when Whisper is confident. `spokenLanguages` only breaks ties on clips
+// Whisper is genuinely unsure about, where its low-confidence guess defaults to English.
+//
+// The transcription pass is tuned for one person talking into a phone, which is what this is mostly
+// used for. See the constants below: the defaults whisper.cpp ships are aimed at clean dictation and
+// produce loops, clipped words and breath-length paragraph breaks on real voice memos.
+//
+// Both requests pass `timeout: false`. Bun's fetch aborts at 300s by default, and whisper.cpp runs at
+// roughly 8x realtime, so anything over ~40 minutes of audio died with "The operation timed out"
+// about 20 seconds short of the answer. AbortSignal.timeout() does not raise that ceiling — only
+// disabling the built-in timeout does.
+
+// Bun's fetch accepts `timeout: false` to disable its built-in 300s ceiling. The DOM RequestInit
+// type this project compiles against does not declare it, so widen it here rather than casting at
+// each call site.
+type BunRequestInit = RequestInit & { timeout?: boolean | number };
+
+type TranscribeArgs = {
+  file: File | Blob;
+  whisperUrl: string;
+  spokenLanguages: string[];
+};
+
+export type TranscribeResult = {
+  text: string;
+  detectedLanguage: string;
+};
+
+// Above this probability Whisper's own detection is taken as authoritative. Below it the clip is
+// treated as ambiguous and the user's spoken languages break the tie.
+const CONFIDENT_DETECTION = 0.5;
+
+// whisper.cpp's "language" field uses full names ("english"); ISO codes live in
+// `language_probabilities`. Map covers what the user can pick in Profile settings.
+const LANG_NAME_TO_ISO: Record<string, string> = {
+  english: 'en',
+  portuguese: 'pt',
+  spanish: 'es',
+  french: 'fr',
+  german: 'de',
+  italian: 'it',
+  dutch: 'nl',
+  russian: 'ru',
+  chinese: 'zh',
+  japanese: 'ja',
+  korean: 'ko',
+};
+
+// Whisper reuses its own decoded output as the prompt for the next 30-second window, which is what
+// makes it fall into loops ("I know. I know. I know.") once it slips. `max_context` is the budget for
+// that carried text, and setting it to 0 stops the loops — but the same switch also disables the
+// initial prompt, since whisper.cpp gates both on `n_max_text_ctx > 0`.
+//
+// The way to keep the prompt and still starve the loop: `carry_initial_prompt` puts the prompt in a
+// static slot that is filled first and in full, and only the leftover budget goes to decoded text.
+// Every prompt below is comfortably longer than this budget, so there is never any leftover — the
+// vocabulary and style reach every window and none of the model's own output does.
+const PROMPT_CONTEXT_TOKENS = 96;
+
+// Whisper imitates whatever it is primed with; it does not take instructions. So each prompt is a
+// worked example of the output wanted — one person talking, punctuated the way it should come back —
+// and nothing else. An earlier version opened by *describing* the format ("Commas separate clauses,
+// and apostrophes are written properly") and that backfired: priming words which never occur in
+// speech put them in play, and a character surname came back from a Monk episode as "Commas".
+// Everything here is ordinary conversational language for that reason.
+//
+// Each is written in its own language, since an English prompt on Portuguese audio biases the
+// output, and each deliberately runs past PROMPT_CONTEXT_TOKENS — see above for why the length is
+// load-bearing. Overflow is trimmed from the front, so nothing depends on the opening words.
+//
+// Languages without an entry fall through to no prompt at all, which is handled explicitly below.
+//
+// Every prompt uses its language's full diacritic set (and, for a non-Latin script, its own
+// punctuation — Japanese 。/、, Greek ; as a question mark, Arabic ، and ؟) in ordinary words, never
+// forced in. Omitting one, e.g. writing Swedish without å ä ö, teaches Whisper to drop it too.
+const TRANSCRIPT_PROMPTS: Record<string, string> = {
+  en:
+    'Hey, sorry for the late reply — I was stuck in a meeting all morning and only just got out. ' +
+    "I had a look at the document you sent over, and honestly, I think it's mostly fine. There are " +
+    "a couple of things I'd change in the second half, but nothing serious. The introduction reads " +
+    'really well. Let me know when you have a few minutes and we can talk it through properly. ' +
+    "I'm around all afternoon, so whenever suits you is fine by me. Thanks again for putting it " +
+    'together, I know it took a while.',
+  pt:
+    'Olá, desculpa a demora a responder — estive numa reunião toda a manhã e só agora consegui ' +
+    'sair. Já vi o documento que enviaste e, sinceramente, acho que está quase tudo bem. Há duas ' +
+    'ou três coisas que mudava na segunda metade, mas nada de grave. A introdução está muito bem ' +
+    'escrita. Diz-me quando tiveres uns minutos e falamos com calma. Estou por aqui toda a tarde, ' +
+    'por isso quando te der jeito está bem para mim. Obrigado outra vez por teres tratado disto, ' +
+    'sei que deu trabalho.',
+  es:
+    'Hola, perdona la tardanza en responder — he estado toda la mañana en una reunión y recién ahora ' +
+    'he podido salir. Ya vi el documento que me enviaste y, la verdad, creo que está bastante bien. ' +
+    'Hay un par de cosas que cambiaría en la segunda mitad, pero nada grave. La introducción está muy ' +
+    'bien escrita. Avísame cuando tengas unos minutos y lo hablamos con calma. Estoy disponible toda ' +
+    'la tarde, así que cuando te venga bien está perfecto para mí. Gracias otra vez por armarlo, sé ' +
+    'que llevó tiempo.',
+  de:
+    'Hallo, entschuldige die späte Antwort — ich saß den ganzen Vormittag in einer Besprechung und ' +
+    'bin gerade erst rausgekommen. Ich habe mir das Dokument angeschaut, das du geschickt hast, und ' +
+    'ehrlich gesagt finde ich es größtenteils gut. In der zweiten Hälfte würde ich ein paar ' +
+    'Kleinigkeiten ändern, aber nichts Ernstes. Die Einleitung liest sich wirklich gut. Sag mir ' +
+    'Bescheid, wenn du später ein paar Minuten hast, dann können wir in Ruhe darüber reden. Ich bin ' +
+    'den ganzen Nachmittag über da, also wann immer es dir passt, ist mir recht. Danke nochmal, dass ' +
+    'du dir die Mühe gemacht hast, ich weiß, das hat Zeit gekostet.',
+  fr:
+    "Salut, désolé pour la réponse tardive — j'étais coincé en réunion toute la matinée et je viens " +
+    "tout juste d'en sortir. J'ai regardé le document que tu as envoyé, et honnêtement, je trouve que " +
+    "c'est plutôt bien. Il y a deux ou trois choses que je changerais dans la deuxième moitié, mais " +
+    "rien de grave. L'introduction est vraiment bien écrite. Dis-moi quand tu as quelques minutes et " +
+    "on en parle tranquillement. Je suis disponible tout l'après-midi, donc quand ça t'arrange, ça me " +
+    "va. Merci encore de l'avoir préparé, je sais que ça a pris du temps.",
+  sv:
+    'Hej, förlåt att jag inte svarat tidigare — jag satt i möte hela förmiddagen och kom precis loss. ' +
+    'Jag har tittat på dokumentet du skickade, och ärligt talat tycker jag att det mesta är bra. Det ' +
+    'är några saker jag skulle ändra i andra halvan, men inget allvarligt. Inledningen är verkligen ' +
+    'bra skriven. Säg till när du har några minuter så pratar vi igenom det ordentligt. Jag är ledig ' +
+    'hela eftermiddagen, så när det passar dig passar det mig. Tack igen för att du satte ihop det, ' +
+    'jag vet att det tog ett tag.',
+  it:
+    'Ciao, scusa il ritardo nella risposta — sono stato in riunione tutta la mattina e sono appena ' +
+    "uscito. Ho dato un'occhiata al documento che mi hai mandato e, sinceramente, penso che vada bene " +
+    'quasi tutto. Ci sono un paio di cose che cambierei nella seconda metà, ma niente di grave. ' +
+    "L'introduzione è scritta davvero bene. Fammi sapere quando hai qualche minuto così ne parliamo " +
+    'con calma. Sono libero tutto il pomeriggio, quindi va bene quando ti fa comodo. Grazie ancora ' +
+    'per averlo messo insieme, so che ci è voluto tempo.',
+  nl:
+    'Hoi, sorry voor het late antwoord — ik zat de hele ochtend in een vergadering en ben er net pas ' +
+    'uit. Ik heb naar het document gekeken dat je hebt gestuurd, en eerlijk gezegd vind ik het ' +
+    'grotendeels goed. Er zijn een paar dingen die ik in de tweede helft zou veranderen, maar niets ' +
+    'ergs. De inleiding leest heel prettig. Laat het me weten wanneer je een paar minuten hebt, dan ' +
+    'bespreken we het rustig. Ik ben de hele middag beschikbaar, dus wanneer het jou uitkomt is voor ' +
+    'mij prima. Bedankt nogmaals dat je het hebt samengesteld, ik weet dat het tijd heeft gekost.',
+  pl:
+    'Cześć, przepraszam za późną odpowiedź — siedziałem cały ranek na spotkaniu i w końcu udało mi ' +
+    'się z niego wyrwać. Zerknąłem na dokument, który przesłałeś, i szczerze mówiąc, myślę, że ' +
+    'większość jest w porządku. Jest kilka rzeczy, które zmieniłbym w drugiej połowie, ale nic ' +
+    'poważnego. Wstęp jest naprawdę dobrze napisany. Daj znać, kiedy będziesz mieć chwilę, możemy to ' +
+    'spokojnie omówić. Jestem wolny całe popołudnie, więc kiedy ci pasuje, mi też pasuje. Dzięki ' +
+    'jeszcze raz za to, że to zebrałeś, wiem, że zajęło to trochę czasu.',
+  da:
+    'Hej, undskyld det sene svar — jeg sad i møde hele formiddagen og er lige kommet ud. Jeg har ' +
+    'kigget på dokumentet, du sendte, og ærligt talt synes jeg det meste er fint. Der er et par ting, ' +
+    'jeg ville ændre i anden halvdel, men ikke noget alvorligt. Indledningen er skrevet rigtig godt. ' +
+    'Sig til, når du har et par minutter, så snakker vi ordentligt om det. Jeg er ledig hele ' +
+    'eftermiddagen, så det passer mig, når det passer dig. Tak igen fordi du satte det sammen, jeg ' +
+    'ved det tog tid.',
+  no:
+    'Hei, beklager det sene svaret — jeg satt i møte hele formiddagen og er akkurat ferdig. Jeg har ' +
+    'sett på dokumentet du sendte, og ærlig talt synes jeg det meste er bra. Det er et par ting jeg ' +
+    'ville endret i andre halvdel, men ingenting alvorlig. Innledningen er skrevet veldig bra. Si ' +
+    'ifra når du har noen minutter, så tar vi en skikkelig prat om det. Jeg er ledig hele ' +
+    'ettermiddagen, så det som passer deg passer meg. Takk igjen for at du satte det sammen, jeg vet ' +
+    'det tok tid.',
+  fi:
+    'Hei, anteeksi myöhäinen vastaus — istuin koko aamupäivän palaverissa ja pääsin juuri äsken pois. ' +
+    'Katsoin dokumentin, jonka lähetit, ja rehellisesti sanottuna suurin osa siitä on ihan hyvä. ' +
+    'Loppupuoliskolla on pari asiaa, jotka muuttaisin, mutta ei mitään vakavaa. Johdanto on ' +
+    'kirjoitettu tosi hyvin. Sano, kun sinulla on hetki aikaa, niin jutellaan siitä kunnolla. Olen ' +
+    'vapaana koko iltapäivän, joten mikä tahansa sopii sinulle, sopii minulle. Kiitos vielä kerran, ' +
+    'kun kokosit sen, tiedän että siihen meni aikaa.',
+  tr:
+    'Selam, geç cevap verdiğim için kusura bakma — bütün sabah toplantıdaydım ve az önce çıkabildim. ' +
+    'Gönderdiğin dokümana baktım ve açıkçası çoğunlukla iyi olduğunu düşünüyorum. İkinci yarıda ' +
+    'değiştireceğim birkaç şey var ama ciddi bir şey değil. Giriş kısmı gerçekten iyi yazılmış. ' +
+    'Birkaç dakikan olduğunda haber ver, düzgünce konuşuruz. Bütün öğleden sonra müsaitim, yani sana ' +
+    'uyan zaman bana da uyar. Bunu hazırladığın için tekrar teşekkürler, biliyorum zaman almıştır.',
+  cs:
+    'Ahoj, promiň za pozdní odpověď — celé dopoledne jsem byl na poradě a teprve teď jsem se dostal ' +
+    'ven. Podíval jsem se na dokument, cos poslal, a upřímně řečeno, myslím, že většina je v pořádku. ' +
+    'V druhé polovině bych pár věcí změnil, ale nic vážného. Úvod je napsaný fakt dobře. Dej vědět, ' +
+    'až budeš mít pár minut, můžeme to pořádně probrat. Celé odpoledne mám volno, takže kdy se ti to ' +
+    'bude hodit, mně to vyhovuje. Díky ještě jednou, žes to dal dohromady, vím, že to zabralo čas.',
+  el:
+    'Γεια σου, συγγνώμη για την καθυστερημένη απάντηση — ήμουν σε συνάντηση όλο το πρωί και μόλις ' +
+    'τώρα βγήκα. Είδα το έγγραφο που έστειλες και, ειλικρινά, νομίζω πως είναι σχεδόν όλο εντάξει. ' +
+    'Υπάρχουν δύο τρία πράγματα που θα άλλαζα στο δεύτερο μισό, αλλά τίποτα σοβαρό. Η εισαγωγή είναι ' +
+    'γραμμένη πολύ καλά. Έχεις λίγα λεπτά να τα πούμε με την ησυχία μας; Είμαι ελεύθερος όλο το ' +
+    'απόγευμα, οπότε όποτε σε βολεύει εμένα με βολεύει. Ευχαριστώ ξανά που το ετοίμασες, ξέρω πως ' +
+    'πήρε χρόνο.',
+  uk:
+    'Привіт, вибач за пізню відповідь — я весь ранок сидів на нараді і щойно звідти вийшов. Подивився ' +
+    'документ, який ти надіслав, і чесно кажучи, мої думки такі — майже все добре. У мене є пара ' +
+    'речей, які я б змінив у другій половині, але нічого серйозного. Вступ написаний дуже добре. ' +
+    'Напиши, коли матимеш кілька хвилин, і спокійно все обговоримо. Я вільний увесь день, тобто коли тобі зручно, ' +
+    'мені теж підходить. Дякую ще раз, що зібрав це докупи, знаю, що це зайняло час.',
+  ru:
+    'Привет, извини, что долго не отвечал — всё утро просидел на встрече и только что освободился. ' +
+    'Посмотрел документ, который ты прислал, и, честно говоря, думаю, что почти всё нормально. Есть ' +
+    'пара моментов, которые я бы изменил во второй половине, но ничего серьёзного. Введение написано ' +
+    'правда хорошо. Напиши, когда будет пара свободных минут, спокойно всё обсудим. Я свободен весь ' +
+    'день, так что когда тебе удобно, мне тоже подходит. Спасибо ещё раз, что всё это собрал, знаю, ' +
+    'что это заняло время.',
+  ro:
+    'Salut, scuze pentru răspunsul întârziat — am fost toată dimineața într-o ședință și abia acum am ' +
+    'scăpat. M-am uitat pe documentul pe care mi l-ai trimis și, sincer, cred că e aproape totul ' +
+    'bine. Sunt vreo două-trei lucruri pe care le-aș schimba în a doua jumătate, dar nimic grav. ' +
+    'Introducerea e scrisă chiar bine. Spune-mi când ai câteva minute și vorbim pe îndelete despre ' +
+    'asta. Sunt liber toată după-amiaza, deci oricând îți convine mie îmi convine. Mulțumesc încă o ' +
+    'dată că ai pus totul cap la cap, știu că a durat.',
+  hu:
+    'Szia, bocs a késői válaszért — egész délelőtt gyűlésen ültem, és csak most sikerült ' +
+    'kiszabadulnom. Megnéztem a dokumentumot, amit küldtél, és őszintén szólva szerintem szinte ' +
+    'minden rendben van. Van pár dolog, amit megváltoztatnék a második felében, de semmi komoly. A ' +
+    'bevezető nagyon jól van megírva. Szólj, ha van pár szabad perced, és nyugodtan átbeszéljük. ' +
+    'Egész délután érek rá, szóval amikor neked jó, nekem is megfelel. Köszönöm még egyszer, hogy ' +
+    'összeraktad, tudom, hogy hosszú időbe telt.',
+  ja:
+    '返信が遅くなってごめん。朝からずっと会議で、今やっと抜けられたところ。送ってもらった資料、見たよ。' +
+    '正直、ほとんど問題ないと思う。後半のところで直したい部分が二つ三つあるけど、大したことじゃない。' +
+    '導入の部分はすごくよく書けてると思う。時間があるときに教えて、ゆっくり話そう。' +
+    '午後はずっと空いてるから、都合のいいときでいいよ。まとめてくれてありがとう、時間かかったよね。',
+  zh:
+    '抱歉这么晚才回你——我一早上都在开会，刚出来。你发的那份文件我看过了，说实话，大部分都挺好的。' +
+    '后半部分有几个地方我想改一下，但都不是什么大问题。开头写得真的很不错。你什么时候有空跟我说一声，我们好好聊聊。' +
+    '我整个下午都有空，所以你什么时候方便都行。再次谢谢你把这个整理出来，我知道挺花时间的。',
+  ko:
+    '답장이 늦어서 미안해. 오전 내내 회의하다가 방금 겨우 빠져나왔어. 보내준 문서 봤는데, 솔직히 거의 다 괜찮은 것 같아. 후반부에 고치고 싶은 부분이 두어 개 있긴 한데, ' +
+    '심각한 건 아니야. 서론은 진짜 잘 쓴 것 같아. 시간 될 때 얘기해줘, 그럼 차분히 얘기해보자. 오후 내내 시간 있으니까 편한 때 아무 때나 괜찮아. 정리해줘서 다시 한번 ' +
+    '고마워, 시간 좀 걸렸을 텐데.',
+  ar:
+    'مرحبًا، آسف على تأخري في الرد — كنت في اجتماع طوال الصباح ولتوّي خرجت منه. اطّلعت على المستند ' +
+    'الذي أرسلته، وبصراحة أعتقد أن معظمه جيد. هناك بعض الأشياء التي أود تغييرها في النصف الثاني، لكن ' +
+    'لا شيء خطير. المقدمة مكتوبة بشكل جيد جدًا. هل يمكن أن تخبرني متى تكون لديك بضع دقائق لنتحدث ' +
+    'بهدوء؟ أنا متفرغ طوال بعد الظهر، فأي وقت يناسبك يناسبني. شكرًا مرة أخرى على إعدادك لهذا، أعرف أن ' +
+    'الأمر استغرق وقتًا.',
+  he:
+    'היי, סליחה על התגובה המאוחרת — הייתי בישיבה כל הבוקר ורק עכשיו יצאתי. הסתכלתי על המסמך ששלחת, ' +
+    'ובכנות, אני חושב שרוב הדברים בסדר. יש כמה דברים שהייתי משנה בחצי השני, אבל שום דבר רציני. הפתיחה ' +
+    'כתובה ממש טוב. תגיד לי מתי יש לך כמה דקות ונדבר על זה בנחת. אני פנוי כל אחר הצהריים, אז מתי שנוח ' +
+    'לך נוח גם לי. תודה שוב שסידרת את זה, אני יודע שזה לקח זמן.',
+  hi:
+    'हाय, देर से जवाब देने के लिए माफ़ करना — मैं पूरी सुबह मीटिंग में था और अभी-अभी निकल पाया। तुमने ' +
+    'जो डॉक्यूमेंट भेजा था, वो देख लिया, और सच कहूं तो ज़्यादातर हिस्सा ठीक लग रहा है। दूसरे हिस्से ' +
+    'में कुछ चीज़ें हैं जो मैं बदलना चाहूंगा, पर कुछ गंभीर नहीं है। शुरुआत बहुत अच्छी लिखी गई है। जब ' +
+    'भी कुछ मिनट मिलें बता देना, फिर आराम से बात करते हैं। पूरी दोपहर मैं फ्री हूं, तो जब भी तुम्हें ' +
+    'सही लगे मुझे ठीक है। इसे तैयार करने के लिए फिर से शुक्रिया, पता है इसमें वक़्त लगा होगा।',
+};
+
+// Beam search rather than the default greedy decode (whisper.cpp ships `beam_size = -1`). It is the
+// single biggest quality lever here and it costs time, which this flow has — nothing waits on it.
+const BEAM_SIZE = 5;
+const BEST_OF = 5;
+
+// The whisper container already runs silero VAD, but its defaults assume clean dictation. Widen the
+// segments so they break at real pauses instead of at breaths, and pad the edges so word onsets are
+// not clipped — clipped onsets are what shows up in the output as a word split down the middle.
+const VAD_TUNING: Record<string, string> = {
+  vad_speech_pad_ms: '200', // default 30
+  vad_min_silence_duration_ms: '500', // default 100 — a breath is not a sentence boundary
+  vad_samples_overlap: '0.2', // default 0.1
+  vad_max_speech_duration_s: '25', // default unbounded — keep a segment inside one 30s window
+};
+
+// A silence this long reads as a new thought. Whisper reports segment times against the original
+// audio even when VAD is on (whisper.cpp maps them back through its VAD table), so these really are
+// gaps in the recording rather than artefacts of the filtering.
+const PARAGRAPH_GAP_SECONDS = 1.2;
+const MAX_PARAGRAPH_CHARS = 900;
+
+// OpenAI Whisper's own silence rule: a segment the model thinks is probably not speech *and* decodes
+// with low confidence is a hallucination rather than a transcript. whisper.cpp applies a subtly
+// different form of this internally, so it is worth re-applying to the values it reports — this is
+// what removes the stray words that appear over music and room tone.
+const NO_SPEECH_PROB = 0.6;
+const LOW_CONFIDENCE_LOGPROB = -1.0;
+
+export type WhisperSegment = {
+  text?: string;
+  start?: number;
+  end?: number;
+  no_speech_prob?: number;
+  avg_logprob?: number;
+};
+
+// Defaults are chosen so a segment missing either field is kept: dropping real speech is much worse
+// than keeping a stray word.
+const isHallucinatedSilence = (segment: WhisperSegment) =>
+  (segment.no_speech_prob ?? 0) > NO_SPEECH_PROB && (segment.avg_logprob ?? 0) < LOW_CONFIDENCE_LOGPROB;
+
+// Whisper emits each segment with a leading space and now and then strands trailing punctuation in a
+// segment of its own, which is why the old `response_format=text` output contained lone "." lines.
+const appendSegment = (paragraph: string, text: string) => {
+  if (!paragraph) return text;
+  return /^[.,;:!?…)\]]/.test(text) ? paragraph + text : `${paragraph} ${text}`;
+};
+
+// Whisper returns one segment per utterance, not per paragraph. Rejoin them into prose and start a
+// new paragraph on a long pause, so a voice memo reads as something written rather than as a list of
+// fragments.
+export function toParagraphs(segments: WhisperSegment[]): string {
+  const paragraphs: string[] = [];
+  let current = '';
+  let previousEnd: number | null = null;
+
+  for (const segment of segments) {
+    const text = (segment.text ?? '').replace(/\s+/g, ' ').trim();
+    if (!text || isHallucinatedSilence(segment)) continue;
+
+    const gap = previousEnd !== null && segment.start !== undefined ? segment.start - previousEnd : 0;
+    // Only break an over-long paragraph where a sentence actually ended, never mid-thought.
+    const overlong = current.length >= MAX_PARAGRAPH_CHARS && /[.!?…]["')\]]?$/.test(current);
+
+    if (current && (gap >= PARAGRAPH_GAP_SECONDS || overlong)) {
+      paragraphs.push(current);
+      current = '';
+    }
+
+    current = appendSegment(current, text);
+    if (segment.end !== undefined) previousEnd = segment.end;
+  }
+
+  if (current) paragraphs.push(current);
+  return paragraphs.join('\n\n');
+}
+
+export async function transcribeAudio({
+  file,
+  whisperUrl,
+  spokenLanguages,
+}: TranscribeArgs): Promise<TranscribeResult> {
+  const base = whisperUrl.replace(/\/+$/, '');
+
+  // Step 1: detect language, and only fall back to the spoken-language bias when Whisper is unsure.
+  const detectForm = new FormData();
+  detectForm.append('file', file);
+  detectForm.append('temperature', '0.0');
+  detectForm.append('response_format', 'verbose_json');
+  detectForm.append('detect_language', 'true');
+
+  const detectRes = await fetch(`${base}/inference`, {
+    method: 'POST',
+    body: detectForm,
+    timeout: false,
+  } as BunRequestInit);
+  if (!detectRes.ok) throw new Error(`Language detection failed (${detectRes.status})`);
+  const detectJson = (await detectRes.json()) as {
+    language?: string;
+    detected_language?: string;
+    detected_language_probability?: number;
+    language_probabilities?: Record<string, number>;
+  };
+
+  const probs = detectJson.language_probabilities;
+  const ranked = probs ? Object.entries(probs).sort((a, b) => b[1] - a[1]) : [];
+  const [topCode, topProb] = ranked[0] ?? [];
+
+  let detectedLanguage: string;
+  if (topCode && (topProb ?? 0) >= CONFIDENT_DETECTION) {
+    // Whisper is sure. Trust it even when it is not a language the user speaks — that is exactly the
+    // case translation exists for.
+    detectedLanguage = topCode;
+  } else if (ranked.length > 0 && spokenLanguages.length > 0) {
+    // Genuinely ambiguous (usually a short clip). Break the tie toward a language the user speaks,
+    // since Whisper's low-confidence guess defaults to English regardless of the audio.
+    const bestSpoken = spokenLanguages
+      .map((code) => [code, probs?.[code] ?? 0] as const)
+      .sort((a, b) => b[1] - a[1])[0];
+    detectedLanguage = bestSpoken?.[0] ?? topCode ?? 'en';
+  } else if (topCode) {
+    detectedLanguage = topCode;
+  } else {
+    // No probabilities field (non-whisper.cpp backend) — try to map the reported name.
+    const raw = (detectJson.detected_language ?? detectJson.language ?? 'en').toLowerCase();
+    detectedLanguage = LANG_NAME_TO_ISO[raw] ?? raw;
+  }
+
+  // Step 2: transcribe in the detected language
+  const transcribeForm = new FormData();
+  transcribeForm.append('file', file);
+  transcribeForm.append('language', detectedLanguage);
+  transcribeForm.append('temperature', '0.0');
+  transcribeForm.append('temperature_inc', '0.2');
+  transcribeForm.append('beam_size', String(BEAM_SIZE));
+  transcribeForm.append('best_of', String(BEST_OF));
+  transcribeForm.append('suppress_nst', 'true');
+  transcribeForm.append('response_format', 'verbose_json');
+  // verbose_json re-runs a full language auto-detect unless this is set. Step 1 already answered
+  // that question, so it is pure duplicated work on every transcription.
+  transcribeForm.append('no_language_probabilities', 'true');
+  // Segment timestamps drive the paragraphing below and are kept; per-token timestamps are extra
+  // work on every segment and nothing here reads them.
+  transcribeForm.append('token_timestamps', 'false');
+
+  const prompt = TRANSCRIPT_PROMPTS[detectedLanguage];
+  if (prompt) {
+    transcribeForm.append('prompt', prompt);
+    transcribeForm.append('carry_initial_prompt', 'true');
+    transcribeForm.append('max_context', String(PROMPT_CONTEXT_TOKENS));
+  } else {
+    // Nothing worth protecting the budget for, so close the loop-feeding path outright.
+    transcribeForm.append('max_context', '0');
+  }
+
+  for (const [key, value] of Object.entries(VAD_TUNING)) transcribeForm.append(key, value);
+
+  const res = await fetch(`${base}/inference`, {
+    method: 'POST',
+    body: transcribeForm,
+    timeout: false,
+  } as BunRequestInit);
+  if (!res.ok) throw new Error(`Transcription failed (${res.status})`);
+
+  const json = (await res.json()) as { text?: string; segments?: WhisperSegment[] };
+  // Fall back to the flat text for any backend that does not return segments.
+  const segments = json.segments ?? [];
+  const text = segments.length > 0 ? toParagraphs(segments) : (json.text ?? '').trim();
+
+  return { text, detectedLanguage };
+}