🎁 Get the FREE AI Skills Starter Guide β€” Subscribe β†’
BytesAgainBytesAgain
BytesAgain β€Ί Skills β€Ί Webchat Audio Notifications
πŸ¦€ ClawHub

Webchat Audio Notifications

by @brokemac79

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

Versionv1.2.0
Downloads2,843
Installs5
Stars⭐ 1
#audio#legal#communication
TERMINAL
clawhub install webchat-audio-notifications

πŸ“– About This Skill

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: - client/howler.min.js β†’ /webchat/js/ - client/notification.js β†’ /webchat/js/ - client/sounds/ β†’ /webchat/sounds/ 2. Add to your webchat HTML before closing :
3. Hook into message events: 
          socket.on('message', () => {
            if (notifier) notifier.notify();
          });
4. Test by switching tabs and triggering a message See docs/integration.md for full guide.

πŸ”” 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

    | 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

    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

    • πŸ’‘ Examples

    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();
});

    πŸ“‹ Tips & Best Practices

    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)