speak-english-tts

v1.0.0

Published

8 months ago

Automatic English Text-to-Speech tool with clipboard monitoring for macOS. Helps improve English learning through listening.

0High
0Medium
0Low

sufubo

tts text-to-speech macos say english learning clipboard monitor automatic speech-synthesis language-learning english-learning pronunciation

📢 Speak English - 自动英语朗读工具

English Text-to-Speech Tool with Automatic Clipboard Monitoring

🚀 快速开始 (Quick Start)

# 全局安装 (Global install)
npm install -g speak-english-tts

# 启动自动监听 (Start auto-monitor)
speak-monitor

# 选中任何英文文本，自动朗读！
# Select any English text, auto-read!

📖 目录 (Table of Contents)

🎯 功能介绍 (Features)

这是一个基于 Node.js 的自动英语朗读工具，帮助您通过听力提升英语学习效果。

This is a Node.js-based automatic English text-to-speech tool that helps improve your English learning through listening.

核心功能 (Core Features)

✅ 自动剪贴板监听 - 选中文本自动朗读，无需手动操作
Auto clipboard monitoring - Automatically reads selected text, no manual operation needed
✅ 智能英文识别 - 自动识别并提取英文内容
Smart English detection - Automatically detects and extracts English content
✅ 引用块优先 - 优先朗读 > 引用块中的内容（适配双语文本）
Quote block priority - Prioritizes content in > quoted blocks (suitable for bilingual text)
✅ 可调语速 - 支持自定义语速，适合不同学习需求
Adjustable speed - Customizable speech rate for different learning needs
✅ 后台运行 - 一次启动，持续监听
Background running - Start once, continuous monitoring
✅ 零依赖 GUI - 纯命令行工具，无需额外应用
Zero GUI dependency - Pure CLI tool, no extra apps needed

🔍 实现原理 (How It Works)

工作流程 (Workflow)

┌─────────────────────────────────────────────────────────┐
│  用户操作 (User Action)                                   │
│  三击选中文本 / Triple-click to select text              │
└─────────────────┬───────────────────────────────────────┘
                  │
                  ▼
┌─────────────────────────────────────────────────────────┐
│  终端自动复制 (Terminal Auto-Copy)                        │
│  Text copied to system clipboard                        │
└─────────────────┬───────────────────────────────────────┘
                  │
                  ▼
┌─────────────────────────────────────────────────────────┐
│  脚本监听 (Script Monitoring)                             │
│  clipboard-monitor.js polls every 500ms                 │
│  执行: pbpaste 读取剪贴板                                  │
└─────────────────┬───────────────────────────────────────┘
                  │
                  ▼
┌─────────────────────────────────────────────────────────┐
│  内容检测 (Content Detection)                             │
│  1. 检查是否有 > 引用块                                    │
│  2. 如果没有，检测是否为纯英文（中文<20%）                   │
└─────────────────┬───────────────────────────────────────┘
                  │
                  ▼
┌─────────────────────────────────────────────────────────┐
│  文本处理 (Text Processing)                               │
│  提取英文内容 / Extract English content                   │
└─────────────────┬───────────────────────────────────────┘
                  │
                  ▼
┌─────────────────────────────────────────────────────────┐
│  语音合成 (Speech Synthesis)                              │
│  say -v Samantha -r 150 "text"                          │
│  使用 macOS 内置 TTS 引擎                                  │
└─────────────────────────────────────────────────────────┘

关键技术点 (Key Technical Points)

剪贴板轮询 (Clipboard Polling)
- 每 500ms 检查一次剪贴板内容
- 使用 macOS pbpaste 命令读取
- 对比上次内容，检测变化

智能英文检测 (Smart English Detection)

// 检测中文字符占比
// Detect Chinese character ratio
const chineseChars = (text.match(/[\u4e00-\u9fa5]/g) || []).length;
const ratio = chineseChars / totalChars;

// 如果中文少于 20%，视为英文
// If Chinese < 20%, consider as English
return ratio < 0.2;

引用块提取 (Quote Block Extraction)

// 提取所有 > 开头的行
// Extract all lines starting with >
const englishLines = lines
  .filter(line => line.trim().startsWith('>'))
  .map(line => line.trim().substring(1).trim());

macOS TTS (Text-to-Speech)

say -v "Samantha" -r 150 "Your text here"

🏗️ 技术架构 (Technical Architecture)

项目结构 (Project Structure)

