@tychenjiajun/pi-voice 0.0.0-stage → 0.2.0

package/index.ts

@@ -0,0 +1 @@
+export { default } from "./src/index.ts";

package/package.json

@@ -1,6 +1,70 @@
 {
   "name": "@tychenjiajun/pi-voice",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "Speech-to-text for Pi (local model or OpenAI-compatible remote ASR)",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/tychenjiajun/pi-voice.git"
+  },
+  "homepage": "https://github.com/tychenjiajun/pi-voice#readme",
+  "bugs": {
+    "url": "https://github.com/tychenjiajun/pi-voice/issues"
+  },
+  "files": [
+    "src",
+    "index.ts",
+    "catalog/recommendations.json",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "voice",
+    "dictation",
+    "transcription",
+    "speech-to-text"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "check": "tsc --noEmit",
+    "test": "npm run check && node scripts/run-tests.mjs",
+    "prepublishOnly": "npm test",
+    "catalog:generate": "node scripts/generate-catalog.mjs",
+    "recommendations:generate": "node scripts/generate-recommendations.mjs",
+    "catalog:verify": "node scripts/catalog-metadata.mjs",
+    "catalog:update-metadata": "node scripts/catalog-metadata.mjs --write"
+  },
+  "pi": {
+    "extensions": [
+      "./index.ts"
+    ]
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*",
+    "typebox": "*"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "0.83.0",
+    "@earendil-works/pi-tui": "^0.83.0",
+    "@huggingface/gguf": "^0.4.6",
+    "@types/node": "22.20.1",
+    "typebox": "^1.3.7",
+    "typescript": "5.9.3"
+  },
+  "dependencies": {
+    "@handy-computer/recorder": "0.1.0",
+    "@huggingface/hub": "2.15.0",
+    "openai": "^7.31.0",
+    "opencc-js": "^1.4.1",
+    "transcribe-cpp": "0.2.4"
+  }
+}

package/src/async-limiter.ts

@@ -0,0 +1,77 @@
+type Waiter = {
+  signal?: AbortSignal;
+  resolve: (release: () => void) => void;
+  reject: (error: unknown) => void;
+  onAbort?: () => void;
+};
+
+/** Bounds async work without starting queued tasks until a permit is available. */
+export class AsyncLimiter {
+  private active = 0;
+  private readonly waiters: Waiter[] = [];
+
+  constructor(private readonly concurrency: number) {
+    if (!Number.isInteger(concurrency) || concurrency < 1) {
+      throw new Error("AsyncLimiter concurrency must be a positive integer");
+    }
+  }
+
+  get saturated(): boolean {
+    return this.active >= this.concurrency;
+  }
+
+  async run<T>(task: () => Promise<T>, signal?: AbortSignal): Promise<T> {
+    const release = await this.acquire(signal);
+    try {
+      signal?.throwIfAborted();
+      return await task();
+    } finally {
+      release();
+    }
+  }
+
+  private acquire(signal?: AbortSignal): Promise<() => void> {
+    signal?.throwIfAborted();
+    if (this.active < this.concurrency) {
+      this.active += 1;
+      return Promise.resolve(this.createRelease());
+    }
+
+    return new Promise<() => void>((resolve, reject) => {
+      const waiter: Waiter = { signal, resolve, reject };
+      if (signal) {
+        waiter.onAbort = () => {
+          const index = this.waiters.indexOf(waiter);
+          if (index >= 0) this.waiters.splice(index, 1);
+          reject(signal.reason ?? new Error("Operation cancelled"));
+        };
+        signal.addEventListener("abort", waiter.onAbort, { once: true });
+      }
+      this.waiters.push(waiter);
+    });
+  }
+
+  private createRelease(): () => void {
+    let released = false;
+    return () => {
+      if (released) return;
+      released = true;
+      this.release();
+    };
+  }
+
+  private release(): void {
+    while (this.waiters.length > 0) {
+      const waiter = this.waiters.shift()!;
+      if (waiter.onAbort) waiter.signal?.removeEventListener("abort", waiter.onAbort);
+      if (waiter.signal?.aborted) {
+        waiter.reject(waiter.signal.reason ?? new Error("Operation cancelled"));
+        continue;
+      }
+      // Transfer the active permit directly to the next waiter.
+      waiter.resolve(this.createRelease());
+      return;
+    }
+    this.active -= 1;
+  }
+}

package/src/audio-constants.ts

@@ -0,0 +1 @@
+export const CAPTURE_SAMPLE_RATE = 16_000;

package/src/audio-errors.ts

