@p8n.ai/pi-listens 0.1.1 → 0.2.0

package/CHANGELOG.md

@@ -6,6 +6,29 @@ This project follows [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [0.2.0] - 2026-05-09
+
+### Added
+
+- `/init` command to create a global settings file (`~/.pi/pi-listens.json`) with sensible defaults.
+- `/voice-check` command (replaces `/voice-status`) with improved diagnostic output.
+
+### Changed
+
+- `/voice-on` now enables auto-speak by default for a full hands-free experience. Use `--no-speak` to opt out.
+- Rename `/voice-status` to `/voice-check` to better communicate its diagnostic purpose.
+
+### Removed
+
+- `/listen` slash command. Use `/voice-on` for the hands-free voice loop, or the `voice_input` agent tool for programmatic speech input.
+## [0.1.2] - 2026-05-09
+
+### Changed
+
+- Stream TTS audio directly to the local player so speech starts sooner.
+- Make `voice_output` non-blocking by default; pass `wait_for_playback: true` to wait.
+- Replace the `R` voice-panel shortcut with Space for easier listen/stop control.
+
 ## [0.1.1] - 2026-05-09
 
 ### Fixed
@@ -31,6 +54,8 @@ This project follows [Semantic Versioning](https://semver.org/).
 - Stop active audio capture/playback subprocesses when voice mode is closed or the Pi session shuts down.
 - Clean up generated audio files when spoken playback is interrupted.
 
-[Unreleased]: https://github.com/p8n-ai/pi-listens/compare/v0.1.1...HEAD
+[Unreleased]: https://github.com/p8n-ai/pi-listens/compare/v0.2.0...HEAD
 [0.1.0]: https://github.com/p8n-ai/pi-listens/releases/tag/v0.1.0
 [0.1.1]: https://github.com/p8n-ai/pi-listens/releases/tag/v0.1.1
+[0.1.2]: https://github.com/p8n-ai/pi-listens/releases/tag/v0.1.2
+[0.2.0]: https://github.com/p8n-ai/pi-listens/releases/tag/v0.2.0

package/README.md

@@ -7,14 +7,27 @@ Speech-first Pi package powered by [Sarvam AI](https://www.sarvam.ai/). It gives
 - voice-first clarification loops where the agent speaks a question, listens, transcribes, and continues
 - interactive TUI and headless/RPC usage through Pi extension tools and UI fallback
 
-## Install
+## Quick start
 
 ```bash
 pi install npm:@p8n.ai/pi-listens
-export SARVAM_API_KEY="your-sarvam-api-key"
 pi
 ```
 
+Inside Pi, run `/init` to create a global settings file with sensible defaults:
+
+```
+/init
+```
+
+Then open `~/.pi/pi-listens.json` and replace the `apiKey` placeholder with your [Sarvam AI API key](https://dashboard.sarvam.ai).
+
+Alternatively, set the key via environment variable:
+
+```bash
+export SARVAM_API_KEY="your-sarvam-api-key"
+```
+
 For local development from this checkout:
 
 ```bash
@@ -88,16 +101,15 @@ The extension also injects voice guidance into the system prompt:
 
 | Command | Purpose |
 | --- | --- |
-| `/listen [seconds]` | Stream one utterance over Sarvam WebSocket STT, wait for a sustained silence boundary, transcribe, and send it to Pi as a user message. |
+| `/init` | Create a global settings file at `~/.pi/pi-listens.json` with sensible defaults. Use `--overwrite` to replace an existing file. |
 | `/speak <text>` | Speak text with Sarvam TTS. |
-| `/voice-on [--speak] [--manual] [--no-listen] [seconds]` | Open the hands-free TUI panel. By default it listens now and auto-listens again after each agent response. `--speak` reads short assistant replies aloud. `--manual` leaves the panel active but only listens when you press R. |
-| `/voice-on --no-speak` | Open the panel without auto-reading assistant replies. |
-| `/voice-status` | Show setup and voice-mode status. |
+| `/voice-on [--no-speak] [--manual] [--no-listen] [seconds]` | Start the hands-free voice loop. Auto-speaks assistant replies and auto-listens by default. `--no-speak` disables reading replies aloud. `--manual` disables auto-listen (press Space to listen). |
+| `/voice-check` | Show setup diagnostics and voice-mode status. |
 
 Voice panel controls in interactive mode:
-- R: listen now; press again while listening to stop listening; if Pi is speaking, R stops playback before listening
-- A: auto-listen on/off (listen again after each assistant reply)
-- S: read aloud on/off (speak assistant replies)
+- Space: listen now; press again while listening to stop; if Pi is speaking, stops playback first
+- A: toggle auto-listen (listen again after each assistant reply)
+- S: toggle read-aloud (speak assistant replies)
 - Q: close the panel and stop any active listening or speaking
 - Click the orb: visual ripple feedback (terminals with mouse reporting)
 
@@ -143,7 +155,7 @@ Example config file:
   "ttsSampleRate": 24000,
   "ttsOutputCodec": "wav",
   "textFallback": true,
-  "autoSpeakAssistant": false,
+  "autoSpeakAssistant": true,
   "maxAutoSpeakChars": 320
 }
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@p8n.ai/pi-listens",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "Pi package for speech-first interaction using Sarvam AI speech-to-text and text-to-speech.",
   "author": "Ravindra Barthwal",
   "license": "MIT",

package/skills/pi-listens/SKILL.md

@@ -15,6 +15,13 @@ This Pi package provides voice tools backed by Sarvam AI.
 - `voice_transcribe_file`: transcribe an existing audio file.
 - `voice_setup_check`: diagnose API key, recorder, player, and voice settings.
 
+## Commands
+
+- `/init`: create a global settings file with defaults. User only needs to set their Sarvam API key.
+- `/speak <text>`: speak text with Sarvam TTS.
+- `/voice-on`: start hands-free voice loop (auto-speaks replies and auto-listens by default).
+- `/voice-check`: show setup diagnostics and voice-mode status.
+
 ## Usage rules
 
 1. When you need user input, clarification, or confirmation, use `voice_ask` instead of asking only in text.

package/src/audio.ts

@@ -1,7 +1,7 @@
 import { mkdir, rm } from "node:fs/promises";
 import { randomUUID } from "node:crypto";
 import { join } from "node:path";
-import { spawn } from "node:child_process";
+import { spawn, type StdioOptions } from "node:child_process";
 import { accessSync, constants } from "node:fs";
 import { once } from "node:events";
 import type { PiListensConfig } from "./config.js";
@@ -10,15 +10,17 @@ export interface AudioRuntime {
 	record(seconds?: number, signal?: AbortSignal): Promise<string>;
 	streamPcm(signal?: AbortSignal): AsyncIterable<Buffer>;
 	play(path: string, signal?: AbortSignal): Promise<void>;
+	playStream(stream: ReadableStream<Uint8Array>, signal?: AbortSignal): Promise<void>;
 	cleanup(path: string): Promise<void>;
 	stopPlayback(): void;
 	stopAll(): void;
-	describe(): { recorder: string; player: string };
+	describe(): { recorder: string; player: string; streamingPlayer: string };
 }
 
 export function createAudioRuntime(config: PiListensConfig): AudioRuntime {
 	const recorder = config.recordCommand ? "custom" : detectRecorder();
 	const player = config.playCommand ? "custom" : detectPlayer();
+	const streamingPlayer = detectStreamingPlayer();
 
 	return {
 		async record(seconds = config.recordSeconds, signal?: AbortSignal): Promise<string> {
@@ -68,6 +70,16 @@ export function createAudioRuntime(config: PiListensConfig): AudioRuntime {
 			await run(command.command, command.args, signal, { kind: "play" });
 		},
 
+		async playStream(stream: ReadableStream<Uint8Array>, signal?: AbortSignal): Promise<void> {
+			if (!streamingPlayer) {
+				throw new Error(
+					"No streaming audio player found. Install ffplay or sox (`play`) for low-latency TTS playback, or use file playback fallback.",
+				);
+			}
+			const command = streamingPlayerCommand(streamingPlayer, config.ttsOutputCodec, config.ttsSampleRate);
+			await pipeStreamToCommand(stream, command.command, command.args, signal);
+		},
+
 		async cleanup(path: string): Promise<void> {
 			if (!config.deleteAudio) return;
 			await rm(path, { force: true }).catch(() => undefined);
@@ -82,7 +94,7 @@ export function createAudioRuntime(config: PiListensConfig): AudioRuntime {
 		},
 
 		describe() {
-			return { recorder: recorder ?? "missing", player: player ?? "missing" };
+			return { recorder: recorder ?? "missing", player: player ?? "missing", streamingPlayer: streamingPlayer ?? "missing" };
 		},
 	};
 }
@@ -205,6 +217,13 @@ function detectPlayer(): string | null {
 	return null;
 }
 
+function detectStreamingPlayer(): string | null {
+	if (isCommandAvailable("ffplay")) return "ffplay";
+	if (isCommandAvailable("play")) return "play";
+	if (isCommandAvailable("aplay")) return "aplay";
+	return null;
+}
+
 function isCommandAvailable(command: string): boolean {
 	const paths = (process.env.PATH ?? "").split(":").filter(Boolean);
 	for (const dir of paths) {
@@ -303,6 +322,76 @@ async function* streamCommandOutput(command: string, args: string[], signal?: Ab
 	}
 }
 
+async function pipeStreamToCommand(stream: ReadableStream<Uint8Array>, command: string, args: string[], signal?: AbortSignal): Promise<void> {
+	if (signal?.aborted) throw new Error("Cancelled");
+	const child = spawnManaged(command, args, "play", ["pipe", "pipe", "pipe"]);
+	let stderr = "";
+	let stdout = "";
+	let exitCode: number | null = null;
+	let exitSignal: NodeJS.Signals | null = null;
+	let spawnError: Error | undefined;
+
+	const stop = () => terminateChild(child);
+	signal?.addEventListener("abort", stop, { once: true });
+	child.stdout?.on("data", (chunk) => { stdout += chunk.toString(); });
+	child.stderr?.on("data", (chunk) => { stderr += chunk.toString(); });
+	child.on("error", (err) => { spawnError = err; });
+	child.on("close", (code, termSignal) => { exitCode = code; exitSignal = termSignal; });
+
+	try {
+		if (!child.stdin) throw new Error(`${command} did not provide stdin for streaming audio playback`);
+		const stdin = child.stdin;
+		const reader = stream.getReader();
+		try {
+			while (true) {
+				if (signal?.aborted) throw new Error("Cancelled");
+				if (spawnError) throw spawnError;
+				const { done, value } = await reader.read();
+				if (done) break;
+				if (!value?.byteLength) continue;
+				if (!stdin.write(Buffer.from(value))) await once(stdin, "drain");
+			}
+		} finally {
+			reader.releaseLock();
+		}
+		stdin.end();
+		if (exitCode === null && !spawnError) await once(child, "close");
+		if (signal?.aborted) throw new Error("Cancelled");
+		if (spawnError) throw spawnError;
+		if (exitCode !== 0) {
+			const output = [stderr.trim(), stdout.trim()].filter(Boolean).join("\n");
+			throw new Error(`${command} failed${exitSignal ? ` (${exitSignal})` : ""}${exitCode === null ? "" : ` with exit code ${exitCode}`}${output ? `: ${output}` : ""}`);
+		}
+	} finally {
+		signal?.removeEventListener("abort", stop);
+		if (!child.killed && exitCode === null) stop();
+	}
+}
+
+function streamingPlayerCommand(player: string, codec: PiListensConfig["ttsOutputCodec"], sampleRate: number): CommandSpec {
+	if (player === "ffplay") {
+		const args = ["-nodisp", "-autoexit", "-loglevel", "error"];
+		if (codec === "linear16") args.push("-f", "s16le", "-ar", String(sampleRate), "-ac", "1");
+		if (codec === "mulaw") args.push("-f", "mulaw", "-ar", String(sampleRate), "-ac", "1");
+		if (codec === "alaw") args.push("-f", "alaw", "-ar", String(sampleRate), "-ac", "1");
+		args.push("-i", "pipe:0");
+		return { command: "ffplay", args };
+	}
+	if (player === "play") {
+		if (codec === "linear16") return { command: "play", args: ["-q", "-r", String(sampleRate), "-c", "1", "-b", "16", "-e", "signed-integer", "-t", "raw", "-"] };
+		if (codec === "mulaw" || codec === "alaw") return { command: "play", args: ["-q", "-r", String(sampleRate), "-c", "1", "-t", codec, "-"] };
+		return { command: "play", args: ["-q", "-t", soxTypeForCodec(codec), "-"] };
+	}
+	if (player === "aplay" && codec === "wav") return { command: "aplay", args: ["-q", "-"] };
+	throw new Error(`Unsupported streaming player ${player} for codec ${codec}`);
+}
+
+function soxTypeForCodec(codec: PiListensConfig["ttsOutputCodec"]): string {
+	if (codec === "aac") return "adts";
+	if (codec === "linear16") return "raw";
+	return codec;
+}
+
 type AudioProcessKind = "record" | "play" | "other";
 
 type ManagedChild = ReturnType<typeof spawn>;
@@ -318,10 +407,10 @@ export function stopActiveAudioProcesses(options: { kind?: AudioProcessKind; for
 	}
 }
 
-function spawnManaged(command: string, args: string[], kind: AudioProcessKind): ManagedChild {
+function spawnManaged(command: string, args: string[], kind: AudioProcessKind, stdio: StdioOptions = ["ignore", "pipe", "pipe"]): ManagedChild {
 	installProcessExitCleanup();
 	const child = spawn(command, args, {
-		stdio: ["ignore", "pipe", "pipe"],
+		stdio,
 		detached: process.platform !== "win32",
 	});
 	activeChildren.add(child);

package/src/commands.ts

@@ -1,9 +1,11 @@
-import { mkdir } from "node:fs/promises";
+import { existsSync, readFileSync } from "node:fs";
+import { mkdir, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
 import { join } from "node:path";
 import type { ExtensionAPI, ExtensionCommandContext, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import type { VoiceToolServices } from "./tools.js";
 import { conciseTranscript, prepareSpokenText } from "./text.js";
-import { audioExtensionForCodec } from "./config.js";
+import { audioExtensionForCodec, maskSecret } from "./config.js";
 import { applyVoiceChrome, installVoiceUi, uninstallVoiceUi } from "./voice-ui.js";
 
 export type VoiceLoopStatus = "idle" | "listening" | "transcribing" | "agent" | "speaking" | "error";
@@ -26,10 +28,10 @@ export interface VoiceModeState {
 }
 
 export function registerVoiceCommands(pi: ExtensionAPI, services: VoiceToolServices, state: VoiceModeState) {
-	pi.registerCommand("listen", {
-		description: "Record speech, transcribe with Sarvam AI, and send it to pi as a user message",
+	pi.registerCommand("init", {
+		description: "Create a global pi-listens settings file at ~/.pi/pi-listens.json with sensible defaults",
 		handler: async (args, ctx) => {
-			await listenAndSend(pi, services, ctx, parseSeconds(args));
+			await initSettings(services, ctx, args.includes("--overwrite"));
 		},
 	});
 
@@ -46,11 +48,10 @@ export function registerVoiceCommands(pi: ExtensionAPI, services: VoiceToolServi
 	});
 
 	pi.registerCommand("voice-on", {
-		description: "Enable hands-free voice loop. Use --speak to read short assistant replies aloud.",
+		description: "Enable hands-free voice loop with auto-speak and auto-listen. Use --no-speak to disable reading replies aloud, --manual to only listen on demand.",
 		handler: async (args, ctx) => {
 			state.enabled = true;
-			if (args.includes("--speak")) state.autoSpeakAssistant = true;
-			if (args.includes("--no-speak")) state.autoSpeakAssistant = false;
+			state.autoSpeakAssistant = !args.includes("--no-speak");
 			state.autoListen = !args.includes("--manual");
 			installVoiceUi(ctx, state, createVoiceUiCallbacks(pi, services, state, ctx));
 			applyVoiceChrome(ctx, state);
@@ -60,29 +61,97 @@ export function registerVoiceCommands(pi: ExtensionAPI, services: VoiceToolServi
 	});
 
 
-	pi.registerCommand("voice-status", {
-		description: "Show pi-listens Sarvam AI, recorder, player, and voice-mode status",
+	pi.registerCommand("voice-check", {
+		description: "Check pi-listens setup: Sarvam AI key, recorder, player, and voice-mode status",
 		handler: async (_args, ctx) => {
 			const config = services.getConfig();
 			const audio = services.getAudio().describe();
+			const ready = Boolean(config.apiKey) && audio.recorder !== "missing" && audio.player !== "missing";
 			ctx.ui.notify(
 				[
-					`Voice mode: ${state.enabled ? "on" : "off"}`,
-					`Auto-speak assistant: ${state.autoSpeakAssistant ? "on" : "off"}`,
-					`Auto-listen: ${state.autoListen ? "on" : "off"}`,
-					`Status: ${state.status}`,
-					`Sarvam API key: ${config.apiKey ? "set" : "missing"}`,
+					ready ? "✓ pi-listens is ready." : "⚠ pi-listens needs attention.",
+					"",
+					`Sarvam API key: ${maskSecret(config.apiKey)}`,
 					`Recorder: ${audio.recorder}`,
 					`Player: ${audio.player}`,
+					`Streaming player: ${audio.streamingPlayer}`,
 					`STT: ${config.sttModel} (${config.translateInputToEnglish ? "translate→English" : config.sttMode}, ${config.sttLanguageCode})`,
 					`TTS: ${config.ttsModel} (${config.ttsLanguageCode}, speaker ${config.ttsSpeaker})`,
+					"",
+					`Voice mode: ${state.enabled ? "on" : "off"}`,
+					`Auto-speak: ${state.autoSpeakAssistant ? "on" : "off"}`,
+					`Auto-listen: ${state.autoListen ? "on" : "off"}`,
 				].join("\n"),
-				config.apiKey && audio.recorder !== "missing" && audio.player !== "missing" ? "info" : "warning",
+				ready ? "info" : "warning",
 			);
 		},
 	});
 }
 
+const INIT_SETTINGS_TEMPLATE = {
+	apiKey: "paste-your-sarvam-api-key-here",
+	sttModel: "saaras:v3",
+	sttMode: "transcribe",
+	sttLanguageCode: "unknown",
+	translateInputToEnglish: true,
+	ttsModel: "bulbul:v3",
+	ttsLanguageCode: "en-IN",
+	ttsSpeaker: "shubh",
+	recordSeconds: 300,
+	recordSampleRate: 16000,
+	streamChunkMs: 250,
+	streamMaxSeconds: 300,
+	silenceStartSeconds: 0.2,
+	silenceStopSeconds: 3.5,
+	silenceThreshold: "1%",
+	ttsSampleRate: 24000,
+	ttsOutputCodec: "wav",
+	textFallback: true,
+	autoSpeakAssistant: true,
+	maxAutoSpeakChars: 320,
+};
+
+async function initSettings(services: VoiceToolServices, ctx: ExtensionCommandContext, overwrite: boolean) {
+	const dir = join(homedir(), ".pi");
+	const filePath = join(dir, "pi-listens.json");
+
+	if (existsSync(filePath) && !overwrite) {
+		const existing = readFileSync(filePath, "utf8");
+		let parsed: Record<string, unknown> = {};
+		try { parsed = JSON.parse(existing) as Record<string, unknown>; } catch { /* ignore */ }
+		const hasKey = typeof parsed.apiKey === "string" && parsed.apiKey !== "paste-your-sarvam-api-key-here" && parsed.apiKey.length > 0;
+		ctx.ui.notify(
+			[
+				`Settings file already exists: ${filePath}`,
+				hasKey ? "Sarvam API key: set" : "Sarvam API key: not yet configured",
+				"",
+				"Use /init --overwrite to replace it with fresh defaults.",
+			].join("\n"),
+			"info",
+		);
+		return;
+	}
+
+	await mkdir(dir, { recursive: true });
+	await writeFile(filePath, `${JSON.stringify(INIT_SETTINGS_TEMPLATE, null, 2)}\n`, "utf8");
+
+	const audio = services.getAudio().describe();
+	ctx.ui.notify(
+		[
+			`✓ Created settings file: ${filePath}`,
+			"",
+			"Next step: open the file and replace the apiKey value with your Sarvam AI API key.",
+			"Get a key at: https://dashboard.sarvam.ai",
+			"",
+			`Recorder: ${audio.recorder}`,
+			`Player: ${audio.player}`,
+			audio.recorder === "missing" || audio.player === "missing"
+				? "⚠ Install SoX (rec/play) or ffmpeg for microphone and audio playback."
+				: "✓ Audio recorder and player detected.",
+		].join("\n"),
+		"info",
+	);
+}
 export async function maybeContinueVoiceLoop(pi: ExtensionAPI, services: VoiceToolServices, state: VoiceModeState, ctx: ExtensionContext) {
 	if (!state.enabled || state.isListening) return;
 	if (state.autoSpeakAssistant && state.lastAssistantText) {
@@ -177,10 +246,8 @@ async function listenAndSend(
 }
 
 async function speakText(services: VoiceToolServices, text: string, signal?: AbortSignal, state?: VoiceModeState, ctx?: ExtensionContext) {
-	const config = services.getConfig();
 	const speakAbortController = state ? new AbortController() : undefined;
 	const speakSignal = combineSignals(signal, speakAbortController?.signal);
-	let path: string | undefined;
 
 	if (state) {
 		state.speakAbortController?.abort();
@@ -190,14 +257,9 @@ async function speakText(services: VoiceToolServices, text: string, signal?: Abo
 	}
 
 	try {
-		await mkdir(config.audioDir, { recursive: true });
-		path = join(config.audioDir, `pi-listens-command-${Date.now()}.${audioExtensionForCodec(config.ttsOutputCodec)}`);
-		const result = await services.getSpeech().synthesizeToFile(text, path, speakSignal.signal);
-		path = result.path;
-		await services.getAudio().play(result.path, speakSignal.signal);
+		await playSpeechBest(services, text, speakSignal.signal);
 	} finally {
 		speakSignal.cleanup();
-		if (path) await services.getAudio().cleanup(path);
 		if (state && state.speakAbortController === speakAbortController) state.speakAbortController = undefined;
 		if (state && state.status === "speaking") {
 			state.status = "idle";
@@ -206,6 +268,25 @@ async function speakText(services: VoiceToolServices, text: string, signal?: Abo
 	}
 }
 
+async function playSpeechBest(services: VoiceToolServices, text: string, signal?: AbortSignal) {
+	const audio = services.getAudio();
+	if (audio.describe().streamingPlayer !== "missing") {
+		const result = await services.getSpeech().synthesizeStream(text, signal);
+		await audio.playStream(result.stream, signal);
+		return;
+	}
+
+	const config = services.getConfig();
+	await mkdir(config.audioDir, { recursive: true });
+	const path = join(config.audioDir, `pi-listens-command-${Date.now()}.${audioExtensionForCodec(config.ttsOutputCodec)}`);
+	try {
+		const result = await services.getSpeech().synthesizeToFile(text, path, signal);
+		await audio.play(result.path, signal);
+	} finally {
+		await audio.cleanup(path);
+	}
+}
+
 function parseSeconds(args: string): number | undefined {
 	const match = args.match(/(?:^|\s)(\d{1,4})(?:\s|$)/);
 	if (!match) return undefined;

package/src/index.ts

@@ -52,7 +52,7 @@ export default function piListensExtension(pi: ExtensionAPI) {
 					`Sarvam API key: ${maskSecret(config.apiKey)}`,
 					`Recorder: ${audioInfo.recorder}`,
 					`Player: ${audioInfo.player}`,
-					"Run /voice-status or call voice_setup_check for details.",
+					"Run /init to create a settings file, or /voice-check for details.",
 				].join("\n"),
 				"warning",
 			);

package/src/sarvam.ts

@@ -15,6 +15,10 @@ export interface SynthesisResult {
 	bytes: number;
 }
 
+export interface SynthesisStreamResult {
+	stream: ReadableStream<Uint8Array>;
+}
+
 type StreamingData = {
 	transcript?: string;
 	request_id?: string;
@@ -127,6 +131,28 @@ export class SarvamSpeechClient {
 		return { path, bytes: buffer.byteLength };
 	}
 
+	async synthesizeStream(text: string, signal?: AbortSignal): Promise<SynthesisStreamResult> {
+		const config = this.getConfig();
+		const client = this.getClient(config);
+		const response = await client.textToSpeech.convertStream(
+			{
+				text,
+				target_language_code: config.ttsLanguageCode as never,
+				speaker: config.ttsSpeaker as never,
+				model: config.ttsModel as never,
+				pace: config.ttsPace,
+				temperature: config.ttsTemperature,
+				speech_sample_rate: config.ttsSampleRate as never,
+				enable_preprocessing: true,
+				output_audio_codec: config.ttsOutputCodec as never,
+			},
+			{ abortSignal: signal },
+		);
+		const stream = response.stream();
+		if (!stream) throw new Error("Sarvam TTS response did not include a readable audio stream");
+		return { stream };
+	}
+
 	private async withStreamingSocket(
 		signal: AbortSignal | undefined,
 		mode: SttMode | undefined,

package/src/tools.ts

@@ -17,7 +17,7 @@ export interface VoiceToolServices {
 
 const VoiceOutputParams = Type.Object({
 	text: Type.String({ description: "Short text to speak to the user. Keep it concise; do not speak code blocks or long logs." }),
-	wait_for_playback: Type.Optional(Type.Boolean({ description: "Wait until audio playback completes before returning. Default true." })),
+	wait_for_playback: Type.Optional(Type.Boolean({ description: "Wait until audio playback completes before returning. Default false." })),
 });
 
 const VoiceInputParams = Type.Object({
@@ -54,21 +54,20 @@ export function registerVoiceTools(pi: ExtensionAPI, services: VoiceToolServices
 		],
 		parameters: VoiceOutputParams,
 		async execute(_toolCallId, params: VoiceOutputInput, signal, onUpdate) {
-			onUpdate?.({ content: [{ type: "text", text: "Synthesizing speech with Sarvam AI…" }], details: {} });
-			const result = await speak(params.text, services, signal);
-			const playback = services.getAudio().play(result.path, signal).finally(() => services.getAudio().cleanup(result.path));
-			if (params.wait_for_playback === false) {
+			onUpdate?.({ content: [{ type: "text", text: "Starting streamed speech with Sarvam AI…" }], details: {} });
+			const playback = playSpeechBest(params.text, services, signal);
+			if (params.wait_for_playback !== true) {
 				void playback.catch(() => undefined);
 				return {
 					content: [{ type: "text", text: `Started speaking to user: ${params.text}` }],
-					details: { ...result, played: "started", text: params.text },
+					details: { played: "started", text: params.text },
 				};
 			}
 			onUpdate?.({ content: [{ type: "text", text: "Playing audio…" }], details: {} });
-			await playback;
+			const details = await playback;
 			return {
 				content: [{ type: "text", text: `Spoke to user: ${params.text}` }],
-				details: { ...result, played: true, text: params.text },
+				details: { ...details, played: true, text: params.text },
 			};
 		},
 		renderCall(args: VoiceOutputInput, theme) {
@@ -117,12 +116,7 @@ export function registerVoiceTools(pi: ExtensionAPI, services: VoiceToolServices
 		parameters: VoiceAskParams,
 		async execute(_toolCallId, params: VoiceAskInput, signal, onUpdate, ctx) {
 			onUpdate?.({ content: [{ type: "text", text: "Speaking question…" }], details: {} });
-			const spoken = await speak(params.question, services, signal);
-			try {
-				await services.getAudio().play(spoken.path, signal);
-			} finally {
-				await services.getAudio().cleanup(spoken.path);
-			}
+			await playSpeechBest(params.question, services, signal);
 			const answer = await listenAndMaybeFallback(
 				params,
 				services,
@@ -173,6 +167,7 @@ export function registerVoiceTools(pi: ExtensionAPI, services: VoiceToolServices
 							`Sarvam API key: ${config.apiKey ? "set" : "missing"}`,
 							`Recorder: ${audio.recorder}`,
 							`Player: ${audio.player}`,
+							`Streaming player: ${audio.streamingPlayer}`,
 							`STT: ${config.sttModel} (${config.translateInputToEnglish ? "translate→English" : config.sttMode}, ${config.sttLanguageCode})`,
 							`TTS: ${config.ttsModel} (${config.ttsLanguageCode}, speaker ${config.ttsSpeaker})`,
 						].join("\n"),
@@ -184,7 +179,24 @@ export function registerVoiceTools(pi: ExtensionAPI, services: VoiceToolServices
 	});
 }
 
-async function speak(text: string, services: VoiceToolServices, signal?: AbortSignal) {
+async function playSpeechBest(text: string, services: VoiceToolServices, signal?: AbortSignal): Promise<Record<string, unknown>> {
+	const audio = services.getAudio();
+	if (audio.describe().streamingPlayer !== "missing") {
+		const result = await services.getSpeech().synthesizeStream(text, signal);
+		await audio.playStream(result.stream, signal);
+		return { playback: "stream" };
+	}
+
+	const result = await speakToFile(text, services, signal);
+	try {
+		await audio.play(result.path, signal);
+		return { ...result, playback: "file" };
+	} finally {
+		await audio.cleanup(result.path);
+	}
+}
+
+async function speakToFile(text: string, services: VoiceToolServices, signal?: AbortSignal) {
 	const config = services.getConfig();
 	await mkdir(config.audioDir, { recursive: true });
 	const path = join(config.audioDir, `pi-listens-output-${Date.now()}-${randomUUID()}.${audioExtensionForCodec(config.ttsOutputCodec)}`);

package/src/voice-ui.ts

@@ -88,7 +88,7 @@ class VoiceLoopEditor extends CustomEditor {
 			if (mouse.pressed && mouse.button === 0) this.triggerMouseOrbClick(mouse);
 			return;
 		}
-		if (data.toLowerCase() === "r") {
+		if (data === " ") {
 			this.triggerOrbClick(1);
 			this.callbacks.startListening();
 			return;
@@ -309,7 +309,7 @@ function frameIntervalForStatus(status: VoiceModeState["status"]): number {
 function controlRail(state: VoiceModeState, palette: OrbPalette, width: number): string[] {
 	const listenLabel = state.isListening ? "stop" : "listen";
 	const pills = [
-		controlPill("R", listenLabel, state.isListening ? "active" : "primary", palette),
+		controlPill("Space", listenLabel, state.isListening ? "active" : "primary", palette),
 		controlPill("A", state.autoListen ? "auto-listen on" : "auto-listen off", state.autoListen ? "active" : "muted", palette),
 		controlPill("S", state.autoSpeakAssistant ? "read aloud on" : "read aloud off", state.autoSpeakAssistant ? "active" : "muted", palette),
 		controlPill("Q", "close", "danger", palette),