claude-sound 0.1.9 → 0.2.2

package/README.md

@@ -1,6 +1,6 @@
 # claude-sound
 
-macOS-only CLI that configures **Claude Code Hooks** to play **bundled sounds** using `afplay`.
+Cross-platform CLI (macOS, Windows, Linux) that configures **Claude Code Hooks** to play **bundled sounds**.
 
 ![claude-sound CLI](assets/images/cli-installation.png)
 
@@ -19,7 +19,7 @@ You’ll be prompted to choose where to write settings:
 - Project (local): `.claude/settings.local.json`
 - Global: `~/.claude/settings.json`
 
-Then you can enable/disable events and choose a sound per event. Selecting a sound plays a quick preview.
+Then you can enable/disable events and choose a sound per event. Selecting a sound plays a quick preview. Choose **Create my own** to generate custom text-to-speech sounds.
 
 ## Commands
 
@@ -84,7 +84,20 @@ Add `assets/sounds/order.json` to control order and display names:
 - Use full IDs (e.g. `common/baemin`). Sounds not listed append at the end.
 - Use `{ "id": "...", "label": "Display Name" }` for custom labels; otherwise the filename is shown.
 
+## Create my own (text-to-speech)
+
+When picking a sound, choose **Create my own** to generate custom sounds from text. Enter any phrase (e.g. "Claude is ready!") and it will be turned into speech using Google Translate TTS (free, no API key). Requires network. Custom sounds are saved to `~/.claude-sound/sounds/`.
+
+See [docs/TTS.md](docs/TTS.md) for details.
+
+## Platform support
+
+| Platform | Audio player | Notes |
+|----------|--------------|-------|
+| **macOS** | `afplay` | Built-in, no setup needed |
+| **Windows** | `ffplay`, `mpv`, `mpg123`, or PowerShell | Install [ffmpeg](https://ffmpeg.org/) (includes `ffplay`) or [mpv](https://mpv.io/) for best support. PowerShell (built-in) plays WAV only. |
+| **Linux** | `ffplay`, `mpv`, `mpg123`, `aplay`, etc. | Install ffmpeg or mpv for MP3 support. |
+
 ## Notes
 
-- macOS only (requires `afplay`).
 - Hooks run `npx` each time the event fires. It’s simple and works everywhere, but may be slower than a local install.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "claude-sound",
-  "version": "0.1.9",
-  "description": "Configure Claude Code hooks to play bundled sounds on macOS (afplay).",
+  "version": "0.2.2",
+  "description": "Configure Claude Code hooks to play bundled sounds (macOS, Windows, Linux).",
   "license": "MIT",
   "homepage": "https://github.com/beefiker/claude-sound",
   "repository": {
@@ -27,6 +27,7 @@
     "prepack": "npm run generate:sounds"
   },
   "dependencies": {
-    "@clack/prompts": "^1.0.0"
+    "@clack/prompts": "^1.0.0",
+    "@sefinek/google-tts-api": "^2.1.11"
   }
 }

package/src/cli.js

@@ -1,11 +1,12 @@
 #!/usr/bin/env node
 
-import { intro, outro, select, isCancel, cancel, note, spinner } from '@clack/prompts';
+import { intro, outro, select, text, isCancel, cancel, note, spinner } from '@clack/prompts';
 import pc from 'picocolors';
 import process from 'node:process';
 import fs from 'node:fs/promises';
 import { playSound } from './play.js';
