📦 Webchat Audio Notifications — 浏览器音频通知

Moltbot/Clawdbot webchat 的浏览器音频通知。当新消息到达时播放通知声音——但仅在标签页处于后台时播放。

功能特点

• 🔔 智能通知 - 仅在标签页隐藏时播放
• 🎚️ 音量控制 - 可调节 0-100%
• 🎵 5 种强度级别 - 耳语 (1) 到 无法忽视 (5)
• 📁 自定义声音 - 上传您自己的音频 (MP3, WAV, OGG, WebM)
• 🔕 轻松切换 - 一键启用/禁用
• 💾 设置持久化 - 首选项保存在 localStorage 中
• 📱 移动端友好 - 在移动端优雅降级
• 🚫 自动播放处理 - 遵守浏览器策略
• ⏱️ 冷却时间 - 防止刷屏（每次提醒间隔 3 秒）
• 🐞 调试模式 - 可选日志记录

快速开始

测试 POC

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

测试步骤：

• 切换到另一个标签页
• 点击"触发通知"
• 听到声音了！🔊

基础集成

// 初始化
const notifier = new WebchatNotifications({
  soundPath: './sounds',
  soundName: 'level3', // 中等强度（默认）
  defaultVolume: 0.7
});
await notifier.init();
// 新消息时触发
socket.on('message', () => notifier.notify());
// 不同事件使用不同级别
socket.on('mention', () => {
  notifier.setSound('level5'); // 提及时使用最大音量
  notifier.notify();
});

API

构造函数选项

new WebchatNotifications({
  soundPath: './sounds', // 声音文件目录路径
  soundName: 'level3', // level1（耳语）到 level5（非常响）
  defaultVolume: 0.7, // 0.0 到 1.0
  cooldownMs: 3000, // 两次提醒之间的最小时间
  enableButton: true, // 显示启用提示
  debug: false // 控制台日志
});

强度级别：

• level1 - 耳语 (9.5KB) - 最低调
• level2 - 轻柔 (12KB) - 温和
• level3 - 中等 (13KB) - 默认
• level4 - 响亮 (43KB) - 引人注意
• level5 - 非常响 (63KB) - 无法忽视

方法

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

浏览器兼容性

文件结构

webchat-audio-notifications/
├── client/
│   ├── notification.js # 主类 (10KB)
│   ├── howler.min.js # 音频库 (36KB)
│   └── sounds/
│       ├── level1.mp3 # 耳语 (9.5KB)
│       ├── level2.mp3 # 轻柔 (12KB)
│       ├── level3.mp3 # 中等 (13KB, 默认)
│       ├── level4.mp3 # 响亮 (43KB)
│       └── level5.mp3 # 非常响 (63KB)
├── examples/
│   └── test.html # 独立测试页面，包含所有级别
├── docs/
│   └── integration.md # 集成指南
└── README.md # 完整文档

集成指南

详见 docs/integration.md：

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

配置示例

简单配置

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

高级配置

const notifier = new WebchatNotifications({
  soundPath: '/assets/sounds',
  soundName: 'level2', // 从轻柔开始
  defaultVolume: 0.8,
  cooldownMs: 5000,
  debug: true
});
await notifier.init();
// 普通消息 = 轻柔
socket.on('message', () => {
  notifier.setSound('level2');
  notifier.notify();
});
// 提及 = 非常响
socket.on('mention', () => {
  notifier.setSound('level5');
  notifier.notify();
});
// 私信 = 响亮
socket.on('dm', () => {
  notifier.setSound('level4');
  notifier.notify();
});

带 UI 控件

测试 🔊

故障排除

没有声音？

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

标签页激活时也播放声音？

• 启用调试模式
• 检查"Tab is visible, skipping"消息
• 如果缺失则报告 bug

移动端不工作？

• iOS 每次播放都需要用户手势
• 考虑视觉回退方案（闪烁 favicon）

性能

• 打包大小： 约 122KB（压缩后）
• 内存： 播放期间约 2MB
• CPU： 可忽略（浏览器原生）
• 网络： 一次性下载，缓存

安全性

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

许可证

MIT 许可证

致谢

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

贡献指南

• 使用 examples/test.html 测试
• 启用调试模式
• 报告问题时附上浏览器和控制台输出

路线图

• [ ] WebM 格式（更小的文件）
• [ ] 每事件独立声音（提及、私信等）
• [ ] 视觉回退（favicon 闪烁）
• [ ] 系统通知 API
• [ ] 设置 UI 组件
• [ ] 勿扰模式

状态： ✅ v1.1.0 完成 - 5 种强度级别

已测试： Chrome、Firefox、Safari

可用于： 生产环境使用和 ClawdHub 发布

相关链接

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