speak-english/
├── clipboard-monitor.js    # 主程序：剪贴板监听 (Main: Clipboard monitor)
├── speak-english.js        # 交互式手动输入模式 (Interactive manual mode)
├── speak-clipboard.js      # 单次剪贴板朗读 (One-time clipboard read)
├── speak-auto.js          # Hook 集成用 (For hook integration)
├── package.json           # 项目配置 (Project config)
└── README.md             # 本文档 (This document)

依赖项 (Dependencies)

{
  "dependencies": {
    "chalk": "^5.3.0"  // 终端彩色输出 (Colored terminal output)
  }
}

系统依赖 (System Dependencies)

Node.js - JavaScript 运行环境
macOS - 使用系统 TTS 和剪贴板命令
- say - 文本转语音
- pbpaste - 读取剪贴板

💻 系统要求 (Requirements)

操作系统 (OS): macOS 10.13+
Node.js: v18.0.0+
终端 (Terminal):
- Terminal.app ✅
- iTerm2 ✅
- Hyper ✅
- 其他支持选中自动复制的终端 (Other terminals with copy-on-select)

📦 安装步骤 (Installation)

方法 1: NPM 全局安装（推荐）(NPM Global Install - Recommended)

这是最简单的安装方式，一条命令即可完成！

This is the simplest installation method, just one command!

npm install -g speak-english-tts

安装后，您可以在任何地方使用以下命令：

After installation, you can use these commands anywhere:

# 启动自动监听模式 (Start auto-monitor mode)
speak-monitor

# 启动交互式输入模式 (Start interactive mode)
speak-english

# 单次读取剪贴板 (One-time clipboard read)
speak-clipboard

验证安装 (Verify Installation)

# 检查是否安装成功 (Check if installed successfully)
which speak-monitor

# 测试 macOS say 命令 (Test macOS say command)
say -v Samantha "Hello, this is a test"

方法 2: NPM 本地安装 (NPM Local Install)

如果您想在特定项目中使用：

If you want to use in a specific project:

npm install speak-english-tts

然后使用 npx 运行：

Then run with npx:

npx speak-monitor
npx speak-english
npx speak-clipboard

方法 3: 从源码安装 (Install from Source)

如果您想从源码安装或进行开发：

If you want to install from source or develop:

1. 克隆或下载项目 (Clone or Download)

cd /Users/your-username/code/Utils
git clone https://github.com/fubosu/speak-english-tts.git speak-english
# 或者直接下载文件到该目录 (Or download files directly to this directory)

2. 安装依赖 (Install Dependencies)

cd speak-english
npm install

3. 运行 (Run)

# 自动监听模式 (Auto-monitor mode)
npm run monitor

# 交互式模式 (Interactive mode)
npm start

# 单次剪贴板读取 (One-time clipboard read)
npm run clipboard

系统要求检查 (System Requirements Check)

在安装前，请确保您的系统满足要求：

Before installation, ensure your system meets the requirements:

# 1. 检查操作系统 (Check OS)
uname -s  # 应该显示 "Darwin" (Should show "Darwin")

# 2. 检查 Node.js 版本 (Check Node.js version)
node --version  # 应该 >= 18.0.0 (Should be >= 18.0.0)

# 3. 检查 say 命令 (Check say command)
which say  # 应该显示 /usr/bin/say (Should show /usr/bin/say)

# 4. 测试 TTS (Test TTS)
say -v Samantha "Hello, this is a test"

🚀 使用方法 (Usage)

方法 1: 自动监听模式（推荐）(Auto-Monitor Mode - Recommended)

这是最常用的模式，启动后自动监听剪贴板变化。

This is the most commonly used mode, automatically monitors clipboard after startup.

启动监听 (Start Monitoring)

如果您通过 NPM 全局安装：

If you installed via NPM globally:

speak-monitor

如果您通过 NPM 本地安装：

If you installed via NPM locally:

npx speak-monitor

如果您从源码运行：

If you're running from source:

cd /Users/your-username/code/Utils/speak-english
npm run monitor
# 或直接运行 (or run directly)
node clipboard-monitor.js

使用步骤 (Usage Steps)

启动脚本后，保持终端窗口运行
Keep terminal window running after starting script
在任何地方选中英文文本（比如 Claude Code 的回复）
Select English text anywhere (e.g., Claude Code responses)
- 三击选中整行 (Triple-click to select entire line)
- 或用鼠标拖动选中 (Or drag with mouse to select)
确保文本已复制到剪贴板
Ensure text is copied to clipboard
- 大多数终端自动复制 (Most terminals auto-copy)
- 如果没有，按 ⌘C (If not, press ⌘C)
等待 0.5 秒，自动朗读！
Wait 0.5 seconds, auto-read!

