@agfpd/voice-connect 0.1.11

package/src/engines/f5.mjs

@@ -0,0 +1,111 @@
+/**
+ * Middle engine — F5-TTS, served on the RTX 4090 box (Windows PC, 192.168.0.141).
+ *
+ * Sits between Gemini (primary, cloud) and Supertonic (local, offline floor):
+ * a quality fallback with LIVE prosody — better than Supertonic's flat 66M
+ * model — for when Gemini's free tier is exhausted (10/day). The service is a
+ * single POST that returns a wav; we normalize it to canonical PCM via the same
+ * ffmpeg path as Supertonic (audio.mjs).
+ *
+ * Contract (verified live 2026-06-01):
+ *   POST http://192.168.0.141:8183/synthesize
+ *        {text, nfe_step:32, speed:1.0, ref_audio_b64?, ref_text?}
+ *        →  HTTP 200, audio/wav (RIFF PCM s16le, mono, 24 kHz — our canonical rate)
+ *
+ * Per-peer voice (6b): when an optional `ref` is passed (a base64 wav sample of
+ * the peer's voice + its transcript), F5 clones THAT voice, so the peer sounds
+ * like itself on an overflow. Without a ref, F5 uses its built-in default voice.
+ * This client only SENDS the ref — minting/caching it is ref.mjs's job, on the
+ * Gemini path (a ref can't be made here, where Gemini is by definition down).
+ *
+ * If F5 is unavailable — network error, non-200 (incl. the service refusing for
+ * lack of free VRAM), or timeout — we throw F5UnavailableError so the ladder
+ * falls through to Supertonic. Other failures (e.g. a malformed-but-200 body)
+ * propagate as plain errors, mirroring Gemini (only the "unavailable" class
+ * triggers the fallback; real bugs surface instead of being masked).
+ */
+import { writeFile } from 'node:fs/promises';
+import { accentPlus } from '../ruaccent.mjs';
+
+/** Full model name — the key under interfaces.voice for the F5 voice (6b). */
+export const F5_MODEL = 'f5-tts';
+/** The service's single fixed reference voice. Per-peer refs land in 6b. */
+export const DEFAULT_F5_VOICE = process.env.PEER_VOICE_F5_VOICE || 'default';
+
+const F5_URL = process.env.PEER_VOICE_F5_URL || 'http://192.168.0.141:8183/synthesize';
+// nfe_step 32 / speed 1.0 — the contract defaults. Override via env.
+const NFE_STEP = Number(process.env.PEER_VOICE_F5_NFE_STEP || '32');
+const SPEED = Number(process.env.PEER_VOICE_F5_SPEED || '1.0');
+// Short text synthesizes in ~1–2 s; a cold model + long text can be slower.
+const TIMEOUT_MS = Number(process.env.PEER_VOICE_F5_TIMEOUT_MS || '120000');
+
+/** Thrown when F5 is unavailable (network / non-200 / VRAM refusal / timeout) —
+ *  the trigger for falling through to Supertonic. */
+export class F5UnavailableError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'F5UnavailableError';
+  }
+}
+
+/**
+ * Synthesize one text to a wav file via the F5 service.
+ * @param {string} text
+ * @param {'ru'|'en'|string} lang  used only to decide Russian stress marking
+ * @param {string} wavPath         where to write the returned wav
+ * @param {{audioB64: string, text: string}|null} [ref] per-peer voice reference
+ *        (6b): a base64 wav sample + its transcript. When present, F5 clones that
+ *        voice; when absent/null, F5 uses its built-in default voice.
+ * @returns {Promise<string>} wavPath
+ */
+export async function f5TTS(text, lang, wavPath, ref = null) {
+  // Test hook: simulate F5 being down to exercise the F5→Supertonic fall
+  // without taking the real service offline. Documented; off unless set.
+  if (process.env.PEER_VOICE_SIMULATE_F5_DOWN === '1') {
+    throw new F5UnavailableError('simulated F5 down (PEER_VOICE_SIMULATE_F5_DOWN=1)');
+  }
+
+  // F5 reads the '+' stress marker natively — send the raw ruaccent output
+  // (NO U+0301 mapping, unlike Supertonic). Russian only; Gemini-style auto
+  // languages need no help. Best-effort: unaccented text on any ruaccent failure.
+  const speakText = lang === 'ru' ? await accentPlus(text) : text;
+
+  const body = { text: speakText, nfe_step: NFE_STEP, speed: SPEED };
+  // Per-peer voice (6b): clone the peer's voice from its cached reference. The
+  // ref_text is the transcript of the sample, NOT the text being synthesized.
+  if (ref && ref.audioB64 && ref.text) {
+    body.ref_audio_b64 = ref.audioB64;
+    body.ref_text = ref.text;
+  }
+
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), TIMEOUT_MS);
+  let res;
+  try {
+    res = await fetch(F5_URL, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(body),
+      signal: controller.signal,
+    });
+  } catch (err) {
+    const why = err && err.name === 'AbortError' ? `timeout ${TIMEOUT_MS}ms` : 'network';
+    throw new F5UnavailableError(`F5 request failed (${why}): ${err.message}`);
+  } finally {
+    clearTimeout(timer);
+  }
+
+  if (!res.ok) {
+    const detail = (await res.text().catch(() => '')).slice(0, 400);
+    // Any non-200 means F5 will not serve this request — including a refusal for
+    // insufficient free VRAM. Treat the whole class as "unavailable" → fall.
+    throw new F5UnavailableError(`F5 HTTP ${res.status}: ${detail}`);
+  }
+
+  const buf = Buffer.from(await res.arrayBuffer());
+  if (buf.length === 0) {
+    throw new F5UnavailableError('F5 returned an empty body');
+  }
+  await writeFile(wavPath, buf);
+  return wavPath;
+}

