Webchat Audio Notifications

Add browser audio notifications to Moltbot/Clawdbot webchat with 5 intensity levels - from whisper to impossible-to-miss (only when tab is backgrounded).

Security Scan

The skill's code, installation steps, and runtime instructions are consistent with its stated purpose (client-side browser audio notifications) and do not request unrelated credentials or elevated system access.

Purpose & Capability

Name/description, SKILL.md install steps, and included files (notification.js, howler, sounds, examples, docs) all match: a client-side webchat audio notifier. No unrelated binaries, env vars, or cloud credentials are requested.

Instruction Scope

Runtime instructions are limited to copying client files into your webchat, loading scripts, initializing the notifier, and hooking into message events. One note: config-loader.js fetches a JSON config from a configurable path (default local path) — if misconfigured to point at an external URL it could pull remote config, so ensure configPath is local/trusted.

Install Mechanism

No automated installer; manual copy of static client files is required. All code is included (Howler is vendored). No downloads from unknown URLs or archive extraction are performed by the skill itself.

Credentials

Skill requires no environment variables, no credentials, and no config paths. It uses browser APIs and localStorage for persisting settings and for storing uploaded custom sounds (base64). These are proportionate to a browser notification feature.

Persistence & Privilege

Skill is not always-enabled, does not request persistent system-wide privileges, and does not modify other skills' configs. It stores settings and optional custom sound data in the browser's localStorage (expected for this feature).

Assessment

This package appears coherent and client-side only, but before installing: 1) host the client files (howler.min.js, notification.js, sounds) on your own webserver—do not reference remote/third-party URLs; 2) review client/notification.js for any unexpected network requests (the code uses fetch only for a configurable local config file by default); 3) note custom sound uploads are stored in localStorage as base64 (size limited and stored per-browser); 4) test in a staging environment to confirm autoplay-handling UX and that no unexpected network traffic occurs; 5) verify licensing (MIT) and the howler.js version for compatibility. If you want extra assurance, run the example pages locally and inspect network traffic in DevTools during tests.

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

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

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