Audio Announcement

# Audio Announcement Skill 🦊

Safety Notice

This listing is from the official public ClawHub registry. Review SKILL.md and referenced scripts before running.

Copy this and send it to your AI assistant to learn

Install skill "Audio Announcement" with this command: npx skills add wililam/audio-announcement

Audio Announcement Skill 🦊

让 OpenClaw 开口说话，实时播报 AI 的一举一动！

概述

这是一个语音播报技能，可以让你的 AI 代理通过语音实时告诉你它在做什么。就像一只爱说话的龙虾，让你更清楚、更安心地知道 AI 的当前状态。

版本: 2.0.8
状态: ✅ 生产就绪
安装: clawhub install audio-announcement 或 pip install audio-announcement

🎯 最新更新 (v2.0.8 - 2026-04-05)

  • ✅ 播报本地化 - 所有播报仅在本机后台播放，不发送语音文件到聊天界面
  • ✅ 统一包装脚本 - 新增 scripts/announce.py，自动解析 skill 路径，避免硬编码
  • ✅ 默认音量优化 - 配置文件默认 volume: 0.1（10%），保护听力避免打扰
  • ✅ CLI 工具修复 - 修复 pygame 导入问题，提升 Windows 稳定性
  • ✅ 文档全面升级 - MEMORY.md / AGENTS.md / TOOLS.md 统一管理播报工作流
  • ✅ 会话复盘机制 - 建立复盘流程，持续改进
  • ✅ 安全边界强化 - 破坏性操作（关机）必须明确授权

🎯 最新更新 (v2.0.7 - 2026-04-05)

  • ✅ 高优先级优化完成 - PyPI 打包支持、配置文件系统、异步默认化
  • ✅ PyPI 支持 - 可通过 pip install audio-announcement 安装
  • ✅ 配置文件 - ~/.config/audio-announcement/config.json（enabled/lang/volume/async_default）
  • ✅ 异步默认 - 默认后台播放，减少对 Agent 响应时间的阻塞
  • ✅ CLI 工具 - audio-announce 命令支持测试、配置、统计
  • ✅ 集成建议更新 - AGENTS.md 添加最佳实践和示例代码

🎯 最新更新 (v2.0.6 - 2026-04-05)

  • ✅ 增强防遗忘机制 - 添加验证脚本、集成检查清单
  • ✅ 快速集成指南 - 提供 announce_helper.py 简化集成
  • ✅ 强制规则模板 - 可直接复制到 AGENTS.md 的完整规则
  • ✅ Windows 高可靠性 - 使用 python -m edge_tts 模块调用，不依赖 PATH

🎯 最新更新 (v2.0.5 - 2026-04-05)

  • ✅ 修复 PATH 依赖问题 - announce_pygame.py 改用 python -m edge_tts 模块调用，不依赖 PATH 环境变量
  • ✅ Windows 高可靠性 - 即使 edge-tts 不在 PATH 也能正常工作
  • ✅ 配置状态记录 - AGENTS.md 添加语音播报配置状态追踪

🎯 最新更新 (v2.0.4 - 2026-03-28)

  • ✅ 强化播报规则 - 5 种播报时机，内容原则，检查清单
  • ✅ 集成到核心配置 - AGENTS.md / SOUL.md / USER.md / MEMORY.md
  • ✅ 强制执行机制 - 每次交互都必须播报，不能遗漏
  • ✅ 内容规范 - ≤20 字，口语化，不带名称

🎯 历史更新 (v1.5.0-v1.7.4)

  • ✅ Windows 默认使用 pygame - announce.sh 在 Windows 平台自动调用 announce_pygame.py
  • ✅ 简化 Windows 使用 - 无需手动选择脚本，统一使用 announce.sh
  • ✅ 清理无用测试脚本 - 移除 test-integration.sh 和备份文件

