🔔 Webchat Audio Notifications

Browser audio notifications for Moltbot/Clawdbot webchat. Plays a notification sound when new messages arrive - but only when the tab is in the background.

Features

• 🔔 Smart notifications - Only plays when tab is hidden
• 🎚️ Volume control - Adjustable 0-100%
• 🎵 5 intensity levels - Whisper (1) to impossible-to-miss (5)
• 📁 Custom sounds - Upload your own (MP3, WAV, OGG, WebM)
• 🔕 Easy toggle - Enable/disable with one click
• 💾 Persistent settings - Preferences saved in localStorage
• 📱 Mobile-friendly - Graceful degradation on mobile
• 🚫 Autoplay handling - Respects browser policies
• ⏱️ Cooldown - Prevents spam (3s between alerts)
• 🐞 Debug mode - Optional logging

Quick Start

Test the POC

cd examples
python3 -m http.server 8080
# Open http://localhost:8080/test.html

Test steps:

1. Switch to another tab
2. Click "Trigger Notification"
3. Hear the sound! 🔊

Basic Integration

// Initialize
const notifier = new WebchatNotifications({
  soundPath: './sounds',
  soundName: 'level3',  // Medium intensity (default)
  defaultVolume: 0.7
});

await notifier.init();

// Trigger on new message
socket.on('message', () => notifier.notify());

// Use different levels for different events
socket.on('mention', () => {
  notifier.setSound('level5');  // Loudest for mentions
  notifier.notify();
});

API

Constructor Options

new WebchatNotifications({
  soundPath: './sounds',               // Path to sounds directory
  soundName: 'level3',                 // level1 (whisper) to level5 (very loud)
  defaultVolume: 0.7,                  // 0.0 to 1.0
  cooldownMs: 3000,                    // Min time between alerts
  enableButton: true,                  // Show enable prompt
  debug: false                         // Console logging
});

Intensity Levels:

• level1 - Whisper (9.5KB) - Most subtle
• level2 - Soft (12KB) - Gentle
• level3 - Medium (13KB) - Default
• level4 - Loud (43KB) - Attention-getting
• level5 - Very Loud (63KB) - Impossible to miss

Methods

• init() - Initialize (call after Howler loads)
• notify(eventType?) - Trigger notification (only if tab hidden)
• test() - Play sound immediately (ignore tab state)
• setEnabled(bool) - Enable/disable notifications
• setVolume(0-1) - Set volume
• setSound(level) - Change intensity ('level1' through 'level5')
• getSettings() - Get current settings

Browser Compatibility

Overall: 92% of users (Web Audio API support)

File Structure