webchat-audio-notifications

name	webchat-audio-notifications
description	Add browser audio notifications to Moltbot/Clawdbot webchat with 5 intensity levels - from whisper to impossible-to-miss (only when tab is backgrounded).
version	1.1.0
author	brokemac79
repository	https://github.com/brokemac79/webchat-audio-notifications
homepage	https://github.com/brokemac79/webchat-audio-notifications
tags	["webchat","notifications","audio","ux","browser","howler"]
metadata	{"clawdbot":{"emoji":"🔔","compatibility":{"minVersion":"2026.1.0","browsers":["Chrome 92+","Firefox 90+","Safari 15+","Edge 92+"]},"dependencies":["howler.js (included)"],"files":["client/howler.min.js","client/notification.js","client/sounds/notification.mp3","client/sounds/alert.mp3"],"install":[{"kind":"manual","label":"Install webchat audio notifications","instructions":"1. Copy files to your webchat directory:\n - client/howler.min.js → /webchat/js/\n - client/notification.js → /webchat/js/\n - client/sounds/ → /webchat/sounds/\n\n2. Add to your webchat HTML before closing </body>:\n\n```html\n<script src=\"/js/howler.min.js\"></script>\n<script src=\"/js/notification.js\"></script>\n<script>\n const notifier = new WebchatNotifications({\n soundPath: '/sounds/notification'\n });\n notifier.init();\n</script>\n```\n\n3. Hook into message events:\n\n```javascript\nsocket.on('message', () => {\n if (notifier) notifier.notify();\n});\n```\n\n4. Test by switching tabs and triggering a message\n\nSee docs/integration.md for full guide.\n"}]}}

🔔 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(,  {
  notifier.();  
  notifier.();
});