piper-tts

使用 Piper 进行本地文本转语音传输语音消息。当用户请求语音响应、音频消息、TTS、文本转语音、语音注释或想要听到大声朗读的内容时使用。在本地将文本转换为语音（无云 API、无成本、无延迟），并在 Telegram、Discord 或任何支持音频的通道上以语音消息形式传送。

# Piper TTS — Local Voice Messages

Generate voice messages using [Piper](https://github.com/rhasspy/piper), a fast local TTS engine. Zero cloud calls, zero cost, zero API keys.

## Setup

If Piper is not installed, run the setup script:

```bash
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:

```bash
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.).

## Example Workflow

1. User asks: "Tell me a joke as audio"
2. Run: `scripts/piper-speak.sh "Why do programmers prefer dark mode? Because light attracts bugs!"`
3. Get MP3 path from output
4. Reply with `[[audio_as_voice]]` + `MEDIA:<path>`

## Available Voices

After setup, download additional voices:

```bash
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 male
- `en_US-hfc_male-medium` — US male
- `en_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 OpenClaw config — it makes every response slow. Keep TTS on-demand.

---

## 中文说明

# Piper TTS — 本地语音消息

使用 [Piper](https://github.com/rhasspy/piper)（一个快速的本地 TTS 引擎）生成语音消息。零云端调用、零成本、零 API 密钥。

## 安装

如果尚未安装 Piper，运行安装脚本：

```bash
scripts/setup-piper.sh
```

这会通过 pip 安装 `piper-tts` 并下载一个默认语音（`en_US-kusal-medium`）。

## 生成语音消息

使用 `scripts/piper-speak.sh` 来生成并传送语音：

```bash
scripts/piper-speak.sh "<text>" [voice]
```

- `text`：要朗读的文本（必填）
- `voice`：Piper 语音名称（默认：`en_US-kusal-medium`）

脚本会输出一个 MP3 路径。在回复中按如下方式包含它：

```
[[audio_as_voice]]
MEDIA:<path-to-mp3>
```

这会在支持的通道（Telegram、Discord 等）上以原生语音消息形式传送音频。

## 示例工作流

1. 用户询问："以音频形式给我讲个笑话"
2. 运行：`scripts/piper-speak.sh "Why do programmers prefer dark mode? Because light attracts bugs!"`
3. 从输出中获取 MP3 路径
4. 用 `[[audio_as_voice]]` + `MEDIA:<path>` 回复

## 可用语音

安装完成后，下载更多语音：

```bash
scripts/setup-piper.sh --voice en_US-ryan-high
scripts/setup-piper.sh --voice en_GB-northern_english_male-medium
```

常用语音：
- `en_US-kusal-medium` — 清晰的男声（默认，推荐）
- `en_US-ryan-high` — 高质量美式男声
- `en_US-hfc_male-medium` — 美式男声
- `en_GB-northern_english_male-medium` — 英式男声
- 浏览全部：https://huggingface.co/rhasspy/piper-voices

## 重要说明

- **速度**：本地生成约 0.5-1 秒，比云端 TTS 快得多。
- **无 API 密钥**：安装完成后可完全离线运行。
- **平台**：macOS（Apple Silicon + Intel）、Linux。需要 Python 3.9+。
- **请勿**在 OpenClaw 配置中设置 `messages.tts.auto: "always"`——这会使每条响应都变慢。保持 TTS 按需触发。