Source Code

🔔 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:

Switch to another tab
Click "Trigger Notification"
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

Browser	Version	Support
Chrome	92+	✅ Full
Firefox	90+	✅ Full
Safari	15+	✅ Full
Mobile	Latest	⚠️ Limited

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

File Structure

webchat-audio-notifications/
├── client/
│   ├── notification.js       # Main class (10KB)
│   ├── howler.min.js         # Audio library (36KB)
│   └── sounds/
│       ├── level1.mp3        # Whisper (9.5KB)
│       ├── level2.mp3        # Soft (12KB)
│       ├── level3.mp3        # Medium (13KB, default)
│       ├── level4.mp3        # Loud (43KB)
│       └── level5.mp3        # Very Loud (63KB)
├── examples/
│   └── test.html            # Standalone test with all levels
├── docs/
│   └── integration.md       # Integration guide
└── README.md                # Full documentation

Integration Guide

See docs/integration.md for:

Step-by-step setup
Moltbot-specific hooks
React/Vue examples
Common patterns (@mentions, DND, badges)
Testing checklist

Configuration Examples

Simple

const notifier = new WebchatNotifications();
await notifier.init();
notifier.notify();

Advanced

const notifier = new WebchatNotifications({
  soundPath: '/assets/sounds',
  soundName: 'level2',  // Start with soft
  defaultVolume: 0.8,
  cooldownMs: 5000,
  debug: true
});

await notifier.init();

// Regular messages = soft
socket.on('message', () => {
  notifier.setSound('level2');
  notifier.notify();
});

// Mentions = very loud
socket.on('mention', () => {
  notifier.setSound('level5');
  notifier.notify();
});

// DMs = loud
socket.on('dm', () => {
  notifier.setSound('level4');
  notifier.notify();
});

With UI Controls

<input type="range" min="0" max="100" 
       onchange="notifier.setVolume(this.value / 100)">
<button onclick="notifier.test()">Test 🔊</button>

Troubleshooting

No sound?

Click page first (autoplay restriction)
Check tab is actually hidden
Verify volume > 0
Check console for errors

Sound plays when tab active?

Enable debug mode
Check for "Tab is visible, skipping" message
Report as bug if missing

Mobile not working?

iOS requires user gesture per play
Consider visual fallback (flashing favicon)

Performance

Bundle: ~122KB total (minified)
Memory: ~2MB during playback
CPU: Negligible (browser-native)
Network: One-time download, cached

Security

✅ No external requests
✅ localStorage only
✅ No tracking
✅ No special permissions

License

MIT License

Credits

Audio library: Howler.js (MIT)
Sounds: Mixkit.co (Royalty-free)
Author: @brokemac79
For: Moltbot/Clawdbot community

Contributing

Test with examples/test.html
Enable debug mode
Report issues with browser + console output

Roadmap

WebM format (smaller files)
Per-event sounds (mention, DM, etc.)
Visual fallback (favicon flash)
System notifications API
Settings UI component
Do Not Disturb mode

Status: ✅ v1.1.0 Complete - 5 Intensity Levels
Tested: Chrome, Firefox, Safari
Ready for: Production use & ClawdHub publishing

webchat-audio-notifications