🔔 网页聊天音频通知

Moltbot/Clawdbot网页聊天的浏览器音频通知。当新消息到达时播放提示音——但仅在标签页处于后台时生效。

功能特性

• 🔔智能通知- 仅在标签页隐藏时播放
• 🎚️音量控制- 可调节范围0-100%
• 🎵5级强度调节- 从轻声提示(1)到不容错过(5)
• 📁自定义提示音- 支持上传自定义音频（MP3、WAV、OGG、WebM格式）
• 🔕快捷开关- 一键启用/禁用
• 💾设置持久化- 偏好设置保存于本地存储
• 📱移动端适配- 移动端优雅降级
• 🚫自动播放处理- 遵循浏览器策略
• ⏱️冷却时间- 防止骚扰（警报间隔3秒）
• 🐞调试模式- 可选日志记录

快速开始

测试概念验证

cd examples
python3 -m http.server 8080
# Open http://localhost:8080/test.html

测试步骤：

1. 切换到另一个标签页
2. 点击"触发通知"
3. 听到声音！ 🔊

基本集成

// 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

构造函数选项

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

强度等级：

• 等级1- 耳语（9.5KB）- 最轻微
• 等级2- 柔和（12KB）- 温和
• 等级3- 中等（13KB）- 默认
• 等级4- 响亮（43KB）- 引人注意
• 等级5- 非常响亮（63KB）- 不容错过

方法

• init()- 初始化（在Howler加载后调用）
• notify(eventType?)- 触发通知（仅当标签页隐藏时）
• test()- 立即播放声音（忽略标签页状态）
• setEnabled(bool)- 启用/禁用通知
• setVolume(0-1)- 设置音量
• setSound(level)- 更改强度（从'level1'到'level5'）
• getSettings()- 获取当前设置

浏览器兼容性

总体情况：92% 的用户（支持 Web Audio API）

文件结构

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

集成指南

请参阅docs/integration.md以了解：

• 分步设置说明
• Moltbot 特定钩子
• React/Vue 示例
• 常见模式（@提及、拖放、徽章）
• 测试清单

配置示例

简单配置

const notifier = new WebchatNotifications();
await notifier.init();
notifier.notify();

高级

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

带界面控制

<input type="range" min="0" max="100" 
       onchange="notifier.setVolume(this.value / 100)">
<button onclick="notifier.test()">Test 🔊</button>

故障排除

没有声音？

• 先点击页面（自动播放限制）
• 检查标签页是否确实被隐藏
• 确认音量 > 0
• 检查控制台是否有错误

标签页激活时有声音吗？

• 启用调试模式
• 检查是否有"标签页可见，跳过"消息
• 若无则报告为错误

移动端不工作？

• iOS每次播放都需要用户手势
• 考虑视觉后备方案（闪烁网站图标）

性能

• 捆绑包：总计约122KB（已压缩）
• 内存：播放期间约2MB
• CPU：可忽略（浏览器原生支持）
• 网络：一次性下载，缓存

安全性

• ✅ 无外部请求
• ✅ 仅使用 localStorage
• ✅ 无追踪
• ✅ 无需特殊权限

许可证

MIT 许可证

鸣谢

• 音频库： Howler.js(MIT)
• 音效： Mixkit.co(免版税)
• 作者：@brokemac79
• 为： Moltbot/Clawdbot社区

贡献指南

1. 使用以下文件测试：examples/test.html
2. 启用调试模式
3. 报告问题时请附上浏览器及控制台输出信息

路线图

• WebM格式（文件更小）
• 事件专属提示音（提及、私信等）
• 视觉后备方案（网站图标闪烁）
• 系统通知API
• 设置界面组件
• 勿扰模式

状态：✅ v1.1.0 已完成 - 5级强度调节
已测试：Chrome、Firefox、Safari
准备就绪：生产环境使用 & ClawdHub发布

链接

• 📖README- 完整文档
• 🔧集成指南- 设置说明
• 🧪测试页面- 亲自试用
• 💬Discord讨论串- 社区讨论