webchat-audio-notifications

# 🔔 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 (12...

# 🔔 Webchat Audio Notifications

Browser audio notifications for Moltbot/Clawdbot webchat. Get notified when new messages arrive - but only when the tab is in the background.

**🧪 [Try the live demo](examples/test.html)** - Download and open in your browser!

**Status:** ✅ v1.2.0 - Production ready, looking for testers!

---

## 🚀 Quick Test (2 minutes)

**Want to try it right now?**

1. **Clone or download** this repo
2. **Open** `examples/test.html` in your browser
3. **Click** the green "🔊 Test Sound" button (unlocks audio)
4. **Hear** the notification sound!
5. **Try** different intensity levels (Level 1-5 dropdown)

That's it! If you hear sounds, it works. 🎉

### ⚠️ Important: Browser Autoplay Policy

**Why you must click "Test Sound" first:**

All modern browsers (Chrome, Firefox, Safari, Edge) **block audio autoplay by default** as a security feature. This prevents websites from playing sounds without your permission.

**This is NORMAL and EXPECTED behavior, not a bug!**

**What happens:**
1. Page loads → Audio is blocked 🔇
2. You click "Test Sound" (or any button) → Audio unlocks 🔊
3. From now on, notifications work automatically ✅

**You only need to click once per session.** After that, all sounds play normally. This is how all web audio works - YouTube, Spotify, etc. all require a click first.

If you don't click first and don't hear sounds, that's why! Just click the Test Sound button.

---

## ✨ Features

- 🔔 **Smart notifications** - Only plays sound when tab is hidden
- 🎚️ **Volume control** - Adjustable notification volume (0-100%)
- 🔕 **Easy toggle** - Enable/disable with one click
- 🎵 **5 intensity levels** - From whisper (level 1) to impossible-to-miss (level 5)
- 📁 **Custom sounds** - Upload your own notification sounds (MP3, WAV, OGG, WebM)
- 💾 **Persistent preferences** - Settings saved in localStorage
- 📱 **Mobile-friendly** - Graceful handling of mobile restrictions
- 🚫 **Autoplay handling** - Respects browser autoplay polici...