speak-tts

speak - 与你的 Claude 对话！

让你的 Agent 能够实时与你对话。在 Apple Silicon 上本地进行文本转语音、语音克隆和音频生成。 让你的 Agent 能够实时与你对话。在 Apple Silicon 上使用本地 TTS 和语音克隆。

先决条件

要求	检查	安装
Apple Silicon Mac	uname -m → arm64	不支持 Intel
macOS 12.0+	sw_vers	-
sox	which sox	brew install sox
ffmpeg	which ffmpeg	brew install ffmpeg
poppler（PDF）	which pdftotext	brew install poppler

输入来源

来源	示例
文本文件	speak article.txt
Markdown	speak doc.md
直接输入字符串	speak "Hello"
剪贴板	pbpaste | speak
标准输入	cat file.txt | speak

网页文章

lynx -dump -nolist "https://example.com/article" | speak --output article.wav

转换格式

格式	转换命令
PDF	pdftotext doc.pdf doc.txt
DOCX	textutil -convert txt doc.docx
HTML	pandoc -f html -t plain doc.html > doc.txt

输出模式

目标	命令
保存以供稍后使用	speak text.txt --output file.wav
立即收听（流式）	speak text.txt --stream
立即收听（完整播放）	speak text.txt --play
两者	speak text.txt --stream --output file.wav

默认行为

speak article.txt          # → ~/Audio/speak/article.wav (no playback)
speak "Hello"              # → ~/Audio/speak/speak_<timestamp>.wav

自动创建目录

目录	是否自动创建？
~/Audio/speak/	✓ 是
~/.chatter/voices/	✗ 否
自定义目录	✗ 否

请务必先创建自定义目录：

mkdir -p ~/.chatter/voices/
mkdir -p ~/Audio/custom/

语音克隆

语音克隆会根据一段简短录音生成与你的声音特征（音高、音色、语调）相符的语音。

质量预期

• 输出会保留声音的总体特征，但无法完美复刻
• 质量在很大程度上取决于样本质量
• 15–25 秒为最佳时长（最短 10 秒，最长 30 秒）

录制你的声音

使用 QuickTime：

1. 打开 QuickTime Player → File → New Audio Recording
2. 录制 20 秒清晰的语音
3. File → Export As → Audio Only (.m4a)
4. 转换为 WAV（见下文）

使用 sox（命令行）：

# -d = use default microphone
# Recording starts immediately and stops after 25 seconds
sox -d -r 24000 -c 1 ~/.chatter/voices/my_voice.wav trim 0 25

转换为所需格式

语音样本必须为：WAV、24000 Hz、单声道、10–30 秒。

# From MP3
ffmpeg -i voice.mp3 -ar 24000 -ac 1 voice.wav

# From M4A (QuickTime)
ffmpeg -i voice.m4a -ar 24000 -ac 1 voice.wav

# Trim to 25 seconds
ffmpeg -i long.wav -t 25 -ar 24000 -ac 1 trimmed.wav

# Check sample properties
ffprobe -i voice.wav 2>&1 | grep -E "Duration|Stream"
# Should show: Duration ~15-25s, 24000 Hz, mono

使用你的声音

# Create directory
mkdir -p ~/.chatter/voices/

# Move sample
mv voice.wav ~/.chatter/voices/my_voice.wav

# Test
speak "Testing my voice" --voice ~/.chatter/voices/my_voice.wav --stream

# Use for content
speak notes.txt --voice ~/.chatter/voices/my_voice.wav --output presentation.wav

路径要求：

• ✓ 可用：~/.chatter/voices/my_voice.wav（shell 会展开波浪号）
• ✓ 可用：/Users/name/.chatter/voices/my_voice.wav
• ✗ 无效：my_voice.wav（相对路径）
• ✗ 无效：./voices/my_voice.wav（相对路径）

语音样本提示

好的样本	不好的样本
安静的房间	有背景噪音
自然的语速	语速过快或语调单一
发音清晰	含糊不清
内容多样	短语重复

默认声音

省略 --voice 时，会使用内置的默认声音：

speak "Hello world" --stream  # Uses default voice

情绪标签

标签会产生可听见的效果（实际声音），而不是口述内容：

speak "[sigh] Monday again." --stream
# Output: (sigh sound) "Monday again."

标签	效果
[laugh]	笑声
[chuckle]	轻笑
[sigh]	叹气
[gasp]	倒吸一口气
[groan]	呻吟
[clear throat]	清嗓子
[cough]	咳嗽
[crying]	哭泣
[singing]	歌唱式说话

不支持： [pause]、[whisper]（会被忽略）

**要添加停顿：**使用标点符号："Wait... let me think."

批量处理

mkdir -p ~/Audio/book/
speak ch01.txt ch02.txt ch03.txt --output-dir ~/Audio/book/
# Creates: ch01.wav, ch02.wav, ch03.wav