package/src/engines/gemini.mjs

@@ -0,0 +1,199 @@
+/**
+ * Primary engine — Gemini 3.1 Flash TTS.
+ *
+ * Recipe verified live 2026-05-31 (see MergeMind "Голосовые сообщения от
+ * агентов — дизайн"): one POST, AUDIO modality, prebuilt voice. The response
+ * carries base64 PCM s16le 24 kHz mono inline. Gemini detects language itself,
+ * so ru+en go through in a SINGLE pass — no per-language splitting needed here.
+ */
+import { readGeminiKey } from '../apikey.mjs';
+
+const MODEL = process.env.PEER_VOICE_GEMINI_MODEL || 'gemini-3.1-flash-tts-preview';
+/** Full model name — the key under interfaces.voice for the Gemini voice. */
+export const GEMINI_MODEL = MODEL;
+export const DEFAULT_GEMINI_VOICE = 'Aoede'; // verdict: fits natalya's personality
+
+/** Thrown when Gemini signals a rate/quota limit — the trigger for fallback. */
+export class GeminiQuotaError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'GeminiQuotaError';
+  }
+}
+
+/** Thrown when no Gemini key is available at all (config gap, not a limit). */
+export class GeminiNoKeyError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'GeminiNoKeyError';
+  }
+}
+
+/**
+ * Thrown when Gemini finished abnormally (finishReason ≠ STOP — e.g. MAX_TOKENS,
+ * SAFETY, RECITATION). The audio in such a response is partial/empty, so we must
+ * NOT return it silently as if it were complete. Treated as an engine-failure
+ * class like the two above: in `auto` it triggers fallback to F5/Supertonic
+ * (which have no token cap and synthesize the full text); under a forced
+ * `engine:'gemini'` it surfaces as a hard error instead of a truncated buffer.
+ */
+export class GeminiTruncatedError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'GeminiTruncatedError';
+  }
+}
+
+/**
+ * Thrown when Gemini cannot serve at all — region block (HTTP 400
+ * FAILED_PRECONDITION "User location is not supported", seen live 2026-06-12
+ * with the host VPN off), auth (401/403), 5xx, or a network failure. Mirrors
+ * the GptAudioUnavailableError posture: the whole "can't serve this" class
+ * triggers the fall to the next rung instead of killing the call — Supertonic
+ * is the OFFLINE floor, so a dead cloud rung must never surface as a hard
+ * error in `auto`.
+ */
+export class GeminiUnavailableError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'GeminiUnavailableError';
+  }
+}
+
+/** The only finishReason that means "the whole utterance was generated". */
+const FINISH_OK = 'STOP';
+
+/**
+ * Build the prompt text for a synthesis call, folding in an optional style.
+ *
+ * Gemini TTS controls delivery (tone/emotion/tempo/accent) via a natural-language
+ * directive prefixed to the text — its documented single-speaker style control,
+ * e.g. "Say cheerfully: Have a wonderful day!". The model voices only what
+ * follows the directive; the directive itself is read as guidance, not spoken.
+ * Without a style, the raw text is sent unchanged (the prior behaviour) — so we
+ * were NOT using this layer before; `style` wires it in.
+ *
+ * The unstyled `text` remains the canonical spoken content (e.g. for the F5 ref
+ * transcript) — only the synthesis prompt carries the directive.
+ * @param {string} text
+ * @param {string} [style] delivery directive
+ * @returns {string}
+ */
+export function geminiPrompt(text, style) {
+  return style && String(style).trim() ? `${String(style).trim()}: ${text}` : text;
+}
+
+/**
+ * Pull the audio out of a parsed generateContent response, enforcing a clean
+ * finish. Shared by the live path and the PEER_VOICE_SIMULATE_GEMINI_FINISH hook
+ * so the truncation check is exercised by the exact same code in both.
+ *
+ * A finishReason that is PRESENT and ≠ STOP is an abnormal stop (truncation /
+ * safety / recitation) → throw GeminiTruncatedError, even if a partial inlineData
+ * is attached. An absent finishReason is tolerated (treated as OK) so we never
+ * false-positive on a well-formed audio response that simply omits the field.
+ *
+ * @param {object} data parsed JSON from generateContent
+ * @returns {{pcm: Buffer, finishReason: string|null}}
+ */
+export function parseGeminiResponse(data) {
+  const cand = data?.candidates?.[0];
+  const finishReason = cand?.finishReason ?? null;
+  if (finishReason && finishReason !== FINISH_OK) {
+    throw new GeminiTruncatedError(
+      `Gemini finished abnormally (finishReason=${finishReason}) — audio would be ` +
+      `truncated/empty; refusing to return a partial buffer.`,
+    );
+  }
+  const b64 = cand?.content?.parts?.[0]?.inlineData?.data;
+  if (!b64) {
+    throw new Error(
+      `Gemini returned no audio inlineData: ${JSON.stringify(data).slice(0, 300)}`,
+    );
+  }
+  return { pcm: Buffer.from(b64, 'base64'), finishReason };
+}
+
+/**
+ * Synthesize one text to canonical PCM (s16le, 24 kHz, mono).
+ * @param {string} text
+ * @param {string} voice  prebuilt voice name (default Aoede)
+ * @param {string} [style] delivery directive (tone/emotion/tempo) — prefixed to
+ *                 the prompt as Gemini's natural-language style control.
+ * @returns {Promise<{pcm: Buffer, finishReason: string|null}>} raw PCM + how the
+ *          generation stopped (STOP on a clean pass; abnormal reasons throw).
+ */
+export async function geminiTTS(text, voice = DEFAULT_GEMINI_VOICE, style = undefined) {
+  // Test hook: simulate a quota limit without spending a real call, to exercise
+  // the auto-fallback routing live. Documented; off unless explicitly set.
+  if (process.env.PEER_VOICE_SIMULATE_GEMINI_429 === '1') {
+    throw new GeminiQuotaError('simulated Gemini 429 (PEER_VOICE_SIMULATE_GEMINI_429=1)');
+  }
+
+  // Test hook: simulate the can't-serve class (region block / 5xx / network)
+  // to exercise the unavailable→fall routing offline, same posture as the 429 hook.
+  if (process.env.PEER_VOICE_SIMULATE_GEMINI_UNAVAILABLE === '1') {
+    throw new GeminiUnavailableError(
+      'simulated Gemini unavailable (PEER_VOICE_SIMULATE_GEMINI_UNAVAILABLE=1)',
+    );
+  }
+
+  // Test hook: simulate a given finishReason WITHOUT a real call, so the
+  // truncation guard (and that STOP still passes) is verifiable offline. The
+  // synthetic response runs through the SAME parseGeminiResponse as the live
+  // path. e.g. PEER_VOICE_SIMULATE_GEMINI_FINISH=MAX_TOKENS → GeminiTruncatedError.
+  const simFinish = process.env.PEER_VOICE_SIMULATE_GEMINI_FINISH;
+  if (simFinish) {
+    return parseGeminiResponse({
+      candidates: [{
+        finishReason: simFinish,
+        content: { parts: [{ inlineData: { data: Buffer.from('simulated-pcm').toString('base64') } }] },
+      }],
+    });
+  }
+
+  const key = readGeminiKey();
+  if (!key) {
+    throw new GeminiNoKeyError(
+      'GEMINI_API_KEY not found in env or shell rc files (~/.zshrc ...).',
+    );
+  }
+
+  const body = {
+    contents: [{ parts: [{ text: geminiPrompt(text, style) }] }],
+    generationConfig: {
+      responseModalities: ['AUDIO'],
+      speechConfig: { voiceConfig: { prebuiltVoiceConfig: { voiceName: voice } } },
+    },
+  };
+
+  let res;
+  try {
+    res = await fetch(
+      `https://generativelanguage.googleapis.com/v1beta/models/${MODEL}:generateContent?key=${key}`,
+      {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify(body),
+      },
+    );
+  } catch (err) {
+    throw new GeminiUnavailableError(`Gemini request failed (network): ${err.message}`);
+  }
+
+  if (!res.ok) {
+    const detail = (await res.text().catch(() => '')).slice(0, 400);
+    // 429 / RESOURCE_EXHAUSTED → quota; this is the fallback trigger.
+    if (res.status === 429 || /RESOURCE_EXHAUSTED|quota/i.test(detail)) {
+      throw new GeminiQuotaError(`Gemini quota/limit (HTTP ${res.status}): ${detail}`);
+    }
+    // Region block / auth / 5xx — the whole can't-serve class → fall to the
+    // next rung (same posture as gptaudio.mjs).
+    throw new GeminiUnavailableError(`Gemini HTTP ${res.status}: ${detail}`);
+  }
+
+  const data = await res.json();
+  // Enforce a clean finishReason before trusting the buffer — a MAX_TOKENS /
+  // SAFETY stop carries partial-or-empty audio that must NOT pass as complete.
+  return parseGeminiResponse(data);
+}

