@tychenjiajun/pi-voice 0.3.0 → 0.5.0

package/src/remote-asr.ts

@@ -0,0 +1,212 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { Box, Container, Input, Spacer, Text, truncateToWidth } from "@earendil-works/pi-tui";
+import { VoiceKeys } from "./keybindings.js";
+import type { BackendSettings } from "./settings.js";
+import {
+  LIST_PADDING,
+  panelBorder,
+  SingleSelectPicker,
+  type SingleSelectChoice,
+} from "./ui-components.js";
+
+export type BackendType = "transcribe-cpp" | "openai-asr";
+
+/** Pick the transcription backend; shared by first-run setup and the settings menu. */
+export async function chooseBackendType(
+  ctx: ExtensionContext,
+  current: BackendSettings,
+): Promise<BackendType | undefined> {
+  const choices: SingleSelectChoice<BackendType>[] = [
+    {
+      value: "transcribe-cpp",
+      label: "Local model",
+      description: "Transcribe fully on-device with the downloaded model; works offline",
+    },
+    {
+      value: "openai-asr",
+      label: "Remote ASR (OpenAI-compatible)",
+      description:
+        "Upload audio to any OpenAI-compatible chat-completions ASR endpoint; no local model is used",
+    },
+  ];
+  return ctx.ui.custom<BackendType | undefined>((tui, theme, keybindings, done) =>
+    new SingleSelectPicker(
+      tui,
+      theme,
+      keybindings,
+      choices,
+      current.type,
+      { title: "Transcription backend", cancelLabel: "back" },
+      done,
+    ),
+  );
+}
+
+function validateBaseUrl(value: string): string | undefined {
+  if (!value) return "Base URL is required";
+  try {
+    const url = new URL(value);
+    if (url.protocol !== "http:" && url.protocol !== "https:") {
+      return "Base URL must start with http:// or https://";
+    }
+  } catch {
+    return "Base URL must be a valid URL";
+  }
+  return undefined;
+}
+
+function validateEnvName(value: string): string | undefined {
+  if (!value) return "Environment variable name is required";
+  if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(value)) {
+    return "Use a plain environment variable name, e.g. OPENAI_API_KEY";
+  }
+  return undefined;
+}
+
+function remoteBackendsEqual(
+  left: Extract<BackendSettings, { type: "openai-asr" }>,
+  right: Extract<BackendSettings, { type: "openai-asr" }>,
+): boolean {
+  return (
+    left.baseUrl === right.baseUrl &&
+    left.model === right.model &&
+    left.apiKeyEnv === right.apiKeyEnv
+  );
+}
+
+/** Warn when the named variable is unset, so remote calls fail until it is set. */
+export function warnMissingApiKey(ctx: ExtensionContext, apiKeyEnv: string): void {
+  if (process.env[apiKeyEnv]) return;
+  ctx.ui.notify(
+    `${apiKeyEnv} is not set in Pi's environment; remote transcription will fail until it is set`,
+    "warning",
+  );
+}
+
+/**
+ * Single-field text prompt built on pi-tui's Input. Empty input may be legal
+ * (the caller decides via validate); Escape backs out of the whole flow.
+ */
+function promptText(
+  ctx: ExtensionContext,
+  options: {
+    title: string;
+    description?: string;
+    value: string;
+    placeholder?: string;
+    validate?: (value: string) => string | undefined;
+  },
+): Promise<string | undefined> {
+  return ctx.ui.custom<string | undefined>((tui, theme, keybindings, done) => {
+    const keys = new VoiceKeys(keybindings);
+    const input = new Input();
+    input.setValue(options.value);
+    let error: string | undefined;
+    const container = new Container();
+
+    const rebuild = (): void => {
+      container.clear();
+      container.addChild(panelBorder(theme));
+      container.addChild(new Spacer(1));
+      container.addChild(new Text(theme.fg("accent", theme.bold(options.title)), 1, 0));
+      if (options.description) {
+        container.addChild(new Text(theme.fg("muted", options.description), 1, 0));
+      }
+      container.addChild(new Spacer(1));
+      if (error) {
+        container.addChild(new Text(theme.fg("error", error), 1, 0));
+        container.addChild(new Spacer(1));
+      }
+      if (!input.getValue() && options.placeholder) {
+        container.addChild(new Text(theme.fg("dim", options.placeholder), 2, 0));
+      }
+      const inputBox = new Box(LIST_PADDING, 0);
+      inputBox.addChild(input);
+      container.addChild(inputBox);
+      container.addChild(new Spacer(1));
+      container.addChild(
+        new Text(
+          `${keys.hint("tui.input.submit", "save")}  ${keys.hint("tui.select.cancel", "back")}`,
+          1,
+          0,
+        ),
+      );
+      container.addChild(new Spacer(1));
+      container.addChild(panelBorder(theme));
+    };
+    rebuild();
+
+    input.onSubmit = (value) => {
+      const problem = options.validate?.(value.trim());
+      if (problem) {
+        error = problem;
+        rebuild();
+        tui.requestRender();
+        return;
+      }
+      done(value.trim());
+    };
+    input.onEscape = () => done(undefined);
+
+    return {
+      get focused() {
+        return input.focused;
+      },
+      set focused(value: boolean) {
+        input.focused = value;
+      },
+      render(width: number): string[] {
+        return container
+          .render(width)
+          .map((line) => truncateToWidth(line, width, ""));
+      },
+      handleInput(data: string): void {
+        input.handleInput(data);
+      },
+      invalidate(): void {
+        container.invalidate();
+      },
+    };
+  });
+}
+
+/**
+ * Collect base URL, model, and API key env var for an OpenAI-compatible ASR
+ * endpoint. Returns undefined if the user backs out of any field. `current`
+ * pre-fills the prompts when editing an existing backend.
+ */
+export async function promptRemoteBackend(
+  ctx: ExtensionContext,
+  current?: Extract<BackendSettings, { type: "openai-asr" }>,
+): Promise<Extract<BackendSettings, { type: "openai-asr" }> | undefined> {
+  const baseUrl = await promptText(ctx, {
+    title: "ASR base URL",
+    description: "OpenAI-compatible endpoint root, without the /chat/completions path",
+    value: current?.baseUrl ?? "",
+    placeholder: "https://api.example.com/v1",
+    validate: validateBaseUrl,
+  });
+  if (baseUrl === undefined) return undefined;
+
+  const model = await promptText(ctx, {
+    title: "ASR model",
+    value: current?.model ?? "",
+    placeholder: "whisper-1",
+    validate: (value) => (value ? undefined : "Model name is required"),
+  });
+  if (model === undefined) return undefined;
+
+  const apiKeyEnv = await promptText(ctx, {
+    title: "API key environment variable",
+    description:
+      "The key itself is read from this variable at runtime; it is never stored in settings",
+    value: current?.apiKeyEnv ?? "",
+    placeholder: "OPENAI_API_KEY",
+    validate: validateEnvName,
+  });
+  if (apiKeyEnv === undefined) return undefined;
+
+  const backend = { type: "openai-asr" as const, baseUrl, model, apiKeyEnv };
+  if (current && remoteBackendsEqual(current, backend)) return undefined;
+  return backend;
+}