@@ -0,0 +1,14 @@
+/**
+ * Recorder errors, matched structurally so eagerly loaded modules need not
+ * load the native recorder that audio.ts imports.
+ */
+function recorderErrorCode(error: unknown): string | undefined {
+  if (!(error instanceof Error) || error.name !== "RecorderError") return undefined;
+  const { code } = error as Error & { code?: unknown };
+  return typeof code === "string" ? code : undefined;
+}
+
+/** macOS refused the terminal microphone access; the fix is in System Settings. */
+export function isMacOSPermissionDenied(error: unknown): boolean {
+  return process.platform === "darwin" && recorderErrorCode(error) === "PermissionDenied";
+}

package/src/audio.ts

@@ -0,0 +1,109 @@
+import {
+  listInputDevices,
+  permissionStatus,
+  Recorder,
+  setLogHandler,
+  type InputDevice,
+  type Permission,
+  type Recording,
+} from "@handy-computer/recorder";
+import { CAPTURE_SAMPLE_RATE } from "./audio-constants.js";
+import type { Capture, CaptureSinks } from "./dictation-controller.js";
+import { logLevel, writeLog } from "./log.js";
+import type { MicrophoneSetting } from "./settings.js";
+
+export type { InputDevice, Permission };
+
+// The recorder's own log into Pi Voice's, stamped with when each line was
+// written: lines from a blocked event loop arrive late but sort correctly.
+const level = logLevel();
+if (level) {
+  setLogHandler(
+    (record) => writeLog(record.level === "trace" ? "debug" : record.level, "recorder", record.message, record.timeMs),
+    { level: level === "debug" ? "debug" : "info" },
+  );
+}
+
+/** 32 ms chunks: a power of two, so the meter's FFT uses every sample. */
+const FRAMES_PER_CHUNK = 512;
+
+export class MicrophoneUnavailableError extends Error {
+  constructor(name: string) {
+    super(`Selected microphone is unavailable: ${name}. Open /voice-settings and choose another microphone.`);
+    this.name = "MicrophoneUnavailableError";
+  }
+}
+
+/** Input devices to offer, without PulseAudio monitors of outputs. */
+export async function getAvailableMicrophones(): Promise<InputDevice[]> {
+  return (await listInputDevices()).filter((device) => !device.isMonitor);
+}
+
+/** A synchronous read that never prompts. */
+export function microphonePermission(): Permission {
+  return permissionStatus();
+}
+
+export function findMicrophone(
+  devices: readonly InputDevice[],
+  selected: { name: string; occurrence: number },
+): InputDevice | undefined {
+  return devices.find((device) => device.name === selected.name && device.occurrence === selected.occurrence);
+}
+
+function interruption(recording: Recording): Error | undefined {
+  const { endReason } = recording;
+  if (endReason.kind === "recorderFailed") {
+    // Access revoked mid-recording (or refused at the first prompt): what
+    // was captured is silence, so fail the take and let the user fix it.
+    if (endReason.error.code === "PermissionDenied") throw endReason.error;
+    return endReason.error;
+  }
+  if (endReason.kind === "sinkPanicked") return new Error(endReason.message);
+  return undefined;
+}
+
+/** Opens the microphone and starts recording 16 kHz mono into `sinks`. */
+export async function openMicrophone(microphone: MicrophoneSetting, sinks: CaptureSinks): Promise<Capture> {
+  let device: InputDevice | undefined;
+  if (microphone.type === "device") {
+    device = findMicrophone(await listInputDevices(), microphone);
+    if (!device) throw new MicrophoneUnavailableError(microphone.name);
+  }
+
+  const recorder = await Recorder.open({
+    device: device?.id,
+    sampleRate: CAPTURE_SAMPLE_RATE,
+    channels: "mono",
+    framesPerChunk: FRAMES_PER_CHUNK,
+    onChunk: ({ samples }) => sinks.onAudio(samples),
+    onFailure: (error) => sinks.onFailure(error),
+  });
+  try {
+    const { format } = recorder.info;
+    if (format.sampleRate !== CAPTURE_SAMPLE_RATE || format.channels !== 1) {
+      throw new Error(`Recorder delivers ${format.sampleRate} Hz × ${format.channels}; expected ${CAPTURE_SAMPLE_RATE} Hz mono`);
+    }
+    recorder.start();
+  } catch (error) {
+    await recorder.close().catch(() => undefined);
+    throw error;
+  }
+
+  return {
+    async stop() {
+      try {
+        const recording = await recorder.stop();
+        return {
+          pcm: recording.samples,
+          interruption: interruption(recording),
+          droppedFrames: recording.droppedFrames,
+        };
+      } finally {
+        // The recording is already in hand; a close that times out only
+        // means the platform holds the device until Pi exits.
+        await recorder.close().catch(() => undefined);
+      }
+    },
+  };
+}