📜 历史更新

  • v1.4.0: Windows 11 完整支持，新增 announce_pygame.py，修复新会话语音、macOS 兼容性、跨平台哈希计算
  • v1.3.0: 新增 workflow-helper.sh，支持自动包装命令
  • v1.2.0: 新增离线模式支持
  • v1.1.0: 支持多语言（9种语言）
  • v1.0.0: 初始版本，支持 macOS/Linux

特性

  • 🎯 透明度：清楚知道 AI 正在执行什么操作
  • 🔒 安全感：实时听到操作，不用盯着日志看
  • 💬 人性化：友好的声音，不是冷冰冰的文字
  • ⚡ 效率：专注你的工作，让 AI 用声音告诉你进度
  • 🌍 9种语言：中文、英文、日文、韩文、西班牙语、法语、德语等
  • 🔄 队列机制：消息永不丢失，自动重试
  • 🛡️ 防遗忘：启动自检 + 身份绑定，两重保障
  • 🔌 Session Hook：自动在 /NEW 和 /RESET 后运行检查

🛡️ 防遗忘机制（最重要！）

为了防止播报功能在 /RESET 或 /NEW 后失效，本 skill 实现了多层防护：

1️⃣ 启动自检（Session Start）

每次 OpenClaw 新会话开始时，自动运行 scripts/startup_check_announcement.py：

  • ✅ 检查 edge-tts、pygame、配置文件、包安装
  • ✅ 自动播放"系统启动"测试语音
  • ✅ 如有问题立即输出修复建议

自动配置方法（任选其一）：

Windows PowerShell ($PROFILE)：

$checkAudio = "C:\Users\williammiao\.openclaw-autoclaw\skills\audio-announcement\scripts\startup_check_announcement.py"
if (Test-Path $checkAudio) {
    python $checkAudio | Out-Host
}

macOS/Linux (~/.bashrc)：

python ~/.openclaw-autoclaw/skills/audio-announcement/scripts/startup_check_announcement.py 2>/dev/null || true

3️⃣ 强制规则（AGENTS.md）

在 AGENTS.md 中添加：

### 2️⃣ 语音播报强制执行（严禁遗漏）

- 所有 agent 必须显式调用播报脚本
- 禁止仅依赖记忆中的规则而不实际执行
- 每次发送回复前必须完成 `complete` 播报
- 任务开始前必须完成 `task` 播报

📋 自我检查清单：
- [ ] 收到消息时是否播报了 `receive`？
- [ ] 任务开始时是否播报了 `task`？
- [ ] 执行过程中是否播报了关键步骤？
- [ ] 完成任务后是否播报了 `complete`？
- [ ] 遇到异常时是否播报了 `error`？

4️⃣ 身份绑定（IDENTITY.md）

播报是你的核心身份特质，不是可选项。在 IDENTITY.md 中记录：

## 核心特质
- 每次交互都必须语音播报（强制执行）
- 有温暖、机敏、可靠的声音
- 透明化操作，让用户知道我在做什么

## 启动播报自检
每次 /NEW 或 /RESET 后，自动检查：
- [ ] edge-tts 和 pygame 是否安装
- [ ] 配置文件是否存在
- [ ] 运行 audio-announce test 验证功能
- [ ] 如果失败，立即修复或提醒用户

5️⃣ 首次设置引导（BOOTSTRAP.md）

在首次对话时，BOOTSTRAP.md 提供完整的播报设置流程，确保从一开始就配置好。

🎤 语音播报（强制执行）

每次交互都必须语音播报！

播报时机与内容

时机类型内容要求示例
收到消息receive收到的指令信息"收到上传指令"
开始工作task工作规划"准备上传到GitHub"
执行中task下一步要处理的内容"正在生成文档"
任务完成complete工作总结"上传完成"
发送回复complete回复内容的简短总结"已发送项目地址"
遇到异常error错误描述"网络连接失败"

内容原则

  • 信息丰富：包含指令/规划/进度/总结
  • 简洁：不超过 20 个字
  • 不带名称：不说用户名、不说"我"
  • 口语化：像朋友随口说一句

🛠️ 快速集成

Python Agent（推荐）