package/src/runtime.ts

@@ -48,7 +48,7 @@ function captureErrorMessage(error: unknown): string {
 
 function transcriptionErrorMessage(error: unknown): string {
   const message = error instanceof Error ? error.message : String(error);
-  return `Local transcription failed: ${message}`;
+  return `Transcription failed: ${message}`;
 }
 
 export function createPiVoiceRuntime(
@@ -145,7 +145,7 @@ export function createPiVoiceRuntime(
       preferredLanguages: previous.preferredLanguages,
       transcriptionLanguage: previous.transcriptionLanguage,
       chineseOutput: previous.chineseOutput,
-      currentModelId: previous.model.id,
+      currentModelId: previous.model?.id,
       microphone: previous.microphone,
       backend: previous.backend,
       polishEnabled: previous.polishEnabled,
@@ -165,12 +165,12 @@ export function createPiVoiceRuntime(
       ctx.ui.notify(settingsReadWarning, "warning");
     }
 
-    if (settings && existsSync(settings.model.path)) {
+    if (settings && (!settings.model || existsSync(settings.model.path))) {
       return { configured: settings, completedFirstRun: false };
     }
 
     const previous = settings;
-    if (settings) {
+    if (settings?.model) {
       ctx.ui.notify(
         `Configured model file is missing: ${settings.model.path}. Choose a model again; nothing will be downloaded without confirmation.`,
         "warning",
@@ -189,15 +189,15 @@ export function createPiVoiceRuntime(
     await loadSettingsOnce();
     if (settingsReadWarning && !settings) {
       throw new Error(
-        `${settingsReadWarning} Ask the user to run /voice-settings in Pi's interactive TUI to configure a local model, then retry transcribe_file.`,
+        `${settingsReadWarning} Ask the user to run /voice-settings in Pi's interactive TUI to set up Pi Voice (a local model or a remote ASR endpoint), then retry transcribe_file.`,
       );
     }
     if (!settings) {
       throw new Error(
-        "Pi Voice is not configured. Ask the user to run /voice-settings in Pi's interactive TUI once to choose and download a local model, then retry transcribe_file.",
+        "Pi Voice is not configured. Ask the user to run /voice-settings in Pi's interactive TUI once to set up Pi Voice (choose and download a local model, or configure a remote ASR endpoint), then retry transcribe_file.",
       );
     }
-    if (!existsSync(settings.model.path)) {
+    if (settings.model && !existsSync(settings.model.path)) {
       throw new Error(
         `The configured transcription model is missing: ${settings.model.path}. Ask the user to run /voice-settings and choose a model again, then retry transcribe_file.`,
       );
@@ -408,7 +408,7 @@ export function createPiVoiceRuntime(
     const { clearTranscribeWidget, showTranscribeStatus } = await loadVisualizer();
     logStep("loading settings");
     await loadSettingsOnce();
-    if (settings && existsSync(settings.model.path)) {
+    if (settings && (!settings.model || existsSync(settings.model.path))) {
       showTranscribeStatus(ctx, "Starting microphone…");
     } else {
       // Setup panes replace only the editor, so a status line set here or by
@@ -458,15 +458,17 @@ export function createPiVoiceRuntime(
     let reload = false;
     await runExclusive(ctx, async () => {
       await loadSettingsOnce();
-      const hadConfiguration = Boolean(settings && existsSync(settings.model.path));
-      const { configured } = await ensureSettings(ctx);
+      const { configured, completedFirstRun } = await ensureSettings(ctx);
       if (!configured) return;
-      if (!hadConfiguration) {
+      if (completedFirstRun) {
         // First-run setup ends on its Ready message rather than falling
         // straight through into the regular settings menu.
         reload = configured.shortcut !== registeredShortcut;
         return;
       }
+      // A recovered missing model file also lands here: the user asked for
+      // settings, so continue into them instead of making them run the
+      // command a second time.
       const { showSettingsMenu } = await import("./settings-menu.js");
       reload = await showSettingsMenu(pi, ctx, configured, registeredShortcut);
     });

package/src/settings-menu.ts

@@ -2,11 +2,10 @@ import type {
   ExtensionAPI,
   ExtensionContext,
 } from "@earendil-works/pi-coding-agent";
-import { Box, Container, Input, Spacer, Text, truncateToWidth } from "@earendil-works/pi-tui";
+import { truncateToWidth } from "@earendil-works/pi-tui";
 import { microphonePermission, type Permission } from "./audio.js";
 import { displayLanguage, getCatalogModel } from "./catalog.js";
 import { chineseOutputSummary, isChineseLanguage } from "./chinese.js";
-import { VoiceKeys } from "./keybindings.js";
 import {
   chooseLanguages,
   createTranscriptionLanguagePicker,
@@ -18,6 +17,7 @@ import {
   microphoneSummary,
 } from "./microphone-picker.js";
 import { runModelSelection } from "./onboarding.js";
+import { chooseBackendType, promptRemoteBackend, warnMissingApiKey } from "./remote-asr.js";
 import {
   writeSettings,
   type BackendSettings,
@@ -30,9 +30,7 @@ import {
 import { displayShortcut } from "./shortcut-core.js";
 import { createShortcutPicker } from "./shortcuts.js";
 import {
-  LIST_PADDING,
   padToWidth,
-  panelBorder,
   SingleSelectPicker,
   type SingleSelectChoice,
 } from "./ui-components.js";
@@ -43,7 +41,7 @@ const SETTINGS_LABEL_WIDTH = 25;
 // Text padding (2), cursor gutter (2), label column, and its gap (2).
 const SETTINGS_ROW_OVERHEAD = SETTINGS_LABEL_WIDTH + 6;
 
-type SettingsAction =
+export type SettingsAction =
   | "preferred-languages"
   | "model"
   | "backend"
@@ -53,7 +51,7 @@ type SettingsAction =
   | "microphone"
   | "shortcut";
 
-type SettingsHomeChoice = SingleSelectChoice<SettingsAction> & {
+export type SettingsHomeChoice = SingleSelectChoice<SettingsAction> & {
   summary: string;
   /** Render the summary in the error color. */
   alert?: boolean;
@@ -98,11 +96,13 @@ function polishSummary(polishEnabled: boolean | undefined, model: PolishModelRef
   return model ? `${model.provider}/${model.id}` : "Pi's current model";
 }
 
-function settingsHomeChoices(
+export function settingsHomeChoices(
   configured: TranscribeSettings,
   permission: Permission,
 ): SettingsHomeChoice[] {
-  const model = getCatalogModel(configured.model.id)!;
+  // Local mode always carries a model; remote mode never does.
+  const model = configured.model ? getCatalogModel(configured.model.id) : undefined;
+  const remote = configured.backend.type === "openai-asr";
   const choices: SettingsHomeChoice[] = [
     {
       value: "preferred-languages",
@@ -110,18 +110,24 @@ function settingsHomeChoices(
       summary: preferredLanguagesSummary(configured.preferredLanguages),
       description: "Languages you speak, used to rank and recommend transcription models",
     },
-    {
+  ];
+
+  if (model) {
+    choices.push({
       value: "model",
       label: "Model",
       summary: model.name,
       description: "Switch between downloaded models, or download a new one",
-    },
+    });
+  }
+
+  choices.push(
     {
       value: "backend",
       label: "Transcription backend",
       summary: backendSummary(configured.backend),
       description:
-        "Local model, or an OpenAI-compatible remote ASR endpoint (local model stays as fallback)",
+        "Local model or remote ASR endpoint; the two modes are exclusive",
     },
     {
       value: "post-processing",
@@ -130,17 +136,28 @@ function settingsHomeChoices(
       description:
         "Refine transcripts with Pi's current model after ASR, like context compaction",
     },
-    {
+  );
+
+  if (model) {
+    choices.push({
       value: "transcription-language",
       label: "Transcription language",
       summary: transcriptionLanguageSummary(configured.transcriptionLanguage, model),
       description: "Language expected in recordings, or automatic detection when supported",
-    },
-  ];
+    });
+  }
 
+  // Chinese script conversion applies when the configured language is Chinese,
+  // when a preferred language is Chinese, or when a detecting model can pick
+  // Chinese on its own. Remote mode can always produce Chinese, so its row is
+  // never gated.
+  const detectsChinese =
+    model?.capabilities.languageDetection && model.languages.some(isChineseLanguage);
   if (
+    remote ||
     isChineseLanguage(configured.transcriptionLanguage) ||
-    configured.preferredLanguages.some(isChineseLanguage)
+    configured.preferredLanguages.some(isChineseLanguage) ||
+    detectsChinese
   ) {
     choices.push({
       value: "chinese-output",
@@ -256,7 +273,8 @@ async function chooseTranscriptionLanguage(
   ctx: ExtensionContext,
   configured: TranscribeSettings,
 ): Promise<TranscriptionLanguage | undefined> {
-  const model = getCatalogModel(configured.model.id)!;
+  const model = configured.model ? getCatalogModel(configured.model.id) : undefined;
+  if (!model) return undefined;
   return ctx.ui.custom<TranscriptionLanguage | undefined>(
     (tui, theme, keybindings, done) =>
       createTranscriptionLanguagePicker(
@@ -280,145 +298,6 @@ async function chooseShortcut(
   );
 }
 
-/**
- * Single-field text prompt built on pi-tui's Input. Empty input may be legal
- * (the caller decides via validate); Escape backs out of the whole flow.
- */
-function promptText(
-  ctx: ExtensionContext,
-  options: {
-    title: string;
-    description?: string;
-    value: string;
-    placeholder?: string;
-    validate?: (value: string) => string | undefined;
-  },
-): Promise<string | undefined> {
-  return ctx.ui.custom<string | undefined>((tui, theme, keybindings, done) => {
-    const keys = new VoiceKeys(keybindings);
-    const input = new Input();
-    input.setValue(options.value);
-    let error: string | undefined;
-    const container = new Container();
-
-    const rebuild = (): void => {
-      container.clear();
-      container.addChild(panelBorder(theme));
-      container.addChild(new Spacer(1));
-      container.addChild(new Text(theme.fg("accent", theme.bold(options.title)), 1, 0));
-      if (options.description) {
-        container.addChild(new Text(theme.fg("muted", options.description), 1, 0));
-      }
-      container.addChild(new Spacer(1));
-      if (error) {
-        container.addChild(new Text(theme.fg("error", error), 1, 0));
-        container.addChild(new Spacer(1));
-      }
-      if (!input.getValue() && options.placeholder) {
-        container.addChild(new Text(theme.fg("dim", options.placeholder), 2, 0));
-      }
-      const inputBox = new Box(LIST_PADDING, 0);
-      inputBox.addChild(input);
-      container.addChild(inputBox);
-      container.addChild(new Spacer(1));
-      container.addChild(
-        new Text(
-          `${keys.hint("tui.input.submit", "save")}  ${keys.hint("tui.select.cancel", "back")}`,
-          1,
-          0,
-        ),
-      );
-      container.addChild(new Spacer(1));
-      container.addChild(panelBorder(theme));
-    };
-    rebuild();
-
-    input.onSubmit = (value) => {
-      const problem = options.validate?.(value.trim());
-      if (problem) {
-        error = problem;
-        rebuild();
-        tui.requestRender();
-        return;
-      }
-      done(value.trim());
-    };
-    input.onEscape = () => done(undefined);
-
-    return {
-      get focused() {
-        return input.focused;
-      },
-      set focused(value: boolean) {
-        input.focused = value;
-      },
-      render(width: number): string[] {
-        return container
-          .render(width)
-          .map((line) => truncateToWidth(line, width, ""));
-      },
-      handleInput(data: string): void {
-        input.handleInput(data);
-      },
-      invalidate(): void {
-        container.invalidate();
-      },
-    };
-  });
-}
-
-async function chooseBackendType(
-  ctx: ExtensionContext,
-  current: BackendSettings,
-): Promise<"transcribe-cpp" | "openai-asr" | undefined> {
-  const choices: SingleSelectChoice<"transcribe-cpp" | "openai-asr">[] = [
-    {
-      value: "transcribe-cpp",
-      label: "Local model",
-      description: "Transcribe fully on-device with the downloaded model; works offline",
-    },
-    {
-      value: "openai-asr",
-      label: "Remote ASR (OpenAI-compatible)",
-      description:
-        "Upload audio to any OpenAI-compatible chat-completions ASR endpoint; falls back to the local model if the request fails",
-    },
-  ];
-  return ctx.ui.custom<"transcribe-cpp" | "openai-asr" | undefined>(
-    (tui, theme, keybindings, done) =>
-      new SingleSelectPicker(
-        tui,
-        theme,
-        keybindings,
-        choices,
-        current.type,
-        { title: "Transcription backend", cancelLabel: "back" },
-        done,
-      ),
-  );
-}
-
-function validateBaseUrl(value: string): string | undefined {
-  if (!value) return "Base URL is required";
-  try {
-    const url = new URL(value);
-    if (url.protocol !== "http:" && url.protocol !== "https:") {
-      return "Base URL must start with http:// or https://";
-    }
-  } catch {
-    return "Base URL must be a valid URL";
-  }
-  return undefined;
-}
-
-function validateEnvName(value: string): string | undefined {
-  if (!value) return "Environment variable name is required";
-  if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(value)) {
-    return "Use a plain environment variable name, e.g. OPENAI_API_KEY";
-  }
-  return undefined;
-}
-
 /** Backend row flow: pick the type, then collect remote settings step by step. */
 async function editBackend(
   ctx: ExtensionContext,
@@ -428,63 +307,40 @@ async function editBackend(
   if (!type) return false;
   if (type === "transcribe-cpp") {
     if (configured.backend.type === "transcribe-cpp") return false;
-    return saveUpdatedSettings(
-      ctx,
-      configured,
-      { ...configured, backend: { type: "transcribe-cpp" } },
-      "Using the local model",
-    );
+    // Remote-only settings carry no local model; pick one first. Every commit
+    // writes local-mode settings, so cancelling keeps the remote setup.
+    const updated = await runModelSelection(ctx, {
+      shortcut: configured.shortcut,
+      preferredLanguages: configured.preferredLanguages,
+      transcriptionLanguage: configured.transcriptionLanguage,
+      chineseOutput: configured.chineseOutput,
+      microphone: configured.microphone,
+      backend: { type: "transcribe-cpp" },
+      polishEnabled: configured.polishEnabled,
+      polishModel: configured.polishModel,
+      postActivation: "stay",
+    });
+    if (!updated) {
+      ctx.ui.notify("Local mode needs a local model; keeping remote ASR", "info");
+      return false;
+    }
+    Object.assign(configured, updated);
+    ctx.ui.notify("Using the local model", "info");
+    return true;
   }
 
   const current =
     configured.backend.type === "openai-asr" ? configured.backend : undefined;
-  const baseUrl = await promptText(ctx, {
-    title: "ASR base URL",
-    description: "OpenAI-compatible endpoint root, without the /chat/completions path",
-    value: current?.baseUrl ?? "",
-    placeholder: "https://api.example.com/v1",
-    validate: validateBaseUrl,
-  });
-  if (baseUrl === undefined) return false;
+  const backend = await promptRemoteBackend(ctx, current);
+  if (!backend) return false;
 
-  const model = await promptText(ctx, {
-    title: "ASR model",
-    value: current?.model ?? "",
-    placeholder: "whisper-1",
-    validate: (value) => (value ? undefined : "Model name is required"),
-  });
-  if (model === undefined) return false;
-
-  const apiKeyEnv = await promptText(ctx, {
-    title: "API key environment variable",
-    description: "The key itself is read from this variable at runtime; it is never stored in settings",
-    value: current?.apiKeyEnv ?? "",
-    placeholder: "OPENAI_API_KEY",
-    validate: validateEnvName,
-  });
-  if (apiKeyEnv === undefined) return false;
-
-  const backend: BackendSettings = { type: "openai-asr", baseUrl, model, apiKeyEnv };
-  if (
-    current &&
-    current.baseUrl === baseUrl &&
-    current.model === model &&
-    current.apiKeyEnv === apiKeyEnv
-  ) {
-    return false;
-  }
   const saved = await saveUpdatedSettings(
     ctx,
     configured,
-    { ...configured, backend },
-    `Remote ASR configured (${model})`,
+    { ...configured, backend, model: undefined },
+    `Remote ASR configured (${backend.model}); the local model is no longer used`,
   );
-  if (saved && !process.env[apiKeyEnv]) {
-    ctx.ui.notify(
-      `${apiKeyEnv} is not set in Pi's environment; remote transcription will fall back to the local model until it is set`,
-      "warning",
-    );
-  }
+  if (saved) warnMissingApiKey(ctx, backend.apiKeyEnv);
   return saved;
 }
 
@@ -682,7 +538,7 @@ export async function showSettingsMenu(
         preferredLanguages: configured.preferredLanguages,
         transcriptionLanguage: configured.transcriptionLanguage,
         chineseOutput: configured.chineseOutput,
-        currentModelId: configured.model.id,
+        currentModelId: configured.model?.id,
         microphone: configured.microphone,
         backend: configured.backend,
         polishEnabled: configured.polishEnabled,
@@ -718,8 +574,12 @@ export async function showSettingsMenu(
       ) {
         continue;
       }
-      const model = getCatalogModel(configured.model.id)!;
-      const summary = transcriptionLanguageSummary(transcriptionLanguage, model);
+      const model = configured.model
+        ? getCatalogModel(configured.model.id)
+        : undefined;
+      const summary = model
+        ? transcriptionLanguageSummary(transcriptionLanguage, model)
+        : transcriptionLanguage;
       await saveUpdatedSettings(
         ctx,
         configured,