pi-voice-input 0.2.10 → 0.2.12

package/README.md

@@ -27,6 +27,7 @@ pi extension: extensions/index.ts → extensions/voice-input.ts
   │    ├─ Linux preferred: pw-record
   │    ├─ Linux fallback: arecord
   │    └─ macOS: afrecord, or ffmpeg/AVFoundation fallback
+  ├─ ducks system output volume while the microphone is listening
   ├─ 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
@@ -108,12 +109,17 @@ The config file is plain JSON and can be edited directly:
 ```json
 {
   "volcApiKey": "",
-  "polishModel": ""
+  "polishModel": "",
+  "duckSystemVolume": true,
+  "duckSystemVolumeFactor": 0.5,
+  "duckSystemVolumeFadeMs": 300
 }
 ```
 
 `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.
 
+`duckSystemVolume` is enabled by default. While recording, the extension lowers system output volume to `duckSystemVolumeFactor` of the original volume using a short ease-in/ease-out fade (`duckSystemVolumeFadeMs`), then restores the saved volume when recording stops or is cancelled. Linux uses `wpctl` or `pactl`; macOS uses `osascript`.
+
 Verify the effective non-secret config:
 
 ```text
@@ -151,6 +157,7 @@ Slash commands:
 - 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.
+- By default, system output volume is ducked to 50% of its previous level with a 300 ms ease-in/ease-out fade while the microphone is listening, then restored after recording stops.
 
 ## Development
 

package/extensions/voice-input.ts

@@ -40,7 +40,9 @@ Rules:
 - Preserve the user's information faithfully. Do not over-summarize or compress. Do not delete constraints, examples, numbers, filenames, errors, multiple requests, ordering, or emphasis.
 - Correct obvious ASR mistakes, homophones, segmentation, and punctuation. Preserve code identifiers, commands, paths, URLs, model names, package names, and proper nouns.
 - If the user self-corrects, keep only the corrected intent and remove the false start, correction process, filler, and chatter. Do not lose any other substantive information.
