pi-voicekit 0.1.2 → 0.1.4

package/README.md

@@ -6,32 +6,30 @@
 > Not affiliated with the original author. Old name: `pi-listen`.
 
 <p align="center">
-  <img src="https://raw.githubusercontent.com/CyFeng16/pi-voicekit/main/assets/banner.png" alt="pi-listen — Voice input for the Pi coding agent" width="100%" />
+  <img src="https://raw.githubusercontent.com/CyFeng16/pi-voicekit/main/assets/brand/banner-en.png" alt="pi-voicekit — Voice input and output for the Pi coding agent" width="100%" />
 </p>
 
-**Hold-to-talk voice input for [Pi](https://github.com/earendil-works/pi-coding-agent).** Cloud streaming via Deepgram or fully offline with local models.
+**Voice in and voice out for [Pi](https://github.com/earendil-works/pi-coding-agent).**
+Hold-to-talk STT — Deepgram streaming (cloud) or 21 offline models — plus TTS that
+speaks the agent's replies (Kitten, Kokoro, Piper, or Deepgram Aura).
 
 [![npm version](https://img.shields.io/npm/v/pi-voicekit.svg)](https://www.npmjs.com/package/pi-voicekit)
 [![license](https://img.shields.io/npm/l/pi-voicekit.svg)](https://github.com/CyFeng16/pi-voicekit/blob/main/LICENSE)
 [![original author](https://img.shields.io/badge/original_author-@baanditeagle-1DA1F2?logo=x&logoColor=white)](https://x.com/baanditeagle)
 
-> **v7.0.0 — World-class TTS UX** — pick models from `/voice-settings` Speak
-> tab (no more JSON editing), auto-download on selection with progress, voice
-> picker for every backend, first-run onboarding with smart-default
-> recommendation by your system locale, and `ttsAutoSpeak: true` finally
-> works — auto-speaks the agent's responses with code-block stripping and
-> rate limiting. Diagnostic command `/voice-speak-info` shows everything.
-> Resume-on-interrupt downloads. Plus all v6 features (14 local models from
-> 25 MB Kitten Nano up, Deepgram Aura cloud, region-strict language matching,
-> sentence-aware chunking). [Full changelog →](CHANGELOG.md)
+> **v0.1.3 — current release** — audio capture prefers `ffmpeg` when
+> `PULSE_SERVER` is set (SSH audio tunnel / remote PulseAudio), so remote
+> microphones record reliably. Voice in **and** voice out: 21 offline STT models,
+> 20 local TTS voices plus Deepgram Aura, driven by one `/voice-settings` panel
+> with 5 tabs. The 0.1.x line is documented in the [changelog](CHANGELOG.md).
 
 ---
 
 ## See How It Works
 
 <p align="center">
-  <a href="https://github.com/CyFeng16/pi-voicekit/blob/main/assets/pi-listen.mp4">
-    <img src="https://raw.githubusercontent.com/CyFeng16/pi-voicekit/main/assets/banner.png" alt="Watch demo video" width="600" />
+  <a href="https://github.com/CyFeng16/pi-voicekit/blob/main/assets/demo/pi-voicekit-demo.mp4">
+    <img src="https://raw.githubusercontent.com/CyFeng16/pi-voicekit/main/assets/brand/banner-en.png" alt="Watch demo video" width="600" />
   </a>
   <br>
   <em>Click to watch the demo video</em>
@@ -50,7 +48,7 @@ pi install npm:pi-voicekit
 
 ### 2. Choose your backend
 
-pi-listen supports two transcription backends:
+pi-voicekit supports two transcription backends:
 
 |                  | Deepgram (cloud)                                         | Local models (offline)                              |
 | ---------------- | -------------------------------------------------------- | --------------------------------------------------- |
@@ -79,7 +77,7 @@ No setup needed — run `/voice-settings`, switch backend to Local, and select a
 
 ### 3. Open Pi
 
-On first launch, pi-listen checks your setup and tells you what's ready:
+On first launch, pi-voicekit checks your setup and tells you what's ready:
 
 - Backend configured (Deepgram key or local model)
 - Audio capture tool detected (sox, ffmpeg, or arecord)
@@ -87,7 +85,7 @@ On first launch, pi-listen checks your setup and tells you what's ready:
 
 ### Audio capture
 
-pi-listen auto-detects your audio tool. No manual install needed if you already have sox or ffmpeg.
+pi-voicekit auto-detects your audio tool. No manual install needed if you already have sox or ffmpeg.
 
 | Priority | Tool            | Platforms             | Install                                                      |
 | -------- | --------------- | --------------------- | ------------------------------------------------------------ |
@@ -95,33 +93,42 @@ pi-listen auto-detects your audio tool. No manual install needed if you already
 | 2        | **ffmpeg**      | macOS, Linux, Windows | `brew install ffmpeg` / `apt install ffmpeg`                 |
 | 3        | **arecord**     | Linux only            | Pre-installed (ALSA)                                         |
 
+> When `PULSE_SERVER` is set (SSH audio tunnel or remote PulseAudio) the order
+> becomes **ffmpeg → sox → arecord** — network Pulse sources need ffmpeg.
+
 ---
 
 ## Settings Panel
 
-All configuration lives in one place: `/voice-settings`. Four tabs cover everything you need.
+All configuration lives in one place: `/voice-settings`. Five tabs cover everything you need.
 
 ### General — backend, language, scope
 
-<img src="https://raw.githubusercontent.com/CyFeng16/pi-voicekit/main/assets/settings-general.png" alt="General settings — backend, model, language, scope, voice toggle" width="600" />
+<img src="https://raw.githubusercontent.com/CyFeng16/pi-voicekit/main/assets/screenshots/settings-general.png" alt="General settings — backend, model, language, scope, voice toggle" width="600" />
 
 Toggle between Deepgram (cloud, live streaming) and Local (offline, batch mode). Change language, scope, and enable/disable voice — all with keyboard shortcuts.
 
 ### Models — browse, search, install
 
-<img src="https://raw.githubusercontent.com/CyFeng16/pi-voicekit/main/assets/settings-models.png" alt="Models tab — browse 21 models with accuracy/speed ratings" width="600" />
+<img src="https://raw.githubusercontent.com/CyFeng16/pi-voicekit/main/assets/screenshots/settings-models.png" alt="Models tab — browse 21 models with accuracy/speed ratings" width="600" />
 
 Browse 21 models from Parakeet, Whisper, Moonshine, SenseVoice, GigaAM, Paraformer, and Qwen3. Each model shows accuracy and speed ratings (●●●●○/●●●●○), fitness badges, and download status. Fuzzy search to find models fast. Press Enter to activate and download.
 
 ### Downloaded — manage installed models
 
-<img src="https://raw.githubusercontent.com/CyFeng16/pi-voicekit/main/assets/settings-downloaded.png" alt="Downloaded tab — manage installed models, activate or delete" width="600" />
+<img src="https://raw.githubusercontent.com/CyFeng16/pi-voicekit/main/assets/screenshots/settings-downloaded.png" alt="Downloaded tab — manage installed models, activate or delete" width="600" />
 
 See what's installed, total disk usage, and which model is active. Press Enter to activate, `x` to delete. Models from [Handy](https://github.com/cjpais/handy) are auto-detected and can be imported without re-downloading.
 
+### Speak — TTS models and voices
+
+Pick a TTS backend (local sherpa-onnx or Deepgram Aura), browse 20 local voices
+from ~13 MB, download on selection, and choose a voice per backend. Auto-speak of
+agent replies is toggled here.
+
 ### Device — hardware profile and dependencies
 
-<img src="https://raw.githubusercontent.com/CyFeng16/pi-voicekit/main/assets/settings-device.png" alt="Device tab — hardware profile, dependencies, disk space" width="600" />
+<img src="https://raw.githubusercontent.com/CyFeng16/pi-voicekit/main/assets/screenshots/settings-device.png" alt="Device tab — hardware profile, dependencies, disk space" width="600" />
 
 See your hardware profile (RAM, CPU, GPU), dependency status (sherpa-onnx runtime), available disk space, and total downloaded models. Model recommendations are based on this profile.
 
@@ -133,7 +140,7 @@ See your hardware profile (RAM, CPU, GPU), dependency status (sherpa-onnx runtim
 
 | Action               | Key                  | Notes                                                                   |
 | -------------------- | -------------------- | ----------------------------------------------------------------------- |
-| **Record to editor** | Hold `SPACE` (≥1.2s) | Release to finalize. Pre-records during warmup so you don't miss words. |
+| **Record to editor** | Hold `SPACE` (≥0.7s) | Release to finalize. Pre-records during warmup so you don't miss words. |
 | **Toggle recording** | `Ctrl+Shift+V`       | Works in all terminals — press to start, press again to stop.           |
 | **Clear editor**     | `Escape` × 2         | Double-tap within 500ms to clear all text.                              |
 
@@ -150,10 +157,15 @@ See your hardware profile (RAM, CPU, GPU), dependency status (sherpa-onnx runtim
 | ------------------------ | --------------------------------------------------------- |
 | `/voice-settings`        | Settings panel — backend, models, language, scope, device |
 | `/voice-models`          | Settings panel (Models tab)                               |
+| `/voice-setup`           | Run the first-run setup wizard                            |
+| `/voice-language`        | Open the settings panel to change language                |
 | `/voice-speak <text>`    | Speak text out loud (TTS)                                 |
 | `/voice-speak-test`      | Speak a sample sentence                                   |
 | `/voice-speak-toggle`    | Enable / disable TTS                                      |
-| `/voice-autosubmit` `[on | off]`                                                     | Toggle: STT text auto-sent to the agent |
+| `/voice-stream`          | Toggle Deepgram streaming TTS (cloud)                     |
+| `/voice-speak-stop`      | Stop in-flight TTS playback                               |
+| `/voice-autosubmit`      | Toggle: STT text auto-sent to the agent (`on`/`off`)      |
+| `/voice-hold-delay`      | Set hold-to-talk delay (200-3000 ms, default 700)         |
 | `/voice-speak-models`    | Browse / install TTS voice models                         |
 | `/voice-speak-info`      | Diagnose TTS state                                        |
 | `/voice-help`            | Keyboard + command reference (or press `F1`)              |
@@ -245,10 +257,10 @@ Models from [Handy](https://github.com/cjpais/handy) (`~/Library/Application Sup
 | **Device-aware recommendations** | Scores models against your hardware. Only best-in-class models get [recommended].        |
 | **Enterprise download pipeline** | Pre-checks (disk, network, permissions), live progress with speed/ETA, post-verification |
 | **Handy integration**            | Auto-detects models from Handy app, imports via symlink                                  |
-| **Audio fallback chain**         | Tries sox, ffmpeg, arecord in order                                                      |
+| **Audio fallback chain**         | Tries sox → ffmpeg → arecord in order — ffmpeg first when `PULSE_SERVER` is set          |
 | **Pre-recording**                | Audio capture starts during warmup — you never miss the first word                       |
 | **Tail recording**               | Keeps recording 1.5s after release so your last word isn't clipped                       |
-| **Live streaming**               | Deepgram Nova 3 WebSocket — interim transcripts as you speak                             |
+| **Live streaming**               | Deepgram Nova 3 WebSocket (Nova 2 for Chinese locales) — live interim transcripts        |
 | **56+ languages**                | Deepgram: 56+ with live streaming. Local: up to 57 depending on model.                   |
 | **Continuous dictation**         | `/voice dictate` for long-form input without holding keys                                |
 | **Typing cooldown**              | Space holds within 400ms of typing are ignored                                           |
@@ -260,15 +272,47 @@ Models from [Handy](https://github.com/cjpais/handy) (`~/Library/Application Sup
 ## Architecture
 
 ```
-extensions/voice.ts                Main extension — state machine, recording, UI, settings panel
-extensions/voice/config.ts         Config loading, saving, migration
-extensions/voice/onboarding.ts     First-run wizard, language picker
-extensions/voice/deepgram.ts       Deepgram URL builder, API key resolver
-extensions/voice/local.ts          Model catalog (21 models), in-process transcription
-extensions/voice/device.ts         Device profiling — RAM, GPU, CPU, container detection
-extensions/voice/model-download.ts Download manager — resume, progress, verification, Handy import
-extensions/voice/sherpa-engine.ts   sherpa-onnx bindings — recognizer lifecycle, inference
-extensions/voice/settings-panel.ts  Settings panel — Component interface, overlay, 4 tabs
+# core
+extensions/voice.ts                         Main extension — state machine, recording, UI, command surface
+extensions/voice/config.ts                  Config loading, saving, migration
+extensions/voice/onboarding.ts              First-run wizard, language picker
+extensions/voice/audio-tool.ts              Capture tool detection (sox / ffmpeg / arecord)
+extensions/voice/hold-to-talk.ts            Hold detection, Kitty and non-Kitty terminals
+extensions/voice/release-controller.ts      Recording lifecycle, release handling
+
+# speech-to-text
+extensions/voice/deepgram.ts                Deepgram URL builder, API key resolver
+extensions/voice/local.ts                   Model catalog (21 models), in-process transcription
+extensions/voice/sherpa-engine.ts           sherpa-onnx bindings — recognizer lifecycle, inference
+extensions/voice/sherpa-loader.ts           Lazy native module loading
+extensions/voice/model-download.ts          Download manager — resume, progress, verification, Handy import
+extensions/voice/device.ts                  Device profiling — RAM, GPU, CPU, container detection
+
+# text-to-speech
+extensions/voice/speak.ts                   Speak entry point, auto-speak wiring
+extensions/voice/tts-engine.ts              sherpa-onnx TTS synthesis
+extensions/voice/tts-deepgram.ts            Deepgram Aura voices (cloud)
+extensions/voice/tts-local-models.ts        Local TTS catalog — 20 voices (Kitten, Kokoro, Piper)
+extensions/voice/tts-playback.ts            Playback, buffering, player detection
+extensions/voice/tts-text-filter.ts         Code-block stripping, sentence prep
+extensions/voice/tts-onboarding.ts          TTS onboarding flow
+extensions/voice/tts-onboarding-overlay.ts  TTS onboarding overlay
+extensions/voice/tts-install-progress.ts    Model install progress widget
+extensions/voice/tts-playback-indicator.ts  Speaking indicator widget
+
+# settings and UI
+extensions/voice/settings-panel.ts          Settings panel — overlay, 5 tabs
+extensions/voice/ui-picker.ts               Generic list picker
+extensions/voice/ui-help-overlay.ts         Keyboard and command reference
+extensions/voice/ui-aura.ts                 Visual primitives (Liquid Braille, Aurora)
+extensions/voice/ui-widget-base.ts          Widget registry and base class
+extensions/voice/ui-render-ticker.ts        Shared render ticker
+extensions/voice/ui-icons.ts                Glyph and icon set
+extensions/voice/ui-width.ts                CJK-aware visual width helpers
+extensions/voice/ui-locale-labels.ts        Native language and voice labels
+
+# types
+extensions/voice/sherpa-onnx-node.d.ts      Type declarations for the optional native module
 ```
 
 ---
@@ -300,6 +344,8 @@ Settings stored in Pi's settings files under the `voice` key:
 into `~/.pi/agent/settings.json`. If you paste a key during onboarding, that is
 an explicit save and it still goes to `~/.env.secrets` or `~/.zshrc`.
 
+Hold-to-talk delay defaults to **700 ms** (`/voice-hold-delay` accepts 200–3000 ms).
+
 ---
 
 ## Troubleshooting
@@ -310,6 +356,7 @@ Run `/voice test` inside Pi for full diagnostics.
 | ------------------------------------------------ | --------------------------------------------------------------------------------------------------------------- |
 | "DEEPGRAM_API_KEY not set"                       | [Get a key](https://dpgr.am/pi-voice) → `export DEEPGRAM_API_KEY="..."` in `~/.zshrc`                           |
 | "No audio capture tool found"                    | `brew install sox` or `brew install ffmpeg`                                                                     |
+| Remote microphone records silence                | Audio over PulseAudio/SSH — install ffmpeg on the Pi side (capture then prefers ffmpeg)                         |
 | Space doesn't activate voice                     | Run `/voice-settings` — voice may be disabled                                                                   |
 | Local model not transcribing                     | Check `/voice-settings` → Device tab for sherpa-onnx status                                                     |
 | Download failed                                  | Partial downloads auto-resume on retry. Check disk space in Device tab.                                         |
@@ -321,7 +368,7 @@ Run `/voice test` inside Pi for full diagnostics.
 
 - **Cloud STT** — audio is sent to Deepgram for transcription (Deepgram backend only)
 - **Local STT** — audio never leaves your machine (local backend)
-- **No telemetry** — pi-listen does not collect or transmit usage data
+- **No telemetry** — pi-voicekit does not collect or transmit usage data
 - **API key** — stored in env var or Pi settings, never logged
 
 See [SECURITY.md](SECURITY.md) for vulnerability reporting.

package/extensions/voice/audio-tool.ts

@@ -0,0 +1,16 @@
+/**
+ * Capture-tool preference.
+ *
+ * SoX' `rec` is the best default for local capture, but it is known to stall on
+ * network PulseAudio servers: over an SSH audio tunnel (`PULSE_SERVER` pointing at
+ * a forwarded TCP port, e.g. `tcp:127.0.0.1:4713`) the same `rec` invocation
+ * returned zero bytes in 40% of runs on this stack, while ffmpeg was reliable in
+ * every run. So when a remote Pulse server is configured, probe ffmpeg first and
+ * keep SoX as the fallback; local capture keeps SoX first.
+ */
+
+export type AudioToolName = "ffmpeg" | "sox" | "arecord";
+
+export function audioToolOrder(env: { PULSE_SERVER?: string | undefined } = process.env): AudioToolName[] {
+	return env.PULSE_SERVER ? ["ffmpeg", "sox", "arecord"] : ["sox", "ffmpeg", "arecord"];
+}

package/extensions/voice/config.ts

@@ -150,7 +150,7 @@ export function readJsonFile(filePath: string): Record<string, unknown> {
 		return JSON.parse(fs.readFileSync(filePath, "utf8"));
 	} catch (err) {
 		process.stderr.write(
-			`[pi-voice] Warning: failed to read ${filePath}: ${err instanceof Error ? err.message : err}\n`
+			`[pi-voicekit] Warning: failed to read ${filePath}: ${err instanceof Error ? err.message : err}\n`
 		);
 		return {};
 	}
@@ -303,7 +303,7 @@ export function loadGlobalToggleShortcut(options: ConfigPathOptions = {}): strin
 			const candidate = (globalVoice as any).toggleShortcut;
 			if (isValidShortcut(candidate)) return candidate;
 			process.stderr.write(
-				`[pi-voice] Warning: invalid toggleShortcut "${candidate}" in settings, using default "${fallback}"\n`
+				`[pi-voicekit] Warning: invalid toggleShortcut "${candidate}" in settings, using default "${fallback}"\n`
 			);
 		}
 	} catch {

package/extensions/voice/onboarding.ts

@@ -314,7 +314,7 @@ export function finalizeOnboardingConfig(
 }
 
 export async function promptFirstRunOnboarding(ctx: VoiceUiContext): Promise<FirstRunDecision> {
-	const choice = await ctx.ui.select("Set up pi-voice now?", ["Start voice setup", "Remind me later"]);
+	const choice = await ctx.ui.select("Set up pi-voicekit now?", ["Start voice setup", "Remind me later"]);
 
 	return { action: choice === "Start voice setup" ? "start" : "later" };
 }
@@ -665,7 +665,7 @@ export async function runVoiceOnboarding(
 	}
 
 	// ─── Choose scope ────────────────────────────────────────
-	const scopeChoice = await ctx.ui.select("Where should pi-voice settings be saved?", [
+	const scopeChoice = await ctx.ui.select("Where should pi-voicekit settings be saved?", [
 		"Global (all projects)",
 		"Project only (this repo)",
 	]);

package/extensions/voice/settings-panel.ts

@@ -193,7 +193,7 @@ export class VoiceSettingsPanel {
 		// commands remain available (panel-less).
 		if (isPanelTooNarrow(width)) {
 			return [
-				`  ${this.bold("pi-listen")}`,
+				`  ${this.bold("pi-voicekit")}`,
 				`  ${this.warning(`Terminal too narrow ${ICON.middot} resize to ${ICON.arrowRight} 60 cols`)}`,
 				`  ${this.dim("Slash commands still work: /voice-speak, /voice-models, /voice-settings")}`,
 			];
@@ -212,7 +212,7 @@ export class VoiceSettingsPanel {
 		// backend/model/voice + active language. Width-tier aware:
 		// at "mid" (60-79) the row is trimmed; at "wide" (≥80) it
 		// shows the full picture.
-		lines.push(t(`  ${this.bold("pi-listen")}  ${this.dim(this.p.formatDeviceSummary(device))}`));
+		lines.push(t(`  ${this.bold("pi-voicekit")}  ${this.dim(this.p.formatDeviceSummary(device))}`));
 		lines.push(t("  " + this.renderStatusRow(widthTier(width) === "mid")));
 		lines.push(t(this.dim("  " + "─".repeat(Math.min(iw, 60)))));
 

package/extensions/voice/tts-local-models.ts

@@ -1,5 +1,5 @@
 /**
- * Local TTS model catalog for pi-listen v6.0.0+.
+ * Local TTS model catalog for pi-voicekit.
  *
  * Three tiers:
  *   - Tier 0 (default): Kitten Nano v0.2 — 25.4 MB, 8 voices, English. The

package/extensions/voice/tts-onboarding-overlay.ts

@@ -17,7 +17,7 @@
  *
  * Visual design (no emoji per v7.1 hard constraint):
  *
- *   ┌─ pi-listen TTS ─────────────────────────────────────────────┐
+ *   ┌─ pi-voicekit TTS ─────────────────────────────────────────────┐
  *   │                                                              │
  *   │   Voice output ready.                                        │
  *   │                                                              │
@@ -90,7 +90,11 @@ export class TtsOnboardingOverlay {
 		// v7.2: rounded corners for modal feel. Title sits inline on the
 		// top edge with thin spacing so the box reads as a "sheet"
 		// rather than a hard frame (HIG modal aesthetic).
-		const top = `${ICON.boxRoundedTL}${ICON.boxH.repeat(2)} ${bold("pi-listen TTS")} ${ICON.boxH.repeat(Math.max(0, innerW - 16))}${ICON.boxRoundedTR}`;
+		// Title sits inline on the top edge; the pad is derived from the title's
+		// *visual* width so the frame stays exactly as wide as the body/bottom
+		// rows (brand length is data, not a magic constant).
+		const title = "pi-voicekit TTS";
+		const top = `${ICON.boxRoundedTL}${ICON.boxH.repeat(2)} ${bold(title)} ${ICON.boxH.repeat(Math.max(0, innerW - visualWidth(title) - 4))}${ICON.boxRoundedTR}`;
 		const bottom = `${ICON.boxRoundedBL}${ICON.boxH.repeat(innerW)}${ICON.boxRoundedBR}`;
 		const hr = `${ICON.boxV}${" ".repeat(innerW)}${ICON.boxV}`;
 		const row = (s: string): string => {
@@ -147,7 +151,7 @@ export class TtsOnboardingOverlay {
 		const dim = (s: string) => (t ? t.fg("dim", s) : s);
 		const accent = (s: string) => (t ? t.fg("accent", s) : s);
 		return [
-			` ${accent("pi-listen TTS")}`,
+			` ${accent("pi-voicekit TTS")}`,
 			` ${dim("Voice output ready. Resize to ≥60 cols for the full hint.")}`,
 			` ${accent("[↵]")} ${dim("test")}   ${accent("[m]")} ${dim("pick")}   ${accent("[esc]")} ${dim("skip")}`,
 		];

package/extensions/voice/tts-playback.ts

@@ -210,7 +210,7 @@ export interface OpenPlaybackStreamOpts {
  * Open a streaming playback sink. Returns `null` when no streaming-capable
  * player is found on PATH — the caller should fall back to the file-based
  * `play()` path. Player priority: `sox` (preferred — works on macOS via
- * homebrew, Linux via apt/yum, ships with most pi-listen STT installs) →
+ * homebrew, Linux via apt/yum, ships with most pi-voicekit STT installs) →
  * `paplay` (Linux PulseAudio) → null.
  *
  * Windows is intentionally unsupported here — PowerShell SoundPlayer
@@ -464,7 +464,7 @@ function pickStreamingPlayer(sampleRate: number): StreamingPlayerSpec | null {
 	if (process.platform === "linux" && binaryAvailable("paplay")) {
 		return {
 			cmd: "paplay",
-			args: ["--raw", `--rate=${sampleRate}`, "--format=s16le", "--channels=1", "--client-name=pi-listen"],
+			args: ["--raw", `--rate=${sampleRate}`, "--format=s16le", "--channels=1", "--client-name=pi-voicekit"],
 		};
 	}
 	// sox last-resort: cross-platform but has the macOS CoreAudio

package/extensions/voice/ui-aura.ts

@@ -1,7 +1,7 @@
 /**
  * "Auroral" visual language — v7.2 world-class polish.
  *
- * Three primitives that elevate pi-listen's visual identity from
+ * Three primitives that elevate pi-voicekit's visual identity from
  * "minimal CLI" to "premium application":
  *
  *  1. Liquid Braille waveform — sub-cell vertical bars at 4-level

package/extensions/voice/ui-help-overlay.ts

@@ -103,7 +103,7 @@ export class HelpOverlay {
 		const w = Math.max(60, Math.min(width - 2, 90));
 		const lines: string[] = [];
 		lines.push(
-			`  ${bold("pi-listen")} ${dim(ICON.middot)} ${bold("Help")} ${dim(`${ICON.middot} press [esc] to close`)}`
+			`  ${bold("pi-voicekit")} ${dim(ICON.middot)} ${bold("Help")} ${dim(`${ICON.middot} press [esc] to close`)}`
 		);
 		lines.push(`  ${dim(ICON.boxH.repeat(Math.min(w, 60)))}`);
 		for (const sec of HELP_SECTIONS) {
@@ -127,7 +127,7 @@ export class HelpOverlay {
 		const dim = (s: string) => (t ? t.fg("dim", s) : s);
 		const accent = (s: string) => (t ? t.fg("accent", s) : s);
 		const lines: string[] = [];
-		lines.push(` ${accent("pi-listen Help")}`);
+		lines.push(` ${accent("pi-voicekit Help")}`);
 		for (const sec of HELP_SECTIONS) {
 			lines.push("");
 			lines.push(` ${accent(sec.heading)}`);

package/extensions/voice/ui-locale-labels.ts

@@ -1,7 +1,7 @@
 /**
  * Native-script + gender labels for the Voice picker (§8 of v7.1 plan).
  *
- * Hand-curated for the languages pi-listen ships voices for, using the
+ * Hand-curated for the languages pi-voicekit ships voices for, using the
  * BCP-47 base-language tag (not script/region) as the lookup key. Three
  * intentional omissions:
  *

package/extensions/voice/ui-width.ts

@@ -8,7 +8,7 @@
  * two halves of nothing.
  *
  * Hand-curated EAW Wide/Fullwidth ranges from Unicode 15.1 EastAsianWidth.txt
- * — only the blocks pi-listen actually ships labels for (CJK, Hangul,
+ * — only the blocks pi-voicekit actually ships labels for (CJK, Hangul,
  * Hiragana/Katakana, fullwidth ASCII). Hindi/Devanagari and Arabic
  * intentionally NOT covered: per the v7.1 plan their voices are rendered
  * with romanized labels, so a precise width here is unnecessary and a

package/extensions/voice.ts

@@ -1,5 +1,5 @@
 /**
- * pi-voice — Enterprise-grade voice STT for Pi CLI.
+ * pi-voicekit — Enterprise-grade voice STT for Pi CLI.
  *
  * Architecture (modeled after Claude Code's voice pipeline):
  *
@@ -100,6 +100,7 @@ import {
 } from "./voice/local";
 import { shouldArmReleaseDetectOnRepeat, decideRecordingStartTimer } from "./voice/hold-to-talk";
 import { GapTimer, type TimerPort } from "./voice/release-controller";
+import { audioToolOrder, type AudioToolName } from "./voice/audio-tool";
 
 /** Adapter for the real event loop — lets GapTimer run under the real setTimeout. */
 const realTimerPort: TimerPort = {
@@ -245,87 +246,95 @@ interface AudioCaptureTool {
 	args: string[];
 }
 
-// Try available audio capture tools in order of preference
+// Try available audio capture tools in the order given by audioToolOrder()
 let _cachedAudioTool: AudioCaptureTool | null | undefined;
-function detectAudioCaptureTool(): AudioCaptureTool | null {
-	if (_cachedAudioTool !== undefined) return _cachedAudioTool;
 
-	// 1. SoX rec — purpose-built for recording, best quality
-	if (commandExists("rec")) {
-		_cachedAudioTool = {
-			name: "sox",
-			cmd: "rec",
-			args: [
-				"-q",
-				"--buffer",
-				"4096",
-				"-c",
-				String(CHANNELS),
-				"-b",
-				"16",
-				"-e",
-				"signed-integer",
-				"-t",
-				"raw",
-				"-",
-				"rate",
-				String(SAMPLE_RATE),
-			],
-		};
-		return _cachedAudioTool;
-	}
+function probeSox(): AudioCaptureTool | null {
+	if (!commandExists("rec")) return null;
+	return {
+		name: "sox",
+		cmd: "rec",
+		args: [
+			"-q",
+			"--buffer",
+			"4096",
+			"-c",
+			String(CHANNELS),
+			"-b",
+			"16",
+			"-e",
+			"signed-integer",
+			"-t",
+			"raw",
+			"-",
+			"rate",
+			String(SAMPLE_RATE),
+		],
+	};
+}
 
-	// 2. ffmpeg — widely installed, captures from default mic
-	if (commandExists("ffmpeg")) {
-		const isLinux = process.platform === "linux";
-		const isMac = process.platform === "darwin";
-		const isWin = process.platform === "win32";
-		// Input device varies by platform
-		let inputArgs: string[];
-		if (isMac) {
-			inputArgs = ["-f", "avfoundation", "-i", ":default"];
-		} else if (isLinux) {
-			inputArgs = ["-f", "pulse", "-i", "default"];
-		} else if (isWin) {
-			// DirectShow has no "default" alias — enumerate devices and pick the first audio device
-			const dshowDevice = detectWindowsAudioDevice();
-			inputArgs = dshowDevice
-				? ["-f", "dshow", "-i", `audio=${dshowDevice}`]
-				: ["-f", "dshow", "-i", "audio=Microphone"]; // last-resort guess
-		} else {
-			inputArgs = ["-f", "pulse", "-i", "default"]; // fallback for other platforms
-		}
-		_cachedAudioTool = {
-			name: "ffmpeg",
-			cmd: "ffmpeg",
-			args: [
-				...inputArgs,
-				"-ac",
-				String(CHANNELS),
-				"-ar",
-				String(SAMPLE_RATE),
-				"-sample_fmt",
-				"s16",
-				"-f",
-				"s16le",
-				"-loglevel",
-				"error",
-				"pipe:1",
-			],
-		};
-		return _cachedAudioTool;
+function probeFfmpeg(): AudioCaptureTool | null {
+	if (!commandExists("ffmpeg")) return null;
+	const isLinux = process.platform === "linux";
+	const isMac = process.platform === "darwin";
+	const isWin = process.platform === "win32";
+	// Input device varies by platform
+	let inputArgs: string[];
+	if (isMac) {
+		inputArgs = ["-f", "avfoundation", "-i", ":default"];
+	} else if (isLinux) {
+		inputArgs = ["-f", "pulse", "-i", "default"];
+	} else if (isWin) {
+		// DirectShow has no "default" alias — enumerate devices and pick the first audio device
+		const dshowDevice = detectWindowsAudioDevice();
+		inputArgs = dshowDevice ? ["-f", "dshow", "-i", `audio=${dshowDevice}`] : ["-f", "dshow", "-i", "audio=Microphone"]; // last-resort guess
+	} else {
+		inputArgs = ["-f", "pulse", "-i", "default"]; // fallback for other platforms
 	}
+	return {
+		name: "ffmpeg",
+		cmd: "ffmpeg",
+		args: [
+			...inputArgs,
+			"-ac",
+			String(CHANNELS),
+			"-ar",
+			String(SAMPLE_RATE),
+			"-sample_fmt",
+			"s16",
+			"-f",
+			"s16le",
+			"-loglevel",
+			"error",
+			"pipe:1",
+		],
+	};
+}
 
-	// 3. arecord — built into Linux ALSA, zero install
-	if (process.platform === "linux" && commandExists("arecord")) {
-		_cachedAudioTool = {
-			name: "arecord",
-			cmd: "arecord",
-			args: ["-q", "-f", "S16_LE", "-r", String(SAMPLE_RATE), "-c", String(CHANNELS), "-t", "raw"],
-		};
-		return _cachedAudioTool;
-	}
+function probeArecord(): AudioCaptureTool | null {
+	if (process.platform !== "linux" || !commandExists("arecord")) return null;
+	return {
+		name: "arecord",
+		cmd: "arecord",
+		args: ["-q", "-f", "S16_LE", "-r", String(SAMPLE_RATE), "-c", String(CHANNELS), "-t", "raw"],
+	};
+}
 
+const audioProbes: Record<AudioToolName, () => AudioCaptureTool | null> = {
+	sox: probeSox,
+	ffmpeg: probeFfmpeg,
+	arecord: probeArecord,
+};
+
+function detectAudioCaptureTool(): AudioCaptureTool | null {
+	if (_cachedAudioTool !== undefined) return _cachedAudioTool;
+	for (const name of audioToolOrder()) {
+		const tool = audioProbes[name]();
+		if (tool) {
+			_cachedAudioTool = tool;
+			return tool;
+		}
+	}
 	_cachedAudioTool = null;
 	return null;
 }
@@ -2270,7 +2279,7 @@ export default function (pi: ExtensionAPI) {
 		// actually loaded after a `pi install .` (path-installed
 		// extensions cache modules across `pi install` reinstalls — only
 		// a fresh `pi` process picks up source changes).
-		voiceDebug("pi-listen v7.1.3 loaded", { reason });
+		voiceDebug("pi-voicekit loaded", { reason });
 
 		// Migration / setup runs on EVERY session_start, regardless of reason.
 		// Only the first-run notification is gated on isStartup.
@@ -2314,7 +2323,7 @@ export default function (pi: ExtensionAPI) {
 				? `Local model: ${LOCAL_MODELS.find((m) => m.id === config.localModel)?.name || config.localModel} (offline, batch mode)`
 				: "Deepgram Nova-3 (cloud, live streaming)";
 			const lines = [
-				"pi-listen ready!",
+				"pi-voicekit ready!",
 				"",
 				"  Hold SPACE to record → release to transcribe",
 				`  ${toggleShortcutLabel} to toggle recording`,
@@ -2330,7 +2339,7 @@ export default function (pi: ExtensionAPI) {
 		// No backend configured — show install hint only on actual startup.
 		if (!isStartup) return;
 		const lines = [
-			"pi-listen installed — voice input for Pi",
+			"pi-voicekit installed — voice input for Pi",
 			"",
 			"  Two backends available:",
 			"  • Deepgram — cloud, live streaming, $200 free credit (6–12 months of use)",
@@ -2946,27 +2955,27 @@ export default function (pi: ExtensionAPI) {
 	// ─── /voice-setup → redirects to settings panel ─────────────────────────
 
 	pi.registerCommand("voice-setup", {
-		description: "Open pi-listen settings panel",
+		description: "Open pi-voicekit settings panel",
 		handler: async (_args, cmdCtx) => openSettingsPanel(cmdCtx),
 	});
 
 	// ─── /voice-language → redirects to settings panel ───────────────────────
 
 	pi.registerCommand("voice-language", {
-		description: "Open pi-listen settings to change language",
+		description: "Open pi-voicekit settings to change language",
 		handler: async (_args, cmdCtx) => openSettingsPanel(cmdCtx),
 	});
 
 	// ─── /voice-help → v7.1 §11 keyboard / command reference ────────────────
 
 	pi.registerCommand("voice-help", {
-		description: "Show pi-listen keyboard + command reference",
+		description: "Show pi-voicekit keyboard + command reference",
 		handler: async (_args, cmdCtx) => openHelpOverlay(cmdCtx),
 	});
 
 	async function openHelpOverlay(cmdCtx: ExtensionCommandContext): Promise<void> {
 		if (!cmdCtx.hasUI) {
-			cmdCtx.ui.notify("pi-listen: hold space=record · /voice-speak <text> · /voice-settings · /voice-help", "info");
+			cmdCtx.ui.notify("pi-voicekit: hold space=record · /voice-speak <text> · /voice-settings · /voice-help", "info");
 			return;
 		}
 		const { HelpOverlay } = await import("./voice/ui-help-overlay");
@@ -3628,10 +3637,10 @@ export default function (pi: ExtensionAPI) {
 		handler: async (_args, cmdCtx) => openSettingsPanel(cmdCtx, 3),
 	});
 
-	// ─── /voice-settings — unified pi-listen settings panel ─────────────
+	// ─── /voice-settings — unified pi-voicekit settings panel ─────────────
 
 	pi.registerCommand("voice-settings", {
-		description: "Open pi-listen settings — backend, models, language, device",
+		description: "Open pi-voicekit settings — backend, models, language, device",
 		handler: async (_args, cmdCtx) => openSettingsPanel(cmdCtx),
 	});
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-voicekit",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "Voice in + voice out for Pi CLI — hold-to-talk STT (Deepgram streaming or 21 offline models) plus TTS (Kitten Nano, Piper, Kokoro, or Deepgram Aura)",
   "type": "module",
   "keywords": [
@@ -46,10 +46,9 @@
     "typecheck": "bunx tsc -p tsconfig.json",
     "test": "bun test",
     "check": "bun run typecheck && bun run test",
-    "format": "bunx prettier@3.3.3 --write \"**/*.{ts,json,yml,yaml}\"",
-    "format:check": "bunx prettier@3.3.3 --check \"**/*.{ts,json,yml,yaml}\"",
-    "release:dry": "bun run check && bun publish --dry-run",
-    "release": "bun run check && bun publish --access public"
+    "format": "prettier --write \"**/*.{ts,json,yml,yaml}\"",
+    "format:check": "prettier --check \"**/*.{ts,json,yml,yaml}\"",
+    "release:dry": "bun run check && bun publish --dry-run"
   },
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": "*",
@@ -58,7 +57,8 @@
   "devDependencies": {
     "@earendil-works/pi-coding-agent": "^0.85.0",
     "@earendil-works/pi-tui": "^0.85.0",
-    "@types/ws": "^8"
+    "@types/ws": "^8",
+    "prettier": "3.3.3"
   },
   "pi": {
     "extensions": [