claude-code-sounds 1.5.3 → 1.6.0

package/README.md

@@ -39,18 +39,6 @@ The bash installer requires `jq` (`brew install jq`).
 
 </details>
 
-## Usage
-
-```bash
-npx claude-code-sounds                    # Interactive install
-npx claude-code-sounds --theme portal     # Install a specific theme directly
-npx claude-code-sounds --mix              # Jump to sound assignment grid
-npx claude-code-sounds --yes              # Install defaults, skip all prompts
-npx claude-code-sounds --list             # List available themes
-npx claude-code-sounds --uninstall        # Remove all sounds and hooks
-npx claude-code-sounds --help             # Show help
-```
-
 ## Themes
 
 | Theme | Sounds | Vibe |
@@ -73,7 +61,78 @@ npx claude-code-sounds --help             # Show help
 
 Each theme maps sounds across all 11 Claude Code lifecycle events.
 
-## Hook Events
+## Usage
+
+```bash
+npx claude-code-sounds                    # Interactive install
+npx claude-code-sounds --theme portal     # Install a specific theme directly
+npx claude-code-sounds --mix              # Jump to sound assignment grid
+npx claude-code-sounds --yes              # Install defaults, skip all prompts
+npx claude-code-sounds --list             # List available themes
+npx claude-code-sounds --mute             # Mute all sounds
+npx claude-code-sounds --unmute           # Unmute all sounds
+npx claude-code-sounds --dnd              # Auto-mute when in video calls
+npx claude-code-sounds --no-dnd           # Disable auto-mute
+npx claude-code-sounds --uninstall        # Remove all sounds and hooks
+npx claude-code-sounds --help             # Show help
+```
+
+## Muting
+
+Mute sounds without uninstalling — three ways:
+
+- **Slash command** (inside Claude Code): type `/mute` or `/unmute`
+- **CLI flag**: `npx claude-code-sounds --mute` or `--unmute`
+- **Interactive menu**: run `npx claude-code-sounds` and select "Mute sounds" / "Unmute sounds"
+
+Muting creates a sentinel file at `~/.claude/sounds/.muted`. The hook script checks for it and exits immediately, so there's zero overhead when muted.
+
+### Do Not Disturb
+
+Sounds are automatically muted when active video calls are detected (Zoom, FaceTime, Webex). This is enabled by default.
+
+Edit `~/.claude/sounds/.dnd` to add or remove app names — one process name per line, `#` for comments.
+
+To disable: `npx claude-code-sounds --no-dnd` or use the interactive menu. Re-enable with `--dnd`.
+
+## Customizing
+
+Re-run with `--mix` to open the sound assignment grid, where you can reassign sounds to hooks, add themes, or preview clips:
+
+```bash
+npx claude-code-sounds --mix
+```
+
+![Sound assignment grid](images/sound-grid.png)
+
+You can also drop any `.wav` or `.mp3` into the sound directories manually:
+
+```
+~/.claude/sounds/
+├── start/        # add files here for session start
+├── stop/         # add files here for response complete
+├── error/        # add files here for failures
+└── ...
+```
+
+The script picks randomly from whatever files are in each directory.
+
+## Uninstalling
+
+```bash
+npx claude-code-sounds --uninstall
+```
+
+This removes all sound files, the hook script, and the hooks config from `settings.json`.
+
+<details>
+<summary><h2 style="display:inline">How It Works</h2></summary>
+
+A single script (`~/.claude/hooks/play-sound.sh`) handles all events. It takes a category name as an argument, picks a random `.wav` or `.mp3` from `~/.claude/sounds/<category>/`, and plays it with `afplay`.
+
+Hooks are configured in `~/.claude/settings.json` — each Claude Code lifecycle event calls the script with the appropriate category.
+
+### Hook Events
 
 | Event | Hook | When |
 |---|---|---|
@@ -89,7 +148,10 @@ Each theme maps sounds across all 11 Claude Code lifecycle events.
 | `compact` | `PreCompact` | Context compaction |
 | `teammate-idle` | `TeammateIdle` | Teammate went idle |
 
-## Creating a Theme
+</details>
+
+<details>
+<summary><h2 style="display:inline">Creating a Theme</h2></summary>
 
 Themes live in `themes/<name>/` with two items:
 
