pi-voice-input 0.2.8 → 0.2.10

package/AGENTS.md

@@ -7,7 +7,8 @@ Development workflow for this repo.
 - Package: `pi-voice-input`
 - GitHub: `git@github.com:tr-nc/pi-voice-input.git`
 - npm: `pi-voice-input`
-- Main extension: `extensions/voice-input.ts`
+- Package entrypoint: `extensions/index.ts`
+- Main extension implementation: `extensions/voice-input.ts`
 - Current provider: VolcEngine WebSocket ASR only
 - Provider architecture should remain extensible so more ASR providers can be added later.
 
@@ -25,8 +26,8 @@ Run from the repo root:
 
 ```bash
 npm install --package-lock=false
-npx tsc --noEmit --module NodeNext --moduleResolution NodeNext --target ES2022 --skipLibCheck --types node extensions/voice-input.ts
-PI_OFFLINE=1 pi -e ./extensions/voice-input.ts --list-models
+npx tsc --noEmit --module NodeNext --moduleResolution NodeNext --target ES2022 --skipLibCheck --types node extensions/index.ts
+PI_OFFLINE=1 pi -e . --list-models
 npm pack --dry-run
 ```
 
@@ -37,6 +38,7 @@ AGENTS.md
 CONTRIBUTING.md
 README.md
 ROADMAP.md
+extensions/index.ts
 extensions/voice-input.ts
 package.json
 ```
@@ -90,7 +92,7 @@ PI_OFFLINE=1 pi --list-models
 If testing a local checkout instead of the npm package, use:
 
 ```bash
-pi -e ./extensions/voice-input.ts
+pi -e .
 ```
 
 Do not leave local development wrappers in `~/.pi/agent/extensions/voice-input.ts` when validating the npm installation path.

package/CONTRIBUTING.md

@@ -41,10 +41,10 @@ cd pi-voice-input
 npm install
 ```
 
-Run the extension directly from the checkout:
+Run the package directly from the checkout:
 
 ```bash
-pi -e ./extensions/voice-input.ts
+pi -e .
 ```
 
 Or install the local checkout into pi while developing:
@@ -82,8 +82,8 @@ Do not commit this config file or any secrets.
 Before opening a pull request, run:
 
 ```bash
-npx tsc --noEmit --module NodeNext --moduleResolution NodeNext --target ES2022 --skipLibCheck --types node extensions/voice-input.ts
-PI_OFFLINE=1 pi -e ./extensions/voice-input.ts --list-models
+npx tsc --noEmit --module NodeNext --moduleResolution NodeNext --target ES2022 --skipLibCheck --types node extensions/index.ts
+PI_OFFLINE=1 pi -e . --list-models
 npm pack --dry-run
 git diff --check
 ```

package/README.md

