Piper TTS
Generate voice messages using , a fast local TTS engine. Zero cloud calls, zero cost, zero API keys.
Setup
If Piper is not installed, run the setup script:
scripts/setup-piper.sh
This installs piper-tts via pip and downloads a default voice (en_US-kusal-medium).
Generating Voice Messages
Use scripts/piper-speak.sh to generate and deliver voice:
scripts/piper-speak.sh "<text>" [voice]
text: The text to speak (required)voice: Piper voice name (default:en_US-kusal-medium)
The script outputs an MP3 path. Include it in your reply as:
[[audio_as_voice]]
MEDIA:<path-to-mp3>
This delivers the audio as a native voice message on supported channels (Telegram, Discord, etc.).
示例
- User asks: "Tell me a joke as audio"
- Run:
scripts/piper-speak.sh "Why do programmers prefer dark mode? Because light attracts bugs!" - Get MP3 path from output
- Reply with
[[audio_as_voice]]+MEDIA:<path>
Available Voices
After setup, download additional voices:
scripts/setup-piper.sh --voice en_US-ryan-high
scripts/setup-piper.sh --voice en_GB-northern_english_male-medium
Popular voices:
en_US-kusal-medium— Clear male voice (default, recommended)en_US-ryan-high— High quality US maleen_US-hfc_male-medium— US maleen_GB-northern_english_male-medium— British male- Browse all: <https://huggingface.co/rhasspy/piper-voices>
Important Notes
- Speed: Local generation is ~0.5-1s. Much faster than cloud TTS.
- No API keys: Works completely offline after setup.
- Platform: macOS (Apple Silicon + Intel), Linux. Requires Python 3.9+.
- Do NOT set
messages.tts.auto: "always"in Skill平台 config — it makes every response slow. Keep TTS on-demand.
依赖说明
运行环境
- Agent平台: 支持SKILL.md的任意AI Agent( Code / Cursor / Codex / CLI等)
- 操作系统: Windows / macOS / Linux
依赖说明
| 依赖项 | 类型 | 是否必需 | 获取方式 |
|---|---|---|---|
| LLM API | API | 必需 | 由Agent内置LLM提供 |
API Key 配置
- 本Skill基于Markdown指令,无需额外API Key(除内容中明确标注的外部API)
可用性分类
- 分类: MD+EXEC(纯Markdown指令,部分功能需要exec命令行执行能力)
- 说明: 基于Markdown的AI Skill,通过自然语言指令驱动Agent执行任务
核心能力
- Local text-to-speech using Piper for voice message delivery
- Use when
the user asks for voice res - 触发关键词: using, local, speech, text, piper, tts, beware
适用场景
| 场景 | 输入 | 输出 |
|---|---|---|
| 基础使用 | 用户请求 | 处理结果 |
不适用于：需要人工判断的复杂决策场景
使用流程
- 确认运行环境满足依赖说明中的要求
- 根据适用场景选择合适的使用方式
- 执行操作并检查输出结果
- 如遇错误，参考错误处理章节
错误处理
| 错误场景 | 原因 | 处理方式 |
|---|---|---|
| 配置错误 | 参数缺失或格式错误 | 检查依赖说明中的配置要求 |
| 运行时错误 | 运行环境不满足 | 确认运行环境符合依赖说明 |
| 网络错误 | 连接超时或不可达 | 检查网络连接后重试，参考国内替代方案 |
常见问题
Q1: 如何开始使用Piper TTS？
A: 请先阅读使用流程章节，确认环境满足依赖说明中的要求。
Q2: 遇到错误怎么办？
A: 请参考错误处理章节，按照表格中的处理方式操作。
Q3: Piper TTS有什么限制？
A: 请参考已知限制章节了解具体限制。
已知限制
- 本地运行，不支持多设备同步
