# VRCTTP

**Repository Path**: sammusen/VRCTTP

## Basic Information

- **Project Name**: VRCTTP
- **Description**: VRChat Text Translate Pipeline | 适用于 VRChat 的文字翻译处理管道
- **Primary Language**: Python
- **License**: AGPL-3.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-07-18
- **Last Updated**: 2026-09-16

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# VRCTTP - VRChat 实时流式翻译工具

> 🎯 **让 VRChat 跨语言交流零障碍**  
> 实时捕获游戏或麦克风音频 → 语音识别 → 机器翻译 → OSC 发送至游戏聊天框

---

## 📥 下载与安装

### 首次使用（推荐）
👉 **https://pan.quark.cn/s/232eeac3d38b**

### 版本更新
1. 前往 **https://github.com/sanmusen214/VRCTTP/releases/** 下载最新 `exe` 文件
2. 直接替换原程序目录中的旧 `exe` 即可

### 交流反馈
💬 **QQ 交流群：964670098**  
📺 **B站视频**: **https://www.bilibili.com/video/BV1cgjN6fEfm/**

> ⚠️ 作者不常看评论区，有问题请进群咨询

---

## ✨ 核心功能

| 功能 | 说明 |
|------|------|
| 🎧 **音频捕获** | 支持 VRChat 游戏音频环回 + 系统麦克风双输入 |
| 🗣️ **语音识别** | 在线/本地语音识别模块可选 |
| 🌍 **实时翻译** | 多翻译模块可选，支持多语种并行 |
| 📺 **多端输出** | VRChat OSC 聊天框 / 终端实时显示 / GUI 面板 |
| 🔀 **多管道并行** | 同时处理多路音频流，互不干扰 |
| 🖥️ **可视化 GUI** | NiceGUI 网页管理台，配置热更新 |

---

## 🏗️ 系统架构

```
┌─────────────────┐    ┌─────────────┐    ┌─────────────┐    ┌─────────────┐
│ LoopbackSource  │───▶│ VolcSTT     │───▶│ Translation │───▶│ VRChat OSC │
│ (游戏/麦克风音频)│    │ (流式识别)   │    │ (多语种翻译) │    │ (游戏聊天框) │
└─────────────────┘    └─────────────┘    └─────────────┘    └─────────────┘
                                                      │
                                                      ▼
                                             ┌─────────────────────┐
                                             │   TerminalConsumer   │
                                             │   (终端/GUI 实时显示) │
                                             └─────────────────────┘
```

## 🚀 快速启动

### 方式一：直接运行（推荐）
```bash
# 双击 VRCTTP.exe 即可
# 程序自动启动 Web GUI（默认 http://localhost:8082）
```

### 方式二：命令行启动
```bash
python main.py              # 默认配置 + 启动 GUI
python main.py --no-gui     # 不启动 GUI，仅命令行运行
python main.py --list-devices  # 列出所有音频设备
```

---

## ⚙️ 配置文件（config.json）

（推荐）请前往 [百度翻译开放平台](https://fanyi-api.baidu.com/product/11) 进行注册并认证为个人开发者，随后开通 通用文本翻译 服务，并填写百度相关密钥

### 环境变量设置
```bash
# Windows PowerShell
$env:BAIDU_APP_ID="your-baidu-app-id"
$env:BAIDU_APP_KEY="your-baidu-app-key"

# 或创建 .env 文件
BAIDU_APP_ID=your-baidu-app-id
BAIDU_APP_KEY=your-baidu-app-key
```

`.env` 和 `config.json` 均位于程序/exe 同级目录。程序会保证 `.env` 至少包含
`VOLC_API_KEY`、`BAIDU_APP_ID`、`BAIDU_APP_KEY`、`llm_api_key` 四个字段，缺失字段以空值补齐；GUI 保存环境变量时会同步写回该文件。
最低字段的名称和 Markdown 获取说明统一记录在 `runtime_paths.py` 的 JSON 兼容列表中。首次打开 GUI 时，如果这四个字段全部为空，程序会自动跳转到环境变量页，并显示黄色配置提醒；该强制跳转在每次程序运行中只发生一次，之后可以正常返回首页。`BAIDU_APP_ID` 和 `BAIDU_APP_KEY` 会作为同一组凭证展示。

打包版首次启动时，如果 exe 同级没有 `config.json`，程序会将同级
`tmp/example_config.json` 移动为 `config.json` 后加载。已有 `config.json` 始终优先使用。

## 🔄 软件更新

程序版本以 `version.py` 的 `version_str` 为唯一来源。启动时会同步 exe 同级
`settings/software_config.json` 的 `NOWVERSION`，并在后台检查最新 Release。发现更新后，首页会自动弹出更新说明；关闭弹窗后仍可点击顶部带边框动画的橙色新版本提示重新打开。点击“立即更新”会启动同目录的 `VRCTTP_UPDATE.exe`。

正式打包目录内主程序固定命名为 `VRCTTP.exe`，更新器固定命名为 `VRCTTP_UPDATE.exe`，以便更新器稳定定位和替换主程序。
`package.py` 还会使用 `zipfile` 将更新器单独打包为同目录的 `VRCTTP{版本号}_update.zip`；压缩包内部文件名保持为 `VRCTTP_UPDATE.exe`。

或者请前往 [火山引擎-豆包语音](https://console.volcengine.com/speech/new/setting/apikeys?projectName=default) 注册并开通 语音识别 与 机器翻译服务，并填写相关火山引擎密钥（新版控制台）`VOLC_API_KEY`

✨ 如果你有想要使用的语音识别或翻译模块，欢迎根据 ai_documents 文档指引，进行模块的搭建，测试以及pr。 ✨

## ❓ 常见问题

**Q：VRChat 无文字发送？**  
A：确认 VRChat 已开启 OSC 功能（设置 → OSC → 启用）

---

## 📋 系统要求

- **操作系统**：Windows 10/11
- **Python**：3.10（源码开发）
- **依赖**：见 `requirements.txt`
- **硬件**：支持音频输入的设备