🔔 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

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

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 - Full documentation

• 🔧 Integration Guide - Setup instructions

• 🧪 Test Page - Try it yourself

• 💬 Discord Thread - Community discussion