ms-speech-synth

by booynal

Install this Skill

curl -fsSL -o ms-speech-synth.zip https://skill.seembox.com/api/v1/skills/ms-speech-synth/download && unzip ms-speech-synth.zip

Download ms-speech-synth.zip

SKILL.md About

---
name: ms-speech-synth
description: 将长文本（最多数千字）使用微软 Edge TTS 分段合成 MP3/WAV 音频。支持单文件和文件夹批量模式，自动降速防限流（可配置 20-30次/分钟），自动清洗 Markdown 格式转为自然朗读。
---

# MS Speech Synth - 微软 TTS 分段合成技能

## 核心能力

将任意长度的中文文本（数千字以上）转换为 MP3 音频，使用**微软 Edge TTS** 音色，通过**分段合成 + PCM 拼接**实现无字符限制的语音生成。支持单文件和文件夹批量处理。

## 工作流程

```
长文本 → 按句子分chunk（每chunk ≤1200字）
       → edge-tts 每段生成 MP3（每段之间延迟防止超限）
       → miniaudio 解码 MP3 → PCM bytes
       → 拼接所有 PCM
       → 写入 WAV 文件
       → ffmpeg 转为 MP3
```

## 工具依赖

| 工具 | 安装 | 用途 |
|------|------|------|
| `edge-tts` | `pip3 install edge-tts` | 微软 TTS 引擎 |
| `miniaudio` | `pip3 install miniaudio` | MP3 解码为 PCM |
| `ffmpeg` | `curl -L .../ffmpeg.zip -o /tmp/ffmpeg.zip && unzip -d /tmp/ffmpeg_bin` | WAV 转 MP3 |

## 速率限制（Rate Limit）

> ⚠️ Edge TTS 是微软必应语音服务的免费接口，**非官方 API**，无正式 SLA。

**限制阈值：**
- 单次请求字符上限：约 **1000–1500 字符**（超出部分被服务器静默截断）
- 连续调用：建议不超过 **20–30 次/分钟**
- 超过限制会触发 `ConnectionResetError`，需等待 30–60 秒恢复

**速率控制参数 `--rate`（每 TTS 请求间延迟）：**

| `--rate` 值 | 实际速率 | 适用场景 |
|-------------|----------|----------|
| `1.5` | 40次/分钟 | 较快，接近上限 |
| `2.0`（默认）| 30次/分钟 | 稳定安全（默认）|
| `3.0` | 20次/分钟 | 保守模式 |

**批量文件夹模式额外策略：** 每文件之间再等待 `--delay` 秒（默认3秒）。

## 使用方式

### 单文件模式

```bash
python3 ~/.openclaw/workspace/skills/ms-speech-synth/scripts/ms_tts_chunked.py \
  --input "/path/to/input.txt" \
  --output "/path/to/output" \
  --voice "zh-CN-XiaoxiaoNeural"

# 从 Markdown 文件（自动清洗 #标题 **加粗** 等格式）
python3 ~/.openclaw/workspace/skills/ms-speech-synth/scripts/ms_tts_chunked.py \
  --input "/path/to/notes.md" \
  --output "/path/to/output"
```

### 文件夹批量模式

处理整个文件夹下所有 `.txt` 和 `.md` 文件，**自动降速防限流**：

```bash
python3 ~/.openclaw/workspace/skills/ms-speech-synth/scripts/ms_tts_chunked.py \
  --input "/path/to/folder/" \
  --output "/path/to/output_folder/" \
  --delay 3      # 每文件间等待3秒（默认）
  --rate 2.0     # 每TTS请求间等待2秒（默认）
```

**批量模式输出示例：**
```
[MS-TTS] Found 5 files to process

[MS-TTS] [1/5] Processing: chapter1.txt
[MS-TTS] Chunk 1/3 (800 chars), waiting 2s...
[MS-TTS] Chunk 2/3 (1100 chars), waiting 2s...
[MS-TTS] Chunk 3/3 (900 chars)
[MS-TTS] ✓ Done: chapter1.mp3 (3 chunks, 4.2MB, 180s)
[MS-TTS] Waiting 3s before next file...

[MS-TTS] [2/5] Processing: chapter2.md
...
[MS-TTS] === Batch complete: 5 ok, 0 failed ===
```