package/src/engines/gptaudio.mjs

@@ -0,0 +1,230 @@
+/**
+ * Second-rung engine — OpenAI gpt-audio, served over OpenRouter.
+ *
+ * Sits between Gemini (primary, direct Google) and F5 (RTX 4090 box): a cloud
+ * quality fallback for when the direct Gemini key is exhausted (free tier 10/day)
+ * BEFORE degrading to the local rungs. Multilingual in one pass (ru+en+fr — Artur
+ * picked it after a live demo, 2026-06-01), so it is tried for ALL languages,
+ * exactly like Gemini, ahead of the language-specific F5/Supertonic split.
+ *
+ * Why NOT Gemini-via-OpenRouter: verified live 2026-06-01 that OpenRouter routes
+ * `google/gemini-3.1-flash-tts-preview` to Google but no provider serves its
+ * audio output (chat/completions → 404 "no endpoints support audio"; /audio/speech
+ * → persistent 503 "no provider"). That rung would be dead. gpt-audio is a real,
+ * served audio model — but a DIFFERENT engine/voice, not "Gemini through another
+ * provider".
+ *
+ * Contract (verified live 2026-06-01, recipe from boris/Artur + confirmed here):
+ *   POST https://openrouter.ai/api/v1/chat/completions
+ *        { model:"openai/gpt-audio", modalities:["text","audio"],
+ *          audio:{ voice, format:"pcm16" }, stream:true,
+ *          messages:[{ role:"user", content:<verbatim instruction + text> }] }
+ *   →  text/event-stream; audio arrives as base64 fragments in
+ *      choices[].delta.audio.data. Concatenating the fragments yields the full
+ *      base64 of canonical PCM (s16le, 24 kHz, mono) — decoded once, it feeds
+ *      straight into encodePcmToOgg (same canonical format as Gemini/Supertonic).
+ *
+ * It is a chat model, so it must be INSTRUCTED to voice the text verbatim (not
+ * answer it). Style (HOW to speak) is folded into that same instruction.
+ *
+ * Failures throw a typed error so the ladder falls through to F5:
+ *   - GptAudioNoKeyError    — no OPENROUTER_API_KEY (config gap)
+ *   - GptAudioQuotaError    — 429 / rate-limit / quota
+ *   - GptAudioUnavailableError — auth (401/403), 5xx / 503 no-provider, network,
+ *     timeout, or a 200 that carried no audio. The whole "can't serve this"
+ *     class → fall. Other (unexpected) errors propagate so real bugs surface.
+ */
+import { readOpenRouterKey } from '../apikey.mjs';
+
+const MODEL = process.env.PEER_VOICE_GPTAUDIO_MODEL || 'openai/gpt-audio';
+/** Full model name — the key under interfaces.voice for the gpt-audio voice. */
+export const GPTAUDIO_MODEL = MODEL;
+/** Built-in default voice (one of OpenRouter's 13: alloy, echo, fable, onyx,
+ *  nova, shimmer, coral, verse, ballad, ash, sage, marin, cedar). Per-peer voice
+ *  comes from interfaces.voice["openai/gpt-audio"] when set. */
+export const DEFAULT_GPTAUDIO_VOICE = process.env.PEER_VOICE_GPTAUDIO_VOICE || 'alloy';
+
+const OPENROUTER_URL =
+  process.env.PEER_VOICE_OPENROUTER_URL || 'https://openrouter.ai/api/v1/chat/completions';
+// Streaming completion can run minutes for long text (the async worker path).
+// One overall cap; env-tunable for ops/tests.
+const TIMEOUT_MS = Number(process.env.PEER_VOICE_GPTAUDIO_TIMEOUT_MS || '600000');
+
+/** No OPENROUTER_API_KEY configured (config gap, not a limit). */
+export class GptAudioNoKeyError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'GptAudioNoKeyError';
+  }
+}
+
+/** OpenRouter signalled a rate/quota limit — like Gemini's quota, a fall trigger. */
+export class GptAudioQuotaError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'GptAudioQuotaError';
+  }
+}
+
+/** gpt-audio could not serve the request (auth / 5xx / 503 no-provider / network /
+ *  timeout / empty audio) — the trigger for falling through to F5. */
+export class GptAudioUnavailableError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'GptAudioUnavailableError';
+  }
+}
+
+/**
+ * Build the single user-message prompt. gpt-audio is a chat model, so we must
+ * tell it to VOICE the text verbatim rather than respond to it; the optional
+ * style directive (HOW to speak) folds into the same instruction.
+ * @param {string} text  the words to speak
+ * @param {string} [style] delivery directive (tone/emotion/tempo/accent)
+ * @returns {string}
+ */
+export function buildGptAudioPrompt(text, style) {
+  const base =
+    'Read the following text aloud, exactly as written, word for word. Do not ' +
+    'translate it, do not answer it, do not add or remove anything — only voice it.';
+  const styleLine = style && String(style).trim() ? ` Speak in this style: ${String(style).trim()}.` : '';
+  return `${base}${styleLine}\n\nText:\n${text}`;
+}
+
+/**
+ * Pull the base64 audio fragment out of one SSE `data:` line, or null when the
+ * line carries no audio (comment, role/transcript delta, [DONE], unparseable).
+ * Pure — the unit-testable core of the stream reassembly.
+ * @param {string} line one line of the event stream
+ * @returns {string|null}
+ */
+export function audioB64FromDataLine(line) {
+  if (typeof line !== 'string' || !line.startsWith('data:')) return null;
+  const payload = line.slice(5).trim();
+  if (!payload || payload === '[DONE]') return null;
+  let json;
+  try {
+    json = JSON.parse(payload);
+  } catch {
+    return null;
+  }
+  const data = json?.choices?.[0]?.delta?.audio?.data;
+  return typeof data === 'string' && data.length ? data : null;
+}
+
+/**
+ * Concatenate all base64 audio fragments from a COMPLETE SSE text blob. Pure;
+ * used by tests and as the reassembly contract. Concatenating the fragments
+ * (rather than decoding each separately) is the safe choice: verified live that
+ * fragments carry no mid-stream padding, so their concatenation is itself valid
+ * base64 of the whole PCM — robust even if a fragment were split mid-unit.
+ * @param {string} sseText
+ * @returns {string} concatenated base64 (decode once with Buffer.from(_, 'base64'))
+ */
+export function collectAudioB64(sseText) {
+  let b64 = '';
+  for (const line of String(sseText).split(/\r?\n/)) {
+    const frag = audioB64FromDataLine(line);
+    if (frag) b64 += frag;
+  }
+  return b64;
+}
+
+/** Stream the SSE body via a reader, accumulating audio base64 line by line. */
+async function streamAudioB64(body) {
+  const reader = body.getReader();
+  const decoder = new TextDecoder();
+  let b64 = '';
+  let buf = '';
+  for (;;) {
+    const { value, done } = await reader.read();
+    if (done) break;
+    buf += decoder.decode(value, { stream: true });
+    let nl;
+    while ((nl = buf.indexOf('\n')) >= 0) {
+      const frag = audioB64FromDataLine(buf.slice(0, nl));
+      if (frag) b64 += frag;
+      buf = buf.slice(nl + 1);
+    }
+  }
+  buf += decoder.decode(); // flush any multibyte tail
+  for (const line of buf.split(/\r?\n/)) {
+    const frag = audioB64FromDataLine(line);
+    if (frag) b64 += frag;
+  }
+  return b64;
+}
+
+/**
+ * Synthesize one text to canonical PCM (s16le, 24 kHz, mono) via gpt-audio.
+ * @param {string} text
+ * @param {string} [voice]  one of OpenRouter's 13 gpt-audio voices
+ * @param {string} [style]  delivery directive (folded into the prompt)
+ * @returns {Promise<{pcm: Buffer}>}
+ */
+export async function gptAudioTTS(text, voice = DEFAULT_GPTAUDIO_VOICE, style = undefined) {
+  // Test hook: simulate gpt-audio being unavailable to exercise the
+  // gpt-audio→F5 fall offline. Documented; off unless explicitly set.
+  if (process.env.PEER_VOICE_SIMULATE_GPTAUDIO_DOWN === '1') {
+    throw new GptAudioUnavailableError('simulated gpt-audio down (PEER_VOICE_SIMULATE_GPTAUDIO_DOWN=1)');
+  }
+
+  const key = readOpenRouterKey();
+  if (!key) {
+    throw new GptAudioNoKeyError(
+      'OPENROUTER_API_KEY not found in env or shell rc files (~/.zshrc ...).',
+    );
+  }
+
+  const body = {
+    model: MODEL,
+    modalities: ['text', 'audio'],
+    audio: { voice, format: 'pcm16' },
+    stream: true,
+    messages: [{ role: 'user', content: buildGptAudioPrompt(text, style) }],
+  };
+
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), TIMEOUT_MS);
+  let res;
+  try {
+    res = await fetch(OPENROUTER_URL, {
+      method: 'POST',
+      headers: {
+        Authorization: `Bearer ${key}`,
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify(body),
+      signal: controller.signal,
+    });
+  } catch (err) {
+    clearTimeout(timer);
+    const why = err && err.name === 'AbortError' ? `timeout ${TIMEOUT_MS}ms` : 'network';
+    throw new GptAudioUnavailableError(`gpt-audio request failed (${why}): ${err.message}`);
+  }
+
+  if (!res.ok) {
+    clearTimeout(timer);
+    const detail = (await res.text().catch(() => '')).slice(0, 400);
+    if (res.status === 429 || /RESOURCE_EXHAUSTED|rate.?limit|quota/i.test(detail)) {
+      throw new GptAudioQuotaError(`gpt-audio quota/limit (HTTP ${res.status}): ${detail}`);
+    }
+    // 401/403 (bad key), 5xx, 503 "no provider" — the whole can't-serve class → fall.
+    throw new GptAudioUnavailableError(`gpt-audio HTTP ${res.status}: ${detail}`);
+  }
+
+  let b64;
+  try {
+    b64 = await streamAudioB64(res.body);
+  } catch (err) {
+    const why = err && err.name === 'AbortError' ? `timeout ${TIMEOUT_MS}ms` : 'stream';
+    throw new GptAudioUnavailableError(`gpt-audio stream failed (${why}): ${err.message}`);
+  } finally {
+    clearTimeout(timer);
+  }
+
+  if (!b64) {
+    throw new GptAudioUnavailableError('gpt-audio returned no audio data in the stream');
+  }
+  return { pcm: Buffer.from(b64, 'base64') };
+}

