@tychenjiajun/pi-voice 0.3.0 → 0.4.0

package/README.md

@@ -27,7 +27,7 @@ The extension registers:
 - a configurable terminal shortcut (`Ctrl+Alt+Z` by default) to start and stop recording;
 - `/voice`, which does the same as the shortcut. While recording, `Space` also stops and transcribes, and `Escape` discards;
 - a `transcribe_file` tool that the agent can use to transcribe local audio or video files;
-- `/voice-settings` for preferred languages, model, transcription language, post-processing, microphone, and shortcut settings.
+- `/voice-settings` for preferred languages, model, transcription backend, transcription language, post-processing, microphone, and shortcut settings.
 
 `/transcribe` remains available as a compatibility alias for `/voice-settings`.
 
@@ -35,7 +35,7 @@ The extension registers:
 
 Pi Voice can send audio to a remote ASR service instead of transcribing with the local model. It speaks the OpenAI chat-completions `input_audio` dialect: the recording is uploaded as a base64 WAV data URL and the transcript is read from `choices[0].message.content`. Any endpoint that accepts that shape works.
 
-Set it up in `/voice-settings` → **Transcription backend** → **Remote ASR (OpenAI-compatible)**. You are asked for:
+Set it up either during first-run setup — `/voice-settings` starts by asking **Local model** or **Remote ASR (OpenAI-compatible)** — or later in `/voice-settings` → **Transcription backend** → **Remote ASR (OpenAI-compatible)**. You are asked for:
 
 1. **Base URL** — endpoint root, without `/chat/completions`;
 2. **Model** — the model name your endpoint expects;
@@ -54,7 +54,7 @@ Behavior:
 - **16 kHz mono WAV** is uploaded as a base64 data URL.
 - Switching back to **Local model** restores the original behavior; the local model is still required either way (it is the fallback and file transcription still needs it).
 
-Transcripts still go through the **Chinese output** script conversion preference.
+Transcripts still go through the **Chinese output** script conversion preference; because a remote response carries no detected language, Han characters in the transcript are what trigger the conversion when the language is set to automatic.
 
 ## Post-processing (compaction-style refinement)
 
@@ -115,6 +115,25 @@ When FFmpeg is unavailable, `transcribe_file` reports platform-specific guidance
 
 ## Changelog
 
+### 0.4.0
+
+**Added — Backend choice in first-run setup**
+
+- `/voice-settings` (and the first shortcut press) now starts by asking **Local model** or **Remote ASR (OpenAI-compatible)**, so the remote backend no longer requires finishing local setup first. A local model is still downloaded as the fallback.
+- The remote endpoint prompts (base URL, model, API-key env var name) are shared by first-run setup and the settings menu.
+
+**Fixed — Settings reachability and remote consistency**
+
+- `/voice-settings` opens the settings menu after recovering a missing model file, instead of returning and making you run the command a second time.
+- **Chinese output** is shown for detecting models that support Chinese, so it is reachable when the transcription language is automatic.
+- Remote transcripts apply the Chinese output preference when the transcript contains Han characters, not only when the configured language is Chinese.
+- Settings and errors no longer assume local-only transcription: the **Transcription language** row explains that a remote endpoint detects the language itself, and the transcription error, `transcribe_file` setup guidance, and Try-it model row describe the remote backend.
+
+**Changed**
+
+- Onboarding progress counts the backend step (1 backend → 2 languages → 3 model → 4 Try it).
+- Try it's **change model** keeps the configured transcription language for the new model.
+
 ### 0.3.0
 
 **Added — Post-processing (compaction-style refinement)**
