@tychenjiajun/pi-voice 0.0.0-stage → 0.2.0

package/src/file-transcription.ts

@@ -0,0 +1,212 @@
+import {
+  DEFAULT_MAX_BYTES,
+  DEFAULT_MAX_LINES,
+  formatSize,
+  truncateHead,
+  type ExtensionAPI,
+  type TruncationResult,
+} from "@earendil-works/pi-coding-agent";
+import { mkdtemp, stat, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { basename, join, resolve } from "node:path";
+import { Type } from "typebox";
+import { AsyncLimiter } from "./async-limiter.js";
+import type { TranscribeSettings } from "./settings.js";
+import type { TranscriptionService } from "./transcription-service.js";
+
+const CONTEXT_LINE_LENGTH = 1_000;
+const MAX_FILE_OPERATIONS = 2;
+const MAX_FILE_DECODERS = 1;
+
+type FileTranscriptionDetails = {
+  inputPath: string;
+  modelId: string;
+  seconds: number;
+  truncation?: TruncationResult;
+  fullTranscriptPath?: string;
+};
+
+type FileTranscriptionOptions = {
+  getSettings: () => Promise<TranscribeSettings>;
+  getService: () => Promise<TranscriptionService>;
+};
+
+export type FileTranscriptionController = {
+  shutdown(): Promise<void>;
+};
+
+function normalizeToolPath(path: string): string {
+  return path.startsWith("@") ? path.slice(1) : path;
+}
+
+/** Wrap long model output lines so Pi's line-aware truncation can retain useful text. */
+function wrapLongLines(text: string): string {
+  const output: string[] = [];
+  for (const originalLine of text.split("\n")) {
+    let line = originalLine;
+    while (line.length > CONTEXT_LINE_LENGTH) {
+      let split = line.lastIndexOf(" ", CONTEXT_LINE_LENGTH);
+      if (split <= 0) split = CONTEXT_LINE_LENGTH;
+      output.push(line.slice(0, split));
+      line = line.slice(split).trimStart();
+    }
+    output.push(line);
+  }
+  return output.join("\n");
+}
+
+async function saveFullTranscript(text: string): Promise<string> {
+  const directory = await mkdtemp(join(tmpdir(), "pi-voice-"));
+  const path = join(directory, "transcript.txt");
+  await writeFile(path, `${text}\n`, "utf8");
+  return path;
+}
+
+export function registerFileTranscriptionTool(
+  pi: ExtensionAPI,
+  options: FileTranscriptionOptions,
+): FileTranscriptionController {
+  let shuttingDown = false;
+  const operations = new Set<Promise<unknown>>();
+  const fileOperations = new AsyncLimiter(MAX_FILE_OPERATIONS);
+  const fileDecoders = new AsyncLimiter(MAX_FILE_DECODERS);
+  const shutdownController = new AbortController();
+
+  function track<T>(operation: Promise<T>): Promise<T> {
+    const tracked = operation.finally(() => {
+      operations.delete(tracked);
+    });
+    operations.add(tracked);
+    return tracked;
+  }
+
+  pi.registerTool({
+    name: "transcribe_file",
+    label: "Transcribe File",
+    description: `Transcribe speech from a local audio or video file using Pi Voice's configured transcription backend (local model, or the configured remote ASR endpoint with the local model as fallback). Requires the ffmpeg executable on PATH (or PI_VOICE_FFMPEG_PATH). Output is truncated to ${DEFAULT_MAX_LINES} lines or ${formatSize(DEFAULT_MAX_BYTES)}; a complete transcript is saved to a temporary file when needed.`,
+    promptSnippet: "Transcribe speech from local audio or video files",
+    promptGuidelines: [
+      "Use transcribe_file when speech in a local audio or video file needs to be read, analyzed, or transcribed.",
+      "transcribe_file automatically queues model work, with interactive dictation taking priority over queued files.",
+      "If transcribe_file reports that FFmpeg is unavailable, explain the installation guidance and ask the user before running a system package-manager command.",
+    ],
+    parameters: Type.Object({
+      path: Type.String({
+        description: "Local media file path, absolute or relative to the current working directory",
+      }),
+    }),
+
+    async execute(_toolCallId, params, signal, onUpdate, ctx) {
+      if (shuttingDown) throw new Error("Pi Voice is shutting down");
+      const operationSignal = signal
+        ? AbortSignal.any([signal, shutdownController.signal])
+        : shutdownController.signal;
+
+      return track(
+        (async () => {
+          operationSignal.throwIfAborted();
+          const input = normalizeToolPath(params.path.trim());
+          if (!input) throw new Error("A media file path is required");
+          const inputPath = resolve(ctx.cwd, input);
+          const inputStat = await stat(inputPath).catch((error: NodeJS.ErrnoException) => {
+            if (error.code === "ENOENT") throw new Error(`Media file not found: ${inputPath}`);
+            throw error;
+          });
+          if (!inputStat.isFile()) throw new Error(`Media path is not a regular file: ${inputPath}`);
+          operationSignal.throwIfAborted();
+
+          const configured = await options.getSettings();
+          const service = await options.getService();
+          if (fileOperations.saturated) {
+            onUpdate?.({
+              content: [{ type: "text", text: "Waiting for file transcription capacity…" }],
+              details: { inputPath, modelId: configured.model.id, seconds: 0 },
+            });
+          }
+
+          return fileOperations.run(async () => {
+            if (fileDecoders.saturated) {
+              onUpdate?.({
+                content: [{ type: "text", text: `Waiting to decode ${basename(inputPath)}…` }],
+                details: { inputPath, modelId: configured.model.id, seconds: 0 },
+              });
+            }
+            const audio = await fileDecoders.run(async () => {
+              onUpdate?.({
+                content: [{ type: "text", text: `Decoding ${basename(inputPath)} with FFmpeg…` }],
+                details: { inputPath, modelId: configured.model.id, seconds: 0 },
+              });
+              const { decodeFileAudio } = await import("./file-audio.js");
+              return decodeFileAudio(inputPath, operationSignal);
+            }, operationSignal);
+
+            onUpdate?.({
+              content: [
+                {
+                  type: "text",
+                  text: `Queued ${audio.seconds.toFixed(1)}s from ${basename(inputPath)} for local transcription…`,
+                },
+              ],
+              details: {
+                inputPath,
+                modelId: configured.model.id,
+                seconds: audio.seconds,
+              },
+            });
+            const transcript = await service.transcribeFile(
+              configured,
+              audio.pcm,
+              operationSignal,
+            );
+            const details: FileTranscriptionDetails = {
+              inputPath,
+              modelId: configured.model.id,
+              seconds: audio.seconds,
+            };
+
+            if (!transcript) {
+              return {
+                content: [
+                  {
+                    type: "text" as const,
+                    text: `No speech detected in ${audio.seconds.toFixed(1)}s of audio from ${inputPath}`,
+                  },
+                ],
+                details,
+              };
+            }
+
+            const contextTranscript =
+              Buffer.byteLength(transcript, "utf8") > DEFAULT_MAX_BYTES
+                ? wrapLongLines(transcript)
+                : transcript;
+            const truncation = truncateHead(contextTranscript, {
+              maxLines: DEFAULT_MAX_LINES,
+              maxBytes: DEFAULT_MAX_BYTES,
+            });
+            let resultText = truncation.content;
+            if (truncation.truncated) {
+              const fullTranscriptPath = await saveFullTranscript(transcript);
+              details.truncation = truncation;
+              details.fullTranscriptPath = fullTranscriptPath;
+              resultText += `\n\n[Transcript truncated: showing ${truncation.outputLines} of ${truncation.totalLines} lines (${formatSize(truncation.outputBytes)} of ${formatSize(truncation.totalBytes)}). Full transcript saved to: ${fullTranscriptPath}]`;
+            }
+
+            return {
+              content: [{ type: "text" as const, text: resultText }],
+              details,
+            };
+          }, operationSignal);
+        })(),
+      );
+    },
+  });
+
+  return {
+    async shutdown() {
+      shuttingDown = true;
+      shutdownController.abort(new Error("Pi Voice is shutting down"));
+      await Promise.allSettled([...operations]);
+    },
+  };
+}

package/src/index.ts

@@ -0,0 +1,135 @@
+import type {
+  ExtensionAPI,
+  ExtensionCommandContext,
+  ExtensionContext,
+} from "@earendil-works/pi-coding-agent";
+import { existsSync } from "node:fs";
+import { registerFileTranscriptionTool } from "./file-transcription.js";
+import {
+  claimLegacyGitNotice,
+  findLegacyGitInstall,
+  legacyGitMigrationMessage,
+} from "./install-migration.js";
+import type { PiVoiceRuntime } from "./runtime.js";
+import { displayShortcut, STATUS_WIDGET_KEY } from "./shortcut-core.js";
+import { initLog, log, logStep, markKeyPress, watchEventLoop } from "./log.js";
+import { legacySettingsPath, logPath, settingsPath } from "./settings-path.js";
+import { readShortcutForRegistration } from "./startup-shortcut.js";
+
+// Pi awaits extension module evaluation before continuing startup. Keep this
+// entry point registration-only and load feature implementations on first use.
+export default function piVoice(pi: ExtensionAPI): void {
+  // Opens nothing yet: the first line written creates the file.
+  initLog({ path: logPath(), level: process.env.PI_VOICE_DEBUG === "1" ? "debug" : "info" });
+  const registeredShortcut = readShortcutForRegistration();
+  let runtimePromise: Promise<PiVoiceRuntime> | undefined;
+  let shuttingDown = false;
+
+  function loadRuntime(): Promise<PiVoiceRuntime> {
+    if (shuttingDown) return Promise.reject(new Error("Pi Voice is shutting down"));
+    if (runtimePromise) return runtimePromise;
+
+    const loadStarted = performance.now();
+    logStep("loading runtime");
+    const loading = import("./runtime.js").then(({ createPiVoiceRuntime }) => {
+      log.debug(`runtime loaded in ${Math.round(performance.now() - loadStarted)} ms`);
+      return createPiVoiceRuntime(pi, registeredShortcut);
+    });
+    runtimePromise = loading;
+    void loading.catch(() => {
+      if (runtimePromise === loading) runtimePromise = undefined;
+    });
+    return loading;
+  }
+
+  pi.on("session_start", async (_event, ctx) => {
+    let showedMigrationNotice = false;
+    if (ctx.mode === "tui") {
+      const legacyInstall = findLegacyGitInstall(pi.getCommands());
+      if (legacyInstall && await claimLegacyGitNotice()) {
+        ctx.ui.notify(legacyGitMigrationMessage(legacyInstall), "warning");
+        showedMigrationNotice = true;
+      }
+    }
+
+    if (
+      !showedMigrationNotice &&
+      !existsSync(settingsPath()) &&
+      !existsSync(legacySettingsPath())
+    ) {
+      ctx.ui.notify(
+        `Pi Voice installed · press ${displayShortcut(registeredShortcut)} or run /voice-settings to set up`,
+        "info",
+      );
+    }
+  });
+
+  const fileTranscription = registerFileTranscriptionTool(pi, {
+    getSettings: async () => (await loadRuntime()).requireConfiguredSettingsForTool(),
+    getService: async () => (await loadRuntime()).service,
+  });
+
+  async function toggleCapture(ctx: ExtensionContext): Promise<void> {
+    markKeyPress();
+    const release = watchEventLoop();
+    // The first press pays deferred module loading before the runtime can
+    // show anything; paint feedback synchronously. Later presses reach the
+    // memoized runtime in a microtask and it paints its own status.
+    if (!runtimePromise && ctx.hasUI) {
+      ctx.ui.setWidget(STATUS_WIDGET_KEY, [
+        ctx.ui.theme.fg("muted", "Starting microphone…"),
+      ]);
+    }
+    try {
+      await (await loadRuntime()).toggleCapture(ctx);
+    } catch (error) {
+      if (ctx.hasUI) ctx.ui.setWidget(STATUS_WIDGET_KEY, undefined);
+      throw error;
+    } finally {
+      release();
+    }
+  }
+
+  pi.registerShortcut(
+    registeredShortcut as Parameters<ExtensionAPI["registerShortcut"]>[0],
+    {
+      description: "Toggle microphone transcription",
+      handler: toggleCapture,
+    },
+  );
+
+  pi.registerCommand("voice", {
+    description: "Start or stop microphone transcription",
+    handler: (_args, ctx) => toggleCapture(ctx),
+  });
+
+  const openSettings = async (
+    _args: string,
+    ctx: ExtensionCommandContext,
+  ): Promise<void> => (await loadRuntime()).showSettings(ctx);
+
+  pi.registerCommand("voice-settings", {
+    description: "Open Pi Voice settings",
+    handler: openSettings,
+  });
+  pi.registerCommand("transcribe", {
+    description: "Open Pi Voice settings (alias for /voice-settings)",
+    handler: openSettings,
+  });
+
+  if (process.env.PI_VOICE_DEBUG === "1") {
+    pi.registerCommand("voice-onboarding", {
+      description: "Replay Pi Voice onboarding (debug)",
+      handler: async (_args, ctx) => (await loadRuntime()).replayOnboarding(ctx),
+    });
+  }
+
+  pi.on("session_shutdown", async (_event, ctx) => {
+    shuttingDown = true;
+    await fileTranscription.shutdown().catch(() => undefined);
+    const loading = runtimePromise;
+    if (!loading) return;
+    const runtime = await loading.catch(() => undefined);
+    await runtime?.shutdown(ctx).catch(() => undefined);
+  });
+}

package/src/install-migration.ts

@@ -0,0 +1,47 @@
+import type { SlashCommandInfo, SourceInfo } from "@earendil-works/pi-coding-agent";
+import { writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+
+const NOTICE_MARKER_FILENAME = ".pi-voice-legacy-git-notice-v1";
+const LEGACY_GIT_REPOSITORY =
+  /github\.com(?::|\/)earendil-works\/pi-transcribe(?:\.git)?(?:@.*)?\/?$/i;
+
+/** Find a loaded package that still uses the pre-rename Git repository source. */
+export function findLegacyGitInstall(
+  commands: readonly SlashCommandInfo[],
+): SourceInfo | undefined {
+  return commands.find(
+    (command) =>
+      command.source === "extension" &&
+      command.sourceInfo.origin === "package" &&
+      LEGACY_GIT_REPOSITORY.test(command.sourceInfo.source),
+  )?.sourceInfo;
+}
+
+/** Atomically claim the one-time notice across concurrently running Pi processes. */
+export async function claimLegacyGitNotice(): Promise<boolean> {
+  try {
+    await writeFile(join(getAgentDir(), NOTICE_MARKER_FILENAME), "shown\n", {
+      encoding: "utf8",
+      flag: "wx",
+      mode: 0o600,
+    });
+    return true;
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "EEXIST") return false;
+    // A read-only config directory should not prevent the user from seeing the
+    // migration guidance, even though it means the notice may appear again.
+    return true;
+  }
+}
+
+export function legacyGitMigrationMessage(sourceInfo: SourceInfo): string {
+  const local = sourceInfo.scope === "project" ? " -l" : "";
+  return [
+    "Pi Voice is still installed from the old pi-transcribe Git repository.",
+    "For stable npm updates, replace it with the renamed package:",
+    `pi remove${local} ${sourceInfo.source}`,
+    `pi install${local} npm:@tychenjiajun/pi-voice`,
+  ].join("\n");
+}

package/src/keybindings.ts

@@ -0,0 +1,119 @@
+import { rawKeyHint } from "@earendil-works/pi-coding-agent";
+import {
+  decodeKittyPrintable,
+  KeybindingsManager,
+  matchesKey,
+  type Keybinding,
+  type KeybindingDefinitions,
+  type KeybindingsConfig,
+  type KeyId,
+} from "@earendil-works/pi-tui";
+
+/**
+ * Every key Pi Voice binds itself, in pi's definition shape. Users
+ * override these with the same ids in pi's keybindings.json; pi keeps entries
+ * it does not recognise and hands them back through `getUserBindings()`.
+ *
+ * Navigation, confirm, and cancel come from pi's `tui.*` ids. Tab is ours: it
+ * continues the language step and browses from Your models. The model pickers
+ * in between swallow the Continue key so the setup sequence never reads Tab as
+ * "go back".
+ */
+export const VOICE_KEYBINDINGS = {
+  "voice.languages.toggle": { defaultKeys: "space", description: "Toggle the highlighted language" },
+  "voice.languages.continue": { defaultKeys: "tab", description: "Continue with the selected languages" },
+  "voice.languages.change": { defaultKeys: "ctrl+l", description: "Change spoken languages" },
+  "voice.recommendations.browseAll": { defaultKeys: "o", description: "Browse all models" },
+  "voice.models.ratingsHelp": { defaultKeys: "?", description: "Open the rating guide" },
+  "voice.ratingsHelp.close": { defaultKeys: "q", description: "Close the rating guide" },
+  "voice.scroll.top": { defaultKeys: "home", description: "Scroll to the top" },
+  "voice.scroll.bottom": { defaultKeys: "end", description: "Scroll to the bottom" },
+  "voice.tryIt.shortcut": { defaultKeys: "s", description: "Change the dictation shortcut" },
+  "voice.tryIt.microphone": { defaultKeys: "m", description: "Change the microphone" },
+  "voice.tryIt.model": { defaultKeys: "c", description: "Change the model" },
+  "voice.shortcut.useDefault": { defaultKeys: "d", description: "Use the default shortcut" },
+  "voice.dictation.cancel": { defaultKeys: "escape", description: "Cancel recording or transcription" },
+  "voice.dictation.stop": { defaultKeys: "space", description: "Stop recording and transcribe" },
+} as const satisfies KeybindingDefinitions;
+
+export type VoiceKeybinding = keyof typeof VOICE_KEYBINDINGS;
+/** A pi `tui.*` id or one of ours; callers never need to know which. */
+export type KeyAction = Keybinding | VoiceKeybinding;
+
+export function isVoiceKeybinding(id: string): id is VoiceKeybinding {
+  return Object.hasOwn(VOICE_KEYBINDINGS, id);
+}
+
+// Our ids are not declaration-merged into pi's `Keybindings`, so pi's manager
+// would silently accept them and never match. Route by table membership instead.
+const asTuiId = (id: VoiceKeybinding): Keybinding => id as unknown as Keybinding;
+
+/**
+ * Before the Pi Voice rename our ids were `transcribe.*`. A user binding under
+ * the old id still applies unless the matching `voice.*` id is also set.
+ */
+function withLegacyBindings(user: KeybindingsConfig): KeybindingsConfig {
+  const bindings = { ...user };
+  for (const id of Object.keys(VOICE_KEYBINDINGS)) {
+    const legacy = user[id.replace(/^voice\./, "transcribe.")];
+    if (bindings[id] === undefined && legacy !== undefined) bindings[id] = legacy;
+  }
+  return bindings;
+}
+
+function matchesLocalKey(data: string, key: KeyId): boolean {
+  if (matchesKey(data, key)) return true;
+  // Single printable keys also accept the shifted or caps-lock form and Kitty's
+  // CSI-u report of the typed character, such as `?` arriving as shift+/.
+  if (key.length !== 1) return false;
+  const typed = data.length === 1 ? data : decodeKittyPrintable(data);
+  return typed?.toLowerCase() === key;
+}
+
+/** The user's dictation shortcut is a runtime setting, not a table entry. */
+export function matchesShortcut(data: string, shortcut: string): boolean {
+  return matchesKey(data, shortcut as KeyId);
+}
+
+/**
+ * One matcher and one hint formatter over pi's manager and our table.
+ * Built per pane from the manager pi injects, so the user's bindings for both
+ * apply. Construct it fresh rather than caching: pi's /reload swaps the user
+ * bindings on its manager and the local copy is a snapshot.
+ */
+export class VoiceKeys {
+  private readonly local: KeybindingsManager;
+
+  constructor(readonly host: KeybindingsManager) {
+    this.local = new KeybindingsManager(VOICE_KEYBINDINGS, withLegacyBindings(host.getUserBindings()));
+  }
+
+  matches(data: string, id: KeyAction): boolean {
+    if (!isVoiceKeybinding(id)) return this.host.matches(data, id);
+    return this.local.getKeys(asTuiId(id)).some((key) => matchesLocalKey(data, key));
+  }
+
+  keys(id: KeyAction): KeyId[] {
+    return isVoiceKeybinding(id) ? this.local.getKeys(asTuiId(id)) : this.host.getKeys(id);
+  }
+
+  keyText(id: KeyAction | readonly KeyAction[]): string {
+    const ids = Array.isArray(id) ? (id as readonly KeyAction[]) : [id as KeyAction];
+    return ids.flatMap((each) => this.keys(each)).join("/");
+  }
+
+  hint(id: KeyAction | readonly KeyAction[], description: string): string {
+    return rawKeyHint(this.keyText(id), description);
+  }
+
+  navLabel(): string {
+    const up = this.keys("tui.select.up");
+    const down = this.keys("tui.select.down");
+    const arrows = up.includes("up") && down.includes("down");
+    return arrows ? "↑↓" : `${up.join("/")}/${down.join("/")}`;
+  }
+
+  navHint(description: string): string {
+    return rawKeyHint(this.navLabel(), description);
+  }
+}

package/src/languages.ts

@@ -0,0 +1,22 @@
+/** A base code, without changing the identity or the model's exact code. */
+export function canonicalLanguage(language: string): string {
+  return language.trim().toLowerCase().split("-", 1)[0] ?? "";
+}
+
+// Model cards and benchmarks use different ISO codes for these languages.
+// This identity is for matching, never a code to send directly to a backend.
+const LANGUAGE_ALIASES: Readonly<Record<string, string>> = { tl: "fil", no: "nb" };
+
+export function languageIdentity(language: string): string {
+  const base = canonicalLanguage(language);
+  return LANGUAGE_ALIASES[base] ?? base;
+}
+
+/** Return a model's exact code, preserving an explicitly chosen regional variant. */
+export function resolveModelLanguage(
+  model: { readonly languages: readonly string[] },
+  language: string,
+): string | undefined {
+  const exact = model.languages.find((code) => code.toLowerCase() === language.trim().toLowerCase());
+  return exact ?? model.languages.find((code) => languageIdentity(code) === languageIdentity(language));
+}