SteamVR Translator

项目仓库 · 版本发布

操作说明

首次启动

1. 将发布包解压到具有写入权限的目录。
2. 启动 SteamVRTranslator.exe。
3. 首次启动服务时，按照安装向导下载 SenseVoice 运行时和模型。仅使用图像翻译时也可以暂不安装。
4. 在“模型提供商”中选择内置“模拟提供商”进行离线测试，或添加 OpenAI 兼容提供商并填写 Base URL、API Key 和模型。
5. 手动启动 SteamVR。本工具不会自动启动 SteamVR，SteamVR 暂时断开后会自动等待并重连。
6. 在管理器中点击“启动服务”，等待状态显示为已连接。
7. 打开 SteamVR 按键绑定，确认翻译键、左右框选扳机、抓握键、窗口点击扳机和右摇杆已经绑定。

图像捕获与翻译

1. 在未接触空间窗口时短按左摇杆，进入捕获模式。
2. 同时按住左右扳机，两只手柄的位置分别作为选择框的两个对角点。
3. 移动双手调整范围，松开任意扳机立即捕获。
4. 捕获成功后，截图窗口会出现在原选择区域。
5. 手接近或抓住截图后：
   • 短按左摇杆直接翻译。
   • 长按左摇杆录制自定义命令，松开后提交。
   • 抓住窗口时，可用另一只手的扳机点击翻译、排版翻译、录音或关闭按钮。
6. 按住抓握键可移动和旋转窗口，松开后固定在当前位置。
7. 触碰结果窗口时使用右摇杆上下滚动。
8. 触碰或抓住单个窗口并长按右摇杆可关闭，松开按键可取消。工具栏中的关闭按钮会立即关闭。
9. 未接触窗口时短按右摇杆，可全局隐藏或重新显示空间窗口。

VR 控制面板

1. 在非捕获状态下长按左摇杆约 650 ms，打开或关闭 VR 控制面板。
2. 使用另一只手指向按钮，并按下扳机点击。
3. 控制面板可启动捕获、打开语音输入、字幕、手机镜像及对应设置。

窗口配色

在“图像翻译 → 叠加层配色”中选择“经典绿色”“浅色”或“黑白”。经典绿色保留原有外观；浅色使用浅底、深色文字和蓝色强调色；黑白使用黑底、白字和灰阶边框及强调色。每项颜色旁均有“选择颜色”按钮，点击打开系统颜色选择器，可在任意预设的基础上修改背景、文字、强调色和边框。点击“应用配色”后自动切换为“自定义”并保存；取消颜色选择不会修改原值。切换预设会保留已保存的自定义颜色。

配色会即时应用到管理器、VR 控制面板、翻译与对话窗口、字幕、语音回显、截图工具栏和手机镜像的窗口边框，无需重启或重建浮窗。截图、手机画面和 HTML 排版翻译的内容保留自身颜色。

VRChat 语音输入

可选的“在面前显示语音文本回显（VR）”可在桌面语音设置或 VR 控制面板的“回显”开关中启用，默认关闭。回显使用大字和宽幅长行，首次显示时放在前方约 1.2 米、略低于眼睛的位置，随后固定在 SteamVR 空间中，不随头部移动或转动。宽高随内容自适应：短句收紧，长句先加宽至最多约 1.6 米，再换行增加高度；文字的实际字号不随框体尺寸缩小。左上角保持固定，面板向右下方伸缩。浮窗只显示识别结果和实际通过 OSC 发送的当前文本段，没有文本时隐藏。

浮窗仅用于显示，不响应点击、滚动、抓取或拖动，也没有可操作的控制栏。仅自己可见，完成后保留 12 秒；显示期间再次录音会立即清空旧内容并复用同一个浮窗及空间定位，新的结果完成后重新计时。自动隐藏或关闭开关后，下一次输入才重新放置到当前面前，仍复用同一个浮窗。没有有效头显定位时等待定位恢复再显示。关闭开关会立即隐藏，启用后从下一次输入开始显示，无需重新加载模型。回显以本机 OSC 发出内容为准，不代表 VRChat 已确认接收。

1. 在“VRChat 语音”页面下载 SenseVoice，选择麦克风和 CPU 或本机 Vulkan GPU。
2. 确认 OSC 地址，VRChat 默认使用 127.0.0.1:9000。
3. 开启 VRChat 语音输入并启动服务。
4. 在 VR 中按住已绑定的 PTT 键录音，松开后识别并发送到 VRChat Chatbox。
5. 桌面模式默认使用左 Ctrl，可在管理器中重新捕获并绑定其他按键。

通过虚拟麦克风发送提示音

