内容
<p align="center">
<img src="logo/yangmei-icon.png" alt="live-translate" width="120" />
</p>
# 即时翻译 — 英语 ↔ 中文
完全本地的英语和中文语音翻译工具，无需云端API。所有音频处理都在您的机器上运行。采用MIT许可证。
<p align="center">
<img src="assets/demo.gif" alt="live-translate demo" width="600" />
</p>
## 安装
```bash
npm install -g live-translate
```
## 快速开始
```bash
live-translate # 按空格键开始录音，再按空格键进行翻译
# 首次运行会自动下载模型并启动服务
live-translate stop # 停止服务
```
## 命令
| 命令 | 描述 |
|---------|-------------|
| `live-translate` | 开始翻译（按空格键开始/停止录音，按Q或Ctrl-C退出） |
| `live-translate config` | 配置翻译提供商 |
| `live-translate start` | 下载模型并启动后端服务（需要时自动运行） |
| `live-translate stop` | 停止所有后端服务 |
| `live-translate status` | 显示服务健康状态和活动提供商 |
| `live-translate doctor` | 检查先决条件 |
## 翻译提供商
运行 `live-translate config` 选择后端。默认使用Opus-MT（完全本地，无需API密钥）。
| 提供商 | 类型 | 质量 | 成本 |
|----------|------|---------|------|
| **Opus-MT** *(默认)* | 本地模型 | 良好 | 免费 |
| **Ollama** (Qwen 2.5) | 本地LLM | 高 | 免费 — 需要约5 GB内存 |
| **Anthropic (Claude)** | 云端API | 优秀 | 约$0.001/次翻译 |
| **OpenAI** | 云端API | 优秀 | 约$0.001/次翻译 |
| **DeepSeek** | 云端API | 优秀，对中文有优势 | 约$0.0005/次翻译 |
对于云端提供商，音频不会离开您的机器 — 只有转录的文本会被发送到API。
```bash
# 交互式设置
live-translate config
# 或直接传递参数
live-translate config --provider anthropic --api-key sk-ant-...
live-translate config --provider ollama --model qwen2.5:14b
live-translate config --provider deepseek --api-key <key>
```
配置保存在 `~/.live-translate/config.json`。
## 工作原理
```
麦克风 → 命令行界面 → 自动语音识别（ASR，Whisper）→ 翻译 → 文本转语音（TTS，Piper）→ 扬声器
```
语音在本地录制。Whisper将语音转录为文本，配置的提供商将文本翻译为目标语言，Piper将翻译后的文本合成语音 — 完整的流程在您的机器上运行，除了使用云端提供商时的翻译步骤。
### 首次运行
首次运行 `live-translate` 时，程序会自动：
1. 下载Piper语音模型（约100 MB，英语和中文）到 `~/.live-translate/voices/`
2. 如果系统上没有安装 `sox` 和 `espeak-ng`，则安装它们
3. 启动四个后端服务作为本地进程
4. 等待最多3分钟，让所有服务达到健康状态
日志写入到 `~/.live-translate/logs/`。
## 与Claude Desktop配合使用
如果您使用Claude Desktop，请安装 **[live-translate-mcp](https://github.com/waxberry-dev/live-translate-mcp)** — 一个独立的MCP服务器，使Claude能够翻译音频文件，无需管理本地服务。它在本地使用Whisper和Piper，而Claude本身用于翻译。
```bash
npm install -g live-translate-mcp
```
```json
{
"mcpServers": {
"live-translate": {
"command": "npx",
"args": ["-y", "live-translate-mcp"],
"env": { "ANTHROPIC_API_KEY": "your-key-here" }
}
}
}
```
参见 [live-translate-mcp README](https://github.com/waxberry-dev/live-translate-mcp) 以获取完整的设置说明。
## 先决条件
- Node.js 18+
运行 `live-translate doctor` 以验证您的设置。如果缺少 `sox` 和 `espeak-ng`，则会在首次运行时自动下载。
## 架构
| 组件 | 端口 | 语言 | 目的 |
|-----------|------|----------|---------|
| 协调器 | 8000 | TypeScript | 管道协调 |
| 自动语音识别（ASR） | 8001 | TypeScript | 语音 → 文本（Whisper via @huggingface/transformers） |
| 翻译 | 8002 | TypeScript | 文本 → 文本（可配置的提供商） |
| 文本转语音（TTS） | 8003 | TypeScript | 文本 → 语音（Piper） |
| 命令行界面 | — | TypeScript | 用户界面和服务管理 |
服务作为本地进程运行，由命令行界面管理。状态和配置存储在 `~/.live-translate/`。
## 开发
```bash
# 开发模式下的命令行界面（无需构建）
cd cli && npm run dev
# 构建
cd cli && npm run build
```
### 测试
```bash
# 单元测试（无需运行服务）
cd cli && npm test
# 集成测试（需要运行 live-translate）
python -m pytest tests/integration/ -v
```
### 项目结构
```
live-translate/
├── cli/ # TypeScript npm 包（整个产品）
│ ├── src/
│ │ ├── commands/ # doctor, config, start, stop, status, translate
│ │ ├── server/ # asr.ts, translation.ts, tts.ts, orchestrator.ts
│ │ ├── services/ # api, processes, recorder, player
│ │ └── utils/ # constants, logger, binaries
│ └── package.json
├── tests/
│ └── integration/ # 端到端测试（需要运行服务）
└── docs/
└── records/ # 设计决策和功能规格
```
## 硬件
| 级别 | 内存 | GPU | 延迟 |
|------|-----|-----|---------|
| 最低 | 8 GB | 无（仅CPU） | 约5秒 |
| 推荐 | 16 GB | 6+ GB显存 | < 1秒 |
磁盘：模型和语音文件约3 GB。
## 许可证
MIT — 参见 [LICENSE](LICENSE)。所有模型依赖项均使用MIT或Apache 2.0许可证。