停止监听 (Stop Monitoring)

按 Ctrl+C 停止脚本

Press Ctrl+C to stop script

方法 2: 交互式输入模式 (Interactive Mode)

手动输入英文文本进行朗读。

Manually input English text for reading.

npm start
# 或
node speak-english.js

可用命令 (Available Commands):

直接输入英文 → 朗读 (Type English → Read)
voice Alex → 更换语音 (Change voice)
rate 180 → 调整语速 (Adjust rate)
voices → 查看可用语音 (List voices)
stop → 停止朗读 (Stop reading)
help → 显示帮助 (Show help)
exit → 退出程序 (Exit program)

方法 3: 单次剪贴板朗读 (One-Time Clipboard Read)

手动触发读取当前剪贴板内容。

Manually trigger reading current clipboard content.

npm run clipboard
# 或
node speak-clipboard.js

使用场景 (Use Cases):

快速测试剪贴板内容 (Quick test clipboard)
配合快捷键使用 (Use with keyboard shortcuts)

⚙️ 配置选项 (Configuration)

调整语速 (Adjust Speech Rate)

编辑 clipboard-monitor.js 文件：

Edit clipboard-monitor.js file:

// 找到这行 (Find this line)
const DEFAULT_RATE = 150;

// 修改为您想要的语速 (Change to your desired rate)
// 100-120 = 非常慢 (Very slow)
// 150 = 学习推荐 (Recommended for learning)
// 200 = 正常速度 (Normal speed)
// 250+ = 快速 (Fast)

更换语音 (Change Voice)

// 找到这行 (Find this line)
const DEFAULT_VOICE = 'Samantha';

// 常用语音选项 (Common voice options):
// 'Samantha' - 美式英语，女声 (US English, Female)
// 'Alex' - 美式英语，男声 (US English, Male)
// 'Daniel' - 英式英语，男声 (UK English, Male)
// 'Karen' - 澳式英语，女声 (Australian English, Female)

查看所有可用语音：

View all available voices:

say -v ?

调整检查间隔 (Adjust Check Interval)

// 找到这行 (Find this line)
const CHECK_INTERVAL = 500; // 单位：毫秒 (Unit: milliseconds)

// 更短的间隔 = 更快响应，但更耗 CPU
// Shorter interval = faster response, but more CPU usage
// 推荐：300-1000ms (Recommended: 300-1000ms)

🤖 Claude Code 集成 (Claude Code Integration)

如果您使用 Claude Code，可以通过以下方式集成这个工具。

If you use Claude Code, you can integrate this tool in the following ways.

方案 1: 在 Claude Code 提示词中提及 (Mention in Prompt)

在您的全局 Claude 配置文件中添加说明，让 Claude 知道这个工具的存在。

Add instructions to your global Claude config file to let Claude know about this tool.

文件位置 (File Location): ~/.claude/CLAUDE.md

添加内容 (Add Content):

# 自动英语朗读工具 (Auto English TTS)

我有一个自动英语朗读工具运行在后台。
> I have an automatic English text-to-speech tool running in the background.

## 工作原理 (How It Works)

- 当我选中（三击）您回复中的文本时，会自动复制到剪贴板
- 后台脚本监听剪贴板变化
- 自动提取英文内容（优先 > 引用块）并朗读

> When I select (triple-click) text in your responses, it auto-copies to clipboard
> Background script monitors clipboard changes
> Automatically extracts English content (prioritizes > quoted blocks) and reads aloud

## 回复格式要求 (Response Format Requirements)

为了更好地配合朗读工具，请在回复时：
> To better work with the TTS tool, please:

1. 继续使用双语格式：中文 + 英文引用块
   > Continue using bilingual format: Chinese + English quote blocks

2. 英文内容用 > 引用块标记
   > Mark English content with > quote blocks

示例：
> Example:

这是中文说明。
> This is the English explanation.

这样我就可以通过三击选中文本，自动听到英文朗读。
> This way I can triple-click to select text and automatically hear the English.

方案 2: 使用 Claude Code Hooks (Use Hooks)

如果您想在 Claude 回复完成时自动触发朗读（而不是手动选中），可以配置 Hooks。

If you want to auto-trigger reading when Claude finishes responding (instead of manual selection), you can configure Hooks.

注意： 这个方案需要在每次对话后手动复制整个回复到剪贴板，实际使用中不如方案 1 便捷。

Note: This approach requires manually copying the entire response to clipboard after each conversation, less convenient than Plan 1 in practice.

配置步骤 (Configuration Steps)