@@ -133,7 +152,7 @@ First release of `@tychenjiajun/pi-voice` — a fork of [`@earendil-works/pi-voi
 **Added — Remote ASR backend**
 
 - Recordings can be transcribed by any OpenAI-compatible chat-completions ASR endpoint via the `input_audio` content block.
-- Configure in `/voice-settings` → **Transcription backend** → **Remote ASR (OpenAI-compatible)**: base URL, model, and the *name* of an env var holding the API key (the key itself is never stored in settings).
+- Configure in `/voice-settings` → **Transcription backend** → **Remote ASR (OpenAI-compatible)**: base URL, model, and the *name* of an env var holding the API key (the key itself is never stored in settings). First-run setup also offers the remote backend directly.
 - Audio is uploaded as a 16 kHz mono WAV base64 data URL. Remote transcription is batch-only (no streaming preview).
 - **Local model fallback:** if a remote request fails (network, quota, HTTP error, or the API key is unset), the full recording is transcribed with the configured local model; the failure is logged to `~/.pi/agent/pi-voice.log`. Aborted/cancelled transcriptions are never retried locally.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tychenjiajun/pi-voice",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Speech-to-text for Pi (local model or OpenAI-compatible remote ASR, compaction-style post-processing)",
   "type": "module",
   "license": "MIT",

package/src/chinese.ts

@@ -33,6 +33,21 @@ export function isChineseLanguage(language: string): boolean {
   return base === "zh" || base === "yue";
 }
 
+/**
+ * CJK ranges worth converting: Ext A, the main block, compatibility ideographs,
+ * and Ext B+ (surrogate pairs are matched by their lead code unit).
+ */
+const HAN_CHARACTERS = /[\u3400-\u4dbf\u4e00-\u9fff\uf900-\ufaff\ud840-\ud87f]/;
+
+/**
+ * Remote ASR reports no detected language, so Chinese output is decided by
+ * looking at the transcript: OpenCC is only worth loading when there is Han
+ * text (or the configured language is Chinese) to convert.
+ */
+export function containsChineseCharacters(text: string): boolean {
+  return HAN_CHARACTERS.test(text);
+}
+
 export async function convertChineseOutput(
   text: string,
   output: ChineseOutput,

package/src/file-transcription.ts

@@ -145,7 +145,7 @@ export function registerFileTranscriptionTool(
               content: [
                 {
                   type: "text",
-                  text: `Queued ${audio.seconds.toFixed(1)}s from ${basename(inputPath)} for local transcription…`,
+                  text: `Queued ${audio.seconds.toFixed(1)}s from ${basename(inputPath)} for transcription…`,
                 },
               ],
               details: {

package/src/onboarding.ts

@@ -14,6 +14,7 @@ import {
 } from "./recommendation-picker.js";
 import { CATALOG_MODELS } from "./catalog.js";
 import { recommendModels } from "./recommendations.js";
+import { promptRemoteBackend, warnMissingApiKey } from "./remote-asr.js";
 import { createShortcutPicker } from "./shortcuts.js";
 import { tryVoice } from "./try-it.js";
 import {
@@ -28,6 +29,10 @@ import {
   type TranscriptionLanguage,
 } from "./settings.js";
 import { DEFAULT_SHORTCUT } from "./shortcut-core.js";
+import {
+  SingleSelectPicker,
+  type SingleSelectChoice,
+} from "./ui-components.js";
 
 function requireTui(ctx: ExtensionContext): boolean {
   if (ctx.mode === "tui") return true;
@@ -213,6 +218,7 @@ export async function changeOnboardingModel(
     () => ({
       shortcut: current.shortcut,
       preferredLanguages: languages,
+      transcriptionLanguage: current.transcriptionLanguage,
       microphone: current.microphone,
       chineseOutput: current.chineseOutput,
       backend: current.backend,
@@ -264,12 +270,61 @@ export async function changeOnboardingModel(
   }
 }
 
+export type SetupMode = "local" | "remote";
+
+/**
+ * First screen of first-run setup: on-device model, or a remote ASR endpoint.
+ * A local model is downloaded in both cases because it is the fallback.
+ */
+async function chooseSetupMode(ctx: ExtensionContext): Promise<SetupMode | undefined> {
+  const choices: SingleSelectChoice<SetupMode>[] = [
+    {
+      value: "local",
+      label: "Local model",
+      description: "Transcribe fully on-device; no audio leaves this machine",
+    },
+    {
+      value: "remote",
+      label: "Remote ASR (OpenAI-compatible)",
+      description:
+        "Send audio to an OpenAI-compatible ASR endpoint; a local model is still downloaded as fallback",
+    },
+  ];
+  return ctx.ui.custom<SetupMode | undefined>((tui, theme, keybindings, done) =>
+    new SingleSelectPicker(
+      tui,
+      theme,
+      keybindings,
+      choices,
+      undefined,
+      {
+        title: "Pi Voice setup",
+        subtitle: "How should Pi Voice transcribe your speech?",
+        cancelLabel: "cancel",
+        onboardingStep: 1,
+      },
+      done,
+    ),
+  );
+}
+
 export async function runOnboarding(
   ctx: ExtensionContext,
   shortcut = DEFAULT_SHORTCUT,
 ): Promise<TranscribeSettings | undefined> {
   if (!requireTui(ctx)) return undefined;
 
+  const mode = await chooseSetupMode(ctx);
+  if (!mode) return undefined;
+
+  let backend: BackendSettings | undefined;
+  if (mode === "remote") {
+    backend = await promptRemoteBackend(ctx);
+    if (!backend) return undefined;
+    warnMissingApiKey(ctx, backend.apiKeyEnv);
+  }
+  const usingRemote = backend !== undefined;
+
   let languages = defaultSpokenLanguages();
   // Navigation cannot undo a completed settings commit. Keep it across a
   // return to languages, even if the user then exits without another choice.
@@ -277,7 +332,7 @@ export async function runOnboarding(
   while (true) {
     const chosen = await chooseLanguages(ctx, languages, {
       cancelLabel: "exit",
-      onboardingStep: 1,
+      onboardingStep: 2,
     });
     if (!chosen?.confirmed) return configured;
     languages = chosen.languages;
@@ -285,7 +340,7 @@ export async function runOnboarding(
     // the real wait on this machine.
     const picks = recommendModels(CATALOG_MODELS, languages);
     const { activate, waitForCommits } = createSettingsActivation(
-      () => ({ shortcut, preferredLanguages: languages }),
+      () => ({ shortcut, preferredLanguages: languages, backend }),
       (settings) => {
         configured = settings;
       },
@@ -298,7 +353,10 @@ export async function runOnboarding(
         languages,
         picks,
         activate,
-        { onboardingStep: 2 },
+        {
+          onboardingStep: 3,
+          ...(usingRemote ? { title: "Choose the local fallback model" } : {}),
+        },
       );
       await waitForCommits();
       if (!recommendation) return configured;
@@ -314,8 +372,8 @@ export async function runOnboarding(
         postActivation: "advance",
         onActivate: activate,
         cancelLabel: "back",
-        onboardingStep: 2,
-        title: "Browse all models",
+        onboardingStep: 3,
+        title: usingRemote ? "Choose the local fallback model" : "Browse all models",
       });
       await waitForCommits();
       if (selection?.type === "complete" && configured) {

package/src/openai-asr.ts

@@ -1,6 +1,6 @@
 import OpenAI from "openai";
 import { CAPTURE_SAMPLE_RATE } from "./audio-constants.js";
-import { convertChineseOutput, isChineseLanguage } from "./chinese.js";
+import { containsChineseCharacters, convertChineseOutput, isChineseLanguage } from "./chinese.js";
 import { describeError, writeLog } from "./log.js";
 import type { BackendSettings, ChineseOutput } from "./settings.js";
 import type {
@@ -122,15 +122,15 @@ function createOpenAITransport(config: OpenAIAsrSettings): {
 /**
  * Trims, then applies the Chinese script preference exactly like the local
  * backend. The chat-completions response carries no detected language, so
- * this mirrors the local `finishTranscript` with detectedLanguage = "" —
- * conversion runs only when the configured language is Chinese.
+ * Chinese is inferred from the text itself: Han characters mean the transcript
+ * is Chinese and the preference applies, matching local models that detect it.
  */
 export async function finishRemoteTranscript(
   text: string,
   options: TranscriptionOptions,
 ): Promise<string> {
   const trimmed = text.trim();
-  return isChineseLanguage(options.language ?? "")
+  return isChineseLanguage(options.language ?? "") || containsChineseCharacters(trimmed)
     ? convertChineseOutput(trimmed, options.chineseOutput ?? "simplified")
     : trimmed;
 }

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; falls back to the local model if the request fails",
+    },
+  ];
+  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 silently fall back to local. */
+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 fall back to the local model 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(
@@ -189,12 +189,12 @@ 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, and optionally 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, and optionally a remote ASR endpoint), then retry transcribe_file.",
       );
     }
     if (!existsSync(settings.model.path)) {
@@ -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,7 +96,7 @@ 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[] {
@@ -134,13 +132,23 @@ function settingsHomeChoices(
       value: "transcription-language",
       label: "Transcription language",
       summary: transcriptionLanguageSummary(configured.transcriptionLanguage, model),
-      description: "Language expected in recordings, or automatic detection when supported",
+      description:
+        configured.backend.type === "openai-asr"
+          ? "Used by the local fallback and Chinese output conversion; the remote endpoint detects the language itself"
+          : "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. Gating only on the first two leaves the row unreachable
+  // for anyone relying on auto-detection.
+  const detectsChinese =
+    model.capabilities.languageDetection && model.languages.some(isChineseLanguage);
   if (
     isChineseLanguage(configured.transcriptionLanguage) ||
-    configured.preferredLanguages.some(isChineseLanguage)
+    configured.preferredLanguages.some(isChineseLanguage) ||
+    detectsChinese
   ) {
     choices.push({
       value: "chinese-output",
@@ -280,145 +288,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,
@@ -438,53 +307,16 @@ async function editBackend(
 
   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})`,
+    `Remote ASR configured (${backend.model})`,
   );
