pi-voice-input 0.2.11 → 0.2.13

package/README.md

@@ -1,186 +1,158 @@
 # pi Voice Input
 
-A publishable, pure TypeScript [pi](https://pi.dev/) extension for Linux and macOS voice dictation into pi's editor.
+Voice dictation for [pi](https://pi.dev/). Press one shortcut, speak naturally, and insert the transcript into the editor without sending the prompt automatically.
 
-- Press `Ctrl+Shift+R` once to start recording.
-- Press `Ctrl+Shift+R` again to stop.
-- The extension sends the audio to VolcEngine WebSocket ASR.
-- The recognized text is inserted into pi's editor without submitting.
+## Why use it?
 
-Current scope:
+Typing long prompts can slow you down. `pi-voice-input` lets you:
 
-- Linux uses `pw-record` from PipeWire tools or `arecord` from alsa-utils.
-- macOS uses `afrecord` when present, otherwise `ffmpeg` with AVFoundation.
-- A VolcEngine Speech API key is required.
-- This is not a local/offline ASR engine.
+- capture ideas quickly while you are thinking out loud
+- dictate long instructions, notes, bug reports, or code review comments
+- speak naturally in Chinese, English, or a mix of both
+- keep your hands on the keyboard with a simple toggle shortcut
+- review or edit the inserted text before you submit it
+- optionally polish dictated text with one of your configured pi models
 
-The provider layer is intended to be extensible. **Current version supports only VolcEngine WebSocket ASR.**
+## Features
 
-No Python, `uv`, or upload service is required for normal shortcut usage. On macOS systems without `afrecord`, install `ffmpeg` for recording.
+- **One-key dictation**: `Ctrl+Shift+R` starts recording; press it again to stop and insert text.
+- **Editor-safe workflow**: transcription is pasted into the current editor only. It does not auto-submit.
+- **Chinese/English mixed input**: handles prompts that switch between Chinese, English, product names, and technical terms.
+- **Works on Linux and macOS**: uses common system recording tools.
+- **Lowers sound while you speak**: automatically turns down system audio during recording, then restores it afterwards.
+- **Optional transcript polish**: use a pi model to clean up punctuation and wording before insertion.
+- **Simple setup commands**: configure from inside pi with `/voice init` and `/voice key`.
 
-## Architecture
+Current speech provider: **VolcEngine Speech ASR**. A VolcEngine Speech API key is required.
 
-```text
-pi extension: extensions/index.ts → extensions/voice-input.ts
-  ├─ registers Ctrl+Shift+R and /voice commands
-  ├─ starts/stops a local recorder process
-  │    ├─ Linux preferred: pw-record
-  │    ├─ Linux fallback: arecord
-  │    └─ macOS: afrecord, or ffmpeg/AVFoundation fallback
-  ├─ records a temporary 16 kHz mono 16-bit WAV
-  ├─ parses the WAV container in TypeScript and extracts raw PCM
-  ├─ sends PCM frames to the configured ASR provider via ws
-  │    └─ current provider: VolcEngine /api/v3/sauc/bigmodel_nostream
-  ├─ optionally post-processes raw ASR text with a configured pi model
-  │    └─ default: disabled; set polishModel to enable it
-  └─ pastes the final transcript into pi's editor
-```
-
-Runtime package dependency:
-
-- `ws`
-
-System dependency, one of:
-
-- Linux: `pw-record` from PipeWire tools, preferred
-- Linux: `arecord` from alsa-utils, fallback
-- macOS: `afrecord` when present, or `ffmpeg` from Homebrew (`brew install ffmpeg`) as the AVFoundation fallback
-
-On macOS, grant Terminal, ffmpeg, or your pi host app microphone permission when prompted. If macOS has previously denied microphone access, enable it in System Settings → Privacy & Security → Microphone.
-
-## Install / Update
-
-Install the published package with pi:
+## Install
 
 ```bash
 pi install npm:pi-voice-input
 ```
 
-Update to the latest published version:
+Update later with:
 
 ```bash
 pi update npm:pi-voice-input
 ```
 
-If pi is already running, restart pi after installing or updating. `/reload` may not replace code that was already loaded by the current pi process.
+Restart pi after installing or updating.
 
-## Providers
+## First-time setup
 
-The extension is structured around a provider boundary: recording, editor insertion, and command handling are generic; ASR transport/protocol logic is provider-specific.
+1. Install the extension:
 
-Currently implemented provider:
+   ```bash
+   pi install npm:pi-voice-input
+   ```
 
-- VolcEngine WebSocket ASR (`bigmodel_nostream`)
+2. Restart pi.
 
-Planned provider direction:
+3. Create the local config:
 
-- add more ASR providers without changing the shortcut/user workflow
-- keep provider credentials and options isolated in config
+   ```text
+   /voice init
+   ```
 
-## Configure
+4. Add your VolcEngine Speech API key:
 
-All plugin settings live in one JSON file:
+   ```text
+   /voice key
+   ```
 
-```text
-~/.pi/agent/voice-input.config.json
-```
+   Get your key here:
 
-Package-local and project-local env files are not read.
+   https://console.volcengine.com/speech/new/setting/apikeys?projectName=default
 
-Create or normalize the file from inside pi:
+5. Check that pi sees your setup:
 
-```text
-/voice init
-```
+   ```text
+   /voice config
+   ```
+
+6. Press `Ctrl+Shift+R`, speak, then press `Ctrl+Shift+R` again to insert the transcript.
+
+## Use
 
-Then set the VolcEngine Speech API key:
+Press:
 
 ```text
-/voice key
+Ctrl+Shift+R
 ```
 
-The key URL is also shown inside pi when the key is missing, when you run `/voice key`, and in `/voice help`:
-
-https://console.volcengine.com/speech/new/setting/apikeys?projectName=default
+Then speak naturally in Chinese, English, or both. Press `Ctrl+Shift+R` again to stop recording. The recognized text appears in the editor at your cursor.
 
-The config file is plain JSON and can be edited directly:
+Useful commands:
 
-```json
-{
-  "volcApiKey": "",
-  "polishModel": ""
-}
+```text
+/voice start    start recording
+/voice stop     stop, transcribe, and insert text
+/voice toggle   start or stop recording
+/voice cancel   stop and discard the recording
+/voice status   show current recorder state
+/voice config   show non-secret configuration
+/voice key      set or replace the API key
+/voice help     show setup help
 ```
 
-`polishModel` is disabled by default. Set it to any model shown by `pi --list-models` to enable transcript polish. If polishing fails, the raw ASR transcript is inserted instead.
+## Optional: polish dictated text
 
-Verify the effective non-secret config:
+By default, pi inserts the raw transcript. To let a pi model clean up punctuation and wording, set `polishModel` in:
 
 ```text
-/voice config
+~/.pi/agent/voice-input.config.json
 ```
 
-## Usage
+Use any model name shown by:
 
-Shortcut:
-
-```text
-Ctrl+Shift+R
+```bash
+pi --list-models
 ```
 
-Slash commands:
+Example:
 
-```text
-/voice start    # start recording
-/voice stop     # stop, transcribe, insert text
-/voice toggle   # start if idle, stop if recording
-/voice cancel   # stop recording and discard local audio without transcribing
-/voice status   # show recorder state
-/voice config   # show effective non-secret config and whether API key is detected
-/voice init     # create or normalize ~/.pi/agent/voice-input.config.json
-/voice key      # prompt for and save the current provider API key
-/voice help     # show setup help, including the explicit VolcEngine API key URL
+```json
+{
+  "volcApiKey": "",
+  "polishModel": "your-model-name"
+}
 ```
 
-## Notes
+If polishing fails, the raw transcript is inserted instead.
 
-- The extension uses post-recording WebSocket ASR: it records locally to a per-run temporary WAV, sends the stopped recording in chunks, then deletes the temporary audio. It is optimized for fast voice input, not live subtitles.
-- The default ASR segment size is intentionally larger than realtime packet sizes because this workflow sends already-recorded audio.
-- The transcript is inserted into the editor only; it is not submitted automatically.
-- Recorder stdout/stderr is not logged to disk, to avoid retaining potentially sensitive runtime data.
-- On startup, legacy `~/.pi/agent/voice-input/recordings` and `~/.pi/agent/voice-input/logs` artifacts are cleaned up when they are not part of an active recording.
-- When `polishModel` is set, polishing uses the unsent editor draft and recent session messages as context, but outputs only the refined voice text to insert at the current cursor. It must not reconstruct the full draft; the final text is pasted without replacing existing editor content.
-- While recording, the status line shows `● Mic on: [device name] — press Ctrl+Shift+R again to stop/transcribe` in the current theme accent color; no separate popup is shown when recording starts.
+## System requirements
 
-## Development
+Linux needs one recording tool:
 
-See [CONTRIBUTING.md](CONTRIBUTING.md) for contribution guidelines, validation commands, and pull request expectations.
+- `pw-record` from PipeWire tools, recommended
+- or `arecord` from alsa-utils
 
-Clone the repo and install dependencies:
+macOS uses the built-in recorder when available. If recording does not work, install ffmpeg:
 
 ```bash
-git clone git@github.com:tr-nc/pi-voice-input.git
-cd pi-voice-input
-npm install
+brew install ffmpeg
 ```
 
-Run directly from the package checkout:
+On macOS, allow microphone access for your terminal or pi host app when prompted. You can also check System Settings → Privacy & Security → Microphone.
 
-```bash
-pi -e .
-```
+## Privacy notes
 
-Or install the local checkout while developing:
+- Your API key is stored locally in `~/.pi/agent/voice-input.config.json`.
+- Recordings are temporary and are removed after use.
+- Transcribed text is inserted into the editor so you can review it before submitting.
 
-```bash
-pi install .
-```
+## Troubleshooting
 
-After changing the extension while pi is open, run:
+- Run `/voice status` to see whether recording is active.
+- Run `/voice config` to confirm the API key is detected.
+- Run `/voice key` again if the key was changed or expired.
+- On macOS, check microphone permission if recording immediately fails.
+- On Linux, make sure `pw-record` or `arecord` is installed and your microphone works in other apps.
 
-```text
-/reload
-```
+## Development
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for contribution guidelines.
 
 ## Roadmap
 
@@ -189,5 +161,4 @@ See [ROADMAP.md](ROADMAP.md) for planned user-visible work.
 ## Links
 
 - API key settings: https://console.volcengine.com/speech/new/setting/apikeys?projectName=default
-- ASR product page: https://www.volcengine.com/product/asr
-- WebSocket ASR docs: https://www.volcengine.com/docs/6561/1354869?lang=zh
+- VolcEngine ASR: https://www.volcengine.com/product/asr

package/extensions/voice-input.ts

@@ -61,6 +61,9 @@ type JsonObject = Record<string, unknown>;
 type VoiceInputConfigFile = {
   volcApiKey: string;
   polishModel: string;
+  duckSystemVolume: boolean;
+  duckSystemVolumeFactor: number;
+  duckSystemVolumeFadeMs: number;
 };
 
 type VoiceConfig = {
@@ -86,6 +89,17 @@ type VoiceConfig = {
   postprocessTimeoutMs: number;
   postprocessMaxTokens: number;
   postprocessContextChars: number;
+  duckSystemVolume: boolean;
+  duckSystemVolumeFactor: number;
+  duckSystemVolumeFadeMs: number;
+};
+
+type SystemVolumeDuckingState = {
+  provider: "macos" | "wpctl" | "pactl";
+  originalVolumePercent: number;
+  duckedVolumePercent: number;
+  factor: number;
+  fadeMs: number;
 };
 
 type RecordingState = {
@@ -95,6 +109,7 @@ type RecordingState = {
   startedAt: string;
   recorderTarget?: string;
   deviceName?: string;
+  systemVolume?: SystemVolumeDuckingState;
 };
 
 type DecodedFrame = {
@@ -124,6 +139,9 @@ function defaultConfigFile(): VoiceInputConfigFile {
   return {
     volcApiKey: "",
     polishModel: DEFAULT_POSTPROCESS_MODEL,
+    duckSystemVolume: true,
+    duckSystemVolumeFactor: 0.5,
+    duckSystemVolumeFadeMs: 300,
   };
 }
 
@@ -136,12 +154,29 @@ function stringField(source: JsonObject, name: string, fallback: string): string
   return typeof value === "string" ? value : fallback;
 }
 
+function booleanField(source: JsonObject, name: string, fallback: boolean): boolean {
+  const value = source[name];
+  return typeof value === "boolean" ? value : fallback;
+}
+
+function numberField(source: JsonObject, name: string, fallback: number): number {
+  const value = source[name];
+  return typeof value === "number" && Number.isFinite(value) ? value : fallback;
+}
+
+function clamp(value: number, min: number, max: number): number {
+  return Math.min(max, Math.max(min, value));
+}
+
 function normalizeConfigFile(input: unknown): VoiceInputConfigFile {
   const defaults = defaultConfigFile();
   const root = isObject(input) ? input : {};
   return {
     volcApiKey: stringField(root, "volcApiKey", defaults.volcApiKey).trim(),
     polishModel: stringField(root, "polishModel", defaults.polishModel).trim(),
+    duckSystemVolume: booleanField(root, "duckSystemVolume", defaults.duckSystemVolume),
+    duckSystemVolumeFactor: clamp(numberField(root, "duckSystemVolumeFactor", defaults.duckSystemVolumeFactor), 0, 1),
+    duckSystemVolumeFadeMs: Math.round(clamp(numberField(root, "duckSystemVolumeFadeMs", defaults.duckSystemVolumeFadeMs), 0, 3000)),
   };
 }
 
@@ -188,6 +223,9 @@ function getConfig(): VoiceConfig {
     postprocessTimeoutMs: 30000,
     postprocessMaxTokens: 2048,
     postprocessContextChars: 6000,
+    duckSystemVolume: fileConfig.duckSystemVolume,
+    duckSystemVolumeFactor: fileConfig.duckSystemVolumeFactor,
+    duckSystemVolumeFadeMs: fileConfig.duckSystemVolumeFadeMs,
   };
 }
 
@@ -218,6 +256,111 @@ function commandOutput(command: string, args: string[], timeoutMs = 1500): strin
   return (result.stdout || "").trim();
 }
 
+function runCommand(command: string, args: string[], timeoutMs = 1500): boolean {
+  return spawnSync(command, args, { stdio: "ignore", timeout: timeoutMs }).status === 0;
+}
+
+function formatPercent(value: number): string {
+  return Number(value.toFixed(2)).toString();
+}
+
+function readSystemOutputVolume(): Pick<SystemVolumeDuckingState, "provider" | "originalVolumePercent"> | null {
+  if (platform() === "darwin") {
+    if (!commandExists("osascript")) return null;
+    const output = commandOutput("osascript", ["-e", "output volume of (get volume settings)"]);
+    const volume = Number(output.trim());
+    return Number.isFinite(volume) ? { provider: "macos", originalVolumePercent: clamp(volume, 0, 100) } : null;
+  }
+
+  if (platform() !== "linux") return null;
+
+  if (commandExists("wpctl")) {
+    const output = commandOutput("wpctl", ["get-volume", "@DEFAULT_AUDIO_SINK@"]);
+    const match = output.match(/Volume:\s*([0-9.]+)/);
+    const volume = match ? Number(match[1]) * 100 : NaN;
+    if (Number.isFinite(volume)) return { provider: "wpctl", originalVolumePercent: Math.max(0, volume) };
+  }
+
+  if (commandExists("pactl")) {
+    const output = commandOutput("pactl", ["get-sink-volume", "@DEFAULT_SINK@"]);
+    const match = output.match(/([0-9]+(?:\.[0-9]+)?)%/);
+    const volume = match ? Number(match[1]) : NaN;
+    if (Number.isFinite(volume)) return { provider: "pactl", originalVolumePercent: Math.max(0, volume) };
+  }
+
+  return null;
+}
+
+function setSystemOutputVolume(state: Pick<SystemVolumeDuckingState, "provider">, volumePercent: number): boolean {
+  if (state.provider === "macos") {
+    return runCommand("osascript", ["-e", `set volume output volume ${Math.round(clamp(volumePercent, 0, 100))}`]);
+  }
+
+  const safePercent = Math.max(0, volumePercent);
+  if (state.provider === "wpctl") {
+    return runCommand("wpctl", ["set-volume", "@DEFAULT_AUDIO_SINK@", `${formatPercent(safePercent)}%`]);
+  }
+
+  return runCommand("pactl", ["set-sink-volume", "@DEFAULT_SINK@", `${formatPercent(safePercent)}%`]);
+}
+
+function easeInOut(t: number): number {
+  return 0.5 - Math.cos(Math.PI * clamp(t, 0, 1)) / 2;
+}
+
+async function fadeSystemOutputVolume(
+  state: Pick<SystemVolumeDuckingState, "provider">,
+  fromPercent: number,
+  toPercent: number,
+  fadeMs: number,
+): Promise<string | null> {
+  if (fadeMs <= 0 || Math.abs(fromPercent - toPercent) < 0.1) {
+    return setSystemOutputVolume(state, toPercent) ? null : "failed to set system output volume";
+  }
+
+  const steps = Math.max(2, Math.min(20, Math.round(fadeMs / 30)));
+  const intervalMs = fadeMs / steps;
+  for (let step = 1; step <= steps; step += 1) {
+    const eased = easeInOut(step / steps);
+    const volume = fromPercent + (toPercent - fromPercent) * eased;
+    if (!setSystemOutputVolume(state, volume)) return "failed to set system output volume";
+    if (step < steps) await sleep(intervalMs);
+  }
+  return null;
+}
+
+function createSystemVolumeDuckingState(config: VoiceConfig): { state?: SystemVolumeDuckingState; warning?: string } {
+  if (!config.duckSystemVolume || config.duckSystemVolumeFactor >= 1) return {};
+  const snapshot = readSystemOutputVolume();
+  if (!snapshot) return { warning: "system output volume ducking is enabled, but no supported volume control was found" };
+
+  return {
+    state: {
+      ...snapshot,
+      duckedVolumePercent: snapshot.originalVolumePercent * config.duckSystemVolumeFactor,
+      factor: config.duckSystemVolumeFactor,
+      fadeMs: config.duckSystemVolumeFadeMs,
+    },
+  };
+}
+
+async function applySystemVolumeDucking(state?: SystemVolumeDuckingState): Promise<string | null> {
+  if (!state) return null;
+  const warning = await fadeSystemOutputVolume(state, state.originalVolumePercent, state.duckedVolumePercent, state.fadeMs);
+  return warning ? `system output volume ducking failed: ${warning}` : null;
+}
+
+async function restoreSystemOutputVolume(state?: SystemVolumeDuckingState): Promise<string | null> {
+  if (!state) return null;
+  const warning = await fadeSystemOutputVolume(state, state.duckedVolumePercent, state.originalVolumePercent, state.fadeMs);
+  return warning ? `system output volume restore failed: ${warning}` : null;
+}
+
+function restoreSystemOutputVolumeNow(state?: SystemVolumeDuckingState): string | null {
+  if (!state) return null;
+  return setSystemOutputVolume(state, state.originalVolumePercent) ? null : "system output volume restore failed";
+}
+
 function selectRecorderExecutable(): string {
   if (platform() === "darwin") {
     if (commandExists("afrecord")) return "afrecord";
@@ -948,22 +1091,46 @@ function cleanPostprocessOutput(output: string): string {
   return text;
 }
 
+const EXPLICIT_ENGLISH_MULTILINE_PATTERN =
+  /\b(?:new\s*line|newline|line break|next line|new paragraph|paragraph break|carriage return|press enter|separate lines?|multi[- ]line|multiple lines)\b/i;
+const EXPLICIT_CHINESE_MULTILINE_PATTERN = /(?:换行|新的一行|另起一行|下一行|回车|分行|多行|逐行|每行|空一行|新段落|另起一段|分段)/u;
+const CJK_LIKE_PATTERN = /[\p{Script=Han}\p{Script=Hiragana}\p{Script=Katakana}\p{Script=Hangul}]/u;
+const CJK_PUNCTUATION_PATTERN = /[，。！？、；：（）《》「」『』“”‘’]/u;
+const CLOSING_PUNCTUATION_PATTERN = /^[,.;:!?，。！？、；：）)\]}》」』”’]/u;
+const OPENING_PUNCTUATION_PATTERN = /[（([{\[《「『“‘]$/u;
+
 function rawTextRequestsMultiline(rawText: string): boolean {
-  return (
-    /\r|\n/.test(rawText) ||
-    /\b(?:new\s*line|newline|line break|next line|new paragraph|paragraph break|carriage return|press enter|separate lines?|multi[- ]line|multiple lines)\b/i.test(rawText) ||
-    /(?:换行|新的一行|另起一行|下一行|回车|分行|多行|逐行|每行|空一行|新段落|另起一段|分段)/u.test(rawText)
-  );
+  // Existing newlines in raw ASR are not reliable user intent: providers can
+  // insert segment or sentence breaks on their own. Treat only spoken layout
+  // commands as intentional multiline input.
+  return EXPLICIT_ENGLISH_MULTILINE_PATTERN.test(rawText) || EXPLICIT_CHINESE_MULTILINE_PATTERN.test(rawText);
+}
+
+function lineBreakJoiner(left: string, right: string): string {
+  if (!left || !right) return "";
+  if (CLOSING_PUNCTUATION_PATTERN.test(right) || OPENING_PUNCTUATION_PATTERN.test(left)) return "";
+  if (CJK_PUNCTUATION_PATTERN.test(left) || CJK_PUNCTUATION_PATTERN.test(right)) return "";
+  if (CJK_LIKE_PATTERN.test(left) && CJK_LIKE_PATTERN.test(right)) return "";
+  return " ";
 }
 
 function collapseUnexpectedLineBreaks(text: string): string {
-  return text
-    .replace(/\r\n?/g, "\n")
-    .replace(/[ \t\f\v]*\n+[ \t\f\v]*/g, " ")
+  const normalized = text.replace(/\r\n?/g, "\n");
+  return normalized
+    .replace(/[ \t\f\v]*\n+[ \t\f\v]*/g, (match, offset: number, source: string) => {
+      const left = source.slice(0, offset).replace(/[ \t\f\v]+$/g, "").at(-1) ?? "";
+      const right = source.slice(offset + match.length).replace(/^[ \t\f\v]+/g, "").at(0) ?? "";
+      return lineBreakJoiner(left, right);
+    })
     .replace(/[ \t\f\v]{2,}/g, " ")
     .trim();
 }
 
+function normalizeRawTextForPostprocess(rawText: string): string {
+  const raw = rawText.trim();
+  return rawTextRequestsMultiline(raw) ? raw : collapseUnexpectedLineBreaks(raw);
+}
+
 function preserveExpectedPostprocessLayout(rawText: string, output: string): string {
   if (rawTextRequestsMultiline(rawText)) return output.trim();
   return collapseUnexpectedLineBreaks(output);
@@ -1050,7 +1217,7 @@ async function postprocessTranscript(ctx: ExtensionContext, rawText: string, con
       messages: [
         {
           role: "user",
-          content: buildPostprocessPrompt(ctx, raw, config),
+          content: buildPostprocessPrompt(ctx, normalizeRawTextForPostprocess(raw), config),
           timestamp: Date.now(),
         },
       ],
@@ -1092,9 +1259,10 @@ async function isRecording(config: VoiceConfig): Promise<boolean> {
 function cleanupStaleRecordingState(config: VoiceConfig): string[] {
   const state = readState(config);
   if (!state || pidAlive(state.pid)) return [];
+  const volumeWarning = restoreSystemOutputVolumeNow(state.systemVolume);
   const cleanupWarnings = cleanupRecordingArtifacts(state);
   clearState(config);
-  return cleanupWarnings;
+  return [volumeWarning, ...cleanupWarnings].filter((message): message is string => Boolean(message));
 }
 
 function requireInteractiveUi(ctx: ExtensionContext, action: string): boolean {
@@ -1128,6 +1296,7 @@ async function startRecording(ctx: ExtensionContext) {
     throw error;
   }
   const deviceName = recordingDeviceName(config, cmd[0]);
+  const volumeDucking = createSystemVolumeDuckingState(config);
 
   ctx.ui.setStatus("voice-input", ctx.ui.theme.fg("warning", "● starting mic"));
   let child: ReturnType<typeof spawn>;
@@ -1152,7 +1321,11 @@ async function startRecording(ctx: ExtensionContext) {
     startedAt: new Date().toISOString(),
     recorderTarget: config.recorderTarget || undefined,
     deviceName,
+    systemVolume: volumeDucking.state,
   });
+  if (volumeDucking.warning) ctx.ui.notify(`Voice input warning: ${volumeDucking.warning}`, "warning");
+  const duckingWarning = await applySystemVolumeDucking(volumeDucking.state);
+  if (duckingWarning) ctx.ui.notify(`Voice input warning: ${duckingWarning}`, "warning");
 
   ctx.ui.setStatus("voice-input", ctx.ui.theme.fg("accent", recordingStatusText(deviceName)));
 }
@@ -1169,7 +1342,9 @@ async function stopRecording(ctx: ExtensionContext, transcribe = true) {
 
   ctx.ui.setStatus("voice-input", ctx.ui.theme.fg("warning", transcribe ? "● transcribing" : "● stopping"));
   if (pidAlive(state.pid)) await stopProcessGroup(state.pid);
+  const volumeRestoreWarning = await restoreSystemOutputVolume(state.systemVolume);
   clearState(config);
+  if (volumeRestoreWarning) ctx.ui.notify(`Voice input warning: ${volumeRestoreWarning}`, "warning");
   if (config.finalizeDelayMs > 0) await sleep(config.finalizeDelayMs);
 
   if (!transcribe) {
@@ -1211,14 +1386,15 @@ async function stopRecording(ctx: ExtensionContext, transcribe = true) {
   if (!result.text.trim()) {
     ctx.ui.setStatus("voice-input", undefined);
     ctx.ui.notify(
-      `Transcription finished but no text was returned. audio=${(durationMs / 1000).toFixed(2)}s total=${result.timings.totalMs}ms`,
-      "warning",
+      `No speech detected. audio=${(durationMs / 1000).toFixed(2)}s total=${result.timings.totalMs}ms`,
+      "info",
     );
     return;
   }
 
   let finalText = result.text;
   let postprocessMs = 0;
+  let postprocessSucceeded = false;
   let postprocessUsed = false;
   if (config.postprocessEnabled) {
     ctx.ui.setStatus("voice-input", ctx.ui.theme.fg("warning", "● polishing"));
@@ -1226,7 +1402,7 @@ async function stopRecording(ctx: ExtensionContext, transcribe = true) {
     try {
       finalText = await postprocessTranscript(ctx, result.text, config);
       postprocessMs = Date.now() - postprocessStart;
-      postprocessUsed = finalText.trim() !== result.text.trim();
+      postprocessSucceeded = true;
     } catch (error) {
       postprocessMs = Date.now() - postprocessStart;
       ctx.ui.notify(
@@ -1236,6 +1412,9 @@ async function stopRecording(ctx: ExtensionContext, transcribe = true) {
     }
   }
 
+  finalText = preserveExpectedPostprocessLayout(result.text, finalText);
+  postprocessUsed = postprocessSucceeded && finalText.trim() !== result.text.trim();
+
   ctx.ui.setStatus("voice-input", undefined);
   insertIntoEditor(ctx, finalText);
   ctx.ui.notify(
@@ -1262,6 +1441,7 @@ function setupHelp(config = getConfig()): string {
     "- To create/update the JSON config file, run: /voice init",
     "- To save/update the key, run: /voice key",
     `- Polish: ${config.postprocessEnabled ? config.postprocessModel : "disabled"}`,
+    `- System volume ducking: ${config.duckSystemVolume ? `${Math.round(config.duckSystemVolumeFactor * 100)}% over ${config.duckSystemVolumeFadeMs}ms` : "disabled"}`,
     `- Get/create a VolcEngine Speech API key here: ${VOLC_API_KEY_URL}`,
     "- After saving the key, run: /voice config",
   ].join("\n");
@@ -1298,8 +1478,11 @@ function configSummary(config: VoiceConfig): string {
     `- config file: ${config.configPath}${existsSync(config.configPath) ? "" : " (missing; run /voice init to create it)"}`,
     `- volcApiKey: ${config.apiKey ? "set" : "missing"} (update with /voice key)`,
     `- polishModel: ${config.postprocessEnabled ? config.postprocessModel : "disabled"}`,
+    `- duckSystemVolume: ${config.duckSystemVolume ? "enabled" : "disabled"}`,
+    `- duckSystemVolumeFactor: ${config.duckSystemVolumeFactor}`,
+    `- duckSystemVolumeFadeMs: ${config.duckSystemVolumeFadeMs}`,
     `- current recording device: ${currentDevice}`,
-    "Config keys: volcApiKey, polishModel. Leave polishModel empty to disable polish.",
+    "Config keys: volcApiKey, polishModel, duckSystemVolume, duckSystemVolumeFactor, duckSystemVolumeFadeMs. Leave polishModel empty to disable polish.",
     `VolcEngine API key URL: ${VOLC_API_KEY_URL}`,
   ].join("\n");
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-voice-input",
-  "version": "0.2.11",
+  "version": "0.2.13",
   "description": "Press Ctrl+Shift+R to dictate prompts into Pi using VolcEngine ASR",
   "type": "module",
   "keywords": [