编辑 Claude Code 设置文件
Edit Claude Code settings file
```
open ~/.claude/settings.json
```

添加 Notification Hook

{
  "hooks": {
    "Notification": [
      {
        "matcher": "*",
        "hooks": [
          {
            "type": "command",
            "command": "/Users/your-username/code/Utils/speak-english/speak-auto.js"
          }
        ]
      }
    ]
  }
}

重启 Claude Code 使配置生效
Restart Claude Code to apply configuration

Hook 工作原理 (How Hook Works)

Claude 完成回复 → 触发 Notification 事件 → 执行 speak-auto.js
→ 读取剪贴板 → 提取英文 → 朗读

Claude finishes response → Triggers Notification event → Executes speak-auto.js
→ Reads clipboard → Extracts English → Reads aloud

❓ 常见问题 (FAQ)

Q1: 为什么选中文字后没有声音？

A: 请检查：

Please check:

监听脚本是否在运行？

Is the monitor script running?

# 应该能看到 clipboard-monitor.js 进程
# Should see clipboard-monitor.js process
ps aux | grep clipboard-monitor

文字是否复制到了剪贴板？

Is text copied to clipboard?

# 运行这个命令查看剪贴板内容
# Run this to view clipboard content
pbpaste

系统音量是否静音？

Is system volume muted?

# 测试 say 命令
# Test say command
say -v Samantha "test"

终端是否支持选中自动复制？
Does terminal support copy-on-select?
- 大多数 macOS 终端默认支持
- 如果不支持，手动按 ⌘C
- Most macOS terminals support by default
- If not, manually press ⌘C

Q2: 语速太快/太慢怎么办？

A: 修改配置文件中的 DEFAULT_RATE 值。

Modify the DEFAULT_RATE value in config file.

# 编辑配置
vim /Users/your-username/code/Utils/speak-english/clipboard-monitor.js

# 找到这行并修改
const DEFAULT_RATE = 150;  // 改成您想要的值 (Change to your desired value)

# 重启脚本
# Restart script

推荐语速 (Recommended Rates):

初学者: 100-120 WPM
学习中: 150 WPM ⭐ (当前默认 Current default)
熟练: 175-200 WPM
母语水平: 250+ WPM

Q3: 能不能朗读纯英文文本（没有 > 引用块）？

A: 可以！脚本会自动检测。

Yes! The script auto-detects.

检测逻辑 (Detection Logic):

优先查找 > 引用块
Prioritize finding > quote blocks
如果没有引用块，检测是否为纯英文
If no quote blocks, detect if pure English
如果中文字符 < 20%，视为英文并朗读
If Chinese characters < 20%, consider as English and read

Q4: 如何后台持续运行？

A: 使用 nohup 或 screen。

Use nohup or screen.

# 方法 1: nohup (退出终端后继续运行)
# Method 1: nohup (continues after closing terminal)
cd /Users/your-username/code/Utils/speak-english
nohup node clipboard-monitor.js > /dev/null 2>&1 &

# 方法 2: screen (可重新连接的会话)
# Method 2: screen (reconnectable session)
screen -S speak-english
node clipboard-monitor.js
# 按 Ctrl+A 然后 D 分离会话 (Press Ctrl+A then D to detach)

# 重新连接 (Reconnect)
screen -r speak-english

Q5: 如何开机自动启动？

A: 创建 LaunchAgent。

Create a LaunchAgent.

创建文件: ~/Library/LaunchAgents/com.speak-english.monitor.plist

Create file: ~/Library/LaunchAgents/com.speak-english.monitor.plist

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>com.speak-english.monitor</string>
    <key>ProgramArguments</key>
    <array>
        <string>/usr/local/bin/node</string>
        <string>/Users/your-username/code/Utils/speak-english/clipboard-monitor.js</string>
    </array>
    <key>RunAtLoad</key>
    <true/>
    <key>KeepAlive</key>
    <true/>
    <key>StandardErrorPath</key>
    <string>/tmp/speak-english.err</string>
    <key>StandardOutPath</key>
    <string>/tmp/speak-english.out</string>
</dict>
</plist>

加载服务:

Load service:

launchctl load ~/Library/LaunchAgents/com.speak-english.monitor.plist

Q6: 能不能选择不同的声音？

A: 可以！修改 DEFAULT_VOICE 或查看所有可用声音。

Yes! Modify DEFAULT_VOICE or view all available voices.

# 查看所有英语声音
# View all English voices
say -v ? | grep en_

