Beware Piper Tts Free

SKILL.md

---
slug: beware-piper-tts-free
name: beware-piper-tts-free
version: "1.0.0"
displayName: Piper TTS Lite
summary: 基于Piper的本地语音合成基础版,使用默认音色将文本转为MP3语音消息,零云端零密钥。
license: MIT
description: |-
  基于 Piper 神经网络引擎的本地语音合成基础版(免费)。全部推理在本地完成,零云端调用、零 API 密钥。
  核心能力:单段文本转语音、默认音色(en_US-kusal-medium)朗读、MP3 输出与语音消息封装。
  适用于偶发的语音消息投递与短文本朗读。如需多音色切换、长文本分段合并、批量生成与风格控制,请升级至 beware-piper-tts 付费版。
tags:
  - 研发工具
  - Creative
  - 语音合成
tools:
  - read
  - exec
---

# Piper TTS Lite

基于 Piper 神经网络语音合成引擎的本地 TTS 基础版。所有推理在本地完成,无需 API Key、无需联网(首次下载音色后),单段生成约 0.5-1 秒。

## 依赖说明

### 运行环境
- **Agent平台**: 支持SKILL.md的任意AI Agent（Claude Code / Cursor / Codex / Gemini CLI等）
- **操作系统**: Windows / macOS / Linux

### 依赖项
| 依赖项 | 类型 | 是否必需 | 获取方式 |
|:-------|:-----|:---------|:---------|
| LLM API | API | 必需 | 由Agent内置LLM提供 |

### API Key 配置
需要配置对应API Key，详见上文环境配置章节

### 可用性分类
- **分类**: MD+EXEC（）


**API Key配置方式**:
```bash
export API_KEY="your_api_key_here"
```
配置后需重启会话或开启新终端生效。API Key应妥善保管,避免泄露到版本控制系统。
## 核心能力

### 1. 单段语音合成
将一段文本用默认音色 `en_US-kusal-medium` 合成为 MP3 并投递到支持的渠道(Telegram、Discord 等)。
```bash
scripts/piper-speak.sh "Why do programmers prefer dark mode? Because light attracts bugs!"
```
脚本输出 MP3 路径,按以下格式封装即可作为原生语音消息投递:
```text
[[audio_as_voice]]
MEDIA:/tmp/piper/out_20260720_103045.mp3
```

**输入**: 用户提供单段语音合成所需的指令和必要参数。
**处理**: 按照skill规范执行单段语音合成操作,遵循单一意图原则。

### 2. 默认音色朗读
免费版使用预置的 `en_US-kusal-medium`(清晰男声)音色,适合英文短文本朗读与语音消息投递。