-import { listSounds, listSoundsGrouped, ensureSoundsLoaded } from './sounds.js';
+import { listSounds, listSoundsGrouped, ensureSoundsLoaded, invalidateSoundCache } from './sounds.js';
+import { generateTts } from './tts.js';
 import { selectWithSoundPreview } from './select-with-preview.js';
 import {
   HOOK_EVENTS,
@@ -18,7 +19,7 @@ import {
 
 function usage(exitCode = 0) {
   process.stdout.write(`\
-claude-sound (macOS)\n\nUsage:\n  npx claude-sound@latest                Interactive hook sound setup\n  claude-sound                          Interactive hook sound setup\n\n  claude-sound play --sound <id>         Play a bundled sound (uses afplay)\n  claude-sound list-sounds              List bundled sound ids\n  claude-sound list-events              List Claude hook event names\n\nOptions:\n  -h, --help                             Show help\n\nExamples:\n  npx claude-sound@latest\n  npx claude-sound@latest play --sound ring1\n`);
+claude-sound (macOS, Windows, Linux)\n\nUsage:\n  npx claude-sound@latest                Interactive hook sound setup\n  claude-sound                          Interactive hook sound setup\n\n  claude-sound play --sound <id>         Play a bundled sound\n  claude-sound list-sounds              List bundled sound ids\n  claude-sound list-events              List Claude hook event names\n\nOptions:\n  -h, --help                             Show help\n\nExamples:\n  npx claude-sound@latest\n  npx claude-sound@latest play --sound ring1\n`);
   process.exit(exitCode);
 }
 
@@ -31,7 +32,9 @@ function parseArg(flag) {
 const SOUND_GROUPS = [
   { value: 'common', label: 'Common' },
   { value: 'game', label: 'Game' },
-  { value: 'ring', label: 'Ring' }
+  { value: 'ring', label: 'Ring' },
+  { value: 'custom', label: 'Custom (TTS)' },
+  { value: '__create__', label: 'Create my own (text-to-speech)' }
 ];
 
 /**
@@ -42,7 +45,11 @@ const SOUND_GROUPS = [
  */
 function formatSoundDisplay(soundId, labels) {
   const displayName = labels[soundId] ?? (soundId.includes('/') ? soundId.split('/')[1] : soundId);
-  const group = SOUND_GROUPS.find((g) => soundId.startsWith(g.value + '/') || (g.value === 'ring' && !soundId.includes('/')));
+  const group = SOUND_GROUPS.find(
+    (g) =>
+      (g.value !== '__create__' && soundId.startsWith(g.value + '/')) ||
+      (g.value === 'ring' && !soundId.includes('/'))
+  );
   return group ? `${group.label} / ${displayName}` : displayName;
 }
 
@@ -179,7 +186,9 @@ async function interactiveSetup() {
       continue;
     }
 
-    const categoryOptions = SOUND_GROUPS.filter((g) => (soundsGrouped[g.value]?.length ?? 0) > 0);
+    const categoryOptions = SOUND_GROUPS.filter(
+      (g) => g.value === '__create__' || (soundsGrouped[g.value]?.length ?? 0) > 0
+    );
 
     while (true) {
       const category = await select({
@@ -189,6 +198,38 @@ async function interactiveSetup() {
 
       if (isCancel(category)) break;
 
+      if (category === '__create__') {
+        const textInput = await text({
+          message: 'Enter text to speak (e.g. "Claude is ready!")',
+          placeholder: 'Claude is ready!',
+          validate: (v) => {
+            if (!v?.trim()) return 'Text cannot be empty';
+            if (v.length > 200) return 'Keep it under 200 characters';
+            return undefined;
+          }
+        });
+
+        if (isCancel(textInput)) continue;
+
+        const s = spinner();
+        s.start('Generating speech...');
+        try {
+          const { soundId: newSoundId } = await generateTts(textInput);
+          invalidateSoundCache();
+          const refreshed = await listSoundsGrouped();
+          soundsGrouped.custom = refreshed.grouped.custom;
+          soundLabels[newSoundId] = refreshed.labels[newSoundId] ?? textInput.trim().slice(0, 30);
+          s.stop('Done');
+          mappings[eventName] = newSoundId;
+          note(`Created and selected: ${newSoundId}`, 'Created');
+          break;
+        } catch (err) {
+          s.stop('Failed');
+          note(String(err?.message ?? err), 'Error');
+          continue;
+        }
+      }
+
       const ids = soundsGrouped[category] ?? [];
       const soundOptions = buildSoundOptionsForGroup(ids, soundLabels);
 

package/src/play.js

@@ -1,6 +1,114 @@
-import { execFile, spawn } from 'node:child_process';
+import { execFile, execFileSync, spawn } from 'node:child_process';
+import { platform } from 'node:os';
 import { resolveSoundPath } from './sounds.js';
 
+/**
+ * Player config: { name, check, args }
+ * - name: executable name
+ * - check: sync function to verify availability (returns boolean)
+ * - args: (filePath) => string[] - args to pass to the executable
+ */
+
+/**
+ * Check if an executable exists in PATH.
+ * Uses command -v (POSIX) on Unix, where.exe on Windows.
+ */
+function findExecutable(name) {
+  try {
+    if (platform() === 'win32') {
+      execFileSync('where.exe', [name], { stdio: 'pipe', windowsHide: true });
+    } else {
+      execFileSync('sh', ['-c', `command -v ${name}`], { stdio: 'pipe' });
+    }
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** @type {Array<{ name: string; check: () => boolean; args: (f: string) => string[] }>} */
+const PLAYERS = [
+  {
+    name: 'afplay',
+    check: () => platform() === 'darwin' && findExecutable('afplay'),
+    args: (f) => [f]
+  },
+  {
+    name: 'ffplay',
+    check: () => findExecutable('ffplay'),
+    args: (f) => ['-nodisp', '-autoexit', '-loglevel', 'quiet', f]
+  },
+  {
+    name: 'mpv',
+    check: () => findExecutable('mpv'),
+    args: (f) => ['--no-video', '--really-quiet', f]
+  },
+  {
+    name: 'mpg123',
+    check: () => findExecutable('mpg123'),
+    args: (f) => ['-q', f]
+  },
+  {
+    name: 'mpg321',
+    check: () => findExecutable('mpg321'),
+    args: (f) => ['-q', f]
+  },
+  {
+    name: 'mplayer',
+    check: () => findExecutable('mplayer'),
+    args: (f) => ['-really-quiet', '-vo', 'null', f]
+  },
+  {
+    name: 'aplay',
+    check: () => findExecutable('aplay'),
+    args: (f) => ['-q', f]
+  },
+  {
+    name: 'paplay',
+    check: () => findExecutable('paplay'),
+    args: (f) => [f]
+  },
+  {
+    name: 'cvlc',
+    check: () => findExecutable('cvlc'),
+    args: (f) => ['--play-and-exit', '-q', f]
+  },
+  {
+    name: 'powershell.exe',
+    check: () => platform() === 'win32',
+    args: (f) => {
+      const escaped = f.replace(/'/g, "''");
+      return [
+        '-NoProfile',
+        '-Command',
+        `(New-Object Media.SoundPlayer '${escaped}').PlaySync()`
+      ];
+    }
+  }
+];
+
+/** @type {{ name: string; args: (f: string) => string[] } | null} */
+let _resolvedPlayer = null;
+
+/**
+ * @returns {{ name: string; args: (f: string) => string[] }}
+ * @throws {Error}
+ */
+function getPlayer() {
+  if (_resolvedPlayer) return _resolvedPlayer;
+
+  for (const p of PLAYERS) {
+    if (p.check()) {
+      _resolvedPlayer = { name: p.name, args: p.args };
+      return _resolvedPlayer;
+    }
+  }
+
+  throw new Error(
+    'No audio player found. On Windows/Linux, install ffmpeg (ffplay) or mpv.'
+  );
+}
+
 /**
  * Play a sound and wait for it to finish.
  * @param {string} soundId
@@ -8,8 +116,9 @@ import { resolveSoundPath } from './sounds.js';
  */
 export function playSound(soundId) {
   const file = resolveSoundPath(soundId);
+  const { name, args } = getPlayer();
   return new Promise((resolve, reject) => {
-    execFile('afplay', [file], (err) => {
+    execFile(name, args(file), { windowsHide: true }, (err) => {
       if (err) reject(err);
       else resolve();
     });
@@ -28,11 +137,17 @@ let _previewProcess = null;
 export function playSoundPreview(soundId) {
   stopPreview();
   const file = resolveSoundPath(soundId);
-  const proc = spawn('afplay', [file], {
+  const { name, args } = getPlayer();
+
+  const proc = spawn(name, args(file), {
     detached: true,
-    stdio: 'ignore'
+    stdio: 'ignore',
+    windowsHide: true
   });
   _previewProcess = proc;
+  proc.on('error', () => {
+    if (_previewProcess === proc) _previewProcess = null;
+  });
   proc.on('exit', () => {
     if (_previewProcess === proc) _previewProcess = null;
   });
@@ -47,7 +162,7 @@ export function stopPreview() {
   if (_previewProcess) {
     try {
       const pid = _previewProcess.pid;
-      if (pid != null && process.platform !== 'win32') {
+      if (pid != null && platform() !== 'win32') {
         process.kill(-pid, 'SIGKILL');
       } else {
         _previewProcess.kill('SIGKILL');

package/src/sounds.js

@@ -1,6 +1,7 @@
 import fs from 'node:fs/promises';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { customSoundsDir } from './tts.js';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
@@ -16,9 +17,17 @@ export function soundsDir() {
 /** @type {SoundPathMap | null} */
 let _soundPathCache = null;
 
+/**
+ * Clear the sound path cache. Call after adding custom sounds.
+ * @returns {void}
+ */
+export function invalidateSoundCache() {
+  _soundPathCache = null;
+}
+
 /**
  * Build a map of sound id -> absolute file path.
- * Discovers sounds from manifest.json and subdirs (common/, game/).
+ * Discovers sounds from manifest.json, subdirs (common/, game/), and custom TTS sounds.
  * @returns {Promise<SoundPathMap>}
  */
 async function buildSoundPathMap() {
@@ -57,6 +66,20 @@ async function buildSoundPathMap() {
     }
   }
 
+  // From custom TTS sounds (~/.claude-sound/sounds/)
+  const customDir = customSoundsDir();
+  try {
+    const entries = await fs.readdir(customDir, { withFileTypes: true });
+    for (const e of entries) {
+      if (e.isFile() && (e.name.endsWith('.mp3') || e.name.endsWith('.wav'))) {
+        const id = `custom/${path.basename(e.name, path.extname(e.name))}`;
+        map[id] = path.join(customDir, e.name);
+      }
+    }
+  } catch {
+    // dir missing or not readable
+  }
+
   _soundPathCache = map;
   return map;
 }
@@ -99,7 +122,7 @@ async function applyCustomOrder(grouped, labels, base) {
   }
   if (!order || typeof order !== 'object') return;
 
-  for (const key of ['common', 'game', 'ring']) {
+  for (const key of ['common', 'game', 'ring', 'custom']) {
     const ids = grouped[key];
     if (!ids?.length) continue;
     const ordered = order[key];
@@ -136,13 +159,15 @@ export async function listSoundsGrouped() {
   const grouped = /** @type {GroupedSounds} */ ({
     common: [],
     game: [],
-    ring: []
+    ring: [],
+    custom: []
   });
   const labels = /** @type {SoundLabels} */ ({});
 
   for (const id of Object.keys(map)) {
     if (id.startsWith('common/')) grouped.common.push(id);
     else if (id.startsWith('game/')) grouped.game.push(id);
+    else if (id.startsWith('custom/')) grouped.custom.push(id);
     else grouped.ring.push(id);
   }
 

package/src/tts.js

@@ -0,0 +1,77 @@
+import path from 'node:path';
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import { getAudioBase64 } from '@sefinek/google-tts-api';
+
+const CUSTOM_SOUNDS_DIR = path.join(os.homedir(), '.claude-sound', 'sounds');
+
+/**
+ * Get the directory for custom TTS sounds.
+ * @returns {string}
+ */
+export function customSoundsDir() {
+  return CUSTOM_SOUNDS_DIR;
+}
+
+/**
+ * Create a filesystem-safe slug from text.
+ * @param {string} text
+ * @returns {string}
+ */
+function slugify(text) {
+  const trimmed = text.trim().slice(0, 40);
+  const slug = trimmed
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-|-$/g, '');
+  return slug || 'custom';
+}
+
+/**
+ * Generate a short hash for uniqueness.
+ * @param {string} s
+ * @returns {string}
+ */
+function shortHash(s) {
+  let h = 0;
+  for (let i = 0; i < s.length; i++) {
+    h = (h * 31 + s.charCodeAt(i)) >>> 0;
+  }
+  return Math.abs(h).toString(36).slice(0, 6);
+}
+
+/**
+ * Generate TTS audio from text and save to custom sounds directory.
+ * Uses Google Translate TTS (free, no API key). Requires network.
+ * @param {string} text - Text to speak
+ * @param {object} [opts]
+ * @param {string} [opts.lang] - Language code (default: 'en')
+ * @returns {Promise<{ soundId: string; filePath: string }>}
+ */
+export async function generateTts(text) {
+  const trimmed = text.trim();
+  if (!trimmed) {
+    throw new Error('Text cannot be empty');
+  }
+
+  const dir = customSoundsDir();
+  await fs.mkdir(dir, { recursive: true });
+
+  const baseSlug = slugify(trimmed);
+  const unique = `${baseSlug}-${shortHash(trimmed)}`;
+  const filePath = path.join(dir, `${unique}.mp3`);
+
+  const base64 = await getAudioBase64(trimmed, {
+    lang: 'en',
+    slow: false,
+    timeout: 15000
+  });
+
+  const buffer = Buffer.from(base64, 'base64');
+  await fs.writeFile(filePath, buffer);
+
+  return {
+    soundId: `custom/${unique}`,
+    filePath
+  };
+}