pi-voicekit 0.1.1 → 0.1.3

package/README.md

@@ -2,7 +2,7 @@
 
 # pi-voicekit
 
-> **Community continuation of [`codexstar69/pi-listen`](https://github.com/codexstar69/pi-listen)** (archived upstream, MIT).
+> **Community continuation of [`codexstar69/pi-listen`](https://github.com/codexstar69/pi-listen)** (upstream, MIT — dormant since v7.2.2 in May 2026).
 > Not affiliated with the original author. Old name: `pi-listen`.
 
 <p align="center">
@@ -109,9 +109,9 @@ Toggle between Deepgram (cloud, live streaming) and Local (offline, batch mode).
 
 ### Models — browse, search, install
 
-<img src="https://raw.githubusercontent.com/CyFeng16/pi-voicekit/main/assets/settings-models.png" alt="Models tab — browse 19 models with accuracy/speed ratings" width="600" />
+<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" />
 
-Browse 19 models from Parakeet, Whisper, Moonshine, SenseVoice, and GigaAM. Each model shows accuracy and speed ratings (●●●●○/●●●●○), fitness badges, and download status. Fuzzy search to find models fast. Press Enter to activate and download.
+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
 
@@ -189,7 +189,7 @@ in front):
 
 ## Local Models
 
-19 models across 5 families. Sorted by quality — best models first.
+21 models across 7 families. Sorted by quality — best models first.
 
 ### Top picks
 
@@ -240,7 +240,7 @@ Models from [Handy](https://github.com/cjpais/handy) (`~/Library/Application Sup
 | Feature                          | Description                                                                              |
 | -------------------------------- | ---------------------------------------------------------------------------------------- |
 | **Dual backend**                 | Deepgram (cloud, live streaming) or local models (offline, batch) — switch in settings   |
-| **19 local models**              | Parakeet, Whisper, Moonshine, SenseVoice, GigaAM — with accuracy/speed ratings           |
+| **21 local models**             | Parakeet, Whisper, Moonshine, SenseVoice, GigaAM, Paraformer, Qwen3 — with accuracy/speed ratings |
 | **Unified settings panel**       | One overlay panel for all configuration — `/voice-settings`                              |
 | **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 |
@@ -264,7 +264,7 @@ extensions/voice.ts                Main extension — state machine, recording,
 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 (19 models), in-process transcription
+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

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.ts

@@ -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;
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "pi-voicekit",
-  "version": "0.1.1",
-  "description": "Voice in + voice out for Pi CLI — hold-to-talk STT (Deepgram or 19 offline models) plus TTS (Kitten Nano, Piper, Kokoro, or Deepgram Aura)",
+  "version": "0.1.3",
+  "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": [
     "pi-package",
@@ -46,6 +46,8 @@
     "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"
   },