### Python 模块导入

```python
from scripts.ms_tts_chunked import synthesize_text, synthesize_file, synthesize_dir

# 单文件
result = synthesize_file("/path/to/input.txt", "/path/to/output",
                         voice="zh-CN-XiaoxiaoNeural",
                         rate_limit_delay=2.0,
                         speed=1.0)   # 语速倍率，1.0=正常

# 批量文件夹
results = synthesize_dir(
    input_dir="/path/to/folder/",
    output_dir="/path/to/output/",
    voice="zh-CN-XiaoxiaoNeural",
    delay=3.0,           # 文件间等待3秒
    rate_limit_delay=2.0, # chunk间等待2秒（30次/分钟）
    speed=1.0            # 语速倍率
)
```

## 关键参数

| 参数 | 默认值 | 说明 |
|------|--------|------|
| `--voice` | `zh-CN-XiaoxiaoNeural` | 微软中文女声（晓晓）|
| `--chunk` | `1200` | 每段最大字符数（建议 1000-1500）|
| `--delay` | `3.0` | 批量模式：每文件间延迟秒数 |
| `--rate` | `2.0` | 每TTS请求间延迟秒数（2s=30次/分钟，3s=20次/分钟）|
| `--speed` | `1.0` | 语速倍率（1.0=正常，0.8=稍慢，1.5=较快，2.0=快一倍）|
| `--ffmpeg` | 自动查找 | FFmpeg 路径（转 MP3 用）|

### 其他可用声音

```python
zh-CN-XiaoxiaoNeural   # 晓晓 - 推荐女声
zh-CN-YunxiNeural      # 云希 - 男声
zh-CN-YunyangNeural    # 云扬 - 新闻风格
zh-HK-HiuMaanNeural    # 香港粤语
zh-TW-HsiaoYuNeural    # 台湾女声
```

## Markdown 格式清洗

输入文件为 `.md` 时，自动将格式控制符转为自然朗读：

| 原始格式 | 转换效果 |
|----------|----------|
| `# 我是标题` | "我是标题……"（直接读标题，末尾加停顿）|
| `## 小标题` | "小标题内容……"（直接读标题，末尾加停顿）|
| `### 本节标题` | "本节标题内容……"（直接读标题，末尾加停顿）|
| `- 要点` / `* 要点` | "第X点：xxx" |
| `> 引用` | "引用：xxx" |
| `**加粗**` | 保留文字（去星号）|
| `` `代码` `` | "代码：xxx" |
| `---` / `***` | 跳过 |
| `[文字](url)` | 读链接文字 |

## 分段策略

**三级保护机制，防截断设计：**

1. **第一级：按句子边界拆分** — 文本按 `。！？；` 拆成最小句子单元
2. **第二级：累积到 chunk_size** — 将句子组合成接近但不超过 `chunk_size` 的大chunk
3. **第三级：超长句二次切分** — 如果单个句子本身就超过 `chunk_size`，按 `顿号 → 逗号 → 空格` 的顺序在子句间切分

**chunk_size 建议值：**
- 1200字 — 微软服务器稳定上限（推荐）
- 1000字 — 更保守，适合超长篇
- 1500字 — 接近边界，有轻微截断风险

## 注意事项

1. **edge-tts 有速率限制**：超过 20–30 次/分钟会触发 `ConnectionResetError`
2. **批量任务**：每文件之间等待 3 秒 + 每 TTS 请求之间等待 2 秒（默认），双重保护
3. **chunk_size 不要太大**：超过 1500 字可能被服务器截断，建议 1000-1200
4. **FFmpeg 路径**：默认自动查找 `/tmp/ffmpeg_bin/ffmpeg` 等位置

_meta.json Metadata

{
  "ownerId": "kn7e7z3dcm6j636gfzyzysy79h85yk07",
  "publishedAt": 1777737448307,
  "slug": "ms-speech-synth",
  "version": "1.0.2"
}