# 常用推荐 (Common recommendations):
# Samantha - 美式女声，清晰自然 (US Female, clear and natural)
# Alex - 美式男声，标准发音 (US Male, standard pronunciation)
# Daniel - 英式男声，适合学英音 (UK Male, good for British accent)
# Karen - 澳式女声 (Australian Female)

🎨 自定义配置 (Customization)

高级配置示例 (Advanced Configuration Examples)

1. 跳过短文本 (Skip Short Texts)

编辑 clipboard-monitor.js:

Edit clipboard-monitor.js:

const MIN_TEXT_LENGTH = 10;  // 默认 10 字符 (Default 10 chars)

// 改成 20 跳过过短的文本
// Change to 20 to skip very short texts
const MIN_TEXT_LENGTH = 20;

2. 朗读前提示音 (Notification Sound Before Reading)

function speak(text) {
  // 添加提示音 (Add notification sound)
  exec('afplay /System/Library/Sounds/Glass.aiff');

  // ... 原有代码 (existing code)
}

3. 朗读完成后通知 (Notification After Reading)

exec(`say -v "${DEFAULT_VOICE}" -r ${DEFAULT_RATE} "${escapedText}"`,
  (error) => {
    if (!error) {
      // 显示系统通知 (Show system notification)
      exec(`osascript -e 'display notification "朗读完成" with title "Speak English"'`);
    }
  }
);

4. 多语音随机选择 (Random Voice Selection)

const VOICES = ['Samantha', 'Alex', 'Karen', 'Daniel'];
const randomVoice = VOICES[Math.floor(Math.random() * VOICES.length)];

📊 性能优化 (Performance Optimization)

CPU 使用 (CPU Usage)

监听脚本占用很少 CPU（< 1%）
每 500ms 一次剪贴板读取
朗读时会短暂使用 CPU 进行语音合成

Monitor script uses minimal CPU (< 1%) Clipboard read every 500ms Brief CPU usage during speech synthesis

内存使用 (Memory Usage)

约 30-50MB 内存占用
Node.js 基础开销

About 30-50MB memory usage Node.js base overhead

优化建议 (Optimization Tips)

增加轮询间隔 减少 CPU 使用（但响应变慢）
Increase polling interval to reduce CPU (but slower response)
限制最大朗读长度 避免过长文本
Limit max reading length to avoid very long texts
使用条件触发 而不是持续监听
Use conditional triggering instead of continuous monitoring

🛠️ 故障排查 (Troubleshooting)

检查系统状态 (Check System Status)

# 1. 检查 Node.js 是否安装
node --version

# 2. 检查 say 命令是否可用
which say
say -v ? | head -5

# 3. 检查 pbpaste 是否可用
which pbpaste
echo "test" | pbcopy && pbpaste

# 4. 检查进程是否运行
ps aux | grep clipboard-monitor

# 5. 检查依赖是否安装
cd /Users/your-username/code/Utils/speak-english
npm list

日志调试 (Log Debugging)

修改脚本启用详细日志：

Modify script to enable verbose logging:

// 在 checkClipboard 函数中添加日志
function checkClipboard() {
  const currentClipboard = getClipboardContent();
  console.log('Clipboard length:', currentClipboard.length);
  console.log('First 50 chars:', currentClipboard.substring(0, 50));

  // ... rest of code
}

📚 参考资料 (References)

macOS TTS 文档 (macOS TTS Documentation)

man say

项目仓库 (Project Repository)

本地路径 (Local Path): /Users/your-username/code/Utils/speak-english

📝 更新日志 (Changelog)

v1.0.0 (2025-11-06)

✅ 实现剪贴板自动监听功能
✅ 智能英文内容识别
✅ 引用块优先提取
✅ 可配置语速和语音
✅ 后台持续运行支持
✅ 完整文档和使用指南

✅ Implemented automatic clipboard monitoring
✅ Smart English content detection
✅ Quote block priority extraction
✅ Configurable speech rate and voice
✅ Background continuous running support
✅ Complete documentation and user guide

📄 许可证 (License)

MIT License

👥 贡献 (Contributing)

欢迎提交 Issues 和 Pull Requests！

Issues and Pull Requests are welcome!

💬 联系方式 (Contact)

如有问题或建议，请通过以下方式联系：

For questions or suggestions, please contact via:

提交 Issue
发送邮件
或其他方式

🎉 致谢 (Acknowledgments)

感谢以下技术和工具的支持：

Thanks to the following technologies and tools:

Node.js
macOS TTS Engine
Chalk (terminal styling)
Claude Code (AI assistance)

Happy Learning English! 🎓📚

享受学习英语的过程！🎓📚