> **升级提示**: 多音色切换(美式女声、英式男声、中文女声)、长文本分段合并、批量生成与 SSML 风格控制仅在 [beware-piper-tts 付费版](#) 中提供。

**处理**: 按照skill规范执行默认音色朗读操作,遵循单一意图原则。
### 指令解析与执行

解析用户指令,执行核心操作并返回处理结果。

**输入**: 用户提供操作指令和必要参数。

**输出**: 返回操作执行的结果。

- 执行`指令解析与执行`操作，处理输入数据并返回结果
- 验证执行结果，确认输出符合预期格式
- 参考`指令解析与执行`相关配置参数进行设置
### 能力覆盖范围

本skill还覆盖以下能力场景: 的本地语音合成基、使用默认音色将文、本转为、零云端零密钥、神经网络引擎的本、地语音合成基础版、全部推理在本地完、零云端调用、API、核心能力、单段文本转语音、输出与语音消息封、适用于偶发的语音、消息投递与短文本、如需多音色切换、批量生成与风格控、请升级至。这些能力在上述核心功能中均有对应处理逻辑。
### 输出格式

执行结果以Markdown格式返回,包含操作状态(成功/失败)、处理摘要和具体输出数据。失败时返回错误码和错误信息,便于定位问题。

## 适用场景

| 场景 | 典型输入 | 输出内容 | 涉及能力 |
|------|---------|---------|---------|
| 语音消息投递 | "把这句笑话读给我听" | MP3 路径 + 原生语音消息封装 | 单段合成 |
| 短文本朗读 | 一段 100 字以内的英文 | MP3 文件路径 | 单段合成 |

**不适用于**: 长文章转有声(单段过长韵律生硬,需付费版分段合并)、多角色对话体(需付费版多音色切换)、中文朗读(需付费版下载中文音色)。

## 使用流程

### 第一步:安装 Piper 与默认音色
```bash
scripts/setup-piper.sh
# 自动安装 piper-tts、检测 espeak-ng、下载默认音色 en_US-kusal-medium
```

### 第二步:合成并投递语音消息
```bash
scripts/piper-speak.sh "你的朗读文本"
```
从脚本输出读取 MP3 路径,以 `[[audio_as_voice]]` + `MEDIA:<path>` 格式回传给用户即可。

### 第三步:确认投递
检查用户渠道(Telegram/Discord)中是否出现可播放的原生语音气泡。若仅出现文件附件而非语音气泡,说明渠道不支持 `audio_as_voice` 协议,改为直接发送 MP3 文件链接。

## 案例展示

### 案例1:语音笑话投递
**场景**: 用户在 Telegram 中要求"讲个笑话,要语音版的"。
```bash
scripts/piper-speak.sh "Why do programmers prefer dark mode? Because light attracts bugs!"
```
**输出**:
```
/tmp/piper/out_20260720_103045.mp3
```
**回传**:
```text
[[audio_as_voice]]
MEDIA:/tmp/piper/out_20260720_103045.mp3
```
该消息在 Telegram 中呈现为可播放的原生语音气泡,本地推理耗时约 0.7 秒。

### 案例2:短文本朗读
**场景**: 用户希望把一段英文摘要朗读出来便于通勤时收听。
```bash
scripts/piper-speak.sh "The quick brown fox jumps over the lazy dog. This is a pangram used to test font rendering."
```
**输出**:
```
/tmp/piper/out_20260720_103112.mp3
```
直接将路径以文件附件形式发送即可。

## 异常处理

| 错误场景 | 错误信息 | 原因分析 | 处理方式 |
|---------|---------|---------|---------|
| Piper 未安装 | `piper: command not found` | 未运行 setup 脚本或 pip 安装失败 | 执行 `scripts/setup-piper.sh`,确认 Python 3.9+ 可用 |
| espeak-ng 缺失 | `espeak-ng not found, phonemize failed` | 系统未安装音素化器 | macOS `brew install espeak-ng`,Linux `apt install espeak-ng` |
| 音色文件缺失 | `voice model not found: en_US-kusal-medium` | 默认音色未下载 | 重新运行 `scripts/setup-piper.sh` 下载默认音色 |
| 文本含非法字符 | `phonemize error: invalid character` | 文本含 Piper 不支持的 emoji 或控制字符 | 调用前用 `sed` 剔除 emoji 与控制字符 |
| 输出目录不可写 | `permission denied: /tmp/piper/out.mp3` | 输出路径无写权限 | 显式指定 `--output` 到有权限的目录,如 `~/.piper-out/` |

## 常见问题

### Q1: 免费版能用哪些音色?
A: 免费版仅预置 `en_US-kusal-medium`(清晰男声)一个音色。如需美式女声、英式男声、中文女声等多音色切换,请升级至 beware-piper-tts 付费版。

### Q2: 单段文本最长能读多少字?
A: 建议单段不超过 500 字。超过后韵律可能生硬,且单次推理显存占用升高。长文章请升级付费版使用 `piper-speak-long.sh` 自动分段合并。

### Q3: 支持中文朗读吗?
A: 免费版默认音色为英文音色,朗读中文会出现明显错读。中文朗读需下载 `zh_CN-huayan-medium` 音色,该能力在付费版中提供。

### Q4: 为什么不要开启 `messages.tts.auto: "always"`?
A: 该配置会让 Agent 对每条回复都触发 TTS,导致响应明显变慢,且大量语音消息干扰阅读体验。建议仅在用户明确要求语音时手动触发。

## 错误处理


| 错误场景 | 原因 | 处理方式 |
|---------|------|---------|
| LLM响应超时或无响应 | 网络延迟或模型负载过高 | 执行ping命令测试网络连通性,检查防火墙和代理设置连接，执行ping命令测试网络连通性,检查防火墙和代理设置连接后重新执行命令请求；确认Agent平台LLM服务正常 |
| 输入内容格式不正确 | 用户输入不符合skill预期格式 | 检查输入是否符合skill使用说明中的格式要求，参考示例章节 |
| 执行结果与预期不符 | 指令描述不够明确或上下文不足 | 提供更详细的指令描述，补充必要的上下文信息 |
| 命令执行失败 | 运行环境不满足要求或权限不足 | 确认运行环境符合依赖说明中的要求；检查命令权限设置 |

## 已知限制

- **单一音色**: 仅支持默认英文男声 `en_US-kusal-medium`,不支持音色切换
- **无长文本分段**: 单段过长韵律生硬,不支持自动分段与合并
- **无批量生成**: 一次仅处理一段文本,不支持内容矩阵生产
- **无风格控制**: 不支持语速、停顿、音高调节
- **英文优先**: 默认音色为英文,中文朗读需付费版下载中文音色
- **Windows 原生支持弱**: 需经 WSL 运行,原生 Windows 下 espeak-ng 安装较繁琐

---

> 想要多音色切换、长文本分段合并、批量生成与 SSML 风格控制?升级至 [beware-piper-tts 付费版](#),解锁专业语音内容生产能力。