🔔 Webchat 音频通知

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

功能特性

• - 🔔 智能通知 - 仅在标签页隐藏时播放
• 🎚️ 音量控制 - 可调节 0-100%
• 🎵 5 级强度 - 从低语(1级)到不容错过(5级)
• 📁 自定义音效 - 上传你自己的音频文件(MP3、WAV、OGG、WebM)
• 🔕 一键开关 - 一键启用/禁用
• 💾 持久化设置 - 偏好设置保存在 localStorage 中
• 📱 移动端适配 - 在移动设备上优雅降级
• 🚫 自动播放处理 - 遵循浏览器策略
• ⏱️ 冷却机制 - 防止通知轰炸(警报间隔 3 秒)
• 🐞 调试模式 - 可选日志输出

快速开始

测试概念验证

bash
cd examples
python3 -m http.server 8080

打开 http://localhost:8080/test.html

测试步骤：

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

基础集成

javascript
// 初始化
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

构造函数选项

javascript
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() - 获取当前设置

浏览器兼容性

总体： 92% 的用户(Web Audio API 支持)

文件结构

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 示例
• 常见模式(@提及、勿扰模式、徽章)
• 测试清单

配置示例

简单配置

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

高级配置

javascript
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 控件

html
onchange=notifier.setVolume(this.value / 100)>
测试 🔊

故障排除

没有声音？

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

标签页激活时仍有声音？

• - 启用调试模式
• 检查是否显示标签页可见，跳过消息
• 如果缺失，请报告为 bug

移动端无法工作？

• - iOS 每次播放需要用户手势
• 考虑使用视觉回退(闪烁的网站图标)

性能

• - 打包： 约 122KB 总计(压缩后)
• 内存： 播放时约 2MB
• CPU： 可忽略(浏览器原生)
• 网络： 一次性下载，缓存

安全性

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

许可证

MIT 许可证

致谢

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

贡献

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

路线图

• - [ ] WebM 格式(更小的文件)
• [ ] 按事件区分音效(提及、私信等)
• [ ] 视觉回退(网站图标闪烁)
• [ ] 系统通知 API
• [ ] 设置 UI 组件
• [ ] 勿扰模式

链接

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