-- Make the output complete relative to the raw speech, logically clear, and actionable. Split into items or steps when helpful, but do not drop raw-speech information or repeat existing draft text.
+- Make the output complete relative to the raw speech, logically clear, and actionable, but do not drop raw-speech information or repeat existing draft text.
+- Preserve the raw speech layout. If the raw speech is a single line, output a single line unless the user explicitly dictates line breaks or another multiline layout, for example by saying "new line" or "换行".
+- Do not introduce line breaks, bullets, numbered lists, tables, or code fences merely to improve style.
 - Do not invent requirements that the raw speech did not express. If uncertain, keep the original meaning and express it more clearly.
 - The output language must match the primary language of the raw speech, not the context language and not this English prompt. Do not translate just because the instructions are in English.`;
 
@@ -59,6 +61,9 @@ type JsonObject = Record<string, unknown>;
 type VoiceInputConfigFile = {
   volcApiKey: string;
   polishModel: string;
+  duckSystemVolume: boolean;
+  duckSystemVolumeFactor: number;
+  duckSystemVolumeFadeMs: number;
 };
 
 type VoiceConfig = {
@@ -84,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 = {
@@ -93,6 +109,7 @@ type RecordingState = {
   startedAt: string;
   recorderTarget?: string;
   deviceName?: string;
+  systemVolume?: SystemVolumeDuckingState;
 };
 
 type DecodedFrame = {
@@ -122,6 +139,9 @@ function defaultConfigFile(): VoiceInputConfigFile {
   return {
     volcApiKey: "",
     polishModel: DEFAULT_POSTPROCESS_MODEL,
+    duckSystemVolume: true,
+    duckSystemVolumeFactor: 0.5,
+    duckSystemVolumeFadeMs: 300,
   };
 }
 
@@ -134,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)),
   };
 }
 
@@ -186,6 +223,9 @@ function getConfig(): VoiceConfig {
     postprocessTimeoutMs: 30000,
     postprocessMaxTokens: 2048,
     postprocessContextChars: 6000,
+    duckSystemVolume: fileConfig.duckSystemVolume,
+    duckSystemVolumeFactor: fileConfig.duckSystemVolumeFactor,
+    duckSystemVolumeFadeMs: fileConfig.duckSystemVolumeFadeMs,
   };
 }
 
@@ -216,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";
@@ -924,7 +1069,18 @@ function resolvePostprocessModel(ctx: ExtensionContext, reference: string): Mode
 }
 
 function extractAssistantText(message: { content: unknown }): string {
-  return textFromContent(message.content).trim();
+  const content = message.content;
+  if (typeof content === "string") return content.trim();
+  if (!Array.isArray(content)) return "";
+  return content
+    .map((part) => {
+      if (!part || typeof part !== "object") return "";
+      const block = part as { type?: unknown; text?: unknown };
+      if (block.type === "text" && typeof block.text === "string") return block.text;
+      return "";
+    })
+    .join("")
+    .trim();
 }
 
 function cleanPostprocessOutput(output: string): string {
@@ -935,6 +1091,27 @@ function cleanPostprocessOutput(output: string): string {
   return text;
 }
 
+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)
+  );
+}
+
+function collapseUnexpectedLineBreaks(text: string): string {
+  return text
+    .replace(/\r\n?/g, "\n")
+    .replace(/[ \t\f\v]*\n+[ \t\f\v]*/g, " ")
+    .replace(/[ \t\f\v]{2,}/g, " ")
+    .trim();
+}
+
+function preserveExpectedPostprocessLayout(rawText: string, output: string): string {
+  if (rawTextRequestsMultiline(rawText)) return output.trim();
+  return collapseUnexpectedLineBreaks(output);
+}
+
 function removeEditorDraftEcho(editorText: string, output: string): string {
   const draft = editorText.trim();
   const text = output.trim();
@@ -981,6 +1158,7 @@ function buildPostprocessPrompt(ctx: ExtensionContext, rawText: string, config:
     "IMPORTANT: your output will be pasted verbatim at the current cursor position. It is not a replacement and not a rewrite of the whole editor draft.",
     "The current editor draft is context only. Do not rewrite, repeat, complete, delete, or replace existing draft text. Do not output the full sentence after insertion.",
     "The true cursor position is not marked in the draft shown here; the pi editor owns the actual insertion point. Do not guess the cursor and synthesize a full surrounding sentence.",
+    "Preserve layout: if the raw ASR text is one line, output one line unless the user explicitly dictated line breaks or another multiline layout.",
     "If the raw speech is an inline insertion, continuation, a few words, or a phrase, output only the newly spoken words or phrase.",
     "Example: draft is `Please make this function async and [cursor].`, raw speech is `add error handling`, correct output is `add error handling`, not `Please make this function async and add error handling.`.",
     "Example: draft is `This variable name is [cursor]unclear`, raw speech is `still`, correct output is `still`, not `This variable name is still unclear`.",
@@ -1038,7 +1216,9 @@ async function postprocessTranscript(ctx: ExtensionContext, rawText: string, con
   }
 
   const polished = cleanPostprocessOutput(extractAssistantText(response));
-  return polished ? removeEditorDraftEcho(getFullEditorText(ctx), polished) : rawText;
+  if (!polished) return rawText;
+  const insertion = removeEditorDraftEcho(getFullEditorText(ctx), polished);
+  return preserveExpectedPostprocessLayout(raw, insertion) || rawText;
 }
 
 function insertIntoEditor(ctx: ExtensionContext, text: string) {
@@ -1055,9 +1235,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 {
@@ -1091,6 +1272,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>;
@@ -1115,7 +1297,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)));
 }
@@ -1132,7 +1318,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) {
@@ -1174,8 +1362,8 @@ 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;
   }
@@ -1225,6 +1413,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");
@@ -1261,8 +1450,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.10",
+  "version": "0.2.12",
   "description": "Press Ctrl+Shift+R to dictate prompts into Pi using VolcEngine ASR",
   "type": "module",
   "keywords": [