@maddeye/pi-voice 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 maddeye
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,80 @@
+# pi voice
+
+Private voice prompt input for [pi](https://github.com/earendil-works/pi-mono), transcribed locally with Whisper. Recorded audio is kept in memory and never uploaded or written to disk.
+
+## Install
+
+After the npm release:
+
+```bash
+pi install npm:@maddeye/pi-voice
+```
+
+From a local checkout:
+
+```bash
+pi install /absolute/path/to/pi-voice
+```
+
+Run `/voice-settings` once, then press **Alt+M** or run `/voice`. Press **Enter** to stop recording or **Esc** to cancel. The transcription is placed in the prompt editor for review; it is never submitted automatically.
+
+## Configuration
+
+`/voice-settings` configures the microphone, language, maximum recording length, and local model entirely inside the pi TUI. Defaults are the system microphone, English, 120 seconds, and Whisper Base.
+
+The shortcut uses pi's normal `~/.pi/agent/keybindings.json`. Change it and run `/reload`:
+
+```json
+{
+  "pi-voice.record": "alt+r"
+}
+```
+
+Use an array for multiple shortcuts or `[]` to disable the shortcut.
+
+Settings are stored in `~/.pi/agent/pi-voice.json` (or the configured pi agent directory). Models are downloaded from Hugging Face on first use and cached in `pi-voice-models/`; after that, transcription works offline. Tiny is fastest, Base is the default, and Small favors accuracy.
+
+> **Disk usage:** Runtime dependencies use about **538 MB**, mostly ONNX Runtime’s cross-platform binaries. The default quantized Whisper Base model adds about **77 MB**, for roughly **615 MB total**. Other models and package versions may vary; keep at least **1 GB free**.
+
+## Privacy
+
+- Microphone samples remain in process memory only.
+- Audio is sent only to the local Whisper model.
+- The first use of each model downloads model files from Hugging Face.
+- No API key is required.
+
+## Compatibility
+
+- Linux x86_64
+- macOS x86_64 and arm64
+- Windows x86_64 and arm64
+- Node.js 22.19 or newer
+
+The terminal running pi needs microphone permission. Native audio and ONNX binaries are included by the runtime dependencies.
+
+## Troubleshooting
+
+- **No microphone / permission denied:** grant microphone access to your terminal in macOS Privacy & Security or Windows Privacy & security. On Linux, verify PipeWire/PulseAudio can see the device.
+- **Configured microphone disappeared:** rerun `/voice-settings`; recording falls back to the system default.
+- **Model download failed:** check network access to `huggingface.co`, then retry `/voice`.
+- **Native module unsupported:** verify the OS/architecture and Node version listed above.
+- **Slow transcription:** select Tiny in `/voice-settings`.
+
+## Upgrade and removal
+
+```bash
+pi update npm:@maddeye/pi-voice
+pi remove npm:@maddeye/pi-voice
+```
+
+Removing the package does not remove downloaded models. Delete `~/.pi/agent/pi-voice-models/` and `~/.pi/agent/pi-voice.json` to remove cached data and settings.
+
+## Development
+
+```bash
+npm ci
+npm run check
+pi -e ./extensions/voice.ts
+```
+
+Before release, verify one real recording on every supported OS/architecture.

package/extensions/voice.ts

@@ -0,0 +1,300 @@
+import { readFileSync } from "node:fs";
+import { mkdir, readFile, writeFile, chmod } from "node:fs/promises";
+import { join } from "node:path";
+import { PvRecorder } from "@picovoice/pvrecorder-node";
+import {
+  BorderedLoader,
+  getAgentDir,
+  type ExtensionAPI,
+  type ExtensionContext,
+} from "@earendil-works/pi-coding-agent";
+import { Key, matchesKey, truncateToWidth } from "@earendil-works/pi-tui";
+
+const WHISPER_MODELS = {
+  "Tiny (fastest)": "Xenova/whisper-tiny",
+  "Base (balanced)": "Xenova/whisper-base",
+  "Small (best accuracy)": "Xenova/whisper-small",
+} as const;
+type WhisperModel = (typeof WHISPER_MODELS)[keyof typeof WHISPER_MODELS];
+
+interface VoiceConfig {
+  deviceName?: string;
+  language?: string;
+  maxSeconds?: number;
+  model?: WhisperModel;
+}
+
+const CONFIG_PATH = join(getAgentDir(), "pi-voice.json");
+const MODEL_CACHE = join(getAgentDir(), "pi-voice-models");
+const DEFAULT_MAX_SECONDS = 120;
+const DEFAULT_MODEL: WhisperModel = "Xenova/whisper-base";
+const DEFAULT_SHORTCUT = "alt+m";
+const SHORTCUT_SETTING = "pi-voice.record";
+
+export function parseVoiceShortcuts(value: unknown): string[] {
+  if (!value || typeof value !== "object" || !(SHORTCUT_SETTING in value)) return [DEFAULT_SHORTCUT];
+  const configured = (value as Record<string, unknown>)[SHORTCUT_SETTING];
+  if (Array.isArray(configured) && configured.length === 0) return [];
+  const shortcuts = Array.isArray(configured) ? configured : [configured];
+  const valid = [...new Set(shortcuts.filter((key): key is string => typeof key === "string" && key.trim().length > 0).map((key) => key.trim()))];
+  return valid.length ? valid : [DEFAULT_SHORTCUT];
+}
+
+function loadVoiceShortcuts(): string[] {
+  try {
+    return parseVoiceShortcuts(JSON.parse(readFileSync(join(getAgentDir(), "keybindings.json"), "utf8")));
+  } catch {
+    return [DEFAULT_SHORTCUT];
+  }
+}
+
+type LocalTranscriber = ((audio: Float32Array, options: Record<string, unknown>) => Promise<{ text: string }>) & {
+  dispose(): void | Promise<void>;
+};
+let transcriber: LocalTranscriber | undefined;
+let loadedModel: WhisperModel | undefined;
+
+async function getTranscriber(model: WhisperModel): Promise<LocalTranscriber> {
+  if (transcriber && loadedModel === model) return transcriber;
+  const previous = transcriber;
+  transcriber = undefined;
+  loadedModel = undefined;
+  await previous?.dispose();
+  await mkdir(MODEL_CACHE, { recursive: true });
+  const { env, pipeline } = await import("@huggingface/transformers");
+  env.cacheDir = MODEL_CACHE;
+  const loaded = await pipeline("automatic-speech-recognition", model, { dtype: "q8" }) as unknown as LocalTranscriber;
+  transcriber = loaded;
+  loadedModel = model;
+  return loaded;
+}
+
+export function parseConfig(value: unknown): VoiceConfig {
+  if (!value || typeof value !== "object") return {};
+  const input = value as Record<string, unknown>;
+  const config: VoiceConfig = {};
+  if (typeof input.deviceName === "string" && input.deviceName.length <= 512) config.deviceName = input.deviceName;
+  if (typeof input.language === "string" && /^[a-z]{2}$/i.test(input.language)) config.language = input.language.toLowerCase();
+  if (Number.isInteger(input.maxSeconds) && Number(input.maxSeconds) >= 5 && Number(input.maxSeconds) <= 600) {
+    config.maxSeconds = Number(input.maxSeconds);
+  }
+  if (typeof input.model === "string" && Object.values(WHISPER_MODELS).includes(input.model as WhisperModel)) {
+    config.model = input.model as WhisperModel;
+  }
+  return config;
+}
+
+export function pcmToFloat32(frames: Int16Array[]): Float32Array {
+  const audio = new Float32Array(frames.reduce((count, frame) => count + frame.length, 0));
+  let offset = 0;
+  for (const frame of frames) {
+    for (const sample of frame) audio[offset++] = sample / 32768;
+  }
+  return audio;
+}
+
+async function loadConfig(): Promise<VoiceConfig> {
+  try {
+    const raw = JSON.parse(await readFile(CONFIG_PATH, "utf8"));
+    const config = parseConfig(raw);
+    if (raw && typeof raw === "object" && "apiKey" in raw) await saveConfig(config);
+    return config;
+  } catch {
+    return {};
+  }
+}
+
+async function saveConfig(config: VoiceConfig): Promise<void> {
+  await mkdir(getAgentDir(), { recursive: true });
+  await writeFile(CONFIG_PATH, `${JSON.stringify(config, null, 2)}\n`, { mode: 0o600 });
+  if (process.platform !== "win32") await chmod(CONFIG_PATH, 0o600);
+}
+
+function availableDevices(): string[] {
+  return PvRecorder.getAvailableDevices();
+}
+
+async function configure(ctx: ExtensionContext): Promise<void> {
+  if (ctx.mode !== "tui") {
+    ctx.ui.notify("/voice-settings requires TUI mode", "error");
+    return;
+  }
+
+  const old = await loadConfig();
+  const devices = availableDevices();
+  const selectedDevice = await ctx.ui.select("Voice microphone", ["System default", ...devices]);
+  if (!selectedDevice) return;
+
+  const languageChoice = await ctx.ui.select("Whisper language", ["en", "de", "es", "fr", "Other ISO-639-1 code"]);
+  if (!languageChoice) return;
+  let language = languageChoice;
+  if (languageChoice === "Other ISO-639-1 code") {
+    const input = await ctx.ui.input("Two-letter language code", old.language ?? "en");
+    if (input === undefined) return;
+    language = input.trim().toLowerCase();
+    if (!/^[a-z]{2}$/.test(language)) {
+      ctx.ui.notify("Language must be a two-letter ISO-639-1 code", "error");
+      return;
+    }
+  }
+
+  const duration = await ctx.ui.select("Maximum recording length", ["30 seconds", "60 seconds", "120 seconds", "300 seconds", "600 seconds"]);
+  if (!duration) return;
+
+  const modelLabel = await ctx.ui.select("Local Whisper model", Object.keys(WHISPER_MODELS));
+  if (!modelLabel) return;
+
+  await saveConfig({
+    deviceName: selectedDevice === "System default" ? undefined : selectedDevice,
+    language,
+    maxSeconds: Number.parseInt(duration, 10),
+    model: WHISPER_MODELS[modelLabel as keyof typeof WHISPER_MODELS],
+  });
+  ctx.ui.notify(`Voice settings saved to ${CONFIG_PATH}`, "info");
+}
+
+async function record(ctx: ExtensionContext, config: VoiceConfig): Promise<Float32Array | null> {
+  const devices = availableDevices();
+  const deviceIndex = config.deviceName ? devices.indexOf(config.deviceName) : -1;
+  if (config.deviceName && deviceIndex < 0) ctx.ui.notify(`Microphone “${config.deviceName}” not found; using system default`, "warning");
+
+  const recorder = new PvRecorder(512, deviceIndex);
+  const frames: Int16Array[] = [];
+  let capturing = true;
+  let captureFailure: unknown;
+  let cleanupFailure: unknown;
+  let finish = (_save: boolean) => {};
+  let capture = Promise.resolve();
+  let timer: NodeJS.Timeout | undefined;
+  let save = false;
+
+  try {
+    if (recorder.sampleRate !== 16_000) {
+      throw new Error(`Local Whisper requires 16 kHz audio; recorder returned ${recorder.sampleRate} Hz`);
+    }
+    const maxSamples = recorder.sampleRate * (config.maxSeconds ?? DEFAULT_MAX_SECONDS);
+    recorder.start();
+    capture = (async () => {
+      try {
+        while (capturing && frames.length * recorder.frameLength < maxSamples) frames.push(await recorder.read());
+        if (capturing) finish(true);
+      } catch (error) {
+        if (capturing) {
+          captureFailure = error;
+          finish(false);
+        }
+      }
+    })();
+
+    const started = Date.now();
+    save = await ctx.ui.custom<boolean>((tui, theme, _keybindings, done) => {
+      finish = done;
+      timer = setInterval(() => tui.requestRender(), 250);
+      return {
+        render(width: number) {
+          const seconds = ((Date.now() - started) / 1000).toFixed(1);
+          return [
+            truncateToWidth(theme.fg("error", theme.bold(`● Recording ${seconds}s`)), width),
+            truncateToWidth(theme.fg("dim", "Enter stop and transcribe • Esc cancel"), width),
+          ];
+        },
+        invalidate() {},
+        handleInput(data: string) {
+          if (matchesKey(data, Key.enter)) done(true);
+          else if (matchesKey(data, Key.escape) || matchesKey(data, Key.ctrl("c"))) done(false);
+        },
+      };
+    });
+  } finally {
+    if (timer) clearInterval(timer);
+    capturing = false;
+    try {
+      if (recorder.isRecording) recorder.stop();
+    } catch (error) {
+      cleanupFailure = error;
+    }
+    await capture;
+    try {
+      recorder.release();
+    } catch (error) {
+      cleanupFailure ??= error;
+    }
+  }
+
+  if (captureFailure) throw captureFailure;
+  if (cleanupFailure) throw cleanupFailure;
+  return save && frames.length ? pcmToFloat32(frames) : null;
+}
+
+async function transcribe(ctx: ExtensionContext, audio: Float32Array, config: VoiceConfig): Promise<string | null> {
+  let failure: unknown;
+  const result = await ctx.ui.custom<string | null>((tui, theme, _keybindings, done) => {
+    const model = config.model ?? DEFAULT_MODEL;
+    const loader = new BorderedLoader(tui, theme, `Running ${model} locally (first use downloads the model)...`, { cancellable: false });
+    getTranscriber(model)
+      .then((pipe) => pipe(audio, {
+        ...(config.language ? { language: config.language } : {}),
+        task: "transcribe",
+        chunk_length_s: 30,
+        stride_length_s: 5,
+      }))
+      .then((output) => done(output.text.trim()))
+      .catch((error) => {
+        failure = error;
+        done(null);
+      });
+    return loader;
+  });
+  if (failure) throw failure;
+  return result;
+}
+
+export default function voiceExtension(pi: ExtensionAPI) {
+  let busy = false;
+
+  const run = async (ctx: ExtensionContext) => {
+    if (ctx.mode !== "tui") return ctx.ui.notify("Voice input requires TUI mode", "error");
+    if (!ctx.isIdle()) return ctx.ui.notify("Wait for pi to finish before recording", "warning");
+    if (busy) return ctx.ui.notify("Voice input is already active", "warning");
+    busy = true;
+    try {
+      const config = await loadConfig();
+      const audio = await record(ctx, config);
+      if (!audio) return ctx.ui.notify("Voice recording cancelled", "info");
+      const text = await transcribe(ctx, audio, config);
+      if (!text) return ctx.ui.notify("No speech detected", "warning");
+      const current = ctx.ui.getEditorText().trimEnd();
+      ctx.ui.setEditorText(current ? `${current} ${text}` : text);
+      ctx.ui.notify("Transcription added to the prompt", "info");
+    } catch (error) {
+      ctx.ui.notify(error instanceof Error ? error.message : String(error), "error");
+    } finally {
+      busy = false;
+    }
+  };
+
+  pi.registerCommand("voice", { description: "Record and transcribe voice into the prompt", handler: (_args, ctx) => run(ctx) });
+  pi.registerCommand("voice-settings", {
+    description: "Configure voice input",
+    handler: async (_args, ctx) => {
+      try {
+        await configure(ctx);
+      } catch (error) {
+        ctx.ui.notify(error instanceof Error ? error.message : String(error), "error");
+      }
+    },
+  });
+  const shortcuts = loadVoiceShortcuts();
+  for (const shortcut of shortcuts) {
+    pi.registerShortcut(shortcut as Parameters<typeof pi.registerShortcut>[0], { description: "Record a voice prompt", handler: run });
+  }
+  pi.on("session_start", (_event, ctx) => {
+    if (ctx.mode === "tui") ctx.ui.setStatus("pi-voice", shortcuts.length ? `voice: ${shortcuts.join(", ")}` : "voice: /voice");
+  });
+  pi.on("session_shutdown", async () => {
+    const loaded = transcriber;
+    transcriber = undefined;
+    loadedModel = undefined;
+    await loaded?.dispose();
+  });
+}

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@maddeye/pi-voice",
+  "version": "1.0.0",
+  "description": "Private, cross-platform voice prompt input for pi using local Whisper",
+  "license": "MIT",
+  "author": "maddeye",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/maddeye/pi-voice.git"
+  },
+  "homepage": "https://github.com/maddeye/pi-voice#readme",
+  "bugs": {
+    "url": "https://github.com/maddeye/pi-voice/issues"
+  },
+  "keywords": [
+    "pi-package",
+    "voice",
+    "whisper",
+    "speech-to-text",
+    "local-first"
+  ],
+  "type": "module",
+  "files": [
+    "extensions",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "pi": {
+    "extensions": [
+      "./extensions/voice.ts"
+    ]
+  },
+  "dependencies": {
+    "@huggingface/transformers": "4.2.0",
+    "@picovoice/pvrecorder-node": "1.2.9"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": ">=0.80.6",
+    "@earendil-works/pi-tui": ">=0.80.6"
+  },
+  "scripts": {
+    "test": "node --test tests/*.test.ts",
+    "typecheck": "tsc --noEmit",
+    "check": "npm run test && npm run typecheck",
+    "prepack": "npm run check"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "typescript": "^5.9.0"
+  }
+}