@agfpd/voicetalk-runtime 0.1.0 → 0.2.0

package/README.md

@@ -27,9 +27,9 @@ voicetalk gives a person presence in an [iapeer](https://github.com/agfpd/iapeer
 
 ## Quick start
 
-> Status: **text caркас (Фаза 2).** The bidirectional router loop works end to end over text; the audio touchpoints (wake-word, STT, TTS) are stubbed and land in Фаза 3 — see the roadmap below.
+> Status: **live voice (Фаза 3).** The microphone, wake words, recognition and spoken replies all run; latency tuning is Фаза 4 — see the roadmap below.
 
-You will need a working iapeer install (and, for Фаза 3, the `voice-connect` voice service).
+You will need a working iapeer install, the `voice-connect` voice service running locally, and `ffmpeg`/`ffplay` on `PATH`.
 
 ```bash
 npx @agfpd/voicetalk-runtime                      # install: binary on PATH + runtime manifest
@@ -38,17 +38,21 @@ voicetalk-runtime doctor                          # check the runtime + this pee
 ```
 
 Once a peer is created, the always-on `voicetalk-runtime run` router pumps IAP
-envelopes both directions. In Фаза 2 the inbound audio source is stubbed by a local
-injector you can drive by hand — the round trip works without a microphone:
+envelopes both directions: the microphone listens, and the owner speaks a peer's wake
+word to address it.
 
 ```bash
-voicetalk-runtime interface --wake-word "hey jarvis" --device mic0   # set the binding
+voicetalk-runtime devices                                            # list audio inputs
+voicetalk-runtime interface --wake-words "дарвин=darwin,борис=boris" \
+  --default-target darwin --device reSpeaker                         # set the binding
 # (run is launched by the foundation under the always-on supervisor)
-voicetalk-runtime say --peer linus "what's the build status"        # inject an utterance (mic+STT stand-in)
+voicetalk-runtime say --peer linus "what's the build status"         # inject an utterance without the mic (debug)
 ```
 
-An outbound peer reply arrives as an `<iap>` envelope on the router's stdin and is
-spoken by the AudioSink — a logging stub today, `voice-connect` TTS in Фаза 3.
+Say «Борис, привет» and the rest of the sentence is delivered to boris; the reply is
+spoken on the host speaker, and the mic stays open for a follow-up. `VOICETALK_AUDIO=0`
+runs the same router text-only, with no microphone at all. Configuration details:
+[`docs/`](docs/README.md).
 
 ## What makes it different
 
@@ -60,8 +64,8 @@ spoken by the AudioSink — a logging stub today, `voice-connect` TTS in Фаз
 
 ## What it does not do (yet)
 
-- No audio yet: the wake-word, STT, and TTS touchpoints are stubbed (the inbound source is a local socket injector; the outbound sink logs instead of speaking). The bidirectional **router loop itself works** over text. Audio lands in Фаза 3 via `voice-connect`.
-- Foundation integration is a coordinated step: the `voicetalk` launch-adapter and runtime classification on the iapeer side gate `iapeer create --runtime voicetalk` (Фаза 1).
+- No barge-in: the owner cannot interrupt a spoken answer by talking over it (that needs acoustic echo cancellation plus a neural VAD). While the runtime speaks, it does not listen.
+- Wake detection runs on the transcript, not on an acoustic wake-word model — so a wake word costs one line of config and no training, at the price of transcribing every voiced segment. An acoustic pre-gate is the Фаза-4 latency upgrade.
 - Single host, single owner, local microphone and speaker. Multi-device and multi-owner are out of scope for the MVP.
 
 ## Roadmap
@@ -69,7 +73,7 @@ spoken by the AudioSink — a logging stub today, `voice-connect` TTS in Фаз
 - **Фаза 0 — Scaffold.** Package skeleton, CLI stub, contract constants. **(done)**
 - **Фаза 1 — Foundation integration (iapeer).** `voicetalk` launch-adapter, runtime classification, `iapeer create --runtime voicetalk`. **(adapter code-complete; deploy coordinated with Фаза 2)**
 - **Фаза 2 — Runtime skeleton.** `runtime.json` manifest + `selfConfig` hook; `interfaces.voicetalk` schema; bidirectional router loop with a text-only IAP round-trip (audio stubbed). **(done)**
-- **Фаза 3 — Voice pipeline.** Always-on wake-word → STT (inbound), TTS → speaker (outbound) via `voice-connect`; modality framing.
+- **Фаза 3 — Voice pipeline.** Always-on microphone → endpointing → STT → wake map (inbound), TTS → speaker (outbound) via `voice-connect`; turn-taking, follow-up window, earcons. **(done)**
 - **Фаза 4 — Latency and live acceptance.** Tune the chain, conversational round-trip live.
 
 ## Documentation

package/docs/README.md

@@ -4,9 +4,9 @@ voicetalk is the voice-presence runtime of [iapeer](https://github.com/agfpd/iap
 a person speaks to the agent team aloud (wake-word + microphone) and hears replies
 from the host speaker, as one more runtime of the peer's single identity.
 
-> Status: scaffold (Фаза 0). The audio pipeline is not implemented yet. This
-> documentation describes the design; it grows as the runtime is built out across
-> Фазы 1–4. See the root [README](../README.md) for the roadmap.
+> Status: the voice pipeline is live (Фаза 3) — microphone, wake words, speech
+> recognition and spoken replies all run; latency tuning is Фаза 4. See the root
+> [README](../README.md) for the roadmap.
 
 ## Contents
 
@@ -14,7 +14,58 @@ from the host speaker, as one more runtime of the peer's single identity.
 - Quick start — operator flow (`iapeer create --runtime voicetalk`).
 - Architecture — the two-layer split (foundation adapter + runtime binary) and the
   `voice-connect` voice service it consumes.
-- Configuration — `interfaces.voicetalk` (`wake_word`, `device`).
+- Configuration — `interfaces.voicetalk`: the wake map, the default agent and the
+  input device (below).
+
+## Configuration — `interfaces.voicetalk`
+
+```jsonc
+{
+  "wake_words": { "дарвин": "darwin", "борис": "boris", "линус": "linus" },
+  "default_target": "darwin",
+  "device": "reSpeaker"            // optional: name substring or avfoundation index
+}
+```
+
+The wake word IS the address: saying a peer's word routes the rest of the sentence to
+that peer. The map is CURATED, not derived from the fleet roster — a word per each of
+30+ peers was rejected as a false-trigger source. `default_target` is the agent the
+owner reaches by default; with no map at all, that agent's own name becomes the
+activation word (`default_target: "darwin"` → «Дарвин, …»). `wake_word` (a single
+string) is the legacy form and is still read.
+
+Set it with `voicetalk-runtime interface --wake-words «дарвин=darwin,борис=boris»
+--default-target darwin --device reSpeaker`, or at provisioning time through the
+`VOICETALK_WAKE_WORDS` / `VOICETALK_DEFAULT_TARGET` / `VOICETALK_DEVICE` env of the
+self-config hook. `voicetalk-runtime devices` lists the host's inputs;
+`voicetalk-runtime doctor` reports the whole contour (binding, wake map,
+voice-connect, microphone).
+
+## How a turn works
+
+1. The microphone runs always-on; energy endpointing cuts an utterance when the
+   speaker pauses (700 ms).
+2. voice-connect transcribes the utterance (locally, on this host).
+3. If it opens by addressing a peer, the body is delivered to that peer as an IAP
+   envelope from the owner's identity, framed for the spoken modality.
+4. The agent's answer arrives on stdin, is spoken through voice-connect on the host
+   speaker, and the microphone stays open for ~9 s so the owner can continue without
+   naming the peer again.
+
+Earcons mark the states: rising = the microphone is yours, short descending = heard
+you, double descending = nothing was routed. Processing is silent.
+
+Everything is tunable by env: `VOICETALK_AUDIO=0` (text-only, no microphone),
+`VOICETALK_FOLLOWUP_MS`, `VOICETALK_HANGOVER_MS`, `VOICETALK_VAD_MIN_RMS`,
+`VOICETALK_VAD_RATIO`, `VOICETALK_STT_LANG`, `VOICETALK_STT_ENGINE`,
+`VOICETALK_TTS_MAX_CHARS`, `VOICETALK_EARCONS=0`.
+
+## Requirements
+
+- `ffmpeg` (microphone capture) and `ffplay` (playback) on `PATH`.
+- The voice-connect HTTP service running locally — it is discovered through
+  `<IAPEER_ROOT>/voice-provider.json` (override with `VOICETALK_VOICE_ENDPOINT`).
+- Microphone permission (TCC) granted once to the process that runs the runtime.
 
 These pages are written as each phase lands. Russian translation lives in
 [`ru/`](ru/README.md).

package/docs/ru/README.md

@@ -4,9 +4,9 @@ voicetalk — голосовой presence-рантайм [iapeer](https://github
 человек говорит флоту агентов вслух (wake-word + микрофон) и слышит ответы из
 динамика хоста — это ещё один рантайм единой личности пира.
 
-> Статус: каркас (Фаза 0). Голосовой пайплайн ещё не реализован. Документация
-> описывает дизайн и наполняется по мере сборки рантайма в Фазах 1–4. Дорожная
-> карта — в корневом [README](../../README.md).
+> Статус: голосовой пайплайн живой (Фаза 3) — микрофон, wake-слова, распознавание и
+> голосовые ответы работают; тюнинг латентности — Фаза 4. Дорожная карта — в корневом
+> [README](../../README.md).
 
 ## Содержание
 
@@ -14,7 +14,57 @@ voicetalk — голосовой presence-рантайм [iapeer](https://github
 - Быстрый старт — операторский поток (`iapeer create --runtime voicetalk`).
 - Архитектура — двухслойность (foundation-адаптер + бинарь рантайма) и голосовой
   сервис `voice-connect`, который voicetalk потребляет.
-- Настройка — `interfaces.voicetalk` (`wake_word`, `device`).
+- Настройка — `interfaces.voicetalk`: карта wake-слов, дефолтный агент, устройство
+  ввода (ниже).
+
+## Настройка — `interfaces.voicetalk`
+
+```jsonc
+{
+  "wake_words": { "дарвин": "darwin", "борис": "boris", "линус": "linus" },
+  "default_target": "darwin",
+  "device": "reSpeaker"            // опционально: часть имени или индекс avfoundation
+}
+```
+
+Wake-слово И ЕСТЬ адрес: произнесённое слово пира отправляет ему остаток фразы.
+Карта — КУРИРУЕМАЯ, она не выводится из ростера флота: слово на каждого из 30+ пиров
+отвергнуто как источник ложных срабатываний. `default_target` — агент по умолчанию;
+если карта не задана вовсе, словом активации становится имя самого этого агента
+(`default_target: "darwin"` → «Дарвин, …»). `wake_word` (одна строка) — легаси-форма,
+читается по-прежнему.
+
+Задаётся командой `voicetalk-runtime interface --wake-words «дарвин=darwin,борис=boris»
+--default-target darwin --device reSpeaker` либо при провижининге через env
+self-config-хука (`VOICETALK_WAKE_WORDS`, `VOICETALK_DEFAULT_TARGET`,
+`VOICETALK_DEVICE`). `voicetalk-runtime devices` показывает входы хоста,
+`voicetalk-runtime doctor` — весь контур целиком (привязка, карта, voice-connect,
+микрофон).
+
+## Как устроен ход разговора
+
+1. Микрофон слушает постоянно; энергетический эндпойнтер закрывает реплику по паузе
+   (700 мс).
+2. voice-connect распознаёт реплику (локально, на этом хосте).
+3. Если реплика начинается с обращения к пиру, тело уходит ему IAP-конвертом от
+   личности владельца, с рамкой голосовой модальности.
+4. Ответ агента приходит на stdin, озвучивается через voice-connect в динамик, и
+   микрофон остаётся открытым ~9 с — продолжить можно без повторного обращения.
+
+Earcon'ы размечают состояния: восходящий — микрофон ваш, короткий нисходящий —
+принял, двойной нисходящий — не отправлено. Обработка идёт молча.
+
+Всё настраивается через env: `VOICETALK_AUDIO=0` (текстовый режим, без микрофона),
+`VOICETALK_FOLLOWUP_MS`, `VOICETALK_HANGOVER_MS`, `VOICETALK_VAD_MIN_RMS`,
+`VOICETALK_VAD_RATIO`, `VOICETALK_STT_LANG`, `VOICETALK_STT_ENGINE`,
+`VOICETALK_TTS_MAX_CHARS`, `VOICETALK_EARCONS=0`.
+
+## Требования
+
+- `ffmpeg` (захват микрофона) и `ffplay` (воспроизведение) на `PATH`.
+- Локально запущенный HTTP-сервис voice-connect — обнаруживается через
+  `<IAPEER_ROOT>/voice-provider.json` (переопределяется `VOICETALK_VOICE_ENDPOINT`).
+- Разрешение на микрофон (TCC), выданное один раз процессу рантайма.
 
 Страницы пишутся по мере прохождения фаз.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agfpd/voicetalk-runtime",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Voice runtime-router for IAP peers.",
   "license": "Apache-2.0",
   "type": "module",

package/src/audio.ts

@@ -0,0 +1,428 @@
+// audio.ts — the host's ears and mouth: microphone capture, endpointing (VAD), WAV
+// framing and speaker playback. Everything here is host-mechanics only; not a single
+// byte of speech recognition or synthesis lives in this file (that is voice-connect).
+//
+// Capture is ffmpeg/avfoundation → raw s16le PCM on stdout, one long-lived child. The
+// segmenter turns that byte river into utterances by energy endpointing: an utterance
+// starts when speech rises above an adaptive noise floor and ends on a pause — never on
+// a fixed timer, so the speaker sets the pace (voice-UX baseline, Описание §continuation).
+
+import { spawn, type ChildProcessByStdio } from 'child_process'
+import type { Readable } from 'stream'
+import { writeFileSync } from 'fs'
+
+export const SAMPLE_RATE = 16_000
+export const FRAME_MS = 20
+export const FRAME_BYTES = (SAMPLE_RATE / 1000) * FRAME_MS * 2 // 640 B — 20 ms mono s16le
+
+// ─────────────────────────────────────────────────────────────────────────────
+// WAV framing
+// ─────────────────────────────────────────────────────────────────────────────
+
+/** Wrap raw mono s16le PCM in a canonical 44-byte WAV header (what the STT route eats). */
+export function pcmToWav(pcm: Buffer, sampleRate = SAMPLE_RATE): Buffer {
+  const header = Buffer.alloc(44)
+  header.write('RIFF', 0)
+  header.writeUInt32LE(36 + pcm.length, 4)
+  header.write('WAVE', 8)
+  header.write('fmt ', 12)
+  header.writeUInt32LE(16, 16) // PCM fmt chunk size
+  header.writeUInt16LE(1, 20) // format = PCM
+  header.writeUInt16LE(1, 22) // channels = mono
+  header.writeUInt32LE(sampleRate, 24)
+  header.writeUInt32LE(sampleRate * 2, 28) // byte rate
+  header.writeUInt16LE(2, 32) // block align
+  header.writeUInt16LE(16, 34) // bits per sample
+  header.write('data', 36)
+  header.writeUInt32LE(pcm.length, 40)
+  return Buffer.concat([header, pcm])
+}
+
+export function writeWav(pcm: Buffer, path: string, sampleRate = SAMPLE_RATE): string {
+  writeFileSync(path, pcmToWav(pcm, sampleRate), { mode: 0o600 })
+  return path
+}
+
+/** Root-mean-square amplitude of one s16le frame, 0…32767. */
+export function frameRms(frame: Buffer): number {
+  const samples = Math.floor(frame.length / 2)
+  if (samples === 0) return 0
+  let sum = 0
+  for (let i = 0; i < samples; i++) {
+    const s = frame.readInt16LE(i * 2)
+    sum += s * s
+  }
+  return Math.sqrt(sum / samples)
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// endpointing
+// ─────────────────────────────────────────────────────────────────────────────
+
+export type SegmenterOptions = {
+  /** Speech must exceed noiseFloor × this to open an utterance. */
+  ratio?: number
+  /** Absolute floor under which nothing counts as speech (dead-quiet room guard). */
+  minRms?: number
+  /** Consecutive loud frames required to open an utterance (debounce). */
+  onsetFrames?: number
+  /** Trailing silence that closes an utterance — the endpointing pause. */
+  hangoverMs?: number
+  /** Audio kept from BEFORE the onset, so the first syllable is not clipped. */
+  prerollMs?: number
+  /** Shorter than this = a cough, not an utterance. */
+  minUtteranceMs?: number
+  /** Hard cap so one long monologue still reaches STT in bounded time. */
+  maxUtteranceMs?: number
+  /** Listen-only warm-up: no utterance may open until the room's noise floor has been
+   *  measured for this long. Without it the very first frames (with the floor still
+   *  unknown) can open a segment on nothing but room tone. */
+  warmupMs?: number
+}
+
+export type Segment = {
+  pcm: Buffer
+  ms: number
+  peakRms: number
+  /** The adaptive noise floor at the moment the utterance opened, and the level it had
+   *  to clear — the two numbers that explain every capture decision in a log. */
+  noiseFloor: number
+  threshold: number
+  /** True when the cap closed the segment rather than a pause. */
+  truncated: boolean
+}
+
+/** Energy endpointer over a stream of 20 ms frames. Pure and synchronous — feed it PCM,
+ *  it hands back finished utterances; a test drives it with synthetic tone/silence. */
+export class Segmenter {
+  private readonly ratio: number
+  private readonly minRms: number
+  private readonly onsetFrames: number
+  private readonly hangoverFrames: number
+  private readonly prerollFrames: number
+  private readonly minFrames: number
+  private readonly maxFrames: number
+  private readonly warmupFrames: number
+  private seenFrames = 0
+
+  private buffer: Buffer<ArrayBufferLike> = Buffer.alloc(0)
+  private preroll: Buffer<ArrayBufferLike>[] = []
+  private speech: Buffer<ArrayBufferLike>[] = []
+  private inSpeech = false
+  private loudRun = 0
+  private silenceRun = 0
+  private peak = 0
+  private floor = -1
+
+  constructor(opts: SegmenterOptions = {}) {
+    this.ratio = opts.ratio ?? 3
+    this.minRms = opts.minRms ?? 200
+    this.onsetFrames = opts.onsetFrames ?? 3
+    this.hangoverFrames = Math.round((opts.hangoverMs ?? 900) / FRAME_MS)
+    this.prerollFrames = Math.round((opts.prerollMs ?? 320) / FRAME_MS)
+    this.minFrames = Math.round((opts.minUtteranceMs ?? 350) / FRAME_MS)
+    this.maxFrames = Math.round((opts.maxUtteranceMs ?? 18_000) / FRAME_MS)
+    this.warmupFrames = Math.round((opts.warmupMs ?? 600) / FRAME_MS)
+  }
+
+  get noiseFloor(): number {
+    return this.floor < 0 ? 0 : this.floor
+  }
+
+  /** Feed captured bytes; returns every utterance completed by this chunk. */
+  push(chunk: Buffer): Segment[] {
+    this.buffer = this.buffer.length ? Buffer.concat([this.buffer, chunk]) : chunk
+    const out: Segment[] = []
+    while (this.buffer.length >= FRAME_BYTES) {
+      const frame = this.buffer.subarray(0, FRAME_BYTES)
+      this.buffer = this.buffer.subarray(FRAME_BYTES)
+      const seg = this.pushFrame(Buffer.from(frame))
+      if (seg) out.push(seg)
+    }
+    return out
+  }
+
+  /** Abandon anything half-captured (used when the mic is gated — e.g. while the
+   *  speaker is talking — so the runtime never transcribes its own voice). */
+  reset(): void {
+    this.buffer = Buffer.alloc(0)
+    this.preroll = []
+    this.speech = []
+    this.inSpeech = false
+    this.loudRun = 0
+    this.silenceRun = 0
+    this.peak = 0
+  }
+
+  private threshold(): number {
+    const adaptive = this.floor < 0 ? this.minRms : this.floor * this.ratio
+    return Math.max(this.minRms, adaptive)
+  }
+
+  private pushFrame(frame: Buffer): Segment | null {
+    const rms = frameRms(frame)
+    this.seenFrames += 1
+    const loud = rms >= this.threshold() && this.seenFrames > this.warmupFrames
+
+    if (!this.inSpeech) {
+      // Track the room's noise floor from quiet frames only, so a long utterance can
+      // never drag the threshold up above the speaker's own voice.
+      if (!loud) this.floor = this.floor < 0 ? rms : this.floor * 0.95 + rms * 0.05
+      this.preroll.push(frame)
+      if (this.preroll.length > this.prerollFrames) this.preroll.shift()
+      this.loudRun = loud ? this.loudRun + 1 : 0
+      if (this.loudRun >= this.onsetFrames) {
+        this.inSpeech = true
+        this.speech = [...this.preroll]
+        this.preroll = []
+        this.silenceRun = 0
+        this.peak = rms
+      }
+      return null
+    }
+
+    this.speech.push(frame)
+    if (rms > this.peak) this.peak = rms
+    this.silenceRun = loud ? 0 : this.silenceRun + 1
+    if (this.silenceRun >= this.hangoverFrames) return this.close(false)
+    if (this.speech.length >= this.maxFrames) return this.close(true)
+    return null
+  }
+
+  private close(truncated: boolean): Segment | null {
+    const frames = this.speech
+    const peak = this.peak
+    const voiced = frames.length - (truncated ? 0 : this.silenceRun)
+    this.inSpeech = false
+    this.speech = []
+    this.preroll = []
+    this.loudRun = 0
+    this.silenceRun = 0
+    this.peak = 0
+    if (voiced < this.minFrames) return null
+    const pcm = Buffer.concat(frames)
+    return {
+      pcm,
+      ms: Math.round((pcm.length / 2 / SAMPLE_RATE) * 1000),
+      peakRms: peak,
+      noiseFloor: this.noiseFloor,
+      threshold: Math.round(this.threshold()),
+      truncated,
+    }
+  }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// devices + capture
+// ─────────────────────────────────────────────────────────────────────────────
+
+export type InputDevice = { index: number; name: string }
+
+function run(cmd: string, args: string[], timeoutMs = 10_000): Promise<{ code: number; stdout: string; stderr: string }> {
+  return new Promise(resolve => {
+    let stdout = ''
+    let stderr = ''
+    let done = false
+    const child = spawn(cmd, args, { stdio: ['ignore', 'pipe', 'pipe'] })
+    const timer = setTimeout(() => {
+      try {
+        child.kill('SIGKILL')
+      } catch {}
+    }, timeoutMs)
+    const finish = (code: number) => {
+      if (done) return
+      done = true
+      clearTimeout(timer)
+      resolve({ code, stdout, stderr })
+    }
+    child.stdout.on('data', d => (stdout += String(d)))
+    child.stderr.on('data', d => (stderr += String(d)))
+    child.on('error', () => finish(-1))
+    child.on('close', code => finish(code ?? -1))
+  })
+}
+
+/** Parse the avfoundation device dump — the audio section only. Exported for tests
+ *  (ffmpeg prints the listing on stderr and always exits non-zero). */
+export function parseAvfoundationAudioDevices(stderr: string): InputDevice[] {
+  const out: InputDevice[] = []
+  let inAudio = false
+  for (const line of stderr.split('\n')) {
+    if (/AVFoundation video devices:/.test(line)) inAudio = false
+    if (/AVFoundation audio devices:/.test(line)) {
+      inAudio = true
+      continue
+    }
+    if (!inAudio) continue
+    const m = /\[(\d+)\]\s+(.+?)\s*$/.exec(line.replace(/^\[AVFoundation indev[^\]]*\]\s*/, ''))
+    if (m) out.push({ index: Number(m[1]), name: m[2] })
+  }
+  return out
+}
+
+export async function listInputDevices(ffmpegBin = 'ffmpeg'): Promise<InputDevice[]> {
+  const r = await run(ffmpegBin, ['-hide_banner', '-f', 'avfoundation', '-list_devices', 'true', '-i', ''])
+  return parseAvfoundationAudioDevices(r.stderr)
+}
+
+/** Resolve `interfaces.voicetalk.device` to an avfoundation input index. A number is
+ *  taken as-is; a string is matched (case-insensitive substring) against device names;
+ *  unset = index 0, the system default input. */
+export async function resolveInputDevice(
+  spec: string | undefined,
+  ffmpegBin = 'ffmpeg',
+): Promise<{ index: number; name?: string; matched: 'default' | 'index' | 'name'; devices: InputDevice[] }> {
+  const devices = await listInputDevices(ffmpegBin)
+  if (spec === undefined || spec.trim() === '') {
+    return { index: 0, name: devices[0]?.name, matched: 'default', devices }
+  }
+  const trimmed = spec.trim()
+  if (/^\d+$/.test(trimmed)) {
+    const idx = Number(trimmed)
+    return { index: idx, name: devices.find(d => d.index === idx)?.name, matched: 'index', devices }
+  }
+  const needle = trimmed.toLowerCase()
+  const hit = devices.find(d => d.name.toLowerCase().includes(needle))
+  if (!hit) {
+    throw new Error(
+      `audio input device "${spec}" not found — available: ${devices.map(d => `[${d.index}] ${d.name}`).join(', ') || 'none'}`,
+    )
+  }
+  return { index: hit.index, name: hit.name, matched: 'name', devices }
+}
+
+export type MicOptions = {
+  deviceIndex: number
+  ffmpegBin?: string
+  onData: (chunk: Buffer) => void
+  onError?: (detail: string) => void
+  /** Called on every (re)start of the capture child — the caller logs/announces it. */
+  onStart?: (attempt: number) => void
+}
+
+/** A self-healing microphone: one ffmpeg child streaming raw PCM, restarted with backoff
+ *  if it dies (device unplugged, sleep/wake). Owns nothing else — the caller decides what
+ *  to do with the bytes. */
+export class Microphone {
+  private child: ChildProcessByStdio<null, Readable, Readable> | null = null
+  private stopped = false
+  private attempt = 0
+  private timer: ReturnType<typeof setTimeout> | null = null
+
+  constructor(private readonly opts: MicOptions) {}
+
+  start(): void {
+    this.stopped = false
+    this.spawnChild()
+  }
+
+  stop(): void {
+    this.stopped = true
+    if (this.timer) clearTimeout(this.timer)
+    this.timer = null
+    try {
+      this.child?.kill('SIGKILL')
+    } catch {}
+    this.child = null
+  }
+
+  get running(): boolean {
+    return this.child !== null
+  }
+
+  private spawnChild(): void {
+    if (this.stopped) return
+    this.attempt += 1
+    const bin = this.opts.ffmpegBin ?? 'ffmpeg'
+    const args = [
+      '-hide_banner',
+      '-loglevel', 'error',
+      '-f', 'avfoundation',
+      '-i', `:${this.opts.deviceIndex}`,
+      '-ac', '1',
+      '-ar', String(SAMPLE_RATE),
+      '-f', 's16le',
+      '-',
+    ]
+    let child: ChildProcessByStdio<null, Readable, Readable>
+    try {
+      child = spawn(bin, args, { stdio: ['ignore', 'pipe', 'pipe'] })
+    } catch (err) {
+      this.opts.onError?.(err instanceof Error ? err.message : String(err))
+      this.scheduleRestart()
+      return
+    }
+    this.child = child
+    this.opts.onStart?.(this.attempt)
+    child.stdout.on('data', (d: Buffer) => this.opts.onData(d))
+    child.stderr.on('data', (d: Buffer) => {
+      const detail = String(d).trim()
+      if (detail) this.opts.onError?.(detail)
+    })
+    child.on('error', err => this.opts.onError?.(err.message))
+    child.on('close', code => {
+      this.child = null
+      if (this.stopped) return
+      this.opts.onError?.(`capture exited (code ${code}) — restarting`)
+      this.scheduleRestart()
+    })
+  }
+
+  private scheduleRestart(): void {
+    if (this.stopped || this.timer) return
+    const delay = Math.min(30_000, 1_000 * Math.min(8, this.attempt))
+    this.timer = setTimeout(() => {
+      this.timer = null
+      this.spawnChild()
+    }, delay)
+  }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// playback + earcons
+// ─────────────────────────────────────────────────────────────────────────────
+
+/** Play a file on the system default output. `.ogg/opus` needs ffplay; WAV can go
+ *  through afplay (no ffmpeg dependency for the earcons). Resolves when playback ends. */
+export function playFile(path: string, opts: { bin?: string; timeoutMs?: number } = {}): Promise<void> {
+  const isWav = /\.wav$/i.test(path)
+  const bin = opts.bin ?? (isWav ? 'afplay' : 'ffplay')
+  const args = isWav && bin === 'afplay' ? [path] : ['-hide_banner', '-loglevel', 'error', '-nodisp', '-autoexit', path]
+  return new Promise((resolve, reject) => {
+    let settled = false
+    const child = spawn(bin, args, { stdio: ['ignore', 'ignore', 'pipe'] })
+    let stderr = ''
+    const timer = setTimeout(() => {
+      try {
+        child.kill('SIGKILL')
+      } catch {}
+    }, opts.timeoutMs ?? 180_000)
+    const finish = (err?: Error) => {
+      if (settled) return
+      settled = true
+      clearTimeout(timer)
+      err ? reject(err) : resolve()
+    }
+    child.stderr.on('data', d => (stderr += String(d)))
+    child.on('error', err => finish(new Error(`${bin}: ${err.message}`)))
+    child.on('close', code => finish(code === 0 ? undefined : new Error(`${bin} exited ${code}: ${stderr.trim().slice(0, 200)}`)))
+  })
+}
+
+/** Synthesize a short earcon (state beep) as a WAV buffer — no external process, no
+ *  network. Two-tone rising = "I heard you"; falling = "not for me / closed". */
+export function earconWav(tones: Array<{ hz: number; ms: number }>, gain = 0.22): Buffer {
+  const parts: Buffer[] = []
+  for (const tone of tones) {
+    const samples = Math.round((SAMPLE_RATE * tone.ms) / 1000)
+    const buf = Buffer.alloc(samples * 2)
+    for (let i = 0; i < samples; i++) {
+      // Raised-cosine envelope — a click-free beep.
+      const env = 0.5 - 0.5 * Math.cos((2 * Math.PI * i) / Math.max(1, samples - 1))
+      const v = Math.sin((2 * Math.PI * tone.hz * i) / SAMPLE_RATE) * env * gain
+      buf.writeInt16LE(Math.max(-32768, Math.min(32767, Math.round(v * 32767))), i * 2)
+    }
+    parts.push(buf)
+  }
+  return pcmToWav(Buffer.concat(parts))
+}