Introduction
# 🔔 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
```bash 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
```javascript // 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
```javascript 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
```javascript const notifier = new WebchatNotifications(); await notifier.init(); notifier.notify(); ```
### Advanced
```javascript 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
```html <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](https://howlerjs.com/) (MIT) - **Sounds:** [Mixkit.co](https://mixkit.co/) (Royalty-free) - **Author:** @brokemac79 - **For:** [Moltbot/Clawdbot](https://github.com/moltbot/moltbot) community
## Contributing
1. Test with `examples/test.html` 2. Enable debug mode 3. 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
## Links
- 📖 [README](./README.md) - Full documentation - 🔧 [Integration Guide](./docs/integration.md) - Setup instructions - 🧪 [Test Page](./examples/test.html) - Try it yourself - 💬 [Discord Thread](https://discord.com/channels/1456350064065904867/1466181146374307881) - Community discussion