klaudio 0.7.0 → 0.8.1

package/README.md

@@ -11,9 +11,10 @@ npx klaudio
 The interactive installer walks you through:
 
 1. **Choose scope** — install globally (`~/.claude`) or per-project (`.claude/`), or launch the **Music Player**
-2. **Pick a source** — use a built-in preset, scan your Steam & Epic Games library for sounds, or provide custom files
+2. **Pick a source** — use a built-in preset, OS system sounds, scan your Steam & Epic Games library, or provide custom files
 3. **Preview & assign** — listen to sounds and assign them to events (tab to switch between events)
-4. **Install** — writes Claude Code hooks to your `settings.json`
+4. **Toggle voice summary** — enable TTS to hear a spoken summary when tasks complete
+5. **Install** — writes Claude Code hooks to your `settings.json`
 
 ## Sound Sources
 
@@ -21,6 +22,10 @@ The interactive installer walks you through:
 
 Ready-made sound packs (Retro 8-bit, Minimal Zen, Sci-Fi Terminal, Victory Fanfare) that work out of the box.
 
+### System Sounds
+
+Use your OS built-in notification sounds (Windows Media, macOS system sounds, Linux sound themes).
+
 ### Game Sound Scanner
 
 Scans your local Steam and Epic Games libraries for audio files:
@@ -47,15 +52,25 @@ Play longer game tracks (90s–4min) as background music while you code:
 
 Requires previously extracted game audio (use "Scan local games" first).
 
