klaudio 0.9.2 → 0.10.1

package/bin/cli.js

@@ -1,12 +1,25 @@
 #!/usr/bin/env node
 
-// Subcommand: klaudio play <file> [--tts]
+// Subcommand: klaudio play <file> [--tts] [--voice <voice>]
 if (process.argv[2] === "play") {
   const { handlePlayCommand } = await import("../src/player.js");
   await handlePlayCommand(process.argv.slice(3));
   process.exit(0);
 }
 
+// Subcommand: klaudio say "text" [--voice <voice>]
+if (process.argv[2] === "say") {
+  const args = process.argv.slice(3);
+  const text = args.find((a) => !a.startsWith("--"));
+  const voice = args.find((a) => a.startsWith("--voice="))?.slice(8)
+    || args[args.indexOf("--voice") + 1];
+  if (text) {
+    const { speak } = await import("../src/tts.js");
+    await speak(text, { voice });
+  }
+  process.exit(0);
+}
+
 // Default: interactive installer UI
 const { run } = await import("../src/cli.js");
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "klaudio",
-  "version": "0.9.2",
+  "version": "0.10.1",
   "description": "Add sound effects to your coding sessions — play sounds when tasks complete, notifications arrive, and more",
   "type": "module",
   "bin": {
@@ -32,6 +32,7 @@
     "ink": "^6.8.0",
     "ink-select-input": "^6.2.0",
     "ink-spinner": "^5.0.0",
+    "kokoro-js": "^1.2.1",
     "react": "^19.2.4"
   },
   "engines": {

package/src/cli.js

@@ -2,6 +2,7 @@ import React, { useState, useEffect, useCallback, useRef, useMemo } from "react"
 import { render, Box, Text, useInput, useApp } from "ink";
 import Spinner from "ink-spinner";
 import { PRESETS, EVENTS } from "./presets.js";
+import { KOKORO_PRESET_VOICES, KOKORO_VOICES, KOKORO_DEFAULT_VOICE } from "./tts.js";
 import { playSoundWithCancel, getWavDuration } from "./player.js";
 import { getAvailableGames, getSystemSounds } from "./scanner.js";
 import { install, uninstall, getExistingSounds } from "./installer.js";
@@ -1369,10 +1370,11 @@ const ExtractingScreen = ({ game, onDone, onBack }) => {
 };
 
 // ── Screen: Confirm ─────────────────────────────────────────────
-const ConfirmScreen = ({ scope, sounds, tts, onToggleTts, onConfirm, onBack }) => {
+const ConfirmScreen = ({ scope, sounds, tts, voice, onToggleTts, onCycleVoice, onConfirm, onBack }) => {
   useInput((input, key) => {
     if (key.escape) onBack();
     else if (input === "t") onToggleTts();
+    else if (input === "v" && tts) onCycleVoice();
   });
 
   const items = [
@@ -1381,6 +1383,7 @@ const ConfirmScreen = ({ scope, sounds, tts, onToggleTts, onConfirm, onBack }) =
   ];
 
   const soundEntries = Object.entries(sounds).filter(([_, path]) => path);
+  const voiceInfo = KOKORO_VOICES.find((v) => v.id === voice);
 
   return h(Box, { flexDirection: "column" },
     h(Text, { bold: true, marginLeft: 2 }, "  Ready to install:"),
@@ -1397,6 +1400,12 @@ const ConfirmScreen = ({ scope, sounds, tts, onToggleTts, onConfirm, onBack }) =
         ),
         h(Text, { dimColor: true }, "  (t to toggle — reads a short summary when tasks complete)"),
       ),
+      tts && voiceInfo ? h(Box, { marginLeft: 4 },
+        h(Text, { color: ACCENT },
+          `🎙 Voice: ${voiceInfo.name} (${voiceInfo.gender}, ${voiceInfo.accent})`,
+        ),
+        h(Text, { dimColor: true }, "  (v to change voice)"),
+      ) : null,
     ),
     h(Box, { marginTop: 1, marginLeft: 2 },
       h(SelectInput, { indicatorComponent: Indicator, itemComponent: Item, items, onSelect: (item) => {
@@ -1409,13 +1418,13 @@ const ConfirmScreen = ({ scope, sounds, tts, onToggleTts, onConfirm, onBack }) =
 };
 
 // ── Screen: Installing ──────────────────────────────────────────
-const InstallingScreen = ({ scope, sounds, tts, onDone }) => {
+const InstallingScreen = ({ scope, sounds, tts, voice, onDone }) => {
   useEffect(() => {
     const validSounds = {};
     for (const [eventId, path] of Object.entries(sounds)) {
       if (path) validSounds[eventId] = path;
     }
-    install({ scope, sounds: validSounds, tts }).then(onDone).catch((err) => {
+    install({ scope, sounds: validSounds, tts, voice }).then(onDone).catch((err) => {
       onDone({ error: err.message });
     });
   }, []);
@@ -1520,6 +1529,7 @@ const InstallApp = () => {
   const [selectedGame, setSelectedGame] = useState(null);
   const [installResult, setInstallResult] = useState(null);
   const [tts, setTts] = useState(true);
+  const [voice, setVoice] = useState(KOKORO_DEFAULT_VOICE);
   const [musicFiles, setMusicFiles] = useState([]);
   const [musicGameName, setMusicGameName] = useState(null);
   const [musicShuffle, setMusicShuffle] = useState(false);
@@ -1568,6 +1578,7 @@ const InstallApp = () => {
             } else {
               setPresetId(id);
               initSoundsFromPreset(id);
+              if (KOKORO_PRESET_VOICES[id]) setVoice(KOKORO_PRESET_VOICES[id]);
               setScreen(SCREEN.PREVIEW);
             }
           },
@@ -1648,7 +1659,12 @@ const InstallApp = () => {
           scope,
           sounds,
           tts,
+          voice,
           onToggleTts: () => setTts((v) => !v),
+          onCycleVoice: () => setVoice((v) => {
+            const idx = KOKORO_VOICES.findIndex((x) => x.id === v);
+            return KOKORO_VOICES[(idx + 1) % KOKORO_VOICES.length].id;
+          }),
           onConfirm: () => setScreen(SCREEN.INSTALLING),
           onBack: () => {
             if (selectedGame) setScreen(SCREEN.GAME_SOUNDS);
@@ -1661,6 +1677,7 @@ const InstallApp = () => {
           scope,
           sounds,
           tts,
+          voice,
           onDone: (result) => {
             setInstallResult(result);
             setScreen(SCREEN.DONE);

package/src/installer.js

@@ -22,7 +22,7 @@ function getTargetDir(scope) {
  * @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, tts = false }) {
+export async function install({ scope, sounds, tts = false, voice } = {}) {
   const claudeDir = getTargetDir(scope);
   const soundsDir = join(claudeDir, "sounds");
   const settingsFile = join(claudeDir, "settings.json");
@@ -69,7 +69,7 @@ export async function install({ scope, sounds, tts = false }) {
     const hookEvent = event.hookEvent;
     // Enable TTS only for the "stop" event (task complete)
     const useTts = tts && eventId === "stop";
-    const playCommand = getHookPlayCommand(soundPath, { tts: useTts });
+    const playCommand = getHookPlayCommand(soundPath, { tts: useTts, voice });
 
     // Check if there's already a klaudio hook for this event
     if (!settings.hooks[hookEvent]) {
@@ -118,7 +118,7 @@ async function installApprovalHooks(settings, soundPath, claudeDir) {
   // Write the timer script
   const script = `#!/usr/bin/env bash
 # klaudio: approval notification timer
-# Plays a sound if a tool isn't approved within DELAY seconds.
+# Plays a sound + speaks a TTS message if a tool isn't approved within DELAY seconds.
 DELAY=15
 MARKER="/tmp/.claude-approval-pending"
 SOUND="${normalized}"
@@ -126,12 +126,16 @@ SOUND="${normalized}"
 case "$1" in
   start)
     TOKEN="$$-$(date +%s%N)"
+    # Store token and CWD so the delayed notification knows the project name
     echo "$TOKEN" > "$MARKER"
+    echo "$PWD" >> "$MARKER"
     (
       sleep "$DELAY"
-      if [ -f "$MARKER" ] && [ "$(cat "$MARKER" 2>/dev/null)" = "$TOKEN" ]; then
+      if [ -f "$MARKER" ] && [ "$(head -1 "$MARKER" 2>/dev/null)" = "$TOKEN" ]; then
+        PROJECT=$(tail -1 "$MARKER" 2>/dev/null | sed 's|.*[/\\\\]||')
         rm -f "$MARKER"
         npx klaudio play "$SOUND" 2>/dev/null
+        npx klaudio say "\${PROJECT:-project} needs your attention" 2>/dev/null
       fi
     ) &
     ;;

package/src/player.js

@@ -444,7 +444,9 @@ export async function handlePlayCommand(args) {
     const spoken = project ? `${project}: ${summary}` : summary;
     await soundPromise;
     const { speak } = await import("./tts.js");
-    await speak(spoken);
+    const voice = args.find((a) => a.startsWith("--voice="))?.slice(8)
+      || args[args.indexOf("--voice") + 1];
+    await speak(spoken, { voice });
   } else {
     await soundPromise;
   }
@@ -453,8 +455,9 @@ export async function handlePlayCommand(args) {
 /**
  * Generate the shell command string for use in Claude Code hooks.
  */
-export function getHookPlayCommand(soundFilePath, { tts = false } = {}) {
+export function getHookPlayCommand(soundFilePath, { tts = false, voice } = {}) {
   const normalized = soundFilePath.replace(/\\/g, "/");
   const ttsFlag = tts ? " --tts" : "";
-  return `npx klaudio play "${normalized}"${ttsFlag}`;
+  const voiceFlag = tts && voice ? ` --voice ${voice}` : "";
+  return `npx klaudio play "${normalized}"${ttsFlag}${voiceFlag}`;
 }

package/src/tts.js

@@ -1,49 +1,110 @@
-import { execFile, spawn } from "node:child_process";
-import { mkdir, stat, rename, chmod } from "node:fs/promises";
+import { execFile } from "node:child_process";
+import { mkdir, stat, chmod, writeFile as fsWriteFile } 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");
 
+// ── Kokoro TTS (primary engine) ─────────────────────────────────
+
+// Default voice per preset vibe
+const KOKORO_PRESET_VOICES = {
+  "retro-8bit": "af_bella",
+  "minimal-zen": "af_heart",
+  "sci-fi-terminal": "af_nova",
+  "victory-fanfare": "af_sky",
+};
+const KOKORO_DEFAULT_VOICE = "af_heart";
+
+// Curated voice list for the picker (best quality voices)
+const KOKORO_VOICES = [
+  { id: "af_heart",  name: "Heart",  gender: "F", accent: "US", grade: "A" },
+  { id: "af_bella",  name: "Bella",  gender: "F", accent: "US", grade: "A-" },
+  { id: "af_nicole", name: "Nicole", gender: "F", accent: "US", grade: "B-" },
+  { id: "af_nova",   name: "Nova",   gender: "F", accent: "US", grade: "C" },
+  { id: "af_sky",    name: "Sky",    gender: "F", accent: "US", grade: "C-" },
+  { id: "af_sarah",  name: "Sarah",  gender: "F", accent: "US", grade: "C+" },
+  { id: "am_fenrir", name: "Fenrir", gender: "M", accent: "US", grade: "C+" },
+  { id: "am_michael",name: "Michael",gender: "M", accent: "US", grade: "C+" },
+  { id: "am_puck",   name: "Puck",   gender: "M", accent: "US", grade: "C+" },
+  { id: "bf_emma",   name: "Emma",   gender: "F", accent: "UK", grade: "B-" },
+  { id: "bm_george", name: "George", gender: "M", accent: "UK", grade: "C" },
+  { id: "bm_fable",  name: "Fable",  gender: "M", accent: "UK", grade: "C" },
+];
+
+// Singleton: reuse the loaded model across calls
+let kokoroInstance = null;
+let kokoroLoadPromise = null;
+
+/**
+ * Load the Kokoro TTS model (singleton, downloads ~86MB on first use).
+ * Uses CPU backend (DirectML has ConvTranspose compatibility issues).
+ */
+async function getKokoro() {
+  if (kokoroInstance) return kokoroInstance;
+  if (kokoroLoadPromise) return kokoroLoadPromise;
+
+  kokoroLoadPromise = (async () => {
+    const { KokoroTTS } = await import("kokoro-js");
+    kokoroInstance = await KokoroTTS.from_pretrained(
+      "onnx-community/Kokoro-82M-v1.0-ONNX",
+      { dtype: "q4", device: "cpu" },
+    );
+    return kokoroInstance;
+  })();
+
+  try {
+    return await kokoroLoadPromise;
+  } catch (err) {
+    kokoroLoadPromise = null;
+    throw err;
+  }
+}
+
 /**
- * Get the piper release asset name for the current platform.
+ * Speak text using Kokoro TTS.
+ * Returns true if successful, false if Kokoro is unavailable.
  */
+async function speakKokoro(text, voice) {
+  const tts = await getKokoro();
+  const voiceId = voice || KOKORO_DEFAULT_VOICE;
+
+  const audio = await tts.generate(text, { voice: voiceId, speed: 1.0 });
+
+  // Save to temp wav and play
+  const hash = createHash("md5").update(text + voiceId).digest("hex").slice(0, 8);
+  const outPath = join(tmpdir(), `klaudio-kokoro-${hash}.wav`);
+  audio.save(outPath);
+
+  const { playSoundWithCancel } = await import("./player.js");
+  await playSoundWithCancel(outPath, { maxSeconds: 0 }).promise.catch(() => {});
+}
+
+// ── Piper TTS (fallback engine) ─────────────────────────────────
+
 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}`);
@@ -53,7 +114,6 @@ async function downloadFile(url, destPath, onProgress) {
   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;
@@ -71,15 +131,10 @@ async function downloadFile(url, destPath, onProgress) {
   });
 }
 
-/**
- * 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",
@@ -92,21 +147,14 @@ async function extractArchive(archivePath, destDir) {
       });
     }
   } 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;
@@ -114,7 +162,6 @@ export async function ensurePiper(onProgress) {
 
   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);
@@ -127,28 +174,20 @@ export async function ensurePiper(onProgress) {
     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);
@@ -157,7 +196,6 @@ export async function ensureVoiceModel(onProgress) {
 
   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...");
@@ -170,7 +208,6 @@ export async function ensureVoiceModel(onProgress) {
 
     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 */ }
@@ -178,28 +215,7 @@ export async function ensureVoiceModel(onProgress) {
   }
 }
 
-/**
- * Speak text using macOS `say` command (built-in, good quality).
- */
-function speakMacOS(text) {
-  return new Promise((resolve) => {
-    execFile("say", ["-v", "Daniel", text], { timeout: 15000 }, () => resolve());
-  });
-}
-
-/**
- * Speak text using Piper TTS, with macOS `say` fallback.
- * 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;
-
-  // macOS: use built-in `say` — better compatibility, no dylib issues
-  if (platform() === "darwin") {
-    return speakMacOS(text);
-  }
-
+async function speakPiper(text, onProgress) {
   let piperBin, modelPath;
   try {
     [piperBin, modelPath] = await Promise.all([
@@ -207,11 +223,9 @@ export async function speak(text, 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`);
 
@@ -225,15 +239,58 @@ export async function speak(text, onProgress) {
         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(() => {});
   } catch {
-    // Piper failed (dylib error, etc.) — skip silently
+    // Piper failed — skip silently
   }
 }
+
+// ── macOS fallback ──────────────────────────────────────────────
+
+function speakMacOS(text) {
+  return new Promise((resolve) => {
+    execFile("say", ["-v", "Daniel", text], { timeout: 15000 }, () => resolve());
+  });
+}
+
+// ── Public API ──────────────────────────────────────────────────
+
+/**
+ * Speak text using the best available TTS engine.
+ * Priority: Kokoro (GPU/CPU) → Piper → macOS say
+ *
+ * @param {string} text - Text to speak
+ * @param {object} [options]
+ * @param {string} [options.voice] - Kokoro voice ID (e.g. "af_heart")
+ * @param {Function} [options.onProgress] - Progress callback for downloads
+ */
+export async function speak(text, options = {}) {
+  if (!text) return;
+
+  const { voice, onProgress } = typeof options === "function"
+    ? { voice: null, onProgress: options }  // backwards compat: speak(text, onProgress)
+    : options;
+
+  // Try Kokoro first (works on all platforms, best quality)
+  try {
+    await speakKokoro(text, voice);
+    return;
+  } catch {
+    // Kokoro unavailable — fall through
+  }
+
+  // macOS: use built-in `say`
+  if (platform() === "darwin") {
+    return speakMacOS(text);
+  }
+
+  // Fallback: Piper
+  return speakPiper(text, onProgress);
+}
+
+export { KOKORO_PRESET_VOICES, KOKORO_VOICES, KOKORO_DEFAULT_VOICE };