# Claude Code Sound Pack

Geluid bij Claude Code via hooks. Je hoort wanneer Claude klaar is, een fout tegenkomt of je aandacht nodig heeft. Met verwisselbare geluidspakketten, **meerdere willekeurige varianten per moment** en **per terminal een eigen pakket**.

**Platform**: macOS (gebruikt `afplay`)
**Nodig**: Node.js en Claude Code met hooks

---

## Hoe werkt het?

Claude Code roept bij bepaalde gebeurtenissen via een hook een Node.js-script aan. Het script:
1. Leest de gegevens van de gebeurtenis van stdin (het standaard hook-protocol)
2. Kijkt of geluid aanstaat en of deze gebeurtenis actief is
3. Koppelt de gebeurtenis aan een geluid (bijvoorbeeld `Stop` wordt `done`)
4. Houdt een wachttijd aan, zodat snelle bewerkingen niet steeds geluid geven
5. Kiest **willekeurig** uit meerdere varianten als het pakket een lijst heeft
6. Kijkt of `CLAUDE_SOUND_PACK` een ander pakket voor deze terminal opgeeft
7. Speelt het geluid op de achtergrond af met `afplay` en stopt meteen, zodat Claude nooit wacht

### Gebeurtenissen en geluiden

| Hook | Wanneer | Geluid | Standaard (macOS) |
|---|---|---|---|
| `SessionStart` | Sessie start | `ready` | Glass |
| `UserPromptSubmit` | Opdracht verstuurd | `acknowledge` | Pop |
| `PostToolUse` | Edit, Write, MultiEdit | `work` | Tink |
| `PostToolUse` | Bash | `command` | Morse |
| `PostToolUseFailure` | Fout in een tool | `error` | Basso |
| `Stop` | Claude is klaar | `done` | Hero |
| `Notification` | Vraagt toestemming | `alert` | Funk |
| `Notification` | Wacht op jou | `idle` | Submarine |

---

## Installatie

### Stap 1: Mappen aanmaken

```bash
mkdir -p ~/.claude/sounds/packs/system-default
```

### Stap 2: Instellingen (`~/.claude/sounds/soundpack.json`)

```bash
cat > ~/.claude/sounds/soundpack.json << 'EOF'
{
  "version": "1.0.0",
  "enabled": true,
  "activePack": "system-default",
  "volume": 0.5,
  "cooldowns": {
    "global": 300,
    "PostToolUse": 2000,
    "PostToolUseFailure": 1000,
    "UserPromptSubmit": 0,
    "SessionStart": 0,
    "Stop": 0,
    "Notification": 500
  },
  "eventOverrides": {
    "SessionStart": true,
    "UserPromptSubmit": true,
    "PostToolUse": true,
    "PostToolUseFailure": true,
    "Stop": true,
    "Notification": true
  }
}
EOF
```

**Instellingen:**
- `enabled`: hoofdschakelaar (true of false)
- `activePack`: naam van het actieve pakket (de mapnaam in `packs/`)
- `volume`: van 0.0 (stil) tot 1.0 (maximaal)
- `cooldowns`: minimale tijd in milliseconden tussen twee keer hetzelfde geluid
- `eventOverrides`: per gebeurtenis aan of uit (false betekent geen geluid)

### Stap 3: Standaardpakket (`~/.claude/sounds/packs/system-default/pack.json`)

Gebruikt de systeemgeluiden van macOS en werkt dus meteen, zonder downloads:

```bash
cat > ~/.claude/sounds/packs/system-default/pack.json << 'EOF'
{
  "name": "System Default",
  "description": "macOS built-in system sounds",
  "sounds": {
    "ready": "/System/Library/Sounds/Glass.aiff",
    "acknowledge": "/System/Library/Sounds/Pop.aiff",
    "work": "/System/Library/Sounds/Tink.aiff",
    "command": "/System/Library/Sounds/Morse.aiff",
    "error": "/System/Library/Sounds/Basso.aiff",
    "done": "/System/Library/Sounds/Hero.aiff",
    "alert": "/System/Library/Sounds/Funk.aiff",
    "idle": "/System/Library/Sounds/Submarine.aiff"
  }
}
EOF
```