package/src/engines/mlxwhisper.mjs

@@ -0,0 +1,70 @@
+/**
+ * mlx-whisper STT engine — the local, offline transcription floor (Apple-silicon
+ * Whisper via the `mlx_whisper` CLI). Same invocation telegram-runtime uses for
+ * its fallback tier: write a .txt to a temp --output-dir, then read it back.
+ *
+ * Command override: PEER_VOICE_STT_FALLBACK_CMD (default `mlx_whisper`, empty to
+ * disable); PEER_VOICE_STT_FALLBACK_MODEL for the model flag.
+ */
+import { spawnSync } from 'node:child_process';
+import { readFileSync, mkdirSync, existsSync, rmSync } from 'node:fs';
+import { join, basename } from 'node:path';
+import { tmpdir } from 'node:os';
+import { randomBytes } from 'node:crypto';
+
+/** Thrown when the local fallback is disabled or fails. */
+export class MlxWhisperError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'MlxWhisperError';
+  }
+}
+
+/** The configured fallback command (default `mlx_whisper`; '' = disabled). */
+export function fallbackCmd() {
+  const c = process.env.PEER_VOICE_STT_FALLBACK_CMD;
+  return c === undefined ? 'mlx_whisper' : c.trim();
+}
+
+/** Pure: the .txt path mlx_whisper writes for `audioPath` inside `outDir`. */
+export function txtOutPath(outDir, audioPath) {
+  return join(outDir, basename(audioPath).replace(/\.[^.]+$/, '') + '.txt');
+}
+
+/**
+ * Transcribe an audio file with the local mlx_whisper CLI.
+ * @param {string} audioPath
+ * @param {{model?:string, lang?:string, prompt?:string, timeoutMs?:number}} [o]
+ * @returns {Promise<{text: string}>}
+ */
+export async function mlxWhisperSTT(audioPath, { model, lang, prompt, timeoutMs } = {}) {
+  const cmd = fallbackCmd();
+  if (!cmd) throw new MlxWhisperError('local STT fallback disabled (PEER_VOICE_STT_FALLBACK_CMD empty)');
+
+  const outDir = join(tmpdir(), `vc-stt-${randomBytes(6).toString('hex')}`);
+  try {
+    mkdirSync(outDir, { recursive: true });
+    const args = [audioPath, '--output-format', 'txt', '--output-dir', outDir];
+    const m = model ?? (process.env.PEER_VOICE_STT_FALLBACK_MODEL || '').trim();
+    if (m) args.push('--model', m);
+    if (lang) args.push('--language', lang);
+    if (prompt) args.push('--initial-prompt', prompt);
+
+    const r = spawnSync(cmd, args, { encoding: 'utf8', timeout: (timeoutMs || 30000) * 4 });
+    if (r.error) throw new MlxWhisperError(`${cmd} spawn error: ${r.error.message}`);
+    if (r.status !== 0) {
+      throw new MlxWhisperError(`${cmd} exit ${r.status ?? 'signal'}: ${String(r.stderr || '').slice(0, 200)}`);
+    }
+    const txtPath = txtOutPath(outDir, audioPath);
+    if (!existsSync(txtPath)) throw new MlxWhisperError('fallback produced no transcript file');
+    const text = readFileSync(txtPath, 'utf8').trim();
+    if (!text) throw new MlxWhisperError('fallback produced empty transcript');
+    return { text };
+  } finally {
+    try {
+      rmSync(outDir, { recursive: true, force: true });
+    } catch {
+      /* best-effort cleanup */
+    }
+  }
+}

