klaudio 0.6.0 → 0.8.0

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.6.0",
+  "version": "0.8.0",
   "description": "Add sound effects to your coding sessions — play sounds when tasks complete, notifications arrive, and more",
   "type": "module",
   "bin": {

package/src/cli.js

@@ -3,7 +3,7 @@ import { render, Box, Text, useInput, useApp } from "ink";
 import Spinner from "ink-spinner";
 import { PRESETS, EVENTS } from "./presets.js";
 import { playSoundWithCancel, getWavDuration } from "./player.js";
-import { getAvailableGames } from "./scanner.js";
+import { getAvailableGames, getSystemSounds } from "./scanner.js";
 import { install, uninstall, getExistingSounds } from "./installer.js";
 import { getVgmstreamPath, findPackedAudioFiles, extractToWav } from "./extractor.js";
 import { extractUnityResource } from "./unity.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,26 +159,47 @@ 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 items = [
     ...Object.entries(PRESETS).map(([id, p]) => ({
       label: `${p.icon} ${p.name}  — ${p.description}`,
       value: id,
     })),
-    { label: "🕹️  Scan local games  — find sounds from your Steam & Epic Games library", value: "_scan" },
+    // separator before these
+    { label: "🔔 System sounds  — use built-in OS notification sounds", value: "_system" },
+    { 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 = 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) 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) }),
+    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 }),
   );
@@ -600,6 +632,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})`;
@@ -757,6 +799,7 @@ const GameSoundsScreen = ({ game, sounds, onSelectSound, onDone, onBack }) => {
 
   // Phase 1: Browse and pick files (auto-preview plays on highlight)
   const filterLower = filter.toLowerCase();
+
   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` : ""})` : "";
@@ -768,11 +811,22 @@ const GameSoundsScreen = ({ game, sounds, onSelectSound, onDone, onBack }) => {
       label: `${catTag}${name}${durStr}`,
       usedTag: usedFor ? `  ← ${usedFor.join(", ")}` : null,
       value: f.path,
+      _dur: dur,
     };
   });
 
   const filteredFiles = filter
-    ? allFileItems.filter((i) => i.label.toLowerCase().includes(filterLower))
+    ? durationFilter
+      ? allFileItems.filter((i) => {
+          if (i._dur == null) return false;
+          const { op, val } = durationFilter;
+          if (op === "<") return i._dur < val;
+          if (op === ">") return i._dur > val;
+          if (op === "<=") return i._dur <= val;
+          if (op === ">=") return i._dur >= val;
+          return true;
+        })
+      : allFileItems.filter((i) => i.label.toLowerCase().includes(filterLower))
     : allFileItems;
 
   const fileItems = [
@@ -797,12 +851,12 @@ const GameSoundsScreen = ({ game, sounds, onSelectSound, onDone, onBack }) => {
     ),
     filter
       ? h(Box, { marginLeft: 4 },
-          h(Text, { color: "yellow" }, "Filter: "),
+          h(Text, { color: "yellow" }, durationFilter ? "Duration: " : "Filter: "),
           h(Text, { bold: true }, filter),
           h(Text, { dimColor: true }, ` (${filteredFiles.length} match${filteredFiles.length !== 1 ? "es" : ""})`),
         )
       : categoryFiles.length > 15
-        ? h(Text, { dimColor: true, marginLeft: 4 }, "Type to filter...")
+        ? h(Text, { dimColor: true, marginLeft: 4 }, "Type to filter... (e.g. <10s, >5s)")
         : null,
     fileItems.length > 0
       ? h(Box, { marginLeft: 2 },
@@ -1248,8 +1302,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" },
@@ -1267,6 +1324,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) => {
@@ -1279,13 +1342,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 });
     });
   }, []);
@@ -1389,6 +1452,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);
@@ -1402,6 +1466,8 @@ const InstallApp = () => {
     switch (screen) {
       case SCREEN.SCOPE:
         return h(ScopeScreen, {
+          tts,
+          onToggleTts: () => setTts((v) => !v),
           onNext: (s) => {
             setScope(s);
             getExistingSounds(s).then((existing) => {
@@ -1417,6 +1483,12 @@ const InstallApp = () => {
           onNext: (id) => {
             if (id === "_music") {
               setScreen(SCREEN.MUSIC_MODE);
+            } else if (id === "_system") {
+              getSystemSounds().then((files) => {
+                const catFiles = categorizeLooseFiles(files);
+                setSelectedGame({ name: "System Sounds", path: "", files: catFiles, fileCount: catFiles.length, hasAudio: catFiles.length > 0 });
+                setScreen(SCREEN.GAME_SOUNDS);
+              });
             } else if (id === "_scan") {
               setScreen(SCREEN.GAME_PICK);
             } else if (id === "_custom") {
@@ -1506,6 +1578,8 @@ const InstallApp = () => {
         return h(ConfirmScreen, {
           scope,
           sounds,
+          tts,
+          onToggleTts: () => setTts((v) => !v),
           onConfirm: () => setScreen(SCREEN.INSTALLING),
           onBack: () => {
             if (selectedGame) setScreen(SCREEN.GAME_SOUNDS);
@@ -1517,6 +1591,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/scanner.js

@@ -379,6 +379,46 @@ export async function scanForGames(onProgress, onGameFound) {
   return games;
 }
 
+/**
+ * Discover system sounds (Windows Media, macOS system sounds, Linux sound themes).
+ * Returns an array of { path, name, dir } matching the game file format.
+ */
+export async function getSystemSounds() {
+  const os = platform();
+  const results = [];
+
+  const dirs = [];
+  if (os === "win32") {
+    dirs.push("C:/Windows/Media", "C:/Windows/Media/dm");
+  } else if (os === "darwin") {
+    dirs.push("/System/Library/Sounds");
+  } else {
+    // Linux: common sound theme locations
+    dirs.push(
+      "/usr/share/sounds/freedesktop/stereo",
+      "/usr/share/sounds/gnome/default/alerts",
+      "/usr/share/sounds/ubuntu/stereo",
+      "/usr/share/sounds",
+    );
+  }
+
+  for (const dir of dirs) {
+    if (!(await dirExists(dir))) continue;
+    try {
+      const entries = await readdir(dir, { withFileTypes: true });
+      for (const entry of entries) {
+        if (!entry.isFile()) continue;
+        const ext = extname(entry.name).toLowerCase();
+        if (AUDIO_EXTENSIONS.has(ext)) {
+          results.push({ path: join(dir, entry.name), name: entry.name, dir });
+        }
+      }
+    } catch { /* skip */ }
+  }
+
+  return results;
+}
+
 /**
  * Get a flat list of all found game directories.
  */

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(() => {});
+}