@@ -116,41 +178,7 @@ Defines metadata and maps sound files to hook categories:
 
 Place audio files (`.wav` or `.mp3`) in `themes/<name>/sounds/` with filenames matching the `name` field in `theme.json`.
 
-## How It Works
-
-A single script (`~/.claude/hooks/play-sound.sh`) handles all events. It takes a category name as an argument, picks a random `.wav` or `.mp3` from `~/.claude/sounds/<category>/`, and plays it with `afplay`.
-
-Hooks are configured in `~/.claude/settings.json` — each Claude Code lifecycle event calls the script with the appropriate category.
-
-## Customizing
-
-Re-run with `--mix` to open the sound assignment grid, where you can reassign sounds to hooks, add themes, or preview clips:
-
-```bash
-npx claude-code-sounds --mix
-```
-
-![Sound assignment grid](images/sound-grid.png)
-
-You can also drop any `.wav` or `.mp3` into the sound directories manually:
-
-```
-~/.claude/sounds/
-├── start/        # add files here for session start
-├── stop/         # add files here for response complete
-├── error/        # add files here for failures
-└── ...
-```
-
-The script picks randomly from whatever files are in each directory.
-
-## Uninstalling
-
-```bash
-npx claude-code-sounds --uninstall
-```
-
-This removes all sound files, the hook script, and the hooks config from `settings.json`.
+</details>
 
 ## Disclaimer
 

package/bin/cli.js