# 方式1: 使用 audio_announcement 包
from audio_announcement import receive, task, complete, error

# 一行调用，默认异步不阻塞
receive("用户查询天气")
task("正在获取数据")
complete("已发送天气预报")
error("网络超时")

# 方式2: 使用 AnnouncementHelper（更多控制）
from audio_announcement import AnnouncementHelper
helper = AnnouncementHelper()
helper.config.async_default = True  # 默认异步
helper.config.volume = 0.8           # 调整音量

配置管理

# 查看当前配置
audio-announce config

# 设置配置
audio-announce config async_default=true volume=0.8

# 测试所有类型
audio-announce test

# 查看统计
audio-announce stats

# 启用/禁用
audio-announce enable
audio-announce disable

配置文件位置：~/.config/audio-announcement/config.json

🔧 平台支持

平台主方案备选方案安装命令
Windowsannounce_pygame.py (pygame)无pip install edge-tts pygame
macOSannounce_pygame.py (pygame)announce.sh (afplay)brew install edge-tts && pip install pygame
Linuxannounce_pygame.py (pygame)announce.sh (mpg123)apt install edge-tts mpg123 && pip install pygame

自动选择逻辑：

  • 如果 pygame 可用 → 所有平台统一使用 announce_pygame.py
  • 如果 pygame 不可用 → macOS/Linux 使用 announce.sh + 系统播放器
  • Windows 无 pygame 会报错（必须安装 pygame）

📦 安装方式

方式一：PyPI（推荐）

pip install audio-announcement
pip install pygame  # 确保 pygame 可用

方式二：ClawHub

clawhub install audio-announcement

方式三：GitHub 源码

git clone https://github.com/wililam/audio-announcement-skills.git
cd audio-announcement-skills
pip install -e .

🧪 测试与验证

完整验证脚本

# 项目自带的验证脚本
cd ~/.openclaw-autoclaw/workspace
py -3 scripts/verify_announcement.py

预期输出：

=== 语音播报功能验证 ===

1. 检查依赖
[OK] edge-tts 已安装: edge-tts 7.2.8
[OK] pygame 已安装: 2.6.1

2. 检查脚本文件
[OK] 脚本存在: ...\announce_pygame.py

3. 测试播报功能
[OK] receive 播报成功
[OK] task 播报成功
[OK] complete 播报成功
[OK] error 播报成功

==================================================
全部通过
通过率: 4/4

恭喜！语音播报功能工作正常！

启动自检脚本

cd ~/.openclaw-autoclaw/skills/audio-announcement
python scripts/startup_check_announcement.py

CLI 测试

audio-announce test

⚙️ 配置选项

配置文件：~/.config/audio-announcement/config.json

{
  "enabled": true,             // 启用/禁用播报
  "default_lang": "zh",        // 默认语言
  "volume": 1.0,               // 音量 (0.0-1.0)
  "async_default": true,       // 默认异步播放
  "cache_enabled": true,       // 启用缓存
  "log_level": "WARNING",      // 日志级别
  "prefer_pygame": true,       // 优先使用 pygame
  "fallback_to_shell": true    // 失败时回退到 shell 脚本
}

运行时修改：

from audio_announcement import set_config
set_config(async_default=False, volume=0.8)

📊 监控与维护

日志查看

