@tychenjiajun/pi-voice 0.4.0 → 0.5.0

package/README.md

@@ -4,7 +4,7 @@ Speech-to-text for Pi — on-device model or OpenAI-compatible remote ASR, with
 
 Press a keyboard shortcut, talk, and the resulting transcript will be put directly into your chat.
 
-> **Fork notice.** `@tychenjiajun/pi-voice` is a fork of [`@earendil-works/pi-voice`](https://github.com/earendil-works/pi-voice) that adds a remote ASR backend (any OpenAI-compatible `input_audio` chat-completions endpoint) with the local model kept as a fallback, plus compaction-style post-processing that refines a transcript with Pi's own model. It is published independently under a personal npm scope. See the [changelog](#changelog) for what changed.
+> **Fork notice.** `@tychenjiajun/pi-voice` is a fork of [`@earendil-works/pi-voice`](https://github.com/earendil-works/pi-voice) that adds a remote ASR backend (any OpenAI-compatible `input_audio` chat-completions endpoint) in an exclusive local-only or remote-only setup, plus compaction-style post-processing that refines a transcript with Pi's own model. It is published independently under a personal npm scope. See the [changelog](#changelog) for what changed.
 
 ## Install
 
@@ -49,12 +49,13 @@ export OPENAI_API_KEY=sk-...
 
 Behavior:
 
-- **Local model stays as 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 instead; the failure is logged to `~/.pi/agent/pi-voice.log`. Aborted/cancelled transcriptions are never retried locally.
+- **Remote-only mode.** Remote settings store no local model: setup skips the model download step, and a failed remote request (network, quota, HTTP error, or an unset API key) surfaces as an error instead of being retried offline. Failures are logged to `~/.pi/agent/pi-voice.log`.
 - **Batch-only.** Remote transcription happens when recording stops (the ASR request carries the whole clip), so there is no streaming preview.
-- **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).
+- **16 kHz mono WAV** is uploaded as a base64 WAV data URL.
+- **Exclusive modes.** Switching **Transcription backend** to **Local model** asks you to pick a model first; switching to **Remote ASR** drops the local model from settings. The **Model** and **Transcription language** settings rows appear only in local mode.
+- `transcribe_file` uses whichever mode is configured — in remote mode the file audio is sent to the endpoint instead of a local model.
 
-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.
+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. The **Chinese output** row stays reachable in remote mode, since the endpoint can always produce Chinese.
 
 ## Post-processing (compaction-style refinement)
 
@@ -111,10 +112,21 @@ export PI_VOICE_FFMPEG_PATH=/path/to/ffmpeg
 
 The legacy `PI_TRANSCRIBE_FFMPEG_PATH` variable remains supported when `PI_VOICE_FFMPEG_PATH` is not set.
 
-When FFmpeg is unavailable, `transcribe_file` reports platform-specific guidance to the agent. The agent should ask before running a package-manager command. Model setup is still explicit: run `/voice-settings` once in the interactive TUI to choose and, after confirmation, download a local model.
+When FFmpeg is unavailable, `transcribe_file` reports platform-specific guidance to the agent. The agent should ask before running a package-manager command. Model setup is still explicit: run `/voice-settings` once in the interactive TUI to choose a mode and, in local mode, confirm the download of a local model.
 
 ## Changelog
 
+### 0.5.0
+
+**Changed — Exclusive local / remote modes (no fallback)**
+
+- Local and remote transcription are now mutually exclusive: remote settings store no local model, and selecting a local model drops any remote configuration. Settings files with both are normalized to remote-only on read.
+- First-run setup in remote mode skips the model step entirely; no local model is downloaded (onboarding jumps from step 2 to step 4, the Try it pane).
+- Removed the local fallback for remote ASR. Network, quota, HTTP, and unset-API-key failures now surface directly and are logged to `~/.pi/agent/pi-voice.log`.
+- The settings menu hides the **Model** and **Transcription language** rows in remote mode and always shows **Chinese output** there; switching the backend to local asks you to pick a model first, and switching to remote clears the local model.
+- Try it shows a **Local model** row in remote mode; choosing a model from it switches setup to local mode.
+- `transcribe_file` works in either mode and reports the remote model name in its details when remote.
+
 ### 0.4.0
 
 **Added — Backend choice in first-run setup**

package/package.json

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

package/src/dictation-controller.ts

@@ -1,7 +1,11 @@
 import { CAPTURE_SAMPLE_RATE } from "./audio-constants.js";
 import { describeError, log, logStep, sinceKeyPress } from "./log.js";
 import { PcmChunker } from "./pcm-chunker.js";
-import type { MicrophoneSetting, TranscribeSettings } from "./settings.js";
+import {
+  transcriptionModelLabel,
+  type MicrophoneSetting,
+  type TranscribeSettings,
+} from "./settings.js";
 import type { DictationReservation, TranscriptionService } from "./transcription-service.js";
 
 /** What a recording captured. `interruption` is why it ended early, if it did. */
@@ -90,7 +94,7 @@ export class DictationController {
   /** Reserves the model for a take; on failure the state says why. */
   private reserve(settings: TranscribeSettings): Take | undefined {
     this.readiness = "loading";
-    logStep("reserving model", settings.model.id);
+    logStep("reserving model", transcriptionModelLabel(settings));
     const reservedAt = this.now();
     let reservation: DictationReservation;
     try {

package/src/file-transcription.ts

@@ -12,7 +12,7 @@ import { basename, join, resolve } from "node:path";
 import { Type } from "typebox";
 import { AsyncLimiter } from "./async-limiter.js";
 import { polishTranscript } from "./polish.js";
-import type { TranscribeSettings } from "./settings.js";
+import { transcriptionModelLabel, type TranscribeSettings } from "./settings.js";
 import type { TranscriptionService } from "./transcription-service.js";
 
 const CONTEXT_LINE_LENGTH = 1_000;
@@ -84,7 +84,7 @@ export function registerFileTranscriptionTool(
   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), then applies Pi Voice's compaction-style post-processing when it is enabled. 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.`,
+    description: `Transcribe speech from a local audio or video file using Pi Voice's configured transcription backend (local model or remote ASR endpoint), then applies Pi Voice's compaction-style post-processing when it is enabled. 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.",
@@ -118,10 +118,11 @@ export function registerFileTranscriptionTool(
 
           const configured = await options.getSettings();
           const service = await options.getService();
+          const modelLabel = transcriptionModelLabel(configured);
           if (fileOperations.saturated) {
             onUpdate?.({
               content: [{ type: "text", text: "Waiting for file transcription capacity…" }],
-              details: { inputPath, modelId: configured.model.id, seconds: 0 },
+              details: { inputPath, modelId: modelLabel, seconds: 0 },
             });
           }
 
@@ -129,13 +130,13 @@ export function registerFileTranscriptionTool(
             if (fileDecoders.saturated) {
               onUpdate?.({
                 content: [{ type: "text", text: `Waiting to decode ${basename(inputPath)}…` }],
-                details: { inputPath, modelId: configured.model.id, seconds: 0 },
+                details: { inputPath, modelId: modelLabel, 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 },
+                details: { inputPath, modelId: modelLabel, seconds: 0 },
               });
               const { decodeFileAudio } = await import("./file-audio.js");
               return decodeFileAudio(inputPath, operationSignal);
@@ -150,7 +151,7 @@ export function registerFileTranscriptionTool(
               ],
               details: {
                 inputPath,
-                modelId: configured.model.id,
+                modelId: modelLabel,
                 seconds: audio.seconds,
               },
             });
@@ -170,7 +171,7 @@ export function registerFileTranscriptionTool(
               : rawTranscript;
             const details: FileTranscriptionDetails = {
               inputPath,
-              modelId: configured.model.id,
+              modelId: modelLabel,
               seconds: audio.seconds,
             };
 

package/src/onboarding.ts

@@ -20,6 +20,7 @@ import { tryVoice } from "./try-it.js";
 import {
   DEFAULT_MICROPHONE,
   settingsForModel,
+  settingsRemoteOnly,
   writeSettings,
   type BackendSettings,
   type ChineseOutput,
@@ -96,7 +97,7 @@ export async function runModelSelection(
     }),
     (settings) => {
       configured = settings;
-      currentModelId = settings.model.id;
+      currentModelId = settings.model?.id;
     },
   );
 
@@ -237,7 +238,7 @@ export async function changeOnboardingModel(
           expanded: true,
           onboardingStep: 3,
         })
-      : await chooseCatalogModel(ctx, languages, chosen?.model.id ?? current.model.id, {
+      : await chooseCatalogModel(ctx, languages, chosen?.model?.id ?? current.model?.id, {
           postActivation: "advance",
           onActivate: activation.activate,
           cancelLabel: "back",
@@ -274,7 +275,7 @@ 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.
+ * The modes are exclusive: remote setup downloads no local model.
  */
 async function chooseSetupMode(ctx: ExtensionContext): Promise<SetupMode | undefined> {
   const choices: SingleSelectChoice<SetupMode>[] = [
@@ -287,7 +288,7 @@ async function chooseSetupMode(ctx: ExtensionContext): Promise<SetupMode | undef
       value: "remote",
       label: "Remote ASR (OpenAI-compatible)",
       description:
-        "Send audio to an OpenAI-compatible ASR endpoint; a local model is still downloaded as fallback",
+        "Send audio to an OpenAI-compatible ASR endpoint; no local model is downloaded",
     },
   ];
   return ctx.ui.custom<SetupMode | undefined>((tui, theme, keybindings, done) =>
@@ -323,7 +324,6 @@ export async function runOnboarding(
     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
@@ -336,6 +336,18 @@ export async function runOnboarding(
     });
     if (!chosen?.confirmed) return configured;
     languages = chosen.languages;
+
+    // Remote mode is remote-only: no model step, settings are complete once
+    // the endpoint and languages are chosen.
+    if (backend?.type === "openai-asr") {
+      const settings = settingsRemoteOnly({ backend, shortcut, preferredLanguages: languages });
+      if (!(await saveOnboardingSettings(ctx, settings))) return configured;
+      configured = settings;
+      return finishOnboarding(ctx, configured, (current) =>
+        changeOnboardingModel(ctx, current),
+      );
+    }
+
     // The picks are judged on the benchmark rig; the Try it step measures
     // the real wait on this machine.
     const picks = recommendModels(CATALOG_MODELS, languages);
@@ -355,7 +367,6 @@ export async function runOnboarding(
         activate,
         {
           onboardingStep: 3,
-          ...(usingRemote ? { title: "Choose the local fallback model" } : {}),
         },
       );
       await waitForCommits();
@@ -368,12 +379,12 @@ export async function runOnboarding(
         continue;
       }
 
-      const selection = await chooseCatalogModel(ctx, languages, configured?.model.id, {
+      const selection = await chooseCatalogModel(ctx, languages, configured?.model?.id, {
         postActivation: "advance",
         onActivate: activate,
         cancelLabel: "back",
         onboardingStep: 3,
-        title: usingRemote ? "Choose the local fallback model" : "Browse all models",
+        title: "Browse all models",
       });
       await waitForCommits();
       if (selection?.type === "complete" && configured) {

package/src/openai-asr.ts

@@ -5,18 +5,11 @@ import { describeError, writeLog } from "./log.js";
 import type { BackendSettings, ChineseOutput } from "./settings.js";
 import type {
   DictationStream,
-  TranscribeCppBackend,
   TranscriptionOptions,
 } from "./transcription.js";
 
 type OpenAIAsrSettings = Extract<BackendSettings, { type: "openai-asr" }>;
 
-/** The slice of the local backend this module needs for offline fallback. */
-export type LocalFallback = Pick<
-  TranscribeCppBackend,
-  "prepare" | "transcribe" | "dispose"
->;
-
 export type AsrRequest = {
   /** `data:audio/wav;base64,…` of the whole recording. */
   dataUrl: string;
@@ -136,8 +129,6 @@ export async function finishRemoteTranscript(
 }
 
 export type OpenAIAsrBackendDeps = {
-  /** Creates the local model used when a remote call fails. */
-  createFallback?: () => Promise<LocalFallback>;
   /** Overrides the network transport (tests). */
   transport?: AsrTransport;
 };
@@ -145,12 +136,11 @@ export type OpenAIAsrBackendDeps = {
 /**
  * Batch-only remote backend: `startStream` resolves to undefined so the
  * service records the whole clip and transcribes it after stop, exactly like
- * a non-streaming local model. Remote failures fall back to the local model;
- * aborts are never retried locally.
+ * a non-streaming local model. Remote failures surface to the caller; there
+ * is no local fallback.
  */
 export class OpenAIAsrBackend {
   private client: { transport: AsrTransport; dispose: () => void } | undefined;
-  private fallback: Promise<LocalFallback> | undefined;
   private disposed = false;
   private readonly injected: AsrTransport | undefined;
 
@@ -164,8 +154,8 @@ export class OpenAIAsrBackend {
   async prepare(): Promise<void> {
     if (this.disposed) throw new Error("Remote ASR backend has been disposed");
     // The transport is created lazily in transcribe() so that a missing API
-    // key (or any construction failure) falls back to the local model instead
-    // of failing prepare() and blocking every subsequent transcription.
+    // key surfaces per recording instead of failing prepare() and blocking
+    // every subsequent transcription.
   }
 
   /** Batch-only: the dictation service drops live chunks and transcribes on stop. */
@@ -184,9 +174,9 @@ export class OpenAIAsrBackend {
       if (!transport) {
         if (this.disposed) throw new Error("Remote ASR backend has been disposed");
         // Lazily build the transport inside the try so a missing API key or
-        // any construction failure falls back to the local model. Success is
-        // cached; a failure is not, so a later call retries once the env is
-        // fixed.
+        // any construction failure is reported like a request failure.
+        // Success is cached; a failure is not, so a later call retries once
+        // the env is fixed.
         const client = this.client ?? createOpenAITransport(this.config);
         this.client = client;
         transport = client.transport;
@@ -205,20 +195,12 @@ export class OpenAIAsrBackend {
       return await finishRemoteTranscript(text, options);
     } catch (error) {
       if (signal?.aborted || this.disposed) throw error;
-      if (!this.deps.createFallback) throw error;
       writeLog(
         "warn",
         "voice",
-        `remote ASR failed (${describeError(error)}); falling back to the local model`,
+        `remote ASR failed (${describeError(error)})`,
       );
-      try {
-        const local = await this.fallbackBackend();
-        return await local.transcribe(pcm, options);
-      } catch (fallbackError) {
-        throw new Error(
-          `Remote ASR failed (${describeError(error)}) and the local fallback failed (${describeError(fallbackError)})`,
-        );
-      }
+      throw error;
     }
   }
 
@@ -227,21 +209,5 @@ export class OpenAIAsrBackend {
     this.disposed = true;
     this.client?.dispose();
     this.client = undefined;
-    if (this.fallback) {
-      const local = await this.fallback.catch(() => undefined);
-      await local?.dispose().catch(() => undefined);
-    }
-  }
-
-  private fallbackBackend(): Promise<LocalFallback> {
-    if (!this.fallback) {
-      // A rejected fallback is not cached: a later attempt can re-create the
-      // local model instead of re-throwing a stale failure.
-      this.fallback = this.deps.createFallback!().catch((error) => {
-        this.fallback = undefined;
-        throw error;
-      });
-    }
-    return this.fallback;
   }
 }

package/src/remote-asr.ts

@@ -26,7 +26,7 @@ export async function chooseBackendType(
       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",
+        "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) =>
@@ -74,11 +74,11 @@ function remoteBackendsEqual(
   );
 }
 
-/** Warn when the named variable is unset, so remote calls silently fall back to local. */
+/** 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 fall back to the local model until it is set`,
+    `${apiKeyEnv} is not set in Pi's environment; remote transcription will fail until it is set`,
     "warning",
   );
 }

package/src/runtime.ts

@@ -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 set up Pi Voice (a local model, and optionally a remote ASR endpoint), 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 set up Pi Voice (choose and download a local model, and optionally a remote ASR endpoint), 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

package/src/settings-menu.ts

@@ -100,7 +100,9 @@ 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",
@@ -108,18 +110,24 @@ export 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",
@@ -128,24 +136,25 @@ export 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:
-        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",
-    },
-  ];
+      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. Gating only on the first two leaves the row unreachable
-  // for anyone relying on auto-detection.
+  // 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);
+    model?.capabilities.languageDetection && model.languages.some(isChineseLanguage);
   if (
+    remote ||
     isChineseLanguage(configured.transcriptionLanguage) ||
     configured.preferredLanguages.some(isChineseLanguage) ||
     detectsChinese
@@ -264,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(
@@ -297,12 +307,26 @@ 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 =
@@ -313,8 +337,8 @@ async function editBackend(
   const saved = await saveUpdatedSettings(
     ctx,
     configured,
-    { ...configured, backend },
-    `Remote ASR configured (${backend.model})`,
+    { ...configured, backend, model: undefined },
+    `Remote ASR configured (${backend.model}); the local model is no longer used`,
   );
   if (saved) warnMissingApiKey(ctx, backend.apiKeyEnv);
   return saved;
@@ -514,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,
@@ -550,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,

package/src/settings.ts

@@ -21,8 +21,8 @@ export type ChineseOutput = "simplified" | "traditional-taiwan" | "traditional-h
 /**
  * Where recordings are transcribed. `transcribe-cpp` runs a local catalog
  * model; `openai-asr` uploads to any OpenAI-compatible chat-completions ASR
- * endpoint via the `input_audio` content block. The local catalog model stays
- * configured in both cases and acts as the fallback when the remote call fails.
+ * endpoint via the `input_audio` content block. The two are exclusive: remote
+ * mode stores no local model, and local mode has no remote configuration.
  */
 export type BackendSettings =
   | { type: "transcribe-cpp" }
@@ -57,7 +57,11 @@ export type TranscribeSettings = {
   polishEnabled?: boolean;
   /** Optional post-processing model override; absent uses the agent's current model. */
   polishModel?: PolishModelRef;
-  model: {
+  /**
+   * The local catalog model. Present only in local mode (backend
+   * `transcribe-cpp`); remote mode stores no local model.
+   */
+  model?: {
     source: "catalog";
     id: string;
     path: string;
@@ -164,6 +168,17 @@ function normalizePolishModel(value: unknown): PolishModelRef | undefined {
   return { provider: value.provider.trim(), id: value.id.trim() };
 }
 
+function validateModelValue(
+  value: unknown,
+): { id: string; path: string; catalogModel: CatalogModel } | undefined {
+  if (!isObject(value) || value.source !== "catalog") return undefined;
+  if (typeof value.id !== "string") return undefined;
+  const catalogModel = getCatalogModel(value.id);
+  if (!catalogModel) return undefined;
+  if (typeof value.path !== "string" || value.path.length === 0) return undefined;
+  return { id: value.id, path: value.path, catalogModel };
+}
+
 function validateSettings(value: unknown): TranscribeSettings | undefined {
   if (!isObject(value) || value.version !== SETTINGS_VERSION) return undefined;
   const backend = validateBackend(value.backend);
@@ -171,36 +186,43 @@ function validateSettings(value: unknown): TranscribeSettings | undefined {
   const shortcut =
     typeof value.shortcut === "string" ? normalizeShortcut(value.shortcut) : undefined;
   if (!shortcut) return undefined;
-  if (!isObject(value.model) || value.model.source !== "catalog") return undefined;
-  if (typeof value.model.id !== "string") return undefined;
-  const model = getCatalogModel(value.model.id);
-  if (!model) return undefined;
-  if (typeof value.model.path !== "string" || value.model.path.length === 0) return undefined;
+
+  const selected = validateModelValue(value.model);
+  // Local mode needs a model; remote mode drops any leftover local model so
+  // settings are ever either local-only or remote-only, never both.
+  if (backend.type === "transcribe-cpp" && !selected) return undefined;
 
   const preferredLanguages = normalizeLanguages(value.preferredLanguages);
   const microphone = validateMicrophone(value.microphone);
   if (!preferredLanguages || !microphone) return undefined;
   const polishModel = normalizePolishModel(value.polishModel);
 
+  // The remote endpoint detects the language itself; the stored language only
+  // triggers Chinese script conversion, so any previous value is kept as-is.
+  const transcriptionLanguage =
+    backend.type === "openai-asr"
+      ? typeof value.transcriptionLanguage === "string" && value.transcriptionLanguage
+        ? value.transcriptionLanguage
+        : "auto"
+      : transcriptionLanguageForModel(
+          value.transcriptionLanguage,
+          selected!.catalogModel,
+          preferredLanguages,
+        );
+
   return {
     version: SETTINGS_VERSION,
     backend,
     shortcut,
     preferredLanguages,
-    transcriptionLanguage: transcriptionLanguageForModel(
-      value.transcriptionLanguage,
-      model,
-      preferredLanguages,
-    ),
+    transcriptionLanguage,
     chineseOutput: validateChineseOutput(value.chineseOutput),
     microphone,
     polishEnabled: value.polishEnabled === true,
     ...(polishModel ? { polishModel } : {}),
-    model: {
-      source: "catalog",
-      id: value.model.id,
-      path: value.model.path,
-    },
+    ...(backend.type === "transcribe-cpp"
+      ? { model: { source: "catalog" as const, id: selected!.id, path: selected!.path } }
+      : {}),
   };
 }
 
@@ -262,7 +284,10 @@ type ModelSettingsOptions = {
   transcriptionLanguage?: TranscriptionLanguage;
   chineseOutput?: ChineseOutput;
   microphone?: MicrophoneSetting;
-  /** Preserved across model re-selection; defaults to the local backend. */
+  /**
+   * Preserved across model re-selection when local; picking a model always
+   * yields local-only settings, since the backends are exclusive.
+   */
   backend?: BackendSettings;
   /** Preserved across model re-selection; defaults to disabled. */
   polishEnabled?: boolean;
@@ -282,7 +307,11 @@ export function settingsForModel(
   ];
   return {
     version: SETTINGS_VERSION,
-    backend: options.backend ?? { type: "transcribe-cpp" },
+    // Exclusive modes: a selected local model drops any remote configuration.
+    backend:
+      options.backend && options.backend.type === "transcribe-cpp"
+        ? options.backend
+        : { type: "transcribe-cpp" },
     shortcut: options.shortcut ?? DEFAULT_SHORTCUT,
     preferredLanguages,
     transcriptionLanguage: transcriptionLanguageForModel(
@@ -297,3 +326,33 @@ export function settingsForModel(
     model: { source: "catalog", id: modelId, path: modelPath },
   };
 }
+
+type RemoteSettingsOptions = Omit<ModelSettingsOptions, "backend"> & {
+  backend: Extract<BackendSettings, { type: "openai-asr" }>;
+};
+
+/** Remote-only settings: no local model is stored, so the endpoint is the sole backend. */
+export function settingsRemoteOnly(options: RemoteSettingsOptions): TranscribeSettings {
+  const preferredLanguages = [
+    ...new Set((options.preferredLanguages ?? ["en"]).map(languageIdentity)),
+  ];
+  return {
+    version: SETTINGS_VERSION,
+    backend: options.backend,
+    shortcut: options.shortcut ?? DEFAULT_SHORTCUT,
+    preferredLanguages,
+    // The endpoint detects the language itself; "auto" keeps the stored value
+    // from triggering Chinese conversion against a language that is not there.
+    transcriptionLanguage: options.transcriptionLanguage ?? "auto",
+    chineseOutput: options.chineseOutput ?? defaultChineseOutput(),
+    microphone: { ...(options.microphone ?? DEFAULT_MICROPHONE) },
+    polishEnabled: options.polishEnabled ?? false,
+    ...(options.polishModel ? { polishModel: options.polishModel } : {}),
+  };
+}
+
+/** The configured transcription source: local model id, or the remote ASR model name. */
+export function transcriptionModelLabel(settings: TranscribeSettings): string {
+  if (settings.model) return settings.model.id;
+  return settings.backend.type === "openai-asr" ? settings.backend.model : "none";
+}

package/src/transcription-service.ts

@@ -59,13 +59,22 @@ type BackendFactory = (
   settings: TranscribeSettings,
 ) => ReusableBackend | Promise<ReusableBackend>;
 
-/** Local backends key on the model file; remote adds its endpoint identity. */
+/** Local backends key on the model file; remote keys on endpoint identity. */
+function requireLocalModel(settings: TranscribeSettings): { path: string } {
+  if (!settings.model) {
+    throw new Error(
+      "No local model is configured. Run /voice-settings and choose a local model, or switch the transcription backend to remote ASR.",
+    );
+  }
+  return settings.model;
+}
+
 function backendKeyFor(settings: TranscribeSettings): string {
   if (settings.backend.type === "openai-asr") {
     const { baseUrl, model } = settings.backend;
-    return `openai-asr:${baseUrl}|${model}|${settings.model.path}`;
+    return `openai-asr:${baseUrl}|${model}`;
   }
-  return settings.model.path;
+  return requireLocalModel(settings).path;
 }
 
 function abortError(signal: AbortSignal): Error {
@@ -104,19 +113,12 @@ export class TranscriptionService {
 
   constructor(
     private readonly createBackend: BackendFactory = async (_key, settings) => {
-      const { TranscribeCppBackend } = await import("./transcription.js");
       if (settings.backend.type === "openai-asr") {
         const { OpenAIAsrBackend } = await import("./openai-asr.js");
-        const modelPath = settings.model.path;
-        return new OpenAIAsrBackend(settings.backend, {
-          createFallback: async () => {
-            const local = new TranscribeCppBackend(modelPath);
-            await local.prepare();
-            return local;
-          },
-        });
+        return new OpenAIAsrBackend(settings.backend);
       }
-      return new TranscribeCppBackend(settings.model.path);
+      const { TranscribeCppBackend } = await import("./transcription.js");
+      return new TranscribeCppBackend(requireLocalModel(settings).path);
     },
   ) {}
 

package/src/try-it.ts

@@ -116,7 +116,10 @@ export class TryItPane implements Component {
 
     const state = this.dictation.state;
     const shortcut = displayShortcut(this.settings.shortcut);
-    const modelName = getCatalogModel(this.settings.model.id)?.name ?? this.settings.model.id;
+    const localModel = this.settings.model;
+    const modelName = localModel
+      ? getCatalogModel(localModel.id)?.name ?? localModel.id
+      : "Not installed (remote mode)";
     const title = "Try it";
     const fg = (color: Parameters<UiTheme["fg"]>[0], text: string) => this.theme.fg(color, text);
     const text = (value: string) => new Text(value, PANEL_PADDING, 0).render(width);
@@ -132,7 +135,8 @@ export class TryItPane implements Component {
       });
     } else if (
       (state.phase === "idle" || state.phase === "ready") &&
-      this.dictation.modelState === "loading"
+      this.dictation.modelState === "loading" &&
+      localModel
     ) {
       activity = fg("muted", `Loading ${modelName}… You can start recording now.`);
     } else if (state.phase === "transcribing") {
@@ -147,7 +151,7 @@ export class TryItPane implements Component {
       activity = fg("muted", formatTranscriptionSummary(speechSeconds, transcribeSeconds));
       if (interruption) {
         details = fg("warning", `The microphone stopped after ${speechSeconds.toFixed(1)}s: ${interruption.message}`);
-      } else if (needsFasterModel(speechSeconds, transcribeSeconds)) {
+      } else if (localModel && needsFasterModel(speechSeconds, transcribeSeconds)) {
         details = fg("warning", `Slow on this machine? Press ${this.keys.keyText("voice.tryIt.model")} to try another model.`);
       }
     } else if (state.phase === "error") {
@@ -209,7 +213,7 @@ export class TryItPane implements Component {
         ...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(
-          this.settings.backend.type === "openai-asr" ? "Fallback" : "Model",
+          localModel ? "Model" : "Local model",
           modelName,
           this.keys.keyText("voice.tryIt.model"),
           compact,