> Alle systeemgeluiden zie je met `ls /System/Library/Sounds/`. Kies gerust andere.

### Stap 4: Hookscript (`~/.claude/sounds/claude-sounds.js`)

```bash
cat > ~/.claude/sounds/claude-sounds.js << 'SCRIPT'
#!/usr/bin/env node
const fs = require('fs');
const path = require('path');
const { spawn } = require('child_process');

const SOUNDS_DIR = path.join(process.env.HOME, '.claude', 'sounds');
const CONFIG_PATH = path.join(SOUNDS_DIR, 'soundpack.json');
const COOLDOWN_PATH = path.join(SOUNDS_DIR, '.cooldown.json');

function mapEventToSound(event, data) {
  const toolName = data.tool_name || '';
  const notificationType = data.notification_type || '';
  switch (event) {
    case 'SessionStart':       return 'ready';
    case 'UserPromptSubmit':   return 'acknowledge';
    case 'PostToolUse':
      if (/^(Edit|Write|MultiEdit|NotebookEdit)$/.test(toolName)) return 'work';
      if (toolName === 'Bash') return 'command';
      return null;
    case 'PostToolUseFailure': return 'error';
    case 'Stop':               return 'done';
    case 'Notification':
      if (notificationType === 'permission_prompt') return 'alert';
      if (notificationType === 'idle_prompt') return 'idle';
      return null;
    default: return null;
  }
}

function checkCooldown(event, config) {
  const now = Date.now();
  let cooldowns = {};
  try { cooldowns = JSON.parse(fs.readFileSync(COOLDOWN_PATH, 'utf8')); } catch {}
  const cooldownMs = Math.max(config.cooldowns?.global || 0, config.cooldowns?.[event] || 0);
  if (now - (cooldowns[event] || 0) < cooldownMs) return false;
  cooldowns[event] = now;
  try { fs.writeFileSync(COOLDOWN_PATH, JSON.stringify(cooldowns)); } catch {}
  return true;
}

function resolveSoundPath(soundName, packName) {
  const packDir = path.join(SOUNDS_DIR, 'packs', packName);
  let pack;
  try { pack = JSON.parse(fs.readFileSync(path.join(packDir, 'pack.json'), 'utf8')); } catch { return null; }
  const soundValue = pack.sounds?.[soundName];
  if (!soundValue) return null;
  // Support arrays: pick a random element
  const fileName = Array.isArray(soundValue)
    ? soundValue[Math.floor(Math.random() * soundValue.length)]
    : soundValue;
  return path.isAbsolute(fileName) ? fileName : path.join(packDir, fileName);
}

function playSound(filePath, volume) {
  if (!fs.existsSync(filePath)) return;
  const child = spawn('afplay', ['--volume', String(volume), filePath], { detached: true, stdio: 'ignore' });
  child.unref();
}

async function main() {
  try {
    const chunks = [];
    for await (const chunk of process.stdin) chunks.push(chunk);
    const input = Buffer.concat(chunks).toString().trim();
    if (!input) process.exit(0);
    const data = JSON.parse(input);
    const event = data.hook_event_name;
    if (!event) process.exit(0);
    let config;
    try { config = JSON.parse(fs.readFileSync(CONFIG_PATH, 'utf8')); } catch { process.exit(0); }
    if (!config.enabled) process.exit(0);
    if (config.eventOverrides?.[event] === false) process.exit(0);
    const soundName = mapEventToSound(event, data);
    if (!soundName) process.exit(0);
    if (!checkCooldown(event, config)) process.exit(0);
    // env var CLAUDE_SOUND_PACK overrides config per terminal
    const activePack = process.env.CLAUDE_SOUND_PACK || config.activePack || 'system-default';
    const soundPath = resolveSoundPath(soundName, activePack);
    if (soundPath) playSound(soundPath, config.volume ?? 0.5);
  } catch {}
  process.exit(0);
}

main();
SCRIPT
```


### Stap 5: Hulpcommando (`~/.claude/sounds/claude-sounds-cli.js`, optioneel)

Het hulpcommando staat niet in deze instructie. Laat Claude Code het schrijven, met deze opdracht:

```text
Maak ~/.claude/sounds/claude-sounds-cli.js: een Node.js-script zonder externe pakketten
dat ~/.claude/sounds/soundpack.json leest en bijwerkt, met deze commando's:
status, enable, disable, toggle, pack <naam>, packs, volume <0.0-1.0>,
test [geluid], event <naam> on|off, init, uninstall <pakket>, help.
Geluiden in pack.json kunnen een naam of een lijst zijn (dan willekeurig kiezen).
Afspelen met afplay, net als claude-sounds.js.
```

| Commando | Wat het doet |
|---|---|
| `status` | Toont de instellingen en het actieve pakket |
| `enable` / `disable` / `toggle` | Geluid aan of uit |
| `pack <naam>` | Wisselt van pakket |
| `packs` | Toont de geinstalleerde pakketten |
| `volume <0.0-1.0>` | Zet het volume |
| `test [geluid]` | Speelt alle geluiden of een enkel geluid af |
| `event <naam> on\|off` | Zet een gebeurtenis aan of uit |
| `init` | Maakt de standaardinstellingen aan |
| `uninstall <pakket>` | Verwijdert een pakket |

### Stap 6: Hooks registreren (`~/.claude/settings.json`)

Voeg de hooks toe aan je `~/.claude/settings.json`. Heb je al hooks, zet deze er dan **naast**:

```json
{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "*",
        "hooks": [
          {
            "type": "command",
            "command": "node \"~/.claude/sounds/claude-sounds.js\"",
            "timeout": 5
          }
        ]
      }
    ],
    "UserPromptSubmit": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "node \"~/.claude/sounds/claude-sounds.js\"",
            "timeout": 5
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Bash|Edit|Write|MultiEdit|NotebookEdit",
        "hooks": [
          {
            "type": "command",
            "command": "node \"~/.claude/sounds/claude-sounds.js\"",
            "timeout": 5
          }
        ]
      }
    ],
    "PostToolUseFailure": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "node \"~/.claude/sounds/claude-sounds.js\"",
            "timeout": 5
          }
        ]
      }
    ],
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "node \"~/.claude/sounds/claude-sounds.js\"",
            "timeout": 5
          }
        ]
      }
    ],
    "Notification": [
      {
        "matcher": "permission_prompt|idle_prompt",
        "hooks": [
          {
            "type": "command",
            "command": "node \"~/.claude/sounds/claude-sounds.js\"",
            "timeout": 5
          }
        ]
      }
    ]
  }
}
```

> **Let op**: vervang `~` door je volledige thuismap (bijvoorbeeld `/Users/jouwnaam`) in settings.json. Claude Code vult geen `~` in bij hook-commando's.

> **Bestaande hooks?** Zet de geluidshooks als extra items in de `hooks`-lijst van elke gebeurtenis. Je bestaande hooks blijven gewoon werken.

### Stap 7: Alias (optioneel)

Zet in `~/.zshrc` of `~/.bashrc`:

```bash
alias claude-sounds='node ~/.claude/sounds/claude-sounds-cli.js'
```

### Stap 8: Testen

```bash
# Moet een geluid geven
echo '{"hook_event_name":"SessionStart"}' | node ~/.claude/sounds/claude-sounds.js

# Herstart Claude Code om de hooks te laden.
# Bij de volgende sessie hoor je een geluid bij de start.
```

---

## Willekeurige varianten

Een pakket kan **meerdere geluiden per moment** hebben, als lijst in `pack.json`. Elke keer kiest het script er willekeurig een. Dat went minder snel.

```json
{
  "name": "Mijn pakket",
  "description": "Meerdere varianten per moment",
  "sounds": {
    "ready": ["hallo-1.aiff", "hallo-2.aiff", "hallo-3.aiff"],
    "error": ["oeps.aiff", "nee.aiff"],
    "done": "klaar.aiff"
  }
}
```

- **Lijst**: willekeurig een geluid uit de lijst
- **Enkele naam**: altijd hetzelfde geluid
- **Combineren**: lijsten en enkele namen mogen in hetzelfde pakket

---

## Eigen pakket maken

Gebruik je eigen opnames, of geluiden waarvan je zeker weet dat je ze mag gebruiken. Geen materiaal uit games, films of series.

### Stap 1: Maak de map