# 播放日志
tail -f ~/.openclaw-autoclaw/skills/audio-announcement/logs/*.log

# 缓存统计
du -sh ~/.cache/audio-announcement/

清理缓存

# 清理所有缓存（会重新生成）
rm -rf ~/.cache/audio-announcement/*.mp3

🧩 高级用法

自定义语音

修改 audio_announcement/announce_helper.py 中的 voices 字典：

voices = {
    "zh": "zh-CN-XiaoxiaoNeural",     # 晓晓
    "en": "en-US-JennyNeural",        # Jenny
    "ja": "ja-JP-NanamiNeural",       # 七海
    # 更多参考: https://learn.microsoft.com/azure/ai-services/speech-service/language-support#text-to-speech
}

批量播报

from audio_announcement import announce

steps = ["开始处理", "步骤一完成", "步骤二完成", "任务结束"]
for step in steps:
    announce("task", step)

错误处理

try:
    result = do_something()
    complete("操作成功")
except Exception as e:
    error(f"操作失败: {e}")
    raise

🔍 故障排除

问题：没有声音

  1. 检查系统音量
  2. 确认 pygame 已安装：python -c "import pygame; print(pygame.version.ver)"
  3. 测试 edge-tts：edge-tts --text "测试" --voice zh-CN-XiaoxiaoNeural --write-media test.mp3
  4. 手动播放 test.mp3 确认音频输出正常

问题：播报延迟

  • 首次使用会有缓存延迟（下载语音包）
  • 考虑使用 async_default=true 异步播放
  • 检查网络连接（edge-tts 需要联网）

问题：/RESET 后播报失效

  • 确认 startup_check_announcement.py 已配置自动运行
  • 手动运行自检：python scripts/startup_check_announcement.py
  • 检查 IDENTITY.md 和 AGENTS.md 是否保留

问题：ClawHub 发布失败

ClawHub CLI 可能存在环境兼容问题，建议：

  • 使用 GitHub 版本：pip install git+https://github.com/wililam/audio-announcement-skills.git
  • 或换用 Python 3.12 环境重试

📈 性能与优化

  • 缓存机制：首次生成 MP3 后缓存，后续播放直接复用（无需重复生成）
  • 异步播放：默认后台播放，不阻塞 Agent 响应（可配置为同步）
  • 批量操作：多文件处理时自动队列化
  • 资源清理：临时文件 24 小时自动清理

🤝 贡献

欢迎提交 Issue 和 PR！

如果你发现任何遗漏播报的场景，或需要更多集成示例，请告诉我们。

📄 License

MIT License - 详见 LICENSE 文件

🎉 总结

audio-announcement v2.0.8 提供了：

  • ✅ 跨平台支持（Windows/macOS/Linux）
  • ✅ PyPI 一键安装
  • ✅ 配置文件管理
  • ✅ 防遗忘两重保障（启动自检 + 强制规则）
  • ✅ Session Hook 自动恢复
  • ✅ 异步非阻塞播放
  • ✅ 9种语言支持

你的 OpenClaw Agent 现在可以"开口说话"了，而且永远不会忘记！ 🦀🗣️

🚀 快速开始：

# 1. 安装
pip install audio-announcement pygame

# 2. 配置
audio-announce config async_default=true

# 3. 测试
audio-announce test

# 4. 集成到你的 Agent
from audio_announcement import receive, task, complete, error

开始享受透明、有温度的声音体验吧！

Source Transparency

This detail page is rendered from real SKILL.md content. Trust labels are metadata-based hints, not a safety guarantee.

Open Registry RecordOpen in ClawHub

Related Skills

Related by shared tags or category signals.

General

Huo15 Openclaw Enhance

火一五·克劳德·龙虾增强插件 v5.7.8 — 全面适配 openclaw 2026.4.24：peerDep ^4.24 + build/compat 同步到 4.24 + 14 处 api.on 全部去掉 as any 改成 typed hook（hookName 联合类型 + handler 自动推断 Pl...

Registry SourceRecently Updated
3030zhaobod1
General

Content Trend Analyzer

Aggregates and analyzes content trends across platforms to identify hot topics, user intent, content gaps, and generates data-driven article outlines.

Registry SourceRecently Updated
260openlark
General

Prompt Debugger

Debug prompts that produce unexpected AI outputs — diagnose failure modes, identify ambiguity and conflicting instructions, test variations, compare model re...

Registry SourceRecently Updated
120charlie-morrison
General

Indie Maker News

独行者 Daily - 变现雷达。读对一条新闻，少走一年弯路。每天5分钟，给创业者装上商业雷达。聚焦一人公司、副业、创业变现资讯，智能分类，行动导向。用户下载即能用，无需本地部署！

Registry SourceRecently Updated
300kylnwu