package/src/engines/speaches.mjs

@@ -0,0 +1,69 @@
+/**
+ * speaches STT engine — an OpenAI-compatible POST /v1/audio/transcriptions
+ * service (speaches / faster-whisper-server). This is the same contract
+ * telegram-runtime already drives (multipart file + model/language/prompt +
+ * response_format=text), lifted here so STT lives in voice-connect's core.
+ *
+ * The endpoint is operator-configured (no universal default): PEER_VOICE_STT_ENDPOINT
+ * is the full /v1/audio/transcriptions URL. When unset, the provider is simply
+ * not applicable and the cascade falls to the local mlx-whisper floor.
+ */
+import { readFileSync } from 'node:fs';
+import { basename } from 'node:path';
+
+/** Thrown when speaches is unreachable / not configured / errors — advances STT cascade. */
+export class SpeachesUnavailableError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'SpeachesUnavailableError';
+  }
+}
+
+/** The configured endpoint URL, or '' (→ provider not applicable). */
+export function sttEndpoint() {
+  return (process.env.PEER_VOICE_STT_ENDPOINT || '').trim();
+}
+
+/** Default model name sent to the endpoint (empty → endpoint's own default). */
+export function sttModel() {
+  return (process.env.PEER_VOICE_STT_MODEL || '').trim();
+}
+
+/** Pure: normalize the transcription response body (response_format=text → plain text). */
+export function parseTranscription(body) {
+  return typeof body === 'string' ? body.trim() : '';
+}
+
+/**
+ * Transcribe an audio file via the OpenAI-compatible endpoint.
+ * @param {string} audioPath
+ * @param {{model?:string, lang?:string, prompt?:string, timeoutMs?:number, endpoint?:string}} [o]
+ * @returns {Promise<{text: string}>}
+ */
+export async function speachesSTT(audioPath, { model, lang, prompt, timeoutMs, endpoint } = {}) {
+  const url = (endpoint || sttEndpoint());
+  if (!url) throw new SpeachesUnavailableError('no STT endpoint (set PEER_VOICE_STT_ENDPOINT)');
+
+  const form = new FormData();
+  form.append('file', new File([readFileSync(audioPath)], basename(audioPath)));
+  const m = model ?? sttModel();
+  if (m) form.append('model', m);
+  if (lang) form.append('language', lang);
+  if (prompt) form.append('prompt', prompt);
+  form.append('response_format', 'text');
+
+  let res;
+  try {
+    res = await fetch(url, {
+      method: 'POST',
+      body: form,
+      signal: AbortSignal.timeout(timeoutMs || 30000),
+    });
+  } catch (err) {
+    throw new SpeachesUnavailableError(`STT endpoint request failed: ${err && err.message ? err.message : err}`);
+  }
+  if (!res.ok) throw new SpeachesUnavailableError(`STT endpoint HTTP ${res.status}`);
+  const text = parseTranscription(await res.text());
+  if (!text) throw new SpeachesUnavailableError('STT endpoint returned empty text');
+  return { text };
+}