---
title: Sounds
description: Hear when venom is done, failed or needs approval, pick or replace the sounds, set quiet hours and choose the player.
section: plugins
order: 50
audience: [user]
sources: [docs/hooks.md, packages/harness/src/notify/sounds.ts, packages/harness/src/notify/player.ts, cli/src/sounds.ts]
features: [plugins.sounds]
---

The TUI plays a sound for venom's events out of the box, so you know when to look at the terminal. The built-in sounds are synthesized in code (no recordings, nothing downloaded) and cached as small WAV files in `~/.venom/cache/sounds/` the first time they play. Only the TUI plays sounds: `venom -p`, `venom serve` and `venom acp` do not (hooks still run).

## Quick start

```bash
venom sounds list                 # the built-ins, your settings, the player venom will use
venom sounds list --play chime    # preview one
```

In a session: `/sounds` lists them, previews the one you pick and mutes or unmutes; `/sounds play <name|path|event>` previews; `/sounds mute`, `/sounds unmute` and `/sounds toggle` apply to this session. The leader then `n` (`ctrl+g n`) toggles mute.

## Configuration {#config}

```yaml
sounds:
  enabled: true
  volume: 0.6
  only_when_unfocused: true
  quiet_hours: "22:00-08:00"
  min_turn_seconds: 5
  events:
    main_agent_done: chime
    subagent_done: tick
    step_done: off
    permission_needed: attention
    agent_failed: ~/sounds/sad-trombone.mp3
    schedule_done: done
```

| Key | Type | Default | What |
|---|---|---|---|
| `sounds` | object | | the section |
| `sounds.enabled` | boolean | `true` | `false` turns every event sound off |
| `sounds.volume` | number 0 to 1 | `0.6` | playback volume |
| `sounds.only_when_unfocused` | boolean | `true` | play only while the terminal is in the background |
| `sounds.quiet_hours` | `"HH:MM-HH:MM"` | none | local time, may wrap midnight; no sounds inside it |
| `sounds.min_turn_seconds` | number | `5` | no `main_agent_done` sound for a run shorter than this (an error always sounds) |
| `sounds.events` | object | below | a built-in name, an absolute path (`~/` works) or `off`, per event |
| `sounds.events.main_agent_done` | string | `chime` | `MainAgentDone` |
| `sounds.events.subagent_done` | string | `tick` | `SubagentDone` |
| `sounds.events.step_done` | string | `off` | `StepDone` (`pop` is a good choice) |
| `sounds.events.permission_needed` | string | `attention` | `PermissionNeeded` |
| `sounds.events.agent_failed` | string | `failure` | `AgentFailed` |
| `sounds.events.schedule_done` | string | `done` | `ScheduleDone` |

| Environment variable | What |
|---|---|
| `VENOM_SOUND_PLAYER` | your own player command (`mpv --no-video`, `ffplay -nodisp -autoexit`); the file path is appended |

A [hook](/docs/plugins/hooks.md) with `sound:` plays a sound for a narrower case, for example one sound per subagent role.

## Built-in sounds

| Name | Sound | Default for |
|---|---|---|
| `chime` | a clear two-note chime (1.2 s) | main agent done |
| `tick` | a soft tick (0.07 s) | subagent done |
| `attention` | two gentle pulses (0.5 s) | permission needed |
| `failure` | a low falling two-tone (0.7 s) | agent failed |
| `done` | a short rising two-tone | schedule done |
| `pop` | a quick pop (0.1 s) | |
| `bell` | a small bell with a long ring | |
| `hiss` | a cobra's hiss | |
| `success` | a rising major arpeggio | |
| `marimba` | a woody descending pair | |

Your own sounds: any audio file by absolute path (`.wav`, `.mp3`, `.aiff`, `.m4a`, `.ogg`, `.flac`); what plays depends on the player.

## Playback per platform

| Where | How |
|---|---|
| macOS | `afplay` (wav, aiff, mp3, m4a) |
| Linux | the first of `pw-play`, `paplay`, `aplay` (wav only) on PATH |
| WSL, Windows | `powershell.exe` with `Media.SoundPlayer` (wav only) |
| over ssh (`SSH_CONNECTION`, `SSH_CLIENT`, `SSH_TTY`) or no player found | the terminal bell, plus a desktop notification escape where the terminal supports one (OSC 9, 777 or 99) |

The player runs detached, never blocks the agent, and is killed after 10 seconds. A missing player or a broken file is silent.

## When a sound does not play

Sounds are off or muted for the session, the event is `off`, the volume is 0, it is quiet hours, the terminal has focus (with `only_when_unfocused`), a `MainAgentDone` run was shorter than `min_turn_seconds`, or you stopped the run with Esc.

Focus detection asks the terminal for focus reports (`CSI ?1004h`). iTerm2, Ghostty, kitty, WezTerm, Alacritty, foot, Windows Terminal, VS Code and tmux with `focus-events on` send them. A terminal that sends none counts as unfocused, so you still hear sounds.

## Related

- [Hooks and venom's events](/docs/plugins/hooks.md)