-  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;
 }
 

package/src/try-it.ts

@@ -189,7 +189,7 @@ export class TryItPane implements Component {
     const topChrome = (compact: boolean): string[] => [
       ...panelBorder(this.theme).render(width),
       ...(compact ? [] : [""]),
-      ...onboardingHeader(this.theme, title, 3).render(width),
+      ...onboardingHeader(this.theme, title, 4).render(width),
       ...(compact ? [] : [""]),
       ...(compact ? [line(instructions(true))] : text(instructions(false))),
       ...(compact ? [] : [""]),
@@ -208,7 +208,12 @@ export class TryItPane implements Component {
         ...permission,
         ...render(setting("Shortcut", shortcut, this.keys.keyText("voice.tryIt.shortcut"), compact)),
         ...render(setting("Microphone", microphoneSummary(this.settings.microphone), this.keys.keyText("voice.tryIt.microphone"), compact)),
-        ...render(setting("Model", modelName, this.keys.keyText("voice.tryIt.model"), compact)),
+        ...render(setting(
+          this.settings.backend.type === "openai-asr" ? "Fallback" : "Model",
+          modelName,
+          this.keys.keyText("voice.tryIt.model"),
+          compact,
+        )),
         ...(compact ? [] : [""]),
         ...text(hints),
         ...(compact ? [] : [""]),
@@ -230,7 +235,7 @@ export class TryItPane implements Component {
     if (top.length + bottom.length + frameRows + 1 > budget) {
       // Tiny terminals: drop settings, but keep the task and current actions visible.
       top = [
-        ...onboardingHeader(this.theme, title, 3).render(width),
+        ...onboardingHeader(this.theme, title, 4).render(width),
         line(instructions(true)),
       ];
       bottom = [...text(hints), ...panelBorder(this.theme).render(width)];

package/src/ui-components.ts

@@ -37,7 +37,7 @@ export function onboardingHeader(
   theme: UiTheme,
   title: string,
   step: number,
-  total = 3,
+  total = 4,
 ): Component {
   const context = `Pi Voice setup · ${step} of ${total}`;
   const compactContext = `${step} of ${total}`;
@@ -217,6 +217,8 @@ export class SingleSelectPicker<T extends string> extends Container implements F
       searchable?: boolean;
       maximumVisible?: number;
       cancelLabel?: string;
+      /** Adds setup context and progress to the title. */
+      onboardingStep?: number;
       /** Extra footer legend, appended after the ✓ current marker. */
       legend?: string;
       /** Custom row body after the cursor and ✓ markers; handles its own active styling. */
@@ -245,7 +247,11 @@ export class SingleSelectPicker<T extends string> extends Container implements F
 
     this.addChild(panelBorder(theme));
     this.addChild(new Spacer(1));
-    this.addChild(this.titleText);
+    if (typeof options.onboardingStep === "number") {
+      this.addChild(onboardingHeader(theme, options.title, options.onboardingStep));
+    } else {
+      this.addChild(this.titleText);
+    }
     if (this.subtitleText) this.addChild(this.subtitleText);
     this.addChild(new Spacer(1));
     if (options.searchable) {