claude-sound 0.1.8 → 0.2.0

package/README.md

@@ -1,8 +1,8 @@
 # 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/captured.png)
+![claude-sound CLI](assets/images/cli-installation.png)
 
 - Setup UI: `npx claude-sound@latest`
 - Hook runner: `npx --yes claude-sound@latest play --event <Event> --sound <SoundId> --managed-by claude-sound`
@@ -84,7 +84,14 @@ 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.
 
+## 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.8",
-  "description": "Configure Claude Code hooks to play bundled sounds on macOS (afplay).",
+  "version": "0.2.0",
+  "description": "Configure Claude Code hooks to play bundled sounds (macOS, Windows, Linux).",
   "license": "MIT",
   "homepage": "https://github.com/beefiker/claude-sound",
   "repository": {

package/src/cli.js

@@ -18,7 +18,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);
 }
 

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');