🔔 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
Test steps:
- Switch to another tab
- Click "Trigger Notification"
- Hear the sound! 🔊
Basic Integration
const notifier = new WebchatNotifications({
soundPath: './sounds',
soundName: 'level3',
defaultVolume: 0.7
});
await notifier.init();
socket.on('message', () => notifier.notify());
socket.on('mention', () => {
notifier.setSound('level5');
notifier.notify();
});
API
Constructor Options
new WebchatNotifications({
soundPath: './sounds',
soundName: 'level3',
defaultVolume: 0.7,
cooldownMs: 3000,
enableButton: true,
debug: false
});
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',
defaultVolume: 0.8,
cooldownMs: 5000,
debug: true
});
await notifier.init();
socket.on('message', () => {
notifier.setSound('level2');
notifier.notify();
});
socket.on('mention', () => {
notifier.setSound('level5');
notifier.notify();
});
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
Contributing
- Test with
examples/test.html
- Enable debug mode
- Report issues with browser + console output
Roadmap
Status: ✅ v1.1.0 Complete - 5 Intensity Levels
Tested: Chrome, Firefox, Safari
Ready for: Production use & ClawdHub publishing
Links