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

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

Test 🔊

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

Links

• 📖 README - Full documentation
• 🔧 Integration Guide - Setup instructions
• 🧪 Test Page - Try it yourself
• 💬 Discord Thread - Community discussion