@tychenjiajun/pi-voice 0.3.0 → 0.5.0

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") {
@@ -189,7 +193,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 +212,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(
+          localModel ? "Model" : "Local model",
+          modelName,
+          this.keys.keyText("voice.tryIt.model"),
+          compact,
+        )),
         ...(compact ? [] : [""]),
         ...text(hints),
         ...(compact ? [] : [""]),
@@ -230,7 +239,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) {