Ambient Sound

The ambient sound system provides audio notifications when Claude Code sessions require attention. This helps users manage multiple sessions without constantly monitoring the screen.

Overview

Ambient sound activates when:

1. A session enters a waiting or idle state
2. The state persists beyond a configurable threshold
3. Sound is enabled for that session

The system supports two audio sources:

• Generated sounds: Web Audio API synthesized ambient tones
• Ambient music: Pre-recorded audio files

Threshold Pool Architecture

The sound system uses a threshold pool to manage multiple sessions:

Session A (waiting 45s) ─┐
                         ├─> Threshold Pool ─> Play Sound
Session B (waiting 60s) ─┘

Session C (active) ────────> Not in pool

Sessions enter the pool when:

• They are in waiting or idle state
• The state has persisted beyond the configured threshold
• Sound notifications are enabled for that state

Sound plays when the pool is non-empty and stops when the pool empties.

Configuration Options

Per-Session Settings

Each session can be configured independently:

Setting	Default	Description
waitEnabled	true	Play sound when waiting for user response
idleEnabled	false	Play sound when idle
waitThresholdSeconds	30	Seconds before wait sound triggers
idleThresholdSeconds	90	Seconds before idle sound triggers
volume	0.5	Volume level (0.0 to 1.0)
preferMusic	true	Use music instead of generated sounds

Global Settings

Setting	Default	Description
masterEnabled	true	Master switch for all sounds
stopMode	'any'	When to stop: 'any' active session or 'all' active
syncSessions	true	Synchronize sound across sessions

Stop Modes

The stopMode setting controls when sound stops:

Mode: 'any' (Default)

Sound stops when any session becomes active:

Session A: waiting ─> active   = Stop sound
Session B: waiting             (still waiting)

This is useful when you want immediate feedback that something needs attention.

Mode: 'all'

Sound continues until all sessions are active:

Session A: waiting ─> active   = Continue sound
Session B: waiting             (still waiting)
Session B: waiting ─> active   = Stop sound

This ensures you address all waiting sessions.

Sound Types

Generated Sounds

The AmbientSoundGenerator creates Web Audio API synthesized sounds:

• Wait sound: Gentle pulsing tone indicating attention needed
• Idle sound: Soft ambient drone for background awareness

Generated sounds work offline and have no external dependencies.

Ambient Music

Pre-recorded audio files provide a more musical notification:

• Located in app/public/sounds/
• Supports MP3 format
• Loops continuously while conditions are met

Music requires the audio files to be present in the deployment.

API Usage

Updating Session Configuration

import { ambientSoundManager } from './lib/ambientSound';

ambientSoundManager.updateSessionConfig('my-session', {
  waitEnabled: true,
  waitThresholdSeconds: 20,
  volume: 0.7
});

Reporting Status Changes

ambientSoundManager.updateSessionStatus('my-session', claudeStatus);

Emergency Stop

Stop all sounds immediately:

ambientSoundManager.emergencyStop();

This clears the threshold pool and prevents sound restart for a cooldown period.

Getting Playback Information

const info = ambientSoundManager.getPlayingInfo();
// {
//   isPlaying: true,
//   poolSessions: ['session-a', 'session-b'],
//   playingSessions: ['session-a', 'session-b'],
//   poolSize: 2,
//   inCooldown: false,
//   cooldownRemaining: 0
// }

UI Integration

The SoundSettings component provides user controls:

• Toggle switches for wait/idle notifications
• Slider for threshold duration
• Volume control
• Music vs generated sound selection
• Emergency stop button

Access settings by clicking the gear icon on a session card.

Troubleshooting

Sound Not Playing

1. Check browser autoplay policy - user interaction may be required first
2. Verify masterEnabled is true
3. Confirm the session state matches enabled settings
4. Check if emergency stop cooldown is active

Sound Not Stopping

1. Verify stopMode matches expected behavior
2. Check that the session actually became active (not just a brief state change)
3. Use emergency stop to force silence

Audio Quality Issues

1. Adjust volume settings
2. For generated sounds, check Web Audio API support
3. For music, verify audio files are properly loaded

Browser Compatibility

The ambient sound system requires:

• Web Audio API support
• HTML5 Audio element support
• User gesture for initial audio playback (browser autoplay policy)

All modern browsers (Chrome, Firefox, Safari, Edge) support these features.