@@ -381,6 +381,8 @@ function showHelp() {
     npx claude-code-sounds --list       List available themes
     npx claude-code-sounds --mute       Mute all sounds
     npx claude-code-sounds --unmute     Unmute all sounds
+    npx claude-code-sounds --dnd        Auto-mute when in video calls
+    npx claude-code-sounds --no-dnd     Disable auto-mute
     npx claude-code-sounds --uninstall  Remove all sounds and hooks
     npx claude-code-sounds --help       Show this help
 
@@ -391,6 +393,8 @@ function showHelp() {
     -l, --list          List available themes
         --mute          Mute all sounds
         --unmute        Unmute all sounds
+        --dnd           Auto-mute when in video calls
+        --no-dnd        Disable auto-mute
     -h, --help          Show this help
 `);
 }
@@ -626,14 +630,27 @@ async function interactiveInstall(autoYes) {
   const existing = detectExistingInstall();
 
   if (existing && !autoYes) {
+    const muted = lib.isMuted(paths);
+    const muteStatus = muted ? color.yellow(" (muted)") : "";
     p.log.info(
-      `Already installed — ${color.bold(existing.themeDisplays.join(", "))} (${existing.totalEnabled} sounds enabled)`
+      `Already installed — ${color.bold(existing.themeDisplays.join(", "))} (${existing.totalEnabled} sounds enabled)${muteStatus}`
     );
 
+    const muteOption = muted
+      ? { value: "unmute", label: "Unmute sounds", hint: "Sounds are currently muted" }
+      : { value: "mute", label: "Mute sounds", hint: "Silence sounds without uninstalling" };
+
+    const dnd = lib.isDnd(paths);
+    const dndOption = dnd
+      ? { value: "dnd-off", label: "Disable Do Not Disturb", hint: "Stop auto-muting during calls" }
+      : { value: "dnd-on", label: "Enable Do Not Disturb", hint: "Auto-mute during video calls" };
+
     const action = await p.select({
       message: "What would you like to do?",
       options: [
         { value: "modify", label: "Modify install", hint: "Add themes, change sounds" },
+        muteOption,
+        dndOption,
         { value: "fresh", label: "Fresh install", hint: "Start over from scratch" },
         { value: "uninstall", label: "Uninstall", hint: "Remove all sounds and hooks" },
       ],
@@ -644,6 +661,30 @@ async function interactiveInstall(autoYes) {
       process.exit(0);
     }
 
+    if (action === "mute") {
+      lib.setMuted(true, paths);
+      p.outro("Sounds muted.");
+      return;
+    }
+
+    if (action === "unmute") {
+      lib.setMuted(false, paths);
+      p.outro("Sounds unmuted.");
+      return;
+    }
+
+    if (action === "dnd-on") {
+      lib.setDnd(true, paths);
+      p.outro("Do Not Disturb enabled. Edit ~/.claude/sounds/.dnd to customize.");
+      return;
+    }
+
+    if (action === "dnd-off") {
+      lib.setDnd(false, paths);
+      p.outro("Do Not Disturb disabled.");
+      return;
+    }
+
     if (action === "uninstall") {
       uninstallAll();
       p.outro("All sounds removed.");
@@ -820,6 +861,13 @@ if (flags.has("--help") || flags.has("-h")) {
 } else if (flags.has("--unmute")) {
   lib.setMuted(false, paths);
   console.log("  Sounds unmuted.");
+} else if (flags.has("--dnd")) {
+  lib.setDnd(true, paths);
+  console.log("  Do Not Disturb enabled. Sounds auto-mute when video call apps are detected.");
+  console.log("  Edit ~/.claude/sounds/.dnd to customize the app list.");
+} else if (flags.has("--no-dnd")) {
+  lib.setDnd(false, paths);
+  console.log("  Do Not Disturb disabled.");
 } else if (flags.has("--uninstall") || flags.has("--remove")) {
   p.intro(color.bold("claude-code-sounds"));
   uninstallAll();

package/bin/lib.js

@@ -133,6 +133,41 @@ function setMuted(muted, paths) {
   }
 }
 
+const DND_DEFAULTS = [
+  "# Auto-mute during active calls",
+  "# One process name per line, # for comments",
+  "# Tip: use meeting-specific processes, not main apps (they stay open after calls)",
+  "# Find process names with: pgrep -la <app>",
+  "CptHost",
+  "FaceTime",
+  "Webex",
+];
+
+function isDnd(paths) {
+  return fs.existsSync(path.join(paths.SOUNDS_DIR, ".dnd"));
+}
+
+function setDnd(enabled, paths) {
+  const dndPath = path.join(paths.SOUNDS_DIR, ".dnd");
+  if (enabled) {
+    mkdirp(paths.SOUNDS_DIR);
+    fs.writeFileSync(dndPath, DND_DEFAULTS.join("\n") + "\n");
+    // Ensure the installed hook script supports DND
+    _updateHookScript(paths);
+  } else if (fs.existsSync(dndPath)) {
+    fs.unlinkSync(dndPath);
+  }
+}
+
+function _updateHookScript(paths) {
+  const hookSrc = path.join(paths.PKG_DIR, "hooks", "play-sound.sh");
+  const hookDest = path.join(paths.HOOKS_DIR, "play-sound.sh");
+  if (fs.existsSync(hookDest) && fs.existsSync(hookSrc)) {
+    fs.copyFileSync(hookSrc, hookDest);
+    fs.chmodSync(hookDest, 0o755);
+  }
+}
+
 // ─── Detect Existing Install ─────────────────────────────────────────────────
 
 function detectExistingInstall(paths) {
@@ -230,6 +265,11 @@ function installHooksConfig(paths) {
       }
     }
   }
+
+  // Enable Do Not Disturb by default (auto-mute during video calls)
+  if (!isDnd(paths)) {
+    setDnd(true, paths);
+  }
 }
 
 function uninstallAll(paths) {
@@ -300,6 +340,9 @@ module.exports = {
   writeInstalled,
   isMuted,
   setMuted,
+  DND_DEFAULTS,
+  isDnd,
+  setDnd,
   detectExistingInstall,
   installSounds,
   installHooksConfig,

package/hooks/play-sound.sh

@@ -6,6 +6,15 @@ CATEGORY="${1:-}"
 cat > /dev/null 2>&1
 
 [[ -f "$SOUNDS_DIR/.muted" ]] && exit 0
+
+# Auto-mute: skip when video call apps are running
+if [[ -f "$SOUNDS_DIR/.dnd" ]]; then
+  while IFS= read -r proc || [[ -n "$proc" ]]; do
+    [[ -z "$proc" || "$proc" == \#* ]] && continue
+    pgrep -xi "$proc" > /dev/null 2>&1 && exit 0
+  done < "$SOUNDS_DIR/.dnd"
+fi
+
 [[ -z "$CATEGORY" ]] && exit 0
 DIR="$SOUNDS_DIR/$CATEGORY"
 [[ ! -d "$DIR" ]] && exit 0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-code-sounds",
-  "version": "1.5.3",
+  "version": "1.6.0",
   "description": "Sound themes for Claude Code lifecycle hooks",
   "bin": {
     "claude-code-sounds": "bin/cli.js"