+## Voice Summary (TTS)
+
+When enabled, klaudio speaks a short summary of what Claude did after playing the task-complete sound. Uses [Piper](https://github.com/rhasspy/piper) for fast, offline neural text-to-speech (auto-downloaded on first use, ~40MB total).
+
+- Toggle with `t` on the scope or confirm screen
+- Reads the first sentence of Claude's last message
+- Uses the `en_GB-alan-medium` voice (British male)
+- Hooks receive data via stdin from Claude Code — no extra setup needed
+
 ## Features
 
 - **Auto-preview** — sounds play automatically as you browse the list (toggle with `p`)
 - **Multi-game selection** — pick sounds from different games, tab between events
 - **Category filtering** — drill into voice, ambient, SFX, etc. when a game has enough variety
 - **Type-to-filter** — start typing to narrow down long lists
+- **Duration filter** — type `<10s`, `>5s`, `<=3s` etc. to filter by audio length
 - **10-second clamp** — long sounds are processed with ffmpeg: silence stripped, fade out baked in
 - **Background scanning** — game list updates live as directories are scanned
-- **Pre-loads existing config** — re-running the installer shows your current sound selections
+- **Re-apply current sounds** — re-running the installer shows your current selections with a quick re-apply option
 
 ## Events
 
@@ -74,7 +89,8 @@ npx klaudio --uninstall
 
 - Node.js 18+ (Claude Code already requires this)
 - [Claude Code](https://docs.anthropic.com/en/docs/claude-code) installed
-- For packed audio extraction: internet connection (vgmstream-cli is downloaded automatically)
+- For packed audio extraction: internet connection (vgmstream-cli downloaded automatically)
+- For voice summaries: internet connection on first use (Piper TTS downloaded automatically)
 - For best playback with fade effects: [ffmpeg/ffplay](https://ffmpeg.org/) on PATH (falls back to native players)
 
 > **Note:** Currently only tested on Windows. macOS and Linux support is planned but not yet verified.

package/bin/cli.js

@@ -1,6 +1,14 @@
 #!/usr/bin/env node
 
-import { run } from "../src/cli.js";
+// Subcommand: klaudio play <file> [--tts]
+if (process.argv[2] === "play") {
+  const { handlePlayCommand } = await import("../src/player.js");
+  await handlePlayCommand(process.argv.slice(3));
+  process.exit(0);
+}
+
+// Default: interactive installer UI
+const { run } = await import("../src/cli.js");
 
 run().catch((err) => {
   if (err.name === "ExitPromptError") {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "klaudio",
-  "version": "0.7.0",
+  "version": "0.8.1",
   "description": "Add sound effects to your coding sessions — play sounds when tasks complete, notifications arrive, and more",
   "type": "module",
   "bin": {

package/src/cli.js

@@ -39,8 +39,17 @@ const SelectInput = ({ items = [], isFocused = true, initialIndex = 0, indicator
     const prevValues = previousItems.current.map((i) => i.value);
     const curValues = items.map((i) => i.value);
     if (prevValues.length !== curValues.length || prevValues.some((v, i) => v !== curValues[i])) {
-      setScrollOffset(0);
-      setSelectedIndex(0);
+      // Try to keep the currently selected item highlighted
+      const prevSelected = previousItems.current[selectedIndex];
+      const newIdx = prevSelected ? items.findIndex((i) => i.value === prevSelected.value) : -1;
+      if (newIdx >= 0) {
+        setSelectedIndex(newIdx);
+        setScrollOffset(hasLimit ? Math.max(0, Math.min(newIdx, items.length - limit)) : 0);
+      } else {
+        // Selected item gone — reset to top
+        setScrollOffset(0);
+        setSelectedIndex(0);
+      }
     }
     previousItems.current = items;
   }, [items]);
@@ -115,7 +124,7 @@ const NavHint = ({ back = true, extra = "" }) =>
   );
 
 // ── Screen: Scope ───────────────────────────────────────────────
-const ScopeScreen = ({ onNext, onMusic }) => {
+const ScopeScreen = ({ onNext, onMusic, tts, onToggleTts }) => {
   const items = [
     { label: "Global — Claude Code + Copilot (all projects)", value: "global" },
     { label: "This project — Claude Code + Copilot (this project only)", value: "project" },
@@ -130,6 +139,8 @@ const ScopeScreen = ({ onNext, onMusic }) => {
       setSel((i) => Math.max(0, i - 1));
     } else if (input === "j" || key.downArrow) {
       setSel((i) => Math.min(items.length - 1, i + 1));
+    } else if (input === "t") {
+      onToggleTts();
     } else if (key.return) {
       const v = items[sel].value;
       if (v === "_music") onMusic();
@@ -148,27 +159,63 @@ const ScopeScreen = ({ onNext, onMusic }) => {
         ),
       )),
     ),
+    h(Box, { marginTop: 1, marginLeft: 4 },
+      h(Text, { color: tts ? "green" : "gray" },
+        tts ? "🗣 Voice summary: ON" : "🗣 Voice summary: OFF",
+      ),
+      h(Text, { dimColor: true }, "  (t to toggle)"),
+    ),
   );
 };
 
 // ── Screen: Preset ──────────────────────────────────────────────
-const PresetScreen = ({ onNext, onBack }) => {
-  useInput((_, key) => { if (key.escape) onBack(); });
-
+const PresetScreen = ({ existingSounds, onNext, onReapply, onBack }) => {
+  const hasExisting = existingSounds && Object.values(existingSounds).some(Boolean);
   const items = [
+    ...(hasExisting ? [{
+      label: "✓ Re-apply current sounds  — update config with current selections",
+      value: "_reapply",
+    }] : []),
     ...Object.entries(PRESETS).map(([id, p]) => ({
       label: `${p.icon} ${p.name}  — ${p.description}`,
       value: id,
     })),
+    // separator before these
     { label: "🔔 System sounds  — use built-in OS notification sounds", value: "_system" },
-    { label: "🕹️  Scan local games  — find sounds from your Steam & Epic Games library", value: "_scan" },
+    { label: "🕹️  Scan your games library  — find sounds from Steam & Epic Games", value: "_scan" },
     { label: "📁 Custom files  — provide your own sound files", value: "_custom" },
   ];
+  const GAP_AT = (hasExisting ? 1 : 0) + Object.keys(PRESETS).length; // separator before non-preset options
+  const [sel, setSel] = useState(0);
+
+  useInput((input, key) => {
+    if (key.escape) onBack();
+    else if (input === "k" || key.upArrow) setSel((i) => Math.max(0, i - 1));
+    else if (input === "j" || key.downArrow) setSel((i) => Math.min(items.length - 1, i + 1));
+    else if (key.return) {
+      if (items[sel].value === "_reapply") onReapply();
+      else onNext(items[sel].value);
+    }
+  });
 
   return h(Box, { flexDirection: "column" },
     h(Text, { bold: true }, "  Choose a sound preset:"),
-    h(Box, { marginLeft: 2 },
-      h(SelectInput, { indicatorComponent: Indicator, itemComponent: Item, items, onSelect: (item) => onNext(item.value) }),
+    hasExisting
+      ? h(Box, { flexDirection: "column", marginLeft: 4, marginBottom: 1 },
+          h(Text, { dimColor: true }, "Current sounds:"),
+          ...Object.entries(existingSounds).filter(([_, p]) => p).map(([eid, p]) =>
+            h(Text, { key: eid, color: "green", dimColor: true }, `  ✓ ${EVENTS[eid].name}: ${basename(p)}`),
+          ),
+        )
+      : null,
+    h(Box, { flexDirection: "column", marginLeft: 2 },
+      ...items.map((item, i) => h(React.Fragment, { key: item.value },
+        i === GAP_AT ? h(Text, { dimColor: true }, "\n  ...or pick your own") : null,
+        h(Box, null,
+          h(Indicator, { isSelected: i === sel }),
+          h(Item, { isSelected: i === sel, label: item.label }),
+        ),
+      )),
     ),
     h(NavHint, { back: true }),
   );
@@ -601,6 +648,16 @@ const GameSoundsScreen = ({ game, sounds, onSelectSound, onDone, onBack }) => {
     return () => clearInterval(interval);
   }, [playing]);
 
+  // Parse duration filter: "10s", "<10s", "< 10s", ">5s", "> 5s", "<=10s", ">=5s"
+  // (must be before early returns to satisfy React hook rules)
+  const durationFilter = useMemo(() => {
+    const m = filter.match(/^\s*(<|>|<=|>=)?\s*(\d+(?:\.\d+)?)\s*s\s*$/);
+    if (!m) return null;
+    const op = m[1] || "<=";
+    const val = parseFloat(m[2]);
+    return { op, val };
+  }, [filter]);
+
   const eventId = eventIds[currentEvent];
   const eventInfo = EVENTS[eventId];
   const stepLabel = `(${currentEvent + 1}/${eventIds.length})`;
@@ -759,15 +816,6 @@ const GameSoundsScreen = ({ game, sounds, onSelectSound, onDone, onBack }) => {
   // Phase 1: Browse and pick files (auto-preview plays on highlight)
   const filterLower = filter.toLowerCase();
 
-  // Parse duration filter: "10s", "<10s", "< 10s", ">5s", "> 5s", "<=10s", ">=5s"
-  const durationFilter = useMemo(() => {
-    const m = filter.match(/^\s*(<|>|<=|>=)?\s*(\d+(?:\.\d+)?)\s*s\s*$/);
-    if (!m) return null;
-    const op = m[1] || "<=";
-    const val = parseFloat(m[2]);
-    return { op, val };
-  }, [filter]);
-
   const allFileItems = categoryFiles.map((f) => {
     const dur = fileDurations[f.path];
     const durStr = dur != null ? ` (${dur}s${dur > MAX_PLAY_SECONDS ? `, preview ${MAX_PLAY_SECONDS}s` : ""})` : "";
@@ -1270,8 +1318,11 @@ const ExtractingScreen = ({ game, onDone, onBack }) => {
 };
 
 // ── Screen: Confirm ─────────────────────────────────────────────
-const ConfirmScreen = ({ scope, sounds, onConfirm, onBack }) => {
-  useInput((_, key) => { if (key.escape) onBack(); });
+const ConfirmScreen = ({ scope, sounds, tts, onToggleTts, onConfirm, onBack }) => {
+  useInput((input, key) => {
+    if (key.escape) onBack();
+    else if (input === "t") onToggleTts();
+  });
 
   const items = [
     { label: "✓  Yes, install!", value: "yes" },
@@ -1289,6 +1340,12 @@ const ConfirmScreen = ({ scope, sounds, onConfirm, onBack }) => {
           `${EVENTS[eid].name} → ${basename(path)}`
         )
       ),
+      h(Box, { marginLeft: 4, marginTop: 1 },
+        h(Text, { color: tts ? "green" : "gray" },
+          tts ? "🗣 Voice summary: ON" : "🗣 Voice summary: OFF",
+        ),
+        h(Text, { dimColor: true }, "  (t to toggle — reads a short summary when tasks complete)"),
+      ),
     ),
     h(Box, { marginTop: 1, marginLeft: 2 },
       h(SelectInput, { indicatorComponent: Indicator, itemComponent: Item, items, onSelect: (item) => {
@@ -1301,13 +1358,13 @@ const ConfirmScreen = ({ scope, sounds, onConfirm, onBack }) => {
 };
 
 // ── Screen: Installing ──────────────────────────────────────────
-const InstallingScreen = ({ scope, sounds, onDone }) => {
+const InstallingScreen = ({ scope, sounds, tts, onDone }) => {
   useEffect(() => {
     const validSounds = {};
     for (const [eventId, path] of Object.entries(sounds)) {
       if (path) validSounds[eventId] = path;
     }
-    install({ scope, sounds: validSounds }).then(onDone).catch((err) => {
+    install({ scope, sounds: validSounds, tts }).then(onDone).catch((err) => {
       onDone({ error: err.message });
     });
   }, []);
@@ -1411,6 +1468,7 @@ const InstallApp = () => {
   const [sounds, setSounds] = useState({});
   const [selectedGame, setSelectedGame] = useState(null);
   const [installResult, setInstallResult] = useState(null);
+  const [tts, setTts] = useState(true);
   const [musicFiles, setMusicFiles] = useState([]);
   const [musicGameName, setMusicGameName] = useState(null);
   const [musicShuffle, setMusicShuffle] = useState(false);
@@ -1424,6 +1482,8 @@ const InstallApp = () => {
     switch (screen) {
       case SCREEN.SCOPE:
         return h(ScopeScreen, {
+          tts,
+          onToggleTts: () => setTts((v) => !v),
           onNext: (s) => {
             setScope(s);
             getExistingSounds(s).then((existing) => {
@@ -1436,6 +1496,8 @@ const InstallApp = () => {
 
       case SCREEN.PRESET:
         return h(PresetScreen, {
+          existingSounds: sounds,
+          onReapply: () => setScreen(SCREEN.CONFIRM),
           onNext: (id) => {
             if (id === "_music") {
               setScreen(SCREEN.MUSIC_MODE);
@@ -1534,6 +1596,8 @@ const InstallApp = () => {
         return h(ConfirmScreen, {
           scope,
           sounds,
+          tts,
+          onToggleTts: () => setTts((v) => !v),
           onConfirm: () => setScreen(SCREEN.INSTALLING),
           onBack: () => {
             if (selectedGame) setScreen(SCREEN.GAME_SOUNDS);
@@ -1545,6 +1609,7 @@ const InstallApp = () => {
         return h(InstallingScreen, {
           scope,
           sounds,
+          tts,
           onDone: (result) => {
             setInstallResult(result);
             setScreen(SCREEN.DONE);

package/src/installer.js

@@ -20,8 +20,9 @@ function getTargetDir(scope) {
  * @param {object} options
  * @param {string} options.scope - "global" or "project"
  * @param {Record<string, string>} options.sounds - Map of event ID -> source sound file path
+ * @param {boolean} [options.tts] - Enable TTS voice summary on task complete
  */
-export async function install({ scope, sounds }) {
+export async function install({ scope, sounds, tts = false }) {
   const claudeDir = getTargetDir(scope);
   const soundsDir = join(claudeDir, "sounds");
   const settingsFile = join(claudeDir, "settings.json");
@@ -60,7 +61,9 @@ export async function install({ scope, sounds }) {
     if (!event) continue;
 
     const hookEvent = event.hookEvent;
-    const playCommand = getHookPlayCommand(soundPath);
+    // Enable TTS only for the "stop" event (task complete)
+    const useTts = tts && eventId === "stop";
+    const playCommand = getHookPlayCommand(soundPath, { tts: useTts });
 
     // Check if there's already a klaudio hook for this event
     if (!settings.hooks[hookEvent]) {

package/src/player.js

@@ -363,16 +363,52 @@ export async function processSound(filePath) {
 }
 
 /**
- * Generate the shell command string for use in Claude Code hooks.
+ * Handle the "play" subcommand: play a sound file and optionally speak a TTS summary.
+ * Reads hook JSON from stdin to get last_assistant_message for TTS.
  */
-export function getHookPlayCommand(soundFilePath) {
-  const normalized = soundFilePath.replace(/\\/g, "/");
-  const ext = extname(normalized).toLowerCase();
-  const needsFfplay = !MEDIA_PLAYER_FORMATS.has(ext);
+export async function handlePlayCommand(args) {
+  const soundFile = args.find((a) => !a.startsWith("-"));
+  const tts = args.includes("--tts");
 
-  if (needsFfplay) {
-    return `if command -v ffplay &>/dev/null; then ffplay -nodisp -autoexit -loglevel quiet "${normalized}" & elif [[ "$OSTYPE" == "darwin"* ]]; then afplay "${normalized}" & elif [[ "$OSTYPE" == "msys"* ]] || [[ "$OSTYPE" == "cygwin"* ]]; then powershell.exe -NoProfile -Command "Add-Type -AssemblyName PresentationCore; \\$p = New-Object System.Windows.Media.MediaPlayer; \\$p.Open([System.Uri]::new('$(cygpath -w "${normalized}")')); Start-Sleep -Milliseconds 200; \\$p.Play(); Start-Sleep -Seconds 2" & else aplay "${normalized}" & fi`;
+  // Read stdin (hook JSON) non-blocking
+  let hookData = {};
+  try {
+    const chunks = [];
+    process.stdin.setEncoding("utf-8");
+    // Read whatever is available with a short timeout
+    const stdinData = await new Promise((res) => {
+      const timer = setTimeout(() => { process.stdin.pause(); res(chunks.join("")); }, 500);
+      process.stdin.on("data", (chunk) => chunks.push(chunk));
+      process.stdin.on("end", () => { clearTimeout(timer); res(chunks.join("")); });
+      process.stdin.resume();
+    });
+    if (stdinData.trim()) hookData = JSON.parse(stdinData);
+  } catch { /* no stdin or invalid JSON */ }
+
+  // Play sound (fire and forget, don't wait)
+  const soundPromise = soundFile
+    ? playSoundWithCancel(soundFile).promise.catch(() => {})
+    : Promise.resolve();
+
+  // TTS: speak first 1-2 sentences of last_assistant_message
+  if (tts && hookData.last_assistant_message) {
+    const msg = hookData.last_assistant_message;
+    // Extract first sentence only
+    const sentences = msg.match(/[^.!?]*[.!?]/g);
+    const summary = sentences ? sentences[0].trim() : msg.slice(0, 100);
+    await soundPromise;
+    const { speak } = await import("./tts.js");
+    await speak(summary);
+  } else {
+    await soundPromise;
   }
+}
 
-  return `if [[ "$OSTYPE" == "darwin"* ]]; then afplay "${normalized}" & elif [[ "$OSTYPE" == "msys"* ]] || [[ "$OSTYPE" == "cygwin"* ]]; then powershell.exe -NoProfile -Command "Add-Type -AssemblyName PresentationCore; \\$p = New-Object System.Windows.Media.MediaPlayer; \\$p.Open([System.Uri]::new('$(cygpath -w "${normalized}")')); Start-Sleep -Milliseconds 200; \\$p.Play(); Start-Sleep -Seconds 2" & else aplay "${normalized}" & fi`;
+/**
+ * Generate the shell command string for use in Claude Code hooks.
+ */
+export function getHookPlayCommand(soundFilePath, { tts = false } = {}) {
+  const normalized = soundFilePath.replace(/\\/g, "/");
+  const ttsFlag = tts ? " --tts" : "";
+  return `npx klaudio play "${normalized}"${ttsFlag}`;
 }

package/src/tts.js

@@ -0,0 +1,220 @@
+import { execFile, spawn } from "node:child_process";
+import { mkdir, stat, rename, chmod } from "node:fs/promises";
+import { createWriteStream } from "node:fs";
+import { join, basename } from "node:path";
+import { homedir, platform, arch, tmpdir } from "node:os";
+import { pipeline } from "node:stream/promises";
+import { createHash } from "node:crypto";
+
+const PIPER_VERSION = "2023.11.14-2";
+const VOICE_NAME = "en_GB-alan-medium";
+const VOICE_SAMPLE_RATE = 22050;
+
+const PIPER_DIR = join(homedir(), ".klaudio", "piper");
+
+/**
+ * Get the piper release asset name for the current platform.
+ */
+function getPiperAssetName() {
+  const os = platform();
+  const a = arch();
+
+  if (os === "win32") return "piper_windows_amd64.zip";
+  if (os === "darwin") return a === "arm64" ? "piper_macos_aarch64.tar.gz" : "piper_macos_x64.tar.gz";
+  // Linux
+  if (a === "arm64" || a === "aarch64") return "piper_linux_aarch64.tar.gz";
+  return "piper_linux_x86_64.tar.gz";
+}
+
+/**
+ * Get the piper binary path.
+ */
+function getPiperBinPath() {
+  const bin = platform() === "win32" ? "piper.exe" : "piper";
+  return join(PIPER_DIR, "piper", bin);
+}
+
+/**
+ * Get the voice model path.
+ */
+function getVoiceModelPath() {
+  return join(PIPER_DIR, `${VOICE_NAME}.onnx`);
+}
+
+/**
+ * Download a file from a URL to a local path.
+ */
+async function downloadFile(url, destPath, onProgress) {
+  const res = await fetch(url, { redirect: "follow" });
+  if (!res.ok) throw new Error(`Download failed: ${res.status} ${res.statusText}`);
+  const total = parseInt(res.headers.get("content-length") || "0", 10);
+  let downloaded = 0;
+
+  const fileStream = createWriteStream(destPath);
+  const reader = res.body.getReader();
+
+  // Manual stream piping with progress
+  while (true) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    fileStream.write(value);
+    downloaded += value.length;
+    if (onProgress && total > 0) {
+      onProgress(Math.round((downloaded / total) * 100));
+    }
+  }
+
+  fileStream.end();
+  await new Promise((resolve, reject) => {
+    fileStream.on("finish", resolve);
+    fileStream.on("error", reject);
+  });
+}
+
+/**
+ * Extract a .tar.gz or .zip archive.
+ */
+async function extractArchive(archivePath, destDir) {
+  const os = platform();
+
+  if (archivePath.endsWith(".zip")) {
+    if (os === "win32") {
+      // Use PowerShell to extract on Windows
+      await new Promise((resolve, reject) => {
+        execFile("powershell.exe", [
+          "-NoProfile", "-Command",
+          `Expand-Archive -Path '${archivePath}' -DestinationPath '${destDir}' -Force`,
+        ], { windowsHide: true, timeout: 60000 }, (err) => err ? reject(err) : resolve());
+      });
+    } else {
+      await new Promise((resolve, reject) => {
+        execFile("unzip", ["-o", archivePath, "-d", destDir], { timeout: 60000 }, (err) => err ? reject(err) : resolve());
+      });
+    }
+  } else {
+    // tar.gz
+    await new Promise((resolve, reject) => {
+      execFile("tar", ["xzf", archivePath, "-C", destDir], { timeout: 60000 }, (err) => err ? reject(err) : resolve());
+    });
+  }
+}
+
+/**
+ * Ensure piper binary is available, downloading if needed.
+ * Returns the path to the piper executable.
+ */
+export async function ensurePiper(onProgress) {
+  const binPath = getPiperBinPath();
+
+  // Check if already downloaded
+  try {
+    await stat(binPath);
+    return binPath;
+  } catch { /* needs download */ }
+
+  try {
+    await mkdir(PIPER_DIR, { recursive: true });
+
+    const asset = getPiperAssetName();
+    const url = `https://github.com/rhasspy/piper/releases/download/${PIPER_VERSION}/${asset}`;
+    const archivePath = join(PIPER_DIR, asset);
+
+    if (onProgress) onProgress(`Downloading piper TTS...`);
+    await downloadFile(url, archivePath, (pct) => {
+      if (onProgress) onProgress(`Downloading piper TTS... ${pct}%`);
+    });
+
+    if (onProgress) onProgress("Extracting piper...");
+    await extractArchive(archivePath, PIPER_DIR);
+
+    // Make executable on Unix
+    if (platform() !== "win32") {
+      try { await chmod(binPath, 0o755); } catch { /* ignore */ }
+    }
+
+    return binPath;
+  } catch (err) {
+    // Clean up partial downloads
+    try { const { unlink } = await import("node:fs/promises"); await unlink(join(PIPER_DIR, getPiperAssetName())); } catch { /* ignore */ }
+    throw new Error(`Failed to download piper: ${err.message}`);
+  }
+}
+
+/**
+ * Ensure voice model is available, downloading if needed.
+ * Returns the path to the .onnx model file.
+ */
+export async function ensureVoiceModel(onProgress) {
+  const modelPath = getVoiceModelPath();
+  const configPath = modelPath + ".json";
+
+  // Check if already downloaded
+  try {
+    await stat(modelPath);
+    await stat(configPath);
+    return modelPath;
+  } catch { /* needs download */ }
+
+  try {
+    await mkdir(PIPER_DIR, { recursive: true });
+
+    const baseUrl = `https://huggingface.co/rhasspy/piper-voices/resolve/v1.0.0/en/en_GB/alan/medium`;
+
+    if (onProgress) onProgress("Downloading voice model...");
+    await downloadFile(`${baseUrl}/${VOICE_NAME}.onnx`, modelPath, (pct) => {
+      if (onProgress) onProgress(`Downloading voice model... ${pct}%`);
+    });
+
+    if (onProgress) onProgress("Downloading voice config...");
+    await downloadFile(`${baseUrl}/${VOICE_NAME}.onnx.json`, configPath);
+
+    return modelPath;
+  } catch (err) {
+    // Clean up partial downloads
+    const { unlink } = await import("node:fs/promises");
+    try { await unlink(modelPath); } catch { /* ignore */ }
+    try { await unlink(configPath); } catch { /* ignore */ }
+    throw new Error(`Failed to download voice model: ${err.message}`);
+  }
+}
+
+/**
+ * Speak text using Piper TTS.
+ * Auto-downloads piper and voice model on first use.
+ * Returns a promise that resolves when speech is done.
+ */
+export async function speak(text, onProgress) {
+  if (!text) return;
+
+  let piperBin, modelPath;
+  try {
+    [piperBin, modelPath] = await Promise.all([
+      ensurePiper(onProgress),
+      ensureVoiceModel(onProgress),
+    ]);
+  } catch {
+    // TTS unavailable (download failed, offline, etc.) — skip silently
+    return;
+  }
+
+  // Generate to temp wav file
+  const hash = createHash("md5").update(text).digest("hex").slice(0, 8);
+  const outPath = join(tmpdir(), `klaudio-tts-${hash}.wav`);
+
+  await new Promise((resolve, reject) => {
+    const child = execFile(piperBin, [
+      "--model", modelPath,
+      "--output_file", outPath,
+    ], { windowsHide: true, timeout: 15000 }, (err) => {
+      if (err) reject(err);
+      else resolve();
+    });
+    // Feed text via stdin
+    child.stdin.write(text);
+    child.stdin.end();
+  });
+
+  // Play the generated wav
+  const { playSoundWithCancel } = await import("./player.js");
+  await playSoundWithCancel(outPath, { maxSeconds: 0 }).promise.catch(() => {});
+}