# With auto-chunking (for long files)
speak chapters/*.txt --output-dir ~/Audio/book/ --auto-chunk

# Skip completed files
speak chapters/*.txt --output-dir ~/Audio/book/ --skip-existing

自动分块行为

批量处理时使用 --auto-chunk：

1. 每个输入文件会独立分块
2. 分块生成后，会按文件自动拼接
3. 最终输出：每个输入文件对应一个 .wav 文件（例如 ch01.wav）
4. 中间分块会被删除（除非使用 --keep-chunks）

无需手动拼接分块——只需拼接最终的章节文件。

拼接音频

# Explicit order (recommended)
speak concat ch01.wav ch02.wav ch03.wav --output book.wav

# Glob pattern (REQUIRES zero-padded filenames)
speak concat audiobook/*.wav --output book.wav

零填充规则

正确的拼接顺序至关重要：

文件	正确	错误
1-9	01、02、...、09	1、2、...、9
10-99	01、02、...、99	1、10、2、...
100+	001、002、...、999	1、100、2、...

原因： Shell 通配符展开会按字母顺序排序。1, 10, 2 与 01, 02, 10。

PDF 转有声读物（完整工作流）

步骤 1：查找章节边界

# Preview table of contents
pdftotext -f 1 -l 5 textbook.pdf toc.txt
cat toc.txt  # Note chapter page numbers

# Or search for "Chapter" markers
pdftotext textbook.pdf - | grep -n "Chapter"

步骤 2：提取章节（使用零填充！）

# For 100-page book with ~10 chapters
pdftotext -f 1 -l 12 -layout textbook.pdf ch01.txt
pdftotext -f 13 -l 25 -layout textbook.pdf ch02.txt
pdftotext -f 26 -l 38 -layout textbook.pdf ch03.txt
# ... continue for all chapters

步骤 3：估算时长

speak --estimate ch*.txt
# Shows: total audio duration, generation time, storage needed

# Quick estimates:
# 1 page ≈ 2 min audio ≈ 1 min generation
# 100 pages ≈ 200 min audio ≈ 100 min generation ≈ 500 MB

步骤 4：生成音频

mkdir -p audiobook/
speak ch01.txt ch02.txt ch03.txt --output-dir audiobook/ --auto-chunk
# Creates: audiobook/ch01.wav, audiobook/ch02.wav, audiobook/ch03.wav

步骤 5：拼接

speak concat audiobook/ch01.wav audiobook/ch02.wav audiobook/ch03.wav --output complete_audiobook.wav
# Or with glob (only if zero-padded):
speak concat audiobook/ch*.wav --output complete_audiobook.wav

PDF 故障排查

问题	解决方案
文本为空或乱码	扫描版 PDF — 使用 OCR：brew install tesseract
编码错误	尝试：pdftotext -enc UTF-8 doc.pdf
检查字数	pdftotext doc.pdf - | wc -w（应大于 100）

多人声内容

mkdir -p podcast/scripts podcast/wav

echo "Welcome to the show." > podcast/scripts/01_host.txt
echo "Thanks for having me." > podcast/scripts/02_guest.txt

speak podcast/scripts/01_host.txt --voice ~/.chatter/voices/host.wav --output podcast/wav/01.wav
speak podcast/scripts/02_guest.txt --voice ~/.chatter/voices/guest.wav --output podcast/wav/02.wav

speak concat podcast/wav/01.wav podcast/wav/02.wav --output podcast.wav

选项参考

选项	描述	默认值
--stream	生成时进行流式输出	false
--play	完成后播放	false
--output <path>	输出文件	~/Audio/speak/
--output-dir <dir>	批量输出目录	-
--voice <path>	声音样本（完整路径）	default
--timeout <sec>	每个文件的超时时间	300
--auto-chunk	拆分长文档	false
--chunk-size <n>	每个分块的字符数	6000
--resume <file>	从清单恢复	-
--keep-chunks	保留中间文件	false
--skip-existing	如果输出已存在则跳过	false
--estimate	显示时长估算	false
--dry-run	仅预览	false
--quiet	不显示输出	false

命令

命令	描述
speak setup	设置环境
speak health	检查系统状态
speak models	列出 TTS 模型
speak concat	拼接音频
speak daemon kill	停止 TTS 服务
speak config	显示配置

性能

指标	数值
冷启动	~4-8s
热启动	~3-8s
速度	0.3-0.5x RTF（快于实时速度）
存储空间	~2.5 MB/分钟，~150 MB/小时

恢复功能

用于中断后继续长时间生成：

# Single file with auto-chunk — use --resume
speak long.txt --auto-chunk --output book.wav
# If interrupted, manifest saved at ~/Audio/speak/manifest.json
speak --resume ~/Audio/speak/manifest.json

# Batch processing — use --skip-existing
speak ch*.txt --output-dir audiobook/ --auto-chunk
# If interrupted, re-run same command:
speak ch*.txt --output-dir audiobook/ --auto-chunk --skip-existing

常见错误

错误	原因	解决方案
"Voice file not found"	相对路径	使用完整路径：~/.chatter/voices/x.wav
"Invalid WAV format"	规格不匹配	转换：ffmpeg -i in.wav -ar 24000 -ac 1 out.wav
"Voice sample too short"	少于 10 秒	录制 15-25 秒
"Output directory doesn't exist"	目录尚未创建	mkdir -p dirname/
"sox not found"	尚未安装	brew install sox
拼接顺序错乱	未使用零填充	使用 01、02，不要使用 1、2
超时	生成时间超过 5 分钟	使用 --auto-chunk 或 --timeout 600
"Server not running"	守护进程已过期	speak daemon kill && speak health

设置

speak "test"     # Auto-setup on first run (downloads model ~500MB)
speak setup      # Or manual setup
speak health     # Verify everything works

服务管理

服务会自动启动，并在空闲 1 小时后关闭。

speak health        # Check status
speak daemon kill   # Stop manually