介绍
# 🔔 Webchat Audio Notifications
Moltbot/Clawdbot 网络聊天的浏览器音频通知。当新消息到达时播放提示音——但仅在标签页处于后台时。
## 功能
- 🔔 **智能通知** - 仅在标签页隐藏时播放 - 🎚️ **音量控制** - 可调节 0-100% - 🎵 **5 种强度级别** - 耳语 (1) 到 无法错过 (5) - 📁 **自定义声音** - 上传您自己的文件 (MP3, WAV, OGG, WebM) - 🔕 **一键开关** - 单击启用/禁用 - 💾 **持久化设置** - 偏好设置保存在 localStorage 中 - 📱 **移动端友好** - 在移动端优雅降级 - 🚫 **自动播放处理** - 遵守浏览器策略 - ⏱️ **冷却时间** - 防止刷屏（警报间隔 3 秒） - 🐞 **调试模式** - 可选日志记录
## 快速开始
### 测试 POC
```bash cd examples python3 -m http.server 8080 # Open http://localhost:8080/test.html ```
**测试步骤：** 1. 切换到另一个标签页 2. 点击“触发通知” 3. 听到声音！🔊
### 基础集成
```javascript // 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
### 构造函数选项
```javascript 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 }); ```
**强度级别：** - `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()` - 获取当前设置
## 浏览器兼容性
| 浏览器 | 版本 | 支持 | |---------|---------|---------| | Chrome | 92+ | ✅ 完全支持 | | Firefox | 90+ | ✅ 完全支持 | | Safari | 15+ | ✅ 完全支持 | | Mobile | 最新版 | ⚠️ 有限支持 |
**总体而言：** 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 示例 - 常见模式 (@mentions, DND, badges) - 测试清单
## 配置示例
### 简单
```javascript const notifier = new WebchatNotifications(); await notifier.init(); notifier.notify(); ```
### 高级
```javascript 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(); }); ```
### 带 UI 控件
```html <input type="range" min="0" max="100" onchange="notifier.setVolume(this.value / 100)"> <button onclick="notifier.test()">Test 🔊</button> ```
## 故障排除
**没有声音？** - 先点击页面（自动播放限制） - 检查标签页是否确实处于隐藏状态 - 验证音量 > 0 - 检查控制台是否有错误
**标签页激活时播放声音？** - 启用调试模式 - 检查是否有“Tab is visible, skipping”消息 - 如果缺少该消息，请报告为错误
**移动端不工作？** - iOS 每次播放都需要用户手势 - 考虑视觉回退（闪烁的 favicon）
## 性能
- **打包：** 总共约 122KB（压缩后） - **内存：** 播放期间约 2MB - **CPU：** 可忽略不计（浏览器原生） - **网络：** 一次性下载，已缓存
## 安全性
- ✅ 无外部请求 - ✅ 仅限 localStorage - ✅ 无跟踪 - ✅ 无特殊权限
## 许可证
MIT License
## 致谢
- **音频库：** [Howler.js](https://howlerjs.com/) (MIT) - **声音素材：** [Mixkit.co](https://mixkit.co/) (免版税) - **作者：** @brokemac79 - **致：** [Moltbot/Clawdbot](https://github.com/moltbot/moltbot) 社区
## 贡献
1. 使用 `examples/test.html` 进行测试 2. 启用调试模式 3. 报告问题时请附上浏览器和控制台输出
## 路线图
- [ ] WebM 格式（文件更小） - [ ] 按事件区分声音（提及、私信等） - [ ] 视觉回退（favicon 闪烁） - [ ] 系统通知 API - [ ] 设置 UI 组件 - [ ] 请勿打扰 (DND) 模式
---
**状态：** ✅ v1.1.0 完成 - 5 种强度级别 **已测试：** Chrome, Firefox, Safari **适用于：** 生产环境使用 & ClawdHub 发布
## 链接
- 📖 [README](./README.md) - 完整文档 - 🔧 [集成指南](./docs/integration.md) - 设置说明 - 🧪 [测试页面](./examples/test.html) - 亲自试用 - 💬 [Discord 讨论串](https://discord.com/channels/1456350064065904867/1466181146374307881) - 社区讨论