```bash
mkdir -p ~/.claude/sounds/packs/mijn-pakket
```

### Stap 2: Zet er geluiden in

MP3, WAV, AIFF en M4A werken allemaal (alles wat `afplay` afspeelt). Geen opnames bij de hand? Laat je Mac ze inspreken:

```bash
cd ~/.claude/sounds/packs/mijn-pakket
say -v Xander -o klaar-1.aiff "Klaar"
say -v Xander -o klaar-2.aiff "Het staat erin"
say -v Xander -o oeps.aiff "Er ging iets mis"
say -v Xander -o hallo.aiff "Daar gaan we"
```

> Welke stemmen er op je Mac staan, zie je met `say -v '?'`. Je hoeft niet alle acht geluiden te vullen.

| Geluid | Betekenis | Wanneer |
|---|---|---|
| `ready` | Begroeting | Sessie start |
| `acknowledge` | Bevestiging | Opdracht ontvangen |
| `work` | Bezig | Bestand bewerkt |
| `command` | Commando | Bash uitgevoerd |
| `error` | Fout | Tool faalt |
| `done` | Klaar | Claude stopt |
| `alert` | Aandacht | Vraagt toestemming |
| `idle` | Wacht | Wacht op jou |

### Stap 3: Maak pack.json

```json
{
  "name": "Mijn pakket",
  "description": "Eigen stemmen",
  "sounds": {
    "ready": "hallo.aiff",
    "done": ["klaar-1.aiff", "klaar-2.aiff"],
    "error": "oeps.aiff"
  }
}
```

> Geluiden die je niet opgeeft, blijven stil. Er is geen terugval op het standaardpakket.

### Stap 4: Kiezen

Zet in `soundpack.json` `"activePack": "mijn-pakket"`, of met het hulpcommando:

```bash
claude-sounds pack mijn-pakket
claude-sounds test
```

### Tips

- Houd geluiden **kort**, onder de drie seconden
- Kies geluiden die je **zonder te kijken** uit elkaar houdt
- **Drie tot vijf varianten** per moment voorkomt dat het gaat vervelen
- Komen geluiden te snel achter elkaar, verhoog dan de **cooldowns**

---

## Per terminal een ander pakket

Met de omgevingsvariabele `CLAUDE_SOUND_PACK` kies je per terminal een pakket. Die gaat voor `activePack` in de instellingen.

```bash
# Terminal 1
export CLAUDE_SOUND_PACK=system-default
claude

# Terminal 2
export CLAUDE_SOUND_PACK=mijn-pakket
claude
```

Met profielen in iTerm2 kun je elk profiel een eigen variabele geven, bijvoorbeeld een rustig pakket voor werk en een eigen pakket voor de rest.

**Volgorde:**
1. `CLAUDE_SOUND_PACK` (als die gezet is)
2. `activePack` in `soundpack.json`
3. `system-default`

---

## Voorbeelden

### Alleen een geluid als Claude klaar is

```bash
claude-sounds event SessionStart off
claude-sounds event UserPromptSubmit off
claude-sounds event PostToolUse off
claude-sounds event PostToolUseFailure off
claude-sounds event Notification off
# Alleen Stop (done) blijft aan
```

### Alleen als je nodig bent

```bash
claude-sounds event SessionStart off
claude-sounds event UserPromptSubmit off
claude-sounds event PostToolUse off
claude-sounds event PostToolUseFailure on
claude-sounds event Stop on
claude-sounds event Notification on
```

### Volume

```bash
claude-sounds volume 0.3   # rustig
claude-sounds volume 0.7   # goed hoorbaar
```

---

## `/sounds`-skill (optioneel)

Met een eigen opdracht in Claude Code beheer je de geluiden in gewone taal. Maak dit bestand:

**`~/.claude/commands/sounds.md`**:

```markdown
# Sound Pack beheren

Beheer de geluiden van Claude Code. De instellingen staan in ~/.claude/sounds/soundpack.json.

## Commando's
- `node ~/.claude/sounds/claude-sounds-cli.js status`: instellingen tonen
- `node ~/.claude/sounds/claude-sounds-cli.js event <naam> on|off`: gebeurtenis aan of uit
- `node ~/.claude/sounds/claude-sounds-cli.js pack <naam>`: pakket wisselen
- `node ~/.claude/sounds/claude-sounds-cli.js volume <0.0-1.0>`: volume
- `node ~/.claude/sounds/claude-sounds-cli.js test [geluid]`: geluiden testen

## Per terminal
- `export CLAUDE_SOUND_PACK=<pakket>` in de terminal, voor het starten van Claude Code

## Nieuw pakket maken
1. Maak ~/.claude/sounds/packs/<naam>/
2. Gebruik bestanden die de gebruiker aanlevert, of maak ze met `say -o <bestand>.aiff "<tekst>"`
3. Download geen geluiden uit games, films of series
4. Maak pack.json (lijsten voor varianten)
5. Activeer het pakket en speel het af met test

## Geluiden
ready = begroeting, acknowledge = begrepen, work = bezig, command = commando,
error = fout, done = klaar, alert = aandacht nodig, idle = wacht
```

Daarna kun je in Claude Code typen:
- `/sounds`: status tonen
- `/sounds alleen klaar en fouten`: gebeurtenissen instellen
- `/sounds maak een pakket met mijn stem in het Nederlands`: nieuw pakket met `say`
- `/sounds volume 0.3`: volume

---

## Bestanden

```
~/.claude/
├── settings.json                  # Hooks (zelf toevoegen)
├── commands/
│   └── sounds.md                  # /sounds (optioneel)
└── sounds/
    ├── soundpack.json             # Instellingen
    ├── claude-sounds.js           # Hookscript
    ├── claude-sounds-cli.js       # Hulpcommando (optioneel)
    ├── .cooldown.json             # Wachttijden (wordt vanzelf aangemaakt)
    └── packs/
        ├── system-default/
        │   └── pack.json          # Systeemgeluiden van macOS
        └── mijn-pakket/           # Eigen pakket
            ├── pack.json
            ├── hallo.aiff
            ├── klaar-1.aiff
            ├── klaar-2.aiff
            └── oeps.aiff
```

---

## Problemen oplossen

**Geen geluid bij het starten van een sessie?**
- Herstart Claude Code nadat je de hooks hebt toegevoegd
- Test met de hand: `echo '{"hook_event_name":"SessionStart"}' | node ~/.claude/sounds/claude-sounds.js`
- Controleer of het pad in settings.json volledig is (geen `~`)

**Geluid speelt niet af?**
- Bestaat het bestand? Probeer `claude-sounds test`
- Staat het volume niet op 0? Kijk met `claude-sounds status`
- Staat de gebeurtenis aan in `eventOverrides`?
- Werkt `afplay`? Probeer `afplay /System/Library/Sounds/Glass.aiff`

**Te veel geluid?**
- Verhoog de cooldowns in `soundpack.json` (in milliseconden)
- Zet drukke gebeurtenissen uit: `claude-sounds event PostToolUse off`

**Pakket per terminal werkt niet?**
- Is de variabele gezet? `echo $CLAUDE_SOUND_PACK`
- Bestaat de map `~/.claude/sounds/packs/<naam>/` met een `pack.json`?
- De variabele moet gezet zijn **voordat** je Claude Code start

**Hooks werken niet?**
- Is `~/.claude/settings.json` geldige JSON? `node -e "JSON.parse(require('fs').readFileSync('$HOME/.claude/settings.json'))"`
- Klopt het pad naar `claude-sounds.js`?
- Herstart Claude Code na een wijziging

---

## Technische details

- **Geen externe pakketten**: alleen Node.js zelf (fs, path, child_process), geen npm install
- **Blokkeert niet**: het script start `afplay` los en stopt meteen
- **Faalt stil**: een kapot geluidsbestand of instelling breekt niets
- **Altijd actueel**: instellingen en wachttijden worden bij elke aanroep opnieuw gelezen
- **Varianten**: geluiden in `pack.json` zijn een naam of een lijst (willekeurig)
- **Per terminal**: `CLAUDE_SOUND_PACK` gaat voor `activePack`
- **Alleen macOS**: gebruikt `afplay`. Op Linux kun je `aplay` of `paplay` gebruiken, op Windows `powershell -c (New-Object Media.SoundPlayer 'file.wav').PlaySync()`