@@ -10,23 +10,23 @@ A publishable, pure TypeScript [pi](https://pi.dev/) extension for Linux and mac
 Current scope:
 
 - Linux uses `pw-record` from PipeWire tools or `arecord` from alsa-utils.
-- macOS uses the system `afrecord` command. This path is implemented but not yet validated by the maintainer on macOS hardware.
+- macOS uses `afrecord` when present, otherwise `ffmpeg` with AVFoundation.
 - A VolcEngine Speech API key is required.
 - This is not a local/offline ASR engine.
 
 The provider layer is intended to be extensible. **Current version supports only VolcEngine WebSocket ASR.**
 
-No Python, `uv`, upload service, or `ffmpeg` is required for normal shortcut usage.
+No Python, `uv`, or upload service is required for normal shortcut usage. On macOS systems without `afrecord`, install `ffmpeg` for recording.
 
 ## Architecture
 
 ```text
-pi extension: extensions/voice-input.ts
+pi extension: extensions/index.ts → extensions/voice-input.ts
   ├─ registers Ctrl+Shift+R and /voice commands
   ├─ starts/stops a local recorder process
   │    ├─ Linux preferred: pw-record
   │    ├─ Linux fallback: arecord
-  │    └─ macOS: afrecord
+  │    └─ macOS: afrecord, or ffmpeg/AVFoundation fallback
   ├─ records a temporary 16 kHz mono 16-bit WAV
   ├─ parses the WAV container in TypeScript and extracts raw PCM
   ├─ sends PCM frames to the configured ASR provider via ws
@@ -44,9 +44,9 @@ System dependency, one of:
 
 - Linux: `pw-record` from PipeWire tools, preferred
 - Linux: `arecord` from alsa-utils, fallback
-- macOS: `afrecord`, included with macOS
+- macOS: `afrecord` when present, or `ffmpeg` from Homebrew (`brew install ffmpeg`) as the AVFoundation fallback
 
-On macOS, grant Terminal or your pi host app microphone permission when prompted. If macOS has previously denied microphone access, enable it in System Settings → Privacy & Security → Microphone.
+On macOS, grant Terminal, ffmpeg, or your pi host app microphone permission when prompted. If macOS has previously denied microphone access, enable it in System Settings → Privacy & Security → Microphone.
 
 ## Install / Update
 
@@ -164,10 +164,10 @@ cd pi-voice-input
 npm install
 ```
 
-Run directly without installing the package:
+Run directly from the package checkout:
 
 ```bash
-pi -e ./extensions/voice-input.ts
+pi -e .
 ```
 
 Or install the local checkout while developing:

package/extensions/index.ts

@@ -0,0 +1 @@
+export { default } from "./voice-input.js";

package/extensions/voice-input.ts

@@ -217,7 +217,10 @@ function commandOutput(command: string, args: string[], timeoutMs = 1500): strin
 }
 
 function selectRecorderExecutable(): string {
-  if (platform() === "darwin" && commandExists("afrecord")) return "afrecord";
+  if (platform() === "darwin") {
+    if (commandExists("afrecord")) return "afrecord";
+    if (commandExists("ffmpeg")) return "ffmpeg";
+  }
   if (commandExists("pw-record")) return "pw-record";
   if (commandExists("arecord")) return "arecord";
   return "";
@@ -237,7 +240,31 @@ function recorderCommand(config: VoiceConfig, outputPath: string): string[] {
   if (executable === "afrecord") {
     return ["afrecord", "-f", "WAVE", "-d", "LEI16@16000", "-c", "1", outputPath];
   }
-  throw new Error("No recorder found. On Linux, install PipeWire tools (pw-record) or alsa-utils (arecord). On macOS, afrecord should be available with the system.");
+  if (executable === "ffmpeg" && platform() === "darwin") {
+    return [
+      "ffmpeg",
+      "-hide_banner",
+      "-loglevel",
+      "error",
+      "-nostdin",
+      "-y",
+      "-f",
+      "avfoundation",
+      "-i",
+      config.recorderTarget || "none:default",
+      "-vn",
+      "-acodec",
+      "pcm_s16le",
+      "-ar",
+      "16000",
+      "-ac",
+      "1",
+      "-f",
+      "wav",
+      outputPath,
+    ];
+  }
+  throw new Error("No recorder found. On Linux, install PipeWire tools (pw-record) or alsa-utils (arecord). On macOS, install ffmpeg (brew install ffmpeg) if afrecord is not available.");
 }
 
 type PipeWireSource = {
@@ -326,6 +353,7 @@ function recordingDeviceName(config: VoiceConfig, recorderExecutable: string): s
   if (recorderExecutable === "pw-record") return pipeWireSourceName(config.recorderTarget);
   if (recorderExecutable === "arecord") return "ALSA default microphone";
   if (recorderExecutable === "afrecord") return "macOS default microphone";
+  if (recorderExecutable === "ffmpeg" && platform() === "darwin") return "macOS default microphone (ffmpeg/AVFoundation)";
   return config.recorderTarget || "default microphone";
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-voice-input",
-  "version": "0.2.8",
+  "version": "0.2.10",
   "description": "Press Ctrl+Shift+R to dictate prompts into Pi using VolcEngine ASR",
   "type": "module",
   "keywords": [
@@ -34,7 +34,7 @@
   ],
   "pi": {
     "extensions": [
-      "extensions"
+      "extensions/index.ts"
     ]
   },
   "dependencies": {