1. 在“VRChat 语音 → 语音输入提示音”中点击“下载 VB-CABLE”。程序从官网下载基础版安装包（约 1.26 MB），显示进度、支持取消并校验 SHA-256；下载不会自动安装驱动。
2. 下载校验通过后，停止服务并点击“安装 VB-CABLE”，完成 Windows 管理员授权和重启。状态显示“VB-CABLE 已就绪”后才能启用提示音，程序会自动找到匹配的播放端和录音端。
3. 目标游戏的麦克风首次选择 CABLE Output (VB-Audio Virtual Cable)，并打开游戏语音或按住游戏自己的发话键。上方用于 SenseVoice 识别的麦克风仍选择实体麦克风；VB-CABLE 仅发送提示音，不转发人声。
4. 内置音效为 开启时清脆上行通知音 → 录音中柔和低频白噪声 → 结束时清脆下行通知音。持续音经过低通处理，减轻高频嘶声。三种声音可分别开关，并可调整音量。每行点击“选择文件…”可替换该阶段的音效，点击“内置”恢复该阶段的默认声音。支持单声道或立体声 WAV / MP3，每段不超过 30 秒、20 MB；导入后保存在程序目录的 sounds/voice-cues 中，原文件可以移动或删除。
5. “本机试听”使用 Windows 默认扬声器或耳机；“发送到游戏麦克风”使用 VB-CABLE。勾选“启用回响”后，正式语音输入和游戏麦克风测试也会在本机播放所选音效。再次点击正在播放的测试按钮可停止。
6. 启动服务后，VR PTT 和桌面 PTT 都会触发音效。开启音播放一次，持续音仅在录音期间循环，松开后立即进入结束音，不等待识别或翻译完成。

提示音和回响默认关闭，设置随启动服务保存，修改或卸载驱动前请先停止服务。回响使用 Windows 默认扬声器或耳机，音量与提示音一致；本机播放失败不会中断游戏通道。在同一区域点击“卸载”会调用官方卸载程序，也会影响其他使用 VB-CABLE 的程序。安装或卸载后请重启 Windows。设备不可用时，启用开关和发送测试按钮会禁用，正在发送的提示音也会停止；仍可本机试听。

更新或搬移程序时，请保留 appsettings.json 和 sounds 文件夹。自定义文件缺失或损坏时，试听会提示原因；正式服务会为该阶段回退到内置音效并记录日志，语音识别继续运行。

VB-CABLE 安装可能让 Windows 自动改变默认音频设备。程序会记录安装前的默认设备，并在发现它们被改为 VB-CABLE 时尝试恢复；如果恢复失败会提示检查声音设置。游戏麦克风设置仍由游戏管理。游戏降噪或语音门限可能过滤白噪声，可使用测试播放检查接收效果。

VB-CABLE 由 VB-Audio Software 提供，采用 Donationware 模式，欢迎捐赠支持。软件使用和分发适用其许可条款。下载、验证和设备连接说明见 VB-CABLE 集成文档。本项目不再构建或分发自研音频驱动。

实时字幕

1. 在管理器中启用实验性字幕功能。
2. 选择本机 SenseVoice 或 VibeVoice API，并完成所需运行时和模型安装。
3. 配置音频来源、目标语言、翻译提供商和显示方式。
4. 启动服务后，从 VR 控制面板打开字幕窗口。
5. 点击字幕窗口中的监听按钮，开始或停止捕获进程音频。

监听会先在后台准备识别引擎，再连接当前 SteamVR 场景进程。语音输入、字幕和文件重放在模型、运行时、语言及 CPU/GPU 配置相同时共用常驻 SenseVoice；语音输入已预热时，字幕开启或重启不会重复加载。识别请求串行执行，语音输入优先于等待中的字幕。停止字幕只取消它自己的任务，最后一个使用者退出后才卸载模型。设置变更在当前音频段处理结束后生效。状态说明及排查方法见 字幕生命周期与诊断。

Pyannote 说话人分段和 ERes2Net 声纹模型由字幕模块单独常驻管理，语音输入不加载它们。首次使用时加载，连续分段和暂停后重启监听均可复用；关闭字幕功能、停止服务或退出程序时释放。

Android 手机镜像

1. 在管理器中启用实验性手机镜像。
2. 下载镜像运行时，并通过 USB 或无线 ADB 连接 Android 设备。
3. 选择设备、分辨率、最大帧率、码率和窗口缩放。
4. 启动服务后，从 VR 控制面板打开手机镜像。
5. 使用 VR 光标点击、拖动或滚动手机画面；窗口底部按钮对应返回、主页和最近任务。

文件位置

程序配置、运行时、模型、截图和日志都保存在安装目录内：

appsettings.json
captures/
logs/
models/
runtimes/
runtime-data/
vibevoice-service/data/

构建方式

构建环境：

• Windows x64
• .NET 8 SDK
• PowerShell

在仓库根目录执行：

./build.ps1

发布包不捆绑 VB-CABLE 二进制文件；用户可在程序中从官网下载。构建无需 WDK、C++ 编译器或自购驱动签名证书。

默认生成依赖 .NET 8 Desktop Runtime 的版本：

artifacts/win-x64/SteamVRTranslator.exe
artifacts/win-x64/vibevoice-service/SteamVRTranslator.VibeVoice.Server.exe
artifacts/SteamVRTranslator-win-x64.zip

生成自包含版本：

./build.ps1 -SelfContained

执行全部自动化测试：

dotnet test SteamVRTranslator.sln

仅验证 Release 构建：

dotnet build SteamVRTranslator.sln -c Release

构建脚本会通过 fetch-openvr.ps1 获取并校验固定版本的 Valve OpenVR 原生运行时。原生 DLL、模型、运行时、构建产物